fix(web): restore the Dashboard status tiles' top padding

CardContent is shadcn's header-adjacent variant (`p-4 pt-0 sm:p-6 sm:pt-0`),
but the four Live-status tiles use it with no CardHeader. tailwind-merge lets
the call site's unprefixed `p-4` cancel the base `pt-0`, yet nothing cancels
`sm:pt-0` — so the tiles lost their top padding at >=640px only, and the
content sat against the top edge. Restores the top inset at the sm breakpoint
and lets the content fill the stretched grid cell so it stays centred when a
sibling tile is taller.

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

.gitea/workflows/flatpak.yml

@@ -73,8 +73,34 @@ jobs:
       # sufficient — the Tooling step's dnf install pulls a systemd package upgrade whose RPM
       # trigger re-runs authselect and regenerates this file, undoing the fix. It's reapplied
       # there, right before the first `flatpak` network call.
-      - name: Fix container DNS (drop nss-resolve — no systemd-resolved in CI)
+      - name: Fix container DNS (drop nss-resolve, resolve over TCP)
-        run: sed -i 's/resolve \[!UNAVAIL=return\] //' /etc/nsswitch.conf
+        run: |
+          sed -i 's/resolve \[!UNAVAIL=return\] //' /etc/nsswitch.conf
+          # Resolve over TCP instead of UDP. The documented root cause of the flathub
+          # bootstrap failures (investigated 2026-07-11, see the Tooling step) is this box's
+          # Docker embedded resolver at 127.0.0.11 DROPPING UDP lookups while the shared
+          # runner fleet is saturated — a datagram nobody retransmits, so the lookup just
+          # times out. The answer then was to widen retry.sh's budget to 10 attempts (~9 min),
+          # which is enough to outlast a main push's ~8-workflow fan-out but NOT a TAG push's
+          # 13: v0.15.0 (twice) and v0.16.0 each burned all 10 attempts and failed the job,
+          # each needing a manual re-run.
+          #
+          # `use-vc` makes glibc use TCP, where the kernel retransmits and the query cannot be
+          # silently lost under load. Same resolver, same search path — only the transport
+          # changes, so internal names (git.unom.io) resolve exactly as before; deliberately
+          # NO extra nameservers, which would risk answering an internal name from a public
+          # resolver. Docker's embedded DNS serves TCP on 127.0.0.11:53 as well as UDP.
+          # retry.sh stays as the backstop for genuine upstream blips.
+          #
+          # Non-fatal: Docker bind-mounts /etc/resolv.conf and can present it read-only, and a
+          # DNS tuning that cannot be applied must not be what fails the release build — that
+          # would trade an occasional re-run for a hard stop. Falling back to UDP just restores
+          # today's behaviour, which retry.sh already covers.
+          if ! grep -q '^options .*use-vc' /etc/resolv.conf 2>/dev/null; then
+            echo 'options use-vc timeout:3 attempts:3' >> /etc/resolv.conf \
+              || echo "::warning::could not set use-vc (read-only resolv.conf?); staying on UDP"
+          fi
+          cat /etc/resolv.conf || true
 
       # fedora:43 has no node, but actions/checkout (a JS action) needs it. A plain `run:` step
       # executes via the container shell (no node needed), so install node BEFORE checkout.

.gitea/workflows/plugin-kit-publish.yml

@@ -0,0 +1,69 @@
+# Publish the plugin framework (@punktfunk/plugin-kit) to the Gitea npm registry
+# (https://git.unom.io/api/packages/unom/npm/).
+#
+# Trigger: push a tag `plugin-kit-vX.Y.Z` (must equal plugin-kit/package.json "version"),
+# or run manually. Versions independently of the app's `v*` and the SDK's `sdk-v*` tags.
+#
+# The kit's devDependency on @punktfunk/host is `file:../sdk`, so the SDK's dist must be
+# built BEFORE the kit's `bun install` copies it.
+#
+# Auth: REGISTRY_TOKEN — the same repo Actions secret sdk-publish.yml uses.
+name: plugin-kit-publish
+
+on:
+  push:
+    tags: ['plugin-kit-v*']
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-24.04
+    container:
+      image: oven/bun:1
+    timeout-minutes: 15
+    steps:
+      # oven/bun's slim base ships neither git, a CA bundle, nor node — actions/checkout's HTTPS
+      # fetch needs git + ca-certificates, and the version-guard step below uses node.
+      - name: Install git + node + CA certs
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git nodejs
+
+      - uses: actions/checkout@v4
+
+      - name: Build the SDK (file:../sdk dependency source)
+        working-directory: sdk
+        run: |
+          bun install --frozen-lockfile --ignore-scripts
+          bun run build
+
+      - name: Install dependencies
+        working-directory: plugin-kit
+        run: bun install --frozen-lockfile --ignore-scripts
+
+      - name: Typecheck
+        working-directory: plugin-kit
+        run: bun run typecheck
+
+      - name: Test
+        working-directory: plugin-kit
+        run: bun test
+
+      - name: Build (dist/ JS + .d.ts + theme.css)
+        working-directory: plugin-kit
+        run: bun run build
+
+      - name: Tag matches package version
+        if: startsWith(github.ref, 'refs/tags/')
+        working-directory: plugin-kit
+        run: |
+          TAG="${GITHUB_REF_NAME#plugin-kit-v}"
+          PKG="$(node -p "require('./package.json').version")"
+          test "$TAG" = "$PKG" || { echo "tag $GITHUB_REF_NAME does not match package version $PKG"; exit 1; }
+
+      - name: Publish to Gitea registry
+        working-directory: plugin-kit
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          test -n "$NODE_AUTH_TOKEN" || { echo "REGISTRY_TOKEN secret is empty"; exit 1; }
+          printf '//git.unom.io/api/packages/unom/npm/:_authToken=%s\n' "$NODE_AUTH_TOKEN" >> .npmrc
+          bun publish

.gitea/workflows/release.yml

@@ -149,6 +149,26 @@ jobs:
           # inherits this from the env during the xcframework build).
           echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"
 
+      - name: Pin + prune Xcode DerivedData
+        # Without -derivedDataPath, xcodebuild derives its DerivedData directory name from the
+        # PROJECT'S ABSOLUTE PATH — and act_runner rotates its workspace
+        # (~/.cache/act/<hash>/hostexecutor), so each rotation minted a brand new ~760 MB tree
+        # under ~/Library that nothing ever collected. 31 of them piled up in three days
+        # (~32 GB with the shared ModuleCache), filled the runner's boot volume, and failed
+        # v0.16.0's xcframework build with "No space left on device". Pinning one path makes the
+        # tree REUSED instead of multiplied — it also keeps the module cache warm between runs.
+        run: |
+          DD="$HOME/ci/derived-data/release"
+          mkdir -p "$DD"
+          echo "DERIVED_DATA=$DD" >> "$GITHUB_ENV"
+          # Safety net for trees the pin does not own: the legacy per-path ones from before this
+          # change, and anything another job leaves in the default root. Untouched for a week ⇒ gone.
+          if [ -d "$HOME/Library/Developer/Xcode/DerivedData" ]; then
+            find "$HOME/Library/Developer/Xcode/DerivedData" -mindepth 1 -maxdepth 1 \
+              -mtime +7 -exec rm -rf {} + 2>/dev/null || true
+          fi
+          echo "disk after prune:"; df -h /System/Volumes/Data | tail -1
+
       - name: Build PunktfunkCore.xcframework (mac + iOS + tvOS)
         # tvOS is a tier-3 target (nightly -Zbuild-std): slow on the first build, then cached on
         # the self-hosted runner. Built on canary too so the tvOS archive/upload below runs on the
@@ -176,6 +196,7 @@ jobs:
             -project "$PROJECT" -scheme Punktfunk \
             -destination 'generic/platform=macOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-macos.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
             -skipMacroValidation -skipPackagePluginValidation \
             MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
             CODE_SIGNING_ALLOWED=NO
@@ -273,6 +294,7 @@ jobs:
             -project "$PROJECT" -scheme Punktfunk \
             -destination 'generic/platform=macOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
             -skipMacroValidation -skipPackagePluginValidation \
             -allowProvisioningUpdates \
             -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
@@ -336,6 +358,7 @@ jobs:
             -project "$PROJECT" -scheme Punktfunk-iOS \
             -destination 'generic/platform=iOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
             -skipMacroValidation -skipPackagePluginValidation \
             -allowProvisioningUpdates \
             -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
@@ -394,6 +417,7 @@ jobs:
             -project "$PROJECT" -scheme Punktfunk-tvOS \
             -destination 'generic/platform=tvOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
             -skipMacroValidation -skipPackagePluginValidation \
             -allowProvisioningUpdates \
             -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \

Cargo.lock

@@ -2159,7 +2159,7 @@ dependencies = [
 
 [[package]]
 name = "latency-probe"
-version = "0.15.0"
+version = "0.16.0"
 
 [[package]]
 name = "lazy_static"
@@ -2264,7 +2264,7 @@ dependencies = [
 
 [[package]]
 name = "libvpl-sys"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "bindgen",
  "cmake",
@@ -2299,7 +2299,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "loss-harness"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "punktfunk-core",
 ]
@@ -2788,7 +2788,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pf-capture"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -2808,7 +2808,7 @@ dependencies = [
 
 [[package]]
 name = "pf-client-core"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2832,7 +2832,7 @@ dependencies = [
 
 [[package]]
 name = "pf-clipboard"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -2850,7 +2850,7 @@ dependencies = [
 
 [[package]]
 name = "pf-console-ui"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2871,7 +2871,7 @@ dependencies = [
 
 [[package]]
 name = "pf-encode"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2894,7 +2894,7 @@ dependencies = [
 
 [[package]]
 name = "pf-ffvk"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "ash",
  "bindgen",
@@ -2903,7 +2903,7 @@ dependencies = [
 
 [[package]]
 name = "pf-frame"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "libc",
@@ -2915,7 +2915,7 @@ dependencies = [
 
 [[package]]
 name = "pf-gpu"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "pf-host-config",
@@ -2929,11 +2929,11 @@ dependencies = [
 
 [[package]]
 name = "pf-host-config"
-version = "0.15.0"
+version = "0.16.0"
 
 [[package]]
 name = "pf-inject"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -2961,14 +2961,14 @@ dependencies = [
 
 [[package]]
 name = "pf-paths"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "tracing",
 ]
 
 [[package]]
 name = "pf-presenter"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2983,7 +2983,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vdisplay"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3013,7 +3013,7 @@ dependencies = [
 
 [[package]]
 name = "pf-win-display"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "pf-paths",
@@ -3025,7 +3025,7 @@ dependencies = [
 
 [[package]]
 name = "pf-zerocopy"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3221,7 +3221,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-android"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "android_logger",
  "jni",
@@ -3237,7 +3237,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -3253,7 +3253,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-session"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "pf-client-core",
@@ -3268,7 +3268,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "async-channel",
  "ffmpeg-next",
@@ -3287,7 +3287,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-core"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "aes-gcm",
  "bytes",
@@ -3318,7 +3318,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-host"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -3400,7 +3400,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-probe"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "mdns-sd",
@@ -3414,7 +3414,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-tray"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "ksni",
@@ -3437,7 +3437,7 @@ checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
 
 [[package]]
 name = "pyrowave-sys"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "bindgen",
  "cmake",

Cargo.toml

@@ -48,7 +48,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.15.0"
+version = "0.16.0"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.15.0"
+    "version": "0.16.0"
   },
   "paths": {
     "/api/v1/clients": {

clients/android/native/src/decode/async_loop.rs

@@ -404,7 +404,14 @@ fn feeder_loop(
                 // stage is consumed: the HUD, or the ABR decode signal (`measure_decode`). The
                 // HUD-only `received` point + host/network split stay gated on the overlay.
                 if stats.enabled() || measure_decode {
-                    let received_ns = now_realtime_ns();
+                    // Core reassembly-completion stamp (ABI v9), NOT the pull instant: stamping
+                    // here would fold the hand-off queue wait into the network latency figure
+                    // (a client-side standing backlog masquerading as network). 0 = older core.
+                    let received_ns = if frame.received_ns > 0 {
+                        frame.received_ns as i128
+                    } else {
+                        now_realtime_ns()
+                    };
                     {
                         let mut g = in_flight
                             .lock()

clients/android/native/src/decode/sync_loop.rs

@@ -221,7 +221,13 @@ pub(super) fn run_sync(
                     // samplers (`received` point, host/network split) stay gated on the overlay so
                     // the hidden steady state adds only a wall-clock read + the receipt push.
                     if stats.enabled() || measure_decode {
-                        let received_ns = now_realtime_ns();
+                        // Core reassembly-completion stamp (ABI v9), not the pull instant — see
+                        // async_loop: a pull stamp folds hand-off queue wait into "network".
+                        let received_ns = if frame.received_ns > 0 {
+                            frame.received_ns as i128
+                        } else {
+                            now_realtime_ns()
+                        };
                         in_flight.push_back((frame.pts_ns / 1000, received_ns));
                         if in_flight.len() > IN_FLIGHT_CAP {
                             in_flight.pop_front(); // stale — codec never echoed it back

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -579,13 +579,21 @@ struct ContentView: View {
                         model?.disconnect() // the captured-state ⌃⌥⇧D combo
                     },
                     onFrame: { [meter = model.meter, latency = model.latency,
-                                split = model.latencySplit, offset = conn.clockOffsetNs] au in
+                                split = model.latencySplit, queue = model.clientQueue,
+                                offset = conn.clockOffsetNs] au in
                         meter.note(byteCount: au.data.count)
                         latency.record(ptsNs: au.ptsNs, offsetNs: offset)
                         // The same receipt, keyed by pts, awaiting its 0xCF host timing (the
-                        // host/network split — drained by the 1 s stats tick).
+                        // host/network split — drained by the 1 s stats tick). receivedNs is
+                        // the core's reassembly stamp (ABI v9), so the split's network term no
+                        // longer contains the client-queue wait...
                         split.recordReceipt(
                             ptsNs: au.ptsNs, receivedNs: au.receivedNs, offsetNs: offset)
+                        // ...which is measured as its own term instead (receipt→pull, both
+                        // client-local).
+                        queue.record(
+                            ptsNs: UInt64(bitPattern: au.receivedNs), atNs: au.pulledNs,
+                            offsetNs: 0)
                     },
                     onSessionEnd: { [weak model] in
                         Task { @MainActor in model?.sessionEnded() }

clients/apple/Sources/PunktfunkClient/Session/SessionModel.swift

@@ -102,6 +102,12 @@ final class SessionModel: ObservableObject {
     @Published var decodeValid = false
     @Published var displayP50Ms = 0.0
     @Published var displayValid = false
+    /// Client-queue wait: core reassembly receipt → the pump's pull (`AccessUnit.pulledNs −
+    /// receivedNs`, ABI v9 receipt split — the 2026-07 two-pair investigation). ~0 on a healthy
+    /// stream; a persistent value is a client-side standing backlog that used to hide inside
+    /// "network". Shown in the detailed tier only when it says something (≥ ~2 ms).
+    @Published var clientQueueP50Ms = 0.0
+    @Published var clientQueueValid = false
     /// The measured OS present floor (design/apple-presentation-rebuild.md): the deadline
     /// engine's vend→glass pipeline depth — an OS property no client can pace under (~2 refresh
     /// intervals composited; would read ~1 under direct-to-display). The HUD subtracts it from
@@ -147,6 +153,9 @@ final class SessionModel: ObservableObject {
     let endToEnd = LatencyMeter()
     let decodeStage = LatencyMeter()
     let displayStage = LatencyMeter()
+    /// Client-queue sampler (see `clientQueueP50Ms`) — fed per AU by the stream view's onFrame,
+    /// drained by the same 1 s tick as the stage meters.
+    let clientQueue = LatencyMeter()
     /// The OS present floor sampler (see `osFloorP50Ms`) — fed one sample per display-link
     /// update by the deadline engine, drained by the same 1 s tick as the stage meters.
     let presentFloor = LatencyMeter()
@@ -489,6 +498,7 @@ final class SessionModel: ObservableObject {
         endToEndValid = false
         decodeValid = false
         displayValid = false
+        clientQueueValid = false
         osFloorValid = false
         lostFrames = 0
         lostPct = 0
@@ -679,6 +689,12 @@ final class SessionModel: ObservableObject {
                 } else {
                     self.osFloorValid = false
                 }
+                if let q = self.clientQueue.drain() {
+                    self.clientQueueP50Ms = q.p50Ms
+                    self.clientQueueValid = true
+                } else {
+                    self.clientQueueValid = false
+                }
                 // Mirror the window to the unified log (see statsLog) — one line per second,
                 // stages in ms, only while frames actually flowed. `fps` counts RECEIVED AUs;
                 // `presents` counts frames that reached glass (the display meter's sample count)
@@ -691,7 +707,7 @@ final class SessionModel: ObservableObject {
                     let line = String(
                         format: "fps=%d presents=%d e2e_p50=%.1f e2e_p95=%.1f hostnet_p50=%.1f "
                             + "decode_p50=%.1f display_p50=%.1f lost=%d "
-                            + "floor_p50=%.1f display_adj=%.1f e2e_adj=%.1f",
+                            + "floor_p50=%.1f display_adj=%.1f e2e_adj=%.1f queue_p50=%.1f",
                         frames,
                         displayWindow?.count ?? 0,
                         self.endToEndValid ? self.endToEndP50Ms : -1,
@@ -702,7 +718,8 @@ final class SessionModel: ObservableObject {
                         lost,
                         self.osFloorValid ? self.osFloorP50Ms : -1,
                         self.displayValid ? self.displayAdjP50Ms : -1,
-                        self.endToEndValid ? self.endToEndAdjP50Ms : -1)
+                        self.endToEndValid ? self.endToEndAdjP50Ms : -1,
+                        self.clientQueueValid ? self.clientQueueP50Ms : -1)
                     statsLog.info("\(line, privacy: .public)")
                 }
             }

clients/apple/Sources/PunktfunkClient/Session/StreamHUDView.swift

@@ -118,6 +118,16 @@ struct StreamHUDView: View {
                             .font(.system(.caption2, design: .monospaced))
                             .foregroundStyle(.tertiary)
                     }
+                    // Client-queue wait (reassembly receipt → decode pull, ABI v9 split): ~0 on
+                    // a healthy stream and hidden as noise; shown from 2 ms — a persistent value
+                    // is a client-side standing backlog that pre-split builds displayed as
+                    // "network" (the 2026-07 two-pair plateau). The core's standing-latency
+                    // bleed logs alongside when it acts on the same state.
+                    if model.clientQueueValid && model.clientQueueP50Ms >= 2 {
+                        Text("client queue +\(model.clientQueueP50Ms, specifier: "%.1f") (receive backlog — standing if it persists)")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.tertiary)
+                    }
                 }
             } else if model.hostNetworkValid {
                 // Stage-1 fallback presenter: the layer decodes + presents internally with no

clients/apple/Sources/PunktfunkKit/Connection/PunktfunkConnection.swift

@@ -35,10 +35,31 @@ public struct AccessUnit: Sendable {
     public let ptsNs: UInt64
     public let frameIndex: UInt32
     public let flags: UInt32
-    /// Client `CLOCK_REALTIME` instant the AU was handed over by the core (post-FEC, decrypted)
+    /// Client `CLOCK_REALTIME` instant the AU finished reassembly in the core (post-FEC,
-    /// — the **received** measurement point of design/stats-unification.md. The decode stage is
+    /// decrypted — `PunktfunkFrame.received_ns`, ABI v9) — the **received** measurement point of
-    /// `decodedNs - receivedNs`, both client-local (no skew offset applies).
+    /// design/stats-unification.md. NOT the pull instant: stamping at the pull folded the
+    /// pre-decode hand-off wait into the network term, which is how the 2026-07 two-pair
+    /// standing-latency plateau hid as "network". The decode stage is `decodedNs - receivedNs`,
+    /// both client-local (no skew offset applies).
     public let receivedNs: Int64
+    /// Client `CLOCK_REALTIME` instant this pull returned. `pulledNs - receivedNs` is the
+    /// client-queue wait (kernel hand-off + FrameChannel dwell) — the term the HUD splits out
+    /// so a client-side standing backlog can never masquerade as network latency again.
+    public let pulledNs: Int64
+
+    /// `pulledNs` defaults to `receivedNs` (zero queue wait) for callers with no pull instant —
+    /// the synthetic probe AUs and decode tests, where the split is meaningless.
+    public init(
+        data: Data, ptsNs: UInt64, frameIndex: UInt32, flags: UInt32,
+        receivedNs: Int64, pulledNs: Int64? = nil
+    ) {
+        self.data = data
+        self.ptsNs = ptsNs
+        self.frameIndex = frameIndex
+        self.flags = flags
+        self.receivedNs = receivedNs
+        self.pulledNs = pulledNs ?? receivedNs
+    }
 }
 
 /// One Opus audio packet (48 kHz stereo, 5 ms frames) — decode with AVAudioConverter
@@ -662,11 +683,16 @@ public final class PunktfunkConnection {
             let data = Data(bytes: base, count: Int(frame.len)) // copy: ptr valid only until next call
             var ts = timespec()
             clock_gettime(CLOCK_REALTIME, &ts)
-            let receivedNs = Int64(ts.tv_sec) * 1_000_000_000 + Int64(ts.tv_nsec)
+            let pulledNs = Int64(ts.tv_sec) * 1_000_000_000 + Int64(ts.tv_nsec)
+            // Receipt = the core's reassembly-completion stamp (ABI v9); the pull instant is
+            // kept separately so the client-queue wait is its own measured term. 0 would mean a
+            // pre-v9 core — impossible here (core and Kit ship in one binary), but fall back to
+            // the pull instant rather than record a 1970 receipt.
+            let receivedNs = frame.received_ns > 0 ? Int64(frame.received_ns) : pulledNs
             return AccessUnit(
                 data: data, ptsNs: frame.pts_ns,
                 frameIndex: frame.frame_index, flags: frame.flags,
-                receivedNs: receivedNs)
+                receivedNs: receivedNs, pulledNs: pulledNs)
         case statusNoFrame:
             return nil
         case statusClosed:

clients/apple/Sources/PunktfunkKit/Video/Stage2Pipeline.swift

@@ -1213,7 +1213,9 @@ public final class Stage2Pipeline {
                         let chunkAligned =
                             au.flags & PunktfunkConnection.userFlagChunkAligned != 0
                         let ptsNs = au.ptsNs
-                        let receivedNs = au.receivedNs
+                        // Decode stage starts at the PULL (matching the VT path's FrameContext —
+                        // receipt→pull is the HUD's separate client-queue term, ABI v9 split).
+                        let receivedNs = au.pulledNs
                         let flags = au.flags
                         let submitted = decoder.decode(
                             au: au.data, chunkAligned: chunkAligned, windowSize: windowSize

clients/apple/Sources/PunktfunkKit/Video/VideoDecoder.swift

@@ -32,9 +32,12 @@ public enum ReadyImage: @unchecked Sendable {
 public struct ReadyFrame: @unchecked Sendable {
     /// Host capture clock (the AU's pts), in nanoseconds.
     public let ptsNs: UInt64
-    /// Client `CLOCK_REALTIME` instant the AU was received (`AccessUnit.receivedNs`, threaded
+    /// Client `CLOCK_REALTIME` instant the AU left `nextAU` (`AccessUnit.pulledNs`, threaded
-    /// through the decode via the frame refcon), in nanoseconds. 0 when unknown (a caller that
+    /// through the decode via the frame refcon), in nanoseconds — the decode stage's start
-    /// didn't stamp receipt) — the decode-stage meter then drops the sample via its sanity guard.
+    /// point. (Named for its historical role; since the ABI v9 receipt split the true
+    /// reassembly receipt lives on `AccessUnit.receivedNs`, and receipt→pull is the HUD's own
+    /// client-queue term.) 0 when unknown (a caller that didn't stamp) — the decode-stage meter
+    /// then drops the sample via its sanity guard.
     public let receivedNs: Int64
     /// Client `CLOCK_REALTIME` instant decode completed, in nanoseconds.
     public let decodedNs: Int64
@@ -167,7 +170,11 @@ public final class VideoDecoder: @unchecked Sendable {
         var infoOut = VTDecodeInfoFlags()
         // The AU's receipt instant + wire flags ride through as a retained context; the output
         // callback reclaims it. Retain immediately before submit so no early return can leak it.
-        let ctx = FrameContext(receivedNs: au.receivedNs, flags: au.flags)
+        // The decode stage starts at the PULL (the AU leaving nextAU), not the reassembly
+        // receipt: both consumers — the decode-stage meter and the ABR decode signal — are
+        // specified from the pull, and the receipt→pull wait is the HUD's separate client-queue
+        // term (see AccessUnit.pulledNs).
+        let ctx = FrameContext(receivedNs: au.pulledNs, flags: au.flags)
         let refcon = Unmanaged.passRetained(ctx).toOpaque()
         let status = VTDecompressionSessionDecodeFrame(
             session,

clients/linux/src/ui_settings.rs

@@ -856,7 +856,15 @@ pub fn show(
         s.render_scale =
             RENDER_SCALES[(scale_row.selected() as usize).min(RENDER_SCALES.len() - 1)];
         s.bitrate_kbps = (bitrate_row.value() * 1000.0) as u32;
-        s.gamepad = GAMEPADS[(pad_row.selected() as usize).min(GAMEPADS.len() - 1)].to_string();
+        // Keep a stored preference this table doesn't list (e.g. "switchpro" — valid to the
+        // session, hand-edited or written by another client): it displays as "Automatic", and
+        // writing that back would silently erase it just by opening + closing the dialog.
+        // Persist the row only when the user picked a non-Auto entry or the stored value was
+        // a listed one to begin with.
+        let pad_sel = (pad_row.selected() as usize).min(GAMEPADS.len() - 1);
+        if pad_sel != 0 || GAMEPADS.contains(&s.gamepad.as_str()) {
+            s.gamepad = GAMEPADS[pad_sel].to_string();
+        }
         s.touch_mode =
             TOUCH_MODES[(touch_row.selected() as usize).min(TOUCH_MODES.len() - 1)].to_string();
         s.forward_pad = chosen_pin.borrow().clone();

clients/probe/src/main.rs

@@ -458,7 +458,11 @@ async fn session(args: Args) -> Result<()> {
         ),
         (None, None) => tracing::info!(%remote, "punktfunk/1 connected"),
     }
-    let (mut send, mut recv) = conn.open_bi().await.context("open control stream")?;
+    let (mut send, recv) = conn.open_bi().await.context("open control stream")?;
+    // Frame every read on the control stream through the resumable reader, exactly as the client
+    // pump does: `clock_sync` bounds each read with a timeout, and a frame straddling two wakeups
+    // would otherwise leave the stream permanently misaligned for the rest of the run.
+    let mut recv = io::MsgReader::new(recv);
 
     io::write_msg(
         &mut send,
@@ -513,8 +517,8 @@ async fn session(args: Args) -> Result<()> {
         .encode(),
     )
     .await?;
-    let welcome = Welcome::decode(&io::read_msg(&mut recv).await?)
+    let welcome =
-        .map_err(|e| anyhow!("Welcome decode: {e:?}"))?;
+        Welcome::decode(&recv.read_msg().await?).map_err(|e| anyhow!("Welcome decode: {e:?}"))?;
     tracing::info!(
         mode = ?welcome.mode,
         fec = ?welcome.fec,
@@ -629,10 +633,7 @@ async fn session(args: Args) -> Result<()> {
                 tracing::error!("Reconfigure write failed");
                 return;
             }
-            match io::read_msg(&mut rr)
+            match rr.read_msg().await.map(|b| Reconfigured::decode(&b)) {
-                .await
-                .map(|b| Reconfigured::decode(&b))
-            {
                 Ok(Ok(ack)) if ack.accepted => {
                     tracing::info!(mode = ?ack.mode, "mode switch ACCEPTED")
                 }
@@ -685,10 +686,7 @@ async fn session(args: Args) -> Result<()> {
                         tracing::error!("SetBitrate write failed");
                         return;
                     }
-                    match io::read_msg(&mut rr)
+                    match rr.read_msg().await.map(|b| BitrateChanged::decode(&b)) {
-                        .await
-                        .map(|b| BitrateChanged::decode(&b))
-                    {
                         Ok(Ok(ack)) => tracing::info!(
                             applied_kbps = ack.bitrate_kbps,
                             "BITRATE CHANGE acked by host"
@@ -750,7 +748,7 @@ async fn session(args: Args) -> Result<()> {
                 tracing::error!("ProbeRequest write failed");
                 return;
             }
-            let res = match io::read_msg(&mut sr).await.map(|b| ProbeResult::decode(&b)) {
+            let res = match sr.read_msg().await.map(|b| ProbeResult::decode(&b)) {
                 Ok(Ok(r)) => r,
                 other => {
                     tracing::error!(?other, "bad ProbeResult");

clients/session/Cargo.toml

@@ -27,9 +27,13 @@ ui = ["dep:pf-console-ui", "dep:serde_json"]
 # Same Linux+Windows gating as the rest of the client stack; elsewhere this is a stub
 # binary.
 [target.'cfg(any(target_os = "linux", windows))'.dependencies]
-pf-presenter = { path = "../../crates/pf-presenter" }
+# `default-features = false` on both: THIS crate's `pyrowave` feature (above) is the single
+# switch that turns the wavelet codec on, and it enables it explicitly on each. Inheriting their
+# defaults instead would make `--no-default-features` a lie — the Windows ARM64 leg builds that
+# way precisely to skip the vendored PyroWave C++, which has no ARM64 SIMD path.
+pf-presenter = { path = "../../crates/pf-presenter", default-features = false }
 pf-console-ui = { path = "../../crates/pf-console-ui", optional = true }
-pf-client-core = { path = "../../crates/pf-client-core" }
+pf-client-core = { path = "../../crates/pf-client-core", default-features = false }
 punktfunk-core = { path = "../../crates/punktfunk-core", features = ["quic"] }
 # The fake-library dev hook (`PUNKTFUNK_FAKE_LIBRARY`, browse mode) parses GameEntry JSON.
 serde_json = { version = "1", optional = true }

clients/windows/Cargo.toml

@@ -29,7 +29,17 @@ punktfunk-core = { path = "../../crates/punktfunk-core", features = ["quic"] }
 # The shared client service layer: the trust/settings stores (ONE `Settings` struct for the
 # shell and the spawned session binary — src/trust.rs re-exports it) and the game-library
 # data model (fetch + art pipeline) behind the library page.
-pf-client-core = { path = "../../crates/pf-client-core" }
+#
+# `default-features = false` drops pf-client-core's default `pyrowave`, which would otherwise
+# build the vendored PyroWave C++ INTO THE SHELL — dead weight here (the shell never decodes;
+# it only offers "pyrowave" as a codec preference string the session binary acts on) and fatal
+# on ARM64, where Granite's math falls back to x86 SSE intrinsics and stops at
+# `simd.hpp: #error "Implement me."`. This does NOT drop PyroWave from the Windows client:
+# decode lives in the spawned punktfunk-session binary, whose own default enables the feature,
+# and cargo's feature unification turns it back on for the shared pf-client-core whenever that
+# binary is in the same build (x64). On the ARM64 leg both are built --no-default-features, so
+# nothing enables it and the C++ is never compiled.
+pf-client-core = { path = "../../crates/pf-client-core", default-features = false }
 
 # WinUI 3 UI via windows-reactor (a declarative React-like framework backed by WinUI). Its
 # `build.rs` downloads the Windows App SDK NuGets and stages the bootstrap DLL + resources.pri

clients/windows/packaging/AppxManifest.xml

@@ -59,9 +59,14 @@
     </Application>
     <!--
       Second entry point: the couch/console UI, for an HTPC or a TV-attached box where the
-      desktop shell is the wrong first screen. Same full-trust executable, launched with
+      desktop shell is the wrong first screen. Its own executable (punktfunk-console.exe)
-      `--console`, which hands straight off to the session binary's controller-driven
+      because an MSIX Application entry cannot pass arguments to a full-trust exe; it hands
-      browse mode (host list, pairing, settings, library) fullscreen.
+      straight off to the session binary's controller-driven browse mode (host list,
+      pairing, settings, library) fullscreen.
+
+      NOTE: never write a double hyphen in this file. XML forbids it inside a comment, and
+      makepri rejects the whole manifest ("Appx manifest not found or is invalid") — which
+      is exactly how the console flag spelled out here broke the v0.15.0 MSIX build.
     -->
     <Application Id="PunktfunkConsole" Executable="punktfunk-console.exe"
                  EntryPoint="Windows.FullTrustApplication">

crates/pf-capture/src/linux/mod.rs

@@ -1310,21 +1310,25 @@ mod pipewire {
     /// (which Mutter delivers as metadata-only "corrupted" buffers) still refresh the position.
     fn update_cursor_meta(cursor: &mut CursorState, spa_buf: *mut spa::sys::spa_buffer) {
         // SAFETY: `spa_buf` is the live buffer we still hold (dequeued, not yet requeued).
-        // `spa_buffer_find_meta_data` scans its metadata array for a `SPA_META_Cursor` of at least
+        // `spa_buffer_find_meta` returns the `spa_meta` (type + byte `size` + `data` pointer) for
-        // `size_of::<spa_meta_cursor>()` bytes and returns a pointer into that buffer's metadata
+        // `SPA_META_Cursor`, or null. We take `find_meta` rather than `find_meta_data` specifically
-        // (or null), valid until requeue. The size argument matches the struct the result is cast to.
+        // to obtain the region's real `size`: the bitmap offset, pixel offset and stride read below
-        let cur = unsafe {
+        // are ALL producer-written, and without a bound against the actual region they drive
-            spa::sys::spa_buffer_find_meta_data(
+        // out-of-bounds pointer arithmetic and an oversized `slice::from_raw_parts` — an OOB read
-                spa_buf,
+        // that SIGSEGVs inside the PipeWire `.process` callback (a segfault `catch_unwind` cannot
-                spa::sys::SPA_META_Cursor,
+        // catch). Every offset below is validated against `region_size` with checked arithmetic,
-                std::mem::size_of::<spa::sys::spa_meta_cursor>(),
+        // mirroring the fd-length guard the main frame path already applies to xdg-desktop-portal-wlr.
-            ) as *const spa::sys::spa_meta_cursor
+        let meta = unsafe { spa::sys::spa_buffer_find_meta(spa_buf, spa::sys::SPA_META_Cursor) };
-        };
+        if meta.is_null() {
-        if cur.is_null() {
             return;
         }
-        // SAFETY: `cur` is non-null and points to a `spa_meta_cursor` of at least its own size
+        // SAFETY: `meta` is non-null and points into the held buffer's metadata array.
-        // inside the held buffer (guaranteed by the size arg above), so every field read is in bounds.
+        let (region_size, data) = unsafe { ((*meta).size as usize, (*meta).data as *const u8) };
+        if data.is_null() || region_size < std::mem::size_of::<spa::sys::spa_meta_cursor>() {
+            return;
+        }
+        let cur = data as *const spa::sys::spa_meta_cursor;
+        // SAFETY: `region_size >= size_of::<spa_meta_cursor>()` checked above, so every field is in bounds.
         let (id, pos_x, pos_y, hot_x, hot_y, bmp_off) = unsafe {
             (
                 (*cur).id,
@@ -1347,13 +1351,18 @@ mod pipewire {
             // Position-only update — keep the cached bitmap.
             return;
         }
-        // SAFETY: `bitmap_offset` is a byte offset from `cur` to a `spa_meta_bitmap`, which the
+        let bmp_off = bmp_off as usize;
-        // producer placed inside the same meta region it sized for this cursor (>= the size we
+        // The `spa_meta_bitmap` header must fit entirely inside the region before we read it —
-        // requested). The resulting pointer is in bounds and aligned for `spa_meta_bitmap`.
+        // `bitmap_offset` is producer-controlled and otherwise reads past the metadata.
-        let bmp =
+        match bmp_off.checked_add(std::mem::size_of::<spa::sys::spa_meta_bitmap>()) {
-            unsafe { (cur as *const u8).add(bmp_off as usize) as *const spa::sys::spa_meta_bitmap };
+            Some(end) if end <= region_size => {}
-        // SAFETY: `bmp` is the in-bounds, aligned `spa_meta_bitmap` pointer computed just above; the
+            _ => return,
-        // producer fully initialized this header, so reading its scalar fields is sound.
+        }
+        // SAFETY: `bmp_off + size_of::<spa_meta_bitmap>() <= region_size` (checked directly above),
+        // so the header is fully in bounds; the producer places it aligned as before.
+        let bmp = unsafe { data.add(bmp_off) as *const spa::sys::spa_meta_bitmap };
+        // SAFETY: `bmp` is the in-bounds `spa_meta_bitmap` header validated just above; reading its
+        // scalar fields is sound.
         let (vfmt, bw, bh, stride, pix_off) = unsafe {
             (
                 (*bmp).format,
@@ -1369,10 +1378,27 @@ mod pipewire {
         }
         let row = bw as usize * 4;
         let stride = if stride < row { row } else { stride };
-        let span = stride * (bh as usize - 1) + row;
+        // `span` is the exact byte extent the strided loop reads: `stride·(bh-1) + row`. Compute it
-        // SAFETY: the bitmap pixels live at `bmp + pix_off` for `span` bytes, within the
+        // with checked arithmetic (a producer stride near `i32::MAX` would otherwise overflow) and
-        // producer-sized meta region. `span` is the exact extent the strided copy below reads.
+        // require the whole pixel block `[bmp_off + pix_off, +span)` to lie inside the region before
-        let src = unsafe { std::slice::from_raw_parts((bmp as *const u8).add(pix_off), span) };
+        // fabricating the slice — this is the check whose absence made the read go out of bounds.
+        let span = match stride
+            .checked_mul(bh as usize - 1)
+            .and_then(|v| v.checked_add(row))
+        {
+            Some(s) => s,
+            None => return,
+        };
+        match bmp_off
+            .checked_add(pix_off)
+            .and_then(|v| v.checked_add(span))
+        {
+            Some(end) if end <= region_size => {}
+            _ => return,
+        }
+        // SAFETY: `bmp_off + pix_off + span <= region_size` (checked directly above), so the slice
+        // is fully within the producer's meta region; `span` is exactly the strided loop's extent.
+        let src = unsafe { std::slice::from_raw_parts(data.add(bmp_off + pix_off), span) };
         let mut rgba = vec![0u8; bw as usize * bh as usize * 4];
         for y in 0..bh as usize {
             for x in 0..bw as usize {
@@ -2164,36 +2190,37 @@ mod pipewire {
                 }
             })
             .process(|stream, ud| {
-                // PipeWire dispatches this from a C trampoline with no catch_unwind; a
+                // Latest-frame-only (OBS pattern): Mutter delivers buffers in bursts and recycles its
-                // panic crossing that FFI boundary would abort the whole host. Contain it.
+                // pool; an older queued buffer carries a STALE frame. Drain all queued buffers, requeue
-                let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                // the older ones, keep only the newest. This dequeue/requeue runs OUTSIDE the
-                    // Latest-frame-only (OBS pattern): Mutter delivers buffers in bursts and
+                // `catch_unwind` below — they are non-panicking C FFI pointer ops, and `newest` is
-                    // recycles its pool; an older queued buffer carries a STALE frame. Drain all
+                // requeued exactly once AFTER the panic-containing region. Previously the whole thing was
-                    // queued buffers, requeue the older ones, keep only the newest.
+                // inside the catch, so a caught panic (in `update_cursor_meta`/`consume_frame`) stranded
-                    // SAFETY: `stream` is the live stream PipeWire passes into this `.process` callback on
+                // `newest` forever, permanently shrinking the stream's fixed pool until capture wedged.
-                    // the loop thread, where `pw_stream_dequeue_buffer` is the documented call. It returns
+                // SAFETY: `stream` is the live stream PipeWire passes into this `.process` callback on the
-                    // a `*mut pw_buffer` owned by the stream (or null when the queue is drained),
+                // loop thread; `dequeue_raw_buffer` returns a stream-owned `*mut pw_buffer` or null
-                    // null-checked before any use. The loop is single-threaded, so no concurrent access.
+                // (null-checked), single-threaded so no concurrent access.
                 let mut newest = unsafe { stream.dequeue_raw_buffer() };
                 if newest.is_null() {
                     return;
                 }
                 let mut drained = 1u32;
                 loop {
-                        // SAFETY: same stream/loop-thread contract as the dequeue above; each call returns
+                    // SAFETY: same stream/loop-thread contract; returns the next stream-owned buffer or null.
-                        // the next stream-owned `*mut pw_buffer` or null (null-checked before use).
                     let next = unsafe { stream.dequeue_raw_buffer() };
                     if next.is_null() {
                         break;
                     }
-                        // SAFETY: `newest` is a non-null `*mut pw_buffer` previously dequeued from this same
+                    // SAFETY: `newest` was dequeued from this stream and not yet requeued; we immediately
-                        // stream and not yet requeued; `pw_stream_queue_buffer` hands ownership back to the
+                    // overwrite it, so the requeued pointer is never touched again.
-                        // stream. We immediately overwrite `newest = next`, so the requeued pointer is never
-                        // touched again (no use-after-requeue). Loop thread, single-threaded.
                     unsafe { stream.queue_raw_buffer(newest) };
                     newest = next;
                     drained += 1;
                 }
+                // PipeWire dispatches from a C trampoline with no catch_unwind; a panic crossing that FFI
+                // boundary would abort the whole host. Contain the inspect/consume work — the only Rust
+                // code here that can panic — and requeue `newest` unconditionally after it.
+                let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                     // SAFETY: `newest` is the non-null buffer we still own (dequeued, not requeued);
                     // `.buffer` is a `*mut spa_buffer` field libpipewire populated. This is a single field
                     // load through a valid pointer — no mutation or aliasing.
@@ -2272,19 +2299,18 @@ mod pipewire {
                                 "capture: skipped a stale CORRUPTED/cursor buffer (GNOME)"
                             );
                         }
-                        // SAFETY: `newest` is the non-null buffer we own (dequeued, never requeued on this
+                        // Skip this stale/cursor buffer — `newest` is requeued unconditionally below.
-                        // skip path); hand it back to the stream exactly once and return without touching it
-                        // again. Loop thread inside `.process`.
-                        unsafe { stream.queue_raw_buffer(newest) };
                         return;
                     }
 
                     consume_frame(ud, spa_buf);
-                    // SAFETY: `consume_frame` has finished reading `spa_buf` (and the `datas` borrows derived
-                    // from `newest`), so requeuing the owned `newest` exactly once here is sound — no
-                    // use-after-requeue. Loop thread inside `.process`.
-                    unsafe { stream.queue_raw_buffer(newest) };
                 }));
+                // Hand `newest` back to the stream exactly once, on EVERY path — normal, corrupted-skip,
+                // or a caught panic in the closure above. This single requeue is what keeps the fixed
+                // buffer pool from draining.
+                // SAFETY: all reads of `spa_buf`/`newest` (update_cursor_meta, consume_frame) completed
+                // inside the closure above; `newest` was dequeued from this stream and not yet requeued.
+                unsafe { stream.queue_raw_buffer(newest) };
                 if outcome.is_err() {
                     // In the per-frame `.process` callback: a deterministic panic (e.g. a bad
                     // format) would fire this every frame, so power-of-two throttle it — enough to

crates/pf-capture/src/windows/idd_push.rs

@@ -1341,6 +1341,12 @@ impl IddPushCapturer {
         self.out_ring.clear(); // the output format changed → rebuild lazily at the new format
         self.video_conv = None; // converters are sized + HDR-specific → rebuild at the new mode
         self.hdr_p010_conv = None;
+        // The PyroWave CSC is mode-baked too (BgraToYuvPlanes picks different SDR vs HDR shaders
+        // and R8/R8G8 vs R16/R16G16 outputs). Without this, a display_hdr flip (Downgrade point D:
+        // client_10bit=true but HDR couldn't enable at open) reused the stale SDR converter against
+        // the freshly HDR-formatted pyro ring — every frame corrupted. `ensure_pyro_conv` only
+        // builds when None, so it must be reset here like its siblings.
+        self.pyro_conv = None;
         self.pyro_ring.clear(); // PyroWave two-plane ring is sized → rebuild at the new mode
         self.pyro_last = None;
         self.out_idx = 0;
@@ -1861,6 +1867,7 @@ impl IddPushCapturer {
                     cbcr,
                     fence_handle,
                     fence_value,
+                    ring_gen: self.generation,
                 }),
             )
         } else {
@@ -1919,6 +1926,7 @@ impl IddPushCapturer {
                         cbcr: dst_cbcr,
                         fence_handle,
                         fence_value,
+                        ring_gen: self.generation,
                     }),
                 }),
                 cursor: None,

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

@@ -447,8 +447,16 @@ fn pump(
         // every ~8–16 ms at 60–120 Hz anyway, so this rarely times out mid-stream).
         match connector.next_frame(Duration::from_millis(20)) {
             Ok(frame) => {
-                // The `received` point: AU fully reassembled, in hand, before decode.
+                // The `received` point: reassembly COMPLETION, stamped by the core session as
-                let received_ns = now_ns();
+                // the AU crossed poll_frame (ABI v9). Stamping here at the hand-off pull instead
+                // would fold the pre-decode queue wait into `host+network` — a client-side
+                // standing backlog masquerading as network latency (the 2026-07 two-pair
+                // investigation). 0 = a core predating the stamp; fall back to the pull instant.
+                let received_ns = if frame.received_ns > 0 {
+                    frame.received_ns
+                } else {
+                    now_ns()
+                };
                 // fps / goodput count every received AU (spec), decoded or not.
                 frames_n += 1;
                 bytes_n += frame.data.len() as u64;

crates/pf-encode/src/enc/codec.rs

@@ -219,6 +219,11 @@ pub struct EncoderCaps {
 
 /// A hardware encoder. One per session; runs on the encode thread.
 pub trait Encoder: Send {
+    /// Submit one captured frame for encoding. Lifetime contract: the caller must keep `frame`
+    /// (and its GPU payload) alive until this frame's AU has been returned by
+    /// [`poll`](Self::poll) — a stream-ordered backend (Linux direct-NVENC's IO-stream binding)
+    /// may still be reading the payload asynchronously after `submit` returns. Both host encode
+    /// loops already hold the frame across their poll drain; new callers must do the same.
     fn submit(&mut self, frame: &CapturedFrame) -> Result<()>;
     /// [`submit`](Self::submit) with the **wire frame index** this frame's AU will carry — the
     /// number the packetizer stamps on it and the client's loss reports/RFI requests name. The
@@ -264,6 +269,15 @@ pub trait Encoder: Send {
     fn invalidate_ref_frames(&mut self, _first_frame: i64, _last_frame: i64) -> bool {
         false
     }
+    /// Escalate into a pipelined (two-thread) retrieve mode under sustained GPU contention — the
+    /// encoder analog of the capturer depth escalation: AUs ride ~one loop tick behind (`poll`
+    /// may return `None` while an encode is in flight) in exchange for capture/submit no longer
+    /// serializing on the encode wait. Returns whether pipelined retrieve is (now) active; the
+    /// switch may be deferred to the next safe point internally. `false` from the default impl =
+    /// unsupported — the session loop stops asking. De-escalation is a v2 item everywhere.
+    fn set_pipelined(&mut self, _on: bool) -> bool {
+        false
+    }
     /// Pull the next encoded AU if one is ready.
     fn poll(&mut self) -> Result<Option<EncodedFrame>>;
     /// Tear the underlying hardware encoder down and rebuild it in place, keeping the session's
@@ -293,6 +307,16 @@ pub trait Encoder: Send {
     /// flagged [`EncodedFrame::chunk_aligned`] and the session marks them on the wire.
     /// Default: no-op (the H.26x backends' bitstreams cannot be cut losslessly).
     fn set_wire_chunking(&mut self, _shard_payload: usize) {}
+    /// How many frames the CAPTURER guarantees the encoder may hold in flight before it starts
+    /// reusing an input texture (`Capturer::pipeline_depth`). Backends that encode the capturer's
+    /// textures IN PLACE — no `CopyResource` — must not pipeline deeper than this: the capturer
+    /// rotates its output ring per delivered frame with no regard for encode completion, so a
+    /// deeper pipeline lets it overwrite a texture mid-encode. That is visual corruption (torn or
+    /// mixed frames), not UB, so it fails silently and intermittently.
+    ///
+    /// Called once by the session glue after the capturer is known; a backend that copies its
+    /// input, or is synchronous, ignores it. Default: no-op.
+    fn set_input_ring_depth(&mut self, _depth: usize) {}
     /// Signal end-of-stream. After this, drain the remaining AUs with [`poll`](Self::poll)
     /// until it returns `None` — NVENC buffers frames internally even at `delay=0`.
     fn flush(&mut self) -> Result<()>;

crates/pf-encode/src/enc/linux/mod.rs

@@ -826,7 +826,7 @@ impl NvencEncoder {
                         (*f).linesize[i] as usize,
                     )
                 });
-                pf_zerocopy::cuda::copy_yuv444_to_device(buf, dsts)
+                pf_zerocopy::cuda::copy_yuv444_to_device(buf, dsts, true)
             } else if self.want_444 {
                 ffi::av_frame_free(&mut f);
                 bail!(
@@ -839,11 +839,11 @@ impl NvencEncoder {
                 let y_pitch = (*f).linesize[0] as usize;
                 let uv_ptr = (*f).data[1] as pf_zerocopy::cuda::CUdeviceptr;
                 let uv_pitch = (*f).linesize[1] as usize;
-                pf_zerocopy::cuda::copy_nv12_to_device(buf, y_ptr, y_pitch, uv_ptr, uv_pitch)
+                pf_zerocopy::cuda::copy_nv12_to_device(buf, y_ptr, y_pitch, uv_ptr, uv_pitch, true)
             } else {
                 let dst_ptr = (*f).data[0] as pf_zerocopy::cuda::CUdeviceptr;
                 let dst_pitch = (*f).linesize[0] as usize;
-                pf_zerocopy::cuda::copy_device_to_device(buf, dst_ptr, dst_pitch)
+                pf_zerocopy::cuda::copy_device_to_device(buf, dst_ptr, dst_pitch, true)
             };
             if let Err(e) = copy_res {
                 ffi::av_frame_free(&mut f);

crates/pf-encode/src/enc/linux/nvenc_cuda.rs

@@ -16,12 +16,20 @@
 //!     ([`zerocopy::cuda::InputSurface`]): each captured `FramePayload::Cuda` `DeviceBuffer` is
 //!     device→device copied into the current ring slot (via the existing `copy_*_to_device`
 //!     helpers) before `encode_picture`. This mirrors the libav path's recycled-hwframe-pool copy
-//!     (NVENC rejects a null-`buf[0]` frame and its CUDADEVICEPTR registration cache is bounded +
+//!     (NVENC rejects a null-`buf[0]` frame; the captured buffer is worker-owned CUDA-IPC memory
-//!     pointer-keyed, so registering a fresh pool pointer each frame would thrash it) — so it is
+//!     recycled on drop, so registering it directly needs a contiguous worker-pool layout + a
-//!     zero regression versus today; true zero-copy input registration is a follow-up.
+//!     registration↔IPC-mapping lifetime tie — the true zero-copy follow-up, plan §7 LN2 v2).
+//!     **Stream-ordered submit** (default, `PUNKTFUNK_NVENC_STREAM_ORDERED=0` reverts): the
+//!     session's IO streams are bound to the encode thread's copy stream
+//!     (`NvEncSetIOCudaStreams`), so in sync-retrieve depth-1 use the copy + cursor blend enqueue
+//!     with NO per-frame `cuStreamSynchronize` and the encode orders after them on the stream —
+//!     the submit path's CPU stalls are gone even though the copy itself remains.
 //!
-//! **Two-thread retrieve** (`PUNKTFUNK_NVENC_ASYNC=1`, the same opt-in knob as the Windows
+//! **Two-thread retrieve** (`PUNKTFUNK_NVENC_ASYNC`: `1` = always, `0` = never, unset =
-//! backend — gpu-contention plan §5.B, latency plan T2.2): NVENC *async mode*
+//! **adaptive** — engaged by the session loop's contention escalation via
+//! [`Encoder::set_pipelined`] when depth-1 can't hold cadence; at depth-1 it costs ~one loop
+//! tick of latency, which is why it is not simply on. gpu-contention plan §5.B, latency plan
+//! T2.2/§7 LN3): NVENC *async mode*
 //! (`enableEncodeAsync` + completion events) is Windows-only, so the session here stays SYNC —
 //! but the NVENC guide's threading model still applies: the main thread should only *submit*
 //! while a secondary thread does the (blocking) `nvEncLockBitstream`. With the flag set, an
@@ -120,6 +128,14 @@ struct EncodeApi {
     encode_picture:
         unsafe extern "C" fn(*mut c_void, *mut nv::NV_ENC_PIC_PARAMS) -> nv::NVENCSTATUS,
     invalidate_ref_frames: unsafe extern "C" fn(*mut c_void, u64) -> nv::NVENCSTATUS,
+    /// `NvEncSetIOCudaStreams` — binds the session's input/output ordering to a CUDA stream so the
+    /// input copy + cursor blend can enqueue without a CPU sync (stream-ordered submit). The two
+    /// `NV_ENC_CUSTREAM_PTR` args are pointers TO `CUstream` values.
+    set_io_cuda_streams: unsafe extern "C" fn(
+        *mut c_void,
+        nv::NV_ENC_CUSTREAM_PTR,
+        nv::NV_ENC_CUSTREAM_PTR,
+    ) -> nv::NVENCSTATUS,
 }
 
 /// Resolve the table once per process. `Err` = NVENC genuinely unavailable (no NVIDIA driver/.so,
@@ -212,6 +228,7 @@ fn load_api() -> std::result::Result<EncodeApi, String> {
             unmap_input_resource: list.nvEncUnmapInputResource.ok_or(MISSING)?,
             encode_picture: list.nvEncEncodePicture.ok_or(MISSING)?,
             invalidate_ref_frames: list.nvEncInvalidateRefFrames.ok_or(MISSING)?,
+            set_io_cuda_streams: list.nvEncSetIOCudaStreams.ok_or(MISSING)?,
         };
         std::mem::forget(lib); // keep the .so mapped for the fn pointers' lifetime (process)
         Ok(api)
@@ -223,15 +240,25 @@ fn load_api() -> std::result::Result<EncodeApi, String> {
 /// bitstream/ring slot is never reused mid-encode.
 const POOL: usize = 8;
 
-/// Whether the operator asked for the two-thread retrieve (`PUNKTFUNK_NVENC_ASYNC` truthy — the
+/// The operator's `PUNKTFUNK_NVENC_ASYNC` intent (the SAME knob as the Windows backend):
-/// SAME knob as the Windows backend, so one env drives the split on either host OS). Opt-in
+/// `Some(true)` = force the two-thread retrieve from session open — note that at the Linux
-/// until on-glass validated. Unlike Windows this changes NO session parameter (Linux stays sync
+/// default pipeline depth of 1 this adds ~one loop tick of latency (the non-blocking poll's AU
-/// mode; only the blocking lock moves off the encode thread), so there is no async-rejecting
+/// rides the next tick), so it only pays under GPU contention; `Some(false)` = never (also
-/// config to fail the open.
+/// vetoes the session loop's contention escalation via [`Encoder::set_pipelined`]); `None`
+/// (unset) = adaptive — off until the session loop escalates on sustained cadence overrun.
+/// Unlike Windows this changes NO session parameter (Linux stays sync mode; only the blocking
+/// lock moves off the encode thread), so there is no async-rejecting config to fail the open.
+fn async_retrieve_env() -> Option<bool> {
+    match std::env::var("PUNKTFUNK_NVENC_ASYNC") {
+        Ok(v) if matches!(v.trim(), "1" | "true" | "yes" | "on") => Some(true),
+        Ok(v) if matches!(v.trim(), "0" | "false" | "no" | "off") => Some(false),
+        _ => None,
+    }
+}
+
+/// Operator forced the two-thread retrieve on from session open (see [`async_retrieve_env`]).
 fn async_retrieve_requested() -> bool {
-    std::env::var("PUNKTFUNK_NVENC_ASYNC")
+    async_retrieve_env() == Some(true)
-        .map(|v| matches!(v.trim(), "1" | "true" | "yes" | "on"))
-        .unwrap_or(false)
 }
 
 /// Max encodes in flight in two-thread mode (`PUNKTFUNK_NVENC_ASYNC_DEPTH`, default 4, clamped
@@ -245,6 +272,18 @@ fn async_inflight_cap() -> usize {
         .clamp(2, POOL - 1)
 }
 
+/// Stream-ordered submit (`PUNKTFUNK_NVENC_STREAM_ORDERED`, default ON; `0` = the pre-existing
+/// blocking copies). With the session's IO streams bound to the encode thread's copy stream
+/// (`NvEncSetIOCudaStreams`), the input copy + cursor blend enqueue with NO CPU sync and
+/// `encode_picture` orders after them on the stream — deleting the 1–3 per-frame
+/// `cuStreamSynchronize` stalls from the submit path (latency plan §7 LN2). Sync-retrieve mode
+/// only, and only while nothing is in flight (see the gate in [`Encoder::submit`]).
+fn stream_ordered_requested() -> bool {
+    std::env::var("PUNKTFUNK_NVENC_STREAM_ORDERED")
+        .map(|v| v.trim() != "0")
+        .unwrap_or(true)
+}
+
 /// One in-flight encode handed to the retrieve thread: the output bitstream to (blocking-)lock.
 /// Raw pointer travels as `usize` (a process-global driver handle; the thread is joined before
 /// the session it belongs to is destroyed).
@@ -302,7 +341,14 @@ fn retrieve_loop(
     if let Err(e) = cuda::make_current() {
         tracing::warn!(error = %format!("{e:#}"), "pf-nvenc-out: cuCtxSetCurrent failed");
     }
+    let mut jobs: u64 = 0;
     while let Ok(job) = work_rx.recv() {
+        // In two-thread mode the host loop's `wait_us` wraps a non-blocking poll, so the real
+        // encode wait (scheduling + ASIC) is measured by NO timer there — sample it here instead
+        // (same PUNKTFUNK_PERF cadence as the submit split).
+        let sample = pf_host_config::config().perf && jobs % 120 == 0;
+        jobs += 1;
+        let t0 = std::time::Instant::now();
         // SAFETY: `job.bs` is one of the session's pool bitstreams a prior `encode_picture`
         // targeted; both it and the session stay valid until `teardown`, which joins this thread
         // first. `lock_bitstream` (version set, struct a live stack local for the synchronous
@@ -341,6 +387,16 @@ fn retrieve_loop(
                 )),
             }
         };
+        if sample {
+            if let Ok((data, _)) = &result {
+                tracing::info!(
+                    lock_us = t0.elapsed().as_micros() as u64,
+                    au_kib = (data.len() / 1024) as u64,
+                    "NVENC retrieve lock (sampled): blocking lock_bitstream + AU copy on \
+                     pf-nvenc-out (the async-mode encode wait)"
+                );
+            }
+        }
         if done_tx.send(RetrieveDone { bs: job.bs, result }).is_err() {
             break; // encoder side gone (teardown drains us via join)
         }
@@ -396,6 +452,9 @@ pub struct NvencCudaEncoder {
     /// submit). Empty until the session is initialized.
     ring: Vec<RingSlot>,
     next: usize,
+    /// Frames submitted over the encoder's lifetime (never reset, unlike `next`) — drives the
+    /// sampled `PUNKTFUNK_PERF` submit-split log cadence, mirroring the VAAPI backend's counter.
+    frames: u64,
     bitstreams: Vec<nv::NV_ENC_OUTPUT_PTR>,
     /// (bitstream, mapped input resource to unmap after retrieval, pts_ns, recovery-anchor) per
     /// in-flight encode. The fourth field tags the first frame encoded after a successful
@@ -440,6 +499,19 @@ pub struct NvencCudaEncoder {
     /// The two-thread retrieve runtime (`PUNKTFUNK_NVENC_ASYNC`) — `None` in the default
     /// single-thread mode and between sessions. Exists only `init_session`→`teardown`.
     async_rt: Option<AsyncRetrieve>,
+    /// The session loop escalated into pipelined retrieve ([`Encoder::set_pipelined`], the
+    /// contention analog of the capturer depth escalation). Sticky across session rebuilds
+    /// (escalate-and-hold, like the depth escalation); the switch itself happens at the next
+    /// safe point via [`maybe_engage_async`](Self::maybe_engage_async).
+    want_async: bool,
+    /// Boxed `CUstream` the session's IO-stream binding points at (`NvEncSetIOCudaStreams` takes
+    /// POINTERS to `CUstream`, and this struct moves — the pointee needs a stable heap address for
+    /// the session's lifetime). Null when stream-ordering is off; freed in `teardown` AFTER the
+    /// session is destroyed.
+    io_stream: *mut *mut c_void,
+    /// Stream-ordered submit armed for the live session (sync-retrieve mode only; see
+    /// [`stream_ordered_requested`]). The per-frame gate additionally requires `pending` empty.
+    stream_ordered: bool,
 }
 
 // SAFETY: the `!Send` fields are the raw NVENC session handle (`encoder`), the shared `CUcontext`
@@ -501,6 +573,7 @@ impl NvencCudaEncoder {
             hdr_meta: None,
             ring: Vec::new(),
             next: 0,
+            frames: 0,
             bitstreams: Vec::new(),
             pending: VecDeque::new(),
             frame_idx: 0,
@@ -518,9 +591,35 @@ impl NvencCudaEncoder {
             split_mode: nv::NV_ENC_SPLIT_ENCODE_MODE::NV_ENC_SPLIT_DISABLE_MODE as u32,
             last_rfi_range: None,
             async_rt: None,
+            want_async: false,
+            io_stream: ptr::null_mut(),
+            stream_ordered: false,
         })
     }
 
+    /// Engage the escalated pipelined retrieve at a safe point: nothing in flight, and — because
+    /// a live session has its IO streams bound for stream-ordered submit, whose output-stream
+    /// semantics would make every later stream op wait on the previous encode and so serialize a
+    /// pipelined session — via a clean session rebuild WITHOUT the binding (the re-open's first
+    /// frame is the standard session-opening IDR). No-op until [`want_async`](Self::want_async)
+    /// is set and `pending` drains.
+    fn maybe_engage_async(&mut self) {
+        if !self.want_async || self.async_rt.is_some() || !self.pending.is_empty() {
+            return;
+        }
+        if self.inited {
+            // SAFETY: encode thread, `pending` empty ⇒ no encode in flight; `teardown` handles
+            // exactly this live-session state (and a torn-down encoder lazily re-inits on the
+            // next submit, which spawns the retrieve thread and skips the IO-stream arming).
+            unsafe { self.teardown() };
+            tracing::info!(
+                "NVENC pipelined-retrieve escalation: rebuilding the session without the \
+                 IO-stream binding (stream-ordered submit and two-thread retrieve are mutually \
+                 exclusive); next frame opens with an IDR"
+            );
+        }
+    }
+
     /// Tear down the encode session + pooled resources. Reused on a size change and at Drop.
     unsafe fn teardown(&mut self) {
         if self.encoder.is_null() {
@@ -557,6 +656,14 @@ impl NvencCudaEncoder {
                  session's slot toward the concurrent-session cap"
             );
         }
+        // The boxed CUstream the IO-stream binding pointed at — freed only now, AFTER the session
+        // that referenced it is destroyed (created by `Box::into_raw` in `init_session`, freed
+        // exactly once here; `io_stream` is nulled so a re-init can't double-free).
+        if !self.io_stream.is_null() {
+            drop(Box::from_raw(self.io_stream));
+            self.io_stream = ptr::null_mut();
+        }
+        self.stream_ordered = false;
         self.ring.clear(); // drops the InputSurfaces, freeing their CUDA allocations
         self.bitstreams.clear();
         self.pending.clear();
@@ -619,6 +726,10 @@ impl NvencCudaEncoder {
             enc,
             nv::NV_ENC_CAPS::NV_ENC_CAPS_SUPPORT_CUSTOM_VBV_BUF_SIZE,
         );
+        // Sub-frame-output prerequisites (latency plan §7 LN1): logged for fleet visibility now,
+        // consumed when slice-level readback lands. Not stored — LN1 re-probes when it configures.
+        let subframe = self.get_cap(enc, nv::NV_ENC_CAPS::NV_ENC_CAPS_SUPPORT_SUBFRAME_READBACK);
+        let dyn_slice = self.get_cap(enc, nv::NV_ENC_CAPS::NV_ENC_CAPS_SUPPORT_DYNAMIC_SLICE_MODE);
         let _ = (api().destroy_encoder)(enc);
 
         if wmax > 0 && hmax > 0 && (self.width as i32 > wmax || self.height as i32 > hmax) {
@@ -641,6 +752,8 @@ impl NvencCudaEncoder {
             rfi = self.rfi_supported,
             custom_vbv = self.custom_vbv,
             yuv444 = self.yuv444_supported,
+            subframe_readback = subframe != 0,
+            dynamic_slice = dyn_slice != 0,
             max = %format!("{wmax}x{hmax}"),
             "NVENC (Linux direct) capabilities probed"
         );
@@ -807,7 +920,11 @@ impl NvencCudaEncoder {
         // `try_open_session` just returned (and `best` only when non-null). `create_bitstream_buffer`
         // and `register_resource` take `enc`, the chosen live session, and `&mut` locals whose
         // `version` is set and which outlive the synchronous call. `InputSurface::alloc_*` returns a
-        // live pitched CUDA allocation on the shared context. No handle escapes the encode thread.
+        // live pitched CUDA allocation on the shared context. `set_io_cuda_streams` takes `enc` plus
+        // two pointers to the boxed live `CUstream` (`Box::into_raw`), which outlives the session —
+        // freed exactly once: in `teardown` after `destroy_encoder` when armed, or via
+        // `Box::from_raw` right here on the rejection path (where `io_stream` is never set). No
+        // handle escapes the encode thread.
         unsafe {
             // Bind to the shared CUDA context; make it current on this (encode) thread for both the
             // session open and every subsequent device→device input copy.
@@ -960,13 +1077,53 @@ impl NvencCudaEncoder {
             self.inited = true;
             // Two-thread retrieve (T2.2): spawn the lock thread against the live session. No
             // session parameter differs — teardown/rebuild always stops it before destroy.
-            if async_retrieve_requested() {
+            if async_retrieve_requested() || self.want_async {
                 self.async_rt = Some(AsyncRetrieve::spawn(self.encoder as usize));
                 tracing::info!(
                     depth = async_inflight_cap(),
+                    escalated = self.want_async,
                     "NVENC two-thread retrieve enabled (submit thread + blocking-lock thread)"
                 );
             }
+            // Stream-ordered submit (latency plan §7 LN2): bind the session's IO streams to this
+            // thread's copy stream so the input copy + cursor blend enqueue with no CPU sync and
+            // `encode_picture` orders after them. Same stream both ways: input-stream semantics
+            // start the encode only after our enqueued copies, output-stream semantics insert the
+            // encode's completion INTO the stream — so later stream work (the next frame's copy
+            // into a reused ring slot) also waits for it. Sync-retrieve mode only: in two-thread
+            // mode the captured buffer may be recycled after `submit` returns while the stream
+            // still holds its copy (the blocking copies are the lifetime guarantee there).
+            if self.async_rt.is_none() && stream_ordered_requested() {
+                let stream = cuda::copy_stream_handle();
+                if !stream.is_null() {
+                    // The pointee must outlive the session (the driver takes CUstream POINTERS) —
+                    // box it; `teardown` frees it after `destroy_encoder`.
+                    let holder = Box::into_raw(Box::new(stream));
+                    match (api().set_io_cuda_streams)(
+                        enc,
+                        holder as nv::NV_ENC_CUSTREAM_PTR,
+                        holder as nv::NV_ENC_CUSTREAM_PTR,
+                    )
+                    .nv_ok()
+                    {
+                        Ok(()) => {
+                            self.io_stream = holder;
+                            self.stream_ordered = true;
+                            tracing::info!(
+                                "NVENC stream-ordered submit armed (IO streams bound — no CPU \
+                                 sync in the submit path)"
+                            );
+                        }
+                        Err(e) => {
+                            drop(Box::from_raw(holder));
+                            tracing::debug!(
+                                status = ?e,
+                                "NvEncSetIOCudaStreams rejected — keeping blocking copies"
+                            );
+                        }
+                    }
+                }
+            }
             tracing::info!(
                 mode = %format_args!("{}x{}@{}", self.width, self.height, self.fps),
                 bit_depth = self.bit_depth,
@@ -980,8 +1137,10 @@ impl NvencCudaEncoder {
     }
 
     /// Copy the captured `DeviceBuffer` into the ring slot's registered input surface (device→device
-    /// on the shared context, synchronized by the copy helpers).
+    /// on the shared context). `sync` blocks until the copy completes (the pre-existing behavior);
-    fn copy_into_slot(&self, buf: &cuda::DeviceBuffer, slot: usize) -> Result<()> {
+    /// `!sync` enqueues on the encode thread's copy stream and leaves ordering to the session's
+    /// IO-stream binding (stream-ordered submit — see the gate in [`Encoder::submit`]).
+    fn copy_into_slot(&self, buf: &cuda::DeviceBuffer, slot: usize, sync: bool) -> Result<()> {
         let s = &self.ring[slot].surface;
         let base = s.ptr;
         let pitch = s.pitch;
@@ -996,16 +1155,16 @@ impl NvencCudaEncoder {
                     (base + pitch as u64 * hh, pitch),
                     (base + 2 * pitch as u64 * hh, pitch),
                 ];
-                cuda::copy_yuv444_to_device(buf, planes)
+                cuda::copy_yuv444_to_device(buf, planes, sync)
             }
             nv::NV_ENC_BUFFER_FORMAT::NV_ENC_BUFFER_FORMAT_NV12 => {
                 if !buf.is_nv12() {
                     bail!("NV12 session but the captured buffer has no chroma plane");
                 }
                 // Contiguous NV12: UV follows Y at base + pitch*height, same pitch.
-                cuda::copy_nv12_to_device(buf, base, pitch, base + pitch as u64 * hh, pitch)
+                cuda::copy_nv12_to_device(buf, base, pitch, base + pitch as u64 * hh, pitch, sync)
             }
-            _ => cuda::copy_device_to_device(buf, base, pitch),
+            _ => cuda::copy_device_to_device(buf, base, pitch, sync),
         }
     }
 
@@ -1052,6 +1211,9 @@ impl Encoder for NvencCudaEncoder {
                 "Linux direct-NVENC needs a CUDA frame (FramePayload::Cuda); got a CPU/dmabuf frame"
             ),
         };
+        // A pending pipelined-retrieve escalation engages here, at the submit-side safe point
+        // (nothing in flight after the previous poll drained).
+        self.maybe_engage_async();
         // Re-init on a size change (the capturer can return at a different resolution after a mode
         // switch). Format changes (NV12↔YUV444) likewise re-init.
         let new_fmt = buffer_format(buf);
@@ -1115,8 +1277,31 @@ impl Encoder for NvencCudaEncoder {
         let slot = self.next % POOL;
         self.next += 1;
 
+        // Sampled breakdown of the submit hot path under PUNKTFUNK_PERF (~1 line per 2 s at
+        // 60 fps, the VAAPI submit-split convention): copy = the per-frame device→device input
+        // copy (the zero-copy-registration target), blend = cursor overlay kernel (0 without a
+        // cursor), map/pic = the NVENC map_input_resource / encode_picture launches. The host
+        // loop's `submit_us` folds all four together; this is what splits them apart.
+        let sample = pf_host_config::config().perf && self.frames % 120 == 0;
+        self.frames += 1;
+
+        // Stream-ordered fast path (§7 LN2): enqueue the copy + blend with no CPU sync and let the
+        // IO-stream binding order `encode_picture` after them — but ONLY while nothing is in
+        // flight (true depth-1 usage). The gate is what makes this sound: with `pending` empty,
+        // every prior encode was drained by a blocking `poll`, so (a) the ring slot being reused
+        // was fully read, and (b) the caller still holds this frame's payload across the matching
+        // `poll` (both host loops do — see `Encoder::submit`'s doc), which blocks until the encode
+        // (and therefore the enqueued copy) completed. A pipelined caller (pending non-empty)
+        // falls back to the blocking copy so an early-recycled source can never be read late.
+        // `async_rt` must be absent too: in two-thread mode the frame may be recycled right after
+        // submit returns while the stream still holds its copy (belt-and-braces — an escalated
+        // session was rebuilt without the binding, so `stream_ordered` is false there anyway).
+        let ordered = self.stream_ordered && self.async_rt.is_none() && self.pending.is_empty();
+        let t0 = std::time::Instant::now();
+
         // Copy the captured buffer into this slot's input surface before encoding it.
-        self.copy_into_slot(buf, slot)?;
+        self.copy_into_slot(buf, slot, !ordered)?;
+        let t_copy = t0.elapsed();
 
         // Cursor-as-metadata: blend the overlay into this slot's OWNED input surface (a tiny kernel
         // over the cursor's rect — never the compositor's dmabuf). The PTX module loads lazily on the
@@ -1159,12 +1344,12 @@ impl Encoder for NvencCudaEncoder {
                 let (w, h) = (self.width, s.height);
                 let r = match self.buffer_fmt {
                     nv::NV_ENC_BUFFER_FORMAT::NV_ENC_BUFFER_FORMAT_YUV444 => {
-                        cb.blend_yuv444(s.ptr, s.pitch, w, h, ov.w, ov.h, ov.x, ov.y)
+                        cb.blend_yuv444(s.ptr, s.pitch, w, h, ov.w, ov.h, ov.x, ov.y, !ordered)
                     }
                     nv::NV_ENC_BUFFER_FORMAT::NV_ENC_BUFFER_FORMAT_NV12 => {
-                        cb.blend_nv12(s.ptr, s.pitch, w, h, ov.w, ov.h, ov.x, ov.y)
+                        cb.blend_nv12(s.ptr, s.pitch, w, h, ov.w, ov.h, ov.x, ov.y, !ordered)
                     }
-                    _ => cb.blend_argb(s.ptr, s.pitch, w, h, ov.w, ov.h, ov.x, ov.y),
+                    _ => cb.blend_argb(s.ptr, s.pitch, w, h, ov.w, ov.h, ov.x, ov.y, !ordered),
                 };
                 if let Err(e) = r {
                     if !self.cursor_blend_warned {
@@ -1180,6 +1365,9 @@ impl Encoder for NvencCudaEncoder {
             }
         }
 
+        let t_blend = t0.elapsed() - t_copy;
+        let t_map: std::time::Duration;
+        let t_pic: std::time::Duration;
         // SAFETY: every NVENC call goes through a function pointer from the runtime table and takes
         // `self.encoder`, the live session `init_session` established (non-null here). `mp`
         // (`NV_ENC_MAP_INPUT_RESOURCE`, version set) maps the ring slot's registration (created in
@@ -1187,8 +1375,11 @@ impl Encoder for NvencCudaEncoder {
         // `pic` (`NV_ENC_PIC_PARAMS`, version set) points `inputBuffer` at `mp.mappedResource` and
         // `outputBitstream` at the live pool bitstream `bitstreams[slot]`; the optional SEI scratch is
         // stack-local and outlives the synchronous `encode_picture`. The input surface for `slot` was
-        // just filled by the (synchronized) device→device copy and is not overwritten until this slot
+        // just filled by the device→device copy — either synchronized (blocking mode) or ordered
-        // is reused POOL submits later, by which time this encode was polled (POOL ≥ in-flight depth).
+        // before this encode by the session's IO-stream binding (`ordered` — same stream, see the
+        // gate above) — and is not overwritten until this slot is reused POOL submits later, by
+        // which time this encode was polled (POOL ≥ in-flight depth; in ordered mode the poll's
+        // blocking lock additionally proves the enqueued copy completed).
         unsafe {
             let reg = self.ring[slot].reg;
             let mut mp = nv::NV_ENC_MAP_INPUT_RESOURCE {
@@ -1196,9 +1387,11 @@ impl Encoder for NvencCudaEncoder {
                 registeredResource: reg,
                 ..Default::default()
             };
+            let tm = std::time::Instant::now();
             (api().map_input_resource)(self.encoder, &mut mp)
                 .nv_ok()
                 .map_err(|e| nvenc_status::call_err("map_input_resource", e))?;
+            t_map = tm.elapsed();
 
             let pts = self.frame_idx as u64;
             self.frame_idx += 1;
@@ -1268,9 +1461,11 @@ impl Encoder for NvencCudaEncoder {
                     }
                 }
             }
+            let tp = std::time::Instant::now();
             (api().encode_picture)(self.encoder, &mut pic)
                 .nv_ok()
                 .map_err(|e| nvenc_status::call_err("encode_picture", e))?;
+            t_pic = tp.elapsed();
             self.pending.push_back((
                 self.bitstreams[slot],
                 mp.mappedResource,
@@ -1278,6 +1473,16 @@ impl Encoder for NvencCudaEncoder {
                 anchor,
             ));
         }
+        if sample {
+            tracing::info!(
+                copy_us = t_copy.as_micros() as u64,
+                blend_us = t_blend.as_micros() as u64,
+                map_us = t_map.as_micros() as u64,
+                pic_us = t_pic.as_micros() as u64,
+                "NVENC submit split (sampled): copy=input D2D copy blend=cursor map=map_input \
+                 pic=encode_picture launch"
+            );
+        }
         // Two-thread mode: hand the blocking lock for this bitstream to the retrieve thread.
         // The sync_channel(POOL) can never fill (in-flight is capped < POOL above).
         if let Some(rt) = &self.async_rt {
@@ -1299,6 +1504,21 @@ impl Encoder for NvencCudaEncoder {
         self.force_kf = true;
     }
 
+    fn set_pipelined(&mut self, on: bool) -> bool {
+        if !on {
+            // v1 is escalate-and-hold (no de-escalation), mirroring the depth escalation.
+            return self.want_async || self.async_rt.is_some();
+        }
+        if async_retrieve_env() == Some(false) {
+            return false; // operator veto: PUNKTFUNK_NVENC_ASYNC=0 means NEVER
+        }
+        if !self.want_async && self.async_rt.is_none() {
+            self.want_async = true;
+            self.maybe_engage_async();
+        }
+        true
+    }
+
     fn caps(&self) -> EncoderCaps {
         EncoderCaps {
             supports_rfi: self.rfi_supported,
@@ -1892,4 +2112,220 @@ mod tests {
         assert!(got, "recovered encoder must produce an AU");
         println!("nvenc_cuda open-failure recovery: cap hit → diagnosed → recovered in place");
     }
+
+    /// ON-HARDWARE (RTX box `.21`): the stream-ordered submit (latency plan §7 LN2) must ARM on a
+    /// default-env session — `NvEncSetIOCudaStreams` accepted, boxed `CUstream` held. Guards
+    /// against a silent fallback to blocking copies: a rejected binding still encodes correctly,
+    /// just with the per-frame CPU syncs back, which no other test would notice.
+    #[test]
+    #[ignore = "requires an NVIDIA GPU + driver — run manually on the RTX box (.21)"]
+    fn nvenc_cuda_stream_ordered_arms() {
+        const W: u32 = 640;
+        const H: u32 = 360;
+        pf_zerocopy::cuda::make_current().expect("shared CUDA context current");
+        // Respect an explicit operator opt-out (or two-thread mode) rather than fail.
+        if !stream_ordered_requested() || async_retrieve_requested() {
+            println!("skipped: stream-ordered submit disabled by env");
+            return;
+        }
+        let mut enc = NvencCudaEncoder::open(
+            Codec::H265,
+            PixelFormat::Nv12,
+            W,
+            H,
+            60,
+            8_000_000,
+            true,
+            8,
+            ChromaFormat::Yuv420,
+        )
+        .expect("open NVENC CUDA session");
+        let frame = nv12_frame(W, H, 0);
+        enc.submit_indexed(&frame, 0).expect("submit");
+        let au = enc.poll().expect("poll").expect("AU");
+        assert!(au.keyframe, "opening AU must be the session IDR");
+        assert!(
+            enc.stream_ordered,
+            "IO-stream binding must arm on a default-env session (NvEncSetIOCudaStreams rejected?)"
+        );
+        assert!(
+            !enc.io_stream.is_null(),
+            "the boxed CUstream must be held while armed"
+        );
+    }
+
+    /// ON-HARDWARE (RTX box `.21`): the §7 LN3 pipelined-retrieve escalation —
+    /// `set_pipelined(true)` on a live sync session must rebuild it without the IO-stream
+    /// binding, spawn the retrieve thread on the re-open, and keep delivering AUs (the first
+    /// post-escalation AU is the re-open's session-opening IDR; pipelined `poll` is
+    /// non-blocking, so AUs may ride a later tick).
+    #[test]
+    #[ignore = "requires an NVIDIA GPU + driver — run manually on the RTX box (.21)"]
+    fn nvenc_cuda_pipelined_escalation() {
+        const W: u32 = 1280;
+        const H: u32 = 720;
+        pf_zerocopy::cuda::make_current().expect("shared CUDA context current");
+        if async_retrieve_env() == Some(false) {
+            println!("skipped: PUNKTFUNK_NVENC_ASYNC=0 vetoes the escalation");
+            return;
+        }
+        let mut enc = NvencCudaEncoder::open(
+            Codec::H265,
+            PixelFormat::Nv12,
+            W,
+            H,
+            60,
+            8_000_000,
+            true,
+            8,
+            ChromaFormat::Yuv420,
+        )
+        .expect("open NVENC CUDA session");
+        // Steady sync frames first (stream-ordered mode).
+        for i in 0..3u32 {
+            let frame = nv12_frame(W, H, i);
+            enc.submit_indexed(&frame, i).expect("submit");
+            enc.poll().expect("poll").expect("AU");
+        }
+        assert!(enc.async_rt.is_none(), "session starts sync");
+        assert!(enc.set_pipelined(true), "escalation must be accepted");
+        let mut aus = 0usize;
+        let mut first_key = false;
+        for i in 3..13u32 {
+            let frame = nv12_frame(W, H, i);
+            enc.submit_indexed(&frame, i)
+                .expect("submit post-escalation");
+            while let Some(au) = enc.poll().expect("poll") {
+                if aus == 0 {
+                    first_key = au.keyframe;
+                }
+                aus += 1;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(3));
+        }
+        // Drain the pipelined tail (bounded).
+        let deadline = std::time::Instant::now() + std::time::Duration::from_millis(500);
+        while aus < 10 && std::time::Instant::now() < deadline {
+            if enc.poll().expect("poll").is_some() {
+                aus += 1;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(1));
+        }
+        assert!(
+            enc.async_rt.is_some(),
+            "retrieve thread must be live after escalation"
+        );
+        assert!(
+            !enc.stream_ordered,
+            "IO-stream binding must be gone in pipelined mode"
+        );
+        assert_eq!(aus, 10, "every post-escalation frame must deliver an AU");
+        assert!(first_key, "first post-escalation AU is the re-open IDR");
+    }
+
+    /// ON-HARDWARE (RTX box `.21`), MEASUREMENT probe for latency plan §7 LN1 — answers the
+    /// go/no-go question for sub-frame slice output: with `PUNKTFUNK_NVENC_SLICES=4` +
+    /// `PUNKTFUNK_NVENC_SUBFRAME=1`, do slices become READABLE incrementally while the frame is
+    /// still encoding (and with what spacing), or does the driver only publish them at frame
+    /// completion? Spins `lock_bitstream(doNotWait)` against the in-flight bitstream and prints a
+    /// `(t_us, numSlices, bytes)` timeline. Asserts only the config half (4 slices materialize);
+    /// the timeline is the experiment's output — read it with `--nocapture`. Run single-threaded
+    /// (env vars are process-global): `-- --ignored --test-threads=1`.
+    #[test]
+    #[ignore = "requires an NVIDIA GPU + driver — run manually on the RTX box (.21)"]
+    fn nvenc_cuda_subframe_slice_probe() {
+        const W: u32 = 1920;
+        const H: u32 = 1080;
+        struct EnvGuard;
+        impl Drop for EnvGuard {
+            fn drop(&mut self) {
+                std::env::remove_var("PUNKTFUNK_NVENC_SLICES");
+                std::env::remove_var("PUNKTFUNK_NVENC_SUBFRAME");
+            }
+        }
+        std::env::set_var("PUNKTFUNK_NVENC_SLICES", "4");
+        std::env::set_var("PUNKTFUNK_NVENC_SUBFRAME", "1");
+        let _guard = EnvGuard;
+
+        pf_zerocopy::cuda::make_current().expect("shared CUDA context current");
+        let mut enc = NvencCudaEncoder::open(
+            Codec::H265,
+            PixelFormat::Nv12,
+            W,
+            H,
+            60,
+            20_000_000,
+            true,
+            8,
+            ChromaFormat::Yuv420,
+        )
+        .expect("open NVENC CUDA session");
+
+        // Frame 0 opens the session (IDR) — drain it normally.
+        let frame = nv12_frame(W, H, 0);
+        enc.submit_indexed(&frame, 0).expect("submit opening frame");
+        enc.poll().expect("poll").expect("opening AU");
+
+        // Frame 1: spin doNotWait locks against the in-flight bitstream BEFORE the blocking poll.
+        let frame = nv12_frame(W, H, 1);
+        enc.submit_indexed(&frame, 1).expect("submit probed frame");
+        let bs = enc.pending.back().expect("in-flight entry").0;
+        let t0 = std::time::Instant::now();
+        let mut timeline: Vec<(u64, nv::NVENCSTATUS, u32, u32)> = Vec::new();
+        let mut offsets = [0u32; 32];
+        loop {
+            let mut lock = nv::NV_ENC_LOCK_BITSTREAM {
+                version: nv::NV_ENC_LOCK_BITSTREAM_VER,
+                outputBitstream: bs,
+                sliceOffsets: offsets.as_mut_ptr(),
+                ..Default::default()
+            };
+            lock.set_doNotWait(1);
+            // SAFETY: `bs` is the pool bitstream the just-submitted `encode_picture` targets and
+            // the session is live for the whole test; `lock` (version set, doNotWait) and
+            // `offsets` are live stack locals across the synchronous call; a successful lock is
+            // unlocked before the next iteration reuses the struct. `reportSliceOffsets` was
+            // armed at init so `sliceOffsets` may be written up to `numSlices` ≤ 32 entries
+            // (sliceModeData = 4).
+            let (status, n, bytes) = unsafe {
+                let st = (api().lock_bitstream)(enc.encoder, &mut lock);
+                let ok = st == nv::NVENCSTATUS::NV_ENC_SUCCESS;
+                let (n, b) = if ok {
+                    (lock.numSlices, lock.bitstreamSizeInBytes)
+                } else {
+                    (0, 0)
+                };
+                if ok {
+                    let _ = (api().unlock_bitstream)(enc.encoder, bs);
+                }
+                (st, n, b)
+            };
+            let t_us = t0.elapsed().as_micros() as u64;
+            timeline.push((t_us, status, n, bytes));
+            // A successful doNotWait lock on a COMPLETE frame reports the final slice count; on
+            // LOCK_BUSY the frame is still encoding. Stop once complete (all 4 slices) or after
+            // a generous 50 ms safety window.
+            if (status == nv::NVENCSTATUS::NV_ENC_SUCCESS && n >= 4) || t_us > 50_000 {
+                break;
+            }
+            std::thread::sleep(std::time::Duration::from_micros(50));
+        }
+        println!("subframe probe timeline (t_us, status, numSlices, bytes):");
+        for (t, st, n, b) in &timeline {
+            println!("  {t:>7} us  {st:?}  slices={n}  bytes={b}");
+        }
+        // Drain the probed frame through the normal path (lock again + unmap) — proves the probe
+        // locks didn't corrupt the session.
+        let au = enc.poll().expect("poll probed frame").expect("probed AU");
+        assert!(!au.data.is_empty(), "probed AU must carry data");
+        let last = timeline.last().expect("at least one sample");
+        assert_eq!(
+            last.2, 4,
+            "4 slices must materialize (PUNKTFUNK_NVENC_SLICES=4 + subframe readback armed)"
+        );
+        // One more frame end-to-end for session health.
+        let frame = nv12_frame(W, H, 2);
+        enc.submit_indexed(&frame, 2).expect("submit follow-up");
+        enc.poll().expect("poll").expect("follow-up AU");
+    }
 }

crates/pf-encode/src/enc/linux/pyrowave.rs

@@ -1176,7 +1176,24 @@ impl Encoder for PyroWaveEncoder {
     fn submit(&mut self, frame: &CapturedFrame) -> Result<()> {
         // SAFETY: single-threaded encoder; `encode_frame` records/submits on handles this
         // struct owns and waits its own fence before touching results.
-        unsafe { self.encode_frame(frame) }
+        let r = unsafe { self.encode_frame(frame) };
+        if r.is_err() {
+            // `encode_frame` opens the recording window early and has several fallible steps
+            // inside it (cursor prep, dmabuf import, format mapping, the CPU-RGB staging path,
+            // an unsupported-payload bail, and the encode call itself). Every one returns with
+            // `self.cmd` still RECORDING, and nothing downstream repairs it — there is exactly
+            // one `begin_command_buffer` in this file and `reset()`/`Drop` never touch `cmd` —
+            // so the NEXT frame would call `begin` on a recording buffer, which is invalid usage.
+            // Legal here on every path: the pool carries RESET_COMMAND_BUFFER and the buffer is
+            // not pending (we never reached the submit, or the submit itself failed).
+            // SAFETY: `self.cmd` is owned by this encoder and, on these paths, not in flight.
+            unsafe {
+                let _ = self
+                    .device
+                    .reset_command_buffer(self.cmd, vk::CommandBufferResetFlags::empty());
+            }
+        }
+        r
     }
 
     fn caps(&self) -> EncoderCaps {

crates/pf-encode/src/enc/linux/vk_util.rs

@@ -77,6 +77,32 @@ pub(crate) unsafe fn import_rgb_dmabuf(
     d: &pf_frame::DmabufFrame,
     cw: u32,
     ch: u32,
+) -> Result<(vk::Image, vk::DeviceMemory, vk::ImageView)> {
+    import_rgb_dmabuf_as(
+        device,
+        ext_fd,
+        mem_props,
+        d,
+        cw,
+        ch,
+        vk::ImageUsageFlags::SAMPLED,
+        None,
+    )
+}
+
+/// [`import_rgb_dmabuf`] with the image usage explicit and an optional video-profile list
+/// (chained into the image create) — the RGB-direct encode path imports the captured buffer
+/// as a profiled `VIDEO_ENCODE_SRC` image instead of a sampled one.
+#[allow(clippy::too_many_arguments)]
+pub(crate) unsafe fn import_rgb_dmabuf_as(
+    device: &ash::Device,
+    ext_fd: &ash::khr::external_memory_fd::Device,
+    mem_props: &vk::PhysicalDeviceMemoryProperties,
+    d: &pf_frame::DmabufFrame,
+    cw: u32,
+    ch: u32,
+    usage: vk::ImageUsageFlags,
+    profile_list: Option<&mut vk::VideoProfileListInfoKHR>,
 ) -> Result<(vk::Image, vk::DeviceMemory, vk::ImageView)> {
     use anyhow::Context;
     use std::os::fd::IntoRawFd;
@@ -90,8 +116,7 @@ pub(crate) unsafe fn import_rgb_dmabuf(
         .plane_layouts(&plane);
     let mut ext = vk::ExternalMemoryImageCreateInfo::default()
         .handle_types(vk::ExternalMemoryHandleTypeFlags::DMA_BUF_EXT);
-    let img = device.create_image(
+    let mut ci = vk::ImageCreateInfo::default()
-        &vk::ImageCreateInfo::default()
         .image_type(vk::ImageType::TYPE_2D)
         .format(fmt)
         .extent(vk::Extent3D {
@@ -103,13 +128,15 @@ pub(crate) unsafe fn import_rgb_dmabuf(
         .array_layers(1)
         .samples(vk::SampleCountFlags::TYPE_1)
         .tiling(vk::ImageTiling::DRM_FORMAT_MODIFIER_EXT)
-            .usage(vk::ImageUsageFlags::SAMPLED)
+        .usage(usage)
         .sharing_mode(vk::SharingMode::EXCLUSIVE)
         .initial_layout(vk::ImageLayout::UNDEFINED)
         .push_next(&mut ext)
-            .push_next(&mut drm),
+        .push_next(&mut drm);
-        None,
+    if let Some(pl) = profile_list {
-    )?;
+        ci = ci.push_next(pl);
+    }
+    let img = device.create_image(&ci, None)?;
     // dup the fd; Vulkan takes ownership of the dup on a successful import.
     let dup = d.fd.try_clone().context("dup dmabuf fd")?.into_raw_fd();
     let fd_props = {
@@ -183,7 +210,8 @@ pub(crate) unsafe fn make_plain_image(
         None,
     )?;
     let req = device.get_image_memory_requirements(img);
-    let mem = device.allocate_memory(
+    // Unwind on failure: callers (the encoders' open paths) only ever see the completed triple.
+    let mem = match device.allocate_memory(
         &vk::MemoryAllocateInfo::default()
             .allocation_size(req.size)
             .memory_type_index(find_mem(
@@ -192,8 +220,24 @@ pub(crate) unsafe fn make_plain_image(
                 vk::MemoryPropertyFlags::DEVICE_LOCAL,
             )),
         None,
-    )?;
+    ) {
-    device.bind_image_memory(img, mem, 0)?;
+        Ok(m) => m,
-    let view = make_view(device, img, fmt, 0)?;
+        Err(e) => {
-    Ok((img, mem, view))
+            device.destroy_image(img, None);
+            return Err(e.into());
+        }
+    };
+    if let Err(e) = device.bind_image_memory(img, mem, 0) {
+        device.destroy_image(img, None);
+        device.free_memory(mem, None);
+        return Err(e.into());
+    }
+    match make_view(device, img, fmt, 0) {
+        Ok(view) => Ok((img, mem, view)),
+        Err(e) => {
+            device.destroy_image(img, None);
+            device.free_memory(mem, None);
+            Err(e)
+        }
+    }
 }

crates/pf-encode/src/enc/linux/vk_valve_rgb.rs

@@ -0,0 +1,82 @@
+//! Vendored `VK_VALVE_video_encode_rgb_conversion` bindings — the RGB→YCbCr encode-source
+//! extension (Vulkan 1.4.327; RADV since Mesa 26.0, hardware-gated on the VCN EFC front-end
+//! conversion block). Our pinned `ash 0.38.0+1.3.281` predates it entirely; same vendoring
+//! rationale as [`vk_av1_encode`](super::vk_av1_encode) — definitions copied from the registry
+//! so the layouts are correct-by-construction, chained via raw `p_next`. Consumed by
+//! `vulkan_video.rs`: B0 probes + logs availability (design/vulkan-rgb-direct-encode.md);
+//! B1 makes the captured BGRx dmabuf the direct encode source with EFC doing the 709-narrow CSC.
+#![allow(dead_code)]
+
+use ash::vk;
+use std::ffi::{c_void, CStr};
+
+pub const EXTENSION_NAME: &CStr = c"VK_VALVE_video_encode_rgb_conversion";
+
+// ---------- struct-type (VkStructureType) values — construct via `stype` ----------
+pub const ST_PHYSICAL_DEVICE_FEATURES: i32 = 1_000_390_000;
+pub const ST_CAPABILITIES: i32 = 1_000_390_001;
+pub const ST_PROFILE_INFO: i32 = 1_000_390_002;
+pub const ST_SESSION_CREATE_INFO: i32 = 1_000_390_003;
+
+// `VkVideoEncodeRgbModelConversionFlagBitsVALVE`
+pub const MODEL_RGB_IDENTITY: u32 = 0x01;
+pub const MODEL_YCBCR_IDENTITY: u32 = 0x02;
+pub const MODEL_YCBCR_709: u32 = 0x04;
+pub const MODEL_YCBCR_601: u32 = 0x08;
+pub const MODEL_YCBCR_2020: u32 = 0x10;
+// `VkVideoEncodeRgbRangeCompressionFlagBitsVALVE`
+pub const RANGE_FULL: u32 = 0x01;
+pub const RANGE_NARROW: u32 = 0x02;
+// `VkVideoEncodeRgbChromaOffsetFlagBitsVALVE`
+pub const CHROMA_OFFSET_COSITED_EVEN: u32 = 0x01;
+pub const CHROMA_OFFSET_MIDPOINT: u32 = 0x02;
+
+/// `VkPhysicalDeviceVideoEncodeRgbConversionFeaturesVALVE` — chain into
+/// `VkPhysicalDeviceFeatures2` (query) / `VkDeviceCreateInfo` (enable).
+#[repr(C)]
+pub struct PhysicalDeviceVideoEncodeRgbConversionFeaturesVALVE {
+    pub s_type: vk::StructureType,
+    pub p_next: *mut c_void,
+    pub video_encode_rgb_conversion: vk::Bool32,
+}
+
+/// `VkVideoEncodeRgbConversionCapabilitiesVALVE` — chain into the
+/// `vkGetPhysicalDeviceVideoCapabilitiesKHR` output when the queried profile carries
+/// [`VideoEncodeProfileRgbConversionInfoVALVE`]; reports which conversions the HW does.
+#[repr(C)]
+pub struct VideoEncodeRgbConversionCapabilitiesVALVE {
+    pub s_type: vk::StructureType,
+    pub p_next: *mut c_void,
+    pub rgb_models: u32,
+    pub rgb_ranges: u32,
+    pub x_chroma_offsets: u32,
+    pub y_chroma_offsets: u32,
+}
+
+/// `VkVideoEncodeProfileRgbConversionInfoVALVE` — part of the video-profile *identity*: every
+/// consumer of the profile (caps query, format query, session, image profile lists) must carry
+/// the same chain.
+#[repr(C)]
+pub struct VideoEncodeProfileRgbConversionInfoVALVE {
+    pub s_type: vk::StructureType,
+    pub p_next: *const c_void,
+    pub perform_encode_rgb_conversion: vk::Bool32,
+}
+
+/// `VkVideoEncodeSessionRgbConversionCreateInfoVALVE` — chain into
+/// `VkVideoSessionCreateInfoKHR`; single-bit selections of the conversion actually performed.
+#[repr(C)]
+pub struct VideoEncodeSessionRgbConversionCreateInfoVALVE {
+    pub s_type: vk::StructureType,
+    pub p_next: *const c_void,
+    pub rgb_model: u32,
+    pub rgb_range: u32,
+    pub x_chroma_offset: u32,
+    pub y_chroma_offset: u32,
+}
+
+/// `vk::StructureType` for a raw `ST_*` constant above.
+#[inline]
+pub fn stype(raw: i32) -> vk::StructureType {
+    vk::StructureType::from_raw(raw)
+}

crates/pf-encode/src/enc/nvenc_core.rs

@@ -101,6 +101,15 @@ pub(super) fn build_init_params(
     };
     // splitEncodeMode is a C bitfield — set via the generated accessor, not a struct field.
     init.set_splitEncodeMode(split_mode);
+    // Sub-frame readback (latency plan §7 LN1 groundwork — EXPERIMENTAL, default off): the driver
+    // writes each slice into the output buffer as it completes and reports per-slice offsets, so a
+    // sync-mode consumer can read slices out while the frame is still encoding. Pair with
+    // `PUNKTFUNK_NVENC_SLICES` (a single-slice frame yields nothing to read early).
+    // `reportSliceOffsets` requires `enableEncodeAsync = 0`, so async (Windows) sessions never arm.
+    if !enable_async && std::env::var("PUNKTFUNK_NVENC_SUBFRAME").as_deref() == Ok("1") {
+        init.set_enableSubFrameWrite(1);
+        init.set_reportSliceOffsets(1);
+    }
     init
 }
 
@@ -118,6 +127,9 @@ pub(super) unsafe fn apply_low_latency_config(cfg: &mut nv::NV_ENC_CONFIG, c: Lo
     cfg.gopLength = nv::NVENC_INFINITE_GOPLENGTH;
     cfg.frameIntervalP = 1;
     cfg.rcParams.rateControlMode = nv::NV_ENC_PARAMS_RC_MODE::NV_ENC_PARAMS_RC_CBR;
+    // Explicit zero reorder delay: with P-only + no lookahead there is no reordering to buffer,
+    // but pin the bit so no preset/driver default can ever slip a frame of reorder delay in.
+    cfg.rcParams.set_zeroReorderDelay(1);
     let bps = c.bitrate.min(u32::MAX as u64) as u32;
     cfg.rcParams.averageBitRate = bps;
     cfg.rcParams.maxBitRate = bps;
@@ -146,6 +158,29 @@ pub(super) unsafe fn apply_low_latency_config(cfg: &mut nv::NV_ENC_CONFIG, c: Lo
         Codec::PyroWave => unreachable!("PyroWave never opens the direct-NVENC backend"),
     }
 
+    // Multi-slice frames (latency plan §7 LN1 groundwork — EXPERIMENTAL, default off = the preset's
+    // single slice): `PUNKTFUNK_NVENC_SLICES=N` (2..=32) splits every frame into N slices
+    // (sliceMode 3 = "N slices per frame"), the unit sub-frame readback ships early and loss
+    // concealment can discard independently. Costs ~1-2 % bitrate in slice headers. H.264/HEVC
+    // only — AV1 partitions via tiles, not slices.
+    if let Some(n) = std::env::var("PUNKTFUNK_NVENC_SLICES")
+        .ok()
+        .and_then(|s| s.parse::<u32>().ok())
+        .filter(|n| (2..=32).contains(n))
+    {
+        match c.codec {
+            Codec::H264 => {
+                cfg.encodeCodecConfig.h264Config.sliceMode = 3;
+                cfg.encodeCodecConfig.h264Config.sliceModeData = n;
+            }
+            Codec::H265 => {
+                cfg.encodeCodecConfig.hevcConfig.sliceMode = 3;
+                cfg.encodeCodecConfig.hevcConfig.sliceModeData = n;
+            }
+            Codec::Av1 | Codec::PyroWave => {}
+        }
+    }
+
     // Chroma + bit depth. Full-chroma 4:4:4 (HEVC Range Extensions, chromaFormatIDC=3 under the FREXT
     // profile) takes precedence and composes with 10-bit (Main 4:4:4 10); it needs a full-chroma-
     // capable input. Otherwise 10-bit selects Main10 (HEVC) or the AV1 output depth — stamping the

crates/pf-encode/src/enc/windows/nvenc.rs

@@ -409,6 +409,12 @@ pub struct NvencD3d11Encoder {
     events: Vec<usize>,
     /// Async mode: the retrieve thread + its channels (`None` = classic same-thread sync retrieve).
     async_rt: Option<AsyncRetrieve>,
+    /// The capturer's `pipeline_depth` (`set_input_ring_depth`). This backend encodes the
+    /// capturer's textures IN PLACE, so it is a HARD ceiling on async in-flight depth: the
+    /// capturer rotates its ring per delivered frame regardless of encode completion, so
+    /// pipelining deeper lets it overwrite a texture mid-encode (torn frames). `None` until the
+    /// session glue reports it — treated as "unknown, don't pipeline past the env cap".
+    input_ring_depth: Option<usize>,
     /// `NV_ENC_CAPS_ASYNC_ENCODE_SUPPORT` from the caps probe — gates the async retrieve mode.
     async_supported: bool,
     /// (bitstream, mapped input resource to unmap after retrieval, pts_ns, recovery-anchor) per
@@ -505,6 +511,7 @@ impl NvencD3d11Encoder {
             bitstreams: Vec::new(),
             events: Vec::new(),
             async_rt: None,
+            input_ring_depth: None,
             async_supported: false,
             pending: VecDeque::new(),
             frame_idx: 0,
@@ -1156,11 +1163,21 @@ impl Encoder for NvencD3d11Encoder {
         // index, which is non-zero on a mid-session encoder rebuild's first frame.
         let opening = self.next == 0;
         // Async backpressure: never hand NVENC an output bitstream that is still in flight, and
-        // keep in-flight depth within the capturer's texture ring (see `async_inflight_cap`). At
+        // keep in-flight depth within the capturer's texture ring. At the cap, block on the OLDEST
-        // the cap, block on the OLDEST completion (the retrieve thread is already waiting on its
+        // completion (the retrieve thread is already waiting on its event) before submitting more —
-        // event) before submitting more — bounding depth exactly like the sync path's per-tick
+        // bounding depth exactly like the sync path's per-tick blocking poll, just `cap` deep
-        // blocking poll, just `cap` deep instead of 1.
+        // instead of 1.
-        while self.async_rt.is_some() && self.pending.len() >= async_inflight_cap() {
+        //
+        // The ring term is the one that matters for correctness: `async_inflight_cap()` is only the
+        // output-bitstream-pool ceiling plus an env knob, and consults NOTHING about the capturer,
+        // despite this comment previously claiming otherwise. Since this backend encodes the
+        // capturer's textures in place, exceeding the capturer's declared `pipeline_depth` lets it
+        // rotate a texture out from under a live encode — torn frames, silently.
+        let cap = match self.input_ring_depth {
+            Some(d) => async_inflight_cap().min(d.max(1)),
+            None => async_inflight_cap(),
+        };
+        while self.async_rt.is_some() && self.pending.len() >= cap {
             let done = {
                 let rt = self.async_rt.as_mut().expect("checked in loop condition");
                 rt.done_rx
@@ -1336,6 +1353,17 @@ impl Encoder for NvencD3d11Encoder {
         self.submit(frame)
     }
 
+    fn set_input_ring_depth(&mut self, depth: usize) {
+        // This backend registers and encodes the capturer's textures in place (no CopyResource),
+        // so the capturer's ring depth is a hard ceiling on how deep async may pipeline.
+        self.input_ring_depth = Some(depth);
+        tracing::debug!(
+            depth,
+            env_cap = async_inflight_cap(),
+            "NVENC: capturer input-ring depth reported — async in-flight bounded by the smaller"
+        );
+    }
+
     fn request_keyframe(&mut self) {
         self.force_kf = true;
     }

crates/pf-encode/src/enc/windows/pyrowave.rs

@@ -43,6 +43,9 @@ const BS_SLACK: usize = 256 * 1024;
 /// (a desktop-switch device recreate), in which case the stale imports are evicted + destroyed.
 const IMPORT_CACHE_CAP: usize = 8;
 
+/// Plane-import cache key: the texture's COM address plus the extent it was imported at.
+type PlaneKey = (isize, u32, u32);
+
 // --- Vulkan enum values not surfaced by pyrowave-sys' bindgen (only enums *reachable* from the
 // pyrowave C API are generated; these plain #define / flags-typedef values are stable spec
 // constants). bindgen renders every reachable Vulkan enum as a `u32` type alias, so these u32
@@ -136,8 +139,12 @@ pub struct PyroWaveEncoder {
     // Imported plane textures, cached by the out-ring texture's raw pointer (stable per ring slot):
     // the full-res R8 Y plane and the half-res R8G8 CbCr plane, imported SEPARATELY (a single planar
     // NV12 import is unreliable on NVIDIA at arbitrary sizes).
-    y_images: Vec<(isize, pw::pyrowave_image)>,
+    /// The capturer ring generation the cached plane imports below belong to. A recreate bumps it,
-    cbcr_images: Vec<(isize, pw::pyrowave_image)>,
+    /// and every cached import is destroyed — the COM addresses they are keyed on can be recycled
+    /// by the allocator after a recreate, so identity cannot rest on the pointer alone.
+    ring_gen: Option<u32>,
+    y_images: Vec<(PlaneKey, pw::pyrowave_image)>,
+    cbcr_images: Vec<(PlaneKey, pw::pyrowave_image)>,
 
     width: u32,
     height: u32,
@@ -268,6 +275,7 @@ impl PyroWaveEncoder {
                 pw_dev,
                 pw_enc,
                 sync: std::ptr::null_mut(),
+                ring_gen: None,
                 y_images: Vec::new(),
                 cbcr_images: Vec::new(),
                 width,
@@ -351,10 +359,16 @@ impl PyroWaveEncoder {
     ///
     /// # Safety
     /// Same contract as [`import_plane`].
+    /// Keyed on `(texture address, width, height)` rather than the bare address: the COM pointer
+    /// carries no reference here, so a released texture's address can be recycled by a later
+    /// allocation and return an import describing the WRONG surface. Folding the extent in means a
+    /// recycled address at a different size can never alias. (A recycle at the SAME size is still
+    /// possible in principle — the complete fix is to key on the capturer's ring generation, which
+    /// needs that generation plumbed onto `PyroFrameShare`.)
     unsafe fn cached_plane(
-        cache: &mut Vec<(isize, pw::pyrowave_image)>,
+        cache: &mut Vec<(PlaneKey, pw::pyrowave_image)>,
         make: impl FnOnce() -> Result<pw::pyrowave_image>,
-        key: isize,
+        key: PlaneKey,
     ) -> Result<pw::pyrowave_image> {
         if let Some((_, img)) = cache.iter().find(|(k, _)| *k == key) {
             return Ok(*img);
@@ -423,6 +437,21 @@ impl PyroWaveEncoder {
             !self.pw_enc.is_null(),
             "pyrowave: encode after a failed reset (encoder was destroyed and not rebuilt)"
         );
+        // The plane textures are imported at the encoder's CONFIGURED extent, not the frame's, so a
+        // capture that changed size would be read under a stale `VkImageCreateInfo`. This is
+        // reachable without any client Reconfigure: the IDD capturer autonomously recreates its ring
+        // on a confirmed display-descriptor change (e.g. a fullscreen game mode-setting the virtual
+        // display). Refuse instead — the session must reopen the encoder at the new mode. Mirrors
+        // the guard the QSV and AMF backends already carry.
+        anyhow::ensure!(
+            frame.width == self.width && frame.height == self.height,
+            "pyrowave: captured frame {}x{} != encoder {}x{} (the capturer recreated its ring at a \
+             new mode — the encoder must be reopened)",
+            frame.width,
+            frame.height,
+            self.width,
+            self.height
+        );
         let FramePayload::D3d11(d3d) = &frame.payload else {
             bail!("pyrowave (Windows) needs a D3D11 frame (the capturer must be in pyrowave mode)")
         };
@@ -431,6 +460,25 @@ impl PyroWaveEncoder {
              in pyrowave mode (session_plan::output_format must set OutputFormat::pyrowave)",
         )?;
 
+        // Ring recreate ⇒ every cached plane import belongs to textures that no longer exist. Their
+        // COM addresses can be handed back out by the allocator, so a pointer-keyed hit could return
+        // an image bound to freed memory. Flush on the generation change rather than relying on the
+        // address (or the FIFO cap) to notice.
+        if self.ring_gen != Some(share.ring_gen) {
+            if self.ring_gen.is_some() {
+                tracing::info!(
+                    from = ?self.ring_gen,
+                    to = share.ring_gen,
+                    cached = self.y_images.len() + self.cbcr_images.len(),
+                    "pyrowave: capturer recreated its ring — flushing stale plane imports"
+                );
+            }
+            for (_, img) in self.y_images.drain(..).chain(self.cbcr_images.drain(..)) {
+                pw::pyrowave_image_destroy(img);
+            }
+            self.ring_gen = Some(share.ring_gen);
+        }
+
         // Import the fence whenever this encoder has no timeline yet — the first frame, OR a fresh
         // encoder after a client mode-switch rebuild (the capturer passes the persistent handle on
         // every frame precisely so a rebuilt encoder can re-import it).
@@ -465,7 +513,7 @@ impl PyroWaveEncoder {
         };
         let pw_dev = self.pw_dev;
         let y_img = {
-            let key = d3d.texture.as_raw() as isize;
+            let key = (d3d.texture.as_raw() as isize, w, h);
             let tex = &d3d.texture;
             Self::cached_plane(
                 &mut self.y_images,
@@ -474,7 +522,7 @@ impl PyroWaveEncoder {
             )?
         };
         let cbcr_img = {
-            let key = share.cbcr.as_raw() as isize;
+            let key = (share.cbcr.as_raw() as isize, cw, ch);
             let tex = &share.cbcr;
             Self::cached_plane(
                 &mut self.cbcr_images,
@@ -976,6 +1024,9 @@ mod tests {
                     cbcr: cbcr_tex,
                     fence_handle: Some(fence_handle.0 as isize),
                     fence_value: 1,
+                    // One synthetic ring for the whole case: a constant generation exercises the
+                    // steady-state cache-hit path (a changing one would flush every frame).
+                    ring_gen: 1,
                 }),
             }),
             cursor: None,

crates/pf-encode/src/enc/windows/qsv.rs

@@ -714,7 +714,16 @@ pub struct QsvEncoder {
     /// `EncoderCaps::supports_rfi` and all per-frame marking/forcing below.
     ltr_active: bool,
     /// The wire frame index stored in each LTR slot (`None` = never marked).
+    ///
+    /// This mirrors the HARDWARE DPB, so an entry must not be cleared merely because we distrust
+    /// it: nulling issues no VPL call, and the encoder keeps the frame marked long-term until that
+    /// `LongTermIdx` is re-marked or an IDR flushes it. Distrust is recorded in `ltr_tainted`
+    /// instead, so the rejection list can still NAME the entry the hardware is holding.
     ltr_slots: [Option<i64>; NUM_LTR_SLOTS],
+    /// Per-slot taint from `invalidate_ref_frames`' sweep: the mark is still live in the hardware
+    /// DPB but was encoded inside the client's corrupt window, so it may not anchor a recovery —
+    /// it must be REJECTED instead. Cleared wherever the slot is re-marked or the DPB is flushed.
+    ltr_tainted: [bool; NUM_LTR_SLOTS],
     next_ltr_slot: usize,
     ltr_mark_interval: i64,
     /// Set by `invalidate_ref_frames`: the slot the next submitted frame force-references.
@@ -789,6 +798,7 @@ impl QsvEncoder {
             ir_active: false,
             ltr_active: false,
             ltr_slots: [None; NUM_LTR_SLOTS],
+            ltr_tainted: [false; NUM_LTR_SLOTS],
             next_ltr_slot: 0,
             ltr_mark_interval: ltr_mark_interval(fps),
             pending_force: None,
@@ -913,6 +923,7 @@ impl QsvEncoder {
         self.ltr_active = ltr_active;
         self.ir_active = ir_active;
         self.ltr_slots = [None; NUM_LTR_SLOTS];
+        self.ltr_tainted = [false; NUM_LTR_SLOTS];
         self.next_ltr_slot = 0;
         self.pending_force = None;
         self.hdr_applied = self.hdr_meta;
@@ -1038,6 +1049,7 @@ impl Encoder for QsvEncoder {
                 // An IDR voids the decoder's reference buffers — drop stale slots and any
                 // queued force; the mark cadence below re-anchors on the IDR itself.
                 self.ltr_slots = [None; NUM_LTR_SLOTS];
+                self.ltr_tainted = [false; NUM_LTR_SLOTS]; // the IDR flushed the DPB with them
                 self.next_ltr_slot = 0;
                 self.pending_force = None;
             } else if self.ltr_test_force_at == Some(cur_idx) {
@@ -1053,7 +1065,9 @@ impl Encoder for QsvEncoder {
                 // emptied the slot since the force was queued. An empty slot means there is
                 // nothing clean to re-reference — the frame must ship as a plain P WITHOUT the
                 // `recovery_anchor` tag (the client lifts its post-loss freeze on that tag).
-                if let Some(idx) = self.ltr_slots[slot] {
+                // The slot is no longer emptied by the sweep, so test the taint flag too — a
+                // tainted slot is exactly the "nothing clean to re-reference" case.
+                if let Some(idx) = self.ltr_slots[slot].filter(|_| !self.ltr_tainted[slot]) {
                     force_ltr = Some((slot, idx));
                     recovery_anchor = true;
                 }
@@ -1061,6 +1075,9 @@ impl Encoder for QsvEncoder {
             if force_ltr.is_none() && (forced || cur_idx % self.ltr_mark_interval == 0) {
                 let slot = self.next_ltr_slot;
                 self.ltr_slots[slot] = Some(cur_idx);
+                // Re-marking replaces the hardware's LongTermIdx: the tainted frame is gone from
+                // the DPB and this slot is clean again.
+                self.ltr_tainted[slot] = false;
                 self.next_ltr_slot = (self.next_ltr_slot + 1) % NUM_LTR_SLOTS;
                 mark_slot = Some(slot);
             }
@@ -1323,13 +1340,23 @@ impl Encoder for QsvEncoder {
         // loss ships corruption as the recovery anchor, and every subsequent mark re-samples
         // the soup — the sustained-loss field failure where the picture never healed. Dropped
         // slots stay dropped; the cadence re-marks a clean frame within ~1/4 s.
-        for marked in self.ltr_slots.iter_mut() {
+        //
+        // Mark tainted rather than clearing: `ltr_slots` mirrors the HARDWARE DPB, and nulling an
+        // entry issues no VPL call — the frame stays marked long-term in the encoder. Clearing it
+        // made the rejection list below (which iterates the post-sweep mirror and only names `Some`
+        // slots) silently SKIP the one entry the sweep exists to distrust, so the recovery frame
+        // could still predict from it. With two slots the "exactly one swept" case is the modal
+        // one, and it was the broken one.
+        for (slot, marked) in self.ltr_slots.iter().enumerate() {
             if marked.is_some_and(|idx| idx >= first) {
-                *marked = None;
+                self.ltr_tainted[slot] = true;
             }
         }
         let mut best: Option<(usize, i64)> = None;
         for (slot, marked) in self.ltr_slots.iter().enumerate() {
+            if self.ltr_tainted[slot] {
+                continue; // still in the DPB, but encoded inside the corrupt window
+            }
             if let Some(idx) = *marked {
                 if idx < first && best.is_none_or(|(_, b)| idx > b) {
                     best = Some((slot, idx));
@@ -1454,6 +1481,7 @@ impl Encoder for QsvEncoder {
                 self.ltr_active = ltr;
                 self.ir_active = ir;
                 self.ltr_slots = [None; NUM_LTR_SLOTS];
+                self.ltr_tainted = [false; NUM_LTR_SLOTS];
                 self.next_ltr_slot = 0;
                 self.pending_force = None;
                 if let Some(inner) = self.inner.as_mut() {

crates/pf-encode/src/lib.rs

@@ -209,6 +209,11 @@ impl Encoder for TrackedEncoder {
     fn set_wire_chunking(&mut self, shard_payload: usize) {
         self.inner.set_wire_chunking(shard_payload)
     }
+    // Forwarded for the same reason as `set_wire_chunking` above — an unforwarded default here
+    // would silently leave the in-place backends pipelining past the capturer's ring.
+    fn set_input_ring_depth(&mut self, depth: usize) {
+        self.inner.set_input_ring_depth(depth)
+    }
     fn poll(&mut self) -> Result<Option<EncodedFrame>> {
         self.inner.poll()
     }
@@ -1338,6 +1343,12 @@ mod vulkan_video;
 #[cfg(all(target_os = "linux", feature = "vulkan-encode"))]
 #[path = "enc/linux/vk_av1_encode.rs"]
 mod vk_av1_encode;
+// Vendored `VK_VALVE_video_encode_rgb_conversion` bindings (host-only) — RGB encode source with
+// the VCN EFC front-end doing the CSC (design/vulkan-rgb-direct-encode.md). ash 0.38 predates
+// the extension; same vendoring rationale as `vk_av1_encode`.
+#[cfg(all(target_os = "linux", feature = "vulkan-encode"))]
+#[path = "enc/linux/vk_valve_rgb.rs"]
+mod vk_valve_rgb;
 // Small ash leaf helpers shared by the Linux Vulkan encode backends (dmabuf import, image/memory
 // utilities) — extracted from `vulkan_video.rs` when the PyroWave backend arrived.
 #[cfg(all(

crates/pf-frame/src/dxgi.rs

@@ -52,6 +52,12 @@ pub struct PyroFrameShare {
     /// The fence value the capturer signalled after THIS frame's convert. The encoder's Vulkan
     /// acquire waits on it, so the wavelet read is ordered after the D3D11 CSC.
     pub fence_value: u64,
+    /// The capturer's ring generation, bumped every time it recreates its texture ring. The
+    /// PyroWave encoder caches its plane imports keyed on the texture's COM address, which carries
+    /// no reference — after a recreate those addresses can be recycled by the allocator, so a
+    /// cached import may describe a texture that no longer exists. The encoder flushes its import
+    /// cache whenever this changes, making cache identity independent of allocator behaviour.
+    pub ring_gen: u32,
 }
 
 /// A GPU-resident captured texture (the Windows zero-copy path: NVENC/AMF/QSV encode it in place;

crates/pf-inject/src/inject/linux/steam_gadget.rs

@@ -17,7 +17,7 @@
 use anyhow::{bail, Context, Result};
 use std::mem::size_of;
 use std::os::fd::RawFd;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread::JoinHandle;
 
@@ -196,6 +196,45 @@ impl Drop for GadgetFd {
     }
 }
 
+/// The signal used to break a worker thread out of a blocking raw_gadget ioctl at teardown.
+/// `EVENT_FETCH`/`EP_WRITE` are `wait_event_interruptible` in the kernel with no timeout and no
+/// `O_NONBLOCK` honouring, and closing the fd cannot wake a thread already inside the ioctl (the
+/// in-flight syscall holds a reference to the struct file). A signal is the only reliable lever:
+/// delivered with a no-op, non-`SA_RESTART` handler it forces the ioctl to return `EINTR`, after
+/// which the loop's top-of-iteration `running` check exits. `SIGUSR1` is unused elsewhere in this
+/// process; the handler is a no-op, so a stray `SIGUSR1` becomes harmless rather than fatal.
+const WAKE_SIGNAL: libc::c_int = libc::SIGUSR1;
+
+/// Install the no-op `WAKE_SIGNAL` handler exactly once. Crucially `sa_flags = 0` (no `SA_RESTART`)
+/// so a delivered signal makes the interruptible ioctl return `EINTR` instead of auto-restarting.
+fn install_wake_handler() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| {
+        extern "C" fn noop(_: libc::c_int) {}
+        // SAFETY: installing a well-formed `sigaction` with an empty mask and a valid no-op handler
+        // for a single signal; touches only this process's disposition for `WAKE_SIGNAL`.
+        unsafe {
+            let mut sa: libc::sigaction = std::mem::zeroed();
+            // Via `*const ()`: casting a function item straight to an integer is what
+            // `clippy::function_casts_as_integer` rejects, and the pointer hop is the documented
+            // way to spell it. `sa_sigaction` is a `usize`-typed handler slot, so the value is
+            // unchanged.
+            sa.sa_sigaction = noop as *const () as usize;
+            libc::sigemptyset(&mut sa.sa_mask);
+            sa.sa_flags = 0;
+            libc::sigaction(WAKE_SIGNAL, &sa, std::ptr::null_mut());
+        }
+    });
+}
+
+/// Lets `Drop` wake a specific worker thread parked in a blocking ioctl. `tid` is the thread's
+/// `pthread_self()` (0 until it starts); `done` is set right before the thread returns, so `Drop`
+/// stops signalling a thread that has already exited.
+struct Waker {
+    tid: Arc<AtomicU64>,
+    done: Arc<AtomicBool>,
+}
+
 /// A virtual Steam Deck presented over the USB gadget subsystem. Dropping it stops the threads and
 /// closes the gadget (the kernel tears down the device).
 pub struct SteamDeckGadget {
@@ -203,6 +242,7 @@ pub struct SteamDeckGadget {
     feedback: Arc<Mutex<super::steam_proto::SteamFeedback>>,
     running: Arc<AtomicBool>,
     threads: Vec<JoinHandle<()>>,
+    wakers: Vec<Waker>,
     _fd: Arc<GadgetFd>,
     seq: u32,
 }
@@ -243,6 +283,18 @@ impl SteamDeckGadget {
         let ctrl_ep = Arc::new(std::sync::atomic::AtomicI32::new(-1));
         let configured = Arc::new(AtomicBool::new(false));
 
+        // The teardown wake path (see `WAKE_SIGNAL`) needs the handler installed before any thread
+        // can park in a blocking ioctl.
+        install_wake_handler();
+        let ctrl_waker = Waker {
+            tid: Arc::new(AtomicU64::new(0)),
+            done: Arc::new(AtomicBool::new(false)),
+        };
+        let stream_waker = Waker {
+            tid: Arc::new(AtomicU64::new(0)),
+            done: Arc::new(AtomicBool::new(false)),
+        };
+
         // Control thread: enumerate + answer every control transfer.
         let control = {
             let fd = fd.clone();
@@ -250,10 +302,15 @@ impl SteamDeckGadget {
             let ctrl_ep = ctrl_ep.clone();
             let configured = configured.clone();
             let feedback = feedback.clone();
+            let tid = ctrl_waker.tid.clone();
+            let done = ctrl_waker.done.clone();
             std::thread::Builder::new()
                 .name("pf-deck-gadget-ctrl".into())
                 .spawn(move || {
-                    control_loop(fd, running, ctrl_ep, configured, feedback, serial, unit_id)
+                    // SAFETY: `pthread_self` is always valid on the calling thread.
+                    tid.store(unsafe { libc::pthread_self() } as u64, Ordering::SeqCst);
+                    control_loop(fd, running, ctrl_ep, configured, feedback, serial, unit_id);
+                    done.store(true, Ordering::SeqCst);
                 })
                 .context("spawn gadget control thread")?
         };
@@ -264,9 +321,16 @@ impl SteamDeckGadget {
             let ctrl_ep = ctrl_ep.clone();
             let configured = configured.clone();
             let report = report.clone();
+            let tid = stream_waker.tid.clone();
+            let done = stream_waker.done.clone();
             std::thread::Builder::new()
                 .name("pf-deck-gadget-stream".into())
-                .spawn(move || stream_loop(fd, running, ctrl_ep, configured, report))
+                .spawn(move || {
+                    // SAFETY: `pthread_self` is always valid on the calling thread.
+                    tid.store(unsafe { libc::pthread_self() } as u64, Ordering::SeqCst);
+                    stream_loop(fd, running, ctrl_ep, configured, report);
+                    done.store(true, Ordering::SeqCst);
+                })
                 .context("spawn gadget stream thread")?
         };
 
@@ -275,6 +339,7 @@ impl SteamDeckGadget {
             feedback,
             running,
             threads: vec![control, stream],
+            wakers: vec![ctrl_waker, stream_waker],
             _fd: fd,
             seq: 0,
         })
@@ -302,6 +367,32 @@ impl SteamDeckGadget {
 impl Drop for SteamDeckGadget {
     fn drop(&mut self) {
         self.running.store(false, Ordering::SeqCst);
+        // The control thread spends steady state parked in a blocking `EVENT_FETCH` ioctl that only
+        // tests `running` at the top of its loop, so clearing the flag is not enough — it must be
+        // signalled out of the syscall (see `WAKE_SIGNAL`). Without this the join below can hang the
+        // caller (the session input thread, via `PadSlots::sweep`) indefinitely. Retry until each
+        // thread reports done, to cover the race where the signal lands just before the thread
+        // re-enters the ioctl; bounded (~1 s) so a genuinely stuck thread can't wedge teardown either.
+        for _ in 0..200 {
+            let mut all_done = true;
+            for w in &self.wakers {
+                if w.done.load(Ordering::SeqCst) {
+                    continue;
+                }
+                all_done = false;
+                let tid = w.tid.load(Ordering::SeqCst);
+                if tid != 0 {
+                    // SAFETY: the thread is joinable and not yet joined (join runs after this loop),
+                    // so `tid` names a live pthread; `pthread_kill` on a finished-but-unjoined thread
+                    // is defined (returns ESRCH), never UB.
+                    unsafe { libc::pthread_kill(tid as libc::pthread_t, WAKE_SIGNAL) };
+                }
+            }
+            if all_done {
+                break;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(5));
+        }
         for t in self.threads.drain(..) {
             let _ = t.join();
         }

crates/pf-inject/src/inject/windows/dualsense_windows.rs

@@ -299,13 +299,20 @@ pub(super) fn create_swdevice(p: &SwDeviceProfile) -> Result<(HSWDEVICE, Option<
     let event = unsafe { CreateEventW(None, true, false, PCWSTR::null())? };
     // `result` starts as E_FAIL, NOT S_OK: if the wait below times out, a zero-initialised HRESULT
     // would read as success and mask the failure (found by the 2026-07 driver-health audit).
-    let mut ctx = SwCreateCtx {
+    // HEAP-allocated, deliberately: `sw_create_cb` writes `result` + up to 127 u16 of instance id
+    // through this pointer and then `SetEvent`s. The wait below is bounded (10 s), so on a wedged-PnP
+    // timeout the callback may still be PENDING — a stack context would be popped and a late callback
+    // would corrupt whatever the input thread put there next, and SetEvent a closed/recycled handle.
+    // On the timeout path we therefore LEAK the box and leave the event open (a one-off ~264 B + one
+    // HANDLE, only on that rare path) so a late callback always writes to live memory.
+    let ctx = Box::into_raw(Box::new(SwCreateCtx {
         event,
         result: E_FAIL,
         instance_id: [0; 128],
-    };
+    }));
-    // SAFETY: info + the buffers + ctx outlive the call (we wait on the event before returning);
+    // SAFETY: info + the buffers outlive the call; `ctx` is a live heap allocation that outlives every
-    // windows-rs returns the HSWDEVICE (the C out-param) as the Result value.
+    // path below (reclaimed only where the callback provably ran). windows-rs returns the HSWDEVICE
+    // (the C out-param) as the Result value.
     let hsw = match unsafe {
         SwDeviceCreate(
             w!("punktfunk"),
@@ -313,13 +320,15 @@ pub(super) fn create_swdevice(p: &SwDeviceProfile) -> Result<(HSWDEVICE, Option<
             &info,
             None,
             Some(sw_create_cb),
-            Some(&mut ctx as *mut SwCreateCtx as *const c_void),
+            Some(ctx as *const c_void),
         )
     } {
         Ok(h) => h,
         Err(e) => {
-            // SAFETY: event is valid.
+            // SAFETY: the call failed, so no callback was registered and `ctx` is ours to reclaim;
+            // `event` is valid and unreferenced.
             unsafe {
+                drop(Box::from_raw(ctx));
                 let _ = CloseHandle(event);
             }
             return Err(anyhow!("SwDeviceCreate failed: {e}"));
@@ -328,17 +337,22 @@ pub(super) fn create_swdevice(p: &SwDeviceProfile) -> Result<(HSWDEVICE, Option<
     // Block until PnP finishes enumerating (the callback signals), then check its result.
     // SAFETY: event is valid.
     let wait = unsafe { WaitForSingleObject(event, 10_000) };
-    // SAFETY: event is valid.
-    unsafe {
-        let _ = CloseHandle(event);
-    }
     if wait != WAIT_OBJECT_0 {
+        // Timed out: the callback may still fire. Intentionally leak `ctx` AND leave `event` open so
+        // its eventual write + SetEvent target live memory/handle rather than freed ones.
         // SAFETY: hsw is the handle SwDeviceCreate returned.
         unsafe { SwDeviceClose(hsw) };
         return Err(anyhow!(
             "SwDeviceCreate enumeration callback never fired (10s) — PnP may be wedged"
         ));
     }
+    // The callback ran (it is what signalled the event), so nothing else will touch `ctx`/`event`.
+    // SAFETY: `ctx` came from `Box::into_raw` above and is reclaimed exactly once here; `event` is
+    // valid and no longer referenced by a pending callback.
+    let ctx = unsafe {
+        let _ = CloseHandle(event);
+        Box::from_raw(ctx)
+    };
     if ctx.result.is_err() {
         // SAFETY: hsw is the handle SwDeviceCreate returned.
         unsafe { SwDeviceClose(hsw) };

crates/pf-inject/src/inject/windows/dualshock4_windows.rs

@@ -62,7 +62,7 @@ impl Ds4WinPad {
             std::ptr::write_unaligned(base as *mut u32, SHM_MAGIC);
         }
         let inst = format!("pf_ds4_{index}");
-        let (hsw, instance_id) = match create_swdevice(&SwDeviceProfile {
+        let (hsw, instance_id) = create_swdevice(&SwDeviceProfile {
             instance: &inst,
             container_tag: 0x5046_4453, // "PFDS"
             container_index: index,
@@ -70,13 +70,13 @@ impl Ds4WinPad {
             usb_vid_pid: "VID_054C&PID_09CC",
             usb_mi: None,
             description: "punktfunk Virtual DualShock 4",
-        }) {
+        })?; // Propagate, do NOT swallow — see below.
-            Ok((h, id)) => (Some(h), id),
+        let (hsw, instance_id) = (Some(hsw), instance_id);
-            Err(e) => {
+        // Swallowing a create failure here (the previous behaviour) latched the pad slot to
-                tracing::warn!(error = %format!("{e:#}"), "SwDeviceCreate failed; DualShock 4 devnode unavailable");
+        // `Some(pad)` with no live devnode: `PadSlots::ensure` short-circuits on `is_some()` and
-                (None, None)
+        // `gate.on_success()` cleared the backoff, so the create-gate that exists precisely to
-            }
+        // self-heal a transient PnP failure never retried. The game saw no controller for the whole
-        };
+        // session unless the client unplugged the pad. Matches the XUSB sibling, which propagates.
         let _sw = hsw.map(super::gamepad_raii::SwDevice::new);
         // Bounded eager delivery — for the DS4 this is what closes the identity race: the driver
         // must read `device_type = 1` from the delivered DATA section before hidclass asks it for

crates/pf-inject/src/inject/windows/gamepad_windows.rs

@@ -82,12 +82,16 @@ fn create_swdevice(index: u8) -> Result<(HSWDEVICE, Option<String>)> {
     let event = unsafe { CreateEventW(None, true, false, PCWSTR::null())? };
     // `result` starts as E_FAIL, NOT S_OK: if the wait below times out, a zero-initialised HRESULT
     // would read as success and mask the failure (found by the 2026-07 driver-health audit).
-    let mut ctx = SwCreateCtx {
+    // HEAP-allocated for the same reason as the DualSense sibling: the callback writes through this
+    // pointer and SetEvents, and the wait below is bounded — a stack context would be popped while a
+    // late callback still holds it. On the timeout path the box is deliberately leaked and the event
+    // left open so a late write/SetEvent always targets live memory/handle.
+    let ctx = Box::into_raw(Box::new(SwCreateCtx {
         event,
         result: E_FAIL,
         instance_id: [0; 128],
-    };
+    }));
-    // SAFETY: info + buffers + ctx outlive the call (we wait on the event before returning).
+    // SAFETY: info + buffers outlive the call; `ctx` is a live heap allocation outliving every path.
     let hsw = match unsafe {
         SwDeviceCreate(
             w!("punktfunk"),
@@ -95,13 +99,14 @@ fn create_swdevice(index: u8) -> Result<(HSWDEVICE, Option<String>)> {
             &info,
             None,
             Some(sw_create_cb),
-            Some(&mut ctx as *mut SwCreateCtx as *const c_void),
+            Some(ctx as *const c_void),
         )
     } {
         Ok(h) => h,
         Err(e) => {
-            // SAFETY: event is valid.
+            // SAFETY: the call failed, so no callback is pending and `ctx` is ours to reclaim.
             unsafe {
+                drop(Box::from_raw(ctx));
                 let _ = CloseHandle(event);
             }
             return Err(anyhow!("SwDeviceCreate(pf_xusb) failed: {e}"));
@@ -109,17 +114,20 @@ fn create_swdevice(index: u8) -> Result<(HSWDEVICE, Option<String>)> {
     };
     // SAFETY: event valid; block until PnP finishes enumerating, then check the callback result.
     let wait = unsafe { WaitForSingleObject(event, 10_000) };
-    // SAFETY: event is valid.
-    unsafe {
-        let _ = CloseHandle(event);
-    }
     if wait != WAIT_OBJECT_0 {
+        // Timed out — intentionally leak `ctx` and leave `event` open (see above).
         // SAFETY: hsw is the handle SwDeviceCreate returned.
         unsafe { SwDeviceClose(hsw) };
         return Err(anyhow!(
             "SwDeviceCreate(pf_xusb) enumeration callback never fired (10s) — PnP may be wedged"
         ));
     }
+    // The callback ran (it signalled the event), so nothing else will touch `ctx`/`event`.
+    // SAFETY: `ctx` came from `Box::into_raw` and is reclaimed exactly once here.
+    let ctx = unsafe {
+        let _ = CloseHandle(event);
+        Box::from_raw(ctx)
+    };
     if ctx.result.is_err() {
         // SAFETY: hsw is the handle SwDeviceCreate returned.
         unsafe { SwDeviceClose(hsw) };

crates/pf-inject/src/inject/windows/steam_deck_windows.rs

@@ -66,7 +66,7 @@ impl DeckWinPad {
             std::ptr::write_unaligned(base as *mut u32, SHM_MAGIC);
         }
         let inst = format!("pf_deck_{index}");
-        let (hsw, instance_id) = match create_swdevice(&SwDeviceProfile {
+        let (hsw, instance_id) = create_swdevice(&SwDeviceProfile {
             instance: &inst,
             container_tag: 0x5046_4453, // "PFDS"
             container_index: index,
@@ -77,13 +77,8 @@ impl DeckWinPad {
             // spike's run-1 failure).
             usb_mi: Some(2),
             description: "punktfunk Virtual Steam Deck",
-        }) {
+        })?; // Propagate — swallowing latched the slot to a pad with no devnode (see the DS4 twin).
-            Ok((h, i)) => (Some(h), i),
+        let (hsw, instance_id) = (Some(hsw), instance_id);
-            Err(e) => {
-                tracing::warn!(error = %format!("{e:#}"), "SwDeviceCreate failed; Steam Deck devnode unavailable");
-                (None, None)
-            }
-        };
         let _sw = hsw.map(super::gamepad_raii::SwDevice::new);
         // Bounded eager delivery — the driver must read `device_type = 3` before hidclass asks
         // it for descriptors, or the pad would enumerate with the default DualSense identity.

crates/pf-presenter/Cargo.toml

@@ -11,7 +11,11 @@ repository.workspace = true
 # Same Linux+Windows gating as the rest of the client stack (dmabuf import is the one
 # Linux-only module — see lib.rs).
 [target.'cfg(any(target_os = "linux", windows))'.dependencies]
-pf-client-core = { path = "../pf-client-core" }
+# `default-features = false`: the PyroWave decode backend is turned on through THIS crate's own
+# `pyrowave` feature (which re-exports it below), never by inheriting the dependency's default.
+# Otherwise a consumer that deliberately builds us without `pyrowave` still drags the vendored
+# C++ in — fatal on Windows ARM64, where Granite has no SIMD path.
+pf-client-core = { path = "../pf-client-core", default-features = false }
 # AVVkFrame access (Vulkan Video frames: live sync state under the frames lock).
 pf-ffvk = { path = "../pf-ffvk" }
 punktfunk-core = { path = "../punktfunk-core", features = ["quic"] }

crates/pf-zerocopy/src/imp/client.rs

@@ -21,7 +21,7 @@ use std::path::{Path, PathBuf};
 use std::process::{Child, Command};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, OnceLock};
-use std::time::Duration;
+use std::time::{Duration, Instant};
 
 /// Handshake budget: EGL + CUDA bring-up is ~200 ms; a cold driver load can take seconds.
 const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(20);
@@ -64,11 +64,27 @@ impl Drop for Shared {
 /// Children whose worker hasn't exited yet at `RemoteImporter` drop time (it exits on socket
 /// EOF, i.e. after the last in-flight frame drops). Swept on every spawn and every drop so
 /// workers don't linger as zombies for more than one capture generation.
-static REAPER: Mutex<Vec<Child>> = Mutex::new(Vec::new());
+static REAPER: Mutex<Vec<(Child, Instant)>> = Mutex::new(Vec::new());
+
+/// How long past `REPLY_TIMEOUT` a parked worker may linger before it is force-killed. A worker
+/// wedged INSIDE a driver call never observes socket EOF, so `try_wait` alone would keep it (and
+/// its CUcontext + BufferPool — order hundreds of MB of VRAM) forever.
+const REAPER_KILL_DEADLINE: Duration = Duration::from_secs(20);
 
 fn sweep_reaper() {
     let mut list = REAPER.lock().unwrap();
-    list.retain_mut(|c| !matches!(c.try_wait(), Ok(Some(_))));
+    let now = Instant::now();
+    list.retain_mut(|(c, parked)| {
+        if matches!(c.try_wait(), Ok(Some(_))) {
+            return false; // exited on its own → reaped
+        }
+        if now.duration_since(*parked) > REAPER_KILL_DEADLINE {
+            let _ = c.kill();
+            let _ = c.wait();
+            return false; // wedged past the deadline → force-killed + reaped
+        }
+        true
+    });
 }
 
 /// Fd pinned to this process's own executable image, opened (once, lazily) via the
@@ -455,7 +471,7 @@ impl Drop for RemoteImporter {
         // gone; park the rest for the next sweep.
         if let Some(mut child) = self.child.take() {
             if !matches!(child.try_wait(), Ok(Some(_))) {
-                REAPER.lock().unwrap().push(child);
+                REAPER.lock().unwrap().push((child, Instant::now()));
             }
         }
         sweep_reaper();

crates/pf-zerocopy/src/imp/cuda.rs

@@ -251,6 +251,32 @@ unsafe fn copy_blocking(copy: &CUDA_MEMCPY2D, what: &str) -> Result<()> {
     ck(cuStreamSynchronize(stream), "cuStreamSynchronize")
 }
 
+/// Issue `copy` on this thread's priority stream WITHOUT waiting — for stream-ordered consumers
+/// only (the direct-NVENC submit path with `NvEncSetIOCudaStreams` bound to this stream): the
+/// stream, not the CPU, orders completion, so the SOURCE must stay valid until the downstream
+/// stream work (the encode) has finished.
+unsafe fn copy_async(copy: &CUDA_MEMCPY2D, what: &str) -> Result<()> {
+    ck(cuMemcpy2DAsync_v2(copy, copy_stream()), what)
+}
+
+/// `copy_blocking` when `sync`, else `copy_async` — the shared tail of the public `copy_*_to_device`
+/// helpers, whose `sync: false` mode carries `copy_async`'s source-lifetime contract.
+unsafe fn copy_issue(copy: &CUDA_MEMCPY2D, what: &str, sync: bool) -> Result<()> {
+    if sync {
+        copy_blocking(copy, what)
+    } else {
+        copy_async(copy, what)
+    }
+}
+
+/// The calling thread's copy/launch stream as a raw handle, for binding external stream-ordering
+/// (the direct-NVENC `NvEncSetIOCudaStreams` hookup). Null = the NULL stream (priority-stream
+/// creation failed) — callers should treat null as "stream-ordering unavailable" and keep their
+/// blocking copies. The shared context must be current on this thread.
+pub fn copy_stream_handle() -> *mut c_void {
+    copy_stream() // CUstream IS *mut c_void (opaque CUstream_st*)
+}
+
 /// Max cursor-overlay bitmap edge (px) uploaded to the device blend buffer — matches the Vulkan path.
 pub const CURSOR_MAX: u32 = 256;
 
@@ -354,6 +380,7 @@ impl CursorBlend {
         ch: u32,
         ox: i32,
         oy: i32,
+        sync: bool,
     ) -> Result<()> {
         let (mut a_surf, mut a_cur) = (surf, self.cur_buf);
         let (mut a_pitch, mut a_w, mut a_h) = (pitch as i32, w as i32, h as i32);
@@ -370,7 +397,7 @@ impl CursorBlend {
             &mut a_ox as *mut _ as *mut c_void,
             &mut a_oy as *mut _ as *mut c_void,
         ];
-        self.launch(self.f_argb, a_cw as u32, a_ch as u32, &mut args)
+        self.launch(self.f_argb, a_cw as u32, a_ch as u32, &mut args, sync)
     }
 
     /// Blend into an owned planar YUV444 surface (3 stacked full-res planes) at `(ox,oy)`.
@@ -385,6 +412,7 @@ impl CursorBlend {
         ch: u32,
         ox: i32,
         oy: i32,
+        sync: bool,
     ) -> Result<()> {
         let (mut a_base, mut a_cur) = (base, self.cur_buf);
         let (mut a_pitch, mut a_w, mut a_h) = (pitch as i32, w as i32, h as i32);
@@ -401,7 +429,7 @@ impl CursorBlend {
             &mut a_ox as *mut _ as *mut c_void,
             &mut a_oy as *mut _ as *mut c_void,
         ];
-        self.launch(self.f_yuv444, a_cw as u32, a_ch as u32, &mut args)
+        self.launch(self.f_yuv444, a_cw as u32, a_ch as u32, &mut args, sync)
     }
 
     /// Blend into an owned NV12 surface (Y plane at `base`, interleaved UV at `base + pitch*h`).
@@ -416,6 +444,7 @@ impl CursorBlend {
         ch: u32,
         ox: i32,
         oy: i32,
+        sync: bool,
     ) -> Result<()> {
         let (mut a_yb, mut a_uvb, mut a_cur) = (base, base + pitch as u64 * h as u64, self.cur_buf);
         let (mut a_yp, mut a_uvp) = (pitch as i32, pitch as i32);
@@ -441,16 +470,20 @@ impl CursorBlend {
             (a_cw as u32).div_ceil(2),
             (a_ch as u32).div_ceil(2),
             &mut args,
+            sync,
         )
     }
 
-    /// Launch `f` over a `work_w × work_h` grid (16×16 blocks) on the copy stream, then synchronize.
+    /// Launch `f` over a `work_w × work_h` grid (16×16 blocks) on the copy stream; `sync` waits
+    /// for it, `!sync` leaves completion to the stream (stream-ordered consumers only — the
+    /// kernel PARAMETERS are copied at launch time, so the arg locals need not outlive the call).
     fn launch(
         &self,
         f: CUfunction,
         work_w: u32,
         work_h: u32,
         args: &mut [*mut c_void],
+        sync: bool,
     ) -> Result<()> {
         if work_w == 0 || work_h == 0 {
             return Ok(());
@@ -458,9 +491,11 @@ impl CursorBlend {
         const B: u32 = 16;
         let stream = copy_stream();
         // SAFETY: `f` is a resolved kernel from our loaded module; `args` holds pointers to live
-        // locals whose types match the kernel's C parameters (per the call site above); grid/block
+        // locals whose types match the kernel's C parameters (per the call site above) — CUDA
-        // dims are non-zero. Launched on the copy stream (ordered after the input-surface copy that
+        // copies the parameter values during `cuLaunchKernel` itself, so they need not outlive
-        // `copy_into_slot` already synchronized) then synchronized. Requires the context current.
+        // the call. Grid/block dims are non-zero. Launched on the copy stream (ordered after the
+        // input-surface copy issued on the same stream); `sync` waits, `!sync` leaves ordering to
+        // the stream (the NVENC IO-stream binding). Requires the context current.
         unsafe {
             ck(
                 cuLaunchKernel(
@@ -478,7 +513,10 @@ impl CursorBlend {
                 ),
                 "cuLaunchKernel(cursor)",
             )?;
-            ck(cuStreamSynchronize(stream), "cuStreamSynchronize(cursor)")
+            if sync {
+                ck(cuStreamSynchronize(stream), "cuStreamSynchronize(cursor)")?;
+            }
+            Ok(())
         }
     }
 }
@@ -1003,7 +1041,13 @@ impl RegisteredTexture {
         // SAFETY: `self.resource` is the valid `CUgraphicsResource` from a successful `register_gl`
         // (its only constructor), so the wrappers forward to the live table; the caller holds the
         // GL+CUDA contexts current (the registration's contract). `cuGraphicsMapResources` maps
-        // `count == 1` resource via `&mut self.resource` (a live field) on the default stream;
+        // `count == 1` resource via `&mut self.resource` (a live field). It is issued on
+        // `copy_stream()` — NOT the NULL stream — because map's only ordering guarantee is that
+        // prior GL work completes before subsequent CUDA work issued IN THE STREAM PASSED TO IT;
+        // the copy below runs on `copy_stream()` (a `CU_STREAM_NON_BLOCKING` stream, exempt from
+        // implicit NULL-stream ordering), so mapping on NULL left the copy free to race the GL
+        // de-tile/CSC that produced this texture (glFlush only, no fence) — intermittent torn or
+        // stale frames under GPU load. Map, copy, and unmap now all share `copy_stream()`.
         // `cuGraphicsSubResourceGetMappedArray` writes the mapped `CUarray` into the live local
         // `array` (index 0, mip 0). On failure we unmap and bail (balanced). `&copy` is a live
         // local `CUDA_MEMCPY2D` outliving the synchronous `copy_blocking`: `srcArray` is valid
@@ -1012,12 +1056,12 @@ impl RegisteredTexture {
         // we always unmap afterward (even on error), keeping the map/unmap pair balanced.
         unsafe {
             ck(
-                cuGraphicsMapResources(1, &mut self.resource, std::ptr::null_mut()),
+                cuGraphicsMapResources(1, &mut self.resource, copy_stream()),
                 "cuGraphicsMapResources",
             )?;
             let mut array: CUarray = std::ptr::null_mut();
             if cuGraphicsSubResourceGetMappedArray(&mut array, self.resource, 0, 0) != 0 {
-                let _ = cuGraphicsUnmapResources(1, &mut self.resource, std::ptr::null_mut());
+                let _ = cuGraphicsUnmapResources(1, &mut self.resource, copy_stream());
                 bail!("cuGraphicsSubResourceGetMappedArray failed");
             }
             let copy = CUDA_MEMCPY2D {
@@ -1031,7 +1075,7 @@ impl RegisteredTexture {
                 ..Default::default()
             };
             let res = copy_blocking(&copy, "cuMemcpy2DAsync_v2");
-            let _ = cuGraphicsUnmapResources(1, &mut self.resource, std::ptr::null_mut());
+            let _ = cuGraphicsUnmapResources(1, &mut self.resource, copy_stream());
             res
         }
     }
@@ -1058,12 +1102,12 @@ impl RegisteredTexture {
         // so the map/unmap pair stays balanced and the array outlives the copy.
         unsafe {
             ck(
-                cuGraphicsMapResources(1, &mut self.resource, std::ptr::null_mut()),
+                cuGraphicsMapResources(1, &mut self.resource, copy_stream()),
                 "cuGraphicsMapResources",
             )?;
             let mut array: CUarray = std::ptr::null_mut();
             if cuGraphicsSubResourceGetMappedArray(&mut array, self.resource, 0, 0) != 0 {
-                let _ = cuGraphicsUnmapResources(1, &mut self.resource, std::ptr::null_mut());
+                let _ = cuGraphicsUnmapResources(1, &mut self.resource, copy_stream());
                 bail!("cuGraphicsSubResourceGetMappedArray failed");
             }
             let copy = CUDA_MEMCPY2D {
@@ -1077,7 +1121,7 @@ impl RegisteredTexture {
                 ..Default::default()
             };
             let res = copy_blocking(&copy, "cuMemcpy2DAsync_v2(plane)");
-            let _ = cuGraphicsUnmapResources(1, &mut self.resource, std::ptr::null_mut());
+            let _ = cuGraphicsUnmapResources(1, &mut self.resource, copy_stream());
             res
         }
     }
@@ -1122,10 +1166,13 @@ pub fn copy_mapped_yuv444(
 /// Copy a pitched device buffer into another device region (device→device), e.g. our imported
 /// [`DeviceBuffer`] into a pooled CUDA surface NVENC owns. Both are 4-byte (BGRx) pixels.
 /// The caller must have the shared context current on this thread (see [`make_current`]).
+/// `sync: false` enqueues without a CPU wait (stream-ordered consumers only — `src` must stay
+/// valid until the downstream stream work completes; see [`copy_stream_handle`]).
 pub fn copy_device_to_device(
     src: &DeviceBuffer,
     dst_ptr: CUdeviceptr,
     dst_pitch: usize,
+    sync: bool,
 ) -> Result<()> {
     let copy = CUDA_MEMCPY2D {
         srcMemoryType: CU_MEMORYTYPE_DEVICE,
@@ -1138,23 +1185,27 @@ pub fn copy_device_to_device(
         Height: src.height as usize,
         ..Default::default()
     };
-    // SAFETY: `copy_blocking` is unsafe (issues a CUDA copy); the caller must have the shared
+    // SAFETY: `copy_issue` is unsafe (issues a CUDA copy); the caller must have the shared
     // context current (documented). `&copy` is a live local device→device `CUDA_MEMCPY2D` outliving
-    // the synchronous call: `srcDevice`/`srcPitch` are `src`'s live allocation, `dstDevice`/
+    // the enqueue: `srcDevice`/`srcPitch` are `src`'s live allocation, `dstDevice`/`dstPitch` the
-    // `dstPitch` the caller's live region, `width*4`×`height` within both. Wrapper → live table.
+    // caller's live region, `width*4`×`height` within both; `sync: false` shifts the source-
-    unsafe { copy_blocking(&copy, "cuMemcpy2DAsync_v2(dev->dev)") }
+    // lifetime obligation to the caller (documented above). Wrapper → live table.
+    unsafe { copy_issue(&copy, "cuMemcpy2DAsync_v2(dev->dev)", sync) }
 }
 
 /// Copy our imported NV12 [`DeviceBuffer`] (Y + UV planes) into NVENC's two-plane CUDA surface
 /// `(y_dst, y_pitch)` / `(uv_dst, uv_pitch)` (`av_hwframe_get_buffer`'s `data[0]`/`data[1]` +
 /// `linesize[0]`/`linesize[1]`). The Y plane is `width`×`height` bytes; the chroma plane is
 /// `(width/2)·2` bytes × `height/2` rows. The caller must have the shared context current.
+/// `sync: false` enqueues without a CPU wait (stream-ordered consumers only — `src` must stay
+/// valid until the downstream stream work completes; see [`copy_stream_handle`]).
 pub fn copy_nv12_to_device(
     src: &DeviceBuffer,
     y_dst: CUdeviceptr,
     y_pitch: usize,
     uv_dst: CUdeviceptr,
     uv_pitch: usize,
+    sync: bool,
 ) -> Result<()> {
     let (src_uv_ptr, src_uv_pitch) = src
         .uv
@@ -1183,15 +1234,16 @@ pub fn copy_nv12_to_device(
         Height: h / 2,
         ..Default::default()
     };
-    // SAFETY: two unsafe `copy_blocking` device→device copies; the caller must have the shared
+    // SAFETY: two unsafe `copy_issue` device→device copies; the caller must have the shared
     // context current (documented). `&y`/`&uv` are live local `CUDA_MEMCPY2D`s outliving each
-    // synchronous call. All four device pointers are valid: `src.ptr`/`src_uv_ptr` come from a live
+    // enqueue. All four device pointers are valid: `src.ptr`/`src_uv_ptr` come from a live
     // NV12 `DeviceBuffer` (its `.uv` presence was checked via `ok_or_else`), `y_dst`/`uv_dst` are
     // the caller's live NVENC surface planes; the luma copy is `w`×`h`, the chroma copy
-    // `(w/2)*2`×`h/2`, each within its planes. Wrappers → live table.
+    // `(w/2)*2`×`h/2`, each within its planes; `sync: false` shifts the source-lifetime obligation
+    // to the caller (documented above). Wrappers → live table.
     unsafe {
-        copy_blocking(&y, "cuMemcpy2DAsync_v2(nv12 Y dev->dev)")?;
+        copy_issue(&y, "cuMemcpy2DAsync_v2(nv12 Y dev->dev)", sync)?;
-        copy_blocking(&uv, "cuMemcpy2DAsync_v2(nv12 UV dev->dev)")
+        copy_issue(&uv, "cuMemcpy2DAsync_v2(nv12 UV dev->dev)", sync)
     }
 }
 
@@ -1199,7 +1251,13 @@ pub fn copy_nv12_to_device(
 /// (`av_hwframe_get_buffer`'s `data[0..3]` + `linesize[0..3]` for a `yuv444p` frames context).
 /// Each plane is `width`×`height` bytes; the source planes sit at row offsets `0/H/2H` of the
 /// single allocation. The caller must have the shared context current.
-pub fn copy_yuv444_to_device(src: &DeviceBuffer, dsts: [(CUdeviceptr, usize); 3]) -> Result<()> {
+/// `sync: false` enqueues without a CPU wait (stream-ordered consumers only — `src` must stay
+/// valid until the downstream stream work completes; see [`copy_stream_handle`]).
+pub fn copy_yuv444_to_device(
+    src: &DeviceBuffer,
+    dsts: [(CUdeviceptr, usize); 3],
+    sync: bool,
+) -> Result<()> {
     anyhow::ensure!(src.yuv444, "copy_yuv444_to_device on a non-YUV444 buffer");
     let w = src.width as usize;
     let h = src.height as usize;
@@ -1215,12 +1273,13 @@ pub fn copy_yuv444_to_device(src: &DeviceBuffer, dsts: [(CUdeviceptr, usize); 3]
             Height: h,
             ..Default::default()
         };
-        // SAFETY: unsafe `copy_blocking` device→device copy; the caller must have the shared
+        // SAFETY: unsafe `copy_issue` device→device copy; the caller must have the shared
-        // context current (documented). `&copy` is a live local outliving the synchronous call;
+        // context current (documented). `&copy` is a live local outliving the enqueue;
         // `src.ptr + pitch·h·i` stays within the live 3·H-row stacked allocation (`yuv444`
         // checked above), `dst_ptr`/`dst_pitch` is the caller's live NVENC plane; `w`×`h` fits
-        // both. Wrapper → live table.
+        // both; `sync: false` shifts the source-lifetime obligation to the caller (documented
-        unsafe { copy_blocking(&copy, "cuMemcpy2DAsync_v2(yuv444 plane dev->dev)")? };
+        // above). Wrapper → live table.
+        unsafe { copy_issue(&copy, "cuMemcpy2DAsync_v2(yuv444 plane dev->dev)", sync)? };
     }
     Ok(())
 }

crates/pf-zerocopy/src/imp/egl.rs

@@ -691,6 +691,15 @@ impl EglImporter {
         width: u32,
         height: u32,
     ) -> Result<DeviceBuffer> {
+        // Even dimensions only: the UV copy walks `height.div_ceil(2)` chroma rows (the correct NV12
+        // count), but the pooled UV plane is sized at `height/2` rows — for an odd height those
+        // disagree by one row and the copy writes a full `uv_pitch` past the allocation (OOB device
+        // write / CUDA_ERROR_ILLEGAL_ADDRESS that poisons the shared context). Reject here, matching
+        // the guards `Nv12Blit::new`/`Yuv444Blit::new` already carry.
+        anyhow::ensure!(
+            width % 2 == 0 && height % 2 == 0,
+            "LINEAR NV12 needs even dimensions (got {width}x{height})"
+        );
         cuda::make_current()?;
         if self
             .linear_nv12_pool

crates/pf-zerocopy/src/imp/vulkan.rs

@@ -86,9 +86,11 @@ impl VkBridge {
         // SAFETY: standard ash bring-up — every call is `unsafe` only because ash cannot statically
         // verify Vulkan handle/CreateInfo validity. `ash::Entry::load` dlopens a real system
         // libvulkan. Each `*CreateInfo`/`AllocateInfo` is built by ash's builders from locals (`app`,
-        // `exts`, `prio`, `qci`, and the inline infos) that all live for the duration of the
+        // `exts`, `prio`, `qci`, `gp_info`, and the inline infos) that all live for the duration of
-        // synchronous `create_*`/`enumerate_*` call that reads them — in particular the
+        // the synchronous `create_*`/`enumerate_*` call that reads them — the ladder loop rebuilds
-        // `enabled_extension_names(&exts)` and `queue_priorities(&prio)` borrows outlive their calls.
+        // `prio`/`gp_info`/`qci`/`exts` fresh per attempt, so every `enabled_extension_names(&exts)`
+        // / `queue_priorities(&prio)` / `push_next(&mut gp_info)` borrow outlives its own
+        // `create_device` call.
         // Every handle passed (`instance`, `phys`, `device`, `qf`, `cmd_pool`) was just created and
         // checked via `?`/`ok_or_else` in this same function, so no invalid handle is ever used. This
         // constructor shares nothing across threads.
@@ -122,23 +124,93 @@ impl VkBridge {
                 .ok_or_else(|| anyhow!("no compute-capable queue family"))?
                 as u32;
 
-            let exts = [
+            // Global-priority queue (latency plan §7 LN4, PyroWave's `ac0e7332` lever for the
+            // VkBridge): the LINEAR/gamescope CSC dispatch shares the SM/compute cores with the
+            // game, so ask for an elevated global priority to get scheduled ahead of it.
+            // `PUNKTFUNK_VK_QUEUE_PRIORITY` = off | high | realtime (default realtime); the
+            // create loop downgrades REALTIME→HIGH→none on NOT_PERMITTED (and retries a plain
+            // create on INITIALIZATION_FAILED) so a refused class never fails the bridge.
+            let gp_ext = std::env::var("PUNKTFUNK_VK_QUEUE_PRIORITY")
+                .ok()
+                .as_deref()
+                .map_or(Some(vk::QueueGlobalPriorityKHR::REALTIME), |v| match v {
+                    "off" | "0" => None,
+                    "high" => Some(vk::QueueGlobalPriorityKHR::HIGH),
+                    _ => Some(vk::QueueGlobalPriorityKHR::REALTIME),
+                })
+                .and_then(|want| {
+                    // Enable whichever alias the driver advertises (KHR = the promoted name).
+                    let props = instance.enumerate_device_extension_properties(phys).ok()?;
+                    let has = |name: &std::ffi::CStr| {
+                        props
+                            .iter()
+                            .any(|p| p.extension_name_as_c_str() == Ok(name))
+                    };
+                    if has(vk::KHR_GLOBAL_PRIORITY_NAME) {
+                        Some((vk::KHR_GLOBAL_PRIORITY_NAME, want))
+                    } else if has(vk::EXT_GLOBAL_PRIORITY_NAME) {
+                        Some((vk::EXT_GLOBAL_PRIORITY_NAME, want))
+                    } else {
+                        None
+                    }
+                });
+            let base_exts = [
                 ash::khr::external_memory_fd::NAME.as_ptr(),
                 ash::ext::external_memory_dma_buf::NAME.as_ptr(),
             ];
+            let mut try_priority = gp_ext.map(|(_, want)| want);
+            let device = loop {
                 let prio = [1.0f32];
-            let qci = [vk::DeviceQueueCreateInfo::default()
+                let mut gp_info = vk::DeviceQueueGlobalPriorityCreateInfoKHR::default()
+                    .global_priority(try_priority.unwrap_or(vk::QueueGlobalPriorityKHR::MEDIUM));
+                let mut qci0 = vk::DeviceQueueCreateInfo::default()
                     .queue_family_index(qf)
-                .queue_priorities(&prio)];
+                    .queue_priorities(&prio);
-            let device = instance
+                let mut exts: Vec<*const std::ffi::c_char> = base_exts.to_vec();
-                .create_device(
+                if try_priority.is_some() {
+                    qci0 = qci0.push_next(&mut gp_info);
+                    exts.push(gp_ext.expect("try_priority implies gp_ext").0.as_ptr());
+                }
+                let qci = [qci0];
+                match instance.create_device(
                     phys,
                     &vk::DeviceCreateInfo::default()
                         .queue_create_infos(&qci)
                         .enabled_extension_names(&exts),
                     None,
-                )
+                ) {
-                .context("vkCreateDevice (external-memory extensions supported?)")?;
+                    Ok(d) => {
+                        if let Some(p) = try_priority {
+                            tracing::info!(
+                                priority = ?p,
+                                "VkBridge queue at elevated global priority (CSC schedules \
+                                 ahead of a GPU-bound game where the driver honors it)"
+                            );
+                        }
+                        break d;
+                    }
+                    // A refused class must never fail the bridge — walk the ladder down.
+                    Err(
+                        vk::Result::ERROR_NOT_PERMITTED_KHR
+                        | vk::Result::ERROR_INITIALIZATION_FAILED,
+                    ) if try_priority == Some(vk::QueueGlobalPriorityKHR::REALTIME) => {
+                        try_priority = Some(vk::QueueGlobalPriorityKHR::HIGH);
+                    }
+                    Err(
+                        vk::Result::ERROR_NOT_PERMITTED_KHR
+                        | vk::Result::ERROR_INITIALIZATION_FAILED,
+                    ) if try_priority.is_some() => {
+                        tracing::debug!(
+                            "global-priority queue not permitted — VkBridge at default priority"
+                        );
+                        try_priority = None;
+                    }
+                    Err(e) => {
+                        return Err(e)
+                            .context("vkCreateDevice (external-memory extensions supported?)")
+                    }
+                }
+            };
             let ext_fd = ash::khr::external_memory_fd::Device::new(&instance, &device);
             let queue = device.get_device_queue(qf, 0);
 
@@ -193,10 +265,17 @@ impl VkBridge {
 
     /// Import `fd` (dup'd internally; Vulkan owns the dup) as a transfer-src buffer of `size`.
     unsafe fn import_src(&mut self, fd: i32, size: u64) -> Result<()> {
+        use std::os::fd::{AsRawFd, FromRawFd, IntoRawFd, OwnedFd};
         let dup = libc::dup(fd);
         if dup < 0 {
             bail!("dup(dmabuf fd)");
         }
+        // Own the dup so every early return BEFORE Vulkan consumes it (at `allocate_memory` success)
+        // closes it. `SrcBuf` holds raw handles with no Drop and is only populated on the success
+        // path, so each fallible step below must also destroy the buffer it created — otherwise a
+        // failed import (which the worker survives and the caller retries every frame) leaks a
+        // VkBuffer + VkDeviceMemory + fd per frame for the worker's whole lifetime.
+        let dup = OwnedFd::from_raw_fd(dup);
         let mut ext_info = vk::ExternalMemoryBufferCreateInfo::default()
             .handle_types(vk::ExternalMemoryHandleTypeFlags::DMA_BUF_EXT);
         let buffer = self
@@ -212,41 +291,55 @@ impl VkBridge {
                     .push_next(&mut ext_info),
                 None,
             )
-            .context("create import buffer")?;
+            .context("create import buffer")?; // `dup` drops → closes on failure
         let mut fd_props = vk::MemoryFdPropertiesKHR::default();
-        self.ext_fd
+        if let Err(e) = self.ext_fd.get_memory_fd_properties(
-            .get_memory_fd_properties(
             vk::ExternalMemoryHandleTypeFlags::DMA_BUF_EXT,
-                dup,
+            dup.as_raw_fd(),
             &mut fd_props,
-            )
+        ) {
-            .context("vkGetMemoryFdPropertiesKHR")?;
+            self.device.destroy_buffer(buffer, None);
+            return Err(e).context("vkGetMemoryFdPropertiesKHR");
+        }
         let reqs = self.device.get_buffer_memory_requirements(buffer);
-        let mem_type = self.memory_type(
+        let mem_type = match self.memory_type(
             reqs.memory_type_bits & fd_props.memory_type_bits,
             vk::MemoryPropertyFlags::empty(),
-        )?;
+        ) {
+            Ok(t) => t,
+            Err(e) => {
+                self.device.destroy_buffer(buffer, None);
+                return Err(e);
+            }
+        };
+        // Vulkan takes ownership of the fd on a SUCCESSFUL import: hand over the raw fd now, and on
+        // failure close it ourselves (matching the original contract) plus destroy the buffer.
+        let raw = dup.into_raw_fd();
         let mut import = vk::ImportMemoryFdInfoKHR::default()
             .handle_type(vk::ExternalMemoryHandleTypeFlags::DMA_BUF_EXT)
-            .fd(dup); // Vulkan takes ownership of `dup` on success
+            .fd(raw);
         let mut dedicated = vk::MemoryDedicatedAllocateInfo::default().buffer(buffer);
-        let memory = self
+        let memory = match self.device.allocate_memory(
-            .device
-            .allocate_memory(
             &vk::MemoryAllocateInfo::default()
                 .allocation_size(reqs.size.max(size))
                 .memory_type_index(mem_type)
                 .push_next(&mut import)
                 .push_next(&mut dedicated),
             None,
-            )
+        ) {
-            .map_err(|e| {
+            Ok(m) => m,
-                libc::close(dup); // failed import does not consume the fd
+            Err(e) => {
-                anyhow!("import dmabuf memory: {e}")
+                libc::close(raw); // failed import does not consume the fd
-            })?;
+                self.device.destroy_buffer(buffer, None);
-        self.device
+                return Err(anyhow!("import dmabuf memory: {e}"));
-            .bind_buffer_memory(buffer, memory, 0)
+            }
-            .context("bind import memory")?;
+        };
+        if let Err(e) = self.device.bind_buffer_memory(buffer, memory, 0) {
+            // `memory` owns the imported fd — freeing it releases the fd too.
+            self.device.free_memory(memory, None);
+            self.device.destroy_buffer(buffer, None);
+            return Err(e).context("bind import memory");
+        }
         self.src_cache.insert(
             fd,
             SrcBuf {
@@ -263,11 +356,11 @@ impl VkBridge {
         if self.dst.as_ref().is_some_and(|d| d.size >= size) {
             return Ok(());
         }
-        if let Some(old) = self.dst.take() {
+        // Build the replacement FULLY before retiring the old one. Previously the old dst was
-            self.device.destroy_buffer(old.buffer, None);
+        // destroyed and `self.dst` nulled up front, so a failed rebuild both dropped the working
-            self.device.free_memory(old.memory, None);
+        // buffer AND leaked every object the partial rebuild created (`buffer`/`memory` are raw ash
-            // old.cuda drops its mapping with it
+        // handles with no Drop, and `VkBridge::drop` only frees the live `self.dst`). Now every
-        }
+        // fallible step unwinds locally, and the swap happens only on full success.
         let mut ext_info = vk::ExternalMemoryBufferCreateInfo::default()
             .handle_types(vk::ExternalMemoryHandleTypeFlags::OPAQUE_FD);
         let buffer = self
@@ -285,35 +378,63 @@ impl VkBridge {
             .context("create export buffer")?;
         let reqs = self.device.get_buffer_memory_requirements(buffer);
         let mem_type =
-            self.memory_type(reqs.memory_type_bits, vk::MemoryPropertyFlags::DEVICE_LOCAL)?;
+            match self.memory_type(reqs.memory_type_bits, vk::MemoryPropertyFlags::DEVICE_LOCAL) {
+                Ok(t) => t,
+                Err(e) => {
+                    self.device.destroy_buffer(buffer, None);
+                    return Err(e);
+                }
+            };
         let mut export = vk::ExportMemoryAllocateInfo::default()
             .handle_types(vk::ExternalMemoryHandleTypeFlags::OPAQUE_FD);
         let mut dedicated = vk::MemoryDedicatedAllocateInfo::default().buffer(buffer);
-        let memory = self
+        let memory = match self.device.allocate_memory(
-            .device
-            .allocate_memory(
             &vk::MemoryAllocateInfo::default()
                 .allocation_size(reqs.size)
                 .memory_type_index(mem_type)
                 .push_next(&mut export)
                 .push_next(&mut dedicated),
             None,
-            )
+        ) {
-            .context("allocate exportable memory")?;
+            Ok(m) => m,
-        self.device
+            Err(e) => {
-            .bind_buffer_memory(buffer, memory, 0)
+                self.device.destroy_buffer(buffer, None);
-            .context("bind export memory")?;
+                return Err(e).context("allocate exportable memory");
-        let opaque_fd = self
+            }
-            .ext_fd
+        };
-            .get_memory_fd(
+        if let Err(e) = self.device.bind_buffer_memory(buffer, memory, 0) {
+            self.device.free_memory(memory, None);
+            self.device.destroy_buffer(buffer, None);
+            return Err(e).context("bind export memory");
+        }
+        let opaque_fd = match self.ext_fd.get_memory_fd(
             &vk::MemoryGetFdInfoKHR::default()
                 .memory(memory)
                 .handle_type(vk::ExternalMemoryHandleTypeFlags::OPAQUE_FD),
-            )
+        ) {
-            .context("vkGetMemoryFdKHR")?;
+            Ok(f) => f,
+            Err(e) => {
+                self.device.free_memory(memory, None);
+                self.device.destroy_buffer(buffer, None);
+                return Err(e).context("vkGetMemoryFdKHR");
+            }
+        };
         // CUDA imports (and on success owns) the exported fd. Size must match the allocation.
-        let cuda = cuda::ExternalDmabuf::import_owned_fd(opaque_fd, reqs.size)
+        // `import_owned_fd` closes `opaque_fd` on its own failure, so only the Vulkan objects unwind.
-            .context("cuImportExternalMemory(OPAQUE_FD from Vulkan)")?;
+        let cuda = match cuda::ExternalDmabuf::import_owned_fd(opaque_fd, reqs.size) {
+            Ok(c) => c,
+            Err(e) => {
+                self.device.free_memory(memory, None);
+                self.device.destroy_buffer(buffer, None);
+                return Err(e).context("cuImportExternalMemory(OPAQUE_FD from Vulkan)");
+            }
+        };
+        // Full success: retire the previous buffer now, then publish the new one.
+        if let Some(old) = self.dst.take() {
+            self.device.destroy_buffer(old.buffer, None);
+            self.device.free_memory(old.memory, None);
+            // old.cuda drops its mapping with it
+        }
         tracing::info!(size, "Vulkan→CUDA exportable staging buffer ready");
         self.dst = Some(DstBuf {
             buffer,
@@ -544,9 +665,19 @@ impl VkBridge {
             self.device
                 .queue_submit(self.queue, &[submit], self.fence)
                 .context("queue submit")?;
-            self.device
+            // Exception-safe wait: a TIMEOUT/DEVICE_LOST must not `?` out with the submission still
+            // executing — `self.cmd` and `self.fence` are reused every frame, and the caller retries
+            // on the SAME bridge (and `ensure_dst` later destroys `dst.buffer` assuming no in-flight
+            // work references it). Drain the GPU and reset the fence before propagating so the shared
+            // cmd/fence return clean.
+            if let Err(e) = self
+                .device
                 .wait_for_fences(&[self.fence], true, 1_000_000_000)
-                .context("fence wait")?;
+            {
+                let _ = self.device.device_wait_idle();
+                let _ = self.device.reset_fences(&[self.fence]);
+                return Err(e).context("fence wait");
+            }
             self.device
                 .reset_fences(&[self.fence])
                 .context("reset fence")?;
@@ -639,9 +770,19 @@ impl VkBridge {
             self.device
                 .queue_submit(self.queue, &[submit], self.fence)
                 .context("queue submit")?;
-            self.device
+            // Exception-safe wait: a TIMEOUT/DEVICE_LOST must not `?` out with the submission still
+            // executing — `self.cmd` and `self.fence` are reused every frame, and the caller retries
+            // on the SAME bridge (and `ensure_dst` later destroys `dst.buffer` assuming no in-flight
+            // work references it). Drain the GPU and reset the fence before propagating so the shared
+            // cmd/fence return clean.
+            if let Err(e) = self
+                .device
                 .wait_for_fences(&[self.fence], true, 1_000_000_000)
-                .context("fence wait")?;
+            {
+                let _ = self.device.device_wait_idle();
+                let _ = self.device.reset_fences(&[self.fence]);
+                return Err(e).context("fence wait");
+            }
             self.device
                 .reset_fences(&[self.fence])
                 .context("reset fence")?;

crates/punktfunk-core/build.rs

@@ -10,7 +10,6 @@ fn main() {
     println!("cargo:rerun-if-changed=src/abi.rs");
     println!("cargo:rerun-if-changed=src/config.rs");
     println!("cargo:rerun-if-changed=src/input.rs");
-    println!("cargo:rerun-if-changed=src/client.rs");
     println!("cargo:rerun-if-changed=src/error.rs");
     println!("cargo:rerun-if-changed=cbindgen.toml");
 

crates/punktfunk-core/src/abi.rs

@@ -78,6 +78,11 @@ impl PunktfunkConfig {
             u8::try_from(self.fec_percent).map_err(|_| PunktfunkStatus::InvalidArg)?;
         let max_data_per_block =
             u16::try_from(self.max_data_per_block).map_err(|_| PunktfunkStatus::InvalidArg)?;
+        // The one narrowing here that differs by target width: on 32-bit (armeabi-v7a) an
+        // `as usize` silently truncates a >4 GiB value to a plausible-looking residue that
+        // passes validate() — reject it instead, like every narrowing above.
+        let max_frame_bytes =
+            usize::try_from(self.max_frame_bytes).map_err(|_| PunktfunkStatus::InvalidArg)?;
         let cfg = Config {
             role,
             phase,
@@ -87,7 +92,7 @@ impl PunktfunkConfig {
                 max_data_per_block,
             },
             shard_payload: self.shard_payload as usize,
-            max_frame_bytes: self.max_frame_bytes as usize,
+            max_frame_bytes,
             encrypt: self.encrypt != 0,
             key: self.key,
             salt: self.salt,
@@ -125,6 +130,12 @@ pub struct PunktfunkFrame {
     pub frame_index: u32,
     pub pts_ns: u64,
     pub flags: u32,
+    /// Wall-clock reassembly-completion instant (ns since the Unix epoch, CLOCK_REALTIME — the
+    /// clock `pts_ns` and the skew handshake use). THIS is the receipt stamp for latency math:
+    /// a stamp the embedder takes itself at the poll return additionally contains the
+    /// pre-decode hand-off queue wait, so a client-side standing backlog would masquerade as
+    /// network latency (ABI v9 — the 2026-07 two-pair standing-latency investigation).
+    pub received_ns: u64,
 }
 
 /// Snapshot of session counters.
@@ -391,6 +402,7 @@ pub unsafe extern "C" fn punktfunk_client_poll_frame(
                         frame_index: f.frame_index,
                         pts_ns: f.pts_ns,
                         flags: f.flags,
+                        received_ns: f.received_ns,
                     };
                 }
                 PunktfunkStatus::Ok
@@ -456,24 +468,32 @@ pub unsafe extern "C" fn punktfunk_set_input_callback(
 #[no_mangle]
 pub unsafe extern "C" fn punktfunk_host_poll_input(s: *mut PunktfunkSession) -> i32 {
     let r = std::panic::catch_unwind(AssertUnwindSafe(|| {
+        let mut count = 0i32;
+        loop {
+            // Narrow scope: re-derive the handle and pull ONE event, then drop the borrow
+            // before dispatching. The callback may legally re-enter `punktfunk_*` on this
+            // handle (get_stats, send_input, clearing the callback) — with a `&mut` held
+            // across the call that re-entry aliased it (UB under noalias). Re-reading
+            // `input_cb` per iteration also makes a mid-drain
+            // `punktfunk_set_input_callback(s, NULL, NULL)` take effect immediately instead
+            // of firing the cleared callback for the queued remainder. (Freeing the session
+            // from inside the callback remains forbidden, as on every entry point.)
+            let (ev, cb) = {
                 let s = match unsafe { s.as_mut() } {
                     Some(s) => s,
                     None => return PunktfunkStatus::NullPointer as i32,
                 };
-        let cb = s.input_cb;
-        let mut count = 0i32;
-        loop {
                 match s.inner.poll_input() {
-                Ok(Some(ev)) => {
+                    Ok(Some(ev)) => (ev, s.input_cb),
+                    Ok(None) => break,
+                    Err(e) => return e.status() as i32,
+                }
+            };
             if let Some((cb, user)) = cb {
                 cb(&ev as *const InputEvent, user);
             }
             count += 1;
         }
-                Ok(None) => break,
-                Err(e) => return e.status() as i32,
-            }
-        }
         count
     }));
     r.unwrap_or(PunktfunkStatus::Panic as i32)
@@ -878,8 +898,8 @@ pub const PUNKTFUNK_GAMEPAD_AUTO: u32 = 0;
 /// uinput X-Box 360 pad (the universal default — every game speaks XInput).
 pub const PUNKTFUNK_GAMEPAD_XBOX360: u32 = 1;
 /// UHID DualSense (kernel `hid-playstation`): adaptive triggers, lightbar, touchpad, motion —
-/// feedback arrives on the HID-output plane ([`punktfunk_connection_next_hidout`]). Honored
+/// feedback arrives on the HID-output plane ([`punktfunk_connection_next_hidout`]). Honored on
-/// only where available (Linux hosts); otherwise the host falls back to X-Box 360.
+/// Linux (UHID) and Windows (UMDF minidriver) hosts; otherwise the host falls back to X-Box 360.
 pub const PUNKTFUNK_GAMEPAD_DUALSENSE: u32 = 2;
 /// uinput X-Box One / Series pad — the X-Box 360 backend with the One/Series USB identity, so
 /// games show One/Series glyphs. XInput-identical to `XBOX360` otherwise (no game-visible gain;
@@ -888,8 +908,8 @@ pub const PUNKTFUNK_GAMEPAD_DUALSENSE: u32 = 2;
 pub const PUNKTFUNK_GAMEPAD_XBOXONE: u32 = 3;
 /// UHID DualShock 4 (kernel `hid-playstation` ≥ 6.2): lightbar, touchpad, motion, rumble — the
 /// touchpad/motion arrive over the rich-input plane and lightbar over the HID-output plane, like
-/// DualSense (minus adaptive triggers / player LEDs / mute). Honored only where available (Linux
+/// DualSense (minus adaptive triggers / player LEDs / mute). Honored on Linux (UHID) and Windows
-/// hosts); otherwise the host falls back to X-Box 360.
+/// (UMDF minidriver) hosts; otherwise the host falls back to X-Box 360.
 pub const PUNKTFUNK_GAMEPAD_DUALSHOCK4: u32 = 4;
 /// UHID classic Steam Controller (Valve `28DE:1102`, kernel `hid-steam`): one stick + dual
 /// trackpads + two grip paddles. Honored only where available (Linux hosts); else Xbox 360.
@@ -899,10 +919,12 @@ pub const PUNKTFUNK_GAMEPAD_STEAMCONTROLLER: u32 = 5;
 /// host. Honored on Linux AND Windows hosts; else folds to X-Box 360.
 pub const PUNKTFUNK_GAMEPAD_STEAMDECK: u32 = 6;
 /// DualSense Edge (Sony `054C:0DF2`): the DualSense plus two back buttons + two Fn buttons, so a
-/// client's back paddles land on native slots. Folds to `DUALSENSE` until its backend lands.
+/// client's back paddles land on native slots. Honored on Linux (UHID `hid-playstation`) and
+/// Windows (UMDF) hosts; otherwise the host falls back to X-Box 360.
 pub const PUNKTFUNK_GAMEPAD_DUALSENSEEDGE: u32 = 7;
 /// Nintendo Switch Pro Controller (Nintendo `057E:2009`, kernel `hid-nintendo`): Nintendo glyphs +
-/// positional layout, gyro/accel, HD rumble. Folds to `XBOX360` until its backend lands.
+/// positional layout, gyro/accel, HD rumble. Honored only where available (Linux hosts, UHID
+/// `hid-nintendo`); otherwise the host falls back to X-Box 360.
 pub const PUNKTFUNK_GAMEPAD_SWITCHPRO: u32 = 8;
 /// New Steam Controller (2026, Valve `28DE:1302`) passed through AS-IS: the host mirrors the
 /// client's raw Triton input reports out of a virtual SC2 with the real identity, and Steam's
@@ -1744,6 +1766,7 @@ pub unsafe extern "C" fn punktfunk_connection_next_au(
                         frame_index: f.frame_index,
                         pts_ns: f.pts_ns,
                         flags: f.flags,
+                        received_ns: f.received_ns,
                     };
                 }
                 PunktfunkStatus::Ok
@@ -1906,6 +1929,13 @@ pub unsafe extern "C" fn punktfunk_connection_next_audio_pcm(
         }
         let AudioPcmState { decoder, pcm } = &mut *state;
         let dec = decoder.as_mut().unwrap();
+        // A header-only datagram (DTX silence — a legal wire form) must be SKIPPED, not
+        // decoded: `decode_float` treats an empty payload as a loss and synthesizes a full
+        // 120 ms of concealment for a ~5 ms slot, growing the playout ring without bound.
+        // Mirrors the host mic pump's guard; the sink underruns to silence on its own.
+        if pkt.data.is_empty() {
+            return PunktfunkStatus::NoFrame;
+        }
         // `decode_float` divides the output buffer length by the channel count to get the
         // per-channel capacity; an empty payload requests packet-loss concealment.
         match dec.decode_float(&pkt.data, pcm, false) {
@@ -2956,7 +2986,14 @@ pub unsafe extern "C" fn punktfunk_connection_next_clipboard(
                 unsafe { *out = out_ev };
                 PunktfunkStatus::Ok
             }
-            Err(e) => e.status(),
+            Err(e) => {
+                // Release the parked payload once the embedder polls past it: clipboard
+                // traffic is sporadic, so without this a one-off 50 MiB paste stays resident
+                // for the rest of the session (there is no other release entry point). The
+                // borrow contract already says `out` data is valid only until the next call.
+                *c.last_clip.lock().unwrap() = None;
+                e.status()
+            }
         }
     })
 }
@@ -3046,6 +3083,35 @@ pub unsafe extern "C" fn punktfunk_connection_clock_offset_ns(
     })
 }
 
+/// The **live** host↔client wall-clock offset (nanoseconds, host minus client): the
+/// connect-time estimate of [`punktfunk_connection_clock_offset_ns`], updated by every applied
+/// mid-stream clock re-sync. Ongoing latency math (per-frame `received − pts` splits, the
+/// glass-to-glass meter) must use this one — after a wall-clock step/slew the frozen
+/// connect-time value reads tens of milliseconds wrong for the rest of the session, while the
+/// core itself has already re-synced. Same clock contract as the connect-time getter.
+///
+/// # Safety
+/// `c` is a valid connection handle; `offset_ns` is writable (NULL is skipped).
+#[cfg(feature = "quic")]
+#[no_mangle]
+pub unsafe extern "C" fn punktfunk_connection_clock_offset_now_ns(
+    c: *const PunktfunkConnection,
+    offset_ns: *mut i64,
+) -> PunktfunkStatus {
+    guard(|| {
+        let c = match unsafe { c.as_ref() } {
+            Some(c) => c,
+            None => return PunktfunkStatus::NullPointer,
+        };
+        unsafe {
+            if !offset_ns.is_null() {
+                *offset_ns = c.inner.clock_offset_now_ns();
+            }
+        }
+        PunktfunkStatus::Ok
+    })
+}
+
 /// Ask the host to switch the live session to `width`x`height`@`refresh_hz` without
 /// reconnecting (window resized, refresh changed). Non-blocking enqueue: on acceptance the
 /// stream continues at the new mode — the first new-mode access unit is an IDR with
@@ -3185,6 +3251,11 @@ pub unsafe extern "C" fn punktfunk_connection_frames_dropped(
     out: *mut u64,
 ) -> PunktfunkStatus {
     guard(|| {
+        // The header promises "writes 0 on a NULL connection" — honor it BEFORE the handle
+        // check, so an embedder that skips the status never reads an uninitialized slot.
+        if !out.is_null() {
+            unsafe { *out = 0 };
+        }
         let c = match unsafe { c.as_ref() } {
             Some(c) => c,
             None => return PunktfunkStatus::NullPointer,
@@ -3242,6 +3313,11 @@ pub unsafe extern "C" fn punktfunk_connection_wants_decode_latency(
     out: *mut bool,
 ) -> PunktfunkStatus {
     guard(|| {
+        // The header promises "writes 0 on a NULL connection" — honor it BEFORE the handle
+        // check: an uninitialized byte is not even a valid C++/Swift bool to read.
+        if !out.is_null() {
+            unsafe { *out = false };
+        }
         let c = match unsafe { c.as_ref() } {
             Some(c) => c,
             None => return PunktfunkStatus::NullPointer,

crates/punktfunk-core/src/client/frame_channel.rs

@@ -73,6 +73,142 @@ pub(crate) const NOOP_CLOCK_FLUSHES_TO_DISARM: u32 = 2;
 /// FIRST no-op clock flush — the moment a step is actually suspected.
 pub(crate) const CLOCK_RESYNC_INTERVAL: Duration = Duration::from_secs(60);
 
+/// Standing-latency bleed (the 2026-07 two-pair investigation): how far above the session's own
+/// one-way-delay floor a report window's MINIMUM must sit to count as a standing elevation. The
+/// jump-to-live detectors above deliberately ignore anything below ~6 frames / 400 ms, so a
+/// small standing state — a sub-frame kernel/reassembly backlog, or a stale clock offset after a
+/// wall-clock step — is carried forever and reads as permanent extra "network" latency. 10 ms
+/// sits above skew-handshake error + normal LAN jitter, and below a single 60 fps frame period,
+/// so the observed one-frame plateau (~17 ms) trips it while a healthy stream cannot.
+pub(crate) const STANDING_LAT_THRESH_NS: i128 = 10_000_000;
+
+/// Consecutive elevated report windows (~750 ms each) before the bleed escalates — ~4.5 s of a
+/// continuously standing, loss-free elevation. Windows with any loss reset the run: loss means
+/// genuine congestion, which the FEC/ABR machinery owns, not this detector.
+pub(crate) const STANDING_LAT_WINDOWS: u32 = 6;
+
+/// Per-session cap on flush+keyframe bleeds. A standing state that survives a clock re-sync AND
+/// this many local flushes is not local and not clock — the path latency itself changed; the
+/// detector disarms with a warning instead of paying a recovery keyframe every few seconds.
+pub(crate) const STANDING_LAT_MAX_BLEEDS: u32 = 3;
+
+/// What the standing-latency detector asks the pump to do this window (see [`StandingLatency`]).
+#[derive(Debug, PartialEq, Eq)]
+pub(crate) enum StandingLatAction {
+    None,
+    /// First escalation: ask for a mid-stream clock re-sync — free, and a stale offset from a
+    /// stepped/slewed wall clock produces exactly this signature (an applied re-sync re-bases
+    /// the floor via the pump's `clock_gen` watch, clearing the elevation if that was the cause).
+    Resync {
+        above_ms: i64,
+    },
+    /// The elevation survived a re-sync attempt: flush the local receive backlog + request a
+    /// keyframe (the jump-to-live action), draining a real sub-threshold standing queue. The
+    /// pump reports execution back via [`StandingLatency::bled`]; an unexecuted action simply
+    /// re-arms next window.
+    Bleed {
+        above_ms: i64,
+    },
+    /// Bleed cap reached and the elevation is back: give up and say so.
+    Disarm {
+        above_ms: i64,
+    },
+}
+
+/// Detector for a small, constant, loss-free one-way-delay elevation — the standing state the
+/// jump-to-live thresholds deliberately tolerate. Tracks the session's OWD floor (minimum of
+/// report-window minimums since start / last re-base) and escalates when windows sit
+/// persistently above it: re-sync first, then a bounded number of flush+keyframe bleeds, then
+/// disarm. Pure state machine (no clocks, no I/O) so the escalation ladder is unit-testable.
+pub(crate) struct StandingLatency {
+    /// Lowest window-minimum OWD seen since session start / last [`rebase`](Self::rebase).
+    floor_ns: Option<i128>,
+    /// Minimum per-frame OWD this report window; `None` = no frames yet.
+    window_min_ns: Option<i128>,
+    /// Consecutive elevated windows.
+    run: u32,
+    /// The current elevation already got its re-sync request — next escalation is a bleed.
+    resync_tried: bool,
+    bleeds: u32,
+    disarmed: bool,
+}
+
+impl StandingLatency {
+    pub(crate) fn new() -> Self {
+        StandingLatency {
+            floor_ns: None,
+            window_min_ns: None,
+            run: 0,
+            resync_tried: false,
+            bleeds: 0,
+            disarmed: false,
+        }
+    }
+
+    /// Feed one frame's skew-corrected OWD (capture→reassembly-complete, ns). Caller gates on a
+    /// live clock offset and plausibility (0 < owd < 10 s), like the ABR OWD signal.
+    pub(crate) fn note_frame(&mut self, owd_ns: i128) {
+        self.window_min_ns = Some(match self.window_min_ns {
+            Some(m) => m.min(owd_ns),
+            None => owd_ns,
+        });
+    }
+
+    /// Close a report window. `loss_free` = the window carried zero loss (loss resets the run —
+    /// congestion is the FEC/ABR machinery's problem, and queues under loss are not "standing").
+    pub(crate) fn on_window(&mut self, loss_free: bool) -> StandingLatAction {
+        let Some(wmin) = self.window_min_ns.take() else {
+            return StandingLatAction::None; // no frames this window — no evidence either way
+        };
+        let floor = *self.floor_ns.get_or_insert(wmin);
+        self.floor_ns = Some(floor.min(wmin));
+        let above_ns = wmin - floor;
+        if self.disarmed {
+            return StandingLatAction::None;
+        }
+        if !loss_free || above_ns < STANDING_LAT_THRESH_NS {
+            self.run = 0;
+            if above_ns < STANDING_LAT_THRESH_NS {
+                self.resync_tried = false; // elevation cleared — a future one re-syncs first again
+            }
+            return StandingLatAction::None;
+        }
+        self.run += 1;
+        if self.run < STANDING_LAT_WINDOWS {
+            return StandingLatAction::None;
+        }
+        self.run = 0; // each escalation gets a fresh observation run
+        let above_ms = (above_ns / 1_000_000) as i64;
+        if !self.resync_tried {
+            self.resync_tried = true;
+            StandingLatAction::Resync { above_ms }
+        } else if self.bleeds < STANDING_LAT_MAX_BLEEDS {
+            StandingLatAction::Bleed { above_ms }
+        } else {
+            self.disarmed = true;
+            StandingLatAction::Disarm { above_ms }
+        }
+    }
+
+    /// The pump executed a [`StandingLatAction::Bleed`] (flush + keyframe). The floor is KEPT: a
+    /// successful bleed brings OWD back down to it (elevation clears naturally); an unsuccessful
+    /// one leaves the elevation visible so the ladder continues toward the cap.
+    pub(crate) fn bled(&mut self) {
+        self.bleeds += 1;
+        self.window_min_ns = None;
+    }
+
+    /// A mid-stream clock re-sync was APPLIED (the pump's `clock_gen` watch): every OWD reading
+    /// shifted, so the floor and any elevation measured under the old offset are meaningless —
+    /// re-learn from scratch. The bleed budget survives (it caps keyframes per session).
+    pub(crate) fn rebase(&mut self) {
+        self.floor_ns = None;
+        self.window_min_ns = None;
+        self.run = 0;
+        self.resync_tried = false;
+    }
+}
+
 /// Client decode-stage latency accumulator for the adaptive-bitrate controller's decode signal.
 /// The embedder adds one sample per decoded frame ([`NativeClient::report_decode_us`], µs from the
 /// AU leaving [`NativeClient::next_frame`] to its decoded output) and the data-plane pump drains a
@@ -191,6 +327,7 @@ mod frame_channel_tests {
             pts_ns: i as u64,
             flags: 0,
             complete: true,
+            received_ns: 0,
         }
     }
 
@@ -258,3 +395,143 @@ mod frame_channel_tests {
         assert_eq!(popped(&ch), Some(total - FRAME_QUEUE_HARD_CAP as u32));
     }
 }
+
+#[cfg(test)]
+mod standing_latency_tests {
+    use super::{
+        StandingLatAction, StandingLatency, STANDING_LAT_MAX_BLEEDS, STANDING_LAT_THRESH_NS,
+        STANDING_LAT_WINDOWS,
+    };
+
+    const FLOOR: i128 = 2_000_000; // a healthy 2 ms LAN OWD
+    const ELEVATED: i128 = FLOOR + STANDING_LAT_THRESH_NS + 7_000_000; // ~one 60fps frame above
+
+    /// Run `n` windows at `owd`, asserting every window but the last returns None; returns the
+    /// last window's action.
+    fn run_windows(d: &mut StandingLatency, owd: i128, n: u32) -> StandingLatAction {
+        for i in 0..n {
+            d.note_frame(owd);
+            let a = d.on_window(true);
+            if i + 1 < n {
+                assert_eq!(a, StandingLatAction::None, "window {i} escalated early");
+            } else {
+                return a;
+            }
+        }
+        unreachable!("n > 0 by construction");
+    }
+
+    /// Learn a clean floor: one window at the healthy OWD.
+    fn learned(d: &mut StandingLatency) {
+        d.note_frame(FLOOR);
+        assert_eq!(d.on_window(true), StandingLatAction::None);
+    }
+
+    #[test]
+    fn healthy_stream_never_escalates() {
+        let mut d = StandingLatency::new();
+        learned(&mut d);
+        // Jitter riding above the floor but under the threshold: never a run.
+        for _ in 0..(STANDING_LAT_WINDOWS * 4) {
+            d.note_frame(FLOOR + STANDING_LAT_THRESH_NS - 1);
+            assert_eq!(d.on_window(true), StandingLatAction::None);
+        }
+    }
+
+    #[test]
+    fn escalation_ladder_resync_then_bleeds_then_disarm() {
+        let mut d = StandingLatency::new();
+        learned(&mut d);
+        // First full elevated run asks for the free fix: a clock re-sync.
+        assert!(matches!(
+            run_windows(&mut d, ELEVATED, STANDING_LAT_WINDOWS),
+            StandingLatAction::Resync { .. }
+        ));
+        // Re-sync didn't help (no rebase came) — each further run is a bleed, up to the cap...
+        for _ in 0..STANDING_LAT_MAX_BLEEDS {
+            assert!(matches!(
+                run_windows(&mut d, ELEVATED, STANDING_LAT_WINDOWS),
+                StandingLatAction::Bleed { .. }
+            ));
+            d.bled();
+        }
+        // ...then the detector gives up loudly, once, and stays quiet.
+        assert!(matches!(
+            run_windows(&mut d, ELEVATED, STANDING_LAT_WINDOWS),
+            StandingLatAction::Disarm { .. }
+        ));
+        d.note_frame(ELEVATED);
+        assert_eq!(d.on_window(true), StandingLatAction::None);
+    }
+
+    #[test]
+    fn loss_windows_reset_the_run() {
+        let mut d = StandingLatency::new();
+        learned(&mut d);
+        for _ in 0..(STANDING_LAT_WINDOWS - 1) {
+            d.note_frame(ELEVATED);
+            assert_eq!(d.on_window(true), StandingLatAction::None);
+        }
+        // A lossy window means congestion, not a standing state: run resets...
+        d.note_frame(ELEVATED);
+        assert_eq!(d.on_window(false), StandingLatAction::None);
+        // ...so the ladder needs the full run again before acting.
+        assert!(matches!(
+            run_windows(&mut d, ELEVATED, STANDING_LAT_WINDOWS),
+            StandingLatAction::Resync { .. }
+        ));
+    }
+
+    #[test]
+    fn recovery_resets_the_ladder_to_resync_first() {
+        let mut d = StandingLatency::new();
+        learned(&mut d);
+        assert!(matches!(
+            run_windows(&mut d, ELEVATED, STANDING_LAT_WINDOWS),
+            StandingLatAction::Resync { .. }
+        ));
+        // The elevation clears on its own (e.g. the successful bleed case, or transient): the
+        // next episode starts back at the free escalation, not at a bleed.
+        d.note_frame(FLOOR);
+        assert_eq!(d.on_window(true), StandingLatAction::None);
+        assert!(matches!(
+            run_windows(&mut d, ELEVATED, STANDING_LAT_WINDOWS),
+            StandingLatAction::Resync { .. }
+        ));
+    }
+
+    #[test]
+    fn applied_resync_rebases_and_clears_a_stale_offset_elevation() {
+        let mut d = StandingLatency::new();
+        learned(&mut d);
+        assert!(matches!(
+            run_windows(&mut d, ELEVATED, STANDING_LAT_WINDOWS),
+            StandingLatAction::Resync { .. }
+        ));
+        // The re-sync APPLIES (pump sees clock_gen move) → rebase. The corrected offset brings
+        // OWD readings back to truth; the floor re-learns and nothing ever escalates to a bleed.
+        d.rebase();
+        for _ in 0..(STANDING_LAT_WINDOWS * 2) {
+            d.note_frame(FLOOR);
+            assert_eq!(d.on_window(true), StandingLatAction::None);
+        }
+    }
+
+    #[test]
+    fn empty_windows_are_no_evidence() {
+        let mut d = StandingLatency::new();
+        learned(&mut d);
+        for _ in 0..(STANDING_LAT_WINDOWS - 1) {
+            d.note_frame(ELEVATED);
+            assert_eq!(d.on_window(true), StandingLatAction::None);
+        }
+        // A frameless window (paused stream) neither advances nor resets the run...
+        assert_eq!(d.on_window(true), StandingLatAction::None);
+        // ...so one more elevated window completes it.
+        d.note_frame(ELEVATED);
+        assert!(matches!(
+            d.on_window(true),
+            StandingLatAction::Resync { .. }
+        ));
+    }
+}

crates/punktfunk-core/src/client/mod.rs

@@ -425,6 +425,12 @@ impl NativeClient {
             Ok(Ok(t)) => t,
             Ok(Err(e)) => return Err(e),
             Err(_) => {
+                // A connect we already reported as failed must not leave a lingering host
+                // session if the handshake lands late: mark it a deliberate QUIT (not a plain
+                // drop / close code 0) so the worker's close tells the host to tear down now
+                // instead of holding the session (and its virtual display) for a reconnect
+                // that will never come.
+                quit.store(true, Ordering::SeqCst);
                 shutdown.store(true, Ordering::SeqCst);
                 return Err(PunktfunkError::Timeout);
             }
@@ -456,9 +462,14 @@ impl NativeClient {
             hot_tids,
             clock_offset,
             decode_lat,
-            // The controller arms exactly when the pump does (see `abr::BitrateController::new`
+            // The controller arms exactly when the pump does — all three terms, not two: Automatic
-            // below): Automatic (the user asked for bitrate 0) and not a rate-pinned PyroWave stream.
+            // (the user asked for bitrate 0), not a rate-pinned PyroWave stream, AND the host
-            wants_decode: bitrate_kbps == 0 && negotiated.codec != crate::quic::CODEC_PYROWAVE,
+            // echoed the rate it actually configured. Dropping the last term made this
+            // over-advertise against an old host that reports no rate, so an embedder fed decode
+            // latency to a controller that never runs.
+            wants_decode: bitrate_kbps == 0
+                && negotiated.codec != crate::quic::CODEC_PYROWAVE
+                && negotiated.bitrate_kbps > 0,
             mode: mode_slot,
             host_fingerprint: negotiated.host_fingerprint,
             resolved_compositor: negotiated.compositor,
@@ -703,14 +714,23 @@ impl NativeClient {
         // Reset the accumulator so a fresh run doesn't blend into the previous one.
         *self.probe.lock().unwrap() = ProbeState {
             active: true,
+            duration_ms,
             ..Default::default()
         };
-        self.ctrl_tx
+        let sent = self
+            .ctrl_tx
             .try_send(CtrlRequest::Probe(ProbeRequest {
                 target_kbps,
                 duration_ms,
             }))
-            .map_err(|_| PunktfunkError::Closed)
+            .map_err(|_| PunktfunkError::Closed);
+        if sent.is_err() {
+            // Nothing was asked of the host, so nothing will ever answer. Leaving `active` latched
+            // would suppress the pump's entire report tick for the rest of the session (the pump
+            // mirrors the startup path's rollback at the same point).
+            self.probe.lock().unwrap().active = false;
+        }
+        sent
     }
 
     /// Read the current speed-test measurement (partial until `done`, final once the host's
@@ -745,7 +765,9 @@ impl NativeClient {
             0.0
         } as f32;
         // Host-side drop: what the send buffer couldn't even accept (the host-side ceiling).
-        let offered_wire = p.host_wire_packets + p.host_send_dropped;
+        // Saturating: both counters arrive verbatim off the wire (same discipline as the
+        // saturating_sub/mul above — a hostile sum must not overflow-panic a debug build).
+        let offered_wire = p.host_wire_packets.saturating_add(p.host_send_dropped);
         let host_drop_pct = if offered_wire > 0 {
             p.host_send_dropped as f64 / offered_wire as f64 * 100.0
         } else {

crates/punktfunk-core/src/client/probe.rs

@@ -32,6 +32,11 @@ pub(crate) struct ProbeState {
     pub(crate) host_duration_ms: u32,
     /// The host's `ProbeResult` arrived → the measurement is final.
     pub(crate) done: bool,
+    /// The requested burst length, so the pump can arm a watchdog for a host that never answers.
+    /// Without one, an ignored `ProbeRequest` latches `active` forever and the pump's whole report
+    /// tick — loss reports, the ABR window feed, the standing-latency ladder and pending clock
+    /// re-syncs — stays suppressed for the rest of the session.
+    pub(crate) duration_ms: u32,
 }
 
 /// A finished/partial speed-test measurement, returned by [`NativeClient::probe_result`].

crates/punktfunk-core/src/client/pump/control_task.rs

@@ -0,0 +1,181 @@
+//! Control task: the handshake stream stays open for mid-stream renegotiation + speed tests.
+//! Outbound requests (mode switch, probe) and inbound replies (Reconfigured, ProbeResult) are
+//! multiplexed with `select!`; a single outbound channel (`ctrl_rx`) keeps one writer so the
+//! two `&mut ctrl_send` borrows don't collide across branches.
+
+use super::super::*;
+use super::*;
+
+pub(super) struct ControlTask {
+    pub(super) ctrl_rx: tokio::sync::mpsc::Receiver<CtrlRequest>,
+    pub(super) ctrl_send: quinn::SendStream,
+    pub(super) ctrl_recv: io::MsgReader,
+    /// `None` = no connect-time skew handshake (old host) — clock re-sync stays off.
+    pub(super) clock_rtt_ns: Option<u64>,
+    pub(super) mode_slot: Arc<Mutex<Mode>>,
+    pub(super) probe: Arc<Mutex<ProbeState>>,
+    /// The latest host `BitrateChanged` ack, drained by the pump's ABR on its report tick.
+    pub(super) bitrate_ack: Arc<Mutex<Option<u32>>>,
+    pub(super) clock_offset: Arc<std::sync::atomic::AtomicI64>,
+    pub(super) clock_gen: Arc<AtomicU32>,
+    /// Clipboard metadata events (ClipState/ClipOffer) feed the same event plane the
+    /// clipboard task uses for fetch data.
+    pub(super) clip_event_tx: std::sync::mpsc::SyncSender<ClipEventCore>,
+}
+
+impl ControlTask {
+    pub(super) async fn run(self) {
+        let ControlTask {
+            mut ctrl_rx,
+            mut ctrl_send,
+            mut ctrl_recv,
+            clock_rtt_ns,
+            mode_slot,
+            probe,
+            bitrate_ack,
+            clock_offset,
+            clock_gen,
+            clip_event_tx,
+        } = self;
+        // Mid-stream clock re-sync (see [`ClockResync`]): a batch runs every
+        // CLOCK_RESYNC_INTERVAL and whenever the pump asks (CtrlRequest::ClockResync after
+        // its first no-op clock flush). Echoes interleave with the other control replies in
+        // the read arm below; only when the host answered the connect-time handshake — an
+        // old host would just eat the probes.
+        let mut resync = ClockResync::new();
+        let mut resync_tick = tokio::time::interval_at(
+            tokio::time::Instant::now() + CLOCK_RESYNC_INTERVAL,
+            CLOCK_RESYNC_INTERVAL,
+        );
+        resync_tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
+        loop {
+            tokio::select! {
+                req = ctrl_rx.recv() => {
+                    let Some(req) = req else { break }; // client dropped
+                    let bytes = match req {
+                        CtrlRequest::Mode(m) => Reconfigure { mode: m }.encode(),
+                        CtrlRequest::Probe(p) => p.encode(),
+                        CtrlRequest::Keyframe => RequestKeyframe.encode(),
+                        CtrlRequest::Rfi(r) => r.encode(),
+                        CtrlRequest::Loss(r) => r.encode(),
+                        CtrlRequest::SetBitrate(k) => SetBitrate { bitrate_kbps: k }.encode(),
+                        CtrlRequest::ClockResync => {
+                            if clock_rtt_ns.is_none() {
+                                continue; // no connect-time handshake — host can't answer
+                            }
+                            resync.begin(wall_clock_ns()).encode()
+                        }
+                        CtrlRequest::ClipControl(c) => c.encode(),
+                        CtrlRequest::ClipOffer(o) => o.encode(),
+                    };
+                    if io::write_msg(&mut ctrl_send, &bytes).await.is_err() {
+                        break;
+                    }
+                }
+                _ = resync_tick.tick(), if clock_rtt_ns.is_some() => {
+                    let probe = resync.begin(wall_clock_ns());
+                    if io::write_msg(&mut ctrl_send, &probe.encode()).await.is_err() {
+                        break;
+                    }
+                }
+                msg = ctrl_recv.read_msg() => {
+                    let Ok(msg) = msg else { break }; // stream closed
+                    if let Ok(ack) = Reconfigured::decode(&msg) {
+                        if ack.accepted {
+                            *mode_slot.lock().unwrap() = ack.mode;
+                            tracing::info!(mode = ?ack.mode, "host accepted mode switch");
+                        } else {
+                            tracing::warn!(active = ?ack.mode, "host rejected mode switch");
+                        }
+                    } else if let Ok(result) = ProbeResult::decode(&msg) {
+                        let mut p = probe.lock().unwrap();
+                        // Freeze the delivered figures now (the burst is done), before resumed
+                        // video can inflate the packet counters.
+                        let base_p = p.base_packets.unwrap_or(p.rx_packets_now);
+                        let base_b = p.base_bytes.unwrap_or(p.rx_bytes_now);
+                        p.delivered_packets = p.rx_packets_now.saturating_sub(base_p);
+                        p.delivered_bytes = p.rx_bytes_now.saturating_sub(base_b);
+                        p.host_goodput_bytes = result.bytes_sent;
+                        p.host_au = result.packets_sent;
+                        p.host_wire_packets = result.wire_packets_sent;
+                        p.host_send_dropped = result.send_dropped;
+                        p.host_duration_ms = result.duration_ms;
+                        p.done = true;
+                        p.active = false; // burst over — the pump stops mirroring counters
+                        tracing::info!(
+                            host_goodput_bytes = result.bytes_sent,
+                            wire_packets_sent = result.wire_packets_sent,
+                            send_dropped = result.send_dropped,
+                            duration_ms = result.duration_ms,
+                            delivered_packets = p.delivered_packets,
+                            "speed-test probe result"
+                        );
+                    } else if let Ok(ack) = BitrateChanged::decode(&msg) {
+                        // Adaptive bitrate: the host's clamp is authoritative — park it for
+                        // the pump's controller (which also reads any ack as "this host
+                        // renegotiates", arming further steps).
+                        tracing::info!(
+                            kbps = ack.bitrate_kbps,
+                            "host re-targeted encoder bitrate"
+                        );
+                        *bitrate_ack.lock().unwrap() = Some(ack.bitrate_kbps);
+                    } else if let Ok(echo) = ClockEcho::decode(&msg) {
+                        match resync.on_echo(&echo, wall_clock_ns()) {
+                            ResyncStep::Probe(p) => {
+                                if io::write_msg(&mut ctrl_send, &p.encode()).await.is_err() {
+                                    break;
+                                }
+                            }
+                            ResyncStep::Done { offset_ns, rtt_ns } => {
+                                // Never let a congested window bias the offset (frames read
+                                // late exactly then) — keep the old estimate and let the next
+                                // periodic batch try again.
+                                if accept_resync(rtt_ns, clock_rtt_ns.unwrap_or(0)) {
+                                    // info, not debug: ≤1/min, and it is THE forensic
+                                    // trail for a stale-offset (stepped/slewed wall clock)
+                                    // latency plateau — the 2026-07 two-pair investigation
+                                    // had to reconstruct this blind.
+                                    tracing::info!(
+                                        offset_ns,
+                                        rtt_us = rtt_ns / 1000,
+                                        "mid-stream clock re-sync applied"
+                                    );
+                                    clock_offset.store(offset_ns, Ordering::Relaxed);
+                                    clock_gen.fetch_add(1, Ordering::Relaxed);
+                                } else {
+                                    tracing::info!(
+                                        rtt_us = rtt_ns / 1000,
+                                        "clock re-sync batch discarded — RTT above the \
+                                         connect-time baseline (congested window)"
+                                    );
+                                }
+                            }
+                            ResyncStep::Idle => {}
+                        }
+                    } else if let Ok(state) = ClipState::decode(&msg) {
+                        // Host ack / policy / backend update for the toggle UI (try_send: a
+                        // lagging embedder drops the newest — a stale toggle heals on the next).
+                        let _ = clip_event_tx.try_send(ClipEventCore::State {
+                            enabled: state.enabled,
+                            policy: state.policy,
+                            reason: state.reason,
+                        });
+                    } else if let Ok(offer) = ClipOffer::decode(&msg) {
+                        // The host copied something: surface the lazy format list; the embedder
+                        // fetches only if a local app pastes.
+                        let _ = clip_event_tx.try_send(ClipEventCore::RemoteOffer {
+                            seq: offer.seq,
+                            kinds: offer.kinds,
+                        });
+                    } else {
+                        tracing::warn!(
+                            tag = ?msg.first(),
+                            len = msg.len(),
+                            "unknown control message — ignoring"
+                        );
+                    }
+                }
+            }
+        }
+    }
+}

crates/punktfunk-core/src/client/pump/data.rs

@@ -0,0 +1,568 @@
+//! The blocking data-plane pump: poll the session for access units, run the adaptive-FEC
+//! loss reports, the ABR controller + startup capacity probe, the jump-to-live detectors,
+//! and the standing-latency bleed, and hand frames to the embedder.
+
+use super::super::*;
+use super::*;
+
+/// Data-plane pump on a blocking thread: poll the session, hand frames to the embedder.
+/// try_send drops the newest frame when the embedder lags (freshness over completeness).
+/// Speed-test filler ([`FLAG_PROBE`]) is folded into the probe accumulator instead of the
+/// decoder queue — it isn't video.
+pub(super) struct DataPump {
+    pub(super) session: Session,
+    pub(super) frames: Arc<FrameChannel>,
+    pub(super) ctrl_tx: tokio::sync::mpsc::Sender<CtrlRequest>,
+    pub(super) shutdown: Arc<std::sync::atomic::AtomicBool>,
+    pub(super) probe: Arc<Mutex<ProbeState>>,
+    pub(super) hot_tids: Arc<Mutex<Vec<i32>>>,
+    pub(super) clock_offset: Arc<std::sync::atomic::AtomicI64>,
+    pub(super) clock_gen: Arc<AtomicU32>,
+    pub(super) decode_lat: Arc<Mutex<DecodeLatAcc>>,
+    pub(super) frames_dropped: Arc<std::sync::atomic::AtomicU64>,
+    pub(super) fec_recovered: Arc<std::sync::atomic::AtomicU64>,
+    pub(super) bitrate_ack: Arc<Mutex<Option<u32>>>,
+    /// The embedder's REQUESTED rate (0 = Automatic — the only case the ABR arms).
+    pub(super) bitrate_kbps: u32,
+    /// The rate the host actually configured (echoed in Welcome).
+    pub(super) resolved_bitrate_kbps: u32,
+    pub(super) negotiated_codec: u8,
+}
+
+impl DataPump {
+    pub(super) fn run(self) {
+        let DataPump {
+            mut session,
+            frames,
+            ctrl_tx,
+            shutdown: pump_shutdown,
+            probe: pump_probe,
+            hot_tids: pump_hot_tids,
+            clock_offset: pump_clock_offset,
+            clock_gen: pump_clock_gen,
+            decode_lat: pump_decode_lat,
+            frames_dropped,
+            fec_recovered,
+            bitrate_ack,
+            bitrate_kbps,
+            resolved_bitrate_kbps,
+            negotiated_codec,
+        } = self;
+        pin_thread_user_interactive(); // feeds the frame channel → the user-interactive video pump
+        register_hot_tid(&pump_hot_tids); // this thread does UDP receive + FEC reassembly — hint it
+                                          // Adaptive-FEC loss reporting: every ADAPT_REPORT_INTERVAL, report the loss observed over the
+                                          // window (shards FEC recovered, plus a bump if any frame went unrecoverable) so the host can
+                                          // size FEC to the link. Suppressed during a speed test (its FLAG_PROBE filler would skew it).
+        const ADAPT_REPORT_INTERVAL: Duration = Duration::from_millis(750);
+        let mut last_report = Instant::now();
+        let (
+            mut last_recovered,
+            mut last_late,
+            mut last_received,
+            mut last_dropped,
+            mut last_bytes,
+        ) = (0u64, 0u64, 0u64, 0u64, 0u64);
+        // PUNKTFUNK_PERF: per-window pump observability — the Session's receive stage split
+        // (recv / decrypt / reassemble+FEC, see `Session::take_pump_perf`) and completed-AU
+        // inter-arrival jitter. Smoothness has no metric otherwise: jump-to-live counters only
+        // fire after the stream is already seconds behind.
+        let pump_perf_on = std::env::var("PUNKTFUNK_PERF").is_ok_and(|v| v != "0");
+        let mut arrivals_us: Vec<u32> = Vec::new();
+        let mut last_arrival: Option<Instant> = None;
+        // Adaptive bitrate (see `crate::abr`): armed only when the embedder asked for Automatic
+        // (`bitrate_kbps == 0`) and the host echoed the rate it actually configured (an old host
+        // echoes 0 → controller stays permanently off). Fed once per report window with the same
+        // deltas the LossReport uses, plus the window's mean skew-corrected one-way delay, the
+        // actual delivered throughput (climb gate + proven-throughput mark), and whether a
+        // jump-to-live flush fired.
+        // PyroWave sessions PIN their rate (§4.6): AIMD descent turns wavelets to mush well
+        // above its floor, and the climb probe's VBV reasoning doesn't apply to hard
+        // per-frame CBR — controller and capacity probe stay off (0 = permanently off).
+        let rate_pinned = negotiated_codec == crate::quic::CODEC_PYROWAVE;
+        let mut abr = BitrateController::new(if bitrate_kbps == 0 && !rate_pinned {
+            resolved_bitrate_kbps
+        } else {
+            0
+        });
+        // Startup link-capacity probe (Automatic sessions): the controller's ceiling is the
+        // negotiated start rate — the conservative 20 Mbps default, historically a box Automatic
+        // could NEVER climb out of. One speed-test burst shortly after the stream settles
+        // measures what the link actually delivers; ×0.7 (headroom for FEC overhead + variance)
+        // becomes the climb ceiling and slow start does the rest. Old hosts decline (all-zero
+        // reply) or never answer (timeout clears the state so LossReports resume) — either way
+        // the ceiling stays negotiated, exactly the old behavior. PUNKTFUNK_ABR_PROBE=0 opts out.
+        const CAPACITY_PROBE_KBPS: u32 = 2_000_000;
+        const CAPACITY_PROBE_MS: u32 = 800;
+        const CAPACITY_PROBE_DELAY: Duration = Duration::from_secs(2);
+        const CAPACITY_PROBE_TIMEOUT: Duration = Duration::from_secs(6);
+        let mut capacity_probe_at: Option<Instant> = (bitrate_kbps == 0
+            && !rate_pinned
+            && resolved_bitrate_kbps > 0
+            && std::env::var("PUNKTFUNK_ABR_PROBE").map_or(true, |v| v != "0"))
+        .then(|| Instant::now() + CAPACITY_PROBE_DELAY);
+        let mut capacity_probe_deadline: Option<Instant> = None;
+        // Edge detector + watchdog for a probe of EITHER origin (the startup capacity probe or an
+        // embedder speed test via `NativeClient::request_probe`). The startup path had both built
+        // in; the embedder path had neither, so an unanswered request wedged the report tick and a
+        // finished one left the ABR window anchored before the burst.
+        let mut was_probing = false;
+        let mut probe_watchdog: Option<Instant> = None;
+        let (mut owd_sum_ns, mut owd_frames) = (0i128, 0u32);
+        let mut flush_in_window = false;
+        // Jump-to-live state (see the guard in the loop below): when the clock-based over-bound
+        // run began (`stale_since`, armed only when the skew handshake succeeded so the clocks
+        // are comparable), when the clock-free non-draining-queue run began (`standing_since`),
+        // and the last-jump instant for the shared cooldown. Wall-clock runs (T1.4), not frame
+        // counts — the detectors' sensitivity must not scale with fps or repeat cadence.
+        let mut stale_since: Option<Instant> = None;
+        let mut standing_since: Option<Instant> = None;
+        let mut last_flush: Option<Instant> = None;
+        // Clock-detector health: consecutive clock-triggered flushes that found no local backlog
+        // (see NOOP_FLUSH_DATAGRAMS). Reaching NOOP_CLOCK_FLUSHES_TO_DISARM turns the clock-based
+        // detector off (a clock step / upstream queue it can't fix) — until a mid-stream clock
+        // re-sync lands and re-arms it (`pump_clock_gen` below). The FIRST no-op flush also asks
+        // the control task for an immediate re-sync (via the report tick): the flush finding no
+        // local backlog IS the "the wall clock stepped under me" signal.
+        let mut noop_clock_flushes: u32 = 0;
+        let mut clock_detector_armed = true;
+        let mut resync_wanted = false;
+        let mut seen_clock_gen = pump_clock_gen.load(Ordering::Relaxed);
+        // Standing-latency bleed (see StandingLatency): the third detector, for the small,
+        // constant, loss-free OWD elevation the two jump-to-live detectors deliberately
+        // tolerate (< QUEUE_HIGH frames, < FLUSH_LATENCY behind) — a sub-frame standing
+        // backlog, or a stale clock offset after a wall-clock step, either of which otherwise
+        // reads as permanent extra "network" latency for the rest of the session.
+        let mut standing_lat = StandingLatency::new();
+        while !pump_shutdown.load(Ordering::SeqCst) {
+            // The live host↔client offset: re-loaded every iteration so an applied mid-stream
+            // re-sync takes effect on the very next frame's latency math.
+            let clock_offset_ns = pump_clock_offset.load(Ordering::Relaxed);
+            // An applied re-sync invalidates the staleness run measured under the OLD offset:
+            // reset the counters and re-arm the clock-based detector if a step had disarmed it.
+            let gen = pump_clock_gen.load(Ordering::Relaxed);
+            if gen != seen_clock_gen {
+                seen_clock_gen = gen;
+                stale_since = None;
+                noop_clock_flushes = 0;
+                // Every OWD reading shifted with the offset — the standing-latency floor and
+                // any elevation measured under the old one are meaningless now. If a stale
+                // offset WAS the elevation, this is also the moment it gets fixed.
+                standing_lat.rebase();
+                if !clock_detector_armed {
+                    clock_detector_armed = true;
+                    tracing::info!("clock re-sync applied — clock-based jump-to-live re-armed");
+                }
+            }
+            // Mirror the reassembler's unrecoverable-drop count for the client's keyframe-recovery
+            // loop, and (during a speed test) the packet-level receive counters for the throughput
+            // measurement. Updated every iteration (not just on a produced frame) so they stay current
+            // through a total-loss drought where no AU completes. Cheap: a few relaxed atomic loads.
+            let st = session.stats();
+            frames_dropped.store(st.frames_dropped, Ordering::Relaxed);
+            fec_recovered.store(st.fec_recovered_shards, Ordering::Relaxed);
+            let probe_active = {
+                let mut p = pump_probe.lock().unwrap();
+                if p.active && !p.done {
+                    p.rx_packets_now = st.packets_received;
+                    p.rx_bytes_now = st.bytes_received;
+                    p.base_packets.get_or_insert(st.packets_received);
+                    p.base_bytes.get_or_insert(st.bytes_received);
+                }
+                p.active && !p.done
+            };
+            // A probe just ended (either kind): rebase EVERY window anchor past the burst. Its
+            // FLAG_PROBE filler landed in `bytes_received`/`packets_received` (session.rs counts
+            // every accepted datagram) but never reached the decoder, and the report tick was
+            // suppressed for the whole burst, so `last_*` still points before it. Without this the
+            // first post-burst window reads the burst rate as `actual_kbps` and poisons the ABR's
+            // monotone proven-throughput high-water mark — which never decays — and divides the
+            // window's loss by a packet count inflated with filler.
+            if was_probing && !probe_active {
+                last_recovered = st.fec_recovered_shards;
+                last_late = st.fec_late_shards;
+                last_received = st.packets_received;
+                last_dropped = st.frames_dropped;
+                last_bytes = st.bytes_received;
+                last_report = Instant::now();
+            }
+            // Arm a watchdog on the leading edge of ANY probe, so a host that silently ignores
+            // `ProbeRequest` (an old build — anticipated, see the capacity-probe timeout below)
+            // cannot latch `active` forever and suppress the report tick for the whole session.
+            if !was_probing && probe_active {
+                let burst = Duration::from_millis(pump_probe.lock().unwrap().duration_ms as u64);
+                probe_watchdog = Some(Instant::now() + burst + CAPACITY_PROBE_TIMEOUT);
+            }
+            if !probe_active {
+                probe_watchdog = None;
+            } else if let Some(deadline) = probe_watchdog {
+                if Instant::now() >= deadline {
+                    probe_watchdog = None;
+                    pump_probe.lock().unwrap().active = false;
+                    tracing::warn!(
+                        "speed-test probe unanswered — clearing it so loss reports and ABR resume"
+                    );
+                }
+            }
+            was_probing = probe_active;
+            // Fire the startup link-capacity probe once the stream has settled (see the constants
+            // above), and fold its measurement into the ABR ceiling when the result lands.
+            // Never steal the slot from an embedder speed test in flight: there is one `ProbeState`
+            // and no correlation id, so a clobber both wrecks the user's "Test connection" figure
+            // (its base counters get re-snapshotted mid-burst against the full-burst denominator)
+            // and mis-scales our own ceiling. Retry once it finishes.
+            if capacity_probe_at.is_some_and(|at| Instant::now() >= at) && probe_active {
+                capacity_probe_at = Some(Instant::now() + CAPACITY_PROBE_DELAY);
+            } else if capacity_probe_at.is_some_and(|at| Instant::now() >= at) {
+                capacity_probe_at = None;
+                *pump_probe.lock().unwrap() = ProbeState {
+                    active: true,
+                    duration_ms: CAPACITY_PROBE_MS,
+                    ..Default::default()
+                };
+                if ctrl_tx
+                    .try_send(CtrlRequest::Probe(ProbeRequest {
+                        target_kbps: CAPACITY_PROBE_KBPS,
+                        duration_ms: CAPACITY_PROBE_MS,
+                    }))
+                    .is_ok()
+                {
+                    capacity_probe_deadline = Some(Instant::now() + CAPACITY_PROBE_TIMEOUT);
+                    tracing::info!(
+                        target_kbps = CAPACITY_PROBE_KBPS,
+                        duration_ms = CAPACITY_PROBE_MS,
+                        "adaptive bitrate: startup link-capacity probe"
+                    );
+                } else {
+                    pump_probe.lock().unwrap().active = false; // ctrl queue full — skip
+                }
+            }
+            if let Some(deadline) = capacity_probe_deadline {
+                let mut p = pump_probe.lock().unwrap();
+                if p.done {
+                    capacity_probe_deadline = None;
+                    // An all-zero reply is a decline (old host / probe-less build) — keep the
+                    // negotiated ceiling. Otherwise: delivered wire kbps × 0.7.
+                    if p.host_duration_ms > 0 && p.delivered_bytes > 0 {
+                        let delivered_kbps = (p.delivered_bytes.saturating_mul(8)
+                            / p.host_duration_ms.max(1) as u64)
+                            as u32;
+                        let ceiling = delivered_kbps.saturating_mul(7) / 10;
+                        abr.set_ceiling(ceiling);
+                        tracing::info!(
+                            delivered_kbps,
+                            ceiling_kbps = ceiling,
+                            "adaptive bitrate: link-capacity probe done — climb ceiling set"
+                        );
+                    } else {
+                        tracing::info!(
+                            "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;
+                } 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.
+                    p.active = false;
+                    capacity_probe_deadline = None;
+                    tracing::info!(
+                        "adaptive bitrate: capacity probe timed out (old host?) — keeping negotiated ceiling"
+                    );
+                }
+            }
+            if !probe_active && last_report.elapsed() >= ADAPT_REPORT_INTERVAL {
+                // A no-op clock flush earlier in this window suspected a wall-clock step: fire
+                // the mid-stream re-sync now (once — the 60 s periodic covers everything else).
+                if resync_wanted {
+                    resync_wanted = false;
+                    let _ = ctrl_tx.try_send(CtrlRequest::ClockResync);
+                }
+                let window_dropped = st.frames_dropped.wrapping_sub(last_dropped);
+                let loss_ppm = window_loss_ppm(
+                    st.fec_recovered_shards.wrapping_sub(last_recovered),
+                    st.fec_late_shards.wrapping_sub(last_late),
+                    st.packets_received.wrapping_sub(last_received),
+                    window_dropped,
+                );
+                let _ = ctrl_tx.try_send(CtrlRequest::Loss(LossReport { loss_ppm }));
+                // Standing-latency bleed: close the detector's window with this report's loss
+                // verdict and run its escalation ladder — re-sync first (free; a stale offset
+                // from a stepped wall clock produces exactly this signature and the applied
+                // re-sync rebases the floor), then a bounded flush+keyframe (drains a real
+                // sub-threshold standing backlog the jump-to-live thresholds tolerate), then a
+                // loud disarm (the path latency itself changed; nothing local fixes that).
+                match standing_lat.on_window(loss_ppm == 0 && window_dropped == 0) {
+                    StandingLatAction::None => {}
+                    StandingLatAction::Resync { above_ms } => {
+                        tracing::info!(
+                            above_ms,
+                            "standing latency above the session floor with zero loss — \
+                             requesting a clock re-sync first (a stale offset reads exactly \
+                             like this)"
+                        );
+                        let _ = ctrl_tx.try_send(CtrlRequest::ClockResync);
+                    }
+                    StandingLatAction::Bleed { above_ms } => {
+                        // Shares the jump-to-live cooldown: an unexecuted bleed simply re-arms
+                        // over the next windows (the detector's run rebuilds).
+                        if last_flush.is_none_or(|t| t.elapsed() >= FLUSH_COOLDOWN) {
+                            last_flush = Some(Instant::now());
+                            // Deliberately NOT `flush_in_window = true`: that flag is the ABR's
+                            // SEVERE verdict (an immediate ×0.7 back-off), and the bleed fires
+                            // only after ~6 provably loss-free windows with a sub-25ms elevation
+                            // the controller itself scores as fine. The bleed's effect reaches
+                            // the ABR through the window's own honest signals (OWD/loss/decode);
+                            // the flag stays exclusive to the jump-to-live path below.
+                            let flushed = session.flush_backlog().unwrap_or(0);
+                            let dropped = frames.clear();
+                            let _ = ctrl_tx.try_send(CtrlRequest::Keyframe);
+                            standing_lat.bled();
+                            tracing::warn!(
+                                above_ms,
+                                flushed_datagrams = flushed,
+                                dropped_frames = dropped,
+                                "standing latency survived a clock re-sync — bled the local \
+                                 backlog (flush + keyframe)"
+                            );
+                        }
+                    }
+                    StandingLatAction::Disarm { above_ms } => {
+                        tracing::warn!(
+                            above_ms,
+                            "standing latency persists after a re-sync and every bleed — not \
+                             local, not clock; the path latency changed. Leaving it be \
+                             (reconnect re-baselines)"
+                        );
+                    }
+                }
+                // Adaptive bitrate: drain any host ack first (its clamp is authoritative), then
+                // feed the controller this window's congestion signals; a decision becomes a
+                // SetBitrate on the control stream.
+                if let Some(acked) = bitrate_ack.lock().unwrap().take() {
+                    abr.on_ack(acked);
+                }
+                let owd_mean_us =
+                    (owd_frames > 0).then(|| (owd_sum_ns / owd_frames as i128 / 1000) as i64);
+                (owd_sum_ns, owd_frames) = (0, 0);
+                // Drain the embedder's decode-latency window (always, so it stays bounded even when
+                // the controller is disabled) → the mean feeds the decode signal; `None` when the
+                // embedder reported nothing this window (old embedder / no decoded frames).
+                let decode_mean_us = {
+                    let mut acc = pump_decode_lat.lock().unwrap();
+                    let (sum, count) = (acc.sum_us, acc.count);
+                    *acc = DecodeLatAcc::default();
+                    (count > 0).then(|| (sum / count as u64) as i64)
+                };
+                // 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).
+                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)
+                    / window_ms) as u32;
+                if let Some(kbps) = abr.on_window(
+                    Instant::now(),
+                    window_dropped,
+                    loss_ppm,
+                    owd_mean_us,
+                    decode_mean_us,
+                    actual_kbps,
+                    flush_in_window,
+                ) {
+                    // Log the window's signals alongside the decision so an on-glass session can
+                    // tell a decode-driven re-target (the new signal — decode_mean_us elevated with
+                    // loss/OWD flat) from a network-driven one.
+                    tracing::info!(
+                        kbps,
+                        loss_ppm,
+                        owd_mean_us = owd_mean_us.unwrap_or(-1),
+                        decode_mean_us = decode_mean_us.unwrap_or(-1),
+                        actual_kbps,
+                        flushed = flush_in_window,
+                        "adaptive bitrate: requesting encoder re-target"
+                    );
+                    let _ = ctrl_tx.try_send(CtrlRequest::SetBitrate(kbps));
+                }
+                flush_in_window = false;
+                last_report = Instant::now();
+                last_recovered = st.fec_recovered_shards;
+                last_late = st.fec_late_shards;
+                last_received = st.packets_received;
+                last_dropped = st.frames_dropped;
+                last_bytes = st.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);
+                        tracing::info!(
+                            recv_ms = p.recv_ns / 1_000_000,
+                            decrypt_ms = p.decrypt_ns / 1_000_000,
+                            reasm_ms = p.reasm_ns / 1_000_000,
+                            packets = p.packets,
+                            batches = p.batches,
+                            pkts_per_batch = p.packets.checked_div(p.batches).unwrap_or(0),
+                            decrypt_ns_pkt = per_pkt_ns(p.decrypt_ns),
+                            reasm_ns_pkt = per_pkt_ns(p.reasm_ns),
+                            "pump stage split (window)"
+                        );
+                    }
+                    // Inter-arrival jitter over the window's completed AUs. `late` counts gaps
+                    // over 2× the window median — the "a frame arrived visibly off-beat" tally.
+                    if arrivals_us.len() >= 8 {
+                        arrivals_us.sort_unstable();
+                        let pct = |q: usize| arrivals_us[(arrivals_us.len() - 1) * q / 100];
+                        let (p50, p95) = (pct(50), pct(95));
+                        let late = arrivals_us.iter().filter(|&&d| d > p50 * 2).count();
+                        tracing::info!(
+                            frames = arrivals_us.len() + 1,
+                            arrival_p50_us = p50,
+                            arrival_p95_us = p95,
+                            arrival_max_us = arrivals_us.last().copied().unwrap_or(0),
+                            late,
+                            "frame inter-arrival jitter (window)"
+                        );
+                    }
+                    arrivals_us.clear();
+                }
+            }
+            match session.poll_frame() {
+                Ok(frame) => {
+                    if frame.flags & FLAG_PROBE as u32 != 0 {
+                        continue; // speed-test filler, not video — measured via the counters above
+                    }
+                    if pump_perf_on {
+                        let now = Instant::now();
+                        if let Some(prev) = last_arrival.replace(now) {
+                            // 4096 ≈ 17 s at 240 fps — a stuck window can't grow it unbounded.
+                            if arrivals_us.len() < 4096 {
+                                arrivals_us
+                                    .push((now - prev).as_micros().min(u32::MAX as u128) as u32);
+                            }
+                        }
+                    }
+                    // Jump-to-live guard. A standing receive/hand-off queue never drains by itself —
+                    // the pump consumes strictly in order at the arrival rate, so once behind, the
+                    // stream stays behind for good (observed live: stuck 6–7 s). Pre-decode AUs are
+                    // reference-chained (infinite GOP), so we can NOT drop a frame mid-stream to catch
+                    // up; the only safe recovery is to discard the whole backlog and re-anchor decode
+                    // on a fresh keyframe. Two independent "we're behind" signals arm it, both gated by
+                    // FLUSH_COOLDOWN, both suspended during a speed test (the probe MEASURES a saturated
+                    // queue; flushing would corrupt its counters):
+                    //  * clock-based — completed frames sit > FLUSH_LATENCY behind the skew-corrected
+                    //    capture clock continuously for FLUSH_AFTER. Needs the skew handshake, and
+                    //    also catches kernel/reassembler backlog the hand-off queue hasn't reached yet.
+                    //  * clock-free — the pre-decode hand-off queue stopped draining: its depth stayed
+                    //    ≥ QUEUE_HIGH (never falling to QUEUE_LOW, still high at the trip) for
+                    //    STANDING_TIME. Works with no handshake / a same-clock session (where the
+                    //    clock path is disarmed), and is the direct signal that the embedder can't
+                    //    keep up. A transient Wi-Fi clump drains within ~100 ms and never trips it.
+                    if probe_active {
+                        // Keep both detectors disarmed across a speed test so its (deliberately)
+                        // saturated queue doesn't leave a primed run that fires the moment it ends.
+                        stale_since = None;
+                        standing_since = None;
+                    } else {
+                        let lat_ns = if clock_offset_ns != 0 {
+                            now_realtime_ns() + clock_offset_ns as i128 - frame.pts_ns as i128
+                        } else {
+                            0
+                        };
+                        // Feed the adaptive-bitrate controller's OWD window (mean capture→received
+                        // delay): rising delay under zero loss is queue growth — the pre-loss
+                        // congestion signal. Only meaningful with a clock handshake.
+                        if clock_offset_ns != 0 && lat_ns > 0 {
+                            owd_sum_ns += lat_ns;
+                            owd_frames += 1;
+                            // The standing-latency detector rides the same signal, but off the
+                            // window MINIMUM (robust against jitter/burst spikes — a standing
+                            // state elevates the floor itself). Same 10 s plausibility clamp as
+                            // the hn stats use.
+                            if lat_ns < 10_000_000_000 {
+                                standing_lat.note_frame(lat_ns);
+                            }
+                        }
+                        if clock_detector_armed
+                            && clock_offset_ns != 0
+                            && lat_ns > FLUSH_LATENCY.as_nanos() as i128
+                        {
+                            stale_since.get_or_insert_with(Instant::now);
+                        } else {
+                            stale_since = None;
+                        }
+                        let depth = frames.depth();
+                        if depth >= QUEUE_HIGH {
+                            standing_since.get_or_insert_with(Instant::now);
+                        } else if depth <= QUEUE_LOW {
+                            standing_since = None;
+                        }
+                        // The queue trip additionally requires the depth to still be high NOW, so
+                        // a run that started ≥ high but is hovering in the hysteresis band (a
+                        // clump mid-drain) never fires on elapsed time alone.
+                        let clock_behind = stale_since.is_some_and(|t| t.elapsed() >= FLUSH_AFTER);
+                        let queue_behind = depth >= QUEUE_HIGH
+                            && standing_since.is_some_and(|t| t.elapsed() >= STANDING_TIME);
+                        if (clock_behind || queue_behind)
+                            && last_flush.is_none_or(|t| t.elapsed() >= FLUSH_COOLDOWN)
+                        {
+                            stale_since = None;
+                            standing_since = None;
+                            last_flush = Some(Instant::now());
+                            flush_in_window = true; // strongest "link can't hold the rate" signal
+                            let flushed = session.flush_backlog().unwrap_or(0);
+                            let dropped = frames.clear();
+                            let _ = ctrl_tx.try_send(CtrlRequest::Keyframe);
+                            tracing::warn!(
+                                behind_ms = if clock_behind { lat_ns / 1_000_000 } else { -1 },
+                                queue_depth = depth,
+                                flushed_datagrams = flushed,
+                                dropped_frames = dropped,
+                                "receive backlog stopped draining — jumped to live (flush + keyframe)"
+                            );
+                            // Clock-detector health check: a clock-only trigger whose flush found
+                            // no local backlog is a false "behind" reading (a wall-clock step, or
+                            // an upstream queue a local flush can't drain) — repeated, it would
+                            // cost a recovery IDR every cooldown forever. Disarm after two in a
+                            // row; the clock-free queue detector keeps covering real backlogs.
+                            if clock_behind
+                                && !queue_behind
+                                && flushed < NOOP_FLUSH_DATAGRAMS
+                                && dropped == 0
+                            {
+                                noop_clock_flushes += 1;
+                                if noop_clock_flushes == 1 {
+                                    // First no-op flush = a wall-clock step is the prime
+                                    // suspect: ask for an immediate re-sync (sent on the next
+                                    // report tick). Applied, it resets these counters and
+                                    // re-arms the detector before the disarm below triggers.
+                                    resync_wanted = true;
+                                }
+                                if noop_clock_flushes >= NOOP_CLOCK_FLUSHES_TO_DISARM {
+                                    clock_detector_armed = false;
+                                    tracing::warn!(
+                                        "clock-based jump-to-live disarmed — its flushes found no \
+                                         local backlog (clock step or upstream queueing suspected); \
+                                         the queue-depth detector stays armed"
+                                    );
+                                }
+                            } else {
+                                noop_clock_flushes = 0;
+                            }
+                            continue; // this frame is part of the stale past — don't render it
+                        }
+                    }
+                    frames.push(frame);
+                }
+                Err(PunktfunkError::NoFrame) => {
+                    std::thread::sleep(Duration::from_micros(300));
+                }
+                Err(_) => break,
+            }
+        }
+        // The pump exited (shutdown / fatal session error) — wake any consumer blocked in
+        // `next_frame` with a Closed signal instead of a spurious timeout (the old mpsc did this
+        // implicitly when the sender dropped).
+        frames.close();
+    }
+}

crates/punktfunk-core/src/client/pump/datagram_task.rs

@@ -0,0 +1,79 @@
+//! Datagram demux: host → client audio/rumble (try_send: a lagging embedder drops the
+//! newest packet rather than backing up the QUIC receive path).
+
+use super::*;
+
+pub(super) async fn run(
+    conn: quinn::Connection,
+    audio_tx: std::sync::mpsc::SyncSender<AudioPacket>,
+    rumble_tx: std::sync::mpsc::SyncSender<RumbleUpdate>,
+    rumble_feed: super::super::rumble::RumbleFeed,
+    hidout_tx: std::sync::mpsc::SyncSender<crate::quic::HidOutput>,
+    hdr_meta_tx: std::sync::mpsc::SyncSender<crate::quic::HdrMeta>,
+    host_timing_tx: std::sync::mpsc::SyncSender<crate::quic::HostTiming>,
+) {
+    // Per-pad reorder gate for v2 rumble envelopes (the seq analog of the host's gamepad-state
+    // gate): a datagram the network reordered must not roll a stopped motor back on. Legacy v1
+    // datagrams carry no seq and bypass it (an old host's own periodic re-send is the only heal).
+    let mut rumble_last_seq: [Option<u8>; crate::input::MAX_PADS] = [None; crate::input::MAX_PADS];
+    while let Ok(d) = conn.read_datagram().await {
+        match d.first() {
+            Some(&crate::quic::AUDIO_MAGIC) => {
+                if let Some((seq, pts_ns, opus)) = crate::quic::decode_audio_datagram(&d) {
+                    let _ = audio_tx.try_send(AudioPacket {
+                        seq,
+                        pts_ns,
+                        data: opus.to_vec(),
+                    });
+                }
+            }
+            Some(&crate::quic::RUMBLE_MAGIC) => {
+                if let Some(u) = crate::quic::decode_rumble_envelope(&d) {
+                    // Gate v2 envelopes on their per-pad seq; forward v1 (envelope: None) as-is.
+                    let fresh = match u.envelope {
+                        Some(env) => {
+                            let idx = u.pad as usize;
+                            if idx < crate::input::MAX_PADS {
+                                if crate::input::GamepadSnapshot::seq_newer(
+                                    env.seq,
+                                    rumble_last_seq[idx],
+                                ) {
+                                    rumble_last_seq[idx] = Some(env.seq);
+                                    true
+                                } else {
+                                    false // reordered/duplicate — drop, keep the newer state
+                                }
+                            } else {
+                                true // out-of-range pad (host never sends these): no gate
+                            }
+                        }
+                        None => true,
+                    };
+                    if fresh {
+                        let ttl = u.envelope.map(|e| e.ttl_ms);
+                        // Both consumers are fed; an embedder drains exactly one of them
+                        // (the legacy queue, or the policy engine's command API).
+                        let _ = rumble_tx.try_send((u.pad, u.low, u.high, ttl));
+                        rumble_feed.wire_update(u.pad, u.low, u.high, ttl);
+                    }
+                }
+            }
+            Some(&crate::quic::HIDOUT_MAGIC) => {
+                if let Some(h) = HidOutput::decode(&d) {
+                    let _ = hidout_tx.try_send(h);
+                }
+            }
+            Some(&crate::quic::HDR_META_MAGIC) => {
+                if let Some(m) = crate::quic::decode_hdr_meta_datagram(&d) {
+                    let _ = hdr_meta_tx.try_send(m);
+                }
+            }
+            Some(&crate::quic::HOST_TIMING_MAGIC) => {
+                if let Some(t) = crate::quic::decode_host_timing_datagram(&d) {
+                    let _ = host_timing_tx.try_send(t);
+                }
+            }
+            _ => {} // unknown tag — a newer host; ignore
+        }
+    }
+}

crates/punktfunk-core/src/client/pump/handshake.rs

@@ -0,0 +1,201 @@
+//! Connect + handshake: dial the host (cert-pinned), exchange Hello/Welcome/Start on the
+//! control stream, run the wall-clock skew handshake, hole-punch the data port, and stand
+//! up the data-plane [`Session`]. A typed application close from the host surfaces as
+//! [`PunktfunkError::Rejected`] instead of the generic transport error.
+
+use super::super::*;
+use super::*;
+
+/// Everything [`run_pump`](super::run_pump) needs from a successful connect + handshake.
+pub(super) struct HandshakeOut {
+    pub(super) conn: quinn::Connection,
+    pub(super) session: Session,
+    pub(super) ctrl_send: quinn::SendStream,
+    pub(super) ctrl_recv: io::MsgReader,
+    pub(super) negotiated: Negotiated,
+    pub(super) host_caps: u8,
+}
+
+pub(super) async fn connect_and_handshake(args: &WorkerArgs) -> Result<HandshakeOut> {
+    let (host, port, pin) = (&args.host, args.port, args.pin);
+    let (mode, compositor, gamepad) = (args.mode, args.compositor, args.gamepad);
+    let (bitrate_kbps, video_caps, audio_channels) =
+        (args.bitrate_kbps, args.video_caps, args.audio_channels);
+    let (video_codecs, preferred_codec, display_hdr) =
+        (args.video_codecs, args.preferred_codec, args.display_hdr);
+    let (launch, identity, shutdown) = (&args.launch, &args.identity, &args.shutdown);
+    let remote: std::net::SocketAddr = join_host_port(host, port)
+        .parse()
+        .map_err(|_| PunktfunkError::InvalidArg("host:port"))?;
+    let (ep, observed) = endpoint::client_pinned_with_identity(
+        pin,
+        identity.as_ref().map(|(c, k)| (c.as_str(), k.as_str())),
+    );
+    let ep = ep.map_err(|e| PunktfunkError::Io(std::io::Error::other(e.to_string())))?;
+    let conn = ep
+        .connect(remote, "punktfunk")
+        .map_err(|_| PunktfunkError::InvalidArg("connect"))?
+        .await
+        .map_err(|e| {
+            // A pin mismatch surfaces as a TLS failure; report it as a crypto error so
+            // the embedder can distinguish "wrong host identity" from plain IO trouble.
+            let fp_mismatch =
+                pin.is_some() && observed.lock().unwrap().map(|fp| Some(fp) != pin) == Some(true);
+            if fp_mismatch {
+                PunktfunkError::Crypto
+            } else {
+                PunktfunkError::Io(std::io::Error::other(e.to_string()))
+            }
+        })?;
+    let fingerprint = observed.lock().unwrap().unwrap_or([0u8; 32]);
+    // The rest of the handshake runs in an inner future so a failure can consult
+    // `conn.close_reason()`: a host that turned us away with a typed application close
+    // (pairing not armed / denied / approval timeout / version mismatch / busy) surfaces
+    // as `PunktfunkError::Rejected` instead of the generic transport error the failed
+    // read produces — the difference between "not accepted" and the actual cause.
+    let handshake = async {
+        let (mut send, recv) = conn
+            .open_bi()
+            .await
+            .map_err(|e| PunktfunkError::Io(std::io::Error::other(e.to_string())))?;
+        // Frame every read on this stream through the resumable reader: the control loop
+        // below drives it from a `select!` arm and `clock_sync` wraps it in a timeout, and a
+        // partial frame lost to either would misalign the stream for the whole session.
+        let mut recv = io::MsgReader::new(recv);
+
+        io::write_msg(
+            &mut send,
+            &Hello {
+                abi_version: crate::WIRE_VERSION,
+                mode,
+                compositor,
+                gamepad,
+                bitrate_kbps,
+                // No device name yet: the connect ABI has no name parameter (pairing does). The
+                // host falls back to a fingerprint-derived label in its pending-approval list.
+                name: None,
+                // Library id to launch this session, if the embedder asked for one.
+                launch: launch.clone(),
+                // The embedder's decode/present caps (e.g. the Windows client advertises
+                // VIDEO_CAP_10BIT | VIDEO_CAP_HDR). The host only upgrades to a 10-bit / HDR encode
+                // when the matching bit is set, so `0` stays an 8-bit BT.709 stream. HOST_TIMING is
+                // OR'd in unconditionally: every NativeClient build demuxes the 0xCF plane, and the
+                // bit only asks the host for observability datagrams (never changes the encode).
+                // PROBE_SEQ likewise: the shared reassembler keeps probe filler in its own window
+                // (every embedder inherits it), so the host may burst speed tests without consuming
+                // video frame indexes.
+                video_caps: video_caps
+                    | crate::quic::VIDEO_CAP_HOST_TIMING
+                    | crate::quic::VIDEO_CAP_PROBE_SEQ,
+                // Requested surround channel count; the host echoes the resolved value in Welcome.
+                audio_channels,
+                // The codecs this client can decode + its soft preference (0 = auto). The host
+                // resolves the emitted codec from these and reports it in `Welcome::codec`.
+                video_codecs,
+                preferred_codec,
+                // The client display's HDR volume → the host's virtual-display EDID (host apps
+                // tone-map to the client's real panel). `None` = unknown/SDR.
+                display_hdr,
+            }
+            .encode(),
+        )
+        .await?;
+        let welcome = Welcome::decode(&recv.read_msg().await?)?;
+        if welcome.compositor != CompositorPref::Auto {
+            tracing::info!(
+                compositor = welcome.compositor.as_str(),
+                "host resolved compositor"
+            );
+        }
+        if welcome.gamepad != GamepadPref::Auto {
+            tracing::info!(
+                gamepad = welcome.gamepad.as_str(),
+                "host resolved gamepad backend"
+            );
+        }
+
+        // Reserve our data-plane port, then start the host.
+        let probe = std::net::UdpSocket::bind("0.0.0.0:0")?;
+        let udp_port = probe.local_addr()?.port();
+        drop(probe);
+        io::write_msg(
+            &mut send,
+            &Start {
+                client_udp_port: udp_port,
+            }
+            .encode(),
+        )
+        .await?;
+
+        // Wall-clock skew handshake on the control stream (before the session's control task takes
+        // it): align our clock to the host's so the embedder can express receive/present instants in
+        // the host's capture clock (the AU `pts_ns`). 0 ⇒ an old host that didn't answer (shared-clock
+        // assumption, as before). This is the substrate for glass-to-glass present-time measurement.
+        let (clock_offset_ns, clock_rtt_ns) =
+            match crate::quic::clock_sync(&mut send, &mut recv).await {
+                Some(skew) => {
+                    tracing::info!(
+                        offset_ns = skew.offset_ns,
+                        rtt_us = skew.rtt_ns / 1000,
+                        rounds = skew.rounds,
+                        "clock skew estimated (host-client)"
+                    );
+                    (skew.offset_ns, Some(skew.rtt_ns))
+                }
+                None => (0, None),
+            };
+
+        let host_udp = std::net::SocketAddr::new(remote.ip(), welcome.udp_port);
+        let transport =
+            UdpTransport::connect(&format!("0.0.0.0:{udp_port}"), &host_udp.to_string())?;
+        // Hole-punch the host's data port so video traverses a NAT / stateful inter-VLAN firewall
+        // (control + side planes ride the client-initiated QUIC; the raw video UDP needs the client
+        // to open the path first). Stops with the session via the shared shutdown flag.
+        if let Ok(sock) = transport.try_clone_socket() {
+            crate::transport::spawn_data_punch(sock, shutdown.clone());
+        }
+        let mut session = Session::new(welcome.session_config(Role::Client), Box::new(transport))?;
+        // PyroWave sessions opt into partial delivery (plan §4.4): an aged-out lossy
+        // frame arrives as blocks-with-holes instead of vanishing — the all-intra codec
+        // renders it as one frame of localized blur, strictly better than a freeze.
+        if welcome.codec == crate::quic::CODEC_PYROWAVE {
+            session.set_deliver_partial_frames(true);
+        }
+        Ok::<_, PunktfunkError>((
+            session,
+            send,
+            recv,
+            Negotiated {
+                mode: welcome.mode,
+                compositor: welcome.compositor,
+                gamepad: welcome.gamepad,
+                host_fingerprint: fingerprint,
+                bitrate_kbps: welcome.bitrate_kbps,
+                clock_offset_ns,
+                clock_rtt_ns,
+                bit_depth: welcome.bit_depth,
+                color: welcome.color,
+                chroma_format: welcome.chroma_format,
+                audio_channels: welcome.audio_channels,
+                codec: welcome.codec,
+                shard_payload: welcome.shard_payload,
+                host_caps: welcome.host_caps,
+            },
+            welcome.host_caps,
+        ))
+    };
+    match handshake.await {
+        Ok((session, send, recv, negotiated, host_caps)) => Ok(HandshakeOut {
+            conn,
+            session,
+            ctrl_send: send,
+            ctrl_recv: recv,
+            negotiated,
+            host_caps,
+        }),
+        Err(e) => Err(match reject_from_close(&conn) {
+            Some(r) => PunktfunkError::Rejected(r),
+            None => e,
+        }),
+    }
+}

crates/punktfunk-core/src/client/pump/input_task.rs

@@ -0,0 +1,139 @@
+//! Input task: embedder events → QUIC datagrams. Toward a host that advertised
+//! HOST_CAP_GAMEPAD_STATE, the per-transition gamepad events every embedder still emits are
+//! folded into idempotent, sequence-numbered full-state snapshots (`GamepadSnapshot`): the
+//! datagram plane drops and reorders (and sheds oldest-first at the 4 KiB send cap), so a lost
+//! per-transition event would corrupt held pad state until the *next* change — a held trigger
+//! stuck wrong indefinitely. Snapshots heal on the next send, the seq lets the host drop stale
+//! reorders, and a periodic refresh of every touched pad bounds any loss to one refresh
+//! interval — the same idempotent-state discipline as the host's 500 ms rumble refresh.
+//! Keyboard/mouse/touch events pass through unchanged; an older host (no caps bit) keeps
+//! getting the legacy per-transition gamepad events.
+
+use super::super::*;
+use super::*;
+
+pub(super) async fn run(
+    conn: quinn::Connection,
+    mut input_rx: tokio::sync::mpsc::UnboundedReceiver<InputEvent>,
+    gamepad_snapshots: bool,
+) {
+    use crate::input::{GamepadSnapshot, InputKind, MAX_PADS};
+    // Touched pads only: an entry appears on the first gamepad event for that index, so the
+    // refresh never conjures a virtual pad the embedder didn't drive.
+    let mut pads: [Option<GamepadSnapshot>; MAX_PADS] = [None; MAX_PADS];
+    // Per-pad wrapping seq that PERSISTS across a pad's remove/re-add on the same index (the
+    // snapshot itself is cleared to `None` on removal). A removal takes `seq[idx] + 1` so it
+    // supersedes every prior snapshot; the re-added pad's first snapshot takes the next value
+    // after that, so the host's seq gate accepts it instead of rejecting a restarted-at-0 seq.
+    let mut seq: [u8; MAX_PADS] = [0; MAX_PADS];
+    // Re-sends of a removal still owed on refresh ticks (the removal rides the lossy datagram
+    // plane; a single lost one would silently strand a ghost pad on the host — the exact bug
+    // the removal fixes). Mirrors the host's rumble stop burst: a few time-spread re-sends,
+    // each with a fresh (higher) seq, and canceled the moment the pad is driven again.
+    const REMOVE_RESENDS: u8 = 2;
+    let mut remove_owed: [u8; MAX_PADS] = [0; MAX_PADS];
+    // Per-pad declared controller kind ([`GamepadArrival`]) + its owed re-sends: the host needs
+    // the kind before the pad's first frame to build a matching virtual device (mixed types), so
+    // like the removal it rides the lossy plane with a small time-spread re-send burst.
+    const ARRIVAL_RESENDS: u8 = 2;
+    let mut arrival: [Option<u8>; MAX_PADS] = [None; MAX_PADS];
+    let mut arrival_owed: [u8; MAX_PADS] = [0; MAX_PADS];
+    let mut refresh = tokio::time::interval(Duration::from_millis(100));
+    refresh.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
+    loop {
+        tokio::select! {
+            ev = input_rx.recv() => {
+                let Some(ev) = ev else { break };
+                let idx = ev.flags as usize;
+                if gamepad_snapshots
+                    && matches!(ev.kind, InputKind::GamepadButton | InputKind::GamepadAxis)
+                    && idx < MAX_PADS
+                {
+                    // The pad is being driven — cancel any owed removal (a re-plug on this
+                    // index; its fresh snapshot seq already supersedes the removal's).
+                    remove_owed[idx] = 0;
+                    let snap = pads[idx].get_or_insert(GamepadSnapshot {
+                        pad: idx as u8,
+                        ..Default::default()
+                    });
+                    // Unknown axis ids don't send (the host's legacy fold drops them too).
+                    if snap.fold(&ev) {
+                        seq[idx] = seq[idx].wrapping_add(1);
+                        snap.seq = seq[idx];
+                        let _ = conn
+                            .send_datagram(snap.to_event().encode().to_vec().into());
+                    }
+                    continue;
+                }
+                if gamepad_snapshots && ev.kind == InputKind::GamepadRemove && idx < MAX_PADS {
+                    // Stop refreshing the pad and forward a seq-stamped removal (in the shared
+                    // seq space) so the host tears its virtual device down and no reordered
+                    // snapshot can resurrect it; arm the re-send burst against datagram loss.
+                    // Drop any owed kind declaration too — a re-plug on this index sends its own.
+                    pads[idx] = None;
+                    arrival[idx] = None;
+                    arrival_owed[idx] = 0;
+                    seq[idx] = seq[idx].wrapping_add(1);
+                    remove_owed[idx] = REMOVE_RESENDS;
+                    let rem = crate::input::InputEvent {
+                        flags: crate::input::encode_gamepad_remove(idx as u8, seq[idx]),
+                        ..ev
+                    };
+                    let _ = conn.send_datagram(rem.encode().to_vec().into());
+                    continue;
+                }
+                if gamepad_snapshots && ev.kind == InputKind::GamepadArrival && idx < MAX_PADS {
+                    // Remember the declared kind (`code`) and forward it, arming a re-send burst
+                    // so the host learns it before the pad's first frame even under loss.
+                    arrival[idx] = Some(ev.code as u8);
+                    arrival_owed[idx] = ARRIVAL_RESENDS;
+                    let _ = conn.send_datagram(ev.encode().to_vec().into());
+                    continue;
+                }
+                let _ = conn.send_datagram(ev.encode().to_vec().into());
+            }
+            _ = refresh.tick() => {
+                for idx in 0..MAX_PADS {
+                    // Re-send an owed kind declaration (independent of whether the pad has state
+                    // yet — it may be idle-but-connected). Idempotent on the host.
+                    if arrival_owed[idx] > 0 {
+                        if let Some(kind) = arrival[idx] {
+                            arrival_owed[idx] -= 1;
+                            let arr = crate::input::InputEvent {
+                                kind: InputKind::GamepadArrival,
+                                _pad: [0; 3],
+                                code: kind as u32,
+                                x: 0,
+                                y: 0,
+                                flags: idx as u32,
+                            };
+                            let _ = conn.send_datagram(arr.encode().to_vec().into());
+                        } else {
+                            arrival_owed[idx] = 0;
+                        }
+                    }
+                    if let Some(snap) = pads[idx].as_mut() {
+                        seq[idx] = seq[idx].wrapping_add(1);
+                        snap.seq = seq[idx];
+                        let _ = conn.send_datagram(snap.to_event().encode().to_vec().into());
+                    } else if remove_owed[idx] > 0 {
+                        // Idempotent removal re-send with a fresh seq (the host drops it as a
+                        // no-op once the pad is already gone, but a re-plug's later snapshot
+                        // still wins by seq).
+                        remove_owed[idx] -= 1;
+                        seq[idx] = seq[idx].wrapping_add(1);
+                        let rem = crate::input::InputEvent {
+                            kind: InputKind::GamepadRemove,
+                            _pad: [0; 3],
+                            code: 0,
+                            x: 0,
+                            y: 0,
+                            flags: crate::input::encode_gamepad_remove(idx as u8, seq[idx]),
+                        };
+                        let _ = conn.send_datagram(rem.encode().to_vec().into());
+                    }
+                }
+            }
+        }
+    }
+}

crates/punktfunk-core/src/clipboard.rs

@@ -145,6 +145,11 @@ pub async fn run(
                 let Some(cmd) = cmd else { break }; // NativeClient dropped
                 match cmd {
                     ClipCommand::Fetch { xfer_id, seq, file_index, mime } => {
+                        // Prune finished fetches first: a completed/failed/timed-out fetch task
+                        // drops its cancel receiver, so its sender reads closed. Without this
+                        // the map grew by one dead sender per paste for the whole session (only
+                        // an explicit Cancel ever removed entries).
+                        fetch_cancels.retain(|_, tx| !tx.is_closed());
                         let (cancel_tx, cancel_rx) = oneshot::channel();
                         fetch_cancels.insert(xfer_id, cancel_tx);
                         let conn = conn.clone();
@@ -153,14 +158,39 @@ pub async fn run(
                         tokio::spawn(run_outbound_fetch(conn, xfer_id, req, events, cancel_rx));
                     }
                     ClipCommand::Serve { req_id, bytes, last } => {
-                        serve_bufs.entry(req_id).or_default().extend_from_slice(&bytes);
+                        // Gate on a genuinely parked fetch (the waiter registers before the
+                        // FetchRequest event is emitted, so a live serve always finds it):
+                        // bytes served under a stale/unknown/cancelled req_id would otherwise
+                        // pool here for the whole session with Ok returned for every chunk.
+                        if !serve_waiters.lock().unwrap().contains_key(&req_id) {
+                            serve_bufs.remove(&req_id);
+                        } else {
+                            let buf = serve_bufs.entry(req_id).or_default();
+                            if buf.len().saturating_add(bytes.len()) > CLIP_FETCH_CAP {
+                                // The requester bounds its read at CLIP_FETCH_CAP — anything
+                                // larger is memory burned toward a guaranteed peer rejection.
+                                // Fail the transfer NOW: peer reads UNAVAILABLE, embedder gets
+                                // an Error instead of silent Ok-per-chunk.
+                                serve_bufs.remove(&req_id);
+                                if let Some(tx) = serve_waiters.lock().unwrap().remove(&req_id) {
+                                    let _ = tx.send(None);
+                                }
+                                let _ = events.try_send(ClipEventCore::Error {
+                                    id: req_id,
+                                    code: PunktfunkStatus::InvalidArg as i32,
+                                });
+                            } else {
+                                buf.extend_from_slice(&bytes);
                                 if last {
                                     let full = serve_bufs.remove(&req_id).unwrap_or_default();
-                            if let Some(tx) = serve_waiters.lock().unwrap().remove(&req_id) {
+                                    if let Some(tx) = serve_waiters.lock().unwrap().remove(&req_id)
+                                    {
                                         let _ = tx.send(Some(full));
                                     }
                                 }
                             }
+                        }
+                    }
                     ClipCommand::Cancel { id } => {
                         // Route to whichever table owns the id (they are disjoint by the high bit).
                         if let Some(tx) = fetch_cancels.remove(&id) {
@@ -224,8 +254,27 @@ async fn serve_inbound(
         return;
     }
 
-    match rx.await {
+    // Overall stall bound (§3.4) — the inbound mirror of `run_outbound_fetch`'s: an embedder
-        Ok(Some(bytes)) => {
+    // that never answers must not hold the waiter, this task, and the accepted bi-stream open
+    // for the rest of the session (~100 unanswered pastes exhaust the connection's bidi-stream
+    // budget and every later host paste stalls). `send.stopped()` additionally wakes us the
+    // moment the peer gives up on its side of the fetch.
+    let answer = tokio::select! {
+        r = rx => r.ok().flatten(),
+        _ = send.stopped() => {
+            let _ = events.try_send(ClipEventCore::Cancelled { id: req_id });
+            None
+        }
+        _ = tokio::time::sleep(std::time::Duration::from_secs(FETCH_STALL_SECS)) => {
+            let _ = events.try_send(ClipEventCore::Cancelled { id: req_id });
+            None
+        }
+    };
+    // Idempotent — the answering/denying paths already removed it; the stall paths must.
+    waiters.lock().unwrap().remove(&req_id);
+
+    match answer {
+        Some(bytes) => {
             if clipstream::write_fetch_hdr(
                 &mut send,
                 &ClipFetchHdr {
@@ -302,3 +351,65 @@ async fn run_outbound_fetch(
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::quic::test_util::connect_pair;
+    use crate::quic::CLIP_FILE_INDEX_NONE;
+
+    /// A serve chunk that alone breaches the requester-side CLIP_FETCH_CAP must fail the
+    /// transfer immediately — Error to the embedder, UNAVAILABLE to the peer — instead of
+    /// accumulating Ok-per-chunk toward a guaranteed peer-side rejection. Also pins the
+    /// waiter-membership gate: the serve only accumulated because the fetch was parked.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn oversized_serve_fails_the_transfer_instead_of_buffering() {
+        let (_s, _c, host_conn, client_conn) = connect_pair().await;
+        let (ev_tx, ev_rx) = std::sync::mpsc::sync_channel(16);
+        let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
+        tokio::spawn(run(client_conn, ev_tx, cmd_rx));
+
+        // Host pastes: it opens a fetch bi-stream toward the client.
+        let req = ClipFetch {
+            seq: 1,
+            file_index: CLIP_FILE_INDEX_NONE,
+            mime: "text/plain;charset=utf-8".into(),
+        };
+        let (_send, mut recv) = clipstream::open_fetch(&host_conn, &req).await.unwrap();
+
+        // The client core surfaces the FetchRequest (the waiter is parked now).
+        let (req_id, ev_rx) = tokio::task::spawn_blocking(move || {
+            match ev_rx
+                .recv_timeout(std::time::Duration::from_secs(5))
+                .unwrap()
+            {
+                ClipEventCore::FetchRequest { req_id, .. } => (req_id, ev_rx),
+                other => panic!("expected FetchRequest, got {other:?}"),
+            }
+        })
+        .await
+        .unwrap();
+
+        cmd_tx
+            .send(ClipCommand::Serve {
+                req_id,
+                bytes: vec![0u8; CLIP_FETCH_CAP + 1],
+                last: false,
+            })
+            .unwrap();
+        let ev = tokio::task::spawn_blocking(move || {
+            ev_rx
+                .recv_timeout(std::time::Duration::from_secs(5))
+                .unwrap()
+        })
+        .await
+        .unwrap();
+        match ev {
+            ClipEventCore::Error { id, .. } => assert_eq!(id, req_id),
+            other => panic!("expected Error, got {other:?}"),
+        }
+        // The peer's read side sees the transfer refused, not a hang.
+        let hdr = clipstream::read_fetch_hdr(&mut recv).await.unwrap();
+        assert_eq!(hdr.status, CLIP_FETCH_UNAVAILABLE);
+    }
+}

crates/punktfunk-core/src/config.rs

@@ -548,4 +548,100 @@ mod tests {
             Some(SteamController)
         );
     }
+
+    #[test]
+    fn compositor_pref_wire_and_names() {
+        for p in [
+            CompositorPref::Auto,
+            CompositorPref::Kwin,
+            CompositorPref::Wlroots,
+            CompositorPref::Mutter,
+            CompositorPref::Gamescope,
+        ] {
+            assert_eq!(CompositorPref::from_u8(p.to_u8()), p);
+            assert_eq!(CompositorPref::from_name(p.as_str()), Some(p));
+        }
+        // Aliases + unknowns.
+        assert_eq!(CompositorPref::from_name("KDE"), Some(CompositorPref::Kwin));
+        assert_eq!(
+            CompositorPref::from_name("sway"),
+            Some(CompositorPref::Wlroots)
+        );
+        assert_eq!(CompositorPref::from_name("nope"), None);
+        // Unknown wire byte degrades to Auto (forward-compatible).
+        assert_eq!(CompositorPref::from_u8(200), CompositorPref::Auto);
+    }
+
+    #[test]
+    fn gamepad_pref_wire_and_names() {
+        for p in [
+            GamepadPref::Auto,
+            GamepadPref::Xbox360,
+            GamepadPref::DualSense,
+            GamepadPref::XboxOne,
+            GamepadPref::DualShock4,
+            GamepadPref::SteamController,
+            GamepadPref::SteamDeck,
+            GamepadPref::DualSenseEdge,
+            GamepadPref::SwitchPro,
+            GamepadPref::SteamController2,
+            GamepadPref::SteamController2Puck,
+        ] {
+            assert_eq!(GamepadPref::from_u8(p.to_u8()), p);
+            assert_eq!(GamepadPref::from_name(p.as_str()), Some(p));
+        }
+        // Every wire byte 0..=10 is assigned, distinct, and pinned (forward-compat with peers
+        // that only know a prefix of the range).
+        for (v, p) in [
+            (0, GamepadPref::Auto),
+            (1, GamepadPref::Xbox360),
+            (2, GamepadPref::DualSense),
+            (3, GamepadPref::XboxOne),
+            (4, GamepadPref::DualShock4),
+            (5, GamepadPref::SteamController),
+            (6, GamepadPref::SteamDeck),
+            (7, GamepadPref::DualSenseEdge),
+            (8, GamepadPref::SwitchPro),
+            (9, GamepadPref::SteamController2),
+            (10, GamepadPref::SteamController2Puck),
+        ] {
+            assert_eq!(p.to_u8(), v);
+            assert_eq!(GamepadPref::from_u8(v), p);
+        }
+        // The next unassigned byte degrades to Auto today; assigning it later must update this.
+        assert_eq!(GamepadPref::from_u8(11), GamepadPref::Auto);
+        // Aliases + unknowns.
+        assert_eq!(GamepadPref::from_name("PS5"), Some(GamepadPref::DualSense));
+        assert_eq!(GamepadPref::from_name("x360"), Some(GamepadPref::Xbox360));
+        assert_eq!(GamepadPref::from_name("ps4"), Some(GamepadPref::DualShock4));
+        assert_eq!(GamepadPref::from_name("DS4"), Some(GamepadPref::DualShock4));
+        assert_eq!(
+            GamepadPref::from_name("edge"),
+            Some(GamepadPref::DualSenseEdge)
+        );
+        assert_eq!(
+            GamepadPref::from_name("Switch-Pro"),
+            Some(GamepadPref::SwitchPro)
+        );
+        assert_eq!(
+            GamepadPref::from_name("ibex"),
+            Some(GamepadPref::SteamController2)
+        );
+        assert_eq!(
+            GamepadPref::from_name("sc2"),
+            Some(GamepadPref::SteamController2)
+        );
+        assert_eq!(
+            GamepadPref::from_name("sc2puck"),
+            Some(GamepadPref::SteamController2Puck)
+        );
+        assert_eq!(
+            GamepadPref::from_name("xbox-one"),
+            Some(GamepadPref::XboxOne)
+        );
+        assert_eq!(GamepadPref::from_name("series"), Some(GamepadPref::XboxOne));
+        assert_eq!(GamepadPref::from_name("nope"), None);
+        // Unknown wire byte degrades to Auto (forward-compatible).
+        assert_eq!(GamepadPref::from_u8(200), GamepadPref::Auto);
+    }
 }

crates/punktfunk-core/src/fec/gf8.rs

@@ -86,8 +86,18 @@ impl ErasureCoder for Gf8Coder {
             // No FEC: every original must already be present.
             return collect_originals(received, data_count);
         }
+        // Same (k, m)-keyed cache as `encode_into`: a fresh ReedSolomon per lossy block costs a
+        // full generator build (k×2k Gauss-Jordan + total×k×k multiply) on the real-time pump
+        // thread AND forfeits the instance's decode-matrix cache for stable loss patterns.
+        let mut guard = self.rs.lock().unwrap_or_else(|p| p.into_inner());
+        let cached =
+            matches!(&*guard, Some((ck, cm, _)) if *ck == data_count && *cm == recovery_count);
+        if !cached {
             let rs = ReedSolomon::new(data_count, recovery_count)
                 .map_err(|_| FecError::Config("invalid GF(2^8) shard counts"))?;
+            *guard = Some((data_count, recovery_count, rs));
+        }
+        let rs = &guard.as_ref().expect("cache populated above").2;
         rs.reconstruct_data(received)
             .map_err(|_| FecError::Backend("gf8 reconstruct"))?;
         collect_originals(received, data_count)
@@ -116,8 +126,17 @@ impl ErasureCoder for Gf8Coder {
         for &(j, bytes) in recovery {
             received[data_count + j] = Some(bytes.to_vec());
         }
+        // Cache the codec by (k, m) exactly as `encode_into`/`reconstruct` do (see the note
+        // there) — this path runs per lossy block on the pump thread.
+        let mut guard = self.rs.lock().unwrap_or_else(|p| p.into_inner());
+        let cached =
+            matches!(&*guard, Some((ck, cm, _)) if *ck == data_count && *cm == recovery_count);
+        if !cached {
             let rs = ReedSolomon::new(data_count, recovery_count)
                 .map_err(|_| FecError::Config("invalid GF(2^8) shard counts"))?;
+            *guard = Some((data_count, recovery_count, rs));
+        }
+        let rs = &guard.as_ref().expect("cache populated above").2;
         rs.reconstruct_data(&mut received)
             .map_err(|_| FecError::Backend("gf8 reconstruct"))?;
         for (i, h) in have.iter().enumerate() {

crates/punktfunk-core/src/lib.rs

@@ -16,6 +16,17 @@
 //!   (recv → open → reorder → FEC recover → reassemble) state machines.
 //! - [`transport`] — pluggable packet I/O (in-process loopback for tests; UDP for real).
 //! - [`abi`] — the `extern "C"` surface and `cbindgen`-generated `punktfunk_core.h`.
+//! - [`config`] / [`error`] / [`stats`] — session configuration, the shared error/status
+//!   vocabulary, and the counters snapshot.
+//! - [`input`] — the wire input-event vocabulary (keyboard/mouse/touch, gamepad snapshots).
+//! - [`reject`] — typed application-close rejection codes · [`reanchor`] — the post-loss
+//!   freeze-until-reanchor client gate · [`render_scale`] — the shared render-scale setting ·
+//!   [`audio`] — Opus PCM decode for C-ABI embedders · [`wol`] — Wake-on-LAN.
+//! - `quic` (feature `quic`) — the punktfunk/1 control plane: handshake, typed control
+//!   messages, pairing (SPAKE2), the datagram plane codecs, and clock sync. With it come
+//!   `client` (the embeddable NativeClient worker), `abr` (the adaptive-bitrate
+//!   controller), and `clipboard` (the shared-clipboard transport task). `tls`
+//!   (feature `tls`) — the pinned-fingerprint certificate verifier.
 //!
 //! ## Threading contract
 //!
@@ -83,7 +94,15 @@ pub use stats::Stats;
 /// `punktfunk_connection_clipboard_{control,offer,fetch,serve,cancel}` +
 /// `punktfunk_connection_next_clipboard`. Additive; the wire grows only backward-compatible control
 /// messages (0x40-0x44) and a new `Welcome::host_caps` bit, so [`WIRE_VERSION`] is unchanged.
-pub const ABI_VERSION: u32 = 8;
+/// v9: `PunktfunkFrame` grew `received_ns` — the reassembly-completion receipt stamp, so
+/// embedders stop stamping receipt at the hand-off pull (which folds the pre-decode queue wait
+/// into apparent network latency). Struct-size change on the frame poll surface = a hard ABI
+/// break for embedders reading `PunktfunkFrame`; nothing on the wire moved, so [`WIRE_VERSION`]
+/// is unchanged.
+/// v10: added `punktfunk_connection_clock_offset_now_ns` — the LIVE (mid-stream re-synced)
+/// clock offset ongoing latency math must use; the connect-time getter stays frozen by
+/// contract. Additive, client-local — no wire change, so [`WIRE_VERSION`] is unchanged.
+pub const ABI_VERSION: u32 = 10;
 
 /// The punktfunk/1 **wire** version — what `Hello`/`Welcome` carry and hosts equality-check.
 /// Deliberately its own constant: [`ABI_VERSION`] tracks the embeddable **C surface**

crates/punktfunk-core/src/packet/packetize.rs

@@ -39,10 +39,19 @@ pub struct Packetizer {
     /// DATA shards before any block's parity — all blocks' parity must stay alive until the
     /// frame's second emission pass.
     recovery: Vec<Vec<Vec<u8>>>,
+    /// The peer's per-block `data + recovery` acceptance ceiling, frozen from the **negotiated**
+    /// config exactly as the far side derives it in [`ReassemblerLimits::from_config`]. Adaptive
+    /// FEC moves `fec.fec_percent` live ([`set_fec_percent`](Self::set_fec_percent)) but the
+    /// receiver's ceiling is computed once at session construction and never re-derived, so parity
+    /// must be clamped against this or a raised percentage puts blocks over the far side's bound —
+    /// where every packet of the block is dropped wholesale, the frame never completes, and the
+    /// resulting loss pushes adaptive FEC *higher*. See the `recovery_for` clamp in `packetize_each`.
+    max_total_shards: usize,
 }
 
 impl Packetizer {
     pub fn new(config: &Config) -> Self {
+        let max_data = config.fec.max_data_per_block as usize;
         Packetizer {
             next_frame_index: 0,
             next_probe_index: 0,
@@ -52,6 +61,9 @@ impl Packetizer {
             version: config.phase as u8,
             tail: Vec::new(),
             recovery: Vec::new(),
+            // Mirrors `ReassemblerLimits::from_config` — keep the two in step.
+            max_total_shards: (max_data + config.fec.recovery_for(max_data))
+                .min(config.fec.scheme.max_total_shards()),
         }
     }
 
@@ -173,6 +185,15 @@ impl Packetizer {
         };
         // Per-block shard geometry (deterministic — recomputed in both passes).
         let block_data_count = |b: usize| ((b + 1) * max_block).min(total_data) - b * max_block;
+        // Parity for a `k`-shard block: the configured percentage, clamped so the block's wire
+        // total never exceeds what the peer will accept (see `max_total_shards`). The clamp only
+        // binds on blocks near `max_data_per_block`; smaller blocks keep the full adaptive range,
+        // so raising FEC still buys real protection wherever there is headroom. Bound as locals,
+        // not as a `&self` method: `emit_one` below would otherwise capture all of `self` and
+        // collide with the `&mut self.recovery[b]` parity borrow.
+        let (fec, max_total_shards) = (self.fec, self.max_total_shards);
+        let recovery_for =
+            move |k: usize| fec.recovery_for(k).min(max_total_shards.saturating_sub(k));
 
         // One parity pool per block, reused across frames (steady-state zero-alloc).
         if self.recovery.len() < block_count {
@@ -183,7 +204,7 @@ impl Packetizer {
         let mut total_recovery = 0usize;
         for b in 0..block_count {
             let k = block_data_count(b);
-            let m = self.fec.recovery_for(k);
+            let m = recovery_for(k);
             if k + m > u16::MAX as usize {
                 return Err(PunktfunkError::Unsupported("block shard count exceeds u16"));
             }
@@ -204,7 +225,7 @@ impl Packetizer {
                     block_index: b as u16,
                     block_count: block_count as u16,
                     data_shards: k as u16,
-                    recovery_shards: self.fec.recovery_for(k) as u16,
+                    recovery_shards: recovery_for(k) as u16,
                     shard_index: shard_index as u16,
                     shard_bytes: payload as u16,
                     magic: PUNKTFUNK_MAGIC,
@@ -223,7 +244,7 @@ impl Packetizer {
 
             // This block's data shards: references into `frame` (plus the staged tail).
             let data_shards: Vec<&[u8]> = (first..first + k).map(shard_at).collect();
-            let recovery_count = self.fec.recovery_for(k);
+            let recovery_count = recovery_for(k);
             coder.encode_into(&data_shards, recovery_count, &mut self.recovery[b])?;
 
             for (shard_index, body) in data_shards.iter().enumerate() {
@@ -242,7 +263,7 @@ impl Packetizer {
         let mut parity_left = total_recovery;
         for b in 0..block_count {
             let k = block_data_count(b);
-            let recovery_count = self.fec.recovery_for(k);
+            let recovery_count = recovery_for(k);
             for r in 0..recovery_count {
                 parity_left -= 1;
                 let mut flags = FLAG_PIC;

crates/punktfunk-core/src/packet/reassemble.rs

@@ -106,8 +106,19 @@ pub struct ReassemblerLimits {
 impl ReassemblerLimits {
     pub fn from_config(c: &Config) -> Self {
         let max_data = c.fec.max_data_per_block as usize;
+        // Size the ceiling from the whole range adaptive FEC may reach, NOT from the percentage
+        // negotiated at session start: the sender moves `fec_percent` live (`Packetizer::
+        // set_fec_percent`, clamped to ≤ 90) and the wire is self-describing, so it never
+        // renegotiates. Deriving this from the start value made every packet of a large block
+        // fail the `total > max_total_shards` check once FEC ramped up — the block never
+        // accumulated a shard, the frame aged out, and the resulting loss drove FEC *higher*,
+        // wedging large frames at 100% loss exactly when FEC was meant to rescue the link. A
+        // current sender also clamps its side (`Packetizer::recovery_for`); this keeps an
+        // already-deployed sender that doesn't from wedging a current receiver. Still a hard
+        // pre-allocation bound against hostile headers — just the sender's clamp, not a stale
+        // snapshot of it.
         let max_total =
-            (max_data + c.fec.recovery_for(max_data)).min(c.fec.scheme.max_total_shards());
+            (max_data + (max_data * 90).div_ceil(100)).min(c.fec.scheme.max_total_shards());
         let total_data = c.max_frame_bytes.div_ceil(c.shard_payload.max(1)).max(1);
         ReassemblerLimits {
             shard_bytes: c.shard_payload,
@@ -489,6 +500,7 @@ impl Reassembler {
                 pts_ns: done.pts_ns,
                 flags: done.user_flags,
                 complete: true,
+                received_ns: 0, // stamped by Session::poll_frame at the session boundary
             }));
         }
         Ok(None)
@@ -506,6 +518,10 @@ impl Reassembler {
         // The dropped frames' buffers (and their parity bufs) go back to the allocator, not the
         // pool — a flush is the rare path. The budget resets with them.
         self.in_flight_bytes = 0;
+        // An aged-out partial parked for delivery is from the discarded past too — without this
+        // it survives `flush_backlog` and gets handed up as the first "frame" after the
+        // jump-to-live, exactly the stale content the flush existed to discard.
+        self.pending_partial = None;
     }
 }
 
@@ -592,6 +608,7 @@ impl ReassemblyWindow {
                                 pts_ns: f.pts_ns,
                                 flags: f.user_flags,
                                 complete: false,
+                                received_ns: 0, // stamped by Session::poll_frame at the session boundary
                             });
                         }
                     }
@@ -632,3 +649,35 @@ impl ReassemblyWindow {
         }
     }
 }
+
+#[cfg(test)]
+mod reset_tests {
+    use super::*;
+
+    /// `flush_backlog` discards the past wholesale — an aged-out partial parked for delivery is
+    /// part of that past and must not survive [`Reassembler::reset`] to be handed up as the
+    /// first "frame" after a jump-to-live.
+    #[test]
+    fn reset_drops_a_parked_partial() {
+        let mut r = Reassembler::new(ReassemblerLimits {
+            shard_bytes: 64,
+            max_data_shards: 8,
+            max_total_shards: 16,
+            max_blocks: 4,
+            max_frame_bytes: 4096,
+        });
+        r.pending_partial = Some(Frame {
+            data: vec![0u8; 64],
+            frame_index: 7,
+            pts_ns: 1,
+            flags: 0,
+            complete: false,
+            received_ns: 0,
+        });
+        r.reset();
+        assert!(
+            r.take_partial().is_none(),
+            "a pre-flush partial must not survive reset()"
+        );
+    }
+}

crates/punktfunk-core/src/packet/tests.rs

@@ -579,3 +579,64 @@ fn rejects_wrong_shard_bytes_and_oversized_frame() {
         .is_none());
     assert_eq!(stats.snapshot().packets_dropped, 1);
 }
+
+/// Adaptive FEC raises `fec_percent` mid-session while the receiver's per-block acceptance
+/// ceiling is frozen at session construction and never renegotiated. A maximal block must
+/// therefore still land: the sender clamps its parity to the ceiling
+/// (`Packetizer::recovery_for`), and the receiver sizes that ceiling from the whole clamp range
+/// rather than the start percentage. Regression guard for the wedge this caused — every packet
+/// of a large block failing `total > max_total_shards`, so the frame never completed and the
+/// resulting loss drove adaptive FEC higher still.
+#[test]
+fn adaptive_fec_ramp_keeps_maximal_blocks_within_the_peers_ceiling() {
+    let cfg = e2e_config(FecScheme::Gf16, 10);
+    let coder = coder_for(FecScheme::Gf16);
+    let lim = ReassemblerLimits::from_config(&cfg);
+    let mut pk = Packetizer::new(&cfg);
+
+    // Ramp far past the negotiated 10% — exactly what `apply_fec_target` does under loss.
+    pk.set_fec_percent(50);
+
+    // A frame of full `max_data_per_block` blocks: where the ceiling actually binds.
+    let frame_len = cfg.shard_payload * cfg.fec.max_data_per_block as usize * 2;
+    let src: Vec<u8> = (0..frame_len).map(|i| (i * 131 + 7) as u8).collect();
+    let pkts = pk.packetize(&src, 1, 0, coder.as_ref()).unwrap();
+
+    let k = cfg.fec.max_data_per_block as usize;
+    let mut clamped = false;
+    for p in &pkts {
+        let hdr = PacketHeader::read_from_bytes(&p[..HEADER_LEN]).unwrap();
+        let total = hdr.data_shards as usize + hdr.recovery_shards as usize;
+        assert!(
+            total <= lim.max_total_shards,
+            "block total {total} exceeds the peer's ceiling {} — every packet of this block \
+             would be dropped",
+            lim.max_total_shards
+        );
+        // The unclamped 50% would put 2 parity on a full block; the negotiated 10% ceiling
+        // leaves room for 1. Proves the clamp actually bound rather than passing vacuously.
+        if hdr.data_shards as usize == k {
+            assert!(
+                (hdr.recovery_shards as usize) < cfg.fec.recovery_for(k).max(1) + 1,
+                "parity must be clamped to the peer's ceiling"
+            );
+            clamped = true;
+        }
+    }
+    assert!(clamped, "test must exercise a maximal block");
+
+    // And the frame still reassembles byte-identically.
+    let mut r = Reassembler::new(lim);
+    let stats = StatsCounters::default();
+    let mut got = None;
+    for p in &pkts {
+        if let Some(f) = r.push(p, coder.as_ref(), &stats).unwrap() {
+            got = Some(f);
+        }
+    }
+    assert_eq!(
+        got.expect("frame must complete after an adaptive-FEC ramp")
+            .data,
+        src
+    );
+}

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

@@ -91,8 +91,13 @@ pub fn resolve_codec(client_codecs: u8, host_capable: u8, preferred: u8) -> Opti
         return None;
     }
     // Honor the client's preference when the host can also emit it; else fall back to precedence.
+    // `preferred` is a single-bit field by contract but arrives as a raw wire byte — isolate ONE
+    // bit of the intersection instead of echoing the request, so a non-conformant multi-bit
+    // value can never escape as a codec id (downstream `from_wire` folds unknown values to HEVC,
+    // which may not even be in the shared set).
     if preferred != 0 && shared & preferred != 0 {
-        return Some(preferred);
+        let want = shared & preferred;
+        return Some(want & want.wrapping_neg());
     }
     // Precedence: HEVC > AV1 > H.264.
     [CODEC_HEVC, CODEC_AV1, CODEC_H264]
@@ -171,3 +176,75 @@ impl Default for ColorInfo {
         Self::SDR_BT709
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::config::{CompositorPref, FecConfig, FecScheme, GamepadPref, Mode};
+    use crate::quic::*;
+
+    #[test]
+    fn host_cap_clipboard_bit_is_distinct_and_survives_welcome() {
+        // The new cap packs into the existing trailing host_caps byte with no layout change.
+        assert_ne!(HOST_CAP_CLIPBOARD, HOST_CAP_GAMEPAD_STATE);
+        let mut w = Welcome {
+            abi_version: 1,
+            udp_port: 1,
+            mode: Mode {
+                width: 1920,
+                height: 1080,
+                refresh_hz: 60,
+            },
+            fec: FecConfig {
+                scheme: FecScheme::Gf16,
+                fec_percent: 0,
+                max_data_per_block: 1024,
+            },
+            shard_payload: 1024,
+            encrypt: false,
+            key: [0; 16],
+            salt: [0; 4],
+            frames: 0,
+            compositor: CompositorPref::Auto,
+            gamepad: GamepadPref::Auto,
+            bitrate_kbps: 0,
+            bit_depth: 8,
+            color: ColorInfo::SDR_BT709,
+            chroma_format: CHROMA_IDC_420,
+            audio_channels: 2,
+            codec: CODEC_HEVC,
+            host_caps: HOST_CAP_GAMEPAD_STATE | HOST_CAP_CLIPBOARD,
+        };
+        let got = Welcome::decode(&w.encode()).unwrap();
+        assert_eq!(got.host_caps & HOST_CAP_CLIPBOARD, HOST_CAP_CLIPBOARD);
+        assert_eq!(
+            got.host_caps & HOST_CAP_GAMEPAD_STATE,
+            HOST_CAP_GAMEPAD_STATE
+        );
+        // Clipboard-off host: the bit is clear, gamepad bit still set.
+        w.host_caps = HOST_CAP_GAMEPAD_STATE;
+        assert_eq!(
+            Welcome::decode(&w.encode()).unwrap().host_caps & HOST_CAP_CLIPBOARD,
+            0
+        );
+    }
+
+    #[test]
+    fn resolve_codec_canonicalizes_a_multi_bit_preference() {
+        // A non-conformant peer may stuff its capability MASK into `preferred` — the result
+        // must still be a single bit of the shared set, never the raw multi-bit echo (which
+        // folds to HEVC downstream and can select a codec the client can't decode).
+        assert_eq!(
+            resolve_codec(CODEC_H264, CODEC_H264 | CODEC_AV1, CODEC_H264 | CODEC_AV1),
+            Some(CODEC_H264)
+        );
+        // Several shared preferred bits: still exactly one bit, and one of the preferred ones.
+        let got = resolve_codec(
+            CODEC_H264 | CODEC_HEVC | CODEC_AV1,
+            CODEC_H264 | CODEC_HEVC | CODEC_AV1,
+            CODEC_AV1 | CODEC_HEVC,
+        )
+        .unwrap();
+        assert_eq!(got.count_ones(), 1);
+        assert_ne!(got & (CODEC_AV1 | CODEC_HEVC), 0);
+    }
+}

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

@@ -115,3 +115,134 @@ pub async fn read_data(recv: &mut quinn::RecvStream, max_bytes: usize) -> std::i
         .await
         .map_err(std::io::Error::other)
 }
+
+// In-process QUIC loopback: the real clipstream fetch transport, both success and cancel.
+#[cfg(test)]
+mod tests {
+    use crate::quic::clipstream;
+    use crate::quic::test_util::connect_pair;
+    use crate::quic::*;
+
+    #[tokio::test]
+    async fn fetch_text_transfers_then_cancel_resets() {
+        let (_server_ep, _client_ep, host_conn, client_conn) = connect_pair().await;
+
+        let payload = b"hello clipboard \xf0\x9f\x93\x8b".to_vec(); // text + a 4-byte emoji
+        let holder_payload = payload.clone();
+
+        // Holder = the host side: accept two fetch streams. Serve the first; cancel the second.
+        let holder = tokio::spawn(async move {
+            // Fetch #1 — serve the payload.
+            let (mut send, mut recv) = host_conn.accept_bi().await.expect("accept fetch #1");
+            let kind = clipstream::read_stream_header(&mut recv)
+                .await
+                .expect("stream header #1");
+            assert_eq!(kind, clipstream::CLIP_STREAM_KIND_FETCH);
+            let req = clipstream::read_fetch(&mut recv)
+                .await
+                .expect("fetch req #1");
+            assert_eq!(req.seq, 1);
+            assert_eq!(req.file_index, CLIP_FILE_INDEX_NONE);
+            assert_eq!(req.mime, "text/plain;charset=utf-8");
+            clipstream::write_fetch_hdr(
+                &mut send,
+                &ClipFetchHdr {
+                    status: CLIP_FETCH_OK,
+                    total_size: holder_payload.len() as u64,
+                },
+            )
+            .await
+            .expect("write hdr #1");
+            clipstream::write_data(&mut send, &holder_payload)
+                .await
+                .expect("write data #1");
+
+            // Fetch #2 — read the request, then cancel mid-transfer with RESET_STREAM.
+            let (mut send2, mut recv2) = host_conn.accept_bi().await.expect("accept fetch #2");
+            clipstream::read_stream_header(&mut recv2)
+                .await
+                .expect("stream header #2");
+            let _ = clipstream::read_fetch(&mut recv2)
+                .await
+                .expect("fetch req #2");
+            send2.reset(clipstream::cancelled_code()).unwrap();
+
+            host_conn // keep alive until the requester side is done
+        });
+
+        // Requester = the client side.
+        // #1: full lazy fetch of the text payload.
+        let req = ClipFetch {
+            seq: 1,
+            file_index: CLIP_FILE_INDEX_NONE,
+            mime: "text/plain;charset=utf-8".into(),
+        };
+        let (_send, mut recv) = clipstream::open_fetch(&client_conn, &req)
+            .await
+            .expect("open fetch #1");
+        let hdr = clipstream::read_fetch_hdr(&mut recv)
+            .await
+            .expect("read hdr #1");
+        assert_eq!(hdr.status, CLIP_FETCH_OK);
+        assert_eq!(hdr.total_size as usize, payload.len());
+        let got = clipstream::read_data(&mut recv, 8 << 20)
+            .await
+            .expect("read data #1");
+        assert_eq!(got, payload);
+
+        // #2: the holder resets the stream — the requester surfaces an error rather than hanging.
+        let req2 = ClipFetch {
+            seq: 2,
+            file_index: CLIP_FILE_INDEX_NONE,
+            mime: "text/plain;charset=utf-8".into(),
+        };
+        let (_send2, mut recv2) = clipstream::open_fetch(&client_conn, &req2)
+            .await
+            .expect("open fetch #2");
+        assert!(
+            clipstream::read_fetch_hdr(&mut recv2).await.is_err(),
+            "a cancelled fetch must surface as an error, not a hang"
+        );
+
+        let _host_conn = holder.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn read_data_enforces_size_cap() {
+        let (_server_ep, _client_ep, host_conn, client_conn) = connect_pair().await;
+
+        let big = vec![0xABu8; 200_000]; // > the 64 KiB chunk, and > the cap we set below
+        let holder_payload = big.clone();
+        let holder = tokio::spawn(async move {
+            let (mut send, mut recv) = host_conn.accept_bi().await.expect("accept");
+            clipstream::read_stream_header(&mut recv).await.unwrap();
+            let _ = clipstream::read_fetch(&mut recv).await.unwrap();
+            clipstream::write_fetch_hdr(
+                &mut send,
+                &ClipFetchHdr {
+                    status: CLIP_FETCH_OK,
+                    total_size: holder_payload.len() as u64,
+                },
+            )
+            .await
+            .unwrap();
+            let _ = clipstream::write_data(&mut send, &holder_payload).await;
+            host_conn
+        });
+
+        let req = ClipFetch {
+            seq: 1,
+            file_index: CLIP_FILE_INDEX_NONE,
+            mime: "application/octet-stream".into(),
+        };
+        let (_send, mut recv) = clipstream::open_fetch(&client_conn, &req).await.unwrap();
+        assert_eq!(
+            clipstream::read_fetch_hdr(&mut recv).await.unwrap().status,
+            CLIP_FETCH_OK
+        );
+        // Cap below the payload size ⇒ read_data errors instead of buffering unboundedly.
+        assert!(clipstream::read_data(&mut recv, 64 * 1024).await.is_err());
+
+        let _host_conn = holder.await.unwrap();
+    }
+}

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

@@ -38,7 +38,7 @@ pub struct ClockSkew {
 /// with, so the offset aligns a client receive instant to the host's capture clock.
 pub async fn clock_sync(
     send: &mut quinn::SendStream,
-    recv: &mut quinn::RecvStream,
+    recv: &mut io::MsgReader,
 ) -> Option<ClockSkew> {
     use std::time::Duration;
     const ROUNDS: usize = 8;
@@ -50,7 +50,7 @@ pub async fn clock_sync(
         if io::write_msg(send, &probe).await.is_err() {
             break;
         }
-        let read = tokio::time::timeout(read_timeout, io::read_msg(recv)).await;
+        let read = tokio::time::timeout(read_timeout, recv.read_msg()).await;
         let echo = match read {
             Ok(Ok(b)) => match ClockEcho::decode(&b) {
                 Ok(e) => e,
@@ -154,3 +154,115 @@ impl Default for ClockResync {
 pub fn accept_resync(batch_rtt_ns: u64, connect_rtt_ns: u64) -> bool {
     batch_rtt_ns <= (connect_rtt_ns + connect_rtt_ns / 2).max(2_000_000)
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::quic::*;
+
+    #[test]
+    fn clock_offset_picks_min_rtt_and_recovers_offset() {
+        // Host clock is +1_000_000 ns ahead of the client. Construct samples where a symmetric
+        // round-trip recovers exactly that offset, and a noisy (asymmetric, high-RTT) sample is
+        // present but must be ignored by the min-RTT selection.
+        const OFF: i64 = 1_000_000;
+        // Clean sample: client t1=0, one-way=200µs each way → t2 = t1 + 200_000 + OFF (host clock),
+        // t3 = t2 + 50_000 (host processing), t4 = t3 - OFF + 200_000 (back in client clock).
+        let t1 = 0u64;
+        let t2 = (t1 as i64 + 200_000 + OFF) as u64;
+        let t3 = t2 + 50_000;
+        let t4 = (t3 as i64 - OFF + 200_000) as u64;
+        // Noisy sample: same offset but a fat, asymmetric RTT (slow return path) — higher RTT.
+        let n1 = 1_000_000u64;
+        let n2 = (n1 as i64 + 200_000 + OFF) as u64;
+        let n3 = n2 + 50_000;
+        let n4 = (n3 as i64 - OFF + 5_000_000) as u64; // 5 ms return → big RTT
+        let (offset, rtt) =
+            clock_offset_ns(&[(n1, n2, n3, n4), (t1, t2, t3, t4)]).expect("non-empty");
+        // The min-RTT sample recovers the offset exactly; its RTT is 2x200us, and the noisy
+        // (asymmetric, 5 ms return) sample is ignored by the min-RTT selection.
+        assert_eq!(offset, OFF);
+        assert_eq!(rtt, 400_000);
+        assert!(clock_offset_ns(&[]).is_none());
+    }
+
+    /// The mid-stream re-sync state machine: 8 rounds collected via matched echoes, stale
+    /// echoes ignored, a restarted batch abandons the old one, and the batch result is the
+    /// min-RTT estimate — the exact behavior the connect-time `clock_sync` loop has.
+    #[test]
+    fn clock_resync_collects_rounds_and_ignores_stale_echoes() {
+        // Host clock +1 ms ahead; symmetric 100 µs one-way paths except one congested round.
+        const OFF: i64 = 1_000_000;
+        let echo_for = |t1: u64, one_way: u64| ClockEcho {
+            t1_ns: t1,
+            t2_ns: (t1 as i64 + one_way as i64 + OFF) as u64,
+            t3_ns: (t1 as i64 + one_way as i64 + OFF) as u64 + 10_000,
+        };
+        let t4_for = |e: &ClockEcho, one_way: u64| (e.t3_ns as i64 - OFF + one_way as i64) as u64;
+
+        let mut rs = ClockResync::new();
+        // An unsolicited echo before any batch is ignored.
+        assert_eq!(
+            rs.on_echo(&echo_for(42, 100_000), 500_000),
+            ResyncStep::Idle
+        );
+
+        let mut probe = rs.begin(1_000_000);
+        // A stale echo (wrong t1: the abandoned pre-begin probe) is ignored mid-batch.
+        assert_eq!(
+            rs.on_echo(&echo_for(42, 100_000), 500_000),
+            ResyncStep::Idle
+        );
+        for round in 0..ClockResync::ROUNDS {
+            // Round 3 is congested (5 ms one-way) — it must lose the min-RTT selection.
+            let one_way = if round == 3 { 5_000_000 } else { 100_000 };
+            let echo = echo_for(probe.t1_ns, one_way);
+            let t4 = t4_for(&echo, one_way);
+            match rs.on_echo(&echo, t4) {
+                ResyncStep::Probe(p) => {
+                    assert!(round < ClockResync::ROUNDS - 1, "batch overran its rounds");
+                    probe = p;
+                }
+                ResyncStep::Done { offset_ns, rtt_ns } => {
+                    assert_eq!(round, ClockResync::ROUNDS - 1, "batch ended early");
+                    assert_eq!(offset_ns, OFF, "min-RTT round recovers the offset exactly");
+                    assert_eq!(rtt_ns, 200_000); // 2×100 µs; host processing (t3−t2) excluded
+                }
+                ResyncStep::Idle => panic!("matched echo must advance the batch"),
+            }
+        }
+        // The batch is done: even a matching-t1 replay no longer advances anything.
+        assert_eq!(
+            rs.on_echo(&echo_for(probe.t1_ns, 100_000), probe.t1_ns + 300_000),
+            ResyncStep::Idle
+        );
+
+        // begin() mid-batch abandons the in-flight batch: its echo is stale afterwards.
+        let old = rs.begin(2_000_000);
+        let fresh = rs.begin(3_000_000);
+        assert_eq!(
+            rs.on_echo(&echo_for(old.t1_ns, 100_000), 2_300_000),
+            ResyncStep::Idle
+        );
+        assert!(matches!(
+            rs.on_echo(&echo_for(fresh.t1_ns, 100_000), 3_300_000),
+            ResyncStep::Probe(_)
+        ));
+    }
+
+    /// The acceptance guard: a batch measured through a congested window (fat RTT) must not
+    /// replace the offset — its queueing delay biases the estimate exactly when frames
+    /// already read late. Floor of 2 ms so a near-zero connect RTT (same-host/LAN) doesn't
+    /// reject every later batch over normal jitter.
+    #[test]
+    fn clock_resync_acceptance_guard() {
+        // Generous connect RTT (10 ms): accept up to 1.5×.
+        assert!(accept_resync(14_000_000, 10_000_000));
+        assert!(!accept_resync(16_000_000, 10_000_000));
+        // Tiny connect RTT (200 µs, wired LAN): the 2 ms floor governs.
+        assert!(accept_resync(1_900_000, 200_000));
+        assert!(!accept_resync(2_100_000, 200_000));
+        // Boundary: exactly at the bound is accepted.
+        assert!(accept_resync(2_000_000, 0));
+        assert!(accept_resync(15_000_000, 10_000_000));
+    }
+}

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

@@ -782,3 +782,369 @@ impl ClipFetchHdr {
         })
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::config::Mode;
+    use crate::quic::*;
+
+    #[test]
+    fn reconfigure_roundtrip() {
+        let rq = Reconfigure {
+            mode: Mode {
+                width: 1920,
+                height: 1080,
+                refresh_hz: 144,
+            },
+        };
+        assert_eq!(Reconfigure::decode(&rq.encode()).unwrap(), rq);
+        for accepted in [true, false] {
+            let rs = Reconfigured {
+                accepted,
+                mode: rq.mode,
+            };
+            assert_eq!(Reconfigured::decode(&rs.encode()).unwrap(), rs);
+        }
+        // The type byte separates the post-handshake messages from each other.
+        assert!(Reconfigure::decode(
+            &Reconfigured {
+                accepted: true,
+                mode: rq.mode
+            }
+            .encode()
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn request_keyframe_roundtrip() {
+        let bytes = RequestKeyframe.encode();
+        assert!(RequestKeyframe::decode(&bytes).is_ok());
+        // Distinct from the other control messages — its type byte must not collide.
+        let mode = Mode {
+            width: 1280,
+            height: 720,
+            refresh_hz: 60,
+        };
+        assert!(RequestKeyframe::decode(&Reconfigure { mode }.encode()).is_err());
+        assert!(Reconfigure::decode(&bytes).is_err());
+        // Length is exact (no trailing bytes accepted).
+        assert!(RequestKeyframe::decode(&[bytes.as_slice(), &[0]].concat()).is_err());
+    }
+
+    #[test]
+    fn rfi_request_roundtrip() {
+        for (first_frame, last_frame) in [(0u32, 0u32), (40, 47), (5, 5), (1_000_000, u32::MAX)] {
+            let r = RfiRequest {
+                first_frame,
+                last_frame,
+            };
+            assert_eq!(RfiRequest::decode(&r.encode()).unwrap(), r);
+        }
+        // Disjoint from the bare keyframe request (its loss-unaware sibling) and others: type byte + length.
+        assert!(RfiRequest::decode(&RequestKeyframe.encode()).is_err());
+        assert!(RequestKeyframe::decode(
+            &RfiRequest {
+                first_frame: 1,
+                last_frame: 2
+            }
+            .encode()
+        )
+        .is_err());
+        // Exact length — no trailing bytes.
+        let bytes = RfiRequest {
+            first_frame: 3,
+            last_frame: 9,
+        }
+        .encode();
+        assert!(RfiRequest::decode(&[bytes.as_slice(), &[0]].concat()).is_err());
+        assert!(RfiRequest::decode(&bytes[..bytes.len() - 1]).is_err());
+    }
+
+    #[test]
+    fn loss_report_roundtrip() {
+        for loss_ppm in [0u32, 1, 12_345, 50_000, 1_000_000] {
+            let r = LossReport { loss_ppm };
+            assert_eq!(LossReport::decode(&r.encode()).unwrap(), r);
+        }
+        // Disjoint from the other control messages (type byte + length).
+        assert!(LossReport::decode(&RequestKeyframe.encode()).is_err());
+        assert!(RequestKeyframe::decode(&LossReport { loss_ppm: 0 }.encode()).is_err());
+        assert!(LossReport::decode(
+            &[LossReport { loss_ppm: 0 }.encode().as_slice(), &[0]].concat()
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn window_loss_ppm_estimates_and_caps() {
+        // No traffic → 0. A clean window (nothing recovered) → 0.
+        assert_eq!(window_loss_ppm(0, 0, 0, 0), 0);
+        assert_eq!(window_loss_ppm(0, 0, 1000, 0), 0);
+        // 50 recovered of 1000 total (950 received + 50 recovered) = 5%.
+        assert_eq!(window_loss_ppm(50, 0, 950, 0), 50_000);
+        // An unrecoverable frame adds the +5% bump (push FEC past the current cap).
+        assert_eq!(window_loss_ppm(50, 0, 950, 1), 100_000);
+        // A total-loss window with a drop but nothing received still reports the bump, capped at 1e6.
+        assert_eq!(window_loss_ppm(0, 0, 0, 3), 50_000);
+        assert!(window_loss_ppm(u64::MAX, 0, 1, 9) <= 1_000_000);
+        // Reordering: shards "recovered" early that then arrived are late, not lost — netted out, so
+        // a pure-reorder window reads 0. Partially late nets to the true loss (20 of 1000 = 2%).
+        assert_eq!(window_loss_ppm(50, 50, 1000, 0), 0);
+        assert_eq!(window_loss_ppm(50, 30, 980, 0), 20_000);
+        // `late` can outrun `recovered` across a window boundary (reorder straddling the report
+        // tick) or via a rare wire duplicate — saturate at a clean window, never underflow.
+        assert_eq!(window_loss_ppm(10, 25, 1000, 0), 0);
+    }
+
+    #[test]
+    fn bitrate_messages_roundtrip() {
+        let req = SetBitrate {
+            bitrate_kbps: 14_000,
+        };
+        assert_eq!(SetBitrate::decode(&req.encode()).unwrap(), req);
+        let ack = BitrateChanged {
+            bitrate_kbps: 14_000,
+        };
+        assert_eq!(BitrateChanged::decode(&ack.encode()).unwrap(), ack);
+        // Same payload shape as LossReport — the type byte alone must keep them disjoint.
+        assert!(LossReport::decode(&req.encode()).is_err());
+        assert!(SetBitrate::decode(&ack.encode()).is_err());
+        assert!(BitrateChanged::decode(&req.encode()).is_err());
+        assert!(SetBitrate::decode(&LossReport { loss_ppm: 7 }.encode()).is_err());
+    }
+
+    #[test]
+    fn probe_messages_roundtrip() {
+        let req = ProbeRequest {
+            target_kbps: 250_000,
+            duration_ms: 2000,
+        };
+        assert_eq!(ProbeRequest::decode(&req.encode()).unwrap(), req);
+        let res = ProbeResult {
+            bytes_sent: 62_500_000,
+            packets_sent: 480,
+            duration_ms: 2003,
+            wire_packets_sent: 41_000,
+            send_dropped: 1_200,
+        };
+        assert_eq!(ProbeResult::decode(&res.encode()).unwrap(), res);
+        assert_eq!(res.encode().len(), 29);
+        // A pre-wire-stats host's 21-byte ProbeResult still decodes, with the new fields zeroed.
+        let legacy = {
+            let full = res.encode();
+            full[..21].to_vec()
+        };
+        let decoded = ProbeResult::decode(&legacy).unwrap();
+        assert_eq!(decoded.wire_packets_sent, 0);
+        assert_eq!(decoded.send_dropped, 0);
+        assert_eq!(decoded.bytes_sent, res.bytes_sent);
+        // Type bytes keep the control messages disjoint from each other.
+        assert!(ProbeRequest::decode(&res.encode()).is_err());
+        assert!(Reconfigure::decode(&req.encode()).is_err());
+        assert!(ProbeResult::decode(&req.encode()).is_err());
+    }
+
+    #[test]
+    fn clock_messages_roundtrip() {
+        let probe = ClockProbe {
+            t1_ns: 1_700_000_000_123,
+        };
+        assert_eq!(ClockProbe::decode(&probe.encode()).unwrap(), probe);
+        let echo = ClockEcho {
+            t1_ns: 1_700_000_000_123,
+            t2_ns: 1_700_000_050_456,
+            t3_ns: 1_700_000_050_789,
+        };
+        assert_eq!(ClockEcho::decode(&echo.encode()).unwrap(), echo);
+        // Disjoint from the other control messages (distinct type bytes).
+        assert!(ClockProbe::decode(&echo.encode()).is_err());
+        assert!(ProbeRequest::decode(&probe.encode()).is_err());
+        assert!(ClockEcho::decode(&probe.encode()).is_err());
+    }
+
+    // ---- Shared clipboard control + fetch-stream message codecs (0x40-0x44) -----------------------
+
+    #[test]
+    fn clip_control_roundtrip() {
+        for (enabled, flags) in [
+            (true, 0u8),
+            (false, 0),
+            (true, CLIP_FLAG_FILES),
+            (false, 0xFF),
+        ] {
+            let m = ClipControl { enabled, flags };
+            assert_eq!(ClipControl::decode(&m.encode()).unwrap(), m);
+        }
+        // Disjoint from its host→client sibling (type byte + length) and exact length.
+        assert!(ClipControl::decode(
+            &ClipState {
+                enabled: true,
+                policy: 0,
+                reason: 0
+            }
+            .encode()
+        )
+        .is_err());
+        let bytes = ClipControl {
+            enabled: true,
+            flags: 0,
+        }
+        .encode();
+        assert!(ClipControl::decode(&[bytes.as_slice(), &[0]].concat()).is_err());
+        assert!(ClipControl::decode(&bytes[..bytes.len() - 1]).is_err());
+    }
+
+    #[test]
+    fn clip_state_roundtrip() {
+        let cases = [
+            ClipState {
+                enabled: true,
+                policy: CLIP_POLICY_TEXT | CLIP_POLICY_FILES,
+                reason: CLIP_REASON_OK,
+            },
+            ClipState {
+                enabled: false,
+                policy: 0,
+                reason: CLIP_REASON_BACKEND_UNAVAILABLE,
+            },
+            ClipState {
+                enabled: true,
+                policy: CLIP_POLICY_TEXT,
+                reason: CLIP_REASON_NO_FILES,
+            },
+        ];
+        for m in cases {
+            assert_eq!(ClipState::decode(&m.encode()).unwrap(), m);
+        }
+        // A ClipControl must not decode as a ClipState (type byte).
+        assert!(ClipState::decode(
+            &ClipControl {
+                enabled: true,
+                flags: 0
+            }
+            .encode()
+        )
+        .is_err());
+        let bytes = cases[0].encode();
+        assert!(ClipState::decode(&bytes[..bytes.len() - 1]).is_err());
+    }
+
+    #[test]
+    fn clip_offer_roundtrip() {
+        // Empty offer, one kind, and a full multi-format offer (text/rich/image/files).
+        let cases = [
+            ClipOffer {
+                seq: 0,
+                kinds: vec![],
+            },
+            ClipOffer {
+                seq: 1,
+                kinds: vec![ClipKind {
+                    mime: "text/plain;charset=utf-8".into(),
+                    size_hint: 12,
+                }],
+            },
+            ClipOffer {
+                seq: u32::MAX,
+                kinds: vec![
+                    ClipKind {
+                        mime: "text/plain;charset=utf-8".into(),
+                        size_hint: 0,
+                    },
+                    ClipKind {
+                        mime: "text/html".into(),
+                        size_hint: 4096,
+                    },
+                    ClipKind {
+                        mime: "image/png".into(),
+                        size_hint: 1 << 30,
+                    },
+                    ClipKind {
+                        mime: "application/x-punktfunk-files".into(),
+                        size_hint: 5_000_000_000,
+                    },
+                ],
+            },
+        ];
+        for m in &cases {
+            assert_eq!(&ClipOffer::decode(&m.encode()).unwrap(), m);
+        }
+        // Trailing bytes are rejected (get_clip_kind consumes exactly to the end).
+        let mut padded = cases[1].encode();
+        padded.push(0);
+        assert!(ClipOffer::decode(&padded).is_err());
+        // A count byte over the cap is rejected before allocating.
+        let mut over = cases[0].encode();
+        over[9] = (CLIP_MAX_KINDS + 1) as u8;
+        assert!(ClipOffer::decode(&over).is_err());
+        // Disjoint from a same-family control message.
+        assert!(ClipOffer::decode(
+            &ClipControl {
+                enabled: true,
+                flags: 0
+            }
+            .encode()
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn clip_fetch_roundtrip() {
+        let cases = [
+            ClipFetch {
+                seq: 1,
+                file_index: CLIP_FILE_INDEX_NONE,
+                mime: "text/plain;charset=utf-8".into(),
+            },
+            ClipFetch {
+                seq: 7,
+                file_index: 0,
+                mime: "application/x-punktfunk-files".into(),
+            },
+            ClipFetch {
+                seq: u32::MAX,
+                file_index: 41,
+                mime: String::new(),
+            },
+        ];
+        for m in &cases {
+            assert_eq!(&ClipFetch::decode(&m.encode()).unwrap(), m);
+        }
+        // Trailing + truncation both rejected (exact-length mime check).
+        let bytes = cases[0].encode();
+        assert!(ClipFetch::decode(&[bytes.as_slice(), &[0]].concat()).is_err());
+        assert!(ClipFetch::decode(&bytes[..bytes.len() - 1]).is_err());
+        // A fetch-stream message must not decode as a control-stream offer, and vice-versa.
+        assert!(ClipOffer::decode(&cases[0].encode()).is_err());
+        assert!(ClipFetch::decode(
+            &ClipOffer {
+                seq: 1,
+                kinds: vec![]
+            }
+            .encode()
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn clip_fetch_hdr_roundtrip() {
+        for (status, total_size) in [
+            (CLIP_FETCH_OK, 15u64),
+            (CLIP_FETCH_STALE, 0),
+            (CLIP_FETCH_UNAVAILABLE, 0),
+            (CLIP_FETCH_DENIED, 0),
+            (CLIP_FETCH_OK, u64::MAX),
+        ] {
+            let m = ClipFetchHdr { status, total_size };
+            assert_eq!(ClipFetchHdr::decode(&m.encode()).unwrap(), m);
+        }
+        let bytes = ClipFetchHdr {
+            status: CLIP_FETCH_OK,
+            total_size: 1,
+        }
+        .encode();
+        assert!(ClipFetchHdr::decode(&[bytes.as_slice(), &[0]].concat()).is_err());
+        assert!(ClipFetchHdr::decode(&bytes[..bytes.len() - 1]).is_err());
+    }
+}

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

@@ -605,3 +605,321 @@ pub fn decode_host_timing_datagram(b: &[u8]) -> Option<HostTiming> {
         stages,
     })
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::quic::*;
+
+    #[test]
+    fn hdr_meta_datagram_roundtrip_and_truncation() {
+        let m = HdrMeta {
+            // BT.2020 display primaries in 1/50000 units (the DXGI/ST.2086 reference values).
+            display_primaries: [[8500, 39850], [6550, 2300], [35400, 14600]],
+            white_point: [15635, 16450],                 // D65
+            max_display_mastering_luminance: 10_000_000, // 1000 nits in 0.0001 cd/m²
+            min_display_mastering_luminance: 1,          // 0.0001 nits
+            max_cll: 1000,
+            max_fall: 400,
+        };
+        let d = encode_hdr_meta_datagram(&m);
+        assert_eq!(d[0], HDR_META_MAGIC);
+        assert_eq!(decode_hdr_meta_datagram(&d), Some(m));
+        // Truncated buffers and a wrong tag are rejected (never partially read).
+        for n in 0..d.len() {
+            assert_eq!(decode_hdr_meta_datagram(&d[..n]), None);
+        }
+        let mut bad = d.clone();
+        bad[0] = HIDOUT_MAGIC;
+        assert_eq!(decode_hdr_meta_datagram(&bad), None);
+    }
+
+    #[test]
+    fn host_timing_datagram_roundtrip_and_truncation() {
+        let t = HostTiming {
+            pts_ns: 1_751_500_000_123_456_789, // a realistic 2026 CLOCK_REALTIME capture stamp
+            host_us: 4_321,
+            stages: None,
+        };
+        let d = encode_host_timing_datagram(&t);
+        assert_eq!(d[0], HOST_TIMING_MAGIC);
+        assert_eq!(d.len(), 13);
+        assert_eq!(decode_host_timing_datagram(&d), Some(t));
+        // Truncated buffers and a wrong tag are rejected (never partially read).
+        for n in 0..d.len() {
+            assert_eq!(decode_host_timing_datagram(&d[..n]), None);
+        }
+        let mut bad = d.clone();
+        bad[0] = HDR_META_MAGIC;
+        assert_eq!(decode_host_timing_datagram(&bad), None);
+
+        // Extended form (T0.1): the stage tail roundtrips; a truncated tail (an old host's 13-byte
+        // datagram, or anything short of the full 25) degrades to `stages: None`, never a partial
+        // read; the prefix fields stay identical in both forms (the append-extensibility contract).
+        let ts = HostTiming {
+            stages: Some(HostStages {
+                queue_us: 900,
+                encode_us: 3_100,
+                pace_us: 2_500,
+            }),
+            ..t
+        };
+        let ds = encode_host_timing_datagram(&ts);
+        assert_eq!(ds.len(), 25);
+        assert_eq!(
+            &ds[..13],
+            &d[..13],
+            "prefix is byte-identical to the legacy form"
+        );
+        assert_eq!(decode_host_timing_datagram(&ds), Some(ts));
+        for n in 13..ds.len() {
+            assert_eq!(
+                decode_host_timing_datagram(&ds[..n]),
+                Some(t),
+                "partial stage tail ({n} B) must degrade to the legacy decode"
+            );
+        }
+    }
+
+    #[test]
+    fn audio_datagram_roundtrip() {
+        let opus = [0x42u8; 97];
+        let d = encode_audio_datagram(7, 1_000_000_123, &opus);
+        assert_eq!(d[0], AUDIO_MAGIC);
+        let (seq, pts, payload) = decode_audio_datagram(&d).unwrap();
+        assert_eq!((seq, pts), (7, 1_000_000_123));
+        assert_eq!(payload, opus);
+        assert!(decode_audio_datagram(&d[..12]).is_none()); // truncated header
+        assert!(decode_audio_datagram(&[0u8; 13]).is_none()); // bad magic
+
+        // Empty payload is legal (DTX) — header-only datagram.
+        let header_only = encode_audio_datagram(0, 0, &[]);
+        let (_, _, empty) = decode_audio_datagram(&header_only).unwrap();
+        assert!(empty.is_empty());
+    }
+
+    #[test]
+    fn rumble_datagram_roundtrip() {
+        let d = encode_rumble_datagram(1, 0x1234, 0xFFFF);
+        assert_eq!(d[0], RUMBLE_MAGIC);
+        assert_eq!(decode_rumble_datagram(&d), Some((1, 0x1234, 0xFFFF)));
+        assert!(decode_rumble_datagram(&d[..6]).is_none());
+    }
+
+    #[test]
+    fn rumble_envelope_roundtrip_and_legacy_tolerance() {
+        // v2 envelope round-trips seq + ttl.
+        let d = encode_rumble_datagram_v2(2, 0x4000, 0x8000, 7, 400);
+        assert_eq!(d[0], RUMBLE_MAGIC);
+        assert_eq!(d.len(), RUMBLE_V2_LEN);
+        assert_eq!(
+            decode_rumble_envelope(&d),
+            Some(RumbleUpdate {
+                pad: 2,
+                low: 0x4000,
+                high: 0x8000,
+                envelope: Some(RumbleEnvelope {
+                    seq: 7,
+                    ttl_ms: 400
+                }),
+            })
+        );
+        // The legacy level decoder reads a v2 datagram as a plain level — the tail is ignored, so an
+        // old client running against a new host still renders the right amplitudes.
+        assert_eq!(decode_rumble_datagram(&d), Some((2, 0x4000, 0x8000)));
+
+        // A legacy 7-byte datagram (old host) decodes as a level with no envelope — a new client then
+        // applies its own staleness policy.
+        let v1 = encode_rumble_datagram(3, 0x1111, 0x2222);
+        assert_eq!(
+            decode_rumble_envelope(&v1),
+            Some(RumbleUpdate {
+                pad: 3,
+                low: 0x1111,
+                high: 0x2222,
+                envelope: None,
+            })
+        );
+
+        // A torn/short tail (8 or 9 bytes) is not a valid envelope — degrade to a level, never panic
+        // or drop. (The host never emits these; a truncating middlebox might.)
+        assert_eq!(
+            decode_rumble_envelope(&d[..8]).map(|u| u.envelope),
+            Some(None)
+        );
+        assert_eq!(
+            decode_rumble_envelope(&d[..9]).map(|u| u.envelope),
+            Some(None)
+        );
+
+        // Bad tag / too short → None on both decoders.
+        assert!(decode_rumble_envelope(&d[..6]).is_none());
+        let mut wrong_tag = d;
+        wrong_tag[0] = AUDIO_MAGIC;
+        assert!(decode_rumble_envelope(&wrong_tag).is_none());
+    }
+
+    #[test]
+    fn rumble_envelope_seq_gate_drops_reordered_stale_start() {
+        use crate::input::GamepadSnapshot;
+        // The client-side reorder gate (reused verbatim from gamepad snapshots): a stale start
+        // arriving after a stop must not re-light the motors.
+        let stop = decode_rumble_envelope(&encode_rumble_datagram_v2(0, 0, 0, 10, 0)).unwrap();
+        let stale_start =
+            decode_rumble_envelope(&encode_rumble_datagram_v2(0, 0x8000, 0x8000, 9, 400)).unwrap();
+        let stop_seq = stop.envelope.unwrap().seq;
+        let stale_seq = stale_start.envelope.unwrap().seq;
+        // Nothing applied yet → the first update always passes.
+        assert!(GamepadSnapshot::seq_newer(stop_seq, None));
+        // The reordered older start does NOT supersede the stop.
+        assert!(!GamepadSnapshot::seq_newer(stale_seq, Some(stop_seq)));
+        // A genuine later renewal does.
+        assert!(GamepadSnapshot::seq_newer(11, Some(stop_seq)));
+        // Wraps: seq 1 supersedes 254.
+        assert!(GamepadSnapshot::seq_newer(1, Some(254)));
+    }
+
+    #[test]
+    fn mic_datagram_roundtrip_and_disjoint_from_audio() {
+        let opus = [0x5Au8; 80];
+        let d = encode_mic_datagram(42, 9_999, &opus);
+        assert_eq!(d[0], MIC_MAGIC);
+        let (seq, pts, payload) = decode_mic_datagram(&d).unwrap();
+        assert_eq!((seq, pts), (42, 9_999));
+        assert_eq!(payload, opus);
+        assert!(decode_mic_datagram(&d[..12]).is_none()); // truncated
+                                                          // Tag separation: a mic datagram is not an audio datagram and vice-versa.
+        assert!(decode_audio_datagram(&d).is_none());
+        assert!(decode_mic_datagram(&encode_audio_datagram(1, 2, &opus)).is_none());
+        // Empty payload (DTX) is legal.
+        assert!(decode_mic_datagram(&encode_mic_datagram(0, 0, &[]))
+            .unwrap()
+            .2
+            .is_empty());
+    }
+
+    #[test]
+    fn rich_input_roundtrip() {
+        for ev in [
+            RichInput::Touchpad {
+                pad: 1,
+                finger: 0,
+                active: true,
+                x: 40000,
+                y: 12345,
+            },
+            RichInput::Motion {
+                pad: 0,
+                gyro: [-100, 200, -300],
+                accel: [16384, -8192, 1],
+            },
+            RichInput::TouchpadEx {
+                pad: 2,
+                surface: 1,
+                finger: 1,
+                touch: true,
+                click: false,
+                x: -12345,
+                y: 30000,
+                pressure: 4000,
+            },
+        ] {
+            let d = ev.encode();
+            assert_eq!(d[0], RICH_INPUT_MAGIC);
+            assert_eq!(RichInput::decode(&d), Some(ev));
+        }
+        // A raw Triton state report rides the plane verbatim (as-is SC2 passthrough).
+        let mut data = [0u8; HID_REPORT_MAX];
+        data[0] = 0x42; // ID_TRITON_CONTROLLER_STATE
+        for (i, b) in data.iter_mut().enumerate().take(46).skip(1) {
+            *b = i as u8;
+        }
+        let raw = RichInput::HidReport {
+            pad: 3,
+            len: 46,
+            data,
+        };
+        let d = raw.encode();
+        assert_eq!(d.len(), 4 + 46); // tag + kind + pad + len + body — no fixed-array padding
+        assert_eq!(RichInput::decode(&d), Some(raw));
+        // A torn HidReport truncates to what arrived rather than over-reading (len clamps).
+        assert_eq!(
+            RichInput::decode(&d[..20]),
+            Some(RichInput::HidReport {
+                pad: 3,
+                len: 16,
+                data: {
+                    let mut t = [0u8; HID_REPORT_MAX];
+                    t[..16].copy_from_slice(&data[..16]);
+                    t
+                },
+            })
+        );
+        // Disjoint from the fixed input datagram (0xC8); unknown kind + truncation → None.
+        assert!(RichInput::decode(&[crate::input::INPUT_MAGIC; 18]).is_none());
+        assert!(RichInput::decode(&[RICH_INPUT_MAGIC, 0x7F]).is_none()); // unknown kind
+        assert!(RichInput::decode(&[RICH_INPUT_MAGIC, RICH_TOUCHPAD, 0]).is_none()); // short
+        assert!(RichInput::decode(&[RICH_INPUT_MAGIC, RICH_TOUCHPAD_EX, 0, 0, 0, 0]).is_none());
+        // short
+    }
+
+    #[test]
+    fn hid_output_roundtrip() {
+        let cases = [
+            HidOutput::Led {
+                pad: 2,
+                r: 0xAA,
+                g: 0xBB,
+                b: 0xCC,
+            },
+            HidOutput::PlayerLeds {
+                pad: 0,
+                bits: 0b10101,
+            },
+            HidOutput::Trigger {
+                pad: 1,
+                which: 1,
+                effect: vec![0x26, 0x90, 0xA0, 0xFF, 0x00, 0x00],
+            },
+            HidOutput::TrackpadHaptic {
+                pad: 0,
+                side: 1,
+                amplitude: 0x1234,
+                period: 0x5678,
+                count: 9,
+            },
+            // A raw Triton rumble output report (as-is SC2 passthrough, host→client).
+            HidOutput::HidRaw {
+                pad: 1,
+                kind: HID_RAW_OUTPUT,
+                data: vec![0x80, 0, 0, 0, 0x34, 0x12, 0, 0x78, 0x56, 0],
+            },
+            // A raw 64-byte feature report (lizard-off / IMU-enable settings write).
+            HidOutput::HidRaw {
+                pad: 0,
+                kind: HID_RAW_FEATURE,
+                data: {
+                    let mut f = vec![0u8; HID_REPORT_MAX];
+                    f[0] = 1; // Triton feature reports ride report id 1
+                    f[1] = 0x87; // ID_SET_SETTINGS_VALUES
+                    f
+                },
+            },
+        ];
+        for ev in &cases {
+            let d = ev.encode();
+            assert_eq!(d[0], HIDOUT_MAGIC);
+            assert_eq!(HidOutput::decode(&d).as_ref(), Some(ev));
+        }
+        assert!(HidOutput::decode(&[HIDOUT_MAGIC, 0x7F]).is_none()); // unknown kind
+                                                                     // A rich-input datagram is not a HID-output datagram.
+        assert!(HidOutput::decode(
+            &RichInput::Motion {
+                pad: 0,
+                gyro: [0; 3],
+                accel: [0; 3]
+            }
+            .encode()
+        )
+        .is_none());
+    }
+}

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

@@ -26,10 +26,12 @@ fn stream_transport() -> Arc<quinn::TransportConfig> {
 /// path is PINGed at least twice per window and a single lost PING (wifi roam / brief blip) won't
 /// false-close. `idle` is clamped to a ≥1s floor so a misconfigured tiny value can't tear live
 /// sessions down. Active sessions are unaffected either way: video keeps the connection live and
-/// the keep-alive holds it open through quiet control periods.
+/// the keep-alive holds it open through quiet control periods. Clamped to a 1 s..1 h window:
+/// the ceiling keeps an absurd operator-supplied value inside QUIC's VarInt millisecond range,
+/// so the conversion below genuinely cannot fail (it used to panic host startup instead).
 fn stream_transport_idle(idle: std::time::Duration) -> Arc<quinn::TransportConfig> {
     use std::time::Duration;
-    let idle = idle.max(Duration::from_secs(1));
+    let idle = idle.clamp(Duration::from_secs(1), Duration::from_secs(3600));
     let keep_alive = (idle / 2).min(Duration::from_secs(4));
     let mut t = quinn::TransportConfig::default();
     t.max_idle_timeout(Some(
@@ -293,3 +295,25 @@ impl rustls::server::danger::ClientCertVerifier for AcceptAnyClientCert {
             .supported_schemes()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::quic::endpoint;
+
+    #[test]
+    fn fingerprint_is_sha256_of_der() {
+        // Stable across calls, distinct for distinct certs.
+        let a = endpoint::cert_fingerprint(b"cert-a");
+        assert_eq!(a, endpoint::cert_fingerprint(b"cert-a"));
+        assert_ne!(a, endpoint::cert_fingerprint(b"cert-b"));
+    }
+
+    #[test]
+    fn absurd_idle_timeout_is_clamped_not_a_panic() {
+        // The conversion to quinn's IdleTimeout fails past the QUIC VarInt millisecond
+        // ceiling — an operator-supplied huge PUNKTFUNK_IDLE_TIMEOUT_MS used to panic host
+        // startup through the `expect`. Both extremes must construct.
+        let _ = super::stream_transport_idle(std::time::Duration::MAX);
+        let _ = super::stream_transport_idle(std::time::Duration::ZERO);
+    }
+}

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

@@ -182,8 +182,9 @@ pub struct Start {
 }
 
 /// Truncate `s` to at most `max` bytes on a UTF-8 char boundary (so a multi-byte char straddling
-/// the cap is dropped whole, never split). Shared by Hello's length-prefixed name/launch fields.
+/// the cap is dropped whole, never split). Shared by Hello's length-prefixed name/launch fields
-fn truncate_to(s: &str, max: usize) -> &str {
+/// and [`PairRequest`](super::PairRequest)'s copy of the same name cap.
+pub(super) fn truncate_to(s: &str, max: usize) -> &str {
     if s.len() <= max {
         return s;
     }
@@ -495,3 +496,601 @@ impl Start {
         })
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::config::{CompositorPref, FecConfig, FecScheme, GamepadPref, Mode, Role};
+    use crate::quic::*;
+
+    #[test]
+    fn welcome_roundtrip() {
+        let w = Welcome {
+            abi_version: 1,
+            udp_port: 9999,
+            mode: Mode {
+                width: 2560,
+                height: 1440,
+                refresh_hz: 240,
+            },
+            fec: FecConfig {
+                scheme: FecScheme::Gf16,
+                fec_percent: 20,
+                max_data_per_block: 4096,
+            },
+            shard_payload: 1200,
+            encrypt: true,
+            key: [7u8; 16],
+            salt: [1, 2, 3, 4],
+            frames: 600,
+            compositor: CompositorPref::Gamescope,
+            gamepad: GamepadPref::DualSense,
+            bitrate_kbps: 50_000,
+            bit_depth: 10,
+            color: ColorInfo::HDR10_BT2020_PQ,
+            chroma_format: CHROMA_IDC_444,
+            audio_channels: 2,
+            codec: CODEC_H264, // exercise a non-default codec through the roundtrip
+            host_caps: HOST_CAP_GAMEPAD_STATE,
+        };
+        assert_eq!(Welcome::decode(&w.encode()).unwrap(), w);
+
+        // Client-side reassembler ceiling derives from the negotiated rate: 4x the average frame at
+        // 50 Mbps/240 Hz is ~104 KB, so the 8 MiB floor governs. The host keeps the p1_defaults
+        // bound (it never reassembles video), as does a client of a bitrate-0 (older) host.
+        let cc = w.session_config(Role::Client);
+        assert_eq!(cc.max_frame_bytes, 8 << 20);
+        cc.validate().expect("derived client config validates");
+        assert_eq!(w.session_config(Role::Host).max_frame_bytes, 64 << 20);
+        let old_host = Welcome {
+            bitrate_kbps: 0,
+            ..w
+        };
+        assert_eq!(
+            old_host.session_config(Role::Client).max_frame_bytes,
+            64 << 20
+        );
+        // A high-rate mode scales past the floor: 1.5 Gbps at 60 Hz = 4 x 3.125 MB = 12.5 MB.
+        let fat = Welcome {
+            bitrate_kbps: 1_500_000,
+            mode: Mode {
+                width: 5120,
+                height: 1440,
+                refresh_hz: 60,
+            },
+            ..w
+        };
+        let derived = fat.session_config(Role::Client).max_frame_bytes;
+        assert_eq!(derived, 4 * 1_500_000 * 125 / 60);
+        assert!(derived > (8 << 20) && derived < (64 << 20));
+    }
+
+    #[test]
+    fn codec_negotiation_and_back_compat() {
+        // resolve_codec precedence (HEVC > AV1 > H.264), no preference (0).
+        assert_eq!(
+            resolve_codec(CODEC_H264 | CODEC_HEVC, CODEC_HEVC | CODEC_AV1, 0),
+            Some(CODEC_HEVC)
+        );
+        assert_eq!(
+            resolve_codec(CODEC_H264 | CODEC_AV1, CODEC_AV1 | CODEC_H264, 0),
+            Some(CODEC_AV1)
+        );
+        assert_eq!(resolve_codec(CODEC_H264, CODEC_H264, 0), Some(CODEC_H264));
+        // A software host (H.264 only) + an HEVC-only client share nothing → refuse.
+        assert_eq!(resolve_codec(CODEC_HEVC, CODEC_H264, 0), None);
+        // An older client (0 = no codec byte) is treated as HEVC-only.
+        assert_eq!(
+            resolve_codec(0, CODEC_HEVC | CODEC_H264, 0),
+            Some(CODEC_HEVC)
+        );
+        assert_eq!(resolve_codec(0, CODEC_H264, 0), None);
+
+        // Soft preference: honored when the host can also emit it, overriding precedence...
+        assert_eq!(
+            resolve_codec(CODEC_H264 | CODEC_HEVC, CODEC_H264 | CODEC_HEVC, CODEC_H264),
+            Some(CODEC_H264)
+        );
+        assert_eq!(
+            resolve_codec(CODEC_HEVC | CODEC_AV1, CODEC_HEVC | CODEC_AV1, CODEC_AV1),
+            Some(CODEC_AV1)
+        );
+        // ...but falls back to precedence when the preferred codec isn't in the shared set.
+        assert_eq!(
+            resolve_codec(CODEC_HEVC | CODEC_H264, CODEC_HEVC | CODEC_H264, CODEC_AV1),
+            Some(CODEC_HEVC)
+        );
+        // A preference the host can't emit still can't rescue a no-shared-codec case.
+        assert_eq!(resolve_codec(CODEC_HEVC, CODEC_H264, CODEC_HEVC), None);
+
+        // PyroWave is opt-in ONLY (plan §3): mutual support NEVER auto-selects it — the ladder
+        // ignores it entirely...
+        assert_eq!(
+            resolve_codec(CODEC_HEVC | CODEC_PYROWAVE, CODEC_HEVC | CODEC_PYROWAVE, 0),
+            Some(CODEC_HEVC)
+        );
+        // ...even when it is the ONLY shared codec (an all-intra 200 Mbps stream must never be a
+        // silent fallback)...
+        assert_eq!(resolve_codec(CODEC_PYROWAVE, CODEC_PYROWAVE, 0), None);
+        // ...it is reachable exclusively through the client's explicit preference.
+        assert_eq!(
+            resolve_codec(
+                CODEC_HEVC | CODEC_PYROWAVE,
+                CODEC_HEVC | CODEC_PYROWAVE,
+                CODEC_PYROWAVE
+            ),
+            Some(CODEC_PYROWAVE)
+        );
+        // A pyrowave preference against a host without the backend falls back to the ladder.
+        assert_eq!(
+            resolve_codec(CODEC_HEVC | CODEC_PYROWAVE, CODEC_HEVC, CODEC_PYROWAVE),
+            Some(CODEC_HEVC)
+        );
+        // And the negotiated bit SURVIVES the Welcome wire roundtrip — the decode whitelist
+        // once folded unknown codec bytes (incl. PyroWave) to HEVC, which sent wavelet AUs
+        // into an FFmpeg HEVC decoder on the first on-glass run.
+        let mut pw_w = Welcome::decode(
+            &Welcome {
+                abi_version: 2,
+                udp_port: 1,
+                mode: Mode {
+                    width: 1280,
+                    height: 720,
+                    refresh_hz: 60,
+                },
+                fec: FecConfig {
+                    scheme: FecScheme::Gf16,
+                    fec_percent: 0,
+                    max_data_per_block: 1024,
+                },
+                shard_payload: 1024,
+                encrypt: false,
+                key: [0; 16],
+                salt: [0; 4],
+                frames: 0,
+                compositor: CompositorPref::Auto,
+                gamepad: GamepadPref::Auto,
+                bitrate_kbps: 0,
+                bit_depth: 8,
+                color: ColorInfo::SDR_BT709,
+                chroma_format: CHROMA_IDC_420,
+                audio_channels: 2,
+                codec: CODEC_PYROWAVE,
+                host_caps: 0,
+            }
+            .encode(),
+        )
+        .unwrap();
+        assert_eq!(pw_w.codec, CODEC_PYROWAVE);
+        // A genuinely unknown future bit still folds to the HEVC default.
+        pw_w.codec = 0x40;
+        assert_eq!(Welcome::decode(&pw_w.encode()).unwrap().codec, CODEC_HEVC);
+
+        // A Hello advertising codecs roundtrips, and the wire form of a codec-only Hello decodes on
+        // a build that ignores the trailing byte (back-compat: extra bytes are skipped).
+        let h = Hello {
+            abi_version: 2,
+            mode: Mode {
+                width: 1280,
+                height: 720,
+                refresh_hz: 60,
+            },
+            compositor: CompositorPref::Auto,
+            gamepad: GamepadPref::Auto,
+            bitrate_kbps: 0,
+            name: None,
+            launch: None,
+            video_caps: 0,
+            audio_channels: 2, // stereo — forces the video_caps/audio_channels placeholders
+            video_codecs: CODEC_H264 | CODEC_HEVC,
+            preferred_codec: CODEC_H264,
+            display_hdr: None,
+        };
+        let enc = h.encode();
+        let dec = Hello::decode(&enc).unwrap();
+        assert_eq!(dec.video_codecs, CODEC_H264 | CODEC_HEVC);
+        assert_eq!(dec.preferred_codec, CODEC_H264);
+        // Drop the preferred_codec byte → still decodes, video_codecs intact, preference gone.
+        let no_pref = &enc[..enc.len() - 1];
+        assert_eq!(
+            Hello::decode(no_pref).unwrap().video_codecs,
+            CODEC_H264 | CODEC_HEVC
+        );
+        assert_eq!(Hello::decode(no_pref).unwrap().preferred_codec, 0);
+        // A pre-codec Hello (no video_codecs/preferred bytes) decodes to 0 → HEVC-only.
+        let legacy = &enc[..enc.len() - 2];
+        assert_eq!(Hello::decode(legacy).unwrap().video_codecs, 0);
+        assert_eq!(Hello::decode(legacy).unwrap().preferred_codec, 0);
+
+        // A pre-codec Welcome (no codec byte) decodes to HEVC.
+        let mut w = Welcome::decode(
+            &Welcome {
+                abi_version: 2,
+                udp_port: 1,
+                mode: h.mode,
+                fec: FecConfig {
+                    scheme: FecScheme::Gf16,
+                    fec_percent: 0,
+                    max_data_per_block: 1024,
+                },
+                shard_payload: 1024,
+                encrypt: false,
+                key: [0; 16],
+                salt: [0; 4],
+                frames: 0,
+                compositor: CompositorPref::Auto,
+                gamepad: GamepadPref::Auto,
+                bitrate_kbps: 0,
+                bit_depth: 8,
+                color: ColorInfo::SDR_BT709,
+                chroma_format: CHROMA_IDC_420,
+                audio_channels: 2,
+                codec: CODEC_H264,
+                host_caps: 0,
+            }
+            .encode(),
+        )
+        .unwrap();
+        assert_eq!(w.codec, CODEC_H264);
+        w.codec = CODEC_HEVC;
+        let wenc = w.encode();
+        assert_eq!(
+            Welcome::decode(&wenc[..wenc.len() - 1]).unwrap().codec,
+            CODEC_HEVC
+        );
+    }
+
+    #[test]
+    fn hello_start_roundtrip() {
+        let h = Hello {
+            abi_version: 1,
+            mode: Mode {
+                width: 1280,
+                height: 720,
+                refresh_hz: 120,
+            },
+            compositor: CompositorPref::Kwin,
+            gamepad: GamepadPref::DualSense,
+            bitrate_kbps: 25_000,
+            name: Some("Test Device".into()),
+            launch: Some("steam:570".into()),
+            video_caps: VIDEO_CAP_10BIT,
+            audio_channels: 2,
+            video_codecs: CODEC_H264 | CODEC_HEVC, // exercise the codec bitfield roundtrip
+            preferred_codec: CODEC_HEVC,
+            display_hdr: None,
+        };
+        assert_eq!(Hello::decode(&h.encode()).unwrap(), h);
+        let s = Start {
+            client_udp_port: 1234,
+        };
+        assert_eq!(Start::decode(&s.encode()).unwrap(), s);
+    }
+
+    #[test]
+    fn hello_welcome_compositor_back_compat() {
+        // Trailing optional bytes (compositor at 20/53, gamepad at 21/54): a legacy peer's
+        // shorter message still decodes (missing fields = Auto), and a legacy peer reading a
+        // new message ignores the trailing bytes. Simulate both directions by truncation.
+        let h = Hello {
+            abi_version: 2,
+            mode: Mode {
+                width: 1920,
+                height: 1080,
+                refresh_hz: 60,
+            },
+            compositor: CompositorPref::Mutter,
+            gamepad: GamepadPref::DualSense,
+            bitrate_kbps: 80_000,
+            name: None,
+            launch: None,
+            video_caps: 0,
+            audio_channels: 2,
+            video_codecs: 0,
+            preferred_codec: 0,
+            display_hdr: None,
+        };
+        let enc = h.encode();
+        assert_eq!(enc.len(), 26);
+        // Legacy (20-byte) Hello → both Auto, no bitrate, mode intact.
+        let legacy = Hello::decode(&enc[..20]).unwrap();
+        assert_eq!(legacy.compositor, CompositorPref::Auto);
+        assert_eq!(legacy.gamepad, GamepadPref::Auto);
+        assert_eq!(legacy.bitrate_kbps, 0);
+        assert_eq!(legacy.mode, h.mode);
+        // Compositor-era (21-byte) Hello → compositor intact, gamepad Auto.
+        let mid = Hello::decode(&enc[..21]).unwrap();
+        assert_eq!(mid.compositor, CompositorPref::Mutter);
+        assert_eq!(mid.gamepad, GamepadPref::Auto);
+        // Gamepad-era (22-byte) Hello → compositor + gamepad intact, bitrate 0 (host default).
+        let pre_bitrate = Hello::decode(&enc[..22]).unwrap();
+        assert_eq!(pre_bitrate.gamepad, GamepadPref::DualSense);
+        assert_eq!(pre_bitrate.bitrate_kbps, 0);
+        // Full message → bitrate intact.
+        assert_eq!(Hello::decode(&enc).unwrap().bitrate_kbps, 80_000);
+
+        let w = Welcome {
+            abi_version: 2,
+            udp_port: 7000,
+            mode: h.mode,
+            fec: FecConfig {
+                scheme: FecScheme::Gf16,
+                fec_percent: 20,
+                max_data_per_block: 4096,
+            },
+            shard_payload: 1200,
+            encrypt: true,
+            key: [3u8; 16],
+            salt: [9, 8, 7, 6],
+            frames: 0,
+            compositor: CompositorPref::Kwin,
+            gamepad: GamepadPref::Xbox360,
+            bitrate_kbps: 120_000,
+            bit_depth: 10,
+            color: ColorInfo::HDR10_BT2020_PQ,
+            chroma_format: CHROMA_IDC_444,
+            audio_channels: 6, // 5.1 — exercises the non-default trailing byte
+            codec: CODEC_HEVC,
+            host_caps: HOST_CAP_GAMEPAD_STATE,
+        };
+        let wenc = w.encode();
+        assert_eq!(wenc.len(), 68); // 60 base + 4 colour + chroma + audio-channels + codec + host-caps
+        let legacy_w = Welcome::decode(&wenc[..53]).unwrap();
+        assert_eq!(legacy_w.compositor, CompositorPref::Auto);
+        assert_eq!(legacy_w.gamepad, GamepadPref::Auto);
+        assert_eq!(legacy_w.bitrate_kbps, 0);
+        assert_eq!(legacy_w.frames, 0);
+        assert_eq!(legacy_w.key, w.key);
+        let mid_w = Welcome::decode(&wenc[..54]).unwrap();
+        assert_eq!(mid_w.compositor, CompositorPref::Kwin);
+        assert_eq!(mid_w.gamepad, GamepadPref::Auto);
+        // Gamepad-era (55-byte) Welcome → gamepad intact, bitrate 0 (unknown).
+        let pre_bitrate_w = Welcome::decode(&wenc[..55]).unwrap();
+        assert_eq!(pre_bitrate_w.gamepad, GamepadPref::Xbox360);
+        assert_eq!(pre_bitrate_w.bitrate_kbps, 0);
+        assert_eq!(pre_bitrate_w.bit_depth, 8); // older host (no trailing byte) → 8-bit assumed
+        assert_eq!(legacy_w.bit_depth, 8);
+        // A pre-colour (60-byte) Welcome → SDR BT.709 (the only colour those hosts produced).
+        let pre_color_w = Welcome::decode(&wenc[..60]).unwrap();
+        assert_eq!(pre_color_w.bit_depth, 10);
+        assert_eq!(pre_color_w.color, ColorInfo::SDR_BT709);
+        assert_eq!(pre_color_w.chroma_format, CHROMA_IDC_420); // pre-chroma host → 4:2:0
+        assert_eq!(legacy_w.color, ColorInfo::SDR_BT709);
+        assert_eq!(legacy_w.chroma_format, CHROMA_IDC_420);
+        // A pre-chroma (64-byte) Welcome carries colour but no chroma/audio bytes → 4:2:0 + stereo.
+        let pre_chroma_w = Welcome::decode(&wenc[..64]).unwrap();
+        assert_eq!(pre_chroma_w.color, ColorInfo::HDR10_BT2020_PQ);
+        assert_eq!(pre_chroma_w.chroma_format, CHROMA_IDC_420);
+        assert_eq!(pre_chroma_w.audio_channels, 2); // audio byte (offset 65) absent → stereo
+                                                    // A pre-audio (65-byte) Welcome carries chroma but no audio byte → 4:4:4 + stereo.
+        let pre_audio_w = Welcome::decode(&wenc[..65]).unwrap();
+        assert_eq!(pre_audio_w.chroma_format, CHROMA_IDC_444);
+        assert_eq!(pre_audio_w.audio_channels, 2);
+        assert_eq!(Welcome::decode(&wenc).unwrap().bitrate_kbps, 120_000);
+        assert_eq!(Welcome::decode(&wenc).unwrap().bit_depth, 10); // full form carries it
+        assert_eq!(
+            Welcome::decode(&wenc).unwrap().color,
+            ColorInfo::HDR10_BT2020_PQ
+        );
+        assert_eq!(
+            Welcome::decode(&wenc).unwrap().chroma_format,
+            CHROMA_IDC_444
+        ); // full form carries 4:4:4
+        assert_eq!(Welcome::decode(&wenc).unwrap().audio_channels, 6); // ...and 5.1
+                                                                       // A pre-host-caps (67-byte) Welcome → 0 (legacy input only); the full form carries the bit.
+        assert_eq!(Welcome::decode(&wenc[..67]).unwrap().host_caps, 0);
+        assert_eq!(
+            Welcome::decode(&wenc).unwrap().host_caps,
+            HOST_CAP_GAMEPAD_STATE
+        );
+    }
+
+    #[test]
+    fn hello_name_roundtrip_and_back_compat() {
+        let base = Hello {
+            abi_version: 2,
+            mode: Mode {
+                width: 1280,
+                height: 720,
+                refresh_hz: 60,
+            },
+            compositor: CompositorPref::Auto,
+            gamepad: GamepadPref::Auto,
+            bitrate_kbps: 0,
+            name: Some("Enrico's MacBook".into()),
+            launch: None,
+            video_caps: 0,
+            audio_channels: 2,
+            video_codecs: 0,
+            preferred_codec: 0,
+            display_hdr: None,
+        };
+        let enc = base.encode();
+        assert_eq!(
+            Hello::decode(&enc).unwrap().name.as_deref(),
+            Some("Enrico's MacBook")
+        );
+        // A bitrate-era (26-byte) peer reading a named Hello ignores the trailing name; a named
+        // host reading a bitrate-era Hello decodes name = None.
+        assert_eq!(Hello::decode(&enc[..26]).unwrap().name, None);
+        // No name → wire form is byte-identical to the bitrate-era message (26 bytes).
+        let unnamed = Hello {
+            name: None,
+            ..base.clone()
+        };
+        assert_eq!(unnamed.encode().len(), 26);
+        // Over-long names truncate to a char boundary within HELLO_NAME_MAX on encode.
+        let long = Hello {
+            name: Some(format!("{}ü", "x".repeat(HELLO_NAME_MAX - 1))), // ü straddles the cap
+            ..base.clone()
+        };
+        let dec = Hello::decode(&long.encode()).unwrap();
+        let n = dec.name.expect("truncated name still present");
+        assert!(n.len() <= HELLO_NAME_MAX && n.starts_with('x'));
+        // A corrupt length byte (longer than the buffer) or bad UTF-8 degrades to None, never Err.
+        let mut bad_len = unnamed.encode();
+        bad_len.push(40); // claims 40 name bytes, none follow
+        assert_eq!(Hello::decode(&bad_len).unwrap().name, None);
+        let mut bad_utf8 = unnamed.encode();
+        bad_utf8.extend_from_slice(&[2, 0xFF, 0xFE]);
+        assert_eq!(Hello::decode(&bad_utf8).unwrap().name, None);
+    }
+
+    #[test]
+    fn hello_launch_roundtrip_and_back_compat() {
+        let base = Hello {
+            abi_version: 2,
+            mode: Mode {
+                width: 1920,
+                height: 1080,
+                refresh_hz: 60,
+            },
+            compositor: CompositorPref::Auto,
+            gamepad: GamepadPref::Auto,
+            bitrate_kbps: 0,
+            name: None,
+            launch: None,
+            video_caps: 0,
+            audio_channels: 2,
+            video_codecs: 0,
+            preferred_codec: 0,
+            display_hdr: None,
+        };
+        // launch alone (no name): a zero-length name placeholder keeps the offset deterministic.
+        let with_launch = Hello {
+            launch: Some("steam:570".into()),
+            ..base.clone()
+        };
+        assert_eq!(Hello::decode(&with_launch.encode()).unwrap(), with_launch);
+        // launch + name together.
+        let both = Hello {
+            name: Some("Enrico's Mac".into()),
+            launch: Some("custom:abc123".into()),
+            ..base.clone()
+        };
+        assert_eq!(Hello::decode(&both.encode()).unwrap(), both);
+        // name but no launch (a name-era client): launch decodes None.
+        let name_only = Hello {
+            name: Some("Enrico's Mac".into()),
+            ..base.clone()
+        };
+        assert_eq!(Hello::decode(&name_only.encode()).unwrap().launch, None);
+        // Neither field → still the 26-byte bitrate-era form (no launch placeholder emitted).
+        assert_eq!(base.encode().len(), 26);
+        assert_eq!(Hello::decode(&base.encode()).unwrap().launch, None);
+        // A bitrate-era (26-byte) peer reading a launch-bearing Hello ignores it.
+        assert_eq!(
+            Hello::decode(&with_launch.encode()[..26]).unwrap().launch,
+            None
+        );
+        // Over-long ids truncate on a char boundary within HELLO_LAUNCH_MAX.
+        let long = Hello {
+            launch: Some(format!("{}ü", "x".repeat(HELLO_LAUNCH_MAX - 1))),
+            ..base.clone()
+        };
+        let dec = Hello::decode(&long.encode())
+            .unwrap()
+            .launch
+            .expect("present");
+        assert!(dec.len() <= HELLO_LAUNCH_MAX && dec.starts_with('x'));
+    }
+
+    #[test]
+    fn hello_display_hdr_roundtrip_and_back_compat() {
+        let base = Hello {
+            abi_version: 2,
+            mode: Mode {
+                width: 3840,
+                height: 2160,
+                refresh_hz: 120,
+            },
+            compositor: CompositorPref::Auto,
+            gamepad: GamepadPref::Auto,
+            bitrate_kbps: 0,
+            name: None,
+            launch: None,
+            video_caps: VIDEO_CAP_10BIT | VIDEO_CAP_HDR,
+            audio_channels: 2,
+            video_codecs: 0,
+            preferred_codec: 0,
+            display_hdr: None,
+        };
+        // A real client-panel volume (P3 primaries, 800-nit peak, 0.05-nit floor, 400-nit FALL).
+        let vol = HdrMeta {
+            display_primaries: [[13250, 34500], [7500, 3000], [34000, 16000]], // G, B, R
+            white_point: [15635, 16450],                                       // D65
+            max_display_mastering_luminance: 8_000_000,                        // 800 nits
+            min_display_mastering_luminance: 500,                              // 0.05 nits
+            max_cll: 0,
+            max_fall: 400,
+        };
+        let with_hdr = Hello {
+            display_hdr: Some(vol),
+            ..base.clone()
+        };
+        // Full roundtrip, including the forced placeholders for the earlier trailing fields.
+        assert_eq!(Hello::decode(&with_hdr.encode()).unwrap(), with_hdr);
+        // display_hdr alone (every earlier optional at its default) still lands at a deterministic
+        // offset — the placeholder discipline holds through the whole tail.
+        let hdr_only = Hello {
+            video_caps: 0,
+            display_hdr: Some(vol),
+            ..base.clone()
+        };
+        assert_eq!(Hello::decode(&hdr_only.encode()).unwrap(), hdr_only);
+        // An older host reading a display_hdr-bearing Hello ignores the trailing block (its decode
+        // stops at preferred_codec); a new host reading an older client's Hello gets None.
+        let enc = with_hdr.encode();
+        assert_eq!(
+            Hello::decode(&enc[..enc.len() - HDR_META_BODY_LEN]).unwrap(),
+            Hello {
+                display_hdr: None,
+                ..with_hdr.clone()
+            }
+        );
+        assert_eq!(Hello::decode(&base.encode()).unwrap().display_hdr, None);
+        // A TRUNCATED trailing block (mid-datagram cut) degrades to None, never a partial read.
+        assert_eq!(
+            Hello::decode(&enc[..enc.len() - 1]).unwrap().display_hdr,
+            None
+        );
+        // Exact wire length: 26 bitrate-era bytes + the 6 forced single-byte placeholders
+        // (name len, launch len, video_caps, audio_channels, video_codecs, preferred_codec) + the body.
+        assert_eq!(hdr_only.encode().len(), 26 + 6 + HDR_META_BODY_LEN);
+    }
+
+    #[test]
+    fn control_messages_disjoint_from_hello() {
+        // A Hello uses MAGIC (PKF1); control messages use CTL_MAGIC (PKFc). No Hello — at
+        // any abi_version — can be misparsed as a control message, and vice-versa.
+        for abi in [1u32, 2, 16, 0x10, 0x0113, 0x1410] {
+            let h = Hello {
+                abi_version: abi,
+                mode: Mode {
+                    width: 1280,
+                    height: 720,
+                    refresh_hz: 60,
+                },
+                compositor: CompositorPref::Auto,
+                gamepad: GamepadPref::Auto,
+                bitrate_kbps: 0,
+                name: None,
+                launch: None,
+                video_caps: 0,
+                audio_channels: 2,
+                video_codecs: 0,
+                preferred_codec: 0,
+                display_hdr: None,
+            }
+            .encode();
+            assert!(PairRequest::decode(&h).is_err(), "abi {abi} parsed as pair");
+            assert!(Reconfigure::decode(&h).is_err());
+        }
+        // And a PairRequest never parses as a Hello.
+        let pr = PairRequest {
+            name: "x".into(),
+            spake_a: vec![0u8; 33],
+        }
+        .encode();
+        assert!(Hello::decode(&pr).is_err());
+    }
+}

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

@@ -1,6 +1,14 @@
 //! Length-prefixed framing for QUIC control-stream messages: a `u16` length header followed by the
 //! payload, bounded at 64 KiB (control messages are tiny).
 /// Read one framed message (bounded at 64 KiB — control messages are tiny).
+///
+/// **Not cancel-safe**: it frames with two `quinn::RecvStream::read_exact` calls, and quinn
+/// documents `read_exact` as not cancel-safe (the bytes it has already taken out of the stream
+/// live only in the future's own buffer, and nothing puts them back on drop). Dropping a
+/// partially-progressed future therefore destroys the bytes it consumed and misaligns every
+/// subsequent read on that stream. Use it only where the read runs to completion — the sequential
+/// handshake/pairing exchanges. Anything driving a read from a `select!` arm or a
+/// `tokio::time::timeout` must use [`MsgReader`] instead.
 pub async fn read_msg(recv: &mut quinn::RecvStream) -> std::io::Result<Vec<u8>> {
     let mut len = [0u8; 2];
     recv.read_exact(&mut len)
@@ -14,9 +22,158 @@ pub async fn read_msg(recv: &mut quinn::RecvStream) -> std::io::Result<Vec<u8>>
     Ok(buf)
 }
 
+/// Cancel-safe framed reader for a long-lived control stream.
+///
+/// Keeps the frame in progress in `buf` rather than inside the read future, so dropping the future
+/// — which both control loops do on every iteration where a sibling `select!` arm wins, and which
+/// [`clock_sync`](super::clock_sync) does on a read timeout — resumes instead of losing bytes.
+/// With the plain [`read_msg`] a control frame that straddles two wakeups (a ~2 KB `ClipOffer`
+/// exceeds one QUIC packet; so does any frame whose second half is lost or reordered) left the
+/// stream permanently misaligned: the next read took two payload bytes as a length, every later
+/// message decoded as garbage and was silently ignored, and a bogus 64 KiB length parked the read
+/// forever — killing mode switches, adaptive bitrate, clock re-sync and clipboard for the rest of
+/// the session with nothing but a `warn!` in the log.
+pub struct MsgReader {
+    recv: quinn::RecvStream,
+    /// The frame in progress, length prefix included.
+    buf: Vec<u8>,
+    /// Bytes `buf` must reach: 2 while reading the prefix, then `2 + payload length`.
+    need: usize,
+}
+
+impl MsgReader {
+    pub fn new(recv: quinn::RecvStream) -> Self {
+        MsgReader {
+            recv,
+            buf: Vec::new(),
+            need: 2,
+        }
+    }
+
+    /// Read one framed message. Cancel-safe: dropping the future keeps the partial frame, so the
+    /// next call resumes where this one stopped.
+    pub async fn read_msg(&mut self) -> std::io::Result<Vec<u8>> {
+        loop {
+            while self.buf.len() < self.need {
+                let mut chunk = [0u8; 2048];
+                let want = (self.need - self.buf.len()).min(chunk.len());
+                // `read` IS cancel-safe: it only reports bytes it hands back, and they are
+                // committed to `self.buf` before the next await point.
+                match self
+                    .recv
+                    .read(&mut chunk[..want])
+                    .await
+                    .map_err(std::io::Error::other)?
+                {
+                    Some(n) => self.buf.extend_from_slice(&chunk[..n]),
+                    None => {
+                        return Err(std::io::Error::new(
+                            std::io::ErrorKind::UnexpectedEof,
+                            "control stream finished mid-frame",
+                        ))
+                    }
+                }
+            }
+            if self.need == 2 {
+                self.need = 2 + u16::from_le_bytes([self.buf[0], self.buf[1]]) as usize;
+                if self.need == 2 {
+                    self.buf.clear();
+                    return Ok(Vec::new()); // zero-length frame
+                }
+            } else {
+                let msg = self.buf.split_off(2);
+                self.buf.clear();
+                self.need = 2;
+                return Ok(msg);
+            }
+        }
+    }
+}
+
 /// Write one framed message.
 pub async fn write_msg(send: &mut quinn::SendStream, payload: &[u8]) -> std::io::Result<()> {
     send.write_all(&super::frame(payload))
         .await
         .map_err(std::io::Error::other)
 }
+
+/// The control stream is read from a `select!` arm on both peers, so the read future is dropped
+/// routinely — and quinn documents `read_exact` (what `io::read_msg` uses) as NOT cancel-safe.
+/// [`io::MsgReader`] must survive that: the partial frame lives in the reader, not the future.
+#[cfg(test)]
+mod tests {
+    use crate::quic::io;
+    use crate::quic::test_util::connect_pair;
+
+    /// A frame whose halves land in different wakeups, with the read cancelled in between, must
+    /// still be delivered whole — and the NEXT frame must decode correctly too. Without a
+    /// resumable reader the consumed length prefix is lost, the following read takes two payload
+    /// bytes as a length, and every later control message is garbage for the rest of the session.
+    #[tokio::test]
+    async fn cancelled_mid_frame_read_resumes_without_desync() {
+        let (_server_ep, _client_ep, host_conn, client_conn) = connect_pair().await;
+
+        let first = b"the-frame-that-straddles-two-wakeups".to_vec();
+        let second = b"the-frame-after-it".to_vec();
+        let (f1, f2) = (first.clone(), second.clone());
+
+        let writer = tokio::spawn(async move {
+            let (mut send, _recv) = host_conn.open_bi().await.expect("open bi");
+            let framed = crate::quic::frame(&f1);
+            // Length prefix + only part of the payload, then a real pause: this is the ClipOffer
+            // -sized frame split across two QUIC packets that made the bug reachable.
+            let split = 2 + f1.len() / 3;
+            send.write_all(&framed[..split]).await.expect("write head");
+            tokio::time::sleep(std::time::Duration::from_millis(120)).await;
+            send.write_all(&framed[split..]).await.expect("write tail");
+            send.write_all(&crate::quic::frame(&f2))
+                .await
+                .expect("write second");
+            tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+            host_conn
+        });
+
+        let (_send, recv) = client_conn.accept_bi().await.expect("accept bi");
+        let mut reader = io::MsgReader::new(recv);
+
+        // Cancel mid-frame — exactly what a sibling `select!` arm does.
+        let cancelled =
+            tokio::time::timeout(std::time::Duration::from_millis(30), reader.read_msg()).await;
+        assert!(
+            cancelled.is_err(),
+            "the head-only frame must not complete yet (test setup)"
+        );
+
+        let got = tokio::time::timeout(std::time::Duration::from_secs(5), reader.read_msg())
+            .await
+            .expect("first frame must arrive after resuming")
+            .expect("first frame reads cleanly");
+        assert_eq!(got, first, "the cancelled read must resume, not lose bytes");
+
+        let got2 = tokio::time::timeout(std::time::Duration::from_secs(5), reader.read_msg())
+            .await
+            .expect("second frame must arrive")
+            .expect("second frame reads cleanly");
+        assert_eq!(got2, second, "stream must still be framed correctly");
+
+        let _host_conn = writer.await.unwrap();
+    }
+
+    /// A zero-length frame is a legal encoding and must not stall the reader or eat the next one.
+    #[tokio::test]
+    async fn zero_length_frame_round_trips() {
+        let (_server_ep, _client_ep, host_conn, client_conn) = connect_pair().await;
+        let writer = tokio::spawn(async move {
+            let (mut send, _recv) = host_conn.open_bi().await.expect("open bi");
+            send.write_all(&crate::quic::frame(&[])).await.unwrap();
+            send.write_all(&crate::quic::frame(b"after")).await.unwrap();
+            tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+            host_conn
+        });
+        let (_send, recv) = client_conn.accept_bi().await.expect("accept bi");
+        let mut reader = io::MsgReader::new(recv);
+        assert!(reader.read_msg().await.unwrap().is_empty());
+        assert_eq!(reader.read_msg().await.unwrap(), b"after");
+        let _host_conn = writer.await.unwrap();
+    }
+}

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

@@ -22,11 +22,14 @@
 //! reported back for persisting). The data plane adds AES-GCM on top.
 //! All integers little-endian; every message is `u16 length || payload`.
 //!
-//! Split by concern (networking-audit deferred plan §3 — a pure move): [`msgs`] the
+//! Split by concern (networking-audit deferred plan §3 — a pure move): `handshake` the
-//! handshake + typed control messages, [`pake`] the pairing SPAKE2, [`datagram`] the
+//! positional Hello/Welcome/Start codecs, `caps` the capability/codec-negotiation
-//! 0xC9–0xCF plane codecs, [`io`] framed stream IO, [`clock`] skew estimation + mid-stream
+//! vocabulary, `control` the typed control + clipboard messages, `pairing` the pairing
-//! re-sync, [`endpoint`] the quinn constructors. Every item is re-exported here, so all
+//! message codecs with [`pake`] the SPAKE2 itself, `datagram` the 0xC9–0xCF plane codecs,
-//! existing `crate::quic::X` paths compile unchanged.
+//! [`io`] framed stream IO, `clock` skew estimation + mid-stream re-sync, [`endpoint`] the
+//! quinn constructors, [`clipstream`] the per-transfer clipboard fetch streams. Every item
+//! is re-exported here, so all existing `crate::quic::X` paths compile unchanged; each
+//! module's tests sit at its own foot.
 
 /// Protocol magic + version, first bytes of the positional handshake (Hello/Welcome/Start).
 pub const MAGIC: &[u8; 4] = b"PKF1";
@@ -76,4 +79,4 @@ pub use pairing::*;
 pub use crate::reject::*;
 
 #[cfg(test)]
-mod tests;
+pub(crate) mod test_util;

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

@@ -78,13 +78,16 @@ fn get_bytes(b: &[u8], off: usize) -> Result<(&[u8], usize)> {
 
 impl PairRequest {
     pub fn encode(&self) -> Vec<u8> {
-        let name = self.name.as_bytes();
+        // Same cap, same rule as Hello's copy of this field: truncate on a char boundary —
-        let n = name.len().min(64);
+        // a raw byte cut mid-sequence put invalid UTF-8 on the wire, and the host showed the
+        // name with a permanent replacement char in its paired-clients list.
+        let name = super::handshake::truncate_to(&self.name, HELLO_NAME_MAX).as_bytes();
+        let n = name.len();
         let mut b = Vec::with_capacity(8 + n + self.spake_a.len());
         b.extend_from_slice(CTL_MAGIC);
         b.push(MSG_PAIR_REQUEST);
         b.push(n as u8);
-        b.extend_from_slice(&name[..n]);
+        b.extend_from_slice(name);
         put_bytes(&mut b, &self.spake_a);
         b
     }
@@ -171,3 +174,50 @@ impl PairResult {
         Ok(PairResult { ok: b[5] != 0 })
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::quic::*;
+
+    #[test]
+    fn pair_messages_roundtrip() {
+        let pr = PairRequest {
+            name: "Enrico's Mac".into(),
+            spake_a: vec![1, 2, 3, 4, 5],
+        };
+        assert_eq!(PairRequest::decode(&pr.encode()).unwrap(), pr);
+        let pc = PairChallenge {
+            spake_b: vec![9; 33],
+            confirm: [7u8; 32],
+        };
+        assert_eq!(PairChallenge::decode(&pc.encode()).unwrap(), pc);
+        let pp = PairProof { confirm: [3u8; 32] };
+        assert_eq!(PairProof::decode(&pp.encode()).unwrap(), pp);
+        for ok in [true, false] {
+            assert_eq!(
+                PairResult::decode(&PairResult { ok }.encode()).unwrap().ok,
+                ok
+            );
+        }
+        // Length-exact: a truncated/padded PairProof is rejected.
+        let mut bad = pp.encode();
+        bad.push(0);
+        assert!(PairProof::decode(&bad).is_err());
+    }
+
+    #[test]
+    fn pair_request_name_cap_respects_char_boundaries() {
+        // A multi-byte char straddling the 64-byte cap must be dropped whole (Hello's rule),
+        // not split mid-sequence into invalid UTF-8 the host then renders as U+FFFD forever.
+        let pr = PairRequest {
+            name: format!("{}\u{00fc}", "x".repeat(HELLO_NAME_MAX - 1)),
+            spake_a: vec![1, 2, 3],
+        };
+        let dec = PairRequest::decode(&pr.encode()).unwrap();
+        assert!(dec.name.len() <= HELLO_NAME_MAX && dec.name.starts_with('x'));
+        assert!(
+            !dec.name.contains('\u{FFFD}'),
+            "name must never be split mid-char on the wire"
+        );
+    }
+}

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

@@ -80,3 +80,36 @@ impl PairingPake {
 pub fn verify(expected: &[u8; 32], got: &[u8; 32]) -> bool {
     ct_eq(expected, got)
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::quic::pake;
+
+    #[test]
+    fn spake2_pairing_agrees_only_on_matching_pin_and_certs() {
+        let cfp = [0x11u8; 32];
+        let hfp = [0x22u8; 32];
+
+        // Right PIN, same fingerprint views on both sides → both confirmations agree.
+        let (ca, ma) = pake::start(true, "4321", &cfp, &hfp);
+        let (cb, mb) = pake::start(false, "4321", &cfp, &hfp);
+        let a = ca.finish(&mb).unwrap();
+        let b = cb.finish(&ma).unwrap();
+        assert!(pake::verify(&a.host, &b.host) && pake::verify(&a.client, &b.client));
+
+        // Wrong PIN → different keys → confirmations DON'T match (one online guess wasted).
+        let (ca, ma) = pake::start(true, "0000", &cfp, &hfp);
+        let (cb, mb) = pake::start(false, "4321", &cfp, &hfp);
+        let a = ca.finish(&mb).unwrap();
+        let b = cb.finish(&ma).unwrap();
+        assert!(!pake::verify(&a.client, &b.client));
+
+        // MITM: the two legs saw different host certs → no agreement even with the right PIN.
+        let attacker_hfp = [0x33u8; 32];
+        let (ca, ma) = pake::start(true, "4321", &cfp, &attacker_hfp);
+        let (cb, mb) = pake::start(false, "4321", &cfp, &hfp);
+        let a = ca.finish(&mb).unwrap();
+        let b = cb.finish(&ma).unwrap();
+        assert!(!pake::verify(&a.client, &b.client));
+    }
+}

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

@@ -0,0 +1,28 @@
+//! Shared in-process QUIC loopback plumbing for the quic submodule tests.
+use super::endpoint;
+
+/// Stand up two loopback quinn endpoints, connect, and return
+/// `(server_ep, client_ep, host_conn, client_conn)`. Both endpoints are returned so the caller
+/// keeps them in scope — dropping a `quinn::Endpoint` tears down its connections.
+pub(crate) async fn connect_pair() -> (
+    quinn::Endpoint,
+    quinn::Endpoint,
+    quinn::Connection,
+    quinn::Connection,
+) {
+    let server = endpoint::server("127.0.0.1:0".parse().unwrap()).unwrap();
+    let addr = server.local_addr().unwrap();
+    let client = endpoint::client_insecure().unwrap();
+    let accept = tokio::spawn(async move {
+        let incoming = server.accept().await.expect("incoming connection");
+        let conn = incoming.await.expect("host side connects");
+        (server, conn)
+    });
+    let client_conn = client
+        .connect(addr, "punktfunk")
+        .unwrap()
+        .await
+        .expect("client side connects");
+    let (server, host_conn) = accept.await.unwrap();
+    (server, client, host_conn, client_conn)
+}

crates/punktfunk-core/src/session.rs

@@ -30,6 +30,14 @@ pub struct Frame {
     /// ([`crate::packet::USER_FLAG_CHUNK_ALIGNED`]) are ever delivered partial; missing
     /// shard ranges are zero-filled at their exact offsets.
     pub complete: bool,
+    /// Wall-clock instant (ns since the Unix epoch, CLOCK_REALTIME basis — the same clock the
+    /// skew handshake compares and the host stamps `pts_ns` with) at which this AU finished
+    /// reassembly, stamped by [`Session::poll_frame`] as the frame leaves the session. Embedders
+    /// that previously stamped receipt themselves at the hand-off pull should use this instead:
+    /// the pull stamp additionally contains the pre-decode queue wait, silently folding any
+    /// client-side standing backlog into the apparent NETWORK latency. The reassembler itself
+    /// leaves this 0 (it owns no clock — the stamp is the session boundary's job).
+    pub received_ns: u64,
 }
 
 /// One end of a stream. Constructed for a single [`Role`]; calling the other role's
@@ -82,160 +90,27 @@ pub struct Session {
     lane_scratch: Vec<Vec<u8>>,
 }
 
-/// Wire-packet count at which a frame's sealing splits across two lanes (plan Phase 1.5):
+/// Stamp [`Frame::received_ns`] as the frame crosses the session boundary in
-/// below it the channel rendezvous (~µs) isn't worth it; at it the halved AES-GCM span
+/// [`Session::poll_frame`] — completed frames return the moment their last shard lands, so
-/// (≥ ~125 µs of ~1 µs/packet work) dwarfs the hand-off. ≈300 KB of wire, i.e. ≥150 Mbps
+/// stamping at return IS stamping at reassembly completion (µs apart). CLOCK_REALTIME to match
-/// at 60 fps — small frames and the probe's ~17-packet AUs stay strictly single-lane.
+/// `pts_ns` / the skew handshake (deliberately not monotonic — cross-machine latency math).
-const TWO_LANE_MIN_PACKETS: usize = 256;
+fn stamp_received(mut f: Frame) -> Frame {
-
+    f.received_ns = std::time::SystemTime::now()
-/// One two-lane seal hand-off: the frame's back-half wire buffers, sealed by the worker with
+        .duration_since(std::time::UNIX_EPOCH)
-/// nonces `seq_base + i` (the nonce order is deterministic per shard index, which is what
+        .map(|d| d.as_nanos() as u64)
-/// makes the split sound). Round-trips through the channels so the buffers return to the pool.
+        .unwrap_or(0);
-struct SealJob {
+    f
-    bufs: Vec<Vec<u8>>,
-    seq_base: u64,
-    timed: bool,
-    /// Worker-lane CPU ns (when `timed`) and the seal outcome, filled in by the worker.
-    ns: u64,
-    result: Result<()>,
 }
 
-/// The persistent second seal lane: a worker thread that AES-GCM-seals the back half of a
+mod perf;
-/// large frame's packets while the send thread seals the front half. Rendezvous channels
+mod replay;
-/// (bound 1) — the send thread submits, seals its half, then waits; no per-frame spawn.
+mod seal;
-/// Dropping the struct closes the channel and the worker exits.
-struct SealLane {
-    to_worker: std::sync::mpsc::SyncSender<SealJob>,
-    from_worker: std::sync::mpsc::Receiver<SealJob>,
-}
 
-impl SealLane {
+pub use perf::{PumpPerf, SealPerf};
-    fn spawn(crypto: std::sync::Arc<SessionCrypto>) -> Option<SealLane> {
-        let (to_worker, jobs) = std::sync::mpsc::sync_channel::<SealJob>(1);
-        let (done_tx, from_worker) = std::sync::mpsc::sync_channel::<SealJob>(1);
-        std::thread::Builder::new()
-            .name("punktfunk-seal2".into())
-            .spawn(move || {
-                while let Ok(mut job) = jobs.recv() {
-                    let t0 = job.timed.then(std::time::Instant::now);
-                    job.result = seal_wire_slice(&crypto, &mut job.bufs, job.seq_base);
-                    if let Some(t0) = t0 {
-                        job.ns = t0.elapsed().as_nanos() as u64;
-                    }
-                    if done_tx.send(job).is_err() {
-                        break; // session gone mid-frame — nothing left to seal for
-                    }
-                }
-            })
-            .ok()?;
-        Some(SealLane {
-            to_worker,
-            from_worker,
-        })
-    }
-}
 
-/// Seal a run of pre-written wire buffers in place: buffer `i` is `seq(8) ‖ plaintext ‖ tag
+use perf::TimedCoder;
-/// scratch` and seals over `[8..]` with sequence `seq_base + i` — the exact per-packet layout
+use replay::{seq_of, ReplayWindow};
-/// and nonce order of the fused single-lane path. Shared by both lanes.
+use seal::{seal_wire_slice, SealJob, SealLane, TWO_LANE_MIN_PACKETS};
-fn seal_wire_slice(c: &SessionCrypto, wires: &mut [Vec<u8>], seq_base: u64) -> Result<()> {
-    for (i, wire) in wires.iter_mut().enumerate() {
-        c.seal_in_place(seq_base.wrapping_add(i as u64), &mut wire[8..])?;
-    }
-    Ok(())
-}
-
-/// Accumulated client receive-path stage timings since the last [`Session::take_pump_perf`].
-/// Answers "where does the pump core go" at line rate: kernel drain (`recv_ns`) vs AES-GCM
-/// (`decrypt_ns`) vs reassembly+FEC (`reasm_ns`, the `Reassembler::push` round-trip including
-/// shard copies and block reconstruction). 2026-07-14 sweep context: the pump pegs one core at
-/// ~1.5 Gbps wire, ~85% of it userspace — this split is what Phase 2.1 (pooled reassembly) is
-/// validated against.
-#[derive(Debug, Default, Clone, Copy)]
-pub struct PumpPerf {
-    /// ns inside `recv_batch` (recvmmsg / recvmsg_x), i.e. syscall + kernel copy.
-    pub recv_ns: u64,
-    /// ns inside `open_in_place` across all datagrams (AES-128-GCM + replay-window upkeep).
-    pub decrypt_ns: u64,
-    /// ns inside `Reassembler::push` (header parse, shard copy, FEC reconstruct, AU assembly).
-    pub reasm_ns: u64,
-    /// recv_batch calls (batches) and datagrams processed over the accumulation window.
-    pub batches: u64,
-    pub packets: u64,
-}
-
-/// Accumulated host send-path stage timings since the last [`Session::take_seal_perf`] (plan
-/// Phase 0.4, host half). Answers "where does the send thread go" at rate: FEC parity
-/// generation (`fec_ns`, inside [`ErasureCoder::encode_into`]) vs AES-GCM (`seal_ns`,
-/// per-packet `seal_in_place`) vs the socket handoff (`sock_ns` — `send_gso`/`sendmmsg`
-/// syscalls; the internal submit paths time it here, the paced video path folds its chunk
-/// sends in via [`Session::note_sock_ns`]). The Phase 1.5 gate reads off this split: build
-/// two-lane seal only if `seal_ns` exceeds ~15% of the send thread at 2 Gbps.
-#[derive(Debug, Default, Clone, Copy)]
-pub struct SealPerf {
-    /// ns inside `ErasureCoder::encode_into` (parity generation).
-    pub fec_ns: u64,
-    /// ns inside `seal_in_place` across all wire packets (AES-128-GCM).
-    pub seal_ns: u64,
-    /// ns inside `send_sealed` (socket syscalls), where the session can see it.
-    pub sock_ns: u64,
-    /// Frames sealed and wire packets sealed over the accumulation window.
-    pub frames: u64,
-    pub packets: u64,
-}
-
-/// [`ErasureCoder`] shim accumulating the time spent in `encode_into` (the send-path FEC
-/// stage) — only constructed when `PUNKTFUNK_PERF` armed the session's [`SealPerf`]. The
-/// counter is atomic purely to satisfy the trait's `Sync` bound; it lives on one thread.
-struct TimedCoder<'a> {
-    inner: &'a dyn ErasureCoder,
-    ns: &'a std::sync::atomic::AtomicU64,
-}
-
-impl ErasureCoder for TimedCoder<'_> {
-    fn scheme(&self) -> crate::config::FecScheme {
-        self.inner.scheme()
-    }
-    fn encode(
-        &self,
-        data: &[&[u8]],
-        recovery_count: usize,
-    ) -> std::result::Result<Vec<Vec<u8>>, crate::fec::FecError> {
-        self.inner.encode(data, recovery_count)
-    }
-    fn encode_into(
-        &self,
-        data: &[&[u8]],
-        recovery_count: usize,
-        out: &mut Vec<Vec<u8>>,
-    ) -> std::result::Result<(), crate::fec::FecError> {
-        let t0 = std::time::Instant::now();
-        let r = self.inner.encode_into(data, recovery_count, out);
-        self.ns.fetch_add(
-            t0.elapsed().as_nanos() as u64,
-            std::sync::atomic::Ordering::Relaxed,
-        );
-        r
-    }
-    fn reconstruct(
-        &self,
-        data_count: usize,
-        recovery_count: usize,
-        received: &mut [Option<Vec<u8>>],
-    ) -> std::result::Result<Vec<Vec<u8>>, crate::fec::FecError> {
-        self.inner.reconstruct(data_count, recovery_count, received)
-    }
-    fn reconstruct_into(
-        &self,
-        recovery_count: usize,
-        data: &mut [&mut [u8]],
-        have: &[bool],
-        recovery: &[(usize, &[u8])],
-    ) -> std::result::Result<(), crate::fec::FecError> {
-        self.inner
-            .reconstruct_into(recovery_count, data, have, recovery)
-    }
-}
 
 /// Datagrams drained per `recvmmsg` syscall on the client (the reused ring's size). 128 keeps
 /// the syscall rate ≤ ~3.4k/s even at the ~430k pkt/s the post-2026-07-14 receive path delivers
@@ -483,7 +358,10 @@ impl Session {
             }
             let mut split_done = false;
             if two_lane && used >= TWO_LANE_MIN_PACKETS {
-                if let Some(lane) = seal_lane.as_ref() {
+                // Take the lane for the frame: a healthy round-trip puts it back; either
+                // failure arm drops the corpse so the next large frame respawns a fresh one
+                // instead of retrying a dead channel forever.
+                if let Some(lane) = seal_lane.take() {
                     let half = used / 2;
                     let mut tail = std::mem::take(lane_scratch);
                     tail.extend(wires.drain(half..));
@@ -494,7 +372,8 @@ impl Session {
                         ns: 0,
                         result: Ok(()),
                     };
-                    if lane.to_worker.send(job).is_ok() {
+                    match lane.to_worker.send(job) {
+                        Ok(()) => {
                             // Seal the front half while the worker runs; collect BOTH results
                             // before erroring so the lane is always drained and reusable.
                             let t0 = perf_armed.then(std::time::Instant::now);
@@ -502,10 +381,9 @@ impl Session {
                             if let Some(t0) = t0 {
                                 seal_ns += t0.elapsed().as_nanos() as u64;
                             }
-                        let mut done = lane
+                            match lane.from_worker.recv() {
-                            .from_worker
+                                Ok(mut done) => {
-                            .recv()
+                                    *seal_lane = Some(lane);
-                            .map_err(|_| PunktfunkError::Unsupported("seal lane died"))?;
                                     seal_ns += done.ns;
                                     wires.append(&mut done.bufs);
                                     *lane_scratch = done.bufs;
@@ -513,7 +391,23 @@ impl Session {
                                     done.result?;
                                     split_done = true;
                                 }
-                    // A failed send means the worker is gone — fall through to single-lane.
+                                Err(_) => {
+                                    // The worker died holding the back half — the frame is
+                                    // unrecoverable (its packets are gone), but the error now
+                                    // SURFACES instead of `Ok` with half an access unit.
+                                    front?;
+                                    return Err(PunktfunkError::Unsupported("seal lane died"));
+                                }
+                            }
+                        }
+                        Err(std::sync::mpsc::SendError(job)) => {
+                            // The worker is gone but the channel hands the job back: reclaim
+                            // the back half so the single-lane pass below seals the WHOLE
+                            // frame — previously this fall-through sealed and returned only
+                            // the front half, silently, as `Ok`.
+                            wires.extend(job.bufs);
+                        }
+                    }
                 }
             }
             if !split_done {
@@ -684,7 +578,7 @@ impl Session {
                     // Nothing new on the wire — hand over an aged-out partial if one is
                     // waiting (it can only get staler).
                     if let Some(p) = self.reassembler.take_partial() {
-                        return Ok(p);
+                        return Ok(stamp_received(p));
                     }
                     return Err(PunktfunkError::NoFrame);
                 }
@@ -748,12 +642,12 @@ impl Session {
             }
             if let Some(frame) = pushed {
                 StatsCounters::add(&self.stats.frames_completed, 1);
-                return Ok(frame);
+                return Ok(stamp_received(frame));
             }
             // A push that completed nothing may still have aged a partial out — deliver it
             // ahead of further draining (its successors are already arriving).
             if let Some(p) = self.reassembler.take_partial() {
-                return Ok(p);
+                return Ok(stamp_received(p));
             }
         }
     }
@@ -816,102 +710,6 @@ impl Session {
     }
 }
 
-/// Extract the AEAD-authenticated 8-byte big-endian sequence prefix from a sealed wire datagram.
-/// Only called on the encrypted receive path, where a preceding successful open has already
-/// established `wire.len() >= 8`.
-fn seq_of(wire: &[u8]) -> u64 {
-    u64::from_be_bytes(wire[..8].try_into().unwrap())
-}
-
-/// Depth of the anti-replay window, in sequences. The sender advances its sequence once per
-/// datagram, so this must cover the reassembler's 120 ms loss window
-/// ([`LOSS_WINDOW_NS`](crate::packet)) at line-rate packet rates — otherwise the replay filter
-/// silently re-tightens the "late ≠ lost" fix: a Wi-Fi-retry-delayed shard the reassembler would
-/// still use gets dropped here as "older than the window" first (4096 was only ~33 ms at the
-/// ~125k pkt/s of a 1 Gbps stream; 32768 topped out around ~2 Gbps — which the client now
-/// exceeds: the 2026-07-14 zero-copy + hardware-AES work measured ~4.8 Gbps wire ≈ 430k pkt/s
-/// delivered). 131072 covers 120 ms up to ~1.09M pkt/s (≈12 Gbps wire) and is effectively
-/// unbounded for the sparse input stream, while still bounding how far back a replay could
-/// hide; the bitmap costs 16 KiB per session.
-const REPLAY_WINDOW: u64 = 131072;
-const REPLAY_WORDS: usize = (REPLAY_WINDOW / 64) as usize;
-
-/// Sliding-window anti-replay filter over the AEAD-authenticated wire sequence. The sender counts
-/// its datagrams from 0, and the protocol never legitimately re-sends a sequence (FEC recovery
-/// shards get fresh ones), so a sequence seen twice is a replay. The AEAD tag already authenticates
-/// the sequence — a forged one can't open — so this only has to reject *duplicates* of validly
-/// sealed datagrams (and anything older than the window, which we can no longer prove is fresh).
-/// Genuine reordering within the window is accepted. Bitmap-per-sequence, indexed `seq % WINDOW`.
-struct ReplayWindow {
-    /// Highest sequence accepted so far; `seen` stays false until the first datagram.
-    highest: u64,
-    seen: bool,
-    /// One bit per in-window sequence in `(highest - WINDOW, highest]`.
-    bits: [u64; REPLAY_WORDS],
-}
-
-impl ReplayWindow {
-    fn new() -> ReplayWindow {
-        ReplayWindow {
-            highest: 0,
-            seen: false,
-            bits: [0; REPLAY_WORDS],
-        }
-    }
-
-    #[inline]
-    fn word_bit(seq: u64) -> (usize, u64) {
-        let idx = (seq % REPLAY_WINDOW) as usize;
-        (idx / 64, 1u64 << (idx % 64))
-    }
-    fn is_set(&self, seq: u64) -> bool {
-        let (w, b) = Self::word_bit(seq);
-        self.bits[w] & b != 0
-    }
-    fn set(&mut self, seq: u64) {
-        let (w, b) = Self::word_bit(seq);
-        self.bits[w] |= b;
-    }
-    fn unset(&mut self, seq: u64) {
-        let (w, b) = Self::word_bit(seq);
-        self.bits[w] &= !b;
-    }
-
-    /// Record `seq`, returning `true` if it's fresh (accept) or `false` if it's a replay / too old.
-    fn accept(&mut self, seq: u64) -> bool {
-        if !self.seen {
-            self.seen = true;
-            self.highest = seq;
-            self.set(seq);
-            return true;
-        }
-        if seq > self.highest {
-            // Advance the window. Sequences between the old and new high slide in unseen, so clear
-            // their (possibly stale, from a full window ago) slots — unless we jumped an entire
-            // window, in which case wipe the bitmap wholesale.
-            if seq - self.highest >= REPLAY_WINDOW {
-                self.bits = [0; REPLAY_WORDS];
-            } else {
-                let mut s = self.highest + 1;
-                while s < seq {
-                    self.unset(s);
-                    s += 1;
-                }
-            }
-            self.highest = seq;
-            self.set(seq);
-            true
-        } else if self.highest - seq >= REPLAY_WINDOW || self.is_set(seq) {
-            // Older than the window (can't prove it isn't a replay) or already seen (a duplicate) —
-            // either way, drop it.
-            false
-        } else {
-            self.set(seq); // in-window and not yet seen — a genuine reorder
-            true
-        }
-    }
-}
-
 #[cfg(test)]
 mod wire_equivalence_tests {
     use super::*;
@@ -1011,6 +809,42 @@ mod wire_equivalence_tests {
         (0..len).map(|i| (i * 31 + 7) as u8).collect()
     }
 
+    /// A dead seal lane (worker gone, channels dangling) must degrade to a single-lane seal of
+    /// the WHOLE frame — the old fall-through sealed and returned only the front half as `Ok` —
+    /// and the corpse must be dropped so the next large frame respawns a fresh lane.
+    #[test]
+    fn dead_seal_lane_falls_back_to_single_lane_whole_frame() {
+        let mut opt = host_session(host_cfg(FecScheme::Gf16, 20, true));
+        let mut refr = host_session(host_cfg(FecScheme::Gf16, 20, true));
+        // A lane whose worker has already exited: both far ends dropped, so `send` fails
+        // immediately and hands the job (with the frame's back half) back.
+        let (to_worker, jobs) = std::sync::mpsc::sync_channel::<SealJob>(1);
+        let (done_tx, from_worker) = std::sync::mpsc::sync_channel::<SealJob>(1);
+        drop(jobs);
+        drop(done_tx);
+        opt.seal_lane = Some(SealLane {
+            to_worker,
+            from_worker,
+        });
+        let frame = pattern(20000); // > TWO_LANE_MIN_PACKETS wire packets → takes the split path
+        let got = opt.seal_frame(&frame, 7, 0).unwrap();
+        let want = seal_via_wrapper(&mut refr, &frame, 7, 0);
+        assert_eq!(got, want, "fallback must seal the whole frame, not half");
+        assert!(
+            opt.seal_lane.is_none(),
+            "the dead lane must be dropped, not retried forever"
+        );
+        // The next large frame respawns a fresh, working lane.
+        opt.reclaim_wires(got);
+        let got2 = opt.seal_frame(&frame, 8, 1).unwrap();
+        let want2 = seal_via_wrapper(&mut refr, &frame, 8, 1);
+        assert_eq!(got2, want2);
+        assert!(
+            opt.seal_lane.is_some(),
+            "a fresh lane respawns on the next large frame"
+        );
+    }
+
     /// Partial delivery (plan §4.4): a chunk-aligned frame that loses shards past FEC's
     /// reach is DELIVERED once it ages out — `complete: false`, received shards at their
     /// exact offsets, missing ranges zero-filled — instead of silently dropping. Plain
@@ -1106,78 +940,3 @@ mod wire_equivalence_tests {
         );
     }
 }
-
-#[cfg(test)]
-mod replay_tests {
-    use super::*;
-
-    #[test]
-    fn accepts_in_order_and_rejects_duplicates() {
-        let mut w = ReplayWindow::new();
-        for seq in 0..1000 {
-            assert!(w.accept(seq), "fresh in-order seq {seq} must be accepted");
-        }
-        // Every one of those is now a replay.
-        for seq in 0..1000 {
-            assert!(!w.accept(seq), "replayed seq {seq} must be rejected");
-        }
-    }
-
-    #[test]
-    fn accepts_reorder_within_window_once() {
-        let mut w = ReplayWindow::new();
-        assert!(w.accept(100));
-        // Earlier-but-in-window sequences (a genuine reorder) are accepted exactly once.
-        assert!(w.accept(80));
-        assert!(!w.accept(80), "second copy of a reordered seq is a replay");
-        assert!(w.accept(99));
-        assert!(
-            !w.accept(100),
-            "the high-water seq itself can't be replayed"
-        );
-    }
-
-    #[test]
-    fn rejects_older_than_window() {
-        let mut w = ReplayWindow::new();
-        assert!(w.accept(REPLAY_WINDOW * 2));
-        // Anything a full window or more behind the high-water mark is dropped (can't prove fresh).
-        assert!(!w.accept(REPLAY_WINDOW * 2 - REPLAY_WINDOW));
-        assert!(!w.accept(0));
-        // But just inside the window is still accepted.
-        assert!(w.accept(REPLAY_WINDOW * 2 - (REPLAY_WINDOW - 1)));
-    }
-
-    #[test]
-    fn large_forward_jump_wipes_stale_bits() {
-        let mut w = ReplayWindow::new();
-        assert!(w.accept(5));
-        // Jump far forward (more than a window). The slot for an old seq that aliases 5 mod WINDOW
-        // must read as unseen afterward, i.e. the jump cleared it — so a NEW seq there is accepted.
-        let far = 10 * REPLAY_WINDOW + 5;
-        assert!(w.accept(far));
-        assert!(
-            !w.accept(5),
-            "the pre-jump seq is now far older than the window"
-        );
-        // A fresh seq aliasing 5 (mod WINDOW) but inside the new window is accepted, proving the
-        // stale bit was cleared rather than mistaken for a replay.
-        assert!(w.accept(far - REPLAY_WINDOW + 1));
-    }
-
-    #[test]
-    fn first_seq_need_not_be_zero() {
-        // Startup loss can mean the first datagram we ever open isn't seq 0.
-        let mut w = ReplayWindow::new();
-        assert!(w.accept(42));
-        assert!(!w.accept(42));
-        assert!(w.accept(43));
-    }
-
-    #[test]
-    fn seq_of_reads_the_big_endian_prefix() {
-        let mut wire = 0x0102_0304_0506_0708u64.to_be_bytes().to_vec();
-        wire.extend_from_slice(b"ciphertext-and-tag");
-        assert_eq!(seq_of(&wire), 0x0102_0304_0506_0708);
-    }
-}

crates/punktfunk-core/src/session/perf.rs

@@ -0,0 +1,98 @@
+//! `PUNKTFUNK_PERF` stage-timing telemetry for the two hot paths: where the client pump
+//! and the host send thread actually spend their time, accumulated per report window and
+//! drained via [`Session::take_pump_perf`](super::Session::take_pump_perf) /
+//! [`Session::take_seal_perf`](super::Session::take_seal_perf).
+
+use crate::fec::ErasureCoder;
+
+/// Accumulated client receive-path stage timings since the last [`Session::take_pump_perf`](super::Session::take_pump_perf).
+/// Answers "where does the pump core go" at line rate: kernel drain (`recv_ns`) vs AES-GCM
+/// (`decrypt_ns`) vs reassembly+FEC (`reasm_ns`, the `Reassembler::push` round-trip including
+/// shard copies and block reconstruction). 2026-07-14 sweep context: the pump pegs one core at
+/// ~1.5 Gbps wire, ~85% of it userspace — this split is what Phase 2.1 (pooled reassembly) is
+/// validated against.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct PumpPerf {
+    /// ns inside `recv_batch` (recvmmsg / recvmsg_x), i.e. syscall + kernel copy.
+    pub recv_ns: u64,
+    /// ns inside `open_in_place` across all datagrams (AES-128-GCM + replay-window upkeep).
+    pub decrypt_ns: u64,
+    /// ns inside `Reassembler::push` (header parse, shard copy, FEC reconstruct, AU assembly).
+    pub reasm_ns: u64,
+    /// recv_batch calls (batches) and datagrams processed over the accumulation window.
+    pub batches: u64,
+    pub packets: u64,
+}
+
+/// Accumulated host send-path stage timings since the last [`Session::take_seal_perf`](super::Session::take_seal_perf) (plan
+/// Phase 0.4, host half). Answers "where does the send thread go" at rate: FEC parity
+/// generation (`fec_ns`, inside [`ErasureCoder::encode_into`]) vs AES-GCM (`seal_ns`,
+/// per-packet `seal_in_place`) vs the socket handoff (`sock_ns` — `send_gso`/`sendmmsg`
+/// syscalls; the internal submit paths time it here, the paced video path folds its chunk
+/// sends in via [`Session::note_sock_ns`](super::Session::note_sock_ns)). The Phase 1.5 gate reads off this split: build
+/// two-lane seal only if `seal_ns` exceeds ~15% of the send thread at 2 Gbps.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct SealPerf {
+    /// ns inside `ErasureCoder::encode_into` (parity generation).
+    pub fec_ns: u64,
+    /// ns inside `seal_in_place` across all wire packets (AES-128-GCM).
+    pub seal_ns: u64,
+    /// ns inside `send_sealed` (socket syscalls), where the session can see it.
+    pub sock_ns: u64,
+    /// Frames sealed and wire packets sealed over the accumulation window.
+    pub frames: u64,
+    pub packets: u64,
+}
+
+/// [`ErasureCoder`] shim accumulating the time spent in `encode_into` (the send-path FEC
+/// stage) — only constructed when `PUNKTFUNK_PERF` armed the session's [`SealPerf`]. The
+/// counter is atomic purely to satisfy the trait's `Sync` bound; it lives on one thread.
+pub(super) struct TimedCoder<'a> {
+    pub(super) inner: &'a dyn ErasureCoder,
+    pub(super) ns: &'a std::sync::atomic::AtomicU64,
+}
+
+impl ErasureCoder for TimedCoder<'_> {
+    fn scheme(&self) -> crate::config::FecScheme {
+        self.inner.scheme()
+    }
+    fn encode(
+        &self,
+        data: &[&[u8]],
+        recovery_count: usize,
+    ) -> std::result::Result<Vec<Vec<u8>>, crate::fec::FecError> {
+        self.inner.encode(data, recovery_count)
+    }
+    fn encode_into(
+        &self,
+        data: &[&[u8]],
+        recovery_count: usize,
+        out: &mut Vec<Vec<u8>>,
+    ) -> std::result::Result<(), crate::fec::FecError> {
+        let t0 = std::time::Instant::now();
+        let r = self.inner.encode_into(data, recovery_count, out);
+        self.ns.fetch_add(
+            t0.elapsed().as_nanos() as u64,
+            std::sync::atomic::Ordering::Relaxed,
+        );
+        r
+    }
+    fn reconstruct(
+        &self,
+        data_count: usize,
+        recovery_count: usize,
+        received: &mut [Option<Vec<u8>>],
+    ) -> std::result::Result<Vec<Vec<u8>>, crate::fec::FecError> {
+        self.inner.reconstruct(data_count, recovery_count, received)
+    }
+    fn reconstruct_into(
+        &self,
+        recovery_count: usize,
+        data: &mut [&mut [u8]],
+        have: &[bool],
+        recovery: &[(usize, &[u8])],
+    ) -> std::result::Result<(), crate::fec::FecError> {
+        self.inner
+            .reconstruct_into(recovery_count, data, have, recovery)
+    }
+}

crates/punktfunk-core/src/session/replay.rs

@@ -0,0 +1,175 @@
+//! Sliding-window anti-replay filter over the AEAD-authenticated wire sequence
+//! (plan §1). Applied on both encrypted receive paths —
+//! [`Session::poll_frame`](super::Session::poll_frame) and
+//! [`Session::poll_input`](super::Session::poll_input).
+
+/// Extract the AEAD-authenticated 8-byte big-endian sequence prefix from a sealed wire datagram.
+/// Only called on the encrypted receive path, where a preceding successful open has already
+/// established `wire.len() >= 8`.
+pub(super) fn seq_of(wire: &[u8]) -> u64 {
+    u64::from_be_bytes(wire[..8].try_into().unwrap())
+}
+
+/// Depth of the anti-replay window, in sequences. The sender advances its sequence once per
+/// datagram, so this must cover the reassembler's 120 ms loss window
+/// ([`LOSS_WINDOW_NS`](crate::packet)) at line-rate packet rates — otherwise the replay filter
+/// silently re-tightens the "late ≠ lost" fix: a Wi-Fi-retry-delayed shard the reassembler would
+/// still use gets dropped here as "older than the window" first (4096 was only ~33 ms at the
+/// ~125k pkt/s of a 1 Gbps stream; 32768 topped out around ~2 Gbps — which the client now
+/// exceeds: the 2026-07-14 zero-copy + hardware-AES work measured ~4.8 Gbps wire ≈ 430k pkt/s
+/// delivered). 131072 covers 120 ms up to ~1.09M pkt/s (≈12 Gbps wire) and is effectively
+/// unbounded for the sparse input stream, while still bounding how far back a replay could
+/// hide; the bitmap costs 16 KiB per session.
+const REPLAY_WINDOW: u64 = 131072;
+const REPLAY_WORDS: usize = (REPLAY_WINDOW / 64) as usize;
+
+/// Sliding-window anti-replay filter over the AEAD-authenticated wire sequence. The sender counts
+/// its datagrams from 0, and the protocol never legitimately re-sends a sequence (FEC recovery
+/// shards get fresh ones), so a sequence seen twice is a replay. The AEAD tag already authenticates
+/// the sequence — a forged one can't open — so this only has to reject *duplicates* of validly
+/// sealed datagrams (and anything older than the window, which we can no longer prove is fresh).
+/// Genuine reordering within the window is accepted. Bitmap-per-sequence, indexed `seq % WINDOW`.
+pub(super) struct ReplayWindow {
+    /// Highest sequence accepted so far; `seen` stays false until the first datagram.
+    highest: u64,
+    seen: bool,
+    /// One bit per in-window sequence in `(highest - WINDOW, highest]`.
+    bits: [u64; REPLAY_WORDS],
+}
+
+impl ReplayWindow {
+    pub(super) fn new() -> ReplayWindow {
+        ReplayWindow {
+            highest: 0,
+            seen: false,
+            bits: [0; REPLAY_WORDS],
+        }
+    }
+
+    #[inline]
+    fn word_bit(seq: u64) -> (usize, u64) {
+        let idx = (seq % REPLAY_WINDOW) as usize;
+        (idx / 64, 1u64 << (idx % 64))
+    }
+    fn is_set(&self, seq: u64) -> bool {
+        let (w, b) = Self::word_bit(seq);
+        self.bits[w] & b != 0
+    }
+    fn set(&mut self, seq: u64) {
+        let (w, b) = Self::word_bit(seq);
+        self.bits[w] |= b;
+    }
+    fn unset(&mut self, seq: u64) {
+        let (w, b) = Self::word_bit(seq);
+        self.bits[w] &= !b;
+    }
+
+    /// Record `seq`, returning `true` if it's fresh (accept) or `false` if it's a replay / too old.
+    pub(super) fn accept(&mut self, seq: u64) -> bool {
+        if !self.seen {
+            self.seen = true;
+            self.highest = seq;
+            self.set(seq);
+            return true;
+        }
+        if seq > self.highest {
+            // Advance the window. Sequences between the old and new high slide in unseen, so clear
+            // their (possibly stale, from a full window ago) slots — unless we jumped an entire
+            // window, in which case wipe the bitmap wholesale.
+            if seq - self.highest >= REPLAY_WINDOW {
+                self.bits = [0; REPLAY_WORDS];
+            } else {
+                let mut s = self.highest + 1;
+                while s < seq {
+                    self.unset(s);
+                    s += 1;
+                }
+            }
+            self.highest = seq;
+            self.set(seq);
+            true
+        } else if self.highest - seq >= REPLAY_WINDOW || self.is_set(seq) {
+            // Older than the window (can't prove it isn't a replay) or already seen (a duplicate) —
+            // either way, drop it.
+            false
+        } else {
+            self.set(seq); // in-window and not yet seen — a genuine reorder
+            true
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accepts_in_order_and_rejects_duplicates() {
+        let mut w = ReplayWindow::new();
+        for seq in 0..1000 {
+            assert!(w.accept(seq), "fresh in-order seq {seq} must be accepted");
+        }
+        // Every one of those is now a replay.
+        for seq in 0..1000 {
+            assert!(!w.accept(seq), "replayed seq {seq} must be rejected");
+        }
+    }
+
+    #[test]
+    fn accepts_reorder_within_window_once() {
+        let mut w = ReplayWindow::new();
+        assert!(w.accept(100));
+        // Earlier-but-in-window sequences (a genuine reorder) are accepted exactly once.
+        assert!(w.accept(80));
+        assert!(!w.accept(80), "second copy of a reordered seq is a replay");
+        assert!(w.accept(99));
+        assert!(
+            !w.accept(100),
+            "the high-water seq itself can't be replayed"
+        );
+    }
+
+    #[test]
+    fn rejects_older_than_window() {
+        let mut w = ReplayWindow::new();
+        assert!(w.accept(REPLAY_WINDOW * 2));
+        // Anything a full window or more behind the high-water mark is dropped (can't prove fresh).
+        assert!(!w.accept(REPLAY_WINDOW * 2 - REPLAY_WINDOW));
+        assert!(!w.accept(0));
+        // But just inside the window is still accepted.
+        assert!(w.accept(REPLAY_WINDOW * 2 - (REPLAY_WINDOW - 1)));
+    }
+
+    #[test]
+    fn large_forward_jump_wipes_stale_bits() {
+        let mut w = ReplayWindow::new();
+        assert!(w.accept(5));
+        // Jump far forward (more than a window). The slot for an old seq that aliases 5 mod WINDOW
+        // must read as unseen afterward, i.e. the jump cleared it — so a NEW seq there is accepted.
+        let far = 10 * REPLAY_WINDOW + 5;
+        assert!(w.accept(far));
+        assert!(
+            !w.accept(5),
+            "the pre-jump seq is now far older than the window"
+        );
+        // A fresh seq aliasing 5 (mod WINDOW) but inside the new window is accepted, proving the
+        // stale bit was cleared rather than mistaken for a replay.
+        assert!(w.accept(far - REPLAY_WINDOW + 1));
+    }
+
+    #[test]
+    fn first_seq_need_not_be_zero() {
+        // Startup loss can mean the first datagram we ever open isn't seq 0.
+        let mut w = ReplayWindow::new();
+        assert!(w.accept(42));
+        assert!(!w.accept(42));
+        assert!(w.accept(43));
+    }
+
+    #[test]
+    fn seq_of_reads_the_big_endian_prefix() {
+        let mut wire = 0x0102_0304_0506_0708u64.to_be_bytes().to_vec();
+        wire.extend_from_slice(b"ciphertext-and-tag");
+        assert_eq!(seq_of(&wire), 0x0102_0304_0506_0708);
+    }
+}

crates/punktfunk-core/src/session/seal.rs

@@ -0,0 +1,74 @@
+//! The second seal lane (plan Phase 1.5): a persistent worker thread that AES-GCM-seals
+//! the back half of a large frame's wire packets while the send thread seals the front.
+//! [`Session`](super::Session)`::seal_frame_inner` owns the split policy; this module owns
+//! the lane machinery and the shared per-slice seal loop.
+
+use crate::crypto::SessionCrypto;
+use crate::error::Result;
+
+/// Wire-packet count at which a frame's sealing splits across two lanes (plan Phase 1.5):
+/// below it the channel rendezvous (~µs) isn't worth it; at it the halved AES-GCM span
+/// (≥ ~125 µs of ~1 µs/packet work) dwarfs the hand-off. ≈300 KB of wire, i.e. ≥150 Mbps
+/// at 60 fps — small frames and the probe's ~17-packet AUs stay strictly single-lane.
+pub(super) const TWO_LANE_MIN_PACKETS: usize = 256;
+
+/// One two-lane seal hand-off: the frame's back-half wire buffers, sealed by the worker with
+/// nonces `seq_base + i` (the nonce order is deterministic per shard index, which is what
+/// makes the split sound). Round-trips through the channels so the buffers return to the pool.
+pub(super) struct SealJob {
+    pub(super) bufs: Vec<Vec<u8>>,
+    pub(super) seq_base: u64,
+    pub(super) timed: bool,
+    /// Worker-lane CPU ns (when `timed`) and the seal outcome, filled in by the worker.
+    pub(super) ns: u64,
+    pub(super) result: Result<()>,
+}
+
+/// The persistent second seal lane: a worker thread that AES-GCM-seals the back half of a
+/// large frame's packets while the send thread seals the front half. Rendezvous channels
+/// (bound 1) — the send thread submits, seals its half, then waits; no per-frame spawn.
+/// Dropping the struct closes the channel and the worker exits.
+pub(super) struct SealLane {
+    pub(super) to_worker: std::sync::mpsc::SyncSender<SealJob>,
+    pub(super) from_worker: std::sync::mpsc::Receiver<SealJob>,
+}
+
+impl SealLane {
+    pub(super) fn spawn(crypto: std::sync::Arc<SessionCrypto>) -> Option<SealLane> {
+        let (to_worker, jobs) = std::sync::mpsc::sync_channel::<SealJob>(1);
+        let (done_tx, from_worker) = std::sync::mpsc::sync_channel::<SealJob>(1);
+        std::thread::Builder::new()
+            .name("punktfunk-seal2".into())
+            .spawn(move || {
+                while let Ok(mut job) = jobs.recv() {
+                    let t0 = job.timed.then(std::time::Instant::now);
+                    job.result = seal_wire_slice(&crypto, &mut job.bufs, job.seq_base);
+                    if let Some(t0) = t0 {
+                        job.ns = t0.elapsed().as_nanos() as u64;
+                    }
+                    if done_tx.send(job).is_err() {
+                        break; // session gone mid-frame — nothing left to seal for
+                    }
+                }
+            })
+            .ok()?;
+        Some(SealLane {
+            to_worker,
+            from_worker,
+        })
+    }
+}
+
+/// Seal a run of pre-written wire buffers in place: buffer `i` is `seq(8) ‖ plaintext ‖ tag
+/// scratch` and seals over `[8..]` with sequence `seq_base + i` — the exact per-packet layout
+/// and nonce order of the fused single-lane path. Shared by both lanes.
+pub(super) fn seal_wire_slice(
+    c: &SessionCrypto,
+    wires: &mut [Vec<u8>],
+    seq_base: u64,
+) -> Result<()> {
+    for (i, wire) in wires.iter_mut().enumerate() {
+        c.seal_in_place(seq_base.wrapping_add(i as u64), &mut wire[8..])?;
+    }
+    Ok(())
+}

crates/punktfunk-core/src/transport/udp/linux.rs

@@ -198,8 +198,14 @@ pub(super) fn send_gso(t: &UdpTransport, packets: &[&[u8]]) -> std::io::Result<u
         return send_batch(t, packets);
     }
     let fd = t.socket.as_raw_fd();
-    // A GSO super-buffer is capped at 64 segments AND 65535 payload bytes (kernel limits).
+    // A GSO super-buffer is capped at 64 segments AND, in bytes, by the kernel's UDP payload
-    let max_seg = (65535 / seg).clamp(1, 64);
+    // ceiling. 65535 is the IP-datagram cap — the payload is that minus the IP + UDP headers
+    // the cork accounts for (IPv4: 65507, IPv6: 65487). Use the tighter v6 figure: it costs at
+    // most one segment per train, while a super-buffer over the ceiling is bounced with
+    // EMSGSIZE — which gso_unsupported() reads as "no GSO on this path" and latches GSO off
+    // process-wide, silently forfeiting the multi-Gbps lever over a local arithmetic slip.
+    const GSO_MAX_PAYLOAD: usize = 65535 - 40 - 8;
+    let max_seg = (GSO_MAX_PAYLOAD / seg).clamp(1, 64);
     let mut scratch: Vec<u8> = Vec::with_capacity(seg * max_seg);
     let mut sent = 0usize;
     for chunk in packets.chunks(max_seg) {

crates/punktfunk-core/src/transport/udp/mod.rs

@@ -110,9 +110,19 @@ pub fn spawn_data_punch(sock: UdpSocket, stop: std::sync::Arc<std::sync::atomic:
         .spawn(move || {
             let mut i = 0u32;
             while !stop.load(std::sync::atomic::Ordering::Relaxed) {
-                if sock.send(PUNCH_MAGIC).is_err() {
+                match sock.send(PUNCH_MAGIC) {
+                    Ok(_) => {}
+                    // Same contract as `Transport::send`: a momentarily full tx queue, a stale
+                    // ICMP or a network-path blip is a lossy drop, not a reason to stop holding
+                    // the NAT/firewall path open. Breaking here is silent and permanent — the
+                    // path recovers, video keeps flowing, and the stream dies later when the
+                    // idle timer expires the mapping during a static scene.
+                    Err(e) if is_transient_io(&e) => {}
+                    Err(e) => {
+                        tracing::debug!(error = %e, "data-plane punch send failed — stopping keepalive");
                         break;
                     }
+                }
                 let delay_ms = if i < 15 { 200 } else { 2000 };
                 i = i.saturating_add(1);
                 std::thread::sleep(std::time::Duration::from_millis(delay_ms));
@@ -160,34 +170,65 @@ impl UdpTransport {
     /// NAT-translated one, which can differ from the client-reported `fallback_peer`). If no punch
     /// arrives (a client that doesn't hole-punch), fall back to `fallback_peer` — the same flat-LAN
     /// behaviour as [`connect`](Self::connect). Returns `(transport, punched)`.
+    ///
+    /// `expect_ip` is the *authenticated* peer address (the QUIC connection's remote IP) — see
+    /// [`from_socket_punch`](Self::from_socket_punch) for why only punches from it are honoured.
     pub fn connect_via_punch(
         local: &str,
         fallback_peer: &str,
+        expect_ip: std::net::IpAddr,
         punch_timeout: std::time::Duration,
     ) -> std::io::Result<(Self, bool)> {
-        Self::from_socket_punch(UdpSocket::bind(local)?, fallback_peer, punch_timeout)
+        Self::from_socket_punch(
+            UdpSocket::bind(local)?,
+            fallback_peer,
+            expect_ip,
+            punch_timeout,
+        )
     }
 
     /// [`connect_via_punch`](Self::connect_via_punch) on an already-bound socket — see
     /// [`from_socket`](Self::from_socket) for why the host binds the data port up front.
+    ///
+    /// `expect_ip` binds the data plane to the peer the control plane already authenticated.
+    /// [`PUNCH_MAGIC`] is a fixed public constant carrying no key, nonce or session id, so without
+    /// this check *any* source that lands an 8-byte datagram on the (ephemeral, sprayable) data
+    /// port during the punch wait becomes the video destination — the legitimate client is then
+    /// filtered out by the `connect` below and receives nothing, while QUIC stays healthy so no
+    /// reconnect is triggered. Only the *port* is in question here (that is what a NAT remaps, and
+    /// what the punch exists to discover); the IP is known, because the client binds `0.0.0.0:0`
+    /// and dials the same host IP as its QUIC connection, so the kernel picks the same source IP
+    /// for both planes and any NAT on the path presents one source IP for both.
     pub fn from_socket_punch(
         socket: UdpSocket,
         fallback_peer: &str,
+        expect_ip: std::net::IpAddr,
         punch_timeout: std::time::Duration,
     ) -> std::io::Result<(Self, bool)> {
-        socket.set_read_timeout(Some(punch_timeout))?;
         let deadline = std::time::Instant::now() + punch_timeout;
         let mut buf = [0u8; 64];
         let mut observed: Option<std::net::SocketAddr> = None;
         loop {
+            // Budget the read from what's LEFT, not the full window: off-peer datagrams are
+            // discarded below, and a full-window timeout per read would let a stray flood stretch
+            // the punch wait far past `punch_timeout`.
+            let remaining = deadline.saturating_duration_since(std::time::Instant::now());
+            if remaining.is_zero() {
+                break;
+            }
+            socket.set_read_timeout(Some(remaining))?;
             match socket.recv_from(&mut buf) {
                 Ok((n, src))
-                    if n >= PUNCH_MAGIC.len() && &buf[..PUNCH_MAGIC.len()] == PUNCH_MAGIC =>
+                    if src.ip() == expect_ip
+                        && n >= PUNCH_MAGIC.len()
+                        && &buf[..PUNCH_MAGIC.len()] == PUNCH_MAGIC =>
                 {
                     observed = Some(src);
                     break;
                 }
-                Ok(_) => {} // stray datagram — keep waiting for a real punch
+                // Stray, or a well-formed punch from someone who isn't the authenticated peer —
+                // keep waiting for a real one.
+                Ok(_) => {}
                 Err(e)
                     if matches!(
                         e.kind(),
@@ -198,9 +239,6 @@ impl UdpTransport {
                 }
                 Err(e) => return Err(e),
             }
-            if std::time::Instant::now() >= deadline {
-                break;
-            }
         }
         let punched = observed.is_some();
         let target = observed.map(|s| s.to_string());
@@ -482,4 +520,89 @@ mod tests {
             "every datagram should be drained via recv_batch"
         );
     }
+
+    /// The punch discovers the peer's NAT-remapped *port*, so a punch from the authenticated IP on
+    /// a port that differs from the client-reported one must still be adopted — that is the whole
+    /// reason hole-punching exists, and the source-IP check must not break it.
+    #[test]
+    fn punch_adopts_remapped_port_from_the_authenticated_peer() {
+        // Stands in for the client's post-NAT data socket: same IP as the "QUIC peer", new port.
+        let puncher = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+        puncher
+            .set_read_timeout(Some(std::time::Duration::from_millis(500)))
+            .unwrap();
+        // The client-*reported* address, which the NAT remapped — video must NOT go here.
+        let reported = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+        reported
+            .set_read_timeout(Some(std::time::Duration::from_millis(200)))
+            .unwrap();
+
+        let host_sock = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+        let host_addr = host_sock.local_addr().unwrap();
+        puncher.send_to(PUNCH_MAGIC, host_addr).unwrap();
+
+        let (transport, punched) = UdpTransport::from_socket_punch(
+            host_sock,
+            &reported.local_addr().unwrap().to_string(),
+            std::net::IpAddr::from([127, 0, 0, 1]),
+            std::time::Duration::from_millis(500),
+        )
+        .unwrap();
+        assert!(punched, "a punch from the authenticated IP must be adopted");
+
+        transport.send(b"video").unwrap();
+        let mut buf = [0u8; 64];
+        let n = puncher
+            .recv(&mut buf)
+            .expect("video must follow the punched (NAT-remapped) port");
+        assert_eq!(&buf[..n], b"video");
+        assert!(
+            reported.recv(&mut buf).is_err(),
+            "video must not go to the stale reported port"
+        );
+    }
+
+    /// A punch from any source other than the QUIC-authenticated peer must be ignored: `PUNCH_MAGIC`
+    /// is a fixed public constant with no key or session id, so honouring an off-peer punch lets
+    /// anyone who lands an 8-byte datagram on the ephemeral data port steal (or redirect) the video
+    /// plane while the control plane stays healthy. Falling back to the reported address is correct.
+    #[test]
+    fn punch_from_an_unauthenticated_source_is_ignored() {
+        let attacker = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+        attacker
+            .set_read_timeout(Some(std::time::Duration::from_millis(200)))
+            .unwrap();
+        let legit = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+        legit
+            .set_read_timeout(Some(std::time::Duration::from_millis(500)))
+            .unwrap();
+
+        let host_sock = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+        let host_addr = host_sock.local_addr().unwrap();
+        attacker.send_to(PUNCH_MAGIC, host_addr).unwrap();
+
+        // The authenticated peer is TEST-NET-1, so nothing arriving over loopback is the peer.
+        let (transport, punched) = UdpTransport::from_socket_punch(
+            host_sock,
+            &legit.local_addr().unwrap().to_string(),
+            std::net::IpAddr::from([192, 0, 2, 1]),
+            std::time::Duration::from_millis(300),
+        )
+        .unwrap();
+        assert!(
+            !punched,
+            "an off-peer punch must not be adopted as the video destination"
+        );
+
+        transport.send(b"video").unwrap();
+        let mut buf = [0u8; 64];
+        assert!(
+            attacker.recv(&mut buf).is_err(),
+            "video must never be redirected to the punch source"
+        );
+        let n = legit
+            .recv(&mut buf)
+            .expect("video falls back to the reported peer address");
+        assert_eq!(&buf[..n], b"video");
+    }
 }

crates/punktfunk-core/vendor/fec-rs/src/galois.rs

@@ -187,34 +187,58 @@ pub fn detect_mul_slice() -> (MulSliceFn, MulSliceFn) {
 // Safe wrappers for SIMD functions (used as function pointer targets)
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_gfni_avx2(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_gfni_avx2(c, input, out) }
 }
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_xor_gfni_avx2(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_xor_gfni_avx2(c, input, out) }
 }
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_avx2(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_avx2(c, input, out) }
 }
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_xor_avx2(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_xor_avx2(c, input, out) }
 }
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_gfni_sse(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_gfni_sse(c, input, out) }
 }
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_xor_gfni_sse(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_xor_gfni_sse(c, input, out) }
 }
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_ssse3(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_ssse3(c, input, out) }
 }
 #[cfg(target_arch = "x86_64")]
 fn wrap_mul_slice_xor_ssse3(c: u8, input: &[u8], out: &mut [u8]) {
+    // The unsafe callee bounds every load AND store on input.len(); unequal
+    // lengths would write past `out`. Same invariant mul_slice/mul_slice_xor enforce.
+    assert_eq!(input.len(), out.len());
     unsafe { mul_slice_xor_ssse3(c, input, out) }
 }
 

crates/punktfunk-core/vendor/fec-rs/src/reed_solomon.rs

@@ -624,8 +624,15 @@ impl ReedSolomon {
             for (i_input, &valid_idx) in valid_indices.iter().enumerate() {
                 // SAFETY: valid_idx and missing indices are disjoint sets,
                 // so we can safely read from valid_idx while writing to missing indices.
-                let input_ptr = shards[valid_idx].get().unwrap().as_ptr();
+                // Pointer AND length from the same `get()` — an impl whose `len()`
-                let input_slice = unsafe { std::slice::from_raw_parts(input_ptr, shard_len) };
+                // disagrees with its slice then panics in `mul_slice` instead of this
+                // fabricating an out-of-bounds slice from the trait-reported length.
+                let (input_ptr, input_len) = {
+                    let input = shards[valid_idx].get().unwrap();
+                    debug_assert_eq!(input.len(), shard_len);
+                    (input.as_ptr(), input.len())
+                };
+                let input_slice = unsafe { std::slice::from_raw_parts(input_ptr, input_len) };
 
                 for (i_out, &missing_idx) in missing_data_indices.iter().enumerate() {
                     let c = matrix_rows[i_out][i_input];
@@ -659,8 +666,13 @@ impl ReedSolomon {
 
             for i_input in 0..self.data_shard_count {
                 // SAFETY: data shards (0..data_shard_count) are disjoint from parity shards.
-                let input_ptr = shards[i_input].get().unwrap().as_ptr();
+                // Same discipline as the data-shard loop above: length from the slice.
-                let input_slice = unsafe { std::slice::from_raw_parts(input_ptr, shard_len) };
+                let (input_ptr, input_len) = {
+                    let input = shards[i_input].get().unwrap();
+                    debug_assert_eq!(input.len(), shard_len);
+                    (input.as_ptr(), input.len())
+                };
+                let input_slice = unsafe { std::slice::from_raw_parts(input_ptr, input_len) };
 
                 for (i_out, &missing_idx) in missing_parity_indices.iter().enumerate() {
                     let c = matrix_rows[i_out][i_input];
@@ -702,6 +714,10 @@ impl ReedSolomon {
 /// yield non-overlapping memory regions from `get()`/`get_mut()`. Specifically:
 /// - `get()` on element `i` must not alias `get_mut()` on element `j` when `i != j`.
 /// - The returned slices must remain valid and not be moved/reallocated while borrows are active.
+/// - `len()` must return `Some(n)` exactly when `get()`/`get_mut()` return `Some(s)`, and then
+///   `s.len() == n`; after `initialize(n)`, `get_mut()` must return a slice of length `n`.
+///   `reconstruct_internal` sizes its raw-pointer reads from `len()`, so a disagreement would
+///   otherwise read past the allocation.
 ///
 /// This is required because `reconstruct_internal` uses raw pointers to read from
 /// some shard indices while writing to others simultaneously.

crates/punktfunk-host/src/main.rs

@@ -168,6 +168,29 @@ fn main() {
     }
 }
 
+/// A lightweight management/CLI subcommand — package/service/driver ops, spec/library dumps — as
+/// opposed to a streaming/capture command. These never touch DXGI or run the host, so they skip the
+/// startup banner and (on Windows) the GPU-preference hook, whose DPI-awareness probe otherwise
+/// prints an alarming `SetProcessDpiAwarenessContext … "access denied"` WARN on a plain
+/// `plugins add`. `service run` is the SCM-launched host itself, so it is explicitly NOT lightweight
+/// (it must keep the hook — the hybrid-GPU ACCESS_LOST fix depends on it).
+fn is_management_cli(args: &[String]) -> bool {
+    match args.first().map(String::as_str) {
+        Some("plugins")
+        | Some("driver")
+        | Some("web")
+        | Some("openapi")
+        | Some("library")
+        | Some("detect-conflicts")
+        | Some("-h")
+        | Some("--help")
+        | Some("help")
+        | None => true,
+        Some("service") => args.get(1).map(String::as_str) != Some("run"),
+        _ => false,
+    }
+}
+
 fn real_main() -> Result<()> {
     let args: Vec<String> = std::env::args().skip(1).collect();
 
@@ -180,11 +203,16 @@ fn real_main() -> Result<()> {
         return Ok(());
     }
 
+    // Lightweight CLI commands (e.g. `plugins add`) get none of the host-startup noise below.
+    let management_cli = is_management_cli(&args);
+
+    if !management_cli {
         tracing::info!(
             "punktfunk-host {} (punktfunk_core ABI v{})",
             env!("PUNKTFUNK_VERSION"),
             punktfunk_core::ABI_VERSION
         );
+    }
 
     // Wire pf-vdisplay's display-lifecycle events into the SSE event bus (the subsystem crate emits a
     // neutral DisplayEvent; the orchestrator owns the bus type — plan §W6). Set once, ignore re-set.
@@ -208,8 +236,12 @@ fn real_main() -> Result<()> {
     // render-adapter selection creates a DXGI factory during virtual-display setup, well before
     // capture). On a hybrid-GPU box this stops DXGI from reparenting the virtual output off the
     // capture GPU — the ACCESS_LOST churn fix. Idempotent (Once); harmless on non-hybrid boxes.
+    // Skipped for lightweight CLI commands (`plugins`, `openapi`, …): they never touch DXGI, and the
+    // hook's DPI-awareness probe prints a misleading "access denied" WARN that looks like a failure.
     #[cfg(target_os = "windows")]
+    if !management_cli {
         crate::capture::dxgi::install_gpu_pref_hook();
+    }
 
     // NVIDIA clock hygiene (Linux, host subcommands only): install the P2-cap driver profile and,
     // under PUNKTFUNK_PIN_CLOCKS, hold the NVML core-clock floor for the host lifetime (reset on
@@ -498,6 +530,10 @@ fn parse_serve(args: &[String]) -> Result<(mgmt::Options, native::NativeServe, b
     if opts.token.is_none() {
         opts.token = Some(crate::mgmt_token::load_or_generate()?);
     }
+    // The scripting runner's scoped credential: minted + persisted (plugin-token) alongside the
+    // admin token so a plugin's zero-config `connect()` picks it up — it authorizes the plugin
+    // surface but not hook registration or pairing administration (mgmt::auth::plugin_may_access).
+    opts.plugin_token = Some(crate::mgmt_token::load_or_generate_plugin()?);
     // Default the mgmt listener to ALL interfaces (not just loopback) so a paired native client can
     // fetch the game library over mTLS with no operator step — the whole point of "browse works by
     // default". This only LAN-exposes the read-only cert allowlist; the bearer-token admin surface

crates/punktfunk-host/src/mgmt.rs

@@ -56,6 +56,10 @@ pub struct Options {
     /// Bearer token required on `/api/v1` (except `/health`). `None` ⇒ unauthenticated,
     /// which [`run`] only permits on loopback binds.
     pub token: Option<String>,
+    /// The scripting runner's capability-limited bearer token (`plugin-token`): authorizes the
+    /// plugin surface only, never hook registration or pairing administration
+    /// (`auth::plugin_may_access`). Optional — `None` simply disables the lane.
+    pub plugin_token: Option<String>,
 }
 
 impl Default for Options {
@@ -63,6 +67,7 @@ impl Default for Options {
         Options {
             bind: SocketAddr::from(([127, 0, 0, 1], DEFAULT_PORT)),
             token: None,
+            plugin_token: None,
         }
     }
 }
@@ -81,6 +86,9 @@ pub(crate) struct MgmtState {
     /// (native-only) host, where a Moonlight PIN can never arrive.
     gamestream_enabled: bool,
     token: Option<String>,
+    /// The plugin lane's token (see [`Options::plugin_token`]). Checked only after the admin token
+    /// mismatches, and gated by `auth::plugin_may_access` per route.
+    plugin_token: Option<String>,
     /// The port we serve on, echoed in [`PortMap`] so a client can persist a full endpoint map.
     port: u16,
 }
@@ -119,6 +127,7 @@ pub async fn run(
     let app = app(
         state,
         Some(token),
+        opts.plugin_token.filter(|t| !t.trim().is_empty()),
         opts.bind.port(),
         native,
         stats,
@@ -131,6 +140,7 @@ pub async fn run(
 fn app(
     state: Arc<AppState>,
     token: Option<String>,
+    plugin_token: Option<String>,
     port: u16,
     native: Option<Arc<crate::native_pairing::NativePairing>>,
     stats: Arc<crate::stats_recorder::StatsRecorder>,
@@ -142,6 +152,7 @@ fn app(
         stats,
         gamestream_enabled,
         token,
+        plugin_token,
         port,
     });
     let (api_routes, api) = api_router_parts();

crates/punktfunk-host/src/mgmt/auth.rs

@@ -1,5 +1,12 @@
 //! Auth gate for the management API `/api/v1` routes: paired client cert (mTLS, from anywhere)
-//! or the bearer token (loopback peers only). Split out of the `mgmt` facade (plan §W5).
+//! or a bearer token (loopback peers only). Split out of the `mgmt` facade (plan §W5).
+//!
+//! Three lanes, three authorities:
+//! - **paired streaming cert** (mTLS, LAN) — the read-only [`cert_may_access`] allowlist.
+//! - **plugin token** (bearer, loopback) — the scripting runner's capability-limited credential:
+//!   the admin surface MINUS hook registration and pairing administration
+//!   ([`plugin_may_access`]).
+//! - **admin token** (bearer, loopback) — everything.
 
 use super::shared::*;
 use crate::gamestream::tls::PeerAddr;
@@ -86,6 +93,27 @@ pub(crate) async fn require_auth(
         .and_then(|v| v.strip_prefix("Bearer "));
     match presented {
         Some(token) if token_eq(token, expected) => next.run(req).await,
+        // The scripting runner's scoped lane: same loopback confinement as the admin token, but
+        // routes that would let a plugin escalate — registering hooks (arbitrary command
+        // execution as the host user) or administering pairing (admitting/ejecting devices,
+        // reading the PIN) — need the operator's admin token. Checked AFTER the admin token so
+        // equal tokens (operator misconfiguration) degrade to full access, never to a lockout.
+        Some(token)
+            if st
+                .plugin_token
+                .as_deref()
+                .is_some_and(|pt| token_eq(token, pt)) =>
+        {
+            if plugin_may_access(req.method(), req.uri().path()) {
+                next.run(req).await
+            } else {
+                api_error(
+                    StatusCode::FORBIDDEN,
+                    "this route is not authorized for the plugin token — it requires the \
+                     operator's admin token",
+                )
+            }
+        }
         _ => api_error(
             StatusCode::UNAUTHORIZED,
             "missing or invalid credentials (a paired client cert, or a bearer token)",
@@ -93,6 +121,31 @@ pub(crate) async fn require_auth(
     }
 }
 
+/// Which routes the scripting runner's **plugin token** may reach: the admin surface minus the
+/// escalation routes. Exclusion-based (a plugin legitimately reads status/library/events, drives
+/// sessions, and registers its UI lease), with these carve-outs:
+/// - **hooks** — `hooks.json` runs operator commands on lifecycle events; writing it is arbitrary
+///   command execution as the host user, and reading it can expose webhook credentials.
+/// - **pairing administration** — arming/approving/denying/unpairing (and PIN visibility) decide
+///   *which devices may stream*; a plugin defect must not be able to admit an attacker's device
+///   or eject the operator's.
+/// - **UI proxy credentials** — a plugin has no business reading another plugin's per-boot UI
+///   secret; only the console proxy (admin token) needs it.
+pub(crate) fn plugin_may_access(method: &Method, path: &str) -> bool {
+    let denied = path == "/api/v1/hooks"
+        || path == "/api/v1/pair"
+        || path.starts_with("/api/v1/pair/")
+        || path == "/api/v1/native/pair"
+        || path.starts_with("/api/v1/native/pair/")
+        || path == "/api/v1/native/pending"
+        || path.starts_with("/api/v1/native/pending/")
+        || (method == Method::DELETE
+            && (path.starts_with("/api/v1/clients/")
+                || path.starts_with("/api/v1/native/clients/")))
+        || (path.starts_with("/api/v1/plugins/") && path.ends_with("/ui-credential"));
+    !denied
+}
+
 /// Which routes a paired *streaming* cert (mTLS, no bearer token) may reach: a small allowlist of
 /// safe, read-only status routes only. Deny-by-default — every state-changing route and every route
 /// that exposes a pairing PIN or the pending-approval queue requires the operator's bearer token, so

crates/punktfunk-host/src/mgmt/tests.rs

@@ -42,6 +42,8 @@ fn test_app(state: Arc<AppState>, token: Option<&str>) -> Router {
     app(
         state,
         Some(token.unwrap_or("test-secret").to_string()),
+        // The scoped plugin lane, exercised by the `plugin_token_*` tests below.
+        Some("plugin-secret".to_string()),
         DEFAULT_PORT,
         None,
         stats,
@@ -57,6 +59,7 @@ fn test_app_native(state: Arc<AppState>, np: Arc<crate::native_pairing::NativePa
     app(
         state,
         Some("test-secret".to_string()),
+        Some("plugin-secret".to_string()),
         DEFAULT_PORT,
         Some(np),
         stats,
@@ -374,6 +377,133 @@ async fn bearer_token_is_enforced() {
     );
 }
 
+/// The pure route gate for the plugin lane: exclusion-based, so spot-check both sides — the
+/// surface a plugin legitimately uses, and every escalation carve-out.
+#[test]
+fn plugin_allowlist_excludes_escalation_routes() {
+    use axum::http::Method;
+
+    // The legitimate plugin surface stays open (including mutations — sessions, library, leases).
+    assert!(auth::plugin_may_access(&Method::GET, "/api/v1/status"));
+    assert!(auth::plugin_may_access(&Method::GET, "/api/v1/library"));
+    assert!(auth::plugin_may_access(&Method::GET, "/api/v1/clients"));
+    assert!(auth::plugin_may_access(&Method::GET, "/api/v1/plugins"));
+    assert!(auth::plugin_may_access(
+        &Method::PUT,
+        "/api/v1/plugins/rom-manager"
+    ));
+    assert!(auth::plugin_may_access(
+        &Method::DELETE,
+        "/api/v1/plugins/rom-manager"
+    ));
+
+    // Hooks: registration is command execution; even the read can expose webhook credentials.
+    assert!(!auth::plugin_may_access(&Method::GET, "/api/v1/hooks"));
+    assert!(!auth::plugin_may_access(&Method::PUT, "/api/v1/hooks"));
+
+    // Pairing administration + PIN visibility.
+    assert!(!auth::plugin_may_access(&Method::GET, "/api/v1/pair"));
+    assert!(!auth::plugin_may_access(&Method::POST, "/api/v1/pair/pin"));
+    assert!(!auth::plugin_may_access(
+        &Method::GET,
+        "/api/v1/native/pair"
+    ));
+    assert!(!auth::plugin_may_access(
+        &Method::POST,
+        "/api/v1/native/pair/arm"
+    ));
+    assert!(!auth::plugin_may_access(
+        &Method::GET,
+        "/api/v1/native/pending"
+    ));
+    assert!(!auth::plugin_may_access(
+        &Method::POST,
+        "/api/v1/native/pending/1/approve"
+    ));
+    assert!(!auth::plugin_may_access(
+        &Method::DELETE,
+        "/api/v1/clients/aabbcc"
+    ));
+    assert!(!auth::plugin_may_access(
+        &Method::DELETE,
+        "/api/v1/native/clients/aabbcc"
+    ));
+
+    // Another plugin's UI proxy secret.
+    assert!(!auth::plugin_may_access(
+        &Method::GET,
+        "/api/v1/plugins/x/ui-credential"
+    ));
+}
+
+/// The plugin bearer lane end-to-end: scoped 403s on the carve-outs, 200s on the plugin surface,
+/// and the same loopback confinement as the admin token.
+#[tokio::test]
+async fn plugin_token_lane_is_scoped_and_loopback_only() {
+    use axum::http::Method;
+    let app = test_app(test_state(), None); // admin "test-secret", plugin "plugin-secret"
+
+    let plugin_req = |method: Method, path: &str| {
+        axum::http::Request::builder()
+            .method(method)
+            .uri(path)
+            .header("authorization", "Bearer plugin-secret")
+            .body(Body::empty())
+            .unwrap()
+    };
+
+    // The plugin surface authenticates: status + the plugin directory (list and lease removal).
+    assert_eq!(
+        send(&app, plugin_req(Method::GET, "/api/v1/status"))
+            .await
+            .0,
+        StatusCode::OK
+    );
+    assert_eq!(
+        send(&app, plugin_req(Method::GET, "/api/v1/plugins"))
+            .await
+            .0,
+        StatusCode::OK
+    );
+    assert_eq!(
+        send(
+            &app,
+            plugin_req(Method::DELETE, "/api/v1/plugins/no-such-plugin")
+        )
+        .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"),
+        (Method::PUT, "/api/v1/hooks"),
+        (Method::GET, "/api/v1/pair"),
+        (Method::POST, "/api/v1/native/pair/arm"),
+        (Method::GET, "/api/v1/native/pending"),
+        (Method::DELETE, "/api/v1/clients/aabbcc"),
+        (Method::GET, "/api/v1/plugins/x/ui-credential"),
+    ] {
+        let (status, body) = send(&app, plugin_req(method.clone(), path)).await;
+        assert_eq!(status, StatusCode::FORBIDDEN, "{method} {path}");
+        assert!(body["error"].as_str().unwrap().contains("plugin token"));
+    }
+
+    // A wrong token never reaches the lane.
+    let wrong = axum::http::Request::get("/api/v1/status")
+        .header("authorization", "Bearer plugin-wrong")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, wrong).await.0, StatusCode::UNAUTHORIZED);
+
+    // Loopback-only, exactly like the admin token: a LAN peer is refused before token compare.
+    let mut lan = plugin_req(Method::GET, "/api/v1/status");
+    lan.extensions_mut()
+        .insert(PeerAddr("192.168.1.50:40000".parse().unwrap()));
+    assert_eq!(send(&app, lan).await.0, StatusCode::UNAUTHORIZED);
+}
+
 #[tokio::test]
 async fn host_info_reports_identity_and_ports() {
     let app = test_app(test_state(), None);
@@ -544,6 +674,7 @@ async fn blank_token_rejected() {
     let opts = Options {
         bind: "127.0.0.1:0".parse().unwrap(),
         token: Some("   ".into()),
+        plugin_token: None,
     };
     let err = run(test_state(), opts, None, test_stats(), false)
         .await

crates/punktfunk-host/src/mgmt_token.rs

@@ -1,12 +1,19 @@
 //! Management-API bearer token resolution.
 //!
 //! The mgmt API always serves HTTPS (the host's identity cert) and now always requires auth — even
-//! on a loopback bind. This module guarantees a token always exists: an explicit
+//! on a loopback bind. This module guarantees the tokens always exist: an explicit env var wins
-//! `PUNKTFUNK_MGMT_TOKEN` env wins (operator override, not persisted); otherwise the persisted
+//! (operator override, not persisted); otherwise the persisted file under the config dir is used;
-//! `~/.config/punktfunk/mgmt-token` is used; otherwise a fresh 32-byte hex token is generated and
+//! otherwise a fresh 32-byte hex token is generated and persisted. Files are written in
-//! persisted. The file is written in `PUNKTFUNK_MGMT_TOKEN=<hex>` form (0600) so the bundled web
+//! `KEY=<hex>` form (0600) so the bundled web console can source them directly as a systemd
-//! console can source it directly as a systemd `EnvironmentFile` — a single source of truth shared
+//! `EnvironmentFile` — a single source of truth shared between the host and its consumers.
-//! between the host and the console with no copying.
+//!
+//! Two tokens, two authorities:
+//! - **`mgmt-token`** (`PUNKTFUNK_MGMT_TOKEN`) — the operator/console token; authorizes the full
+//!   admin surface.
+//! - **`plugin-token`** (`PUNKTFUNK_PLUGIN_TOKEN`) — the scripting runner's capability-limited
+//!   credential (`mgmt::auth::plugin_may_access`): everything a plugin legitimately needs, but not
+//!   hook registration or pairing administration. The SDK's `connect()` prefers this file, so a
+//!   defect in an operator plugin can't rewrite `hooks.json` or admit new devices.
 
 use anyhow::{Context, Result};
 use rand::RngCore;
@@ -15,19 +22,32 @@ use std::path::Path;
 
 const ENV_VAR: &str = "PUNKTFUNK_MGMT_TOKEN";
 const FILE: &str = "mgmt-token";
+const PLUGIN_ENV_VAR: &str = "PUNKTFUNK_PLUGIN_TOKEN";
+const PLUGIN_FILE: &str = "plugin-token";
 
-/// Resolve the mgmt token (env > persisted file > generate+persist). Hex (not base64) so the
+/// Resolve the mgmt (full-admin) token (env > persisted file > generate+persist). Hex (not base64)
-/// persisted `KEY=VALUE` line is safe to source from a shell / systemd `EnvironmentFile`.
+/// so the persisted `KEY=VALUE` line is safe to source from a shell / systemd `EnvironmentFile`.
 pub fn load_or_generate() -> Result<String> {
-    if let Ok(v) = std::env::var(ENV_VAR) {
+    load_or_generate_impl(ENV_VAR, FILE)
+}
+
+/// Resolve the scripting runner's scoped plugin token, same precedence as [`load_or_generate`].
+/// Persisted to `plugin-token` next to `mgmt-token`; on Windows `plugins enable` grants the
+/// runner's LocalService principal read on exactly this file (and `cert.pem`) — never `mgmt-token`.
+pub fn load_or_generate_plugin() -> Result<String> {
+    load_or_generate_impl(PLUGIN_ENV_VAR, PLUGIN_FILE)
+}
+
+fn load_or_generate_impl(env_var: &str, file: &str) -> Result<String> {
+    if let Ok(v) = std::env::var(env_var) {
         let v = v.trim();
         if !v.is_empty() {
             return Ok(v.to_string());
         }
     }
-    let path = pf_paths::config_dir().join(FILE);
+    let path = pf_paths::config_dir().join(file);
     if let Ok(contents) = fs::read_to_string(&path) {
-        if let Some(tok) = parse_token(&contents) {
+        if let Some(tok) = parse_token(&contents, env_var) {
             return Ok(tok);
         }
     }
@@ -37,29 +57,29 @@ pub fn load_or_generate() -> Result<String> {
     let dir = pf_paths::config_dir();
     // Owner-private dir (0700 Unix / DACL-locked Windows) so the token can't leak via the config path.
     pf_paths::create_private_dir(&dir).with_context(|| format!("create {}", dir.display()))?;
-    write_token(&path, &token)?;
+    write_token(&path, env_var, &token)?;
-    tracing::info!(path = %path.display(), "generated and persisted management API token (owner-only)");
+    tracing::info!(path = %path.display(), "generated and persisted API token (owner-only)");
     Ok(token)
 }
 
 /// Parse the token from the persisted file: accept either a bare token line or a
-/// `PUNKTFUNK_MGMT_TOKEN=<token>` line (the form we write, also valid as an EnvironmentFile).
+/// `<KEY>=<token>` line (the form we write, also valid as an EnvironmentFile).
-fn parse_token(contents: &str) -> Option<String> {
+fn parse_token(contents: &str, env_var: &str) -> Option<String> {
     let line = contents.lines().find(|l| !l.trim().is_empty())?.trim();
     let tok = line
-        .strip_prefix("PUNKTFUNK_MGMT_TOKEN=")
+        .strip_prefix(env_var)
+        .and_then(|rest| rest.strip_prefix('='))
         .unwrap_or(line)
         .trim();
     (!tok.is_empty()).then(|| tok.to_string())
 }
 
-/// Write `PUNKTFUNK_MGMT_TOKEN=<token>` to `path` as an owner-only secret — 0600 on Unix AND
+/// Write `<KEY>=<token>` to `path` as an owner-only secret — 0600 on Unix AND DACL-locked to
-/// DACL-locked to SYSTEM/Administrators on Windows. Routes through the shared `write_secret_file` so
+/// SYSTEM/Administrators on Windows. Routes through the shared `write_secret_file` so both bearer
-/// the mgmt bearer token (full admin authority) gets the SAME Windows lockdown as the host key; the
+/// tokens get the SAME Windows lockdown as the host key; the bespoke `cfg(unix)`-only writer used
-/// bespoke `cfg(unix)`-only writer used to leave it readable by any local user (security-review
+/// to leave the mgmt token readable by any local user (security-review 2026-06-28 #2).
-/// 2026-06-28 #2).
+fn write_token(path: &Path, env_var: &str, token: &str) -> Result<()> {
-fn write_token(path: &Path, token: &str) -> Result<()> {
+    let line = format!("{env_var}={token}\n");
-    let line = format!("PUNKTFUNK_MGMT_TOKEN={token}\n");
     pf_paths::write_secret_file(path, line.as_bytes())
         .with_context(|| format!("write {}", path.display()))
 }
@@ -70,13 +90,17 @@ mod tests {
 
     #[test]
     fn parses_bare_and_keyvalue_forms() {
-        assert_eq!(parse_token("abc123\n").as_deref(), Some("abc123"));
+        assert_eq!(parse_token("abc123\n", ENV_VAR).as_deref(), Some("abc123"));
         assert_eq!(
-            parse_token("PUNKTFUNK_MGMT_TOKEN=deadbeef\n").as_deref(),
+            parse_token("PUNKTFUNK_MGMT_TOKEN=deadbeef\n", ENV_VAR).as_deref(),
             Some("deadbeef")
         );
-        assert_eq!(parse_token("\n  \n"), None);
+        assert_eq!(
-        assert_eq!(parse_token("PUNKTFUNK_MGMT_TOKEN=\n"), None);
+            parse_token("PUNKTFUNK_PLUGIN_TOKEN=deadbeef\n", PLUGIN_ENV_VAR).as_deref(),
+            Some("deadbeef")
+        );
+        assert_eq!(parse_token("\n  \n", ENV_VAR), None);
+        assert_eq!(parse_token("PUNKTFUNK_MGMT_TOKEN=\n", ENV_VAR), None);
     }
 
     #[test]
@@ -84,9 +108,9 @@ mod tests {
         let dir = std::env::temp_dir().join(format!("pf-mgmt-token-test-{}", std::process::id()));
         let _ = fs::create_dir_all(&dir);
         let path = dir.join(FILE);
-        write_token(&path, "cafef00d").unwrap();
+        write_token(&path, ENV_VAR, "cafef00d").unwrap();
         let read = fs::read_to_string(&path).unwrap();
-        assert_eq!(parse_token(&read).as_deref(), Some("cafef00d"));
+        assert_eq!(parse_token(&read, ENV_VAR).as_deref(), Some("cafef00d"));
         #[cfg(unix)]
         {
             use std::os::unix::fs::PermissionsExt;

crates/punktfunk-host/src/native.rs

@@ -1265,6 +1265,10 @@ async fn serve_session(
                 UdpTransport::from_socket_punch(
                     data_sock,
                     &client_udp.to_string(),
+                    // Only honour a punch from the peer QUIC already authenticated: the punch is
+                    // there to discover the NAT-remapped *port*, and `client_udp`'s IP is the
+                    // host-observed QUIC remote (only its port is client-reported).
+                    client_udp.ip(),
                     std::time::Duration::from_millis(2500),
                 )
             };

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

@@ -16,7 +16,7 @@ use punktfunk_core::quic::{ClipControl, ClipOffer, ClipState};
 #[allow(clippy::too_many_arguments)]
 pub(super) async fn run(
     mut ctrl_send: quinn::SendStream,
-    mut ctrl_recv: quinn::RecvStream,
+    ctrl_recv: quinn::RecvStream,
     initial_mode: punktfunk_core::Mode,
     codec: crate::encode::Codec,
     live_reconfig_ok: bool,
@@ -47,9 +47,13 @@ pub(super) async fn run(
     // coalesces a well-behaved resize drag; compliant clients self-limit to ≥ 1 s).
     const MIN_SWITCH_INTERVAL: std::time::Duration = std::time::Duration::from_millis(500);
     let mut last_accepted_switch: Option<std::time::Instant> = None;
+    // Resumable framing: this read is one arm of a `select!` whose siblings fire on every probe
+    // result / reconfigure / clip offer, so the read future is dropped routinely. `io::read_msg`
+    // would lose the partial frame and misalign the stream for the rest of the session.
+    let mut ctrl_reader = io::MsgReader::new(ctrl_recv);
     loop {
         tokio::select! {
-            msg = io::read_msg(&mut ctrl_recv) => {
+            msg = ctrl_reader.read_msg() => {
                 let Ok(msg) = msg else { break }; // stream closed
                 if let Ok(req) = Reconfigure::decode(&msg) {
                     let now = std::time::Instant::now();

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

@@ -1207,6 +1207,9 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
     let mut cur_depth: usize = 1;
     let mut behind_score: u32 = 0;
     let mut depth_frames: u64 = 0;
+    // Second escalation stage (§7 LN3): once depth is maxed (or was never available — Linux),
+    // ask the encoder for pipelined retrieve exactly once. Latched whether it accepts or not.
+    let mut pipeline_asked = false;
     // ~20 net behind-frames (≈0.3 s sustained) escalates; a lone hitch decays away. Warmup skips
     // the first ~1 s so bring-up (display acquire, encoder open) never triggers it.
     const DEPTH_ESCALATE: u32 = 20;
@@ -1477,6 +1480,9 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                         if let Some(c) = plan.wire_chunk {
                             new_enc.set_wire_chunking(c);
                         }
+                        // (`max_depth` is computed later in the iteration — read the capturer
+                        // directly so an ABR rebuild re-establishes the bound immediately.)
+                        new_enc.set_input_ring_depth(capturer.pipeline_depth().max(1));
                         enc = new_enc;
                         bitrate_kbps = new_kbps;
                         live_bitrate.store(new_kbps, Ordering::Relaxed);
@@ -2053,10 +2059,15 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
         // Adaptive-depth escalate signal (measured BEFORE the trailing sleep): "behind" = the
         // frame's work overran its cadence deadline `next`, so the trailing sleep would be
         // zero/negative. At depth-1 that means the synchronous poll (encode + WDDM wait) can't
-        // fit a frame interval — the contention case pipelining is for — so escalate to the
+        // fit a frame interval — the contention case pipelining is for — so escalate, and hold
-        // capturer's max and hold there. Leaky bucket + warmup skip reject one-off hitches and
+        // there. Leaky bucket + warmup skip reject one-off hitches and bring-up; no
-        // bring-up. Once escalated, `cur_depth` stays (no de-escalation in v1).
+        // de-escalation in v1. Two stages: first the CAPTURER's max depth (Windows IDD depth-2
-        if idd_adaptive_enabled() && cur_depth < max_depth {
+        // overlap); where depth can't grow (Linux portal is permanently depth-1, §7 LN3), the
+        // ENCODER's pipelined retrieve is the same trade on the other side of submit — the
+        // two-thread lock moves the encode wait off this loop so capture/submit keep cadence,
+        // at ~one tick of AU latency. `enc.set_pipelined` may decline (unsupported backend or
+        // an explicit PUNKTFUNK_NVENC_ASYNC=0); either way it is asked exactly once.
+        if idd_adaptive_enabled() && (cur_depth < max_depth || !pipeline_asked) {
             depth_frames += 1;
             if depth_frames > DEPTH_WARMUP_FRAMES {
                 let behind = std::time::Instant::now() >= next;
@@ -2066,6 +2077,7 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                     behind_score.saturating_sub(1)
                 };
                 if behind_score >= DEPTH_ESCALATE {
+                    if cur_depth < max_depth {
                         cur_depth = max_depth;
                         tracing::info!(
                             depth = cur_depth,
@@ -2073,6 +2085,19 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                              (GPU contention); pipelining for the rest of the session (latency \
                              trade for throughput)"
                         );
+                    } else {
+                        pipeline_asked = true;
+                        if enc.set_pipelined(true) {
+                            tracing::info!(
+                                "encoder pipelined retrieve escalated — encode can't hold \
+                                 cadence and the capturer has no depth to give; the encode wait \
+                                 moves off the loop for the rest of the session (latency trade \
+                                 for throughput)"
+                            );
+                        }
+                    }
+                    // Give the action time to take effect before judging again.
+                    behind_score = 0;
                 }
             }
         }
@@ -2265,6 +2290,9 @@ fn try_inplace_resize(
     if let Some(c) = plan.wire_chunk {
         new_enc.set_wire_chunking(c);
     }
+    // Re-report the capturer's ring depth: in-place backends bound async pipelining by it, and a
+    // rebuilt encoder starts with it unset.
+    new_enc.set_input_ring_depth(capturer.pipeline_depth().max(1));
     *enc = new_enc;
     *frame = new_frame;
     *interval = std::time::Duration::from_secs_f64(1.0 / effective_hz.max(1) as f64);
@@ -2579,6 +2607,10 @@ fn build_pipeline(
     if let Some(c) = plan.wire_chunk {
         enc.set_wire_chunking(c);
     }
+    // Tell in-place backends (Windows direct-NVENC) how deep they may pipeline against the
+    // capturer's texture ring — without it they use only the env/pool cap and can encode a texture
+    // the capturer has already rotated and overwritten.
+    enc.set_input_ring_depth(capturer.pipeline_depth().max(1));
     // Post-open cross-check: the Welcome already committed `chroma_format` from the pre-open probe, so
     // warn loudly if the encoder actually opened a different chroma than negotiated (the in-band SPS is
     // authoritative for the decoder, but a mismatch means the probe and the live open disagreed).

crates/punktfunk-host/src/plugins.rs

@@ -14,9 +14,16 @@
 //!   package present.
 //!
 //! Windows needs elevation for both halves: the plugins dir lives under the ACL'd
-//! `%ProgramData%\punktfunk` (see `pf_paths::create_private_dir`) and the task runs as SYSTEM. We
+//! `%ProgramData%\punktfunk` (see `pf_paths::create_private_dir`) and the task is admin-owned. We
 //! check up front and print one actionable line instead of letting `bun add` fail with a bare
 //! EACCES.
+//!
+//! The task itself runs as **`NT AUTHORITY\LocalService`**, not SYSTEM: plugins are
+//! operator-installed code, and a plugin defect must cost a throwaway service account, not the
+//! most privileged principal on the box. `enable` converges the principal (migrating tasks an
+//! older installer registered as SYSTEM) and grants LocalService read on exactly the two files
+//! the runner's `connect()` needs — the scoped `plugin-token` and the TLS pin `cert.pem` — never
+//! the full-admin `mgmt-token`.
 
 use anyhow::{bail, Context, Result};
 use std::process::Command;
@@ -71,13 +78,15 @@ USAGE:
 
 NAMES:
     A bare first-party name resolves into the @punktfunk scope: `playnite` installs
-    @punktfunk/plugin-playnite, `rom-manager` installs @punktfunk/plugin-rom-manager.
+    @punktfunk/plugin-playnite, `rom-manager` installs @punktfunk/plugin-rom-manager —
-    A scoped (@scope/pkg) or `punktfunk-plugin-*` name is used verbatim.
+    always from Punktfunk's own package registry. Any other name (`punktfunk-plugin-*`,
+    a foreign @scope) installs from the PUBLIC npm registry and is refused unless you
+    pass --allow-public-registry.
 
 NOTES:
     Plugins run under the runner, which is OPT-IN — `plugins add` installs, `plugins enable`
-    turns the runner on. Plugins are operator-installed code that runs as the host user;
+    turns the runner on. Plugins are operator-installed code that runs with operator
-    install only plugins you trust.
+    privileges; install only plugins you trust.
 "
     );
     #[cfg(target_os = "windows")]
@@ -212,13 +221,66 @@ fn systemctl_output(args: &[&str]) -> Option<String> {
     }
 }
 
+/// `NT AUTHORITY\LocalService` — the runner task's principal — in icacls SID form.
+#[cfg(target_os = "windows")]
+const LOCAL_SERVICE_SID: &str = "*S-1-5-19";
+
+/// The two (and only two) secrets the runner needs to read to reach the mgmt API: the scoped
+/// plugin token and the host identity cert it pins TLS against. `mgmt-token` (full admin) is
+/// deliberately NOT here.
+#[cfg(target_os = "windows")]
+const RUNNER_SECRET_FILES: [&str; 2] = ["plugin-token", "cert.pem"];
+
+/// The unit directories the runner imports code from. LocalService gets an inheritable
+/// read+execute+write-attributes grant on these: bun's module loader opens unit files
+/// requesting FILE_WRITE_ATTRIBUTES on top of read (plain `(RX)` makes every import die with
+/// EPERM — found on-glass), and WA can only touch timestamps/readonly bits, never content —
+/// the runner's own integrity check (`windowsSddlUnsafeReason`) treats it as harmless.
+#[cfg(target_os = "windows")]
+const RUNNER_UNIT_DIRS: [&str; 2] = ["plugins", "scripts"];
+
+/// The runner's writable state root: `<config_dir>\plugin-state`. A plugin persists its config +
+/// cache under `plugin-state\<name>` (`@punktfunk/host`'s `pluginStateDir`), so LocalService needs
+/// real **Modify** here — unlike the code dirs (RX,WA) and the secrets (R). This keeps the
+/// three-way split crisp: code is read-only (a plugin can't rewrite itself), secrets are
+/// read-only, only this one dir is writable. Inheritable so per-plugin subdirs the runner creates
+/// carry the grant. Users stay read-only (config-dir default), so another non-admin still can't
+/// tamper with a plugin's launch templates.
+#[cfg(target_os = "windows")]
+const RUNNER_STATE_DIRS: [&str; 1] = ["plugin-state"];
+
+/// The plugin **ingest** inbox: `<config_dir>\ingest`. The INVERSE grant of `plugin-state` —
+/// `BUILTIN\Users` gets **Modify**, so an app running as the interactive user (e.g. the Playnite
+/// exporter, a Playnite extension) can drop data (`ingest\<plugin>\…`) that the de-privileged
+/// LocalService runner then READS (LocalService is a member of Users, so it inherits read here).
+/// This is the one place a plugin can receive data produced by *another* account — the runner can
+/// no longer traverse the interactive user's profile the way the old SYSTEM runner could. Scoped
+/// to this one inbox: the rest of the config tree stays Users-read-only, so the widening is a
+/// well-defined drop box, not a general write hole. (Accepted tradeoff: any local user can drop a
+/// file here — trusted-single-user model, and the runner it feeds is only LocalService.)
+#[cfg(target_os = "windows")]
+const RUNNER_INGEST_DIRS: [&str; 1] = ["ingest"];
+
+/// `BUILTIN\Users` (S-1-5-32-545) in icacls SID form — the ingest inbox's writer.
+#[cfg(target_os = "windows")]
+const USERS_SID: &str = "*S-1-5-32-545";
+
 #[cfg(target_os = "windows")]
 fn enable() -> Result<()> {
+    // Converge the task principal BEFORE starting it: the installer registers it as LocalService,
+    // but a task from an older install (or a hand-registered dev box) still runs as SYSTEM, and
+    // enabling that unmigrated would hand operator plugins the highest privilege on the box.
+    // Idempotent; -LogonType ServiceAccount needs no stored password.
+    powershell(&format!(
+        "$p = New-ScheduledTaskPrincipal -UserId 'LocalService' -LogonType ServiceAccount; \
+         Set-ScheduledTask -TaskName {TASK} -Principal $p -ErrorAction Stop | Out-Null"
+    ))?;
+    grant_runner_secret_reads();
     powershell(&format!(
         "Enable-ScheduledTask -TaskName {TASK} -ErrorAction Stop | Out-Null; \
          Start-ScheduledTask -TaskName {TASK} -ErrorAction Stop"
     ))?;
-    println!("Plugin runner enabled and started ({TASK}).");
+    println!("Plugin runner enabled and started ({TASK}, runs as LocalService).");
     Ok(())
 }
 
@@ -228,17 +290,173 @@ fn disable() -> Result<()> {
         "Stop-ScheduledTask -TaskName {TASK} -ErrorAction SilentlyContinue; \
          Disable-ScheduledTask -TaskName {TASK} -ErrorAction Stop | Out-Null"
     ))?;
+    revoke_runner_secret_reads();
     println!("Plugin runner stopped and disabled ({TASK}).");
     Ok(())
 }
 
+/// Grant LocalService **read** on the runner's two secret files. Both are written by the host's
+/// `serve` with a SYSTEM/Administrators-only DACL (`pf_paths::write_secret_file`), which the
+/// de-privileged runner cannot read — this is the one, narrow widening it needs. `/grant:r`
+/// replaces only LocalService's ACE, leaving the lockdown otherwise intact. Files the host hasn't
+/// minted yet get an actionable note instead of a failed icacls: the grant re-runs on the next
+/// `plugins enable`. NOTE: the host re-locks a secret's DACL whenever it rewrites the file (e.g.
+/// a regenerated identity cert) — re-running `plugins enable` restores the grant.
+#[cfg(target_os = "windows")]
+fn grant_runner_secret_reads() {
+    let cfg = pf_paths::config_dir();
+    for name in RUNNER_SECRET_FILES {
+        let path = cfg.join(name);
+        if !path.exists() {
+            println!(
+                "note: {} does not exist yet (the host writes it on first serve). Start the \
+                 host once, then run `punktfunk-host plugins enable` again so the runner can \
+                 authenticate.",
+                path.display()
+            );
+            continue;
+        }
+        let ok = Command::new(icacls_path())
+            .arg(&path)
+            .args(["/grant:r", &format!("{LOCAL_SERVICE_SID}:(R)")])
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .is_ok_and(|s| s.success());
+        if !ok {
+            eprintln!(
+                "warning: could not grant LocalService read on {} - the plugin runner may fail \
+                 to authenticate to the management API",
+                path.display()
+            );
+        }
+    }
+    // The unit dirs: inheritable (RX,WA) so the runner can import what lives there (see
+    // RUNNER_UNIT_DIRS). Created here if absent — an elevated create inherits the config dir's
+    // protected DACL, and granting now means files the operator adds later are covered by
+    // inheritance rather than needing another `plugins enable`.
+    for name in RUNNER_UNIT_DIRS {
+        let dir = cfg.join(name);
+        if let Err(e) = std::fs::create_dir_all(&dir) {
+            eprintln!("warning: could not create {}: {e}", dir.display());
+            continue;
+        }
+        let ok = Command::new(icacls_path())
+            .arg(&dir)
+            .args(["/grant:r", &format!("{LOCAL_SERVICE_SID}:(OI)(CI)(RX,WA)")])
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .is_ok_and(|s| s.success());
+        if !ok {
+            eprintln!(
+                "warning: could not grant LocalService read on {} - the runner may fail to \
+                 import plugins/scripts from it",
+                dir.display()
+            );
+        }
+    }
+    // The state root: inheritable Modify so plugins can persist config/cache under
+    // `plugin-state\<name>` (see RUNNER_STATE_DIRS). This is the ONLY writable grant.
+    for name in RUNNER_STATE_DIRS {
+        let dir = cfg.join(name);
+        if let Err(e) = std::fs::create_dir_all(&dir) {
+            eprintln!("warning: could not create {}: {e}", dir.display());
+            continue;
+        }
+        let ok = Command::new(icacls_path())
+            .arg(&dir)
+            .args(["/grant:r", &format!("{LOCAL_SERVICE_SID}:(OI)(CI)(M)")])
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .is_ok_and(|s| s.success());
+        if !ok {
+            eprintln!(
+                "warning: could not grant LocalService write on {} - state-writing plugins \
+                 (config/cache) may fail to persist",
+                dir.display()
+            );
+        }
+    }
+    // The ingest inbox: inheritable Modify for BUILTIN\Users, so an interactive-user app (the
+    // Playnite exporter) can drop `ingest\<plugin>\…` for the LocalService runner to read (see
+    // RUNNER_INGEST_DIRS). The one Users-writable carve-out in the otherwise Users-read-only tree.
+    for name in RUNNER_INGEST_DIRS {
+        let dir = cfg.join(name);
+        if let Err(e) = std::fs::create_dir_all(&dir) {
+            eprintln!("warning: could not create {}: {e}", dir.display());
+            continue;
+        }
+        let ok = Command::new(icacls_path())
+            .arg(&dir)
+            .args(["/grant:r", &format!("{USERS_SID}:(OI)(CI)(M)")])
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .is_ok_and(|s| s.success());
+        if !ok {
+            eprintln!(
+                "warning: could not open the ingest inbox {} for writes - a plugin fed by an \
+                 interactive-user app (e.g. playnite) may see no data",
+                dir.display()
+            );
+        }
+    }
+}
+
+/// Best-effort removal of the LocalService read grants when the runner is switched off — the
+/// mirror of [`grant_runner_secret_reads`]; `enable` re-grants.
+#[cfg(target_os = "windows")]
+fn revoke_runner_secret_reads() {
+    let cfg = pf_paths::config_dir();
+    for name in RUNNER_SECRET_FILES
+        .iter()
+        .chain(RUNNER_UNIT_DIRS.iter())
+        .chain(RUNNER_STATE_DIRS.iter())
+    {
+        let path = cfg.join(name);
+        if !path.exists() {
+            continue;
+        }
+        let _ = Command::new(icacls_path())
+            .arg(&path)
+            .args(["/remove:g", LOCAL_SERVICE_SID])
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status();
+    }
+    // The ingest inbox was opened to Users, not LocalService — remove that explicit grant (the
+    // inherited Users:RX from the config dir remains, so it reverts to read-only, not orphaned).
+    for name in RUNNER_INGEST_DIRS {
+        let path = cfg.join(name);
+        if !path.exists() {
+            continue;
+        }
+        let _ = Command::new(icacls_path())
+            .arg(&path)
+            .args(["/remove:g", USERS_SID])
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status();
+    }
+}
+
+/// Resolve icacls by full System32 path rather than PATH — same planted-binary reasoning as
+/// [`powershell_path`]; matches `pf_paths`.
+#[cfg(target_os = "windows")]
+fn icacls_path() -> String {
+    std::env::var("SystemRoot")
+        .map(|r| format!(r"{r}\System32\icacls.exe"))
+        .unwrap_or_else(|_| "icacls".to_string())
+}
+
 #[cfg(target_os = "windows")]
 fn status() -> Result<()> {
     let out = powershell_output(&format!(
         "$t = Get-ScheduledTask -TaskName {TASK} -ErrorAction SilentlyContinue; \
          if ($null -eq $t) {{ 'missing' }} else {{ \
-           $i = Get-ScheduledTaskInfo -TaskName {TASK} -ErrorAction SilentlyContinue; \
+           \"$($t.State)|$($t.Principal.UserId)\" }}"
-           \"$($t.State)\" }}"
     ));
     match out.as_deref().map(str::trim) {
         Some("missing") | None => {
@@ -248,7 +466,10 @@ fn status() -> Result<()> {
             );
         }
         Some(state) => {
-            println!("runner:  {TASK}\nstate:   {state}");
+            // "State|Principal" — the principal line makes the SYSTEM→LocalService migration
+            // verifiable at a glance (`plugins enable` converges a legacy SYSTEM task).
+            let (state, principal) = state.split_once('|').unwrap_or((state, "?"));
+            println!("runner:  {TASK}\nstate:   {state}\nruns as: {principal}");
             if state.eq_ignore_ascii_case("Disabled") {
                 println!("\nEnable it with: punktfunk-host plugins enable");
             }

docs-site/content/docs/automation.md

@@ -157,6 +157,13 @@ The canonical "decide, don't just observe" pattern — approve pairing from your
 `POST /api/v1/native/pending/{id}/approve` when you tap yes. The full API is documented at
 [`/api/docs`](/api) on your host.
 
+> A unit under the runner auto-connects with the host's **scoped plugin token**, which covers
+> the everyday surface (status, library, sessions, events) but deliberately not **hook
+> registration** or **pairing administration** — so a plugin defect can't admit new devices or
+> install commands. A script that should administer pairing (like the approval pattern above)
+> opts into the full-admin credential explicitly: set `PUNKTFUNK_MGMT_TOKEN` on the unit (e.g.
+> a `systemctl --user edit punktfunk-scripting` drop-in) or pass `{ token }` to `connect()`.
+
 ## Recipe: full controller passthrough (VirtualHere)
 
 To get a controller's *native* features on the host — DualSense gyro, touchpad, adaptive

docs-site/content/docs/plugins.mdx

@@ -31,8 +31,9 @@ punktfunk-host plugins enable           # turn the runner on (once)
 <Tab value="Windows">
 
 Run these from an **elevated** PowerShell — right-click **PowerShell** → **Run as administrator**.
-The plugins directory lives under `%ProgramData%\punktfunk`, which is admin-owned, and the runner
+The plugins directory lives under `%ProgramData%\punktfunk`, which is admin-owned. The runner task
-task runs as SYSTEM.
+itself runs as the low-privilege `NT AUTHORITY\LocalService` account — `plugins enable` sets that
+up (including read access to the runner's scoped API token).
 
 ```powershell
 punktfunk-host plugins add playnite     # or: rom-manager
@@ -62,11 +63,13 @@ The runner is **opt-in**: `plugins add` installs, `plugins enable` turns it on.
 | `punktfunk-host plugins disable` | Stop + disable the runner. |
 | `punktfunk-host plugins status` | Is the runner enabled and running? |
 
-A bare name resolves to the first-party package — `playnite` installs `@punktfunk/plugin-playnite`.
+A bare name resolves to the first-party package — `playnite` installs `@punktfunk/plugin-playnite`,
-A scoped (`@scope/pkg`) or `punktfunk-plugin-*` name is used verbatim, so third-party plugins work
+always from Punktfunk's own package registry. Any other name (`punktfunk-plugin-*`, a foreign
-the same way.
+`@scope/pkg`) would install from the **public npm registry** and is refused unless you add
+`--allow-public-registry` — a guard against typos and look-alike packages pulling untrusted code
+onto your host.
 
-> Plugins are operator-installed code that runs as the host user — they can launch games and run
+> Plugins are operator-installed code with operator privileges — they can launch games and run
 > commands. Install only plugins you trust, from a registry you control.
 
 ## ROM Manager

include/punktfunk_core.h

@@ -37,7 +37,15 @@
 // `punktfunk_connection_clipboard_{control,offer,fetch,serve,cancel}` +
 // `punktfunk_connection_next_clipboard`. Additive; the wire grows only backward-compatible control
 // messages (0x40-0x44) and a new `Welcome::host_caps` bit, so [`WIRE_VERSION`] is unchanged.
-#define ABI_VERSION 8
+// v9: `PunktfunkFrame` grew `received_ns` — the reassembly-completion receipt stamp, so
+// embedders stop stamping receipt at the hand-off pull (which folds the pre-decode queue wait
+// into apparent network latency). Struct-size change on the frame poll surface = a hard ABI
+// break for embedders reading `PunktfunkFrame`; nothing on the wire moved, so [`WIRE_VERSION`]
+// is unchanged.
+// v10: added `punktfunk_connection_clock_offset_now_ns` — the LIVE (mid-stream re-synced)
+// clock offset ongoing latency math must use; the connect-time getter stays frozen by
+// contract. Additive, client-local — no wire change, so [`WIRE_VERSION`] is unchanged.
+#define ABI_VERSION 10
 
 // The punktfunk/1 **wire** version — what `Hello`/`Welcome` carry and hosts equality-check.
 // Deliberately its own constant: [`ABI_VERSION`] tracks the embeddable **C surface**
@@ -105,8 +113,8 @@
 #define PUNKTFUNK_GAMEPAD_XBOX360 1
 
 // UHID DualSense (kernel `hid-playstation`): adaptive triggers, lightbar, touchpad, motion —
-// feedback arrives on the HID-output plane ([`punktfunk_connection_next_hidout`]). Honored
+// feedback arrives on the HID-output plane ([`punktfunk_connection_next_hidout`]). Honored on
-// only where available (Linux hosts); otherwise the host falls back to X-Box 360.
+// Linux (UHID) and Windows (UMDF minidriver) hosts; otherwise the host falls back to X-Box 360.
 #define PUNKTFUNK_GAMEPAD_DUALSENSE 2
 
 // uinput X-Box One / Series pad — the X-Box 360 backend with the One/Series USB identity, so
@@ -117,8 +125,8 @@
 
 // UHID DualShock 4 (kernel `hid-playstation` ≥ 6.2): lightbar, touchpad, motion, rumble — the
 // touchpad/motion arrive over the rich-input plane and lightbar over the HID-output plane, like
-// DualSense (minus adaptive triggers / player LEDs / mute). Honored only where available (Linux
+// DualSense (minus adaptive triggers / player LEDs / mute). Honored on Linux (UHID) and Windows
-// hosts); otherwise the host falls back to X-Box 360.
+// (UMDF minidriver) hosts; otherwise the host falls back to X-Box 360.
 #define PUNKTFUNK_GAMEPAD_DUALSHOCK4 4
 
 // UHID classic Steam Controller (Valve `28DE:1102`, kernel `hid-steam`): one stick + dual
@@ -131,11 +139,13 @@
 #define PUNKTFUNK_GAMEPAD_STEAMDECK 6
 
 // DualSense Edge (Sony `054C:0DF2`): the DualSense plus two back buttons + two Fn buttons, so a
-// client's back paddles land on native slots. Folds to `DUALSENSE` until its backend lands.
+// client's back paddles land on native slots. Honored on Linux (UHID `hid-playstation`) and
+// Windows (UMDF) hosts; otherwise the host falls back to X-Box 360.
 #define PUNKTFUNK_GAMEPAD_DUALSENSEEDGE 7
 
 // Nintendo Switch Pro Controller (Nintendo `057E:2009`, kernel `hid-nintendo`): Nintendo glyphs +
-// positional layout, gyro/accel, HD rumble. Folds to `XBOX360` until its backend lands.
+// positional layout, gyro/accel, HD rumble. Honored only where available (Linux hosts, UHID
+// `hid-nintendo`); otherwise the host falls back to X-Box 360.
 #define PUNKTFUNK_GAMEPAD_SWITCHPRO 8
 
 // New Steam Controller (2026, Valve `28DE:1302`) passed through AS-IS: the host mirrors the
@@ -1112,6 +1122,12 @@ typedef struct {
     uint32_t frame_index;
     uint64_t pts_ns;
     uint32_t flags;
+    // Wall-clock reassembly-completion instant (ns since the Unix epoch, CLOCK_REALTIME — the
+    // clock `pts_ns` and the skew handshake use). THIS is the receipt stamp for latency math:
+    // a stamp the embedder takes itself at the poll return additionally contains the
+    // pre-decode hand-off queue wait, so a client-side standing backlog would masquerade as
+    // network latency (ABI v9 — the 2026-07 two-pair standing-latency investigation).
+    uint64_t received_ns;
 } PunktfunkFrame;
 
 // A single input event. `#[repr(C)]` — shared verbatim with the C ABI as
@@ -2204,6 +2220,20 @@ PunktfunkStatus punktfunk_connection_clock_offset_ns(const PunktfunkConnection *
                                                      int64_t *offset_ns);
 #endif
 
+#if defined(PUNKTFUNK_FEATURE_QUIC)
+// The **live** host↔client wall-clock offset (nanoseconds, host minus client): the
+// connect-time estimate of [`punktfunk_connection_clock_offset_ns`], updated by every applied
+// mid-stream clock re-sync. Ongoing latency math (per-frame `received − pts` splits, the
+// glass-to-glass meter) must use this one — after a wall-clock step/slew the frozen
+// connect-time value reads tens of milliseconds wrong for the rest of the session, while the
+// core itself has already re-synced. Same clock contract as the connect-time getter.
+//
+// # Safety
+// `c` is a valid connection handle; `offset_ns` is writable (NULL is skipped).
+PunktfunkStatus punktfunk_connection_clock_offset_now_ns(const PunktfunkConnection *c,
+                                                         int64_t *offset_ns);
+#endif
+
 #if defined(PUNKTFUNK_FEATURE_QUIC)
 // Ask the host to switch the live session to `width`x`height`@`refresh_hz` without
 // reconnecting (window resized, refresh changed). Non-blocking enqueue: on acceptance the

packaging/nix/packages.nix

@@ -313,7 +313,7 @@ in
         dontFixup = true;
         outputHashMode = "recursive";
         outputHashAlgo = "sha256";
-        outputHash = "sha256-OA4NjwapsCV/z+0rftDCMAQJGWw63Mi/GARetmuy0QU="; # web/bun.lock deps (refresh on lockfile change; see README).
+        outputHash = "sha256-5oVZv65SMvq9i2REzHE8Pyn6qUZaV2FnPQdaouwcwoU="; # web/bun.lock deps (refresh on lockfile change; see README).
       };
     in
     stdenvNoCC.mkDerivation {
@@ -326,6 +326,14 @@ in
 
       # No cross-derivation dep cache: codegen + the vite build are fully offline (every input is in
       # the vendored node_modules, the checked-in api/openapi.json, and web/project.inlang).
+      #
+      # ⚠ "Offline" is load-bearing and NOT self-enforcing. inlang resolves the plugins in
+      # web/project.inlang/settings.json `modules`, and a failed import is only a WARNING there:
+      # paraglide then prints "Successfully compiled", exits 0, and emits ZERO messages, so the
+      # console builds fine and dies at SSR time with every `m.foo()` undefined. That is exactly
+      # what a CDN URL in `modules` did in this network-less sandbox. The plugin is now a normal
+      # devDependency referenced by path, and `bun run codegen` ends in tools/check-i18n.mjs, which
+      # fails the build on a remote module or a short message count. Keep both properties.
       buildPhase = ''
         runHook preBuild
         export HOME=$TMPDIR

packaging/windows/punktfunk-host.iss

@@ -291,13 +291,17 @@ Filename: "{app}\punktfunk-host.exe"; Parameters: "web setup {code:WebSetupParam
   StatusMsg: "Setting up the punktfunk web console..."; Flags: runhidden waituntilterminated
 #endif
 #ifdef WithScripting
-; Register the plugin/script runner's scheduled task (boot, SYSTEM, restart-on-failure) but leave it
+; Register the plugin/script runner's scheduled task (boot, restart-on-failure) but leave it
 ; DISABLED - the runner is OPT-IN (inert until you add scripts/plugins). Enable it when ready:
-;   Enable-ScheduledTask -TaskName PunktfunkScripting
+;   punktfunk-host plugins enable
+; Principal: NT AUTHORITY\LocalService, NOT SYSTEM - plugins are operator-installed code; a plugin
+; defect must cost a throwaway service account, not the box's highest privilege. `plugins enable`
+; grants LocalService read on the two secrets the runner needs (plugin-token, cert.pem) and
+; converges tasks an older installer registered as SYSTEM.
 ; Best-effort (-ErrorAction SilentlyContinue): a task hiccup never fails the whole install. No braces
 ; in the command, so no Inno {{ }} escaping needed.
 Filename: "powershell.exe"; \
-  Parameters: "-NoProfile -ExecutionPolicy Bypass -Command ""$a=New-ScheduledTaskAction -Execute '{app}\scripting\scripting-run.cmd'; $t=New-ScheduledTaskTrigger -AtStartup; $p=New-ScheduledTaskPrincipal -UserId 'SYSTEM' -LogonType ServiceAccount -RunLevel Highest; $s=New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries; Register-ScheduledTask -TaskName PunktfunkScripting -Action $a -Trigger $t -Principal $p -Settings $s -Force -ErrorAction SilentlyContinue | Out-Null; Disable-ScheduledTask -TaskName PunktfunkScripting -ErrorAction SilentlyContinue | Out-Null"""; \
+  Parameters: "-NoProfile -ExecutionPolicy Bypass -Command ""$a=New-ScheduledTaskAction -Execute '{app}\scripting\scripting-run.cmd'; $t=New-ScheduledTaskTrigger -AtStartup; $p=New-ScheduledTaskPrincipal -UserId 'LocalService' -LogonType ServiceAccount; $s=New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries; Register-ScheduledTask -TaskName PunktfunkScripting -Action $a -Trigger $t -Principal $p -Settings $s -Force -ErrorAction SilentlyContinue | Out-Null; Disable-ScheduledTask -TaskName PunktfunkScripting -ErrorAction SilentlyContinue | Out-Null"""; \
   StatusMsg: "Registering the punktfunk script runner (disabled; opt-in)..."; Flags: runhidden waituntilterminated
 #endif
 ; Launch the status tray as the SIGNED-IN user (not the elevated install user) right away, so the

plugin-kit/README.md

@@ -0,0 +1,60 @@
+# @punktfunk/plugin-kit
+
+The Effect-based framework punktfunk plugins are built on. It owns everything that is the
+same in every plugin — lifecycle, config/state, the sync engine, UI serving, the CLI
+scaffold, logging — so a plugin is just its domain logic, its HttpApi contract, and its UI.
+The reference consumer (and the blueprint to copy) is
+[`punktfunk-plugin-rom-manager`](https://git.unom.io/unom/punktfunk-plugin-rom-manager).
+
+Built on [`@punktfunk/host`](../sdk) (the SDK stays the low-level host client; the kit is
+the opinionated plugin layer on top). Effect `4.x` and the SDK are peer dependencies —
+the plugin's own copies are the only copies.
+
+## The one rule: async at the boundary, Effect inside
+
+The packaged runner bundles its own effect + SDK; a plugin's imports resolve to the
+plugin's node_modules. Effect values must therefore never cross the plugin boundary
+(`Context.Tag` identity is per-instance). `definePluginKit` enforces this by construction:
+you write Effect, it exports a plain async-`main` `PluginDef`, and a `ManagedRuntime`
+built from *your* effect instance runs everything. SIGINT/SIGTERM interrupt the plugin
+fiber (scoped finalizers run: UI deregistration, watcher close), bounded by
+`shutdownGraceMs`.
+
+```ts
+import { definePluginKit, serveUi } from "@punktfunk/plugin-kit";
+import { Effect, Layer } from "effect";
+
+export default definePluginKit({
+  name: "my-plugin",
+  version: "0.1.0",
+  layer: MyServices.layer, // over the kit base: HostClient | PluginInfo
+  main: Effect.gen(function* () {
+    const engine = yield* MySync;
+    yield* engine.start;
+    yield* serveUi({ title: "My Plugin", icon: "puzzle", staticDir, api: MyApiLive });
+    yield* Effect.never;
+  }),
+});
+```
+
+## Modules
+
+| Export | What it owns |
+| --- | --- |
+| `definePluginKit` / `runPluginKitDirect` | the async-main boundary + ManagedRuntime + signal handling |
+| `HostClient`, `PluginInfo` | the `pf` facade as services (`request` = the skew-safe untyped seam) |
+| `makeConfigService` | Schema-driven config: raw shape on disk, defaults ONLY in the Schema (`withDecodingDefaultKey` + `encodingStrategy: "omit"`), atomic writes, world-writable refusal, `changes` stream |
+| `makeCacheStore` | disposable derived state (corrupt/absent → empty, write-through) |
+| `ProviderClient` + wire schemas | typed library-provider reconcile over the untyped wire |
+| `makeSyncEngine` | poll + fs-watch + debounce + single-flight coalescing + fingerprint skip + status feed |
+| `serveUi` / `httpApiEnv` | an `effect/unstable/httpapi` HttpApi behind the SDK's `servePluginUi`, core-only layers |
+| `sseRoute` | the status SSE endpoint (httpapi has no event-stream media type) |
+| `runPluginCli` | `<bin> <command>` dispatcher reusing the plugin's layer graph (deliberately not `effect/unstable/cli` — that would drag platform packages into every plugin) |
+| `loggingLayer` | runner-journal line format |
+| `@punktfunk/plugin-kit/react` | browser glue: `createPluginRouter` (path→hash→fallback deep-link restore + `pf-ui:navigate`), `resolvePluginBase`, `useIsEmbedded`, `ResultGate`, `sseAtom` |
+| `@punktfunk/plugin-kit/theme.css` | the console's violet identity for plugin UIs (import first in your Tailwind entry) |
+
+## Publishing
+
+Tag `plugin-kit-vX.Y.Z` (matching `package.json`) — `.gitea/workflows/plugin-kit-publish.yml`
+typechecks, tests, builds, and publishes to the Gitea registry.

plugin-kit/bun.lock

@@ -0,0 +1,205 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@punktfunk/plugin-kit",
+      "devDependencies": {
+        "@punktfunk/host": "file:../sdk",
+        "@types/bun": "^1.3.0",
+        "@types/react": "^19.2.16",
+        "effect": "4.0.0-beta.99",
+        "typescript": "^5.9.3",
+      },
+      "peerDependencies": {
+        "@punktfunk/host": "^0.1.2",
+        "effect": "^4.0.0-beta.98",
+        "react": "^19.2.0",
+      },
+      "optionalPeers": [
+        "react",
+      ],
+    },
+  },
+  "packages": {
+    "@effect/openapi-generator": ["@effect/openapi-generator@4.0.0-beta.98", "", { "dependencies": { "swagger2openapi": "^7.0.8" }, "peerDependencies": { "@effect/platform-node": "^4.0.0-beta.98", "effect": "^4.0.0-beta.98" }, "bin": { "openapigen": "dist/bin.js" } }, "sha512-7bqawr/HqJWqQ8H/bHyzBlLPA3LIIm3Y+cGYlIxnC/QVK795QpiEXb7uxTnP7V7w49V0sBtTerv4/9ZjsMffLQ=="],
+
+    "@effect/platform-node": ["@effect/platform-node@4.0.0-beta.98", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.98", "mime": "^4.1.0", "undici": "^8.7.0" }, "peerDependencies": { "effect": "^4.0.0-beta.98", "ioredis": "^5.7.0" } }, "sha512-IQu1TiLXQEDSGkDBllyYjVadf+UqdjptryqX4mmktVTTbGDq7X4uVxe7cSgXuqZvyfG6kagTzwj2lfynxOaKQg=="],
+
+    "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.99", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.21.0" }, "peerDependencies": { "effect": "^4.0.0-beta.99" } }, "sha512-POBAowafsAAb3bH1x1rJlWnv32yMAazFgEuRW5LhkW/JJA5VGoEk9OnuoUkIH1OW6K/X6IrdNpqcO+5e9lPQJA=="],
+
+    "@exodus/schemasafe": ["@exodus/schemasafe@1.3.0", "", {}, "sha512-5Aap/GaRupgNx/feGBwLLTVv8OQFfv3pq2lPRzPg9R+IOBnDgghTGW7l7EuVXOvg5cc/xSAlRW8rBrjIC3Nvqw=="],
+
+    "@ioredis/commands": ["@ioredis/commands@1.10.0", "", {}, "sha512-UmeW7z4LfctwoQ5wkhVzgq8tXkreED2xZGpX+Bg+zA+WJFZCT6c062AfCK/Dfk81xZnnwdhJCUMkitihRaoC2Q=="],
+
+    "@msgpackr-extract/msgpackr-extract-darwin-arm64": ["@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-LCkGo6JDfaBhgST7UpPWgNgLINpcpabaHfyz5OBx75nUYxBsaEPxjnyNjWpeb/xBup/682QnBfRBy2/LvPutZQ=="],
+
+    "@msgpackr-extract/msgpackr-extract-darwin-x64": ["@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-zExlW9zUJKZH/tOtVMttwjKa4Xm/3KcNjnE3dPN92uCktwavMxpgCA3MoJK/DOnTWsQgo224OaST27/mPNAf+w=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm": ["@msgpackr-extract/msgpackr-extract-linux-arm@3.0.4", "", { "os": "linux", "cpu": "arm" }, "sha512-Tg3yX65f5GbtXLkrYEHE5oibZG9epyYWas7FogTTEJeDEF9JlXJzKgXaNhT3UXlTOeA+AfZpYZYZ0uPj7Cfquw=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm64": ["@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-dgX0P/9wGPJeHFBG+ZmhgE6bmtMt7NP5CRBGyyktpopdk/mW4POnrpQsSLtKI1dwpc+pPLuXHDh6vvskyQE/sw=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-x64": ["@msgpackr-extract/msgpackr-extract-linux-x64@3.0.4", "", { "os": "linux", "cpu": "x64" }, "sha512-8TNXMEjJc3QEy7R/x1INhgiU+XakDAFUzBhaz7+Rbrs8NH5UQeHQxxmzsSBJGyV6I1jW79undiQm8tOI+D+8FQ=="],
+
+    "@msgpackr-extract/msgpackr-extract-win32-x64": ["@msgpackr-extract/msgpackr-extract-win32-x64@3.0.4", "", { "os": "win32", "cpu": "x64" }, "sha512-CmCXPQrkbwExx3j946/PtHWHbYJiCRBRDl4BlkRQcJB/YOwQxJRTpoo7aTsortjgoJ1x7opzTSxn7C+ASSLVjQ=="],
+
+    "@punktfunk/host": ["@punktfunk/host@file:../sdk", { "devDependencies": { "@effect/openapi-generator": "4.0.0-beta.98", "@effect/platform-node": "4.0.0-beta.98", "@types/bun": "^1.3.0", "effect": "^4.0.0-beta.98", "typescript": "^5.9.3" }, "optionalDependencies": { "undici": "^7.0.0" }, "peerDependencies": { "effect": "^4.0.0-beta.98" }, "bin": { "punktfunk-scripting": "./dist/runner-cli.js" } }],
+
+    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@26.1.1", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-nxAkRSVkN1Y0JC1W8ky/fTfkGsMmcrRsbx+3XoZE+rMOX71kLYTV7fLXpqud1GpbpP5TuffXFqfX7fH2GgZREw=="],
+
+    "@types/react": ["@types/react@19.2.17", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw=="],
+
+    "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
+
+    "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
+    "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "call-me-maybe": ["call-me-maybe@1.0.2", "", {}, "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ=="],
+
+    "cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
+
+    "cluster-key-slot": ["cluster-key-slot@1.1.1", "", {}, "sha512-rwHwUfXL40Chm1r08yrhU3qpUvdVlgkKNeyeGPOxnW8/SyVDvgRaed/Uz54AqWNaTCAThlj6QAs3TZcKI0xDEw=="],
+
+    "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
+
+    "color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
+
+    "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" }, "peerDependencies": { "supports-color": "*" }, "optionalPeers": ["supports-color"] }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
+
+    "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
+
+    "effect": ["effect@4.0.0-beta.99", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.9.0", "find-my-way-ts": "^0.1.6", "ini": "^7.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^2.0.4", "multipasta": "^0.2.8", "toml": "^4.1.2", "uuid": "^14.0.1", "yaml": "^2.9.0" } }, "sha512-hP1C61uzINfLl/4kKMwcqksxd34s4sQ3VSjsWjhGrkx9CRlXaqnfOK9dpTEKynQ6rA7wU9rb3c+48eDYw7uzxA=="],
+
+    "emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
+
+    "es6-promise": ["es6-promise@3.3.1", "", {}, "sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg=="],
+
+    "escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
+
+    "fast-check": ["fast-check@4.9.0", "", { "dependencies": { "pure-rand": "^8.0.0" } }, "sha512-7ms6T7SybUev/PQITciI0yLM2pOSFy5zpG8Ty7tQofcVaQUvrMXp6CBwqF6fThLCLOrfBtuHAtwq6Yu4XPCllg=="],
+
+    "fast-safe-stringify": ["fast-safe-stringify@2.1.1", "", {}, "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA=="],
+
+    "find-my-way-ts": ["find-my-way-ts@0.1.6", "", {}, "sha512-a85L9ZoXtNAey3Y6Z+eBWW658kO/MwR7zIafkIUPUMf3isZG0NCs2pjW2wtjxAKuJPxMAsHUIP4ZPGv0o5gyTA=="],
+
+    "get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
+
+    "http2-client": ["http2-client@1.3.5", "", {}, "sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA=="],
+
+    "ini": ["ini@7.0.0", "", {}, "sha512-ifK0CgjALofS5bkrcTy4RaQ9Vx2Knf/eLeIO+NaswQEpH1UblrtTSCIvN71qQDMq0PeQ/SSPojvEJp9vvvfr+w=="],
+
+    "ioredis": ["ioredis@5.11.1", "", { "dependencies": { "@ioredis/commands": "1.10.0", "cluster-key-slot": "1.1.1", "debug": "4.4.3", "denque": "2.1.0", "redis-errors": "1.2.0", "redis-parser": "3.0.0", "standard-as-callback": "2.1.0" } }, "sha512-ehuGcf94bQXhfagULNXrJdfnWO38v070jxSx/qE87Kjzmu2fU7ro5EFAb+OPituLqgfyuQaym5DlrNydW2sJ9A=="],
+
+    "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
+
+    "kubernetes-types": ["kubernetes-types@1.30.0", "", {}, "sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q=="],
+
+    "mime": ["mime@4.1.0", "", { "bin": { "mime": "bin/cli.js" } }, "sha512-X5ju04+cAzsojXKes0B/S4tcYtFAJ6tTMuSPBEn9CPGlrWr8Fiw7qYeLT0XyH80HSoAoqWCaz+MWKh22P7G1cw=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "msgpackr": ["msgpackr@2.0.4", "", { "optionalDependencies": { "msgpackr-extract": "^3.0.4" } }, "sha512-o1C5KRmuRt+apqMr1HuGSqWStZoRBUpEsCsl15uM9VdAF1qHLtvMOU2En747EnTyEl6c4pzPewRMFF31s1CNbA=="],
+
+    "msgpackr-extract": ["msgpackr-extract@3.0.4", "", { "dependencies": { "node-gyp-build-optional-packages": "5.2.2" }, "optionalDependencies": { "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.4" }, "bin": { "download-msgpackr-prebuilds": "bin/download-prebuilds.js" } }, "sha512-4kmO/MdyUIkLIvTPr8VHLil4AtoKIoniWPIEk5+CDy0xnWC84azhSFmuJ7PxZdsYtiP5kEeQsORAVIeMgxT+Hw=="],
+
+    "multipasta": ["multipasta@0.2.8", "", {}, "sha512-ZPWuMKyv0cSO29f7hozp+k6+crZbQijV8ipMvxNxRf2SwtYGTX1ZX89Kd20VV4H9Znonx+EQn+iy1wGQsJ+b+Q=="],
+
+    "node-fetch": ["node-fetch@2.7.0", "", { "dependencies": { "whatwg-url": "^5.0.0" }, "peerDependencies": { "encoding": "^0.1.0" }, "optionalPeers": ["encoding"] }, "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A=="],
+
+    "node-fetch-h2": ["node-fetch-h2@2.3.0", "", { "dependencies": { "http2-client": "^1.2.5" } }, "sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg=="],
+
+    "node-gyp-build-optional-packages": ["node-gyp-build-optional-packages@5.2.2", "", { "dependencies": { "detect-libc": "^2.0.1" }, "bin": { "node-gyp-build-optional-packages": "bin.js", "node-gyp-build-optional-packages-optional": "optional.js", "node-gyp-build-optional-packages-test": "build-test.js" } }, "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw=="],
+
+    "node-readfiles": ["node-readfiles@0.2.0", "", { "dependencies": { "es6-promise": "^3.2.1" } }, "sha512-SU00ZarexNlE4Rjdm83vglt5Y9yiQ+XI1XpflWlb7q7UTN1JUItm69xMeiQCTxtTfnzt+83T8Cx+vI2ED++VDA=="],
+
+    "oas-kit-common": ["oas-kit-common@1.0.8", "", { "dependencies": { "fast-safe-stringify": "^2.0.7" } }, "sha512-pJTS2+T0oGIwgjGpw7sIRU8RQMcUoKCDWFLdBqKB2BNmGpbBMH2sdqAaOXUg8OzonZHU0L7vfJu1mJFEiYDWOQ=="],
+
+    "oas-linter": ["oas-linter@3.2.2", "", { "dependencies": { "@exodus/schemasafe": "^1.0.0-rc.2", "should": "^13.2.1", "yaml": "^1.10.0" } }, "sha512-KEGjPDVoU5K6swgo9hJVA/qYGlwfbFx+Kg2QB/kd7rzV5N8N5Mg6PlsoCMohVnQmo+pzJap/F610qTodKzecGQ=="],
+
+    "oas-resolver": ["oas-resolver@2.5.6", "", { "dependencies": { "node-fetch-h2": "^2.3.0", "oas-kit-common": "^1.0.8", "reftools": "^1.1.9", "yaml": "^1.10.0", "yargs": "^17.0.1" }, "bin": { "resolve": "resolve.js" } }, "sha512-Yx5PWQNZomfEhPPOphFbZKi9W93CocQj18NlD2Pa4GWZzdZpSJvYwoiuurRI7m3SpcChrnO08hkuQDL3FGsVFQ=="],
+
+    "oas-schema-walker": ["oas-schema-walker@1.1.5", "", {}, "sha512-2yucenq1a9YPmeNExoUa9Qwrt9RFkjqaMAA1X+U7sbb0AqBeTIdMHky9SQQ6iN94bO5NW0W4TRYXerG+BdAvAQ=="],
+
+    "oas-validator": ["oas-validator@5.0.8", "", { "dependencies": { "call-me-maybe": "^1.0.1", "oas-kit-common": "^1.0.8", "oas-linter": "^3.2.2", "oas-resolver": "^2.5.6", "oas-schema-walker": "^1.1.5", "reftools": "^1.1.9", "should": "^13.2.1", "yaml": "^1.10.0" } }, "sha512-cu20/HE5N5HKqVygs3dt94eYJfBi0TsZvPVXDhbXQHiEityDN+RROTleefoKRKKJ9dFAF2JBkDHgvWj0sjKGmw=="],
+
+    "pure-rand": ["pure-rand@8.4.2", "", {}, "sha512-vvuOGgcuPJAirlHvuQw1TrOiw7ptaIXXmIbNuiNOY6lNGJJH49PQ1Kj4nd783nPdQhQdicgOjVI2yI/9BD6/Ng=="],
+
+    "redis-errors": ["redis-errors@1.2.0", "", {}, "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w=="],
+
+    "redis-parser": ["redis-parser@3.0.0", "", { "dependencies": { "redis-errors": "^1.0.0" } }, "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A=="],
+
+    "reftools": ["reftools@1.1.9", "", {}, "sha512-OVede/NQE13xBQ+ob5CKd5KyeJYU2YInb1bmV4nRoOfquZPkAkxuOXicSe1PvqIuZZ4kD13sPKBbR7UFDmli6w=="],
+
+    "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
+
+    "should": ["should@13.2.3", "", { "dependencies": { "should-equal": "^2.0.0", "should-format": "^3.0.3", "should-type": "^1.4.0", "should-type-adaptors": "^1.0.1", "should-util": "^1.0.0" } }, "sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ=="],
+
+    "should-equal": ["should-equal@2.0.0", "", { "dependencies": { "should-type": "^1.4.0" } }, "sha512-ZP36TMrK9euEuWQYBig9W55WPC7uo37qzAEmbjHz4gfyuXrEUgF8cUvQVO+w+d3OMfPvSRQJ22lSm8MQJ43LTA=="],
+
+    "should-format": ["should-format@3.0.3", "", { "dependencies": { "should-type": "^1.3.0", "should-type-adaptors": "^1.0.1" } }, "sha512-hZ58adtulAk0gKtua7QxevgUaXTTXxIi8t41L3zo9AHvjXO1/7sdLECuHeIN2SRtYXpNkmhoUP2pdeWgricQ+Q=="],
+
+    "should-type": ["should-type@1.4.0", "", {}, "sha512-MdAsTu3n25yDbIe1NeN69G4n6mUnJGtSJHygX3+oN0ZbO3DTiATnf7XnYJdGT42JCXurTb1JI0qOBR65shvhPQ=="],
+
+    "should-type-adaptors": ["should-type-adaptors@1.1.0", "", { "dependencies": { "should-type": "^1.3.0", "should-util": "^1.0.0" } }, "sha512-JA4hdoLnN+kebEp2Vs8eBe9g7uy0zbRo+RMcU0EsNy+R+k049Ki+N5tT5Jagst2g7EAja+euFuoXFCa8vIklfA=="],
+
+    "should-util": ["should-util@1.0.1", "", {}, "sha512-oXF8tfxx5cDk8r2kYqlkUJzZpDBqVY/II2WhvU0n9Y3XYvAYRmeaf1PvvIvTgPnv4KJ+ES5M0PyDq5Jp+Ygy2g=="],
+
+    "standard-as-callback": ["standard-as-callback@2.1.0", "", {}, "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A=="],
+
+    "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
+
+    "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
+    "swagger2openapi": ["swagger2openapi@7.0.8", "", { "dependencies": { "call-me-maybe": "^1.0.1", "node-fetch": "^2.6.1", "node-fetch-h2": "^2.3.0", "node-readfiles": "^0.2.0", "oas-kit-common": "^1.0.8", "oas-resolver": "^2.5.6", "oas-schema-walker": "^1.1.5", "oas-validator": "^5.0.8", "reftools": "^1.1.9", "yaml": "^1.10.0", "yargs": "^17.0.1" }, "bin": { "swagger2openapi": "swagger2openapi.js", "oas-validate": "oas-validate.js", "boast": "boast.js" } }, "sha512-upi/0ZGkYgEcLeGieoz8gT74oWHA0E7JivX7aN9mAf+Tc7BQoRBvnIGHoPDw+f9TXTW4s6kGYCZJtauP6OYp7g=="],
+
+    "toml": ["toml@4.3.0", "", {}, "sha512-lVb8X9BsPVuH0M4BKeS91tXAmJvCjQ5UIyAbQFaxkKGyUFK2RPkhwaFSQH8vbpl1d23eu/IBH+dwVMHWaq9A5A=="],
+
+    "tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici": ["undici@7.28.0", "", {}, "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+
+    "uuid": ["uuid@14.0.1", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew=="],
+
+    "webidl-conversions": ["webidl-conversions@3.0.1", "", {}, "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="],
+
+    "whatwg-url": ["whatwg-url@5.0.0", "", { "dependencies": { "tr46": "~0.0.3", "webidl-conversions": "^3.0.0" } }, "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw=="],
+
+    "wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
+
+    "ws": ["ws@8.21.1", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-+0NTnW77fFN/DjQi6k/Sq/Yvk4Sgajw7urW8V+asjXnRgDs9gyGkdb7EzgfhA4goXsRIZKE28fzIXBHEzhuiWw=="],
+
+    "y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
+
+    "yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="],
+
+    "yargs": ["yargs@17.7.3", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g=="],
+
+    "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
+
+    "@effect/platform-node/undici": ["undici@8.8.0", "", {}, "sha512-ubshXMXwF3MQIMF1y/WxZdNBnjEKeSg2wF5mcGUtU55YTw34tnVVpKRlLf7ruDXZ5344KokPVX4RBx1wJm64Bw=="],
+
+    "oas-linter/yaml": ["yaml@1.10.3", "", {}, "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA=="],
+
+    "oas-resolver/yaml": ["yaml@1.10.3", "", {}, "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA=="],
+
+    "oas-validator/yaml": ["yaml@1.10.3", "", {}, "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA=="],
+
+    "swagger2openapi/yaml": ["yaml@1.10.3", "", {}, "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA=="],
+  }
+}