docs(changelog): the Windows host no longer blocks system sleep while idle

The mic pump's WASAPI backend rendered silence into the virtual mic's
render endpoint (typically the Steam Streaming Microphone) for the whole
host lifetime. A RUNNING stream makes the Windows audio stack hold a
kernel power request ("An audio stream is currently in use", visible in
powercfg /requests), so every idle Punktfunk host blocked system sleep
forever — field-reported 2026-08-12 ("doesn't go to sleep anymore since
installing punktfunk; powercfg shows the Steam Streaming Microphone").

Stop the render stream (IAudioClient::Stop — client stays initialized,
the mic endpoint keeps existing) after 10 s of silence-only output at an
unchanged queue length, and park the render thread on a condvar the
producer notifies on the empty->non-empty edge, so the next mic frame
resumes the stream within one device period — well under the jitter
buffer's prime depth, so nothing audible changes. Keying the idle window
on the queue LENGTH (not emptiness) also covers a sub-prime tail a
vanished client left behind, while any fresh burst moves the length and
resets the window instead of being dropped.

During a session the box stays awake through the session's own
DisplayWakeRequest (pf-frame), never through this silence.
PUNKTFUNK_MIC_ALWAYS_ON=1 restores the old always-running stream in case
a virtual audio driver misbehaves while its render side is paused.

.gitea/workflows/audit.yml

@@ -15,6 +15,17 @@
 #                   fails if any crate carries a license outside the allowlist — the regression
 #                   guard about.toml always promised. (The Android Gradle tree has no lockfile, so
 #                   nothing scans it — see the CRA roadmap.)
+#   * miri        → NON-BLOCKING interpretation of the few FFI-free leaf crates, one of them
+#                   cross-compiled to MSVC layout. Not a supply-chain scan; it lives here because
+#                   audit.yml already has exactly the shape it needs (weekly cron,
+#                   workflow_dispatch, the rust-ci container, the same cache pattern) and because
+#                   ci.yml runs on every push against a fleet where 37 of 46 jobs contend for
+#                   ubuntu-24.04. See the `miri:` job below for what it does and does not buy.
+#   * c-abi-asan  → NON-BLOCKING ASAN+LSAN run of the C ABI harness (tests/c/run.sh under
+#                   PF_SAN=address): both sides of the abi.rs boundary instrumented at once, and
+#                   the only automated check on its Box::into_raw/from_raw leak contract. Same
+#                   here-not-ci.yml reasoning as miri — plus -Zbuild-std defeats sccache, so it
+#                   must not ride the per-push leg.
 # Triggers: weekly (catch newly-disclosed CVEs in pinned deps), on every lockfile/allowlist
 # change, and on demand.
 # To silence a known-unfixable Rust advisory, add it to `.cargo/audit.toml` ([advisories] ignore=[…]).
@@ -44,6 +55,13 @@ on:
       - 'about.toml'
       - '.gitea/workflows/audit.yml'
   workflow_dispatch:
+# NOTE on the `paths:` list above and the `miri:` job: `crates/pf-driver-proto/**` is deliberately
+# NOT listed, even though that crate is what the Miri job exists to watch. `paths:` is a
+# WORKFLOW-level filter — adding it would fire all six jobs (three bun trees, pnpm, cargo-audit,
+# the license gate) on every driver-proto edit, onto a fleet where 37 of 46 jobs contend for
+# ubuntu-24.04, to run one 2-minute job. Weekly cron + workflow_dispatch is the day-one cadence;
+# revisit once the job has a green history, and if you do, prefer moving miri to its own workflow
+# file over widening this filter.
 
 jobs:
   cargo-audit:
@@ -177,3 +195,254 @@ jobs:
           command -v cargo-about >/dev/null 2>&1 || cargo install --locked cargo-about --version 0.9.1 --features cli
           cargo about generate about.hbs --fail -o /dev/null
           cargo about generate -m packaging/windows/drivers/Cargo.toml -c about.toml about.hbs --fail -o /dev/null
+
+  # ── Miri ─────────────────────────────────────────────────────────────────────────────────────
+  # WHAT THIS BUYS, precisely — one thing, and it is worth having:
+  #   It interprets `pf-driver-proto` CROSS-COMPILED TO `x86_64-pc-windows-msvc`, on a Linux
+  #   runner, with no Windows box anywhere in the loop. That crate is `#![forbid(unsafe_code)]`
+  #   and is path-dep'd by BOTH the main workspace and the driver workspace, so it is the layout
+  #   oracle for every frame and IOCTL crossing that boundary — and drift there is silent
+  #   corruption, not a compile error. Nothing else in CI checks it at MSVC layout.
+  #   On the first run ever performed against this repo it found a real defect: a layout test
+  #   reading an align-8 struct out of an align-1 stack buffer, which had passed on every machine
+  #   and every CI leg since it was written because a stack `[u8; 40]` usually lands 8-aligned.
+  #
+  # WHAT IT DOES NOT BUY — do not let anyone report this as unsafe coverage, and do not publish a
+  #   "Miri coverage" percentage; it would be noise. Miri can execute on the order of 2% of the
+  #   host's unsafe. It cannot run ash, windows-rs, ffmpeg, CUDA or the WDK, and in those crates
+  #   the unsafe *is* the foreign call, so there is nothing for an interpreter to execute. This
+  #   job is a targeted instrument for three leaf surfaces, not a safety net.
+  #
+  # NON-BLOCKING, deliberately, and via a step-level `||` — NOT job-level `continue-on-error`,
+  # which act_runner does not reliably honor (same reasoning as docs-site-audit above; a red job
+  # here would take the whole run red). Flip to blocking only after several weeks of green
+  # establish the nightly-drift rate.
+  #
+  # Do NOT add crates here because they merely compile under Miri. Add them because they contain
+  # pure-Rust unsafe or a layout contract worth interpreting. Explicitly excluded:
+  #   * pf-bitstream    — its compile did not finish in 27 min at 2.1 GB RSS, and it is
+  #                       `forbid(unsafe_code)`, so there is nothing to find. Do not re-add it.
+  #   * pf-update-check — ring; every FFI crate — dies on the first foreign call. Structural.
+  #   * punktfunk-core in bulk — `-- fec packet crypto` selects 63 tests and was killed at a
+  #                       25-minute cap with not one test reported complete. Only the narrow
+  #                       `fec::gf8` selection below is affordable, and it was timed before it
+  #                       was committed. Do not widen this filter without timing the result.
+  #
+  # MEASURED, not estimated — 192.168.1.25 (Ubuntu, 8 cores), on the DATED toolchain this job
+  # actually installs, with a COLD target dir and a COLD sysroot cache (so each step's figure
+  # includes building the Miri sysroot it needs) and a warm cargo registry. Every step below has
+  # been run start to finish; nothing here is extrapolated:
+  #   step A   21 + 12 + 4 pass    43 s
+  #   step B          21 pass      26 s
+  #   step C           2 pass      63 s
+  #   TOTAL 132 s cold. Interpretation itself is ~10 s of that; the rest is compiling, plus ~38 s
+  #   of one-time sysroot builds (21 s host + 17 s MSVC) that the cache below then carries.
+  #   Warm, the three steps are ~6 s / ~3 s / ~10 s. `timeout-minutes: 30` is therefore vast
+  #   headroom, kept deliberately so a first fully-uncached run — which additionally downloads a
+  #   ~400 MB toolchain and the registry — cannot trip it.
+  # If you add a step, MEASURE IT FIRST. The estimate this job replaced said "under 15 s across
+  # all four steps" and was extrapolated from a partial run; the real punktfunk-core figure was
+  # >25 min. Extrapolation is exactly how that happened.
+  miri:
+    runs-on: ubuntu-24.04
+    container:
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
+    timeout-minutes: 30
+    env:
+      # A DATED nightly, bumped deliberately — exactly like rust-toolchain.toml, and for the same
+      # reason. The cache keys below carry this value, so bumping it self-invalidates them.
+      # ⚠ `nightly-<date>` names the day rustup PUBLISHED the build, and that build is compiled
+      # from the PREVIOUS day's commit. This pin therefore resolves to
+      # `rustc 1.99.0-nightly (969b803cb 2026-08-09)` [verified by installing it], NOT the
+      # `12c36e253 2026-08-10` that the rust-safety programme doc's §7 table cites — that figure
+      # came from the ROLLING `nightly` channel and was mislabelled as the dated one. Harmless,
+      # but do not "fix" the date to chase that hash: all three steps below were re-run and are
+      # green on the dated toolchain this job actually installs.
+      MIRI_TOOLCHAIN: nightly-2026-08-10
+      # A GUARD, not a fix for a present problem: audit.yml sets no sccache — only ci.yml does, at
+      # workflow level (ci.yml:27). `cargo-miri` REPLACES rustc and cannot be wrapped; it prints
+      # "Ignoring `RUSTC_WRAPPER` environment variable, Miri does not support wrapping" and
+      # carries on [verified]. This keeps a future workflow-level sccache from becoming a puzzle.
+      RUSTC_WRAPPER: ""
+      # -Zmiri-disable-isolation: pf-gpu's tests mkdir, and Miri aborts them without it [verified].
+      # -Zmiri-symbolic-alignment-check: the whole point — it refuses to let an accidentally
+      #   favourable stack slot stand in for an alignment guarantee. This is the flag that caught
+      #   the pf-driver-proto defect.
+      # NOTE the absence of -Zmiri-ignore-leaks. Miri leak-checks by DEFAULT, and that is the one
+      #   leak-detection capability it offers here. None of the crates below leaks, so the job is
+      #   green. The tree does contain DELIBERATE leaks (pf-umdf-util/src/section.rs `ViewCell`,
+      #   gamepad_raii.rs leak-on-timeout) — when coverage ever reaches them, annotate those two
+      #   sites; do not blanket-disable the check.
+      MIRIFLAGS: -Zmiri-disable-isolation -Zmiri-symbolic-alignment-check
+    steps:
+      - uses: actions/checkout@v4
+
+      # Two caches, split on purpose so a Cargo.lock change does not re-download a ~400 MB
+      # toolchain. Both use their OWN `miri-` key prefix — never a shared one.
+      # The Miri sysroot is per-toolchain and per-target (two are built here: host + MSVC), so it
+      # belongs with the toolchain, not with the lockfile.
+      - name: cache the nightly toolchain + Miri sysroots
+        uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/rustup/toolchains/${{ env.MIRI_TOOLCHAIN }}-x86_64-unknown-linux-gnu
+            ~/.cache/miri
+          key: miri-toolchain-v1-${{ env.MIRI_TOOLCHAIN }}
+      - name: cache the cargo registry
+        uses: actions/cache@v4
+        with:
+          path: /usr/local/cargo/registry
+          key: miri-registry-v1-${{ hashFiles('Cargo.lock') }}
+          restore-keys: miri-registry-v1-
+
+      # The image needs no change for this: ci/rust-ci.Dockerfile:51-54 installs via rustup and
+      # `chmod -R a+w`s both RUSTUP_HOME and CARGO_HOME, so a job can add a toolchain at runtime.
+      # `rust-src` is required — cargo-miri builds its sysroot from source, per target.
+      #
+      # This does NOT disturb the 1.96.0 pin: `cargo +<toolchain>` overrides rust-toolchain.toml
+      # for that single invocation only, so `cargo fmt` / `clippy` keep resolving 1.96.0 and the
+      # fmt-parity contract in CLAUDE.md is untouched. The two echo lines below keep that claim
+      # honest in the log. They are deliberately NOT `rustup show active-toolchain`: that command
+      # RESOLVES the toolchain file and would install the whole 1.96.0 toolchain just to print a
+      # line, in a job where every cargo call is `+$MIRI_TOOLCHAIN` and 1.96.0 is never needed.
+      # Deliberately NOT `rustup override set` — that writes persistent per-directory state into
+      # the runner's rustup config, which leaks into unrelated later jobs on a self-hosted fleet.
+      # Deliberately NOT a second rust-toolchain.toml in a subdirectory — that would apply to
+      # every cargo invocation under that subtree including fmt, which is the drift the root pin
+      # exists to prevent.
+      - name: install the pinned nightly + miri
+        run: |
+          git config --global --add safe.directory "$PWD"
+          rustup toolchain install "$MIRI_TOOLCHAIN" \
+            --profile minimal \
+            --component miri,rust-src \
+            --target x86_64-pc-windows-msvc
+          echo "root pin, untouched by this job: $(grep -E '^channel' rust-toolchain.toml)"
+          cargo +"$MIRI_TOOLCHAIN" --version
+
+      # A run that reports `0 passed` is a selection that matched nothing, not a success — that
+      # exact mistake has already cost one round-trip here. So each step below checks a zero exit
+      # AND that at least one target reported a non-zero pass count, which is what catches a
+      # crate rename or a `--` filter that stops matching. (Each step legitimately prints several
+      # `0 passed` lines too — the empty bin/doctest targets — so the check is "at least one
+      # non-zero", not "no zeroes".) Expected counts at the time of writing: 21 + 12 + 4.
+      - name: miri — FFI-free leaf crates (native)
+        run: |
+          set -o pipefail
+          ok=1
+          cargo +"$MIRI_TOOLCHAIN" miri test \
+            -p pf-driver-proto -p pf-host-config -p pf-gpu 2>&1 | tee /tmp/miri-native.log || ok=0
+          grep -qE 'test result: ok\. [1-9][0-9]* passed' /tmp/miri-native.log || ok=0
+          [ "$ok" = 1 ] || echo "::warning::miri (FFI-free leaf crates, native) did not pass — non-blocking; see punktfunk-planning design/rust-safety-programme.md §7"
+
+      # THE step that justifies the job: pf-driver-proto at MSVC layout, on Linux, no Windows box.
+      # Expected: 21 passed. If this one ever goes red, treat it as a layout-contract break
+      # between the host and driver workspaces until proven otherwise.
+      - name: miri — pf-driver-proto at x86_64-pc-windows-msvc layout
+        run: |
+          set -o pipefail
+          ok=1
+          cargo +"$MIRI_TOOLCHAIN" miri test \
+            -p pf-driver-proto --target x86_64-pc-windows-msvc 2>&1 | tee /tmp/miri-msvc.log || ok=0
+          grep -qE 'test result: ok\. [1-9][0-9]* passed' /tmp/miri-msvc.log || ok=0
+          [ "$ok" = 1 ] || echo "::warning::miri (pf-driver-proto @ MSVC layout) did not pass — non-blocking, but this is the layout oracle for every frame and IOCTL; see design/rust-safety-programme.md §7"
+
+      # fec-rs dispatches its GF(2^8) multiply through RUNTIME `is_x86_feature_detected!`. Under
+      # Miri that detection reports the COMPILE-TIME target features, so WITHOUT these RUSTFLAGS
+      # the step silently interprets the scalar fallback and is worthless. Verified both ways on
+      # 192.168.1.25: bare, `avx2=false ssse3=false`; with the flags, `avx2=true ssse3=true` and
+      # `_mm256_shuffle_epi8` genuinely executes under the interpreter. GFNI stays false either
+      # way — Miri does not implement it — so the gfni branch is simply not covered here.
+      #
+      # ⚠ x86_64 ONLY, and it must stay that way. A RUSTFLAGS env var OVERRIDES config rustflags
+      # ENTIRELY (.cargo/config.toml:11-13 says so), and that config carries `--cfg aes_armv8` /
+      # `--cfg polyval_armv8` for aarch64 — worth a measured ~3x decrypt-throughput cliff if
+      # dropped. Harmless here because this job pins ubuntu-24.04/x86_64; fatal on mac-mini-1.
+      # Narrow selection is mandatory, not an optimisation: see the punktfunk-core note above.
+      - name: miri — punktfunk-core fec::gf8, taking the real AVX2/SSSE3 branches
+        env:
+          RUSTFLAGS: -C target-feature=+avx2,+ssse3
+        run: |
+          set -o pipefail
+          ok=1
+          cargo +"$MIRI_TOOLCHAIN" miri test \
+            -p punktfunk-core --lib -- fec::gf8 2>&1 | tee /tmp/miri-gf8.log || ok=0
+          grep -qE 'test result: ok\. [1-9][0-9]* passed' /tmp/miri-gf8.log || ok=0
+          [ "$ok" = 1 ] || echo "::warning::miri (punktfunk-core fec::gf8, AVX2/SSSE3) did not pass — non-blocking; see design/rust-safety-programme.md §7"
+
+  # ASAN + LSAN over the C ABI harness — §6.1 of design/rust-safety-programme.md, its rank-1
+  # tooling item. crates/punktfunk-core/tests/c/run.sh already proves the staticlib links and
+  # round-trips 4 frames byte-exact from C on every push (ci.yml); PF_SAN=address rebuilds BOTH
+  # sides instrumented — the staticlib on nightly with -Zsanitizer/-Zbuild-std (std itself
+  # included), the harness with clang -fsanitize — so ASAN sees the seam a Rust-only tool cannot,
+  # and LSAN (detect_leaks=1, the script's default) becomes the one automated check on abi.rs's
+  # Box::into_raw/from_raw leak contract.
+  # Proven to fail on 192.168.1.25: deleting a single punktfunk_session_free() from harness.c
+  # makes LSAN report the ~308 Rust-side allocations behind the handle and run.sh exit 1.
+  # What it does NOT see: the invalid-InputKind-discriminant UB at abi.rs (that needs the
+  # validator, tracked in §5 of the programme doc), and nothing GPU/Windows — this is the
+  # default-feature (quic-less, opus-less) core only.
+  c-abi-asan:
+    runs-on: ubuntu-24.04
+    container:
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
+    timeout-minutes: 30
+    env:
+      # The SAME dated pin as the miri job above, deliberately — one nightly date to bump for
+      # both jobs (they have no toolchain interaction; sharing the date just halves the chores).
+      SAN_TOOLCHAIN: nightly-2026-08-10
+      # Same guard as the miri job: audit.yml sets no sccache today, and -Zbuild-std could not
+      # use it anyway. Keeps a future workflow-level sccache from becoming a puzzle.
+      RUSTC_WRAPPER: ""
+    steps:
+      - uses: actions/checkout@v4
+
+      # Own `san-` key prefixes — never shared with the miri caches, per the cache-poisoning
+      # note there (and so an incomplete save from one job can never starve the other).
+      - name: cache the nightly toolchain
+        uses: actions/cache@v4
+        with:
+          path: /usr/local/rustup/toolchains/${{ env.SAN_TOOLCHAIN }}-x86_64-unknown-linux-gnu
+          key: san-toolchain-v1-${{ env.SAN_TOOLCHAIN }}
+      - name: cache the cargo registry
+        uses: actions/cache@v4
+        with:
+          path: /usr/local/cargo/registry
+          key: san-registry-v1-${{ hashFiles('Cargo.lock') }}
+          restore-keys: san-registry-v1-
+
+      # rust-src is required: -Zbuild-std compiles std from source so it is instrumented too —
+      # without that, LSAN cannot attribute allocations made inside std (Vec, Box, HashMap).
+      - name: install the pinned nightly + rust-src
+        run: |
+          git config --global --add safe.directory "$PWD"
+          rustup toolchain install "$SAN_TOOLCHAIN" --profile minimal --component rust-src
+          echo "root pin, untouched by this job: $(grep -E '^channel' rust-toolchain.toml)"
+          cargo +"$SAN_TOOLCHAIN" --version
+
+      # The image installs clang but Ubuntu does not always pull the compiler-rt sanitizer
+      # runtime with it (verified absent on a stock 26.04 box). Probe with an actual ASAN link
+      # and self-heal via apt if it fails — container jobs on this fleet run as root (the
+      # bun-audit job's apt-get above relies on the same fact).
+      - name: ensure clang's ASAN runtime
+        run: |
+          if ! echo 'int main(void){return 0;}' | clang -fsanitize=address -x c - -o /tmp/asan-probe 2>/dev/null; then
+            apt-get update && apt-get install -y --no-install-recommends "libclang-rt-$(clang -dumpversion | cut -d. -f1)-dev"
+            echo 'int main(void){return 0;}' | clang -fsanitize=address -x c - -o /tmp/asan-probe
+          fi
+
+      # run.sh handles everything behind PF_SAN (nightly build, target path, clang flags,
+      # ASAN_OPTIONS=detect_leaks=1) and exits non-zero on any report. The grep is the
+      # proved-it-ran guard, same reasoning as the miri steps: a script change that silently
+      # skips the harness must not read as green. run.sh expects bash and PATH cargo — both true
+      # in this container. PF_SAN_TOOLCHAIN pins the script's `cargo +<toolchain>` to the dated
+      # nightly installed above — without it the script would ask for the ROLLING `nightly`
+      # channel, which this job deliberately does not install.
+      - name: C ABI harness under ASAN+LSAN
+        run: |
+          set -o pipefail
+          ok=1
+          PF_SAN=address PF_SAN_TOOLCHAIN="$SAN_TOOLCHAIN" \
+            bash crates/punktfunk-core/tests/c/run.sh 2>&1 | tee /tmp/asan-harness.log || ok=0
+          grep -q 'PASS: 4 frames round-tripped byte-exact' /tmp/asan-harness.log || ok=0
+          [ "$ok" = 1 ] || echo "::warning::c-abi-asan did not pass — non-blocking on day one; see design/rust-safety-programme.md §6.1. An LSAN report here means the abi.rs into_raw/from_raw contract broke."

.gitea/workflows/ci.yml

@@ -111,9 +111,31 @@ jobs:
       - name: Format
         run: cargo fmt --all --check
 
+      # rust-safety WP2c: three textual gates for classes no lint covers — unsafe fn markers
+      # carrying no contract, panic across an extern boundary (an abort since 1.81), and
+      # process-global safe APIs (env::set_var & co, count-ratcheted). Pure grep/awk, no cargo.
+      # Both failure modes were demonstrated before this became blocking (planted instances).
+      - name: Unsafe-hygiene grep gates
+        run: sh scripts/ci/check-unsafe-hygiene.sh
+
       - name: Clippy (deny warnings)
         run: cargo clippy --workspace --all-targets --locked -- -D warnings
 
+      # WP19 (rust-safety): the hardened NATIVE-ONLY host — no Moonlight-compat planes, no
+      # `rusty_enet` (transpiled C ENet), no `rsa`. Kept compiling here so the cfg boundary can't
+      # rot, and the dependency claim is ASSERTED, not assumed: `cargo tree -i` must find neither
+      # crate in the native-only graph (it exits non-zero with "nothing depends on" — inverted).
+      - name: Clippy + tree (native-only host, no gamestream feature)
+        run: |
+          cargo clippy -p punktfunk-host --no-default-features --features pyrowave \
+            --all-targets --locked -- -D warnings
+          if cargo tree -p punktfunk-host --no-default-features --features pyrowave \
+            --locked -i rusty_enet 2>/dev/null | grep -q rusty_enet; then
+            echo "native-only build still depends on rusty_enet"; exit 1; fi
+          if cargo tree -p punktfunk-host --no-default-features --features pyrowave \
+            --locked -i rsa 2>/dev/null | grep -q "^rsa"; then
+            echo "native-only build still depends on rsa"; exit 1; fi
+
       - name: Build
         run: cargo build --workspace --locked
 
@@ -124,8 +146,8 @@ jobs:
       # `nvenc` gates enc/linux/nvenc_cuda.rs (+ nvenc_core/nvenc_status) and `vulkan-encode` gates
       # enc/linux/vulkan_video.rs (+ the vendored vk_av1_encode/vk_valve_rgb bindings) — ~8,150
       # lines carrying ~70 `unsafe` blocks. Their ONLY prior CI coverage was deb.yml's
-      # `cargo build`, where warnings are not errors, so pf-encode's own
-      # `#![deny(clippy::undocumented_unsafe_blocks)]` — the crate's stated unsafe-proof gate —
+      # `cargo build`, where warnings are not errors, so the `undocumented_unsafe_blocks` deny
+      # (now hoisted into [workspace.lints]) — pf-encode's stated unsafe-proof gate —
       # was never actually enforced on them. (`pyrowave` needs no extra step: punktfunk-host has
       # `default = ["pyrowave"]`, so the steps above already cover it.)
       #

.gitea/workflows/windows-drivers.yml

@@ -159,9 +159,10 @@ jobs:
         # The gamepad drivers' business logic is 100% safe (it moved onto pf-umdf-util, the audited
         # unsafe layer); pf-vdisplay + wdk-iddcx are inherently FFI-bound but every `unsafe {}` carries a
         # `// SAFETY:` proof. Both invariants are lint-gated (`unsafe_op_in_unsafe_fn` +
-        # `undocumented_unsafe_blocks`); this step keeps them from regressing. (wdk-probe is a
-        # toolchain-only probe crate and is excluded.)
-        run: cargo clippy -p pf-umdf-util -p pf-xusb -p pf-gamepad -p pf-mouse -p wdk-iddcx -p pf-vdisplay --all-targets -- -D warnings
+        # `undocumented_unsafe_blocks`); this step keeps them from regressing. wdk-probe is a
+        # toolchain-only probe crate, but it holds real DDI slot-dispatch unsafe (iddcx_rt.rs), so it
+        # runs the same gates.
+        run: cargo clippy -p pf-umdf-util -p pf-xusb -p pf-gamepad -p pf-mouse -p wdk-iddcx -p pf-vdisplay -p wdk-probe --all-targets -- -D warnings
       - name: cargo fmt --check the safe-layer + gamepad/mouse drivers
         run: cargo fmt -p pf-umdf-util -p pf-xusb -p pf-gamepad -p pf-mouse --check
       - name: Inspect /INTEGRITYCHECK (before) — expect FORCE_INTEGRITY set by wdk-build

CHANGELOG.md

@@ -14,6 +14,98 @@ with the version table of the release you are moving to, then read **Breaking ch
 
 ## v0.27.1 — in development
 
+### GameStream is now opt-in on EVERY route (⚠ packager-visible default change)
+
+The secure native-only host is the default everywhere; the Moonlight-compat planes (plain-HTTP
+pairing + the legacy GCM path, security-review #5/#9) are enabled only by an explicit choice:
+
+- **The shipped systemd user unit** (`scripts/punktfunk-host.service`, installed by deb/RPM/Arch/
+  sysext) runs bare `serve` — `--gamestream` is no longer baked into `ExecStart`. Opt in via the
+  new **`PUNKTFUNK_GAMESTREAM=1`** knob in `host.env` (pf-host-config; equivalent to the flag —
+  either source enables), so no unit editing survives-upgrades dance is needed.
+  ⚠ **Upgrade note:** a packaged host that served Moonlight by default becomes native-only until
+  the operator sets the knob (a hand-made `ExecStart` drop-in keeps winning as before).
+- **NixOS module**: `services.punktfunk.host.gamestream` default flipped `true` → `false`
+  (module-check gained a "default is native-only" assertion); enabling it still opens the
+  GameStream firewall ports.
+- **Steam Deck installer**: `--gamestream` opts in (was on-by-default with `--no-gamestream`;
+  the old flag is still accepted as explicit-off).
+- Windows was already opt-in (unchecked installer task) and is unchanged.
+
+### The ENet control port now exists only while a pairing does (rust-safety WP0)
+
+`rusty_enet` — a c2rust-style transpile of C ENet, and the host's only pre-auth-reachable unsafe
+surface — no longer listens unconditionally: UDP 47999 binds when the paired-client list becomes
+non-empty and is torn down when the last pairing is removed (a live client gets the same
+TERMINATION+disconnect farewell as a host-side session end). Pairing itself is HTTPS on nvhttp and
+never touches the port, so a never-paired `--gamestream` host exposes no ENet at all. En route:
+the management API's unpair endpoint never persisted (`save_paired` was missing), so an unpair
+lasted only until the next restart — fixed. `rusty_enet` is now pinned `=0.4.0`.
+
+**Unpair is now a complete revocation, on both planes.** Beyond the persistence fix above, an
+unpair used to leave the revoked client's LIVE session streaming until the client chose to
+leave. Now: unpairing a GameStream client whose certificate owns the active launch ends that
+session (the client gets the standard TERMINATION+disconnect, and unpair-all still closes the
+ENet port); unpairing a native client deliberately stops its live punktfunk/1 session(s)
+(matched by certificate fingerprint — anonymous/TOFU sessions are unaffected, they have no
+pairing to revoke). The unpair endpoint's long-standing docstring caveat ("removes the client
+from the listing without severing its ability to reconnect") is retired: TLS-level handshakes
+still complete by design, but authorization is per-request and a live session no longer
+survives its own revocation.
+
+### GameStream is now a cargo feature (compile-time isolation — packager-visible)
+
+The Moonlight-compat planes (nvhttp pairing, RTSP, the ENet control stream, `_nvstream` mDNS,
+the compat media path) are gated behind a new **`gamestream` cargo feature — default ON**, so
+every stock package is behaviorally identical (GameStream stays runtime-opt-in via
+`--gamestream` / `PUNKTFUNK_GAMESTREAM`). Building with
+`--no-default-features --features pyrowave` produces the **hardened native-only host**:
+
+- **no `rusty_enet`** — the c2rust-transpiled C ENet stack (158 unsafe sites) is absent from
+  the binary, provably (`cargo tree -i rusty_enet` finds nothing; CI asserts it);
+- **no `rsa`** — the native planes run on the P-256 identity (above), and the legacy-identity
+  fallback is a pem-only read (rustls/ring serves an existing RSA cert without the crate), so
+  the accepted Marvin advisory (RUSTSEC-2023-0071) no longer applies to native-only builds;
+- ~6,700 lines of Moonlight protocol code gone; `serve --gamestream` (or the env knob) against
+  such a binary **refuses to start** with a clear error rather than serving less than asked;
+- the native-only management API (and its OpenAPI document) has no GameStream PIN endpoints
+  (`/api/v1/pair`, `/api/v1/pair/pin`); everything else — including the paired-client list and
+  unpair — is identical, so consoles work unchanged.
+
+The checked-in `api/openapi.json` remains the default-features document.
+
+### The identity split — the native planes get their own (P-256) host identity
+
+One RSA-2048 identity historically served every plane, because Moonlight mandates RSA and the
+planes grew out of the GameStream host. The native punktfunk/1 QUIC plane and the management API
+now share a separate **ECDSA P-256** identity (`native-cert.pem`/`native-key.pem`): generated by
+ring via rcgen, browser-compatible (Ed25519 server certs are not), carrying real SANs
+(localhost, loopback, the machine hostname — the legacy cert had none), and free of the accepted
+`rsa`-crate Marvin advisory. The GameStream plane keeps the RSA identity untouched.
+
+**Migration is pin-preserving by construction**: clients TOFU-pin the leaf-cert SHA-256 at
+pairing and use that one pin for both QUIC and the mgmt/library API, so the new identity is
+adopted **only when the native trust store is empty** (fresh installs, or after an explicit
+unpair-all + restart). An upgraded host with live native pairings keeps presenting the legacy
+RSA cert those clients pinned, and logs the migration path. Fingerprint pinning is
+algorithm-agnostic, so existing shipped clients pair against P-256 hosts unchanged.
+
+Follow-the-identity consumers updated in-tree: the tray's loopback pin and the plugin SDK's
+mgmt CA now prefer `native-cert.pem` (falling back to `cert.pem`), and the Windows runner ACL
+grant covers both. ⚠ A plugin bundling an **older** `@punktfunk/host` SDK on a **fresh**
+(P-256) host trusts the wrong cert — set `PUNKTFUNK_MGMT_CA=<config>/native-cert.pem` in its
+environment or rebuild against the current SDK.
+
+### Memory-safety, compiler-enforced (embedder-visible lint tightening)
+
+`punktfunk-core` now carries `#![deny(unsafe_code)]` crate-wide: everything that parses network
+bytes is safe Rust by compiler-enforced invariant. The documented `#![allow]` carve-outs are the
+client surface (`abi`, `client`) and the platform syscall-batching shims under `transport`
+(`udp/{apple,linux,windows}`, `qos_windows`) — none of which interpret attacker bytes. In
+`punktfunk-host`, the modules a secure-default host exposes (`native`, `native_pairing`, `mgmt`,
+`mgmt_token`, `discovery`, `wol`) are `#[forbid(unsafe_code)]`. If you embed `punktfunk-core` and
+patch it, new unsafe outside the carve-outs is now a compile error.
+
 ### NixOS + KDE — session detection, the other half
 
 🛑 **v0.27.0's NixOS session-detection fix did not reach a stock NixOS + Plasma 6 box.** It resolved
@@ -42,6 +134,70 @@ availability probe. The `comm` fast path is still one read for every ordinary di
 Also reached by the same rung: `gamescope` carries `cap_sys_nice` on a number of distros, so a
 *wrapped and capped* gamescope was equally invisible to the foreign-gamescope probe.
 
+### Game Mode on Nobara — the WSI opt-out never reached the games
+
+🛑 **v0.27.0's fix for the distro Vulkan WSI layer was clobbered by the session script, so games ran
+on a black screen** while the host's own log claimed the layer had been disabled. Steam Big Picture
+came up, showed the right mode, showed the perf overlay — and then every game played sound and took
+input over a black picture, with no error on either side.
+
+The layer (`VkLayer_FROG_gamescope_wsi`) ships with the *distro's* gamescope and speaks its
+`gamescope_swapchain` protocol; ours disagrees, so the compositor rejects the client's
+`swapchain_feedback` and kills it. v0.27.0 turned the layer off with `ENABLE_GAMESCOPE_WSI=0` on the
+session unit. `gamescope-session-plus` then runs an unconditional `export ENABLE_GAMESCOPE_WSI=1`
+near the top of the script — before it launches anything — so the opt-out survived exactly as long
+as it took the script to start, and every process the session spawned got the layer back. Nothing
+looked wrong because the casualty is Vulkan clients specifically: Steam's own UI is not one.
+
+The opt-out is now `DISABLE_GAMESCOPE_WSI=1` as well. The Vulkan loader reads an implicit layer's
+two manifest knobs in a fixed order: `enable_environment` must equal `"1"` to switch the layer on,
+and `disable_environment` is then consulted last and wins on **presence alone**, at any value. The
+session script never mentions that second variable, so it is the one that survives. Both spellings
+go out, on the transient unit and on the box's own session drop-in.
+
+### punktfunk-gamescope `+pfhdr6` — a NO_FOCUS window can no longer steal the composite
+
+🛑 **A mapped-but-unpainted window carrying `GAMESCOPE_NO_FOCUS=1` could win gamescope's focus
+selection and turn the composite — and the stream fed from it — black while every health signal
+stayed green.** Bazzite's hhd-ui (Handheld Daemon overlay) sets that atom once at init, stamps
+Steam's appid, and crash-loops under a headless takeover; each respawn remapped a fullscreen black
+window that steamcompmgr then chose over Big Picture (observed on a Bazzite box: client stats
+happily decoding 60 fps at 0.1 Mb/s of black; killing hhd-ui restored the picture instantly). No
+gamescope — upstream or Bazzite's fork — ever consumed the atom; its setters (hhd-ui, MangoHud)
+show and hide via the `STEAM_OVERLAY` protocol and rely on never being focusable. Patch 0008 wires
+`GAMESCOPE_NO_FOCUS` exactly like `GAMESCOPE_EXTERNAL_OVERLAY` (read at map, PropertyNotify-tracked,
+skipped by both focus-candidate collectors) without touching compositing or `appID`. Banner
+`+pfhdr5` → `+pfhdr6`; no new capability — the bump is so a field box's banner tells the two
+behaviors apart.
+
+### Linux capture — the truncated first attempt no longer latches sticky downgrades
+
+🛑 **The pipeline retry loop's deliberately short (2.5 s) first-frame attempt could permanently
+downgrade the whole host process.** On expiry, the portal capturer's timeout diagnosis latched
+whichever offer it implicated — HDR capture off (per source), the raw-dmabuf offer off, the
+EGL→CUDA offer off — as if the compositor had refused it, when the budget was truncated by design
+and a gamescope cold start routinely needs longer before delivering anything. One lost race at
+connect then pinned every later session to SDR and/or CPU capture until the host restarted. The
+truncated attempt is now declared provisional end to end
+(`Capturer::next_frame_within_provisional`): its expiry names the same suspect in the error text
+but latches nothing; only the full-length attempts that follow hand down negotiation verdicts. The
+classification is a pure function with tests
+(`pf_capture::linux::first_frame_timeout_tests`).
+
+### Windows host — an idle box can sleep again (virtual-mic stream idle-stop)
+
+🛑 **Installing the host blocked system sleep forever, client connected or not.** The
+host-lifetime mic pump kept a WASAPI render stream RUNNING on the virtual-mic device
+(typically the Steam Streaming Microphone), writing silence 24/7 — and any running stream makes
+the Windows audio stack hold a kernel power request ("An audio stream is currently in use" in
+`powercfg /requests`, attributed to that device) that vetoes sleep. The render loop now stops
+the stream (`IAudioClient::Stop`; the client stays initialized and the mic *endpoint* keeps
+existing for apps to bind) after 10 s of silence-only output and resumes on the next mic frame
+within one device period — below the jitter buffer's prime depth, so nothing is audible.
+Streaming sessions still hold the box awake through their own `PowerRequest` assertions, as
+before. New knob: `PUNKTFUNK_MIC_ALWAYS_ON=1` restores the old always-running stream in case a
+third-party virtual audio driver misbehaves while its render side is paused.
+
 ## v0.27.0
 
 87 commits since v0.26.0.

Cargo.lock

@@ -1116,6 +1116,7 @@ dependencies = [
 name = "display-disturb"
 version = "0.27.0"
 dependencies = [
+ "pf-win-display",
  "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 

Cargo.toml

@@ -101,6 +101,17 @@ repository = "https://git.unom.io/unom/punktfunk"
 [workspace.lints.rust]
 unsafe_op_in_unsafe_fn = "deny"
 
+# The companion lint: every `unsafe {}` / `unsafe impl` carries a `// SAFETY:` proof. Hoisted here
+# from ~85 per-file `#![deny(...)]` attributes so a NEW crate (or a new module in an old one) is
+# covered on creation rather than on remembering — the per-file form left pf-vkhdr-layer,
+# wdk-probe, and half of pf-clipboard uncovered for months. NOTE: this table reaches only crates
+# with `[lints] workspace = true`; `packaging/windows/drivers` and `packaging/windows/pf-vkhdr-layer`
+# are SEPARATE workspaces and restate it (any "workspace-wide" claim must be made three times or it
+# is false). Of the members, only the two vendored snapshots (pf-bitstream/vendor/cros-codecs,
+# punktfunk-host/vendor/usbip-sim) stay out, deliberately — upstream code stays pristine.
+[workspace.lints.clippy]
+undocumented_unsafe_blocks = "deny"
+
 [profile.release]
 opt-level = 3
 lto = "thin"

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.26.0"
+    "version": "0.27.0"
   },
   "paths": {
     "/api/v1/clients": {
@@ -53,7 +53,7 @@
           "clients"
         ],
         "summary": "Unpair a client",
-        "description": "Removes the client's certificate from the pairing store. Caveat: the nvhttp TLS layer\ndoes not yet reject unlisted certificates (`gamestream/tls.rs` accepts any well-formed\nclient cert — a planned hardening step), so until that lands this removes the client\nfrom the listing without severing its ability to reconnect.",
+        "description": "Removes the client's certificate from the pairing store (persisted — the removal survives a\nhost restart). Revocation is complete: a LIVE GameStream session owned by this certificate is\nended (the client gets the standard TERMINATION+disconnect), and removing the last pairing\nalso closes the ENet control port (UDP 47999), which is only bound while at least one pairing\nexists. The nvhttp TLS layer still completes a handshake with any well-formed client cert BY\nDESIGN (authorization is per-request via the paired-fingerprint check) — an unpaired client\nthat reconnects is rejected at every post-pair endpoint.",
         "operationId": "unpairClient",
         "parameters": [
           {
@@ -4753,6 +4753,10 @@
             "type": "boolean",
             "description": "EXPERIMENTAL (Windows): command physical monitors' panels off over DDC/CI (VCP 0xD6 →\nDPMS off) right before an `Exclusive` isolate deactivates them, and back on at restore.\nTargets the \"connected-but-dark head\" periodic-stutter class (monitor standby\nauto-input-scan / DP link churn while the virtual display is the sole active display) at\nthe monitor-firmware level. Best-effort — monitors without DDC/CI (or with it disabled in\nthe OSD) are skipped. Orthogonal to `preset` (like `game_session`): preserved across\npreset changes; `#[serde(default)]` = off so existing `display-settings.json` files are\nuntouched."
           },
+          "edid_lock": {
+            "type": "boolean",
+            "description": "**EXPERIMENTAL, AMD-only in effect: pin connector EDID emulation while streaming** — the\nsoftware equivalent of an HPD-holding dummy plug (`pf_win_display::adl_emul`). Locked at\nthe first Exclusive isolate BEFORE the physicals deactivate (an awake sink answers its\nlive-EDID read), unlocked at last-member teardown, crash-journaled so a dead host unlocks\non its next start. Targets the standby-sink stall class at its SOURCE: with emulation\npinned the KMD stops servicing the sleeping sink's HPD/DDC/link. Inert without an AMD\ndriver (`atiadlxx.dll` absent) and on non-Windows. Orthogonal to `preset` (like\n`game_session`); `#[serde(default)]` = off."
+          },
           "game_session": {
             "$ref": "#/components/schemas/GameSession",
             "description": "How a game-launching session is served (`design/gamemode-and-dedicated-sessions.md` §5.2).\nOrthogonal to `preset`/lifecycle — preserved across preset changes; `#[serde(default)]` = `Auto`\nso existing `display-settings.json` files are untouched."
@@ -4788,7 +4792,7 @@
           "version": {
             "type": "integer",
             "format": "int32",
-            "description": "Schema version (currently 1) — lets a future field addition migrate rather than reject.",
+            "description": "Schema version (currently 1) — lets a future field addition migrate rather than reject. Read\nat load time ([`DisplayPolicyStore::load_from`] warns when a file claims a version this host\ndoes not know, then reads it best-effort) and pinned back to the current version on write.",
             "minimum": 0
           }
         }
@@ -4857,7 +4861,7 @@
       },
       "EffectivePolicy": {
         "type": "object",
-        "description": "The six resolved fields after preset expansion — what the lifecycle/registry and the Stage-0 call\nsites read, and what the mgmt API echoes as the \"currently in force\" policy. Pure output of\n[`DisplayPolicy::effective`].",
+        "description": "The six resolved fields after preset expansion — what the lifecycle/registry and the policy call\nsites read, and what the mgmt API echoes as the \"currently in force\" policy. Pure output of\n[`DisplayPolicy::effective`].\n\n**Every field is required on the wire, deliberately.** Unlike [`DisplayPolicy`] — which is only\never a *file* — this shape is also the `fields` member of [`CustomPresetInput`], i.e. the request\nbody of `POST /display/presets` and `PUT /display/presets/{id}`, and a *response* member three\ntimes over (`DisplaySettingsState.effective`, `PresetInfo.fields`, `CustomPreset.fields`).\n`#[serde(default)]` here would (a) turn `{\"name\":\"Kiosk\",\"fields\":{}}` — or any camelCase typo —\nfrom a serde rejection into a 201 storing a preset that expands to six axes nobody chose, and\n(b) make all six OPTIONAL in the generated OpenAPI schema, so every codegen'd client has to\nnull-check them. The *persisted* catalog's tolerance for an entry written before an axis existed\nis bought where it belongs, on the read path only: see [`StoredEffectivePolicy`].",
         "required": [
           "keep_alive",
           "topology",
@@ -5915,7 +5919,7 @@
       },
       "Identity": {
         "type": "string",
-        "description": "Stable display identity, so desktop environments persist per-display config (KDE scaling). Stored\nat Stage 0; carriers wired from the identity stage.",
+        "description": "Stable display identity, so desktop environments persist per-display config (KDE scaling). The\nslot this resolves to is carried per backend: the Windows EDID serial + IddCx connector index,\nKWin's per-slot output name, and the host-persisted Mutter scale map.",
         "enum": [
           "shared",
           "per-client",
@@ -6132,14 +6136,14 @@
               "seconds": {
                 "type": "integer",
                 "format": "int32",
-                "description": "Linger window in seconds.",
+                "description": "Linger window in seconds, clamped to `0..=86400` on write (see\n[`DisplayPolicy::sanitized`]): a window longer than a day is `forever` by any honest\nreading, and `u32` seconds is ~136 years — a deadline the reaper would never reach and a\nnonsense `expires_in_ms` in `/display/state`.",
                 "minimum": 0
               }
             }
           },
           {
             "type": "object",
-            "description": "Keep the display until host shutdown or an explicit release (the `Pinned` lifecycle state).\n**Not honored until the display-lifecycle stage** — rejected by the mgmt PUT at Stage 0.",
+            "description": "Keep the display until host shutdown or an explicit release (the `Pinned` lifecycle state).\nHonored end-to-end: the registry resolves it to `Release::Pin`, so the display survives every\ndisconnect — free it with `POST /display/release` (which force-releases `Pinned` exactly like\na `Lingering` display). This is what the `gaming-rig` preset selects.",
             "required": [
               "mode"
             ],
@@ -6183,6 +6187,7 @@
           },
           "positions": {
             "type": "object",
+            "description": "Keys are the **canonical decimal** identity-slot id (`\"1\"`..`\"15\"`) — the exact string\n`arrange` looks a member up by. [`DisplayPolicy::sanitized`] re-canonicalizes them on write\n(`\"01\"` → `\"1\"`) and drops anything that is not a slot id, because a key that never matches is\na pin the operator can see in the console and in `GET /display/settings` while every session\nsilently auto-rows past it.",
             "additionalProperties": {
               "$ref": "#/components/schemas/Position"
             },
@@ -6194,7 +6199,7 @@
       },
       "LayoutMode": {
         "type": "string",
-        "description": "How group members are arranged in the desktop coordinate space. Stored at Stage 0; applied from\nthe multi-monitor stage.",
+        "description": "How group members are arranged in the desktop coordinate space, resolved by `layout::arrange` —\nwhich both the `/display/state` readout and (on Linux, KWin only) the per-backend position apply\nconsume, so the answer is computed in exactly one place.",
         "enum": [
           "auto-row",
           "manual"
@@ -6354,7 +6359,7 @@
       },
       "ModeConflict": {
         "type": "string",
-        "description": "Admission when a *different* client connects while a display/session is already live and asks for\na different mode. Stored at Stage 0; enforced from the mode-conflict admission stage.",
+        "description": "Admission when a *different* client connects while a display/session is already live and asks for\na different mode. Enforced by [`super::admission`] before the Welcome is sent, so a `reject` is a\nclean handshake error rather than a half-built session.",
         "enum": [
           "separate",
           "steal",

clients/android/app/src/main/kotlin/io/unom/punktfunk/App.kt

@@ -56,6 +56,7 @@ import io.unom.punktfunk.kit.link.HostResolution
 import io.unom.punktfunk.kit.SessionEndReason
 import io.unom.punktfunk.kit.security.KnownHostStore
 import io.unom.punktfunk.models.ActiveSession
+import io.unom.punktfunk.models.LibraryReturn
 import io.unom.punktfunk.models.Tab
 import kotlin.math.roundToInt
 import kotlinx.coroutines.launch
@@ -74,7 +75,7 @@ fun App(forceGamepadUi: Boolean = false) {
     // whose library the console shell should come back to. Held HERE because the shell's own
     // navigation state does not outlive the stream. Cleared once the shell has consumed it, so a
     // later manual Back out of the library is not undone by a stale value.
-    var reopenLibraryHostId by remember { mutableStateOf<String?>(null) }
+    var reopenLibrary by remember { mutableStateOf<LibraryReturn?>(null) }
 
     // Console (gamepad) mode mirrors the Apple client: the setting AND (its mode says Always OR a
     // pad is attached OR this is a TV OR the dev force flag). Flips live as controllers
@@ -139,9 +140,9 @@ fun App(forceGamepadUi: Boolean = false) {
                 // than all the way out to host selection. The console shell's own screen state does
                 // not survive the stream (StreamScreen replaces it in the composition, discarding
                 // its `remember`s), so the intent is hoisted here and handed back on the way in.
-                reopenLibraryHostId =
+                reopenLibrary =
                     if (reason == SessionEndReason.GAME_EXITED && active.launchedFromLibrary) {
-                        active.hostId
+                        active.hostId?.let { LibraryReturn(it, active.libraryProfileId) }
                     } else {
                         null
                     }
@@ -154,8 +155,8 @@ fun App(forceGamepadUi: Boolean = false) {
                 onConnected = { session = it },
                 deepLink = pendingLink,
                 onDeepLinkHandled = { activity?.pendingDeepLink = null },
-                reopenLibraryHostId = reopenLibraryHostId,
-                onReopenLibraryHandled = { reopenLibraryHostId = null },
+                reopenLibrary = reopenLibrary,
+                onReopenLibraryHandled = { reopenLibrary = null },
             )
         } else {
             // Adaptive nav: a bottom bar on phones; on tablets / large windows a side NavigationRail
@@ -282,15 +283,19 @@ fun GamepadShell(
     deepLink: String? = null,
     onDeepLinkHandled: () -> Unit = {},
     /**
-     * Open this saved host's library instead of Home on the way in — set when a game launched from
-     * it has just exited. Null (the default) starts on Home exactly as before.
+     * Open this library shelf instead of Home on the way in — set when a game launched from it has
+     * just exited. Null (the default) starts on Home exactly as before.
      */
-    reopenLibraryHostId: String? = null,
+    reopenLibrary: LibraryReturn? = null,
     onReopenLibraryHandled: () -> Unit = {},
 ) {
     val context = LocalContext.current
     var screen by remember { mutableStateOf(GamepadScreen.Home) }
     var libraryHost by remember { mutableStateOf<io.unom.punktfunk.kit.security.KnownHost?>(null) }
+    // Which of that host's shelves is open: the pinned card's profile id, or null for the host's
+    // own tile (design §5.2a). Held beside `libraryHost` because it is the same navigation fact —
+    // a pinned card and its host are two tiles, and the library belongs to whichever you pressed.
+    var libraryPinId by remember { mutableStateOf<String?>(null) }
     // Where the settings screen was when a sub-screen took over. The shell's AnimatedContent
     // discards a screen's `remember`s the moment it stops being the target, so a trip out to the
     // Controllers view and back would otherwise land on the Stream tab's first row — the couch
@@ -301,15 +306,21 @@ fun GamepadShell(
     // Consume the "come back to this library" intent once, on entry. Keyed on the id so a second
     // game exit re-fires it; the parent clears it immediately, so a manual Back stays backed out.
     // A host that has since been forgotten simply leaves us on Home rather than failing.
-    LaunchedEffect(reopenLibraryHostId) {
-        val id = reopenLibraryHostId ?: return@LaunchedEffect
+    LaunchedEffect(reopenLibrary) {
+        val (id, pinId) = reopenLibrary ?: return@LaunchedEffect
         // Navigate BEFORE acknowledging: acknowledging clears the parent's state, which re-keys
         // this effect and cancels the coroutine running it. Nothing suspends in between today, so
         // either order happens to work — but this one cannot be broken by a later edit that adds a
         // suspending call. A host that has since been forgotten just leaves us on Home.
         KnownHostStore(context).all()
             .firstOrNull { it.id == id }
-            ?.let { libraryHost = it; screen = GamepadScreen.Library }
+            // A pin unpinned while the game was running is no longer a shelf: fall back to the
+            // host's own, rather than a card that no longer exists.
+            ?.let { kh ->
+                libraryHost = kh
+                libraryPinId = pinId?.takeIf { it in kh.pinnedProfileIds }
+                screen = GamepadScreen.Library
+            }
         onReopenLibraryHandled()
     }
 
@@ -377,7 +388,11 @@ fun GamepadShell(
                 onDeepLinkHandled = onDeepLinkHandled,
                 gamepadUi = true,
                 onOpenSettings = { screen = GamepadScreen.Settings },
-                onOpenLibrary = { host -> libraryHost = host; screen = GamepadScreen.Library },
+                onOpenLibrary = { host, pinId ->
+                    libraryHost = host
+                    libraryPinId = pinId
+                    screen = GamepadScreen.Library
+                },
                 navGate = s == screen,
             )
             GamepadScreen.Settings -> GamepadSettingsScreen(
@@ -407,8 +422,9 @@ fun GamepadShell(
                     host = host,
                     settings = settings,
                     onLaunched = onConnected,
-                    onBack = { screen = GamepadScreen.Home; libraryHost = null },
+                    onBack = { screen = GamepadScreen.Home; libraryHost = null; libraryPinId = null },
                     navActive = s == screen,
+                    pinnedProfileId = libraryPinId,
                 )
             } ?: run { screen = GamepadScreen.Home }
         }

clients/android/app/src/main/kotlin/io/unom/punktfunk/ConnectPrompts.kt

@@ -42,7 +42,7 @@ internal fun ConnectPrompts(
     optionsTarget: HostCardEntry?,
     onDismissOptions: () -> Unit,
     libraryEnabled: Boolean,
-    onOpenLibrary: (KnownHost) -> Unit,
+    onOpenLibrary: (KnownHost, String?) -> Unit,
     onWake: (KnownHost) -> Unit,
     onSpeedTest: (KnownHost) -> Unit,
     onCopyLink: (KnownHost, StreamProfile?) -> Unit,
@@ -119,9 +119,11 @@ internal fun ConnectPrompts(
             canWake = kh.mac.isNotEmpty() && offline,
             onWake = { onDismissOptions(); onWake(kh) },
             // A saved host always has a library (it's a knownHost) → offer it when the setting's on,
-            // so a TV remote reaches the library here instead of via the Y face button.
-            onLibrary = if (libraryEnabled && pin == null) {
-                { onDismissOptions(); onOpenLibrary(kh) }
+            // so a TV remote reaches the library here instead of via the Y face button. A PIN card
+            // gets it too, opening its own shelf: unlike wake/edit/forget, the library is a way to
+            // start the card, not a property of the host.
+            onLibrary = if (libraryEnabled) {
+                { onDismissOptions(); onOpenLibrary(kh, pin?.id) }
             } else {
                 null
             },

clients/android/app/src/main/kotlin/io/unom/punktfunk/ConnectScreen.kt

@@ -100,7 +100,9 @@ fun ConnectScreen(
     // gamepad shell owns (the touch UI reaches Settings via the bottom bar and has no library button).
     gamepadUi: Boolean = false,
     onOpenSettings: () -> Unit = {},
-    onOpenLibrary: (KnownHost) -> Unit = {},
+    // (host, pinned profile id) — a pinned host+profile card opens ITS shelf, and the id is the
+    // one-off every launch off that shelf runs with (design §5.2a). Null = the host's own tile.
+    onOpenLibrary: (KnownHost, String?) -> Unit = { _, _ -> },
     navGate: Boolean = true, // false while the console home is cross-fading out
     // A `punktfunk://` URL to route (design/client-deep-links.md §3). This screen owns it because
     // it owns the connect path — trust decisions, the local-network grant, wake-and-retry — and a
@@ -772,7 +774,7 @@ fun ConnectScreen(
                 awaiting == null && editTarget == null && optionsTarget == null &&
                 speedTest == null && waker.waking == null && !lnpPrompt,
             onActivate = { it.activate() },
-            onOpenLibrary = { it.knownHost?.let(onOpenLibrary) },
+            onOpenLibrary = { tile -> tile.knownHost?.let { onOpenLibrary(it, tile.pinnedProfileId) } },
             onOpenSettings = onOpenSettings,
             onOptions = { tile ->
                 tile.knownHost?.let { kh ->

clients/android/app/src/main/kotlin/io/unom/punktfunk/GamepadHome.kt

@@ -86,8 +86,10 @@ class HomeTile(
     val knownHost: KnownHost? = null, // set for saved hosts → enables the library (Y)
     /**
      * Set when this tile is a PINNED host+profile combination rather than the host's own tile.
-     * A pin is a shortcut, not a second host: the host-level actions (wake, edit, forget, library)
-     * belong to the host's own tile, and this one offers only Unpin.
+     * A pin is a shortcut, not a second host: the host-level actions (wake, edit, forget) belong
+     * to the host's own tile, and this one offers only Unpin. The library is NOT one of those —
+     * it is a way to start this card (a connect with a title picked first), so a pinned tile opens
+     * its own shelf and every launch off it carries this profile.
      */
     val pinnedProfileId: String? = null,
     /**
@@ -101,9 +103,10 @@ class HomeTile(
     val profileAccent: Color? = null,
     val activate: () -> Unit,
 ) {
-    // Any SAVED host offers the library (matches Apple) — the fetch itself returns a clear "pair
-    // first" message if the host hasn't authorized this device for its management API.
-    val hasLibrary: Boolean get() = knownHost != null && pinnedProfileId == null
+    // Any SAVED host offers the library (matches Apple), pinned cards included — the fetch itself
+    // returns a clear "pair first" message if the host hasn't authorized this device for its
+    // management API.
+    val hasLibrary: Boolean get() = knownHost != null
 }
 
 /**

clients/android/app/src/main/kotlin/io/unom/punktfunk/LibraryScreen.kt

@@ -94,6 +94,13 @@ fun LibraryScreen(
     onLaunched: (ActiveSession) -> Unit,
     onBack: () -> Unit,
     navActive: Boolean = true,
+    /**
+     * The profile this shelf launches with, when it was opened from a PINNED host+profile card
+     * (design §5.2a) rather than the host's own tile: a one-off, exactly like the card's plain
+     * connect. Null = the host's tile, and the host's binding decides — the same rule
+     * [ProfileStore.resolveFor] applies to every other connect.
+     */
+    pinnedProfileId: String? = null,
 ) {
     val ink = LocalGamepadInk.current
     BackHandler(onBack = onBack)
@@ -104,6 +111,14 @@ fun LibraryScreen(
     var state by remember { mutableStateOf<LibState>(LibState.Loading) }
     // A launch (connect) in flight: shows an overlay + gates the pad so a second press can't dial twice.
     var launching by remember { mutableStateOf(false) }
+    // The profile every launch off this shelf runs with, resolved ONCE per shelf by the same rule
+    // the host-list connect uses: this card's pin as the one-off, else the host's binding, else the
+    // globals. Resolved here rather than per launch so a profile edited mid-browse cannot make two
+    // titles on one shelf stream differently.
+    val profile = remember(host.id, pinnedProfileId) {
+        ProfileStore(context).resolveFor(host, pinnedProfileId)
+    }
+    val streamSettings = remember(settings, profile) { settings.effectiveFor(profile) }
 
     LaunchedEffect(host.address, host.port, host.fpHex) {
         state = LibState.Loading
@@ -133,7 +148,16 @@ fun LibraryScreen(
         Box(Modifier.fillMaxSize().hazeSource(hazeState)) {
             GamepadAuroraBackground(Modifier.fillMaxSize())
             Column(Modifier.fillMaxSize().consoleSafeArea()) {
-                ConsoleHeader("${host.name} — Library")
+                // A pinned card's shelf says so, in the card's own `host · profile` shape: what a
+                // launch here will use is a property of the shelf, not something to remember from
+                // the tile two screens back.
+                ConsoleHeader(
+                    if (pinnedProfileId != null && profile != null) {
+                        "${host.name} · ${profile.name} — Library"
+                    } else {
+                        "${host.name} — Library"
+                    },
+                )
                 Box(Modifier.weight(1f).fillMaxWidth(), contentAlignment = Alignment.Center) {
                     when (val s = state) {
                         is LibState.Loading -> LoadingState()
@@ -145,7 +169,7 @@ fun LibraryScreen(
                                     // Dial the host over the same pinned mTLS trust, booting straight
                                     // into this title (the host resolves `launch` = its library id).
                                     val handle = connectToHost(
-                                        context, settings, s.identity,
+                                        context, streamSettings, s.identity,
                                         host.address, host.port, host.fpHex, launch = game.id,
                                     )
                                     launching = false
@@ -153,11 +177,14 @@ fun LibraryScreen(
                                         onLaunched(
                                             ActiveSession(
                                                 handle,
-                                                settings,
+                                                streamSettings,
                                                 host.clipboardSync,
+                                                profileName = profile?.name,
                                                 hostId = host.id,
-                                                // Where to come back to when this game exits.
+                                                // Where to come back to when this game exits —
+                                                // this shelf, pin and all, not the host's default one.
                                                 launchedFromLibrary = true,
+                                                libraryProfileId = pinnedProfileId,
                                             ),
                                         )
                                     }

clients/android/app/src/main/kotlin/io/unom/punktfunk/models/UiModels.kt

@@ -71,8 +71,24 @@ data class ActiveSession(
      * [io.unom.punktfunk.kit.SessionEndReason.GAME_EXITED] ending.
      */
     val launchedFromLibrary: Boolean = false,
+    /**
+     * Which of [hostId]'s shelves that library launch came off: the pinned host+profile card's
+     * profile id (design §5.2a), or null for the host's own tile. Carried purely so the return
+     * trip above lands back on the SAME shelf — a player who launched from a pinned card is still
+     * on that card when the game exits, and coming back to the host's default shelf would silently
+     * change what the next title streams with.
+     */
+    val libraryProfileId: String? = null,
 )
 
+/**
+ * The library shelf a finished game launch should return to: the saved host's id, and the pinned
+ * profile card it was opened from (null = the host's own tile). One value rather than two parallel
+ * ones, because a hostId that arrives without its profile is not "the same shelf" — it is the
+ * default one wearing the same name.
+ */
+data class LibraryReturn(val hostId: String, val profileId: String? = null)
+
 /** Trust state of a host, shown as a colored pill on its card. */
 enum class HostStatus(val label: String) {
     PAIRED("Paired"),

clients/android/app/src/test/kotlin/io/unom/punktfunk/HomeTilesTest.kt

@@ -4,7 +4,6 @@ import androidx.compose.ui.graphics.Color
 import io.unom.punktfunk.kit.discovery.DiscoveredHost
 import io.unom.punktfunk.kit.security.KnownHost
 import org.junit.Assert.assertEquals
-import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertNull
 import org.junit.Assert.assertTrue
@@ -177,9 +176,10 @@ class HomeTilesTest {
             assertTrue(it.paired)
             assertNotNull(it.knownHost)
         }
-        // Host tile → library (Y); pin tile → none, because a pin is a shortcut, not a second host.
+        // Both tiles reach the library (Y): a pin card opens its OWN shelf, whose launches carry
+        // the pinned profile — the library is a way to start a card, not a host-level action.
         assertTrue(result[0].hasLibrary)
-        assertFalse(result[1].hasLibrary)
+        assertTrue(result[1].hasLibrary)
     }
 
     /**

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

@@ -43,10 +43,12 @@ struct OutputReady {
 /// internal looper thread) push the codec ones; the feeder thread pushes `Au`. Each carries only
 /// owned/`Copy` data so the callback closures satisfy the `Send` bound and never touch the codec.
 enum DecodeEvent {
-    /// A received access unit from the feeder, ready to queue into the decoder. The `bool` is the
-    /// feeder's [`NativeClient::note_frame_index`] verdict — `true` when this AU revealed a forward
-    /// frame-index gap, so the loop arms the freeze gate (the feeder already fired the RFI request).
-    Au(Frame, bool),
+    /// A received access unit from the feeder, ready to queue into the decoder. The `u32` is the
+    /// feeder's [`NativeClient::note_frame_index`] verdict — the forward frame-index gap's WIDTH
+    /// (0 = none), so the loop arms the freeze gate with the same signal and pre-credits the
+    /// reassembler's later `frames_dropped` climb for the loss (the feeder already fired the RFI
+    /// request).
+    Au(Frame, u32),
     /// An input buffer slot freed (index) — we can queue an AU into it.
     InputAvailable(usize),
     /// A decoded frame is ready (buffer index + echoed pts + the callback-time `decoded` stamp).
@@ -603,7 +605,11 @@ fn feeder_loop(
                 // AU's first piece (or a whole delivery), so the RFI gap detector keeps
                 // counting AUs.
                 let au_first = frame.part.is_none_or(|p| p.first);
-                let gap = au_first && client.note_frame_index(frame.frame_index);
+                let gap = if au_first {
+                    client.note_frame_index(frame.frame_index)
+                } else {
+                    0
+                };
                 // Park the receipt stamp (keyed by the pts the codec echoes) whenever the `decode`
                 // 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.
@@ -691,9 +697,12 @@ fn dispatch_event(
     match ev {
         DecodeEvent::Au(f, gap) => {
             // A forward frame-index gap arms the freeze; park this AU's flags for the present side to
-            // fold `on_decoded` (keyed by the pts the codec will echo).
-            if gap {
-                gate.arm(Instant::now());
+            // fold `on_decoded` (keyed by the pts the codec will echo). Credited arm: the gap width
+            // pre-covers the reassembler's ~120 ms-later `frames_dropped` climb for the same loss,
+            // so a fast RFI anchor that heals in between isn't re-frozen by it (the double-arm
+            // race — see `ReanchorGate::arm_expecting_drops`).
+            if gap > 0 {
+                gate.arm_expecting_drops(Instant::now(), u64::from(gap));
             }
             // One entry per AU (parts share the pts): the completing delivery carries it.
             if f.complete {

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

@@ -222,8 +222,13 @@ pub(super) fn run_sync(
                     // recovers with a cheap clean P-frame instead of a full IDR. The same forward gap
                     // arms the freeze gate so the decoder's concealment is held off the screen until the
                     // recovery re-anchors. The frames_dropped keyframe path below stays the backstop.
-                    if client.note_frame_index(frame.frame_index) {
-                        gate.arm(Instant::now());
+                    // Credited arm: the gap width pre-covers the reassembler's ~120 ms-later
+                    // `frames_dropped` climb for the same loss, so a fast RFI anchor that heals in
+                    // between isn't re-frozen by it (the double-arm race — see
+                    // `ReanchorGate::arm_expecting_drops`).
+                    let gap = client.note_frame_index(frame.frame_index);
+                    if gap > 0 {
+                        gate.arm_expecting_drops(Instant::now(), u64::from(gap));
                     }
                     // Park this AU's re-anchor flags for the present side (keyed by the pts the codec
                     // echoes on the output buffer) — unconditional, unlike the HUD's `in_flight` map.

clients/android/native/src/session/connect.rs

@@ -9,7 +9,7 @@ use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
-use super::{hex32, jni_guard, parse_hex32, SessionHandle};
+use super::{hex32, jni_guard, lock_recover, parse_hex32, SessionHandle};
 
 /// Machine token of the most recent `nativeConnect`/`nativePair` failure, taken (and cleared)
 /// by `nativeTakeLastError` so Kotlin can render a cause-specific message instead of the old
@@ -41,7 +41,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeTakeLastErr
     env: JNIEnv<'local>,
     _this: JObject<'local>,
 ) -> jni::sys::jstring {
-    let token = std::mem::take(&mut *LAST_ERROR.lock().unwrap());
+    let token = std::mem::take(&mut *lock_recover(&LAST_ERROR));
     match env.new_string(token) {
         Ok(s) => s.into_raw(),
         Err(_) => JObject::null().into_raw(),

clients/android/native/src/session/mod.rs

@@ -45,6 +45,15 @@ pub(crate) fn jni_guard<T>(default: T, f: impl FnOnce() -> T) -> T {
     })
 }
 
+/// Poison-recovering lock for the JNI entry points that are NOT behind [`jni_guard`]: a
+/// `.lock().unwrap()` there turns a poisoned mutex into a panic across the `extern "system"`
+/// boundary — an abort of the whole app on Rust ≥ 1.81 (the panic-in-extern grep gate's class).
+/// The slots behind these mutexes are plane-thread handles and last-value caches; whatever a
+/// poisoned writer left is still valid to inspect or replace.
+pub(crate) fn lock_recover<T>(m: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+    m.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
 /// A live session behind the `jlong` handle: the connector + the decode thread it feeds.
 pub(crate) struct SessionHandle {
     // Read only by the android decode path (`nativeStartVideo` → `crate::decode`); on the host

clients/android/native/src/session/planes.rs

@@ -8,7 +8,7 @@ use jni::objects::JString;
 use jni::sys::{jboolean, jdoubleArray, jintArray, jlong, jsize, jstring};
 use jni::JNIEnv;
 
-use super::{jni_guard, SessionHandle};
+use super::{jni_guard, lock_recover, SessionHandle};
 
 /// `NativeBridge.nativeStartVideo(handle, surface, decoderName, lowLatencyMode, lowLatencyFeature,
 /// isTv, presentPriority, smoothBuffer)` — wrap the SurfaceView's `Surface` as an `ANativeWindow`
@@ -48,7 +48,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
         .filter(|s| !s.is_empty());
     // SAFETY: live handle per the nativeConnect/nativeClose contract.
     let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut guard = h.video.lock().unwrap();
+    let mut guard = lock_recover(&h.video);
     if guard.is_some() {
         return; // already streaming
     }
@@ -222,7 +222,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
-        if h.video.lock().unwrap().is_none() {
+        if lock_recover(&h.video).is_none() {
             return std::ptr::null_mut(); // not streaming → no stats
         }
         let snap = h
@@ -385,7 +385,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
     }
     // SAFETY: live handle per the nativeConnect/nativeClose contract.
     let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut guard = h.audio.lock().unwrap();
+    let mut guard = lock_recover(&h.audio);
     if guard.is_some() {
         return; // already playing
     }
@@ -434,7 +434,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
     }
     // SAFETY: live handle per the nativeConnect/nativeClose contract.
     let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut guard = h.mic.lock().unwrap();
+    let mut guard = lock_recover(&h.mic);
     if let Some(m) = guard.as_ref() {
         return m.session_id(); // already capturing — same stream, same session
     }
@@ -516,7 +516,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartPadAud
             speaker != 0,
         ) {
             Some(p) => {
-                *h.pad_audio.lock().unwrap() = Some(p);
+                *lock_recover(&h.pad_audio) = Some(p);
                 1
             }
             None => 0,
@@ -629,6 +629,6 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeMicActive(
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
-        jboolean::from(h.mic.lock().unwrap().is_some())
+        jboolean::from(lock_recover(&h.mic).is_some())
     })
 }

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -71,7 +71,7 @@ struct ContentView: View {
     /// drives the cancelable "Waiting for approval" prompt and the pin-as-paired on success.
     @State private var awaitingApproval: ApprovalRequest?
     @State private var speedTestTarget: StoredHost?
-    @State private var libraryTarget: StoredHost?
+    @State private var libraryTarget: LibraryTarget?
     /// Wakes a sleeping host and waits for it to come back online before connecting (drives the
     /// "Waking…" phase of the connect overlay). Available on every platform now that the iOS/tvOS
     /// multicast entitlement is granted (see PunktfunkConnection.wakeOnLANAvailable).
@@ -412,10 +412,10 @@ struct ContentView: View {
         // (like the sheets below) so it survives the streaming → home transition the disconnect
         // drives, and consumed here — the model hands the host over once and we clear it, so a
         // later manual dismiss of the library can't be undone by a stale value.
-        .onChange(of: model.returnToLibrary) { _, host in
-            guard let host else { return }
+        .onChange(of: model.returnToLibrary) { _, shelf in
+            guard let shelf else { return }
             model.returnToLibrary = nil
-            libraryTarget = host
+            libraryTarget = shelf
         }
         // On the outer Group so the sheet survives the trust-prompt → home transition
         // (the "Pair with PIN instead" path disconnects first — the host's accept loop
@@ -448,9 +448,9 @@ struct ContentView: View {
         // (the coverflow is a GeometryReader, ideal ≈ zero), so without a frame it collapses to a
         // tiny panel.
         #if os(macOS)
-        .sheet(item: $libraryTarget) { host in
+        .sheet(item: $libraryTarget) { shelf in
             NavigationStack {
-                LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
+                LibraryView(store: store, target: shelf, onLaunch: { launchTitle(shelf, $0) })
             }
             .frame(minWidth: 940, minHeight: 620)
         }
@@ -461,9 +461,9 @@ struct ContentView: View {
         // tile, `returnToLibrary`) keeps writing the same `libraryTarget` either way, and a
         // controller arriving or leaving mid-browse hands the open library to whichever
         // presentation the new mode owns.
-        .fullScreenCover(item: touchLibraryTarget) { host in
+        .fullScreenCover(item: touchLibraryTarget) { shelf in
             NavigationStack {
-                LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
+                LibraryView(store: store, target: shelf, onLaunch: { launchTitle(shelf, $0) })
             }
         }
         #endif
@@ -573,7 +573,7 @@ struct ContentView: View {
 
     /// The iOS library cover's item: `libraryTarget`, hidden while the gamepad shell presents
     /// the library in place (see the cover's comment).
-    private var touchLibraryTarget: Binding<StoredHost?> {
+    private var touchLibraryTarget: Binding<LibraryTarget?> {
         Binding(
             get: { gamepadUIActive ? nil : libraryTarget },
             set: { libraryTarget = $0 })
@@ -743,6 +743,25 @@ struct ContentView: View {
     /// library fetch rides the paired mTLS identity, so there is nothing to show before the host
     /// is saved (the notice says what to do instead).
     private func openLibrary(from link: DeepLink) {
+        // A `profile=` on a browse link picks the shelf, exactly as it picks the settings on a
+        // connect link — and refuses the same way (§10.6): an unknown or ambiguous reference must
+        // never quietly degrade to the host's binding, which is a different shelf wearing the same
+        // host's name.
+        var selection = ProfileSelection.inherit
+        if let reference = link.profile {
+            let (profile, resolution) = profiles.catalog.resolve(reference)
+            switch resolution {
+            case .found:
+                selection = .profile(profile?.id ?? "")
+            case .notFound:
+                deepLinkNotice = "No settings profile called “\(reference)” on this device."
+                return
+            case .ambiguous:
+                deepLinkNotice = "More than one settings profile is called “\(reference)”. "
+                    + "Rename one, or link to it by its id."
+                return
+            }
+        }
         switch link.resolveHost(in: store.hosts) {
         case .known(let host):
             guard !link.pinConflict(with: host) else {
@@ -755,7 +774,7 @@ struct ContentView: View {
                 deepLinkNotice = "Already streaming \(current). End that session first."
                 return
             }
-            libraryTarget = host
+            libraryTarget = LibraryTarget(host: host, profile: selection)
         case .unknown(let address, _, let name, _):
             deepLinkNotice = "\(name ?? address) isn't saved on this device yet. "
                 + "Add it with the + button first — a library can only be browsed on a saved host."
@@ -833,9 +852,9 @@ struct ContentView: View {
                     PairSheet(host: host) { fingerprint in handlePaired(host, fingerprint: fingerprint) }
                         .onExitCommand { pairingTarget = nil }
                 }
-                .fullScreenCover(item: $libraryTarget) { host in
+                .fullScreenCover(item: $libraryTarget) { shelf in
                     NavigationStack {
-                        LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
+                        LibraryView(store: store, target: shelf, onLaunch: { launchTitle(shelf, $0) })
                     }
                     .onExitCommand { libraryTarget = nil }
                 }
@@ -1234,6 +1253,10 @@ struct ContentView: View {
                 setting: PunktfunkConnection.GamepadType(
                     rawValue: UInt32(clamping: effective.gamepadType)) ?? .auto),
             launchID: launchID,
+            // Where a game exit returns to, when this connect launched a title: the shelf that
+            // title was picked on — the host's own, or the pinned card whose profile this connect
+            // is using. Ignored by the model unless there is a launchID.
+            shelf: LibraryTarget(host: host, profile: profile),
             allowTofu: allowTofu,
             requestAccess: requestAccess,
             onUnreachable: onUnreachable)
@@ -1289,9 +1312,13 @@ struct ContentView: View {
 
     /// Picked a title in the (experimental) library: dismiss the browser and start a session that
     /// asks the host to launch it.
-    private func launchTitle(_ host: StoredHost, _ id: String) {
+    /// A title picked on a library shelf: dial its host, booting straight into that title — with
+    /// the shelf's profile. A pinned card's shelf carries its card's profile as the one-off, so a
+    /// launch made there streams with the profile the card promises; the host's own shelf carries
+    /// `.inherit` and the binding decides, exactly as a plain card tap does.
+    private func launchTitle(_ shelf: LibraryTarget, _ id: String) {
         libraryTarget = nil
-        connect(host, launchID: id)
+        connect(shelf.host, launchID: id, profile: shelf.profile)
     }
 
     /// Tap a discovered host: save it (so the session has a stored identity and the trust pin

clients/apple/Sources/PunktfunkClient/Home/GamepadHomeView.swift

@@ -75,7 +75,7 @@ struct GamepadHomeView: View {
     @ObservedObject var store: HostStore
     @ObservedObject var model: SessionModel
     @ObservedObject var discovery: HostDiscovery
-    @Binding var libraryTarget: StoredHost?
+    @Binding var libraryTarget: LibraryTarget?
     /// The host awaiting a PIN ceremony, if any. Owned by ContentView (a connect attempt sets it,
     /// as does the trust card's "Pair with PIN instead"), presented here as a shell screen —
     /// PairSheet's `Form` is unreachable with a controller on iOS/macOS, which made pairing the
@@ -90,7 +90,7 @@ struct GamepadHomeView: View {
     let connectDiscovered: (DiscoveredHost) -> Void
     /// Launch a library title on a host — the in-place library layer's activate path (iOS; the
     /// cover/sheet presentations wire ContentView's `launchTitle` into LibraryView themselves).
-    let launchTitle: (StoredHost, String) -> Void
+    let launchTitle: (LibraryTarget, String) -> Void
     /// A console prompt (GamepadPromptView) is up over the home — it polls the same controller, so
     /// this screen must stand down for as long as it is. Same handoff contract as the connect
     /// takeover and the shell's own layers; without it the carousel keeps scrolling underneath the
@@ -263,7 +263,7 @@ struct GamepadHomeView: View {
         if let host = pairingTarget { return .pair(host) }
         if showSettings { return .settings }
         if showAddHost { return .addHost }
-        if let host = libraryTarget { return .library(host) }
+        if let shelf = libraryTarget { return .library(shelf) }
         return nil
     }
 
@@ -289,10 +289,10 @@ struct GamepadHomeView: View {
                     onPaired: { onPaired(host, $0) },
                     close: { if !transitioning { pairingTarget = nil } },
                     controllerActive: active)
-            case .library(let host):
+            case .library(let shelf):
                 GamepadLibraryScreen(
-                    store: store, host: host,
-                    onLaunch: { launchTitle(host, $0) },
+                    store: store, target: shelf,
+                    onLaunch: { launchTitle(shelf, $0) },
                     close: { if !transitioning { libraryTarget = nil } },
                     controllerActive: active)
             }
@@ -501,9 +501,10 @@ struct GamepadHomeView: View {
                     isPaired: host.pinnedSHA256 != nil,
                     isConnecting: connecting,
                     filled: true,
-                    // A pinned card is a shortcut, not a second host — Y (library) stays on the
-                    // host's own tile, where the host-level actions live.
-                    hasLibrary: profile == nil,
+                    // A pinned card reaches the library too, and gets its OWN shelf: browsing is
+                    // this card's connect with a title picked first, not a host-level action like
+                    // wake or forget.
+                    hasLibrary: true,
                     osChain: host.osChain,
                     canWake: autoWakeEnabled && PunktfunkConnection.wakeOnLANAvailable
                         && !online && !host.wakeMacs.isEmpty,
@@ -539,12 +540,14 @@ struct GamepadHomeView: View {
     }
 
     /// Only saved hosts have a library — matches the touch grid, where "Browse Library…" is a
-    /// `HostCardView`-only action never offered on `DiscoveredCardView`.
+    /// `HostCardView`-only action never offered on `DiscoveredCardView`. A pinned card opens its
+    /// own shelf: the selection already names which card Y was pressed on, and that card's profile
+    /// is what its launches run with.
     private func openLibraryForSelected() {
-        guard libraryEnabled, case .saved(let id, let profile) = selection, profile == nil,
+        guard libraryEnabled, case .saved(let id, let profileID) = selection,
               let host = store.hosts.first(where: { $0.id == id })
         else { return }
-        libraryTarget = host
+        libraryTarget = LibraryTarget(host: host, profile: ProfileSelection(profileID: profileID))
     }
 }
 

clients/apple/Sources/PunktfunkClient/Home/GamepadLibraryScreen.swift

@@ -12,24 +12,26 @@ import SwiftUI
 struct GamepadLibraryScreen: View {
     @Environment(\.gamepadInk) private var ink
     @ObservedObject var store: HostStore
-    let host: StoredHost
+    let target: LibraryTarget
     let onLaunch: (String) -> Void
     let close: () -> Void
     var controllerActive = true
 
     /// `.compact` in a landscape phone window — tighter chrome, like every gamepad screen.
     @Environment(\.verticalSizeClass) private var vSizeClass
+    /// Resolves a pinned shelf's profile name for the title.
+    @ObservedObject private var profiles = ProfileStore.shared
 
     private var compact: Bool { vSizeClass == .compact }
 
     var body: some View {
         LibraryView(
-            store: store, host: host, onLaunch: onLaunch,
+            store: store, target: target, onLaunch: onLaunch,
             onClose: close, controllerActive: controllerActive)
             .safeAreaInset(edge: .top, spacing: 0) {
                 // Leading, like every gamepad heading — no close chrome, B is the exit (the
                 // coverflow's, or LibraryView's own back-catcher before the coverflow exists).
-                Text("\(host.displayName) — Library")
+                Text("\(target.title(in: profiles)) — Library")
                     .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
                     .foregroundStyle(ink.fg)
                     .lineLimit(1)

clients/apple/Sources/PunktfunkClient/Home/GamepadShell.swift

@@ -22,14 +22,16 @@ enum GamepadScreen: Identifiable {
     case settings
     case addHost
     case pair(StoredHost)
-    case library(StoredHost)
+    case library(LibraryTarget)
 
     var id: String {
         switch self {
         case .settings: return "settings"
         case .addHost: return "addHost"
         case .pair(let host): return "pair-\(host.id.uuidString)"
-        case .library(let host): return "library-\(host.id.uuidString)"
+        // Keyed on the SHELF, not the host: a host and each of its pinned cards open different
+        // libraries, and sharing an id would let one stand in for another mid-transition.
+        case .library(let shelf): return "library-\(shelf.id)"
         }
     }
 

clients/apple/Sources/PunktfunkClient/Home/HomeView.swift

@@ -24,7 +24,7 @@ struct HomeView: View {
     @Binding var showAddHost: Bool
     @Binding var pairingTarget: StoredHost?
     @Binding var speedTestTarget: StoredHost?
-    @Binding var libraryTarget: StoredHost?
+    @Binding var libraryTarget: LibraryTarget?
     #if !os(macOS)
     @Binding var showSettings: Bool
     #endif
@@ -34,8 +34,9 @@ struct HomeView: View {
     let connectDiscovered: (DiscoveredHost) -> Void
     /// Pairing succeeded (tvOS PairSheet route) — pin + connect (ContentView guards staleness).
     let onPaired: (StoredHost, Data) -> Void
-    /// Picked a title in the (experimental) library — start a session that launches it.
-    let onLaunchTitle: (StoredHost, String) -> Void
+    /// Picked a title in the (experimental) library — start a session that launches it, with the
+    /// shelf's profile (a pinned card's own; the host's binding on its primary card).
+    let onLaunchTitle: (LibraryTarget, String) -> Void
     /// Explicit Wake-on-LAN of an offline host — fires the packet and waits for it to come online
     /// (the "Waking…" overlay), without connecting. Routed through ContentView's HostWaker.
     let wake: (StoredHost) -> Void
@@ -154,8 +155,8 @@ struct HomeView: View {
             .navigationDestination(item: $speedTestTarget) { host in
                 SpeedTestSheet(host: host)
             }
-            .navigationDestination(item: $libraryTarget) { host in
-                LibraryView(store: store, host: host, onLaunch: { onLaunchTitle(host, $0) })
+            .navigationDestination(item: $libraryTarget) { shelf in
+                LibraryView(store: store, target: shelf, onLaunch: { onLaunchTitle(shelf, $0) })
             }
             #endif
             #if !os(tvOS)
@@ -263,9 +264,13 @@ struct HomeView: View {
     }
 
     private func hostCard(_ host: StoredHost, pinned: StreamProfile?) -> some View {
-        let onBrowseLibrary: (() -> Void)? = libraryEnabled ? { libraryTarget = host } : nil
         // A pinned card connects with ITS profile; the primary card follows the binding.
         let selection: ProfileSelection = pinned.map { .profile($0.id) } ?? .inherit
+        // …and browsing is that same connect with a title picked first, so a pinned card opens its
+        // OWN shelf: every launch off it carries the card's profile rather than the host's binding.
+        let onBrowseLibrary: (() -> Void)? = libraryEnabled
+            ? { libraryTarget = LibraryTarget(host: host, profile: selection) }
+            : nil
         return HostCardView(
             host: host,
             isOnline: isOnline(host),

clients/apple/Sources/PunktfunkClient/Home/HostCards.swift

@@ -219,6 +219,13 @@ struct HostCardView: View {
             // the way to remove the shortcut itself. Unpinning touches neither the profile nor
             // the host's default binding.
             connectWithMenu(menu)
+            // Browsing IS a connect-shaped action — it is this card's connect with a title picked
+            // first — so a pinned card offers it and opens its own shelf, whose launches carry the
+            // pinned profile. (Pair / speed test / wake / forget stay on the host's card: those
+            // are about the machine, and a shortcut has no business claiming them.)
+            if let onBrowseLibrary {
+                Button("Browse Library…", action: onBrowseLibrary)
+            }
             if LinkClipboard.isAvailable {
                 Button("Copy Link") { menu.copyLink(pinned.id) }
             }

clients/apple/Sources/PunktfunkClient/Home/LibraryView.swift

@@ -6,11 +6,53 @@
 import PunktfunkKit
 import SwiftUI
 
+/// Which library shelf is open: a host, and — when it was opened from a PINNED host+profile card
+/// (design/client-settings-profiles.md §5.2a) — that card's profile, which every title launched off
+/// the shelf then runs with, exactly as the card's own tap would.
+///
+/// One value rather than a host plus a profile carried beside it: a host and its pinned cards are
+/// different cards on the grid, so "which library" is not answered by the host alone. That is also
+/// why `id` folds the profile in — a presentation keyed on the host would not re-present when you
+/// move between a host's own shelf and one of its pins.
+struct LibraryTarget: Identifiable, Hashable {
+    let host: StoredHost
+    /// `.inherit` from the host's own card (its binding decides, as it always has); `.profile` from
+    /// a pinned card. `.defaults` never reaches here — nothing opens a library "with the globals".
+    var profile: ProfileSelection = .inherit
+
+    var id: String {
+        switch profile {
+        case .inherit: host.id.uuidString
+        case .defaults: "\(host.id.uuidString)#defaults"
+        case .profile(let id): "\(host.id.uuidString)#\(id)"
+        }
+    }
+
+    /// The pinned profile's id, if this shelf belongs to a pinned card.
+    var pinnedProfileID: String? {
+        if case .profile(let id) = profile { return id }
+        return nil
+    }
+
+    /// What the screen calls itself: the host, and the profile when a pinned card opened it — the
+    /// same `host · profile` shape that card wears, so which shelf you are on is on screen rather
+    /// than remembered from the card you pressed. A pin whose profile has since been deleted
+    /// resolves as no profile everywhere else, and reads as the plain host here.
+    @MainActor func title(in catalog: ProfileStore) -> String {
+        guard let id = pinnedProfileID, let profile = catalog.profile(id: id) else {
+            return host.displayName
+        }
+        return "\(host.displayName) \u{b7} \(profile.name)"
+    }
+}
+
 struct LibraryView: View {
     @ObservedObject var store: HostStore
-    let host: StoredHost
+    /// The shelf being browsed — the host, plus the pinned profile when a pinned card opened it.
+    let target: LibraryTarget
     /// Tapping a title starts a session that asks the host to launch it (the library id is passed
-    /// through). `nil` ⇒ browse-only (cards aren't tappable).
+    /// through). `nil` ⇒ browse-only (cards aren't tappable). The PROFILE a launch runs with is the
+    /// caller's to apply: it holds `target` and connects with `target.profile`.
     var onLaunch: ((String) -> Void)? = nil
     /// How the gamepad shell (GamepadLibraryScreen) closes this screen; nil — every sheet/cover
     /// presentation — falls back to the environment dismiss.
@@ -20,6 +62,12 @@ struct LibraryView: View {
     /// default (their being up IS the launcher's gate).
     var controllerActive = true
     @Environment(\.dismiss) private var dismiss
+    /// Resolves a pinned shelf's profile NAME for the title (the target carries only its id).
+    @ObservedObject private var profiles = ProfileStore.shared
+
+    /// The host this shelf belongs to — every fetch, every poster URL and the launch itself address
+    /// it, and a pinned shelf is the same host seen through one of its cards.
+    private var host: StoredHost { target.host }
 
     @State private var games: [GameEntry] = []
     @State private var loading = false
@@ -50,7 +98,7 @@ struct LibraryView: View {
 
     var body: some View {
         content
-            .navigationTitle("\(host.displayName) — Library")
+            .navigationTitle("\(target.title(in: profiles)) — Library")
             #if os(iOS)
             .navigationBarTitleDisplayMode(.inline)
             #endif

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

@@ -70,9 +70,14 @@ final class SessionModel: ObservableObject {
     /// session ends depends on where it came FROM: a title launched out of the library belongs back
     /// in that library when its game exits, not on the host-selection screen.
     private var launchedTitleID: String?
-    /// Set when a session ended because its game exited and it began as a library launch: the host
-    /// whose library to reopen. The view layer consumes it and sets it back to nil.
-    @Published var returnToLibrary: StoredHost?
+    /// WHICH library shelf that title was launched from — a host's own, or one of its pinned
+    /// host+profile cards (§5.2a). The host alone would not answer it: a pinned card's shelf
+    /// launches with that card's profile, so returning to the host's default shelf would quietly
+    /// change what the next title streams with.
+    private var launchedShelf: LibraryTarget?
+    /// Set when a session ended because its game exited and it began as a library launch: the
+    /// shelf to reopen. The view layer consumes it and sets it back to nil.
+    @Published var returnToLibrary: LibraryTarget?
     /// The settings THIS session runs on — the globals with its profile overlaid, resolved once at
     /// connect (design/client-settings-profiles.md §4.2). Also mirrored into `SessionSettings` for
     /// the readers that live in PunktfunkKit and can't see this model.
@@ -275,6 +280,9 @@ final class SessionModel: ObservableObject {
     func connect(to host: StoredHost, effective: EffectiveSettings,
                  gamepad: PunktfunkConnection.GamepadType = .auto,
                  launchID: String? = nil,
+                 /// The library shelf `launchID` was picked on, so a game exit can return to it.
+                 /// Only meaningful alongside a `launchID`; nil for a plain desktop connect.
+                 shelf: LibraryTarget? = nil,
                  allowTofu: Bool = false,
                  autoTrust: Bool = false,
                  requestAccess: Bool = false,
@@ -283,6 +291,7 @@ final class SessionModel: ObservableObject {
         phase = .connecting
         activeHost = host
         launchedTitleID = launchID
+        launchedShelf = shelf
         errorMessage = nil
         settings = effective
         statsVerbosity = StatsVerbosity(rawValue: effective.statsVerbosity) ?? .normal
@@ -663,6 +672,7 @@ final class SessionModel: ObservableObject {
         activeHost = nil
         // Read by `sessionEnded` BEFORE it calls us, so clearing here can't rob it of the answer.
         launchedTitleID = nil
+        launchedShelf = nil
         phase = .idle
         fps = 0
         mbps = 0
@@ -692,13 +702,16 @@ final class SessionModel: ObservableObject {
         // a plain desktop session has no library to return to.
         let host = activeHost
         let cameFromLibrary = launchedTitleID != nil
+        // The shelf it came off — falling back to the host's own if a caller launched a title
+        // without naming one, which is what that launch effectively browsed.
+        let shelf = launchedShelf ?? activeHost.map { LibraryTarget(host: $0) }
         disconnect(deliberate: false) // host/network ended it — keep the linger for a reconnect
         switch reason {
         case .gameExited:
             // The player quit their own game. Not a failure, and they are probably after the next
             // title — so no banner, and back to the library it came from.
-            if cameFromLibrary, let host {
-                returnToLibrary = host
+            if cameFromLibrary, host != nil, let shelf {
+                returnToLibrary = shelf
             }
         case .hostEnded, .local:
             // Someone asked for this: an operator "End" on the host, or our own close racing in.

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

@@ -774,12 +774,22 @@ public final class PunktfunkConnection {
     /// `noteFrameIndex` (the throttled RFI request); call it for every received AU. Returns false
     /// after close.
     public func noteFrameIndexGap(_ frameIndex: UInt32) -> Bool {
+        noteFrameIndexGapWidth(frameIndex) > 0
+    }
+
+    /// Like `noteFrameIndexGap`, but reports the gap's WIDTH — how many frames this arrival revealed
+    /// as missing (0 = none). The post-loss re-anchor gate arms with the width
+    /// (`ReanchorGate.arm(expectingDrops:)`) so the reassembler's later `framesDropped` climb for
+    /// the SAME loss cannot re-freeze a stream an RFI anchor already healed (the double-arm race).
+    /// Same core side effect as `noteFrameIndex` (the throttled RFI request); call it for every
+    /// received AU. Returns 0 after close.
+    public func noteFrameIndexGapWidth(_ frameIndex: UInt32) -> UInt32 {
         abiLock.lock()
         defer { abiLock.unlock() }
-        guard let h = handle, !closeRequested else { return false }
-        var gap = false
-        _ = punktfunk_connection_note_frame_index(h, frameIndex, &gap)
-        return gap
+        guard let h = handle, !closeRequested else { return 0 }
+        var width: UInt32 = 0
+        _ = punktfunk_connection_note_frame_index_ex(h, frameIndex, &width)
+        return width
     }
 
     /// Cumulative access units the host→client reassembler dropped as unrecoverable (FEC couldn't

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

@@ -55,6 +55,16 @@ final class ReanchorGate: @unchecked Sendable {
         lock.unlock()
     }
 
+    /// `arm()` for a loss detected as a frame-index gap of a known width
+    /// (`PunktfunkConnection.noteFrameIndexGapWidth`). Pre-credits the reassembler's later
+    /// `framesDropped` climb for the same lost frames, so `poll` doesn't re-freeze a stream an
+    /// RFI anchor already healed (the double-arm race — the Rust gate's docs tell the story).
+    func arm(expectingDrops: UInt64) {
+        lock.lock()
+        punktfunk_reanchor_gate_arm_expecting_drops(ptr, expectingDrops)
+        lock.unlock()
+    }
+
     /// Fold one decoded frame. `flags` is the AU's wire `user_flags`. Returns true to PRESENT the
     /// frame, false to WITHHOLD it as a post-loss concealment (hold the last good picture). Pass
     /// `decoderKeyframe: false` — VideoToolbox doesn't flag IDRs, so the wire `FLAG_SOF` covers it.

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

@@ -57,6 +57,8 @@ let presentDebug = ProcessInfo.processInfo.environment["PUNKTFUNK_PRESENT_DEBUG"
 /// to Console.app wirelessly with no env var / Xcode attach. Always on for deadline pacing (the
 /// stats are a few arrays + one log line per second); other pacings keep the env-gated print.
 private let presentLog = Logger(subsystem: "io.unom.punktfunk", category: "present")
+/// Pump-side events (loss recovery, format seeding) — the stage-2 sibling of StreamPump's log.
+private let pumpLog = Logger(subsystem: "io.unom.punktfunk", category: "pump")
 
 /// Decoded-frame hand-off between the decode half and the render thread. The POLICY is the
 /// user's presentation intent (design/apple-presentation-rebuild.md — the 2026-07 rebuild that
@@ -921,7 +923,11 @@ public final class Stage2Pipeline {
                     // recovery above stays the backstop for when the recovery frame itself is lost.
                     // The same gap is the earliest, most precise signal to ARM the display freeze —
                     // the following concealed frames are withheld until a clean re-anchor.
-                    if connection.noteFrameIndexGap(au.frameIndex) { reanchorGate.arm() }
+                    // Credited arm: the gap width pre-covers the reassembler's ~120 ms-later
+                    // framesDropped climb for the same loss, so a fast RFI anchor that heals in
+                    // between isn't re-frozen by it (the double-arm race).
+                    let gapWidth = connection.noteFrameIndexGapWidth(au.frameIndex)
+                    if gapWidth > 0 { reanchorGate.arm(expectingDrops: UInt64(gapWidth)) }
                     onFrame?(au)
                     if let f = connection.videoCodec.formatDescription(fromKeyframe: au.data) {
                         format = f          // refreshed on every IDR (mode changes included)
@@ -932,6 +938,21 @@ public final class Stage2Pipeline {
                         }
                         awaitingIDR = false // a fresh IDR re-anchored decode — recovery complete
                     }
+                    if format == nil {
+                        // No decodable format yet: the opening IDR's parameter sets never
+                        // arrived (or never parsed), and under the host's infinite GOP nothing
+                        // re-delivers them unless we ASK. Without this the guard below drops
+                        // every AU silently, forever — the field "black stream, zero recovery
+                        // requests" state (2026-08-12): the host streams perfectly, the client
+                        // shows nothing and says nothing. awaitingIDR routes through the same
+                        // 100 ms-throttled recovery.request() at the top of the loop.
+                        if !awaitingIDR {
+                            pumpLog.warning(
+                                "video: received AUs but no decodable format (missing/unparsed parameter sets) — requesting an IDR until one seeds it"
+                            )
+                        }
+                        awaitingIDR = true
+                    }
                     guard let f = format, !token.isStopped else { return true }
                     if decoder.decode(au: au, format: f) {
                         decodeFailRun = 0

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

@@ -100,7 +100,11 @@ final class StreamPump {
                     // with a cheap clean P-frame instead of a full IDR. The framesDropped-driven
                     // recovery above stays the backstop for when the recovery frame itself is lost.
                     // The same gap is the earliest, most precise signal to ARM the display freeze.
-                    if connection.noteFrameIndexGap(au.frameIndex) { gate.arm() }
+                    // Credited arm: the gap width pre-covers the reassembler's ~120 ms-later
+                    // framesDropped climb for the same loss, so a fast RFI anchor that heals in
+                    // between isn't re-frozen by it (the double-arm race).
+                    let gapWidth = connection.noteFrameIndexGapWidth(au.frameIndex)
+                    if gapWidth > 0 { gate.arm(expectingDrops: UInt64(gapWidth)) }
                     onFrame?(au)
                     let idrFormat = connection.videoCodec.formatDescription(fromKeyframe: au.data)
                     if let f = idrFormat {
@@ -116,6 +120,21 @@ final class StreamPump {
                         }
                         awaitingIDR = false // a fresh IDR re-anchored decode — recovery complete
                     }
+                    if format == nil {
+                        // No decodable format yet: the opening IDR's parameter sets never
+                        // arrived (or never parsed), and under the host's infinite GOP nothing
+                        // re-delivers them unless we ASK. Without this the format guard below
+                        // drops every AU silently, forever — the field "black stream, zero
+                        // recovery requests" state (2026-08-12). awaitingIDR routes through the
+                        // same 100 ms-throttled recovery.request() at the top of the loop.
+                        if !awaitingIDR {
+                            awaitingSince = Date()
+                            pumpLog.warning(
+                                "video: received AUs but no decodable format (missing/unparsed parameter sets) — requesting an IDR until one seeds it"
+                            )
+                        }
+                        awaitingIDR = true
+                    }
                     let failed = layer.status == .failed
                     if failed {
                         // Decode wedged hard (the cold-first-connect case — a lost/corrupt opening

clients/apple/Sources/PunktfunkShared/EffectiveSettings.swift

@@ -229,7 +229,7 @@ public struct EffectiveSettings: Equatable, Sendable {
 /// through to the binding. Collapsing the two would make the menu item that says "Default
 /// settings" silently connect with the host's profile. It is the same distinction the session
 /// binary's `--profile ""` reserves on the desktop clients.
-public enum ProfileSelection: Equatable, Sendable {
+public enum ProfileSelection: Hashable, Sendable {
     /// No pick — the host's default binding applies (a plain click/tap).
     case inherit
     /// Force the global defaults for this one connect, whatever the host is bound to.

clients/linux/src/ui_hosts.rs

@@ -466,6 +466,13 @@ impl relm4::factory::FactoryComponent for HostCard {
                     // offering them here would blur what the card is.
                     let launch = gio::Menu::new();
                     launch.append(Some("Connect"), Some("card.connect"));
+                    // …and the same stream with a title picked first. The library is a way to
+                    // START this card, not a property of the host, so it belongs to a shortcut
+                    // as much as Connect does — and the card's request carries its profile, so
+                    // what launches from that grid is this card's profile, not the binding.
+                    if *library_enabled {
+                        launch.append(Some("Browse library\u{2026}"), Some("card.library"));
+                    }
                     menu.append_section(None, &launch);
 
                     let links = gio::Menu::new();

clients/linux/src/ui_library.rs

@@ -44,6 +44,26 @@ struct State {
     mock: Cell<bool>,
 }
 
+/// What the page calls the host it is browsing. A request that carries a one-off profile
+/// came from a PINNED card (design §5.2a), and every title launched off this grid inherits
+/// it — so the page names it, the same `host · profile` shape the card wears. A plain card
+/// says nothing extra: its binding is the host's own default, not a second thing to read.
+/// A one-off whose profile has since been deleted resolves as no profile everywhere else,
+/// and reads as a plain host here.
+fn page_host_label(req: &ConnectRequest) -> String {
+    let Some(id) = req.profile.as_deref().filter(|id| !id.is_empty()) else {
+        return req.name.clone();
+    };
+    pf_client_core::profiles::ProfilesFile::load()
+        .profiles
+        .into_iter()
+        .find(|p| p.id == id)
+        .map_or_else(
+            || req.name.clone(),
+            |p| format!("{} \u{b7} {}", req.name, p.name),
+        )
+}
+
 /// Open the library page for a saved host and start the fetch. `mgmt_port` comes from
 /// the live mDNS `mgmt` TXT when the host is advertising (the hosts page resolves it).
 pub fn open(
@@ -194,7 +214,7 @@ fn build(
     toolbar.set_content(Some(&stack));
 
     let page = adw::NavigationPage::builder()
-        .title(format!("{} — Library", req.name))
+        .title(format!("{} — Library", page_host_label(&req)))
         .child(&toolbar)
         .build();
 

clients/windows/src/app/hosts.rs

@@ -913,9 +913,13 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
 
             // …then this host's pinned host+profile tiles, in the order they were pinned
             // (design §5.2a). They share the host's live status because they read the same
-            // record, and a pin whose profile is gone simply doesn't render. No menu of their
-            // own: a pinned tile is a shortcut, not a second host, and pin/unpin already live
-            // on the primary tile's menu — the one place you decide it.
+            // record, and a pin whose profile is gone simply doesn't render. Their menu is
+            // deliberately short: a pinned tile is a shortcut, not a second host, so it carries
+            // only what STARTS it (the library — this tile's connect with a title picked first,
+            // which is why the grid it opens launches with the tile's profile), the link that
+            // reproduces it, and the way to remove it. Everything that configures the machine —
+            // pair, speed test, wake, edit, forget, and pinning itself — stays on the primary
+            // tile's menu, the one place you decide it.
             for id in &k.pinned_profiles {
                 let Some((id, name, accent)) = profiles.iter().find(|(pid, ..)| pid == id) else {
                     continue;
@@ -923,6 +927,67 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                 let (ctx3, ss3, st3) = (ctx.clone(), set_screen.clone(), set_status.clone());
                 let mut pinned_target = pinned_base.clone();
                 pinned_target.profile = Some(id.clone());
+                let pinned_menu = {
+                    let (svc, target) = (props.svc.clone(), pinned_target.clone());
+                    let (fp, pin_id) = (k.fp_hex.clone(), id.clone());
+                    let (hosts_rev, set_hosts_rev) = (props.hosts_rev, props.set_hosts_rev.clone());
+                    let link_host = k.clone();
+                    let link_profile = id.clone();
+                    let unpin_label = format!("{MENU_UNPIN}{name}");
+                    let unpin_item = unpin_label.clone();
+                    button("")
+                        .icon(Symbol::More)
+                        .subtle()
+                        .tooltip("More options")
+                        .automation_name("More options")
+                        .menu_flyout({
+                            let mut items = Vec::new();
+                            // Same gate as the primary tile's: the mgmt API needs the paired
+                            // identity, and the page is behind the experimental toggle.
+                            if library_enabled && k.paired {
+                                items.push(menu_item(MENU_LIBRARY));
+                            }
+                            items.push(menu_item(MENU_COPY_LINK));
+                            items.push(menu_separator());
+                            items.push(menu_item(unpin_label));
+                            items
+                        })
+                        .on_item_clicked(move |item: String| match item.as_str() {
+                            MENU_LIBRARY => {
+                                // The shared target IS what the library page launches through, so
+                                // parking THIS tile's target here is what makes its grid launch
+                                // with the pinned profile.
+                                *svc.ctx.shared.target.lock().unwrap() = target.clone();
+                                super::library::start_fetch(&svc.ctx, &svc.set_library);
+                                svc.set_screen.call(Screen::Library);
+                            }
+                            MENU_COPY_LINK => {
+                                let url = pf_client_core::deeplink::DeepLink::for_host(
+                                    &link_host,
+                                    None,
+                                    Some(link_profile.as_str()),
+                                )
+                                .to_url();
+                                pf_client_core::clipboard::set_text(&url);
+                            }
+                            other if other == unpin_item => {
+                                tracing::info!(pin = %pin_id, host = %fp, on = false, "pin toggle");
+                                let mut known = KnownHosts::load();
+                                if let Some(h) = known.hosts.iter_mut().find(|h| h.fp_hex == fp) {
+                                    h.pinned_profiles.retain(|x| x != &pin_id);
+                                    if let Err(e) = known.save() {
+                                        tracing::warn!(
+                                            error = %format!("{e:#}"), "saving a pin"
+                                        );
+                                    }
+                                }
+                                // Same reason as the primary tile's toggle: nothing the page reads
+                                // as state changed, so the bump is what makes this tile vanish NOW.
+                                set_hosts_rev.call(hosts_rev + 1);
+                            }
+                            _ => {}
+                        })
+                };
                 tiles.push(host_tile(
                     // Its own hover key: two tiles for one host must not light up together.
                     &format!("{}#{id}", k.fp_hex),
@@ -935,7 +1000,7 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                         (!k.paired).then_some(("Trusted", Pill::Info)),
                         Some((name.as_str(), accent.clone())),
                     ),
-                    None,
+                    Some(pinned_menu),
                     Some(Box::new(move || {
                         if can_wake {
                             initiate_waking(&ctx3, pinned_target.clone(), &ss3, &st3);

clients/windows/src/deeplink.rs

@@ -176,7 +176,13 @@ unsafe extern "system" fn wnd_proc(
             let slice = unsafe { std::slice::from_raw_parts(cds.lpData as *const u16, len) };
             let url = String::from_utf16_lossy(slice);
             tracing::debug!(%url, "link from another instance");
-            INBOX.lock().unwrap().push(url);
+            // Poison-recover, never unwrap: a panic out of a window procedure is an abort since
+            // Rust 1.81, and the inbox is a plain Vec that stays valid whatever a poisoned
+            // writer left behind.
+            INBOX
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .push(url);
             return LRESULT(1);
         }
     }

clients/windows/src/main.rs

@@ -15,7 +15,6 @@
 //!                    (measure the path: probe burst → goodput / loss / recommended bitrate)
 
 // Unsafe-proof program: every `unsafe {}` in this client carries a `// SAFETY:` proof.
-#![deny(clippy::undocumented_unsafe_blocks)]
 // Link as a GUI (windows) subsystem binary so the default windowed launch (MSIX / double-click)
 // does NOT pop a console window. The CLI paths (--headless/--discover) reattach to the launching
 // terminal's console at startup (see main), so their output is still visible when run from a shell.

crates/libvpl-sys/src/lib.rs

@@ -10,6 +10,11 @@
 #![allow(non_snake_case)]
 // Bindgen output for a C API: u128 layout warnings and the like are upstream's concern.
 #![allow(improper_ctypes)]
+// The workspace-wide undocumented_unsafe_blocks deny cannot apply to GENERATED code: bindgen
+// emits `unsafe {}` in layout tests/accessors and nobody hand-writes proofs into OUT_DIR. This
+// crate is bindings-only by charter (the safe wrapper lives with the consumer), so the allow is
+// crate-wide; the hand-written link-sanity test below still carries its proof by convention.
+#![allow(clippy::undocumented_unsafe_blocks)]
 // Generated code — clippy findings in it (missing safety docs on generated unsafe fns, style
 // nits across 14k lines) are bindgen's shape, not ours; the safe wrapper in pf-encode is the
 // linted surface.
@@ -27,6 +32,8 @@ mod tests {
     /// implementations — that's fine, MFXLoad itself must still succeed).
     #[test]
     fn dispatcher_links_and_loads() {
+        // SAFETY: MFXLoad allocates the dispatcher's loader context (documented to work with no
+        // driver present) and MFXUnload frees that same non-null handle; nothing else is touched.
         unsafe {
             let loader = MFXLoad();
             assert!(!loader.is_null(), "MFXLoad returned NULL");

crates/pf-capture/src/lib.rs

@@ -7,13 +7,6 @@
 //! [`FrameChannelSender`] closure, so this crate reaches neither the encoder nor the host
 //! orchestrator).
 
-// Every unsafe block in this crate carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-// …and that program only covers a whole `unsafe fn` body once the body needs its own block: in
-// edition 2021 `unsafe_op_in_unsafe_fn` is allow-by-default, which exempted the crate's hardest FFI
-// (the ring/slot construction, the channel broker, every D3D converter ctor) from the deny above.
-#![deny(unsafe_op_in_unsafe_fn)]
-
 use anyhow::Result;
 use pf_frame::{CapturedFrame, FramePayload, PixelFormat};
 // The Linux capturer reaches `DmabufFrame` through `super::`; `CursorOverlay` it names directly as
@@ -43,6 +36,21 @@ pub trait Capturer: Send {
         self.next_frame()
     }
 
+    /// [`next_frame_within`](Self::next_frame_within), but the caller declares the budget
+    /// PROVISIONAL: its expiry is the retry schedule firing (the deliberately truncated first
+    /// attempt), not a verdict on anything this capture offered. The portal backend must NOT
+    /// latch its sticky process-wide downgrades (HDR capture, either dmabuf-only offer) from a
+    /// provisional expiry — a gamescope cold start routinely outlives the short window while it
+    /// would have accepted every offer, and one latched race used to pin the whole host process
+    /// to SDR/CPU capture. The full-length attempt that follows delivers the honest verdict.
+    /// Backends that latch nothing from a timeout just delegate.
+    fn next_frame_within_provisional(
+        &mut self,
+        budget: std::time::Duration,
+    ) -> Result<CapturedFrame> {
+        self.next_frame_within(budget)
+    }
+
     /// Non-blocking: the freshest frame available since the last call, or `None` if none has
     /// arrived (the caller reuses its last frame to hold a steady output rate). The default
     /// just produces a frame each call — fine for instant synthetic sources; the portal

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

@@ -1,4 +1,4 @@
-//! Live capture: xdg ScreenCast portal (`ashpd`) → PipeWire (`pipewire`), CPU-copy path.
+//! Live capture: xdg ScreenCast portal (`ashpd`) → PipeWire (`pipewire`).
 //!
 //! Two dedicated threads, because both stacks are tied to their thread:
 //!   * **portal thread** drives the async ashpd handshake on a multi-thread tokio runtime
@@ -7,9 +7,13 @@
 //!     drops; ashpd's `Session` has no `Drop`);
 //!   * **pipewire thread** owns the (`!Send`) MainLoop/Stream and pumps frames.
 //!
-//! The portal hands the PipeWire remote fd + node id to the pipewire thread; decoded BGRx
-//! frames leave the pipewire thread over a bounded channel. The authoritative frame size
-//! comes from the negotiated PipeWire format, not the portal's size hint.
+//! The portal hands the PipeWire remote fd + node id to the pipewire thread; frames leave that
+//! thread through a ONE-DEEP OVERWRITING slot (`FrameSlot`) plus a wakeup edge — not the bounded
+//! `sync_channel(8)` this once used, which was drop-NEWEST and so handed a stalled consumer stale
+//! frames (see `FrameSlot`'s own note). The payload is not necessarily BGRx either: the negotiation
+//! can settle on packed RGB, NV12, YUV444 or 10-bit PQ, and on a dmabuf passthrough it never touches
+//! the CPU. The authoritative frame size comes from the negotiated PipeWire format, not the portal's
+//! size hint.
 //!
 //! Cleanup: BOTH threads are stopped deterministically — [`PortalCapturer`]'s `Drop` sends a
 //! pipewire `channel` quit and joins that thread (releasing its EGL importer / CUDA context
@@ -18,8 +22,9 @@
 //! connection and so ENDS the compositor's ScreenCast session. Dropping a capturer (session end,
 //! or a retried/failed pipeline build) therefore leaves nothing behind on either side.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
+// Every `unsafe` block in this module TREE carries a `// SAFETY:` proof; enforce it (unsafe-proof
+// program). This file itself has none — the FFI lives in the child modules declared at the bottom
+// (`pipewire`, `pw_cursor`, `pw_pods`, `portal`, `xfixes_cursor`), which this inner attribute covers.
 
 use super::{CapturedFrame, Capturer, DmabufFrame, FramePayload, PixelFormat, ZeroCopyPolicy};
 use anyhow::{anyhow, Context, Result};
@@ -173,8 +178,9 @@ pub struct PortalCapturer {
     /// capture, not per frame.
     negotiation_confirmed: bool,
     /// This capture ran the HDR (10-bit PQ/BT.2020 dmabuf) offer — see [`Self::open`]'s
-    /// `want_hdr`. Read by the negotiation-timeout diagnosis (a failed HDR offer latches the
-    /// process-wide SDR downgrade) and by [`hdr_meta`](Capturer::hdr_meta).
+    /// `want_hdr`. Read by the negotiation-timeout diagnosis (a failed HDR offer latches the SDR
+    /// downgrade for THIS [`Self::hdr_source`] only, not process-wide) and by
+    /// [`hdr_meta`](Capturer::hdr_meta).
     hdr_offer: bool,
     /// Which HDR source this capturer is — the latch a failed [`hdr_offer`](Self::hdr_offer)
     /// belongs to. See [`super::HdrSource`] for why the latch is not one process-wide flag.
@@ -463,7 +469,10 @@ fn spawn_pipewire(
     let zerocopy = allow_zerocopy && pf_zerocopy::enabled();
     // HDR cannot ride the SHM path (see `want_hdr` above): under PUNKTFUNK_FORCE_SHM the HDR
     // offer is dropped — SDR capture, loudly.
-    let force_shm = std::env::var("PUNKTFUNK_FORCE_SHM").as_deref() == Ok("1");
+    // The shared parser, not a bare `== "1"` compare — matching `PUNKTFUNK_PIPEWIRE_NV12` below.
+    // A bare compare silently ignored `PUNKTFUNK_FORCE_SHM=true`/`=on`/`=yes`, so the knob looked
+    // set and did nothing.
+    let force_shm = pf_host_config::env_on("PUNKTFUNK_FORCE_SHM").unwrap_or(false);
     let want_hdr = if want_hdr && force_shm {
         tracing::warn!(
             "HDR capture requested but PUNKTFUNK_FORCE_SHM=1 — the SHM path is 8-bit only; \
@@ -533,7 +542,7 @@ fn spawn_pipewire(
 
 impl Capturer for PortalCapturer {
     fn next_frame(&mut self) -> Result<CapturedFrame> {
-        self.frame_within(Duration::from_secs(10))
+        self.frame_within(Duration::from_secs(10), TimeoutVerdict::Conclusive)
     }
 
     fn cursor(&mut self) -> Option<pf_frame::CursorOverlay> {
@@ -555,6 +564,14 @@ impl Capturer for PortalCapturer {
         // every nested Xwayland the provider reports, RE-RUNS the provider so a game's Xwayland
         // that appears later is adopted, and follows whichever one gamescope draws the pointer on.
         // `frame_size` lets it map root-space coordinates into frame space.
+        //
+        // Idempotent by construction. The contract says "called once", but nothing enforced it, and a
+        // second call evaluated `spawn` BEFORE dropping the old source: two readers then published
+        // into the same slot for the construction window, and a `spawn` that returned `None` destroyed
+        // a perfectly good reader outright.
+        if self._gs_cursor.is_some() {
+            return;
+        }
         self._gs_cursor = xfixes_cursor::XFixesCursorSource::spawn(
             targets,
             Arc::clone(&self.signals.cursor_live),
@@ -563,7 +580,13 @@ impl Capturer for PortalCapturer {
     }
 
     fn next_frame_within(&mut self, budget: Duration) -> Result<CapturedFrame> {
-        self.frame_within(budget)
+        self.frame_within(budget, TimeoutVerdict::Conclusive)
+    }
+
+    fn next_frame_within_provisional(&mut self, budget: Duration) -> Result<CapturedFrame> {
+        // The retry loop's truncated first attempt: its expiry re-runs the schedule, it does not
+        // convict an offer — see `TimeoutVerdict` and the latch arms in `next_frame_timed_out`.
+        self.frame_within(budget, TimeoutVerdict::Provisional)
     }
 
     fn supports_arrival_wait(&self) -> bool {
@@ -655,6 +678,11 @@ impl Capturer for PortalCapturer {
             if let Ok(mut slot) = self.slot.lock() {
                 *slot = None;
             }
+            // Clear the stall clock for the same reason the mailbox is flushed: a pooled capturer
+            // whose previous stream ended mid-stall carried that `Instant` into the next one, so the
+            // first `try_latest` that saw `!streaming` found the 1500 ms grace already expired and
+            // reported capture loss on a stream that had been running for microseconds.
+            self.stall_since = None;
         }
     }
 
@@ -699,12 +727,73 @@ impl Capturer for PortalCapturer {
     }
 }
 
+/// Whether an expired first-frame budget is allowed to CONVICT an offer. The retry loop's
+/// deliberately truncated first attempt passes `Provisional`: its expiry means the schedule
+/// moved on, not that the compositor refused anything — a gamescope cold start regularly needs
+/// longer than that window to accept every offer it would have accepted. Latching from it pinned
+/// the whole host process to SDR + CPU capture off a race the attempt lost by design; only a
+/// full-length wait carries a verdict.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TimeoutVerdict {
+    Conclusive,
+    Provisional,
+}
+
+/// Which offer a first-frame timeout implicates — the diagnosis behind
+/// [`PortalCapturer::next_frame_timed_out`], split out pure so the latch policy is testable.
+/// Mirrors the negotiation state exactly: a negotiated format clears every offer (the compositor
+/// accepted, it just produced nothing), and a forced `PUNKTFUNK_ZEROCOPY=1` keeps both dmabuf
+/// arms erroring loudly instead of implicating them (the operator asked for exactly that path).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TimeoutOffer {
+    /// Format negotiated; no offer implicated — the compositor produced no buffers.
+    NoBuffers,
+    /// The 10-bit PQ/BT.2020 (HDR) dmabuf offer was never accepted.
+    Hdr,
+    /// The dmabuf-only raw-passthrough offer was never accepted.
+    RawDmabuf,
+    /// The dmabuf-only EGL→CUDA offer was never accepted.
+    GpuDmabuf,
+    /// Nothing negotiated and no offer implicated — format/modifier mismatch.
+    NoFormat,
+}
+
+fn classify_first_frame_timeout(
+    negotiated: bool,
+    hdr_offer: bool,
+    vaapi_dmabuf: bool,
+    gpu_dmabuf_offer: bool,
+    zerocopy_forced: bool,
+) -> TimeoutOffer {
+    if negotiated {
+        TimeoutOffer::NoBuffers
+    } else if hdr_offer {
+        TimeoutOffer::Hdr
+    } else if vaapi_dmabuf && !zerocopy_forced {
+        TimeoutOffer::RawDmabuf
+    } else if gpu_dmabuf_offer && !zerocopy_forced {
+        TimeoutOffer::GpuDmabuf
+    } else {
+        TimeoutOffer::NoFormat
+    }
+}
+
+/// The latch policy: only a conclusive expiry of an offer-implicating timeout fires the offer's
+/// sticky process-wide downgrade.
+fn timeout_convicts(offer: TimeoutOffer, verdict: TimeoutVerdict) -> bool {
+    verdict == TimeoutVerdict::Conclusive
+        && matches!(
+            offer,
+            TimeoutOffer::Hdr | TimeoutOffer::RawDmabuf | TimeoutOffer::GpuDmabuf
+        )
+}
+
 impl PortalCapturer {
     /// The blocking first-frame wait behind [`Capturer::next_frame`] /
     /// [`Capturer::next_frame_within`]. First frame can lag behind format negotiation; later
     /// frames arrive at ~fps. Wait in short slices so a GPU-import poison (worker death) fails
     /// the capture within ~0.5 s instead of sitting out the full first-frame budget.
-    fn frame_within(&mut self, budget: Duration) -> Result<CapturedFrame> {
+    fn frame_within(&mut self, budget: Duration, verdict: TimeoutVerdict) -> Result<CapturedFrame> {
         let deadline = std::time::Instant::now() + budget;
         loop {
             if self.signals.broken.load(Ordering::Relaxed) {
@@ -730,7 +819,7 @@ impl PortalCapturer {
                     if let Some(f) = self.take_frame() {
                         return Ok(f);
                     }
-                    return self.next_frame_timed_out(e, budget);
+                    return self.next_frame_timed_out(e, budget, verdict);
                 }
             }
         }
@@ -752,83 +841,118 @@ impl PortalCapturer {
     }
 
     /// The [`frame_within`](Self::frame_within) budget expired (or the thread ended) — turn it
-    /// into the diagnosis-bearing error. Split out of the slicing loop above; behavior unchanged.
+    /// into the diagnosis-bearing error, and fire the offer's sticky downgrade latch when — and
+    /// only when — the expiry convicts the offer (see [`timeout_convicts`]).
     fn next_frame_timed_out(
         &self,
         err: RecvTimeoutError,
         budget: Duration,
+        verdict: TimeoutVerdict,
     ) -> Result<CapturedFrame> {
         let within = budget.as_secs_f32();
         match err {
             RecvTimeoutError::Timeout => {
-                // Split the two black-screen root causes apart so the operator gets a cause, not
-                // just a symptom: did the format negotiate (compositor produced no buffers) or
-                // not (no acceptable format / node never emitted a param)?
-                if self.signals.negotiated.load(Ordering::Relaxed) {
-                    Err(anyhow!(
+                let offer = classify_first_frame_timeout(
+                    self.signals.negotiated.load(Ordering::Relaxed),
+                    self.hdr_offer,
+                    self.vaapi_dmabuf,
+                    self.signals.gpu_dmabuf_offer.load(Ordering::Relaxed),
+                    pf_zerocopy::zerocopy_forced(),
+                );
+                let convicted = timeout_convicts(offer, verdict);
+                // A provisional expiry names the same suspect but hands down no sentence — the
+                // full-length retry that follows is the one whose timeout latches.
+                let sentence = if convicted {
+                    "" // each arm below states its own downgrade
+                } else {
+                    " (short first-attempt window — nothing is latched; the full-length retry \
+                     decides)"
+                };
+                match offer {
+                    TimeoutOffer::NoBuffers => Err(anyhow!(
                         "no PipeWire frame within {within}s (node {}): format negotiated but no \
                          buffers arrived — the compositor produced no frames (virtual output \
                          idle/unmapped, capture never started, or a stream bound during a \
                          compositor (re)start that will never deliver — a reconnect fixes that)",
                         self.node_id
-                    ))
-                } else if self.hdr_offer {
-                    // The HDR (10-bit PQ dmabuf) offer was never accepted — the monitor left HDR
-                    // mode between the probe and the negotiation, the compositor pre-dates the
-                    // GNOME 50 HDR formats, or its allocator can't do LINEAR for XR30/XB30.
-                    // Latch the process-wide SDR downgrade so the next session (Moonlight
-                    // auto-reconnects) negotiates SDR instead of re-running this same timeout.
-                    super::note_hdr_capture_failed(self.hdr_source);
-                    Err(anyhow!(
-                        "no PipeWire frame within {within}s (node {}): the compositor never \
-                         accepted the HDR (10-bit PQ/BT.2020 dmabuf) offer — is the mirrored \
-                         monitor in HDR mode on GNOME 50+? Downgrading this host to SDR capture; \
-                         reconnect to stream SDR",
-                        self.node_id
-                    ))
-                } else if self.vaapi_dmabuf && !pf_zerocopy::zerocopy_forced() {
-                    // The dmabuf-only raw-passthrough offer was never accepted. Latch the
-                    // downgrade so the encode loop's pipeline rebuild retries on the CPU offer
-                    // instead of failing this same negotiation forever. The latch is SCOPED to the
-                    // raw-passthrough decision: it used to be `note_vaapi_dmabuf_failed`, which fed
-                    // `pf_zerocopy::enabled()` and therefore dropped every later session on this
-                    // host — NVENC's EGL→CUDA path included — to CPU capture. Since this offer is
-                    // also the PyroWave one (any vendor), a single PyroWave negotiation timeout was
-                    // enough to do that.
-                    pf_zerocopy::note_raw_dmabuf_negotiation_failed();
-                    Err(anyhow!(
-                        "no PipeWire frame within {within}s (node {}): the compositor never \
-                         accepted the dmabuf-only offer (raw-dmabuf passthrough) — downgrading \
-                         THIS path to CPU capture for the rest of the process; the pipeline \
-                         rebuild will renegotiate without dmabuf",
-                        self.node_id
-                    ))
-                } else if self.signals.gpu_dmabuf_offer.load(Ordering::Relaxed)
-                    && !pf_zerocopy::zerocopy_forced()
-                {
-                    // The EGL→CUDA dmabuf-only offer was never accepted — the twin of the raw-
-                    // passthrough arm above (the offer the thread ACTUALLY made, per the signal
-                    // it set — see `CaptureSignals::gpu_dmabuf_offer`). One timeout is conclusive:
-                    // a compositor that allocates none of the importer's modifiers refuses them
-                    // identically on every retry, so latch the offer off and let the pipeline
-                    // rebuild renegotiate the CPU path instead of re-running this same 10 s
-                    // timeout on every reconnect. A forced PUNKTFUNK_ZEROCOPY=1 keeps erroring
-                    // loudly instead (same rule as the raw arm).
-                    pf_zerocopy::note_gpu_dmabuf_negotiation_failed();
-                    Err(anyhow!(
-                        "no PipeWire frame within {within}s (node {}): the compositor never \
-                         accepted the dmabuf-only offer (EGL→CUDA GPU import) — downgrading THIS \
-                         offer to the CPU path for the rest of the process; the pipeline rebuild \
-                         will renegotiate without dmabuf",
-                        self.node_id
-                    ))
-                } else {
-                    Err(anyhow!(
+                    )),
+                    TimeoutOffer::Hdr => {
+                        // The HDR (10-bit PQ dmabuf) offer was never accepted — the monitor left HDR
+                        // mode between the probe and the negotiation, the compositor pre-dates the
+                        // GNOME 50 HDR formats, or its allocator can't do LINEAR for XR30/XB30.
+                        // Latch the SDR downgrade for THIS source (`HdrSource`, not process-wide — one
+                        // shared flag let either Linux HDR source disable the other) so the next session
+                        // (Moonlight auto-reconnects) negotiates SDR instead of re-running this timeout.
+                        if convicted {
+                            super::note_hdr_capture_failed(self.hdr_source);
+                        }
+                        Err(anyhow!(
+                            "no PipeWire frame within {within}s (node {}): the compositor never \
+                             accepted the HDR (10-bit PQ/BT.2020 dmabuf) offer — is the mirrored \
+                             monitor in HDR mode on GNOME 50+?{}",
+                            self.node_id,
+                            if convicted {
+                                " Downgrading this host to SDR capture; reconnect to stream SDR"
+                            } else {
+                                sentence
+                            }
+                        ))
+                    }
+                    TimeoutOffer::RawDmabuf => {
+                        // The dmabuf-only raw-passthrough offer was never accepted. Latch the
+                        // downgrade so the encode loop's pipeline rebuild retries on the CPU offer
+                        // instead of failing this same negotiation forever. The latch is SCOPED to the
+                        // raw-passthrough decision: it used to be `note_vaapi_dmabuf_failed`, which fed
+                        // `pf_zerocopy::enabled()` and therefore dropped every later session on this
+                        // host — NVENC's EGL→CUDA path included — to CPU capture. Since this offer is
+                        // also the PyroWave one (any vendor), a single PyroWave negotiation timeout was
+                        // enough to do that.
+                        if convicted {
+                            pf_zerocopy::note_raw_dmabuf_negotiation_failed();
+                        }
+                        Err(anyhow!(
+                            "no PipeWire frame within {within}s (node {}): the compositor never \
+                             accepted the dmabuf-only offer (raw-dmabuf passthrough){}",
+                            self.node_id,
+                            if convicted {
+                                " — downgrading THIS path to CPU capture for the rest of the \
+                                 process; the pipeline rebuild will renegotiate without dmabuf"
+                            } else {
+                                sentence
+                            }
+                        ))
+                    }
+                    TimeoutOffer::GpuDmabuf => {
+                        // The EGL→CUDA dmabuf-only offer was never accepted — the twin of the raw-
+                        // passthrough arm above (the offer the thread ACTUALLY made, per the signal
+                        // it set — see `CaptureSignals::gpu_dmabuf_offer`). One FULL-LENGTH timeout
+                        // is conclusive: a compositor that allocates none of the importer's
+                        // modifiers refuses them identically on every retry, so latch the offer off
+                        // and let the pipeline rebuild renegotiate the CPU path instead of
+                        // re-running this same 10 s timeout on every reconnect. A forced
+                        // PUNKTFUNK_ZEROCOPY=1 keeps erroring loudly instead (same rule as the raw
+                        // arm).
+                        if convicted {
+                            pf_zerocopy::note_gpu_dmabuf_negotiation_failed();
+                        }
+                        Err(anyhow!(
+                            "no PipeWire frame within {within}s (node {}): the compositor never \
+                             accepted the dmabuf-only offer (EGL→CUDA GPU import){}",
+                            self.node_id,
+                            if convicted {
+                                " — downgrading THIS offer to the CPU path for the rest of the \
+                                 process; the pipeline rebuild will renegotiate without dmabuf"
+                            } else {
+                                sentence
+                            }
+                        ))
+                    }
+                    TimeoutOffer::NoFormat => Err(anyhow!(
                         "no PipeWire frame within {within}s (node {}): format negotiation never \
                          completed — the compositor offered no format this consumer accepts \
                          (pixel-format/modifier mismatch) or the node never emitted a Format param",
                         self.node_id
-                    ))
+                    )),
                 }
             }
             RecvTimeoutError::Disconnected => Err(anyhow!(
@@ -874,3 +998,89 @@ mod pipewire;
 // unit-test without a compositor, which is the point.
 mod pw_cursor;
 mod pw_pods;
+
+#[cfg(test)]
+mod first_frame_timeout_tests {
+    use super::{classify_first_frame_timeout, timeout_convicts, TimeoutOffer, TimeoutVerdict};
+
+    #[test]
+    fn a_provisional_expiry_convicts_no_offer_whatever_was_on_the_table() {
+        // The bug this pins down: the retry loop's truncated 2.5 s first attempt latched all
+        // three sticky process-wide downgrades as if the compositor had refused the offers — a
+        // gamescope HDR cold start then streamed SDR (and CPU-copied) for the process lifetime.
+        for offer in [
+            TimeoutOffer::NoBuffers,
+            TimeoutOffer::Hdr,
+            TimeoutOffer::RawDmabuf,
+            TimeoutOffer::GpuDmabuf,
+            TimeoutOffer::NoFormat,
+        ] {
+            assert!(
+                !timeout_convicts(offer, TimeoutVerdict::Provisional),
+                "provisional expiry must not latch {offer:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn a_conclusive_expiry_convicts_exactly_the_offer_bearing_diagnoses() {
+        assert!(timeout_convicts(
+            TimeoutOffer::Hdr,
+            TimeoutVerdict::Conclusive
+        ));
+        assert!(timeout_convicts(
+            TimeoutOffer::RawDmabuf,
+            TimeoutVerdict::Conclusive
+        ));
+        assert!(timeout_convicts(
+            TimeoutOffer::GpuDmabuf,
+            TimeoutVerdict::Conclusive
+        ));
+        // A negotiated-but-idle stream and a plain format mismatch implicate no offer — nothing
+        // to latch even on a full-length wait.
+        assert!(!timeout_convicts(
+            TimeoutOffer::NoBuffers,
+            TimeoutVerdict::Conclusive
+        ));
+        assert!(!timeout_convicts(
+            TimeoutOffer::NoFormat,
+            TimeoutVerdict::Conclusive
+        ));
+    }
+
+    #[test]
+    fn classification_mirrors_the_negotiation_state_precedence() {
+        // A negotiated format clears every offer, whatever else was on the table.
+        assert_eq!(
+            classify_first_frame_timeout(true, true, true, true, false),
+            TimeoutOffer::NoBuffers
+        );
+        // The HDR offer outranks the dmabuf arms (it is the offer that failed to negotiate).
+        assert_eq!(
+            classify_first_frame_timeout(false, true, true, true, false),
+            TimeoutOffer::Hdr
+        );
+        assert_eq!(
+            classify_first_frame_timeout(false, false, true, true, false),
+            TimeoutOffer::RawDmabuf
+        );
+        assert_eq!(
+            classify_first_frame_timeout(false, false, false, true, false),
+            TimeoutOffer::GpuDmabuf
+        );
+        assert_eq!(
+            classify_first_frame_timeout(false, false, false, false, false),
+            TimeoutOffer::NoFormat
+        );
+    }
+
+    #[test]
+    fn a_forced_zerocopy_keeps_both_dmabuf_arms_erroring_loudly_instead_of_implicated() {
+        // PUNKTFUNK_ZEROCOPY=1 is the operator insisting on the path — the timeout falls through
+        // to the generic diagnosis (and so never latches), exactly as the old else-if chain did.
+        assert_eq!(
+            classify_first_frame_timeout(false, false, true, true, true),
+            TimeoutOffer::NoFormat
+        );
+    }
+}

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

@@ -1506,7 +1506,20 @@ pub fn pipewire_thread(
             {
                 return;
             }
-            if ud.info.parse(param).is_ok() {
+            // Parse ONCE — `parse` takes `&mut self` — and report a failure instead of swallowing it.
+            // On `Err`, `negotiated` stays false and `format`/`modifier`/`frame_size` keep their
+            // previous values, so the capture dies on the generic "the compositor offered no format
+            // this consumer accepts" timeout — sending the operator hunting a format mismatch when
+            // the real fault was a malformed Format pod we DID accept.
+            let parsed = ud.info.parse(param);
+            if let Err(e) = &parsed {
+                tracing::error!(
+                    error = %e,
+                    "pipewire: failed to parse the negotiated Format pod — capture will time out \
+                     with no usable format"
+                );
+            }
+            if parsed.is_ok() {
                 ud.signals.negotiated.store(true, Ordering::Relaxed);
                 // A (re)negotiation replaces the buffer pool: every cached per-buffer import
                 // (stored fds in the worker, the Vulkan bridge's per-fd sources) keys on

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

@@ -197,6 +197,15 @@ pub(super) fn update_cursor_meta(cursor: &mut CursorState, spa_buf: *mut spa::sy
     if bw == 0 || bh == 0 || bw > 1024 || bh > 1024 {
         return;
     }
+    // SPA's second "no image data" signal, distinct from the `bitmap_offset == 0` position-only
+    // case above: `spa_meta_bitmap.offset` is the offset of the PIXELS within the bitmap struct,
+    // and 0 means there are none. Without this, `pix_off == 0` made the pixel extent start at the
+    // `spa_meta_bitmap` header itself, so a producer signalling an invisible pointer got its own
+    // header words (format/size/stride/offset) decoded and cached as the cursor bitmap. In bounds,
+    // so not unsound — just garbage pixels blitted into every later frame.
+    if pix_off == 0 {
+        return;
+    }
     let row = bw as usize * 4;
     let stride = if stride < row { row } else { stride };
     let Some(extent) = bitmap_extent(bmp_off, pix_off, stride, row, bh as usize, region_size)
@@ -327,7 +336,8 @@ pub(super) fn composite_cursor_rgb10(
 }
 
 /// Alpha-blend the cached cursor bitmap into the tightly-packed CPU frame at its latched
-/// position. Cheap: a straight-alpha blit over at most ~256×256 pixels, clipped to the frame —
+/// position. Cheap: a straight-alpha blit over at most 1024×1024 pixels (the accepted cap; real
+/// cursors are ≤96 px), clipped to the frame —
 /// the whole point of cursor-as-metadata (no forced full-frame composite on the producer).
 pub(super) fn composite_cursor(
     tight: &mut [u8],

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

@@ -377,7 +377,8 @@ pub(super) fn build_dmabuf_buffers() -> Result<Vec<u8>> {
 /// Request the compositor attach `SPA_META_Cursor` to each buffer, so the pointer travels as
 /// metadata (position + an occasional bitmap) instead of being burned into the frame. Paired
 /// with the portal's `CursorMode::Metadata`; producers that don't support it simply don't
-/// attach it (harmless). Size is a range up to a 256×256 bitmap — bigger than any real cursor.
+/// attach it (harmless). Size is a range up to a 1024×1024 bitmap — see the note on `max` below for
+/// why this is not the "bigger than any real cursor" 256² it used to be.
 pub(super) fn build_cursor_meta_param() -> Result<Vec<u8>> {
     fn meta_size(w: u32, h: u32) -> i32 {
         (std::mem::size_of::<spa::sys::spa_meta_cursor>()

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

@@ -55,16 +55,6 @@ use x11rb::rust_connection::{DefaultStream, RustConnection};
 
 use crate::GamescopeCursorTargets;
 
-/// Serializes the `XAUTHORITY` env swap of the LEGACY connect fallback (the var is process-global).
-///
-/// The fallback is a last resort now — see [`connect_conn`]. It serialises this source against
-/// itself and nothing else: `getenv` needs no lock to be racy, so every OTHER thread's read (libspa
-/// plugin load, EGL/CUDA init — concurrent by construction, since `attach_gamescope_cursor` runs
-/// while the PipeWire thread is starting) could still observe the swapped value or a torn
-/// environ. That is why the primary path parses the cookie itself and never touches the
-/// environment.
-static XAUTH_LOCK: Mutex<()> = Mutex::new(());
-
 /// The `MIT-MAGIC-COOKIE-1` auth-protocol name, as it appears in an `.Xauthority` entry.
 const MIT_MAGIC_COOKIE_1: &[u8] = b"MIT-MAGIC-COOKIE-1";
 
@@ -267,17 +257,18 @@ fn connect(dpy: &str, xauthority: Option<&str>) -> Result<Connected, String> {
 /// environment.
 ///
 /// `RustConnection::connect` reads `XAUTHORITY` from the env, so the original implementation
-/// `set_var`'d it around each connect under [`XAUTH_LOCK`]. That is unsound from a live
-/// multithreaded host: the lock serialises this source against itself, but `getenv` takes no lock,
-/// so any concurrent reader (libspa's plugin load, EGL/CUDA init — running at exactly this moment,
-/// since the PipeWire thread is starting up) could read the swapped value or race the environ
-/// rewrite outright. The project already has a process-wide env-lock discipline elsewhere, but
-/// sharing it would be the wrong layer AND would still not fix `getenv`.
+/// `set_var`'d it around each connect under a mutex. That is unsound from a live multithreaded
+/// host: the lock serialised this source against itself, but `getenv` takes no lock, so any
+/// concurrent reader (libspa's plugin load, EGL/CUDA init — running at exactly this moment, since
+/// the PipeWire thread is starting up) could read the swapped value or race the environ rewrite
+/// outright. The project already has a process-wide env-lock discipline elsewhere, but sharing it
+/// would be the wrong layer AND would still not fix `getenv`.
 ///
 /// So: parse the MIT-MAGIC-COOKIE-1 entry out of the file ourselves and hand it to
 /// `connect_to_stream_with_auth_info`, which is what `RustConnection::connect` does internally with
-/// the cookie IT found. The env swap survives only as a fallback for a file we cannot parse (an
-/// unexpected layout, or an auth family whose entry we decline to guess at).
+/// the cookie IT found. Where that finds nothing usable we connect with an explicitly empty token
+/// ([`connect_unauthenticated`]) rather than swapping the environment — this process no longer
+/// writes `environ` at all.
 fn connect_conn(dpy: &str, xauthority: Option<&str>) -> Result<(RustConnection, usize), String> {
     let Some(path) = xauthority else {
         // No per-display cookie file to inject: the ambient environment is already what this
@@ -289,16 +280,16 @@ fn connect_conn(dpy: &str, xauthority: Option<&str>) -> Result<(RustConnection,
             Ok(v) => return Ok(v),
             Err(e) => tracing::debug!(
                 dpy = %dpy, xauthority = %path, error = %e,
-                "gamescope cursor: cookie connect failed — falling back to the XAUTHORITY env swap"
+                "gamescope cursor: cookie connect failed — retrying unauthenticated"
             ),
         },
         None => tracing::debug!(
             dpy = %dpy, xauthority = %path,
-            "gamescope cursor: no MIT-MAGIC-COOKIE-1 entry for this display — falling back to the \
-             XAUTHORITY env swap"
+            "gamescope cursor: no MIT-MAGIC-COOKIE-1 entry for this display — connecting \
+             unauthenticated"
         ),
     }
-    connect_via_env_swap(dpy, path)
+    connect_unauthenticated(dpy)
 }
 
 /// Connect to `dpy` and complete the setup handshake with an explicit cookie — the same two steps
@@ -331,19 +322,31 @@ fn connect_with_cookie(
         .map_err(|e| format!("setup: {e}"))
 }
 
-/// LEGACY fallback (see [`connect_conn`]): swap `XAUTHORITY`, connect, restore. Serialised against
-/// this source's own concurrent connects, but NOT against other threads' `getenv` — which is why it
-/// is a fallback and not the path taken.
-fn connect_via_env_swap(dpy: &str, xauthority: &str) -> Result<(RustConnection, usize), String> {
-    let _g = XAUTH_LOCK.lock().unwrap_or_else(|e| e.into_inner());
-    let prev = std::env::var_os("XAUTHORITY");
-    std::env::set_var("XAUTHORITY", xauthority);
-    let out = RustConnection::connect(Some(dpy));
-    match prev {
-        Some(p) => std::env::set_var("XAUTHORITY", p),
-        None => std::env::remove_var("XAUTHORITY"),
-    }
-    out.map_err(|e| format!("connect: {e}"))
+/// Last-resort fallback (see [`connect_conn`]): connect with an EXPLICITLY EMPTY auth token.
+///
+/// This replaces a `set_var("XAUTHORITY", …)` / connect / restore dance, which was unsound and is
+/// not fixable in place. `setenv`/`unsetenv` rewrite the process-global `environ`; glibc
+/// *reallocates* that array when a variable is added, and the host is emphatically multithreaded
+/// at this moment — `attach_gamescope_cursor` runs while the PipeWire thread is inside `pw_init`'s
+/// `dlopen` and a dozen bare `getenv()` calls, with EGL/CUDA init alongside. A mutex here
+/// serialised this source against itself and against nothing else, because `getenv` takes no lock.
+/// The damaging branch is the one where `XAUTHORITY` is ABSENT and therefore gets *added* — which
+/// `scripts/punktfunk-host.service` makes the normal configuration, since the unit deliberately
+/// does not import the login shell's environment. And `rediscover` re-runs this every 2 s for the
+/// whole session, because a display whose connect fails is never recorded and so is never skipped.
+///
+/// Connecting with an empty token is what the swap actually achieved. We only reach here when our
+/// own lookup found no usable `MIT-MAGIC-COOKIE-1` entry, and x11rb's internal lookup reads the
+/// same file with a STRICTER matcher (it also matches family/address, which we deliberately do
+/// not) — so where we find nothing, it finds nothing too, and connects unauthenticated. That is
+/// precisely why the swap "worked" against a nested Xwayland started without `-auth`.
+///
+/// The one case this gives up is an `.Xauthority` whose entry uses an auth family we decline to
+/// guess at but x11rb would have handled. A gamescope Xwayland writes a single-entry
+/// MIT-MAGIC-COOKIE-1 file, so that case is not reachable here — and a cursor overlay that
+/// declines to attach is the correct outcome anyway, against a torn `environ` in a live session.
+fn connect_unauthenticated(dpy: &str) -> Result<(RustConnection, usize), String> {
+    connect_with_cookie(dpy, Vec::new(), Vec::new())
 }
 
 /// The `MIT-MAGIC-COOKIE-1` `(name, data)` for `dpy` from the `.Xauthority`-format file at `path`.

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

@@ -9,9 +9,6 @@
 //! `crate::dxgi::*` path keeps resolving. DXGI Desktop Duplication has been removed; this
 //! module contains no capturer.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 pub use pf_frame::dxgi::{make_device, pack_luid, D3d11Frame, PyroFrameShare, WinCaptureTarget};
 
 // The P010 colour self-test (sweep Phase 5.5) — the `hdr-p010-selftest` subcommand, its f64
@@ -554,9 +551,11 @@ impl HdrP010Converter {
             let mut ps_uv = None;
             device.CreatePixelShader(&uvb, None, Some(&mut ps_uv))?;
             let sd = D3D11_SAMPLER_DESC {
-                // POINT: the Y pass samples a single texel centre exactly, and the UV pass does its OWN
-                // 2x2 box average via 4 explicit taps at texel centres (offset half a texel). Point
-                // sampling keeps each tap exact; the averaging is in the shader, not the sampler.
+                // POINT: the Y pass samples a single texel centre exactly, and the UV pass takes its OWN
+                // two explicit taps on the 2x2 block's LEFT column (left-cositing) and averages them.
+                // Point sampling keeps each tap exact; the averaging is in the shader, not the sampler.
+                // (It was a 4-tap CENTER-sited 2x2 box until that was found to shift chroma by half a
+                // luma pixel — see `HDR_P010_UV_PS`.)
                 Filter: D3D11_FILTER_MIN_MAG_MIP_POINT,
                 AddressU: D3D11_TEXTURE_ADDRESS_CLAMP,
                 AddressV: D3D11_TEXTURE_ADDRESS_CLAMP,

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

@@ -16,9 +16,6 @@
 //! [`pf_driver_proto`] (which OWNS the contract, with `const` size asserts) — both sides `use` it, so
 //! drift is a compile error rather than a "must match" comment.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::dxgi::{
     make_device, BgraToYuvPlanes, D3d11Frame, HdrP010Converter, HdrRgb10Converter, PyroFrameShare,
     VideoConverter, WinCaptureTarget,
@@ -337,6 +334,7 @@ use channel::ChannelBroker;
 use descriptor::{DescriptorPoller, DisplayDescriptor};
 use stall::{StallEvidence, StallWatch};
 
+/// Creates + owns the shared ring; yields the driver's frames as [`FramePayload::D3d11`].
 pub struct IddPushCapturer {
     device: ID3D11Device,
     context: ID3D11DeviceContext,
@@ -652,14 +650,18 @@ impl IddPushCapturer {
     }
 
     /// The output texture format + the [`PixelFormat`] NVENC encodes, driven by the DISPLAY's HDR
-    /// state (like the WGC path) plus the session's 4:4:4 negotiation: HDR → `P010` (BT.2020 PQ
+    /// state plus the session's 4:4:4 negotiation: HDR → `P010` (BT.2020 PQ
     /// 10-bit limited) → NVENC Main10, and the client auto-detects PQ from the HEVC VUI; SDR →
     /// `Nv12` (BT.709 8-bit limited), or full-chroma `Bgra` passthrough on a 4:4:4 session (NVENC
     /// CSCs RGB→YUV444 itself, following the BT.709 VUI — the one path that deliberately pays the
-    /// SM-side CSC, because the video processor can only produce subsampled output). We do NOT
-    /// gate HDR on the client's advertised `VIDEO_CAP_10BIT` — clients under-report it (e.g. the
-    /// Mac advertises 10-bit only when its OWN display is HDR), yet all decode Main10 +
-    /// auto-switch, exactly as on the WGC path. HDR and 4:4:4 now COMPOSE: an HDR display that
+    /// SM-side CSC, because the video processor can only produce subsampled output). The
+    /// composition depth DOES follow the session's negotiated `client_10bit` — pinned at open
+    /// (`open.rs`, the `!client_10bit` force-off and the 10-bit enable) and re-pinned every sample
+    /// by [`Self::poll_display_hdr`], because a PQ stream sent to a client that advertised SDR-only
+    /// lands on an SDR desktop and blows out. (The older note here claimed the opposite — that the
+    /// advertised `VIDEO_CAP_10BIT` was ignored because clients under-report it. That reasoning
+    /// survives only in the CODEC choice: an HDR-negotiated H.26x session still follows a host
+    /// "Use HDR" flip in either direction.) HDR and 4:4:4 now COMPOSE: an HDR display that
     /// negotiated full chroma emits packed 10-bit BT.2020 PQ RGB (`Rgb10a2`) for NVENC to CSC to
     /// YUV 4:4:4 — HEVC Main 4:4:4 10. (Before, HDR won and the stream silently downgraded to
     /// 4:2:0 *after* the Welcome had already promised 4:4:4.)
@@ -969,7 +971,7 @@ impl IddPushCapturer {
             },
             Usage: D3D11_USAGE_DEFAULT,
             // RENDER_TARGET: the VIDEO processor (NV12) and the P010 shader passes both write here, and
-            // NVENC registers it as encode input — matching the WGC YUV ring. (PyroWave uses its own
+            // NVENC registers it as encode input. (PyroWave uses its own
             // shareable two-plane `pyro_ring` instead, so this NVENC/AMF/QSV ring stays unshared.)
             BindFlags: D3D11_BIND_RENDER_TARGET.0 as u32,
             CPUAccessFlags: 0,
@@ -1970,9 +1972,12 @@ impl Capturer for IddPushCapturer {
     fn pipeline_depth(&self) -> usize {
         // 2 = one frame deferred: submit N+1 (capture + convert/copy into a fresh out-ring texture) while
         // NVENC encodes N on the ASIC. We hand a rotating `OUT_RING` of output textures, so this is safe.
-        // `PUNKTFUNK_IDD_DEPTH` overrides (1 disables pipelining; clamp to ≤ OUT_RING so a frame in flight
-        // always has its own texture).
-        pf_host_config::config().idd_depth.clamp(1, OUT_RING)
+        // `PUNKTFUNK_IDD_DEPTH` overrides (1 disables pipelining). The ceiling is `OUT_RING - 1`, NOT
+        // `OUT_RING`: `d` frames in flight need `d + 1` textures, because the rotation has to hand out a
+        // slot that is not one of the `d` still being encoded. Clamping to `OUT_RING` admitted depth 3 on
+        // a 3-slot ring, where `repeat_last`'s rotation lands back on the slot NVENC is reading and the
+        // convert overwrites it in place — torn frames, silently, with no error anywhere.
+        pf_host_config::config().idd_depth.clamp(1, OUT_RING - 1)
     }
 
     fn capture_target_id(&self) -> Option<u32> {

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

@@ -2,9 +2,6 @@
 //! capturer): duplicates the unnamed shared header / ring / event handles into the driver's WUDFHost
 //! and delivers them as bare handle values over the SYSTEM-only control device.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::*;
 
 /// The sealed channel's handle-duplication broker (`design/idd-push-security.md`): the frame objects
@@ -160,7 +157,18 @@ impl ChannelBroker {
         event: HANDLE,
         slots: &[HostSlot],
     ) -> Result<()> {
-        debug_assert!(slots.len() <= control::RING_LEN_USIZE);
+        // An ERROR, not a `debug_assert`: in a release build the assert is compiled out and the
+        // over-long slice instead panics on `req.texture_handles[k]` in the middle of
+        // `duplicate_and_deliver` — after handles have already been planted in WUDFHost. That panic
+        // unwinds straight past the reap below, leaking every duplicate made so far into the driver
+        // process. Refuse before the first duplication, while there is nothing to reap.
+        if slots.len() > control::RING_LEN_USIZE {
+            anyhow::bail!(
+                "frame channel: {} ring slots exceeds the wire limit of {}",
+                slots.len(),
+                control::RING_LEN_USIZE
+            );
+        }
         let mut req = control::SetFrameChannelRequest {
             target_id,
             generation,

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

@@ -5,9 +5,6 @@
 //! [`pf_frame::CursorOverlay`] the Linux portal path produces — everything downstream (the
 //! cursor forwarder, the wire, the client renderer) is shared.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it.
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::*;
 use pf_driver_proto::cursor::{
     CursorShm, CURSOR_MAGIC, CURSOR_SHAPE_BYTES, CURSOR_SHAPE_MAX, CURSOR_SHAPE_OFFSET,
@@ -42,7 +39,9 @@ impl CursorShared {
     /// the section itself (owned by `self`); the caller duplicates it into the WUDFHost.
     pub(super) fn create(target_id: u32) -> Result<CursorShared> {
         // SAFETY: plain FFI. Unnamed pagefile-backed section, host-lifetime owned; the view is
-        // mapped once and unmapped never (the capturer's life = the session's life).
+        // mapped once here and unmapped exactly once by `MappedSection::drop` (which unmaps before
+        // closing the mapping handle). No borrow into the view outlives the `MappedSection`: every
+        // access goes through `&self` accessors on the owner.
         let section = unsafe {
             let map = CreateFileMappingW(
                 INVALID_HANDLE_VALUE,

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

@@ -10,9 +10,6 @@
 //! alpha-blended quad (the GDI poller's full-fidelity shape at its polled position), entirely
 //! GPU-side on the capture device, before the normal conversion runs from the scratch.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::*;
 use windows::core::s;
 use windows::Win32::Graphics::Direct3D::D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST;

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

@@ -20,9 +20,6 @@
 //! `winsta0\default` (the service supervisor retargets the token — `windows/service.rs`
 //! `spawn_host`), so the poller thread sees the session's cursor directly; no helper process.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::*;
 use windows::Win32::Graphics::Gdi::{
     DeleteObject, GetDC, GetDIBits, GetObjectW, ReleaseDC, BITMAP, BITMAPINFO, BITMAPINFOHEADER,
@@ -55,8 +52,10 @@ struct Shape {
     serial: u64,
 }
 
-/// Off-thread GDI cursor poller. Samples `GetCursorInfo` at ~60 Hz, rasterises the `HCURSOR` only
-/// when its handle value changes, and publishes a ready [`pf_frame::CursorOverlay`] snapshot; the
+/// Off-thread GDI cursor poller. Samples `GetCursorInfo` every [`Self::INTERVAL`] (4 ms, ~250 Hz —
+/// see that constant for why 16 ms was the bug), rasterises the `HCURSOR` when its handle value
+/// changes and when [`Self::EXTENT_PROBE`] catches a resize under a STABLE handle, and publishes a
+/// ready [`pf_frame::CursorOverlay`] snapshot; the
 /// capture thread's per-tick cost is one uncontended mutex read + an `Arc` clone
 /// (same split as [`DescriptorPoller`], and for the same reason: user32/gdi32 calls have no place
 /// on the capture/encode thread).
@@ -186,7 +185,6 @@ fn run(
             // against, and this poller outlives all of them. `None` keeps the last good value — a
             // transient CCD failure must not park the pointer at a `(0, 0, 0, 0)` rect, which would
             // report every position invisible.
-            //
             let fresh = pf_win_display::win_display::source_desktop_rect(target_id);
             if let Some(fresh) = fresh {
                 if fresh != rect {
@@ -302,7 +300,14 @@ fn run(
                 serial: s.serial,
                 hot_x: s.hot_x,
                 hot_y: s.hot_y,
-                visible: showing && in_rect,
+                // `handle != 0` is part of "visible", not just of "worth rasterising": `SetCursor(NULL)`
+                // — how a game or a video player hides the pointer for its own window — leaves
+                // `CURSOR_SHOWING` set with a NULL `hCursor`. Judging on the flags alone published
+                // `visible: true` carrying the last shape we rasterised, so the composite path blended a
+                // ghost arrow into a game that had hidden its cursor, and the forward path told the
+                // client to draw one too. Every rasterise gate below already tests this; the published
+                // verdict has to agree with them.
+                visible: showing && in_rect && handle != 0,
             }
         });
         *slot.lock().unwrap_or_else(|p| p.into_inner()) = overlay;

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

@@ -1,12 +1,8 @@
 //! Off-thread display-descriptor polling (plan §W4, carved out of the IDD-push capturer): the
 //! live HDR state + active resolution of the virtual target, sampled off the capture loop via CCD.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::*;
 
-/// Creates + owns the shared ring; yields the driver's frames as [`FramePayload::D3d11`].
 /// The display descriptor the capture loop follows: live HDR state + active resolution of the
 /// virtual target.
 #[derive(Clone, Copy, PartialEq, Eq)]

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

@@ -33,9 +33,6 @@
 //! The session's `FlushTimer` is 1 s, so a bracket from the trailing second of a gap can land
 //! AFTER that stall's report line — the next report (and the metronomic tally) still carries it.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use std::collections::VecDeque;
 use std::sync::{Arc, Mutex, OnceLock, Weak};
 use std::time::{Duration, Instant};
@@ -142,7 +139,12 @@ unsafe extern "system" fn on_event(record: *mut EVENT_RECORD) {
             (*record).EventHeader.ProcessId,
         )
     };
-    let mut ring = RING.lock().unwrap();
+    // Poison-tolerant, and that is load-bearing rather than tidy: this is an `extern "system"`
+    // callback invoked from an OS thread, so a panic here unwinds across an FFI boundary and
+    // ABORTS the host process. `unwrap()` made a single poisoned lock turn every subsequent event
+    // delivery into a hard abort — a diagnostic taking down capture. Nothing else under this lock
+    // can panic, so recovering the guard also makes the poison unreachable in the first place.
+    let mut ring = RING.lock().unwrap_or_else(|e| e.into_inner());
     if ring.len() == RING_CAP {
         ring.pop_front();
     }

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

@@ -152,8 +152,11 @@ impl IddPushCapturer {
     }
 
     /// Open the IDD-push capturer. On success the caller's `keepalive` is attached (the capturer owns the
-    /// virtual display); on FAILURE the keepalive is handed BACK so the caller can fall back to DDA
-    /// instead of tearing the display down (audit §5.1 — no more 20 s black bail). "Failure" includes the
+    /// virtual display); on FAILURE the keepalive is handed BACK so the caller decides the display's fate
+    /// itself — retire it, or reuse the monitor for a retry — instead of this function tearing it down
+    /// (audit §5.1 — no more 20 s black bail). There is no second capture path to fall back TO: DDA was
+    /// removed (see `lib.rs`), and `punktfunk-host`'s caller drops the returned keepalive under
+    /// `.context("IDD-push capture open (no fallback)")`. "Failure" includes the
     /// driver not attaching to the ring within a few seconds (e.g. a hybrid-GPU render mismatch).
     #[allow(clippy::too_many_arguments)]
     pub fn open(
@@ -666,7 +669,7 @@ impl IddPushCapturer {
                 // wait for the first compose) until the capturer drops with the session.
                 _display_wake: pf_frame::session_tuning::DisplayWakeRequest::new(),
                 // Placeholder; `open()` attaches the real keepalive on success, so a FAILED open can hand
-                // it back to the caller for the DDA fallback (audit §5.1).
+                // it back to the caller to retire or reuse the display (audit §5.1).
                 _keepalive: Box::new(()),
             };
             // The HDR SDR-white reference for the composited cursor, queried ONCE here rather than
@@ -675,15 +678,15 @@ impl IddPushCapturer {
             me.refresh_sdr_white_scale();
             // Bounded wait for the driver to ATTACH to the ring AND publish a first frame. An attach
             // failure (DRV_STATUS_TEX_FAIL) or an attach-but-no-frames (a game left the display in a
-            // format/size the ring can't match) becomes an open failure the caller falls back from (→ DDA),
-            // instead of next_frame's 20 s black-then-bail.
+            // format/size the ring can't match) becomes an open failure the caller handles by retiring the
+            // display, instead of next_frame's 20 s black-then-bail.
             me.wait_for_attach()?;
             Ok(me)
         }
     }
 
     /// Block (bounded) until the driver has ATTACHED to the host ring (`DRV_STATUS_OPENED`) **and published
-    /// a first frame**, else fail so the caller can fall back to DDA (audit §5.1 +
+    /// a first frame**, else fail so the caller can retire the display and rebuild (audit §5.1 +
     /// `design/windows-host-rewrite.md` §2.5 — the GB1 game-capture fix).
     ///
     /// Requiring the first frame — not just the attach — catches the *reconnect-into-a-broken-state* case:

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

@@ -25,9 +25,6 @@
 //! ([`acquire`]), refcounted across parallel capturers; probes sample at 20 Hz or slower and cost
 //! microseconds each, so the engine is invisible next to a streaming session.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use std::collections::VecDeque;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, Weak};
@@ -53,7 +50,9 @@ use super::stall::ProbeWindow;
 
 /// One probe's sample ring: `(completed_at, span, value_us)` — `value` is the measurement (a call
 /// latency or a frozen-span/overshoot), `span` the wall interval it describes ending at
-/// `completed_at`. Capped; ~20 Hz per probe → several minutes of coverage.
+/// `completed_at`. Capped at 512 samples: at the fastest producer's ~20 Hz that is ~26 s of
+/// coverage, ~51 s for the 100 ms loops — comfortably longer than the seconds-old windows a stall
+/// report asks for, but NOT the "several minutes" this used to claim.
 struct Ring {
     samples: Mutex<VecDeque<(Instant, Duration, u64)>>,
 }

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

@@ -1,9 +1,6 @@
 //! Capture-stall detection (plan §W4, carved out of the IDD-push capturer): flags multi-hundred-ms
 //! holes in DWM frame delivery that open while the desktop was actively composing.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::*;
 
 /// A detected capture stall: a multi-hundred-ms hole in DWM's frame delivery that opened while the
@@ -317,7 +314,8 @@ impl StallWatch {
     /// Frames of pre-gap history that must be tight for flow to count as active. Stalls are thus
     /// naturally spaced ≥ RECENT frame times apart — no extra log rate limit needed.
     const RECENT: usize = 8;
-    /// The RECENT pre-gap frames must all fit in this span (8 frames in 400 ms ≈ ≥ 20 fps flow —
+    /// The RECENT pre-gap frames must all fit in this span (8 frames spanning 400 ms is 7 intervals,
+    /// so the real bar is ≈ ≥ 17.5 fps flow —
     /// loose enough for a 30 fps-capped game, tight enough to reject idle-desktop damage).
     const ACTIVE_SPAN: Duration = Duration::from_millis(400);
     /// The smallest hole that counts as a stall (~9 missed frames at 60 Hz) — well below the
@@ -535,14 +533,47 @@ impl StallWatch {
                      suspects)"
                 );
             } else {
+                // The two REALTIME GPU-priority opt-ins, as configured in THIS process's
+                // environment (machine env; the WUDFHost driver process resolves the PFVD pair
+                // the same way, so this read mirrors what the driver decided — modulo a machine
+                // env edited after either process started, which a restart heals). The RX 9070
+                // XT field A/B (2026-08-12) convicted EXACTLY this warning's signature twice
+                // over: the driver's swap-chain REALTIME raise beat at ~1.8 s, the host
+                // auto-gate's REALTIME upgrade at ~3.6 s — so a log carrying this warning must
+                // say whether either lever is engaged before anyone chases display hardware.
+                let rt_gpu_driver = if std::env::var_os("PFVD_NO_RT_GPU").is_some() {
+                    "off (PFVD_NO_RT_GPU)"
+                } else {
+                    match std::env::var_os("PFVD_RT_GPU") {
+                        None => "off (default)",
+                        Some(v) if v.eq_ignore_ascii_case("thread") => "gpu-thread (+7)",
+                        Some(_) => "REALTIME (PFVD_RT_GPU)",
+                    }
+                };
+                let rt_gpu_host = match std::env::var("PUNKTFUNK_GPU_PRIORITY_CLASS")
+                    .ok()
+                    .as_deref()
+                {
+                    Some("off") => "off",
+                    Some("normal") => "normal",
+                    Some("realtime") => "REALTIME (pinned)",
+                    Some("auto") => "auto (gated REALTIME upgrade)",
+                    _ => "high (default)",
+                };
                 tracing::warn!(
                     period_s = format!("{:.2}", period.as_secs_f64()),
                     os_correlated = correlated,
                     connected_inactive = %suspects,
+                    rt_gpu_driver,
+                    rt_gpu_host,
                     verdicts = %verdict_tally,
                     classes = %class_tally,
                     "capture stalls are METRONOMIC with NO coinciding OS display event — \
-                     the disturbance is BELOW Windows: the GPU driver servicing a \
+                     the disturbance is BELOW Windows. FIRST: if rt_gpu_driver or \
+                     rt_gpu_host shows a REALTIME opt-in, clear it (unset PFVD_RT_GPU / \
+                     set PUNKTFUNK_GPU_PRIORITY_CLASS=high) — a punktfunk process holding \
+                     REALTIME GPU priority is the field-proven amplifier of exactly this \
+                     signature on AMD. Otherwise: the GPU driver servicing a \
                      connected-but-asleep sink (standby HPD/DDC/link probing), \
                      display-poller software (the SteelSeries-GG/SignalRGB class — \
                      correlate 'slow display-descriptor poll' lines), or the DWM present \

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

@@ -18,7 +18,6 @@
 // proof of why it is sound. This crate held ~91 unsafe items with NO enforcement while every
 // other subsystem crate denied it — the decoders' `unsafe impl Send`s had a one-line aside
 // instead of an argument precisely because nothing required one.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 #[cfg(any(target_os = "linux", windows))]
 mod au_dump;

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

@@ -885,7 +885,12 @@ fn pump(
                     Some(exp) => {
                         if let Some(gap) = index_gap(exp, frame.frame_index) {
                             let now = Instant::now();
-                            gate.arm(now);
+                            // Credited arm: the reassembler books these same lost frames into
+                            // `frames_dropped` up to ~120 ms from now; the credit keeps that
+                            // delayed climb from re-freezing a stream the RFI anchor healed in
+                            // between (the double-arm race — see
+                            // `ReanchorGate::arm_expecting_drops`).
+                            gate.arm_expecting_drops(now, u64::from(gap));
                             next_expected_index = Some(frame.frame_index.wrapping_add(1));
                             // The gap carries the PRECISE lost range — [first missing, newest
                             // received - 1] — so this is the one recovery signal that can drive true

crates/pf-clipboard/src/host/windows.rs

@@ -17,8 +17,8 @@
 //! (`PostMessage` is the documented thread-safe way to poke a message loop). Per-window state hangs
 //! off `GWLP_USERDATA`, so multiple concurrent sessions each get their own window + state.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; the deny enforcing it sits at
+// the crate root (lib.rs), covering every backend.
 
 use std::cell::RefCell;
 use std::sync::{Arc, Mutex};

crates/pf-clipboard/src/lib.rs

@@ -10,6 +10,10 @@
 //! [`spawn_decline_loop`] — so its control loop compiles unchanged on every host platform; the
 //! platform split lives entirely behind [`start`].
 
+// Unsafe-proof program: every `unsafe` block in any backend carries a `// SAFETY:` proof,
+// enforced workspace-wide by `[workspace.lints]` — a new backend under `host/` is covered on
+// creation.
+
 use std::sync::atomic::AtomicBool;
 use std::sync::Arc;
 

crates/pf-console-ui/src/lib.rs

@@ -11,7 +11,6 @@
 //! capture hint, start banner.
 
 // Unsafe-proof program: every `unsafe {}` in the Skia/Vulkan overlay carries a `// SAFETY:` proof.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 #[cfg(any(target_os = "linux", windows))]
 mod anim;

crates/pf-console-ui/src/screens.rs

@@ -209,7 +209,7 @@ impl Screen {
     pub(crate) fn title(&self, _ctx: &Ctx) -> String {
         match self {
             Screen::Home(_) => "Select a Host".into(),
-            Screen::Library(s) => s.host_name().to_string(),
+            Screen::Library(s) => s.title(),
             Screen::Settings(_) => "Settings".into(),
             Screen::AddHost(s) => s.title(),
             Screen::Pair(s) => format!("Pair with {}", s.host_name()),

crates/pf-console-ui/src/screens/library.rs

@@ -10,7 +10,7 @@ use crate::library::{
     StepResult, BUMP_C, BUMP_K, BUMP_PX, FOCUS_GAP, JUMP, PERSPECTIVE, POSTER_H, POSTER_W,
     RECEDE_DIM, RECEDE_SCALE, ROTATE_DEG, SIDE_SPACING, SPRING_C, SPRING_K, VISIBLE_RANGE,
 };
-use crate::model::{ConsoleCmd, HostRow};
+use crate::model::{ConsoleCmd, HostRow, ProfileChip};
 use crate::pointer::{Pointer, PointerKind};
 use crate::screens::{ConnectIntent, Ctx, Outbox};
 use crate::theme::{accent, fg, Fonts, W};
@@ -24,6 +24,11 @@ pub(crate) struct LibraryScreen {
     port: u16,
     fp_hex: String,
     mgmt: u16,
+    /// `Some` when this library was opened from a PINNED host+profile card (§5.2a) rather
+    /// than the host's primary tile: every launch off this shelf is that card's connect
+    /// with a title attached, so it carries the same one-off profile the card's plain
+    /// A-press would. `None` = the primary tile, where the host's binding decides.
+    pin: Option<ProfileChip>,
     shared: Option<LibraryShared>,
     // Synced snapshot of the shared model (re-pulled when the generation bumps).
     generation: u64,
@@ -48,6 +53,7 @@ impl LibraryScreen {
             port: host.port,
             fp_hex: host.fp_hex.clone(),
             mgmt: host.mgmt_port,
+            pin: host.pin.clone(),
             shared: None, // adopted from Ctx on the first render (the shell owns it)
             generation: u64::MAX,
             phase: LibraryPhase::Loading,
@@ -60,8 +66,13 @@ impl LibraryScreen {
         }
     }
 
-    pub(crate) fn host_name(&self) -> &str {
-        &self.host_name
+    /// The screen's title: the host, and — when this shelf belongs to a pinned card — the
+    /// profile every launch off it will use, in the card's own `host · profile` shape.
+    pub(crate) fn title(&self) -> String {
+        match &self.pin {
+            Some(p) => format!("{} \u{b7} {}", self.host_name, p.name),
+            None => self.host_name.clone(),
+        }
     }
 
     fn fetch_cmd(&self) -> ConsoleCmd {
@@ -123,10 +134,18 @@ impl LibraryScreen {
                         port: self.port,
                         fp_hex: self.fp_hex.clone(),
                         launch: Some(g.id.clone()),
-                        title: g.title.clone(),
+                        // A pinned card's shelf says which profile it is launching with,
+                        // the same way its tile and this screen's title do.
+                        title: match &self.pin {
+                            Some(p) => format!("{} \u{b7} {}", g.title, p.name),
+                            None => g.title.clone(),
+                        },
                         request_access: false,
-                        // Game launches follow the host's default binding.
-                        profile: None,
+                        // A game launch off a PINNED card's shelf is that card's connect
+                        // with a title attached — it carries the card's profile as the
+                        // one-off. Off the primary tile there is none, and the host's
+                        // default binding decides.
+                        profile: self.pin.as_ref().map(|p| p.id.clone()),
                     });
                     Some(MenuPulse::Confirm)
                 }

crates/pf-console-ui/src/shell/tests.rs

@@ -180,6 +180,87 @@ fn finish_motion(s: &mut Shell) {
     s.motion = Motion::None;
 }
 
+/// A pinned host+profile card's library launches with THAT profile (design §5.2a).
+///
+/// The card's plain A-press always carried its profile; Y — which the card offers, being
+/// paired and saved — opened a library screen that knew only the host, so every title
+/// launched off it silently fell back to the host's default binding. The profile a user
+/// pinned is the whole reason they pressed that card.
+#[test]
+fn a_pinned_cards_library_launches_with_its_profile() {
+    let mut rows = hosts();
+    let card = HostRow {
+        key: "aa11\u{0}hdr".into(),
+        pin: Some(crate::model::ProfileChip {
+            id: "hdr".into(),
+            name: "HDR".into(),
+            accent: None,
+        }),
+        ..rows[0].clone()
+    };
+    rows.insert(1, card);
+    let (mut s, console, library) = shell(vec![Screen::Home(HomeScreen::new())]);
+    console.set_hosts(rows);
+    s.sync();
+
+    // Focus the pinned card (it sits right after its host's primary tile), then Y.
+    s.handle_menu(MenuEvent::Move(MenuDir::Right));
+    s.handle_menu(MenuEvent::Secondary);
+    finish_motion(&mut s);
+    match s.stack.last() {
+        Some(Screen::Library(l)) => assert_eq!(
+            l.title(),
+            "Living Room PC \u{b7} HDR",
+            "the shelf names the profile it will launch with"
+        ),
+        _ => panic!("Y on a pinned card opens its library"),
+    }
+
+    library.set_games(vec![crate::library::LibraryGame {
+        id: "steam:570".into(),
+        title: "Dota 2".into(),
+        store: "steam".into(),
+        launcher: false,
+        icon: String::new(),
+    }]);
+    s.handle_menu(MenuEvent::Confirm);
+    match s.take_action() {
+        Some(OverlayAction::Launch {
+            launch, profile, ..
+        }) => {
+            assert_eq!(launch.as_deref(), Some("steam:570"));
+            assert_eq!(
+                profile.as_deref(),
+                Some("hdr"),
+                "the launch carries the pinned card's profile"
+            );
+        }
+        _ => panic!("A on a title raises a launch"),
+    }
+}
+
+/// …and off the host's PRIMARY tile there is no one-off: the host's binding decides,
+/// which is what the resolver sees as `None`.
+#[test]
+fn a_primary_tiles_library_leaves_the_profile_to_the_binding() {
+    let (mut s, _console, library) = shell(vec![Screen::Home(HomeScreen::new())]);
+    s.sync();
+    s.handle_menu(MenuEvent::Secondary); // paired+online host focused first
+    finish_motion(&mut s);
+    library.set_games(vec![crate::library::LibraryGame {
+        id: "steam:570".into(),
+        title: "Dota 2".into(),
+        store: "steam".into(),
+        launcher: false,
+        icon: String::new(),
+    }]);
+    s.handle_menu(MenuEvent::Confirm);
+    assert!(matches!(
+        s.take_action(),
+        Some(OverlayAction::Launch { profile: None, .. })
+    ));
+}
+
 #[test]
 fn wake_gates_input_in_the_same_press() {
     let (mut s, _console, _library) = shell(vec![Screen::Home(HomeScreen::new())]);

crates/pf-driver-proto/src/lib.rs

@@ -1712,7 +1712,13 @@ mod tests {
         let mut legacy = [0u8; 40];
         legacy[..control::ADD_REQUEST_LEGACY_SIZE]
             .copy_from_slice(&bytes[..control::ADD_REQUEST_LEGACY_SIZE]);
-        let old = *bytemuck::from_bytes::<control::AddRequest>(&legacy);
+        // `pod_read_unaligned`, NOT `from_bytes` — same rule as `ChannelProof::parse` above, and
+        // for the same reason. `legacy` is a `[u8; 40]` (align 1) but `AddRequest` opens with a
+        // `u64`, so it is align 8; `from_bytes` takes a REFERENCE into the buffer and panics
+        // unless the buffer happens to be 8-aligned. A stack `[u8; 40]` usually is, which is why
+        // this passed everywhere for so long — Miri caught it because Miri does not let an
+        // accidentally-favourable stack slot stand in for a guarantee.
+        let old = bytemuck::pod_read_unaligned::<control::AddRequest>(&legacy);
         assert_eq!(old.preferred_monitor_id, 7);
         assert_eq!(
             (

crates/pf-dxvadec/src/lib.rs

@@ -52,7 +52,6 @@
 //! ([`dxva::as_bytes`] / [`dxva::slice_bytes`]), fenced behind a sealed trait
 //! that only this crate's `#[repr(C)]` PODs implement, and carrying a written
 //! proof — enforced:
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 pub mod config;
 pub mod descriptors;

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

@@ -48,6 +48,8 @@ impl AvBuffer {
     /// allocator returns on failure (so the `is_null` check every caller used to open-code happens
     /// once, here).
     ///
+    // unsafe-fn-no-op-ok: contract-deferring constructor (`Vec::set_len` shape) — the body is
+    // safe; the ownership transfer promised here is what Drop/as_ptr later rely on.
     /// # Safety
     /// `p` must be null, or a live `AVBufferRef` whose ownership passes to the returned value —
     /// nothing else may unref it.
@@ -117,6 +119,88 @@ impl Drop for AvFilterGraph {
     }
 }
 
+/// An owned `AVFrame`, freed exactly once when it drops.
+///
+/// The house pattern (`AvBuffer` above): `alloc` rejects the allocator's null once, `as_ptr`
+/// lends, `Drop` frees, no `Clone`. Before this type existed the crate held 8 `av_frame_alloc`
+/// sites matched by 22 hand-placed `av_frame_free`s — an ownership contract upheld by nobody,
+/// and broken in practice: the Windows zero-copy submit path leaked the frame AND a pooled
+/// hwframe surface on three `?` exits, under a comment asserting the opposite (fixed in the
+/// same change that introduced this type).
+///
+/// Why not ffmpeg-next's own RAII frame (`frame::Video::empty()`, already used as `VideoFrame`
+/// in the Linux NVENC path): `Frame::empty()` does not null-check — on allocator failure it
+/// wraps null and the next field write through it is UB — whereas every open-coded site here
+/// null-checked. This type keeps that: `alloc` returns `Option`, mirroring
+/// `AvFilterGraph::alloc`.
+pub(crate) struct AvFrame(std::ptr::NonNull<ffi::AVFrame>);
+
+impl AvFrame {
+    /// Allocate a frame, rejecting the null `av_frame_alloc` returns on OOM.
+    ///
+    /// Safe: the call takes no arguments and has no precondition a caller could violate — the
+    /// only contract is what happens to the result, and that is exactly what this type owns.
+    pub(crate) fn alloc() -> Option<Self> {
+        // SAFETY: parameterless allocator; it returns either a fresh, uniquely-owned frame whose
+        // ownership passes to the value returned here, or null (rejected by NonNull::new).
+        std::ptr::NonNull::new(unsafe { ffi::av_frame_alloc() }).map(AvFrame)
+    }
+
+    /// The borrowed pointer, for the ffmpeg calls that fill or read the frame without taking
+    /// ownership of it. Borrowed only — the `AvFrame` stays the owner, so callers must not free
+    /// or move-from what this returns.
+    pub(crate) fn as_ptr(&self) -> *mut ffi::AVFrame {
+        self.0.as_ptr()
+    }
+}
+
+impl Drop for AvFrame {
+    fn drop(&mut self) {
+        let mut p = self.0.as_ptr();
+        // SAFETY: `p` is the non-null frame `alloc` took ownership of, and this type is its
+        // sole owner (neither `Clone` nor `Copy`; `as_ptr` only lends), so this runs exactly
+        // once. `av_frame_free` unrefs any buffers the frame holds (returning pooled hwframe
+        // surfaces to their pool) and frees the frame; it nulls only the local copy.
+        unsafe { ffi::av_frame_free(&mut p) };
+    }
+}
+
+/// An owned swscale context, freed exactly once when it drops.
+///
+/// Same ownership question as the frame above — `sws_getContext` at 3 sites was matched by 5
+/// hand-placed `sws_freeContext`s, two of them inside hand-written `Drop` impls whose real job
+/// this type absorbs.
+pub(crate) struct AvSwsContext(std::ptr::NonNull<ffi::SwsContext>);
+
+impl AvSwsContext {
+    /// Take ownership of a freshly-created `SwsContext`, rejecting the null `sws_getContext`
+    /// returns on failure (unsupported conversion or OOM).
+    ///
+    // unsafe-fn-no-op-ok: contract-deferring constructor (`Vec::set_len` shape) — the body is
+    // safe; the ownership transfer promised here is what Drop/as_ptr later rely on.
+    /// # Safety
+    /// `p` must be null, or a live `SwsContext` whose ownership passes to the returned value —
+    /// nothing else may free it.
+    pub(crate) unsafe fn from_raw(p: *mut ffi::SwsContext) -> Option<Self> {
+        std::ptr::NonNull::new(p).map(AvSwsContext)
+    }
+
+    /// The borrowed pointer, for `sws_scale` calls. Borrowed only — the `AvSwsContext` stays
+    /// the owner.
+    pub(crate) fn as_ptr(&self) -> *mut ffi::SwsContext {
+        self.0.as_ptr()
+    }
+}
+
+impl Drop for AvSwsContext {
+    fn drop(&mut self) {
+        // SAFETY: `self.0` is the non-null context `from_raw` took ownership of, and this type
+        // is its sole owner (neither `Clone` nor `Copy`; `as_ptr` only lends), so this runs
+        // exactly once.
+        unsafe { ffi::sws_freeContext(self.0.as_ptr()) };
+    }
+}
+
 /// One `receive_packet` attempt, with the not-ready states kept distinct so a blocking drain can
 /// tell "still encoding" (retry) from "stream over" (stop). The Linux NVENC/VAAPI polls collapse
 /// `Again`/`Eof` to `None`; the Windows AMF/QSV path keeps them apart for its deadline-driven loop.

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

@@ -12,8 +12,6 @@
 //! does *not* accept — we expand it to `rgb0` (one padding byte/pixel, no colour math).
 //! The encoder is opened *without* a global header so VPS/SPS/PPS are emitted in-band on
 //! every IDR — the output is both a playable raw Annex-B stream and self-contained AUs.
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{ChromaFormat, Codec, EncodedFrame, Encoder};
 use anyhow::{anyhow, bail, Context, Result};
@@ -26,8 +24,8 @@ use std::os::raw::c_int;
 use std::ptr;
 
 use super::libav::{
-    apply_low_latency_rc, pixel_to_av, poll_encoder, AvBuffer, PollOutcome, SWS_CS_ITU709,
-    SWS_POINT,
+    apply_low_latency_rc, pixel_to_av, poll_encoder, AvBuffer, AvFrame, AvSwsContext, PollOutcome,
+    SWS_CS_ITU709, SWS_POINT,
 };
 use ffmpeg::ffi; // = ffmpeg_sys_next
 
@@ -193,6 +191,17 @@ struct OpenArgs {
 }
 
 pub struct NvencEncoder {
+    // FIELD ORDER IS LOAD-BEARING: the hand-written `Drop` this replaced ran before any field
+    // drop, freeing `sws_csc` ahead of `enc`/`frame`/`cuda` — and this path runs on every
+    // stall-watchdog recovery via `*self = fresh` in `reset`. Declaration order is what
+    // preserves that sequence now (drop order follows declaration; an offset_of assert cannot
+    // pin it — repr(Rust) may lay memory out in any order).
+    /// CPU CSC paths only: swscale context converting the captured packed source into
+    /// [`Self::frame`] — RGB/BGR → planar YUV444P for a 4:4:4 session (`hevc_nvenc` only emits
+    /// 4:4:4 from a YUV444 *input*; RGB-in is always 4:2:0), or X2RGB10/X2BGR10 → P010 (BT.2020
+    /// limited) for an HDR session. `None` on the plain RGB paths AND on the zero-copy paths (the
+    /// worker's GPU convert delivers ready CUDA frames).
+    sws_csc: Option<AvSwsContext>,
     enc: encoder::video::Encoder,
     /// Reusable 4-bpp CPU input frame (CPU path only; `None` for the zero-copy/CUDA path).
     /// Mutating it in place across frames is sound only because the encoder is opened with
@@ -201,12 +210,6 @@ pub struct NvencEncoder {
     frame: Option<VideoFrame>,
     /// Zero-copy path: CUDA hwdevice/hwframes contexts (the encoder takes `AV_PIX_FMT_CUDA`).
     cuda: Option<CudaHw>,
-    /// CPU CSC paths only: swscale context converting the captured packed source into
-    /// [`Self::frame`] — RGB/BGR → planar YUV444P for a 4:4:4 session (`hevc_nvenc` only emits
-    /// 4:4:4 from a YUV444 *input*; RGB-in is always 4:2:0), or X2RGB10/X2BGR10 → P010 (BT.2020
-    /// limited) for an HDR session. `None` on the plain RGB paths AND on the zero-copy paths (the
-    /// worker's GPU convert delivers ready CUDA frames). Freed in `Drop`.
-    sws_csc: Option<*mut ffi::SwsContext>,
     /// This session opened as full-chroma 4:4:4 (FREXT) — via either input path.
     want_444: bool,
     src_format: PixelFormat,
@@ -228,7 +231,7 @@ pub struct NvencEncoder {
     args: OpenArgs,
 }
 
-// `CudaHw` holds raw `AVBufferRef`s and `sws_csc` a raw `SwsContext`; the encoder lives on a single
+// `CudaHw` holds raw `AVBufferRef`s and `sws_csc` an owned `SwsContext`; the encoder lives on a single
 // thread. The CPU encoder is already `Send` via ffmpeg-next; assert it for the raw fields too.
 // SAFETY: `NvencEncoder` owns an ffmpeg-next `Encoder`/`VideoFrame` (already `Send`) plus a `CudaHw`
 // holding raw `AVBufferRef`s and an optional raw `SwsContext`, none of which are `Send` by default.
@@ -610,14 +613,13 @@ impl NvencEncoder {
             );
         }
 
-        // Built HERE, below the fallible encoder open, NOT above it. `sws_getContext` returns a raw
-        // pointer whose only free is `Drop for NvencEncoder` — and `Drop` needs a CONSTRUCTED
-        // `Self`, which does not exist on `open`'s early returns (the intra-refresh-unsupported
-        // retry, which recurses into `Self::open`, and the plain error return). Creating the
-        // context above them leaked one per failed attempt, and `open_nvenc_probed`'s EINVAL
-        // bitrate ladder calls `open` up to ~10 times, so a host stepping its bitrate down leaked a
-        // context per step. Nothing between here and the `Ok(NvencEncoder { … })` below can return,
-        // so this placement makes the leak unrepresentable rather than merely unlikely.
+        // Built HERE, below the fallible encoder open, NOT above it — historically because the
+        // context's only free was `Drop for NvencEncoder`, which needs a CONSTRUCTED `Self` that
+        // does not exist on `open`'s early returns; creating it above them leaked one per failed
+        // attempt, and `open_nvenc_probed`'s EINVAL bitrate ladder calls `open` up to ~10 times.
+        // The owned `AvSwsContext` now frees itself on any exit, but the placement stays: it
+        // documents the dependency on the post-open `nvenc_pixel`, and there is no reason to
+        // build a context an early return would just throw away.
         // CPU CSC paths: build the packed-RGB → planar swscale (no rescale) into the encoder's
         // input frame. THREE users: 4:4:4 (RGB→YUV444P, BT.709, range per the flag), HDR
         // (X2RGB10/X2BGR10→P010, BT.2020 limited — the PQ transfer is per-channel and rides
@@ -642,10 +644,10 @@ impl NvencEncoder {
             // formats. Both dims are the encoder's positive `width`/`height` as `c_int`; `src_av` is a
             // valid `AVPixelFormat` (from the `sws_src_pixel`-validated packed-RGB source), the dst is
             // YUV444P (4:4:4) or P010LE (HDR). The trailing filter/param pointers are null = "use
-            // defaults" (documented as accepted). No Rust memory is borrowed; the returned pointer is
-            // null-checked below.
+            // defaults" (documented as accepted). No Rust memory is borrowed; ownership of the
+            // returned context passes to the `AvSwsContext` (null rejected by `from_raw`).
             let sws = unsafe {
-                ffi::sws_getContext(
+                AvSwsContext::from_raw(ffi::sws_getContext(
                     width as c_int,
                     height as c_int,
                     src_av,
@@ -656,11 +658,11 @@ impl NvencEncoder {
                     ptr::null_mut(),
                     ptr::null_mut(),
                     ptr::null(),
-                )
+                ))
             };
-            if sws.is_null() {
+            let Some(sws) = sws else {
                 bail!("sws_getContext(RGB→{nvenc_pixel:?}) failed");
-            }
+            };
             // Colour math applies to the CSC users ONLY. The expand is a pure byte shuffle —
             // packed 3-bpp RGB/BGR to the same channels in 4 bytes, `nvenc_pixel` being `rgb0`/
             // `bgr0` — and NVENC does the RGB→YUV itself downstream. Handing it a matrix + range
@@ -680,7 +682,16 @@ impl NvencEncoder {
                         SWS_CS_ITU709
                     });
                     let dst_range = i32::from(full_range_444);
-                    ffi::sws_setColorspaceDetails(sws, cs, 1, cs, dst_range, 0, 1 << 16, 1 << 16);
+                    ffi::sws_setColorspaceDetails(
+                        sws.as_ptr(),
+                        cs,
+                        1,
+                        cs,
+                        dst_range,
+                        0,
+                        1 << 16,
+                        1 << 16,
+                    );
                 }
             }
             Some(sws)
@@ -694,10 +705,10 @@ impl NvencEncoder {
             Some(VideoFrame::new(nvenc_pixel, width, height))
         };
         Ok(NvencEncoder {
+            sws_csc,
             enc,
             frame,
             cuda: cuda_hw,
-            sws_csc,
             want_444,
             src_format: format,
             width,
@@ -840,7 +851,7 @@ impl NvencEncoder {
         // three CSC users (see `open`): 4:4:4 → planar YUV444P, HDR → P010, and the packed 3-bpp
         // expand → `rgb0`/`bgr0`. The remaining branch below is the 4-bpp source, which needs no
         // conversion at all — just a row copy honouring the destination stride.
-        if let Some(sws) = self.sws_csc {
+        if let Some(sws) = self.sws_csc.as_ref().map(AvSwsContext::as_ptr) {
             let frame = self
                 .frame
                 .as_mut()
@@ -929,27 +940,23 @@ impl NvencEncoder {
         // SAFETY: `frames_ref` is the non-null CUDA frames ctx from `self.cuda` (unwrapped via
         // `.context(..)?` above), and the shared CUDA context was just made current on THIS thread
         // (`make_current()?`), the precondition for the device-pointer copies below.
-        //  * `av_frame_alloc` → `f` (null-checked). `av_hwframe_get_buffer(frames_ref, f, 0)` fills `f`
-        //    with a pooled CUDA surface (sets `data[]`/`linesize[]`/`buf[0]`/`hw_frames_ctx`); on
-        //    failure we free `f` and bail.
-        //  * For NV12 we read `(*f).data[0..2]` / `linesize[0..2]` (Y + interleaved UV), else
-        //    `data[0]`/`linesize[0]` — in-struct fields of the non-null `f`, valid for the surface dims
-        //    ffmpeg allocated — and pass them to the cuda copy helpers, which device→device copy `buf`
-        //    (the imported `DeviceBuffer`, owned by the caller and live for this call) into the surface.
-        //  * On copy error we free `f` and return. Otherwise we write `pts`/`pict_type` through `f` and
-        //    `avcodec_send_frame` it into the live owned `self.enc` context (which takes its own ref of
-        //    the pooled surface), then free our `f` ref exactly once. Single-threaded encoder → no race.
+        //  * `f` is an owned `AvFrame` — every exit below (bail, copy error, success) drops it
+        //    exactly once, releasing its ref on the pooled surface. `av_hwframe_get_buffer` fills
+        //    it with a pooled CUDA surface (sets `data[]`/`linesize[]`/`buf[0]`/`hw_frames_ctx`).
+        //  * For NV12 we read `data[0..2]` / `linesize[0..2]` (Y + interleaved UV), else
+        //    `data[0]`/`linesize[0]` — in-struct fields of the live frame, valid for the surface
+        //    dims ffmpeg allocated — and pass them to the cuda copy helpers, which device→device
+        //    copy `buf` (the imported `DeviceBuffer`, owned by the caller and live for this call)
+        //    into the surface.
+        //  * `avcodec_send_frame` takes its own ref of the pooled surface, so the drop afterwards
+        //    is the sole owning free. Single-threaded encoder → no race.
         unsafe {
-            let mut f = ffi::av_frame_alloc();
-            if f.is_null() {
-                bail!("av_frame_alloc failed");
-            }
+            let f = AvFrame::alloc().context("av_frame_alloc failed")?;
             // Pooled CUDA surface: sets format, width/height, data[0]/linesize[0], buf[0] and
             // hw_frames_ctx. Reused across frames (the pool recycles), keeping NVENC's
             // registration cache warm.
-            let r = ffi::av_hwframe_get_buffer(frames_ref, f, 0);
+            let r = ffi::av_hwframe_get_buffer(frames_ref, f.as_ptr(), 0);
             if r < 0 {
-                ffi::av_frame_free(&mut f);
                 bail!("av_hwframe_get_buffer(CUDA) failed ({r})");
             }
             // NV12 surfaces are two-plane (Y in data[0], interleaved UV in data[1]); YUV444
@@ -960,41 +967,36 @@ impl NvencEncoder {
             let copy_res = if buf.yuv444 {
                 let dsts = core::array::from_fn(|i| {
                     (
-                        (*f).data[i] as pf_zerocopy::cuda::CUdeviceptr,
-                        (*f).linesize[i] as usize,
+                        (*f.as_ptr()).data[i] as pf_zerocopy::cuda::CUdeviceptr,
+                        (*f.as_ptr()).linesize[i] as usize,
                     )
                 });
                 pf_zerocopy::cuda::copy_yuv444_to_device(buf, dsts, true)
             } else if self.want_444 {
-                ffi::av_frame_free(&mut f);
                 bail!(
                     "4:4:4 session but the zero-copy frame is not YUV444 (LINEAR/gamescope \
                      capture has no GPU 4:4:4 convert) — unset PUNKTFUNK_ZEROCOPY to use the \
                      CPU 4:4:4 path on this compositor"
                 );
             } else if buf.is_nv12() {
-                let y_ptr = (*f).data[0] as pf_zerocopy::cuda::CUdeviceptr;
-                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;
+                let y_ptr = (*f.as_ptr()).data[0] as pf_zerocopy::cuda::CUdeviceptr;
+                let y_pitch = (*f.as_ptr()).linesize[0] as usize;
+                let uv_ptr = (*f.as_ptr()).data[1] as pf_zerocopy::cuda::CUdeviceptr;
+                let uv_pitch = (*f.as_ptr()).linesize[1] as usize;
                 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;
+                let dst_ptr = (*f.as_ptr()).data[0] as pf_zerocopy::cuda::CUdeviceptr;
+                let dst_pitch = (*f.as_ptr()).linesize[0] as usize;
                 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);
-                return Err(e).context("copy imported buffer into NVENC surface");
-            }
-            (*f).pts = pts;
-            (*f).pict_type = if idr {
+            copy_res.context("copy imported buffer into NVENC surface")?;
+            (*f.as_ptr()).pts = pts;
+            (*f.as_ptr()).pict_type = if idr {
                 ffi::AVPictureType::AV_PICTURE_TYPE_I
             } else {
                 ffi::AVPictureType::AV_PICTURE_TYPE_NONE
             };
-            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), f);
-            ffi::av_frame_free(&mut f);
+            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), f.as_ptr());
             if r < 0 {
                 bail!("avcodec_send_frame(CUDA) failed ({r})");
             }
@@ -1003,16 +1005,9 @@ impl NvencEncoder {
     }
 }
 
-impl Drop for NvencEncoder {
-    fn drop(&mut self) {
-        if let Some(sws) = self.sws_csc.take() {
-            // SAFETY: `sws` is the non-null `SwsContext` allocated by `sws_getContext` in `open` and
-            // owned exclusively by this encoder (taken out of the field so it can't be freed twice).
-            // `sws_freeContext` frees it; nothing else references it after this single-threaded drop.
-            unsafe { ffi::sws_freeContext(sws) };
-        }
-    }
-}
+// No `Drop` for `NvencEncoder`: `sws_csc` (`Option<AvSwsContext>`) frees itself, and as field #1
+// it does so ahead of `enc`/`frame`/`cuda` — the same sequence the hand-written `Drop` performed
+// (see the field-order note on the struct).
 
 /// Serialises the save → `AV_LOG_FATAL` → restore window that every capability probe opens around
 /// an encoder open it *expects* to fail.

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

@@ -63,8 +63,6 @@
 // the signature. Clearing this file means DELETING the markers that carry no caller contract, not
 // wrapping the calls — until then the lint is off HERE and enforced everywhere else.
 #![allow(unsafe_op_in_unsafe_fn)]
-// Every `unsafe` block / impl in this file carries a `// SAFETY:` proof; enforce it.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::nvenc_core::{
     apply_low_latency_config, build_init_params, cached_ceiling, cached_split_verdict, codec_guid,

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

@@ -19,8 +19,6 @@
 //! hwdevice/hwframes/buffersrc/buffersink calls go through `ffmpeg::ffi` (= `ffmpeg_sys_next`),
 //! as the CUDA encode path and the clients' decode paths already do. The encoder is opened
 //! *without* a global header, so VPS/SPS/PPS are in-band on every IDR.
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{Codec, EncodedFrame, Encoder};
 use anyhow::{anyhow, bail, Context, Result};
@@ -36,8 +34,8 @@ use std::ptr;
 use std::sync::{Mutex, OnceLock};
 
 use super::libav::{
-    apply_low_latency_rc, pixel_to_av, poll_encoder, AvBuffer, AvFilterGraph, PollOutcome,
-    SWS_CS_ITU709, SWS_POINT,
+    apply_low_latency_rc, pixel_to_av, poll_encoder, AvBuffer, AvFilterGraph, AvFrame,
+    AvSwsContext, PollOutcome, SWS_CS_ITU709, SWS_POINT,
 };
 use ffmpeg::ffi; // = ffmpeg_sys_next
 
@@ -546,8 +544,13 @@ impl VaapiHw {
 struct CpuInner {
     enc: encoder::video::Encoder,
     hw: VaapiHw,
-    sws: *mut ffi::SwsContext,
-    nv12: *mut ffi::AVFrame, // reusable software NV12 staging frame (swscale dst → upload src)
+    // FIELD ORDER IS LOAD-BEARING: the hand-written `Drop` this replaced freed `nv12` BEFORE
+    // `sws` — the reverse of the old declaration order — and field-DECLARATION order is what
+    // preserves that now (drop order follows declaration; an offset_of assert cannot pin it,
+    // repr(Rust) may lay memory out in any order).
+    /// Reusable software NV12/P010 staging frame (swscale dst → upload src).
+    nv12: AvFrame,
+    sws: AvSwsContext,
     src_format: PixelFormat,
     width: u32,
     height: u32,
@@ -602,10 +605,10 @@ impl CpuInner {
         // `src_av` is a valid `AVPixelFormat` (from `pixel_to_av` of the `vaapi_sws_src`-validated
         // `src_pixel`), the dst is NV12/P010. The three trailing pointers (srcFilter, dstFilter,
         // param) are explicitly null = "use defaults", which the API documents as accepted. No Rust
-        // memory is borrowed — only by-value ints/enums — and the returned pointer is null-checked
-        // just below.
+        // memory is borrowed — only by-value ints/enums — and ownership of the returned context
+        // passes to the `AvSwsContext` (null rejected by `from_raw`).
         let sws = unsafe {
-            ffi::sws_getContext(
+            AvSwsContext::from_raw(ffi::sws_getContext(
                 width as c_int,
                 height as c_int,
                 src_av,
@@ -616,16 +619,15 @@ impl CpuInner {
                 ptr::null_mut(),
                 ptr::null_mut(),
                 ptr::null(),
-            )
+            ))
         };
-        if sws.is_null() {
+        let Some(sws) = sws else {
             bail!(
                 "sws_getContext(RGB→{})",
                 if ten_bit { "P010" } else { "NV12" }
             );
-        }
-        // SAFETY: `sws` is the non-null `SwsContext` from `sws_getContext` above (the `is_null()`
-        // check immediately preceding returned false). The coefficient table from
+        };
+        // SAFETY: `sws` is the live owned context from above. The coefficient table from
         // `sws_getCoefficients` (ITU-709, or BT.2020 NCL for the HDR path — matching the VUI) is a
         // libswscale static const valid for the whole process, reused here for both the inverse
         // (src) and forward (dst) matrices. `sws_setColorspaceDetails` only reads those tables and
@@ -637,32 +639,22 @@ impl CpuInner {
             } else {
                 SWS_CS_ITU709
             });
-            ffi::sws_setColorspaceDetails(sws, cs, 1, cs, 0, 0, 1 << 16, 1 << 16);
+            ffi::sws_setColorspaceDetails(sws.as_ptr(), cs, 1, cs, 0, 0, 1 << 16, 1 << 16);
         }
-        // SAFETY: `av_frame_alloc` returns a fresh, uniquely-owned heap `AVFrame` (null-checked — on
-        // null we free the already-built `sws` and bail). We then write the plain `format`/`width`/
-        // `height` fields through the non-null, properly-aligned `f` (sole owner, not yet shared).
-        // `av_frame_get_buffer(f, 0)` allocates backing storage for those dims/format; on failure we
-        // free `f` and `sws` (unwinding the half-built state) and bail. On success `f` is a fully-owned
-        // NV12/P010 frame stored in `CpuInner.nv12` and freed once in `CpuInner::drop`. `f` is a
-        // unique fresh pointer, so none of these writes alias anything.
-        let nv12 = unsafe {
-            let f = ffi::av_frame_alloc();
-            if f.is_null() {
-                ffi::sws_freeContext(sws);
-                bail!("av_frame_alloc(staging) failed");
-            }
-            (*f).format = staging_av as c_int;
-            (*f).width = width as c_int;
-            (*f).height = height as c_int;
-            if ffi::av_frame_get_buffer(f, 0) < 0 {
-                let mut f = f;
-                ffi::av_frame_free(&mut f);
-                ffi::sws_freeContext(sws);
+        let nv12 = AvFrame::alloc().context("av_frame_alloc(staging) failed")?;
+        // SAFETY: writing the plain `format`/`width`/`height` fields through the owned frame's
+        // pointer stays inside its allocation (sole owner, not yet shared).
+        // `av_frame_get_buffer` allocates backing storage for those dims/format; on failure the
+        // owned `nv12` (and the `sws` above it) simply drop — the hand-written unwind this
+        // replaced had to free both by hand on every branch.
+        unsafe {
+            (*nv12.as_ptr()).format = staging_av as c_int;
+            (*nv12.as_ptr()).width = width as c_int;
+            (*nv12.as_ptr()).height = height as c_int;
+            if ffi::av_frame_get_buffer(nv12.as_ptr(), 0) < 0 {
                 bail!("av_frame_get_buffer(staging) failed");
             }
-            f
-        };
+        }
         tracing::info!(
             encoder = codec.vaapi_name(),
             "VAAPI encode active ({width}x{height}@{fps}, CPU→{} upload path)",
@@ -671,8 +663,8 @@ impl CpuInner {
         Ok(CpuInner {
             enc,
             hw,
-            sws,
             nv12,
+            sws,
             src_format: format,
             width,
             height,
@@ -693,49 +685,43 @@ impl CpuInner {
         // `bytes.len() >= src_row * h`. `sws_scale` reads `h` rows of `src_row` bytes from
         // `src_data[0] = bytes.as_ptr()` (the other planes null/0 — packed RGB is single-plane), all
         // in bounds; `bytes`, `src_data`, `src_stride` are live locals for this synchronous call.
-        // `self.sws` is the non-null context built in `open`; it writes into `self.nv12` (a non-null
-        // owned frame whose `data`/`linesize` in-struct arrays were sized by `av_frame_get_buffer`).
-        // `av_frame_alloc` (null-checked) yields a fresh `hwf`; `av_hwframe_get_buffer` pulls a pooled
-        // VAAPI surface from the live non-null `self.hw.frames_ref`; `av_hwframe_transfer_data` uploads
-        // the staged NV12 into it — both frames live, failures free `hwf` and bail. We then write
-        // `pts`/`pict_type` through the non-null `hwf` and `avcodec_send_frame` it into the live
-        // owned `self.enc` context (which takes its own ref), then free our `hwf` ref exactly once.
-        // The encoder runs only on this thread (see `unsafe impl Send`), so no aliasing/data race.
+        // `self.sws` is the owned context built in `open`; it writes into `self.nv12` (an owned
+        // frame whose `data`/`linesize` in-struct arrays were sized by `av_frame_get_buffer`).
+        // `hwf` is an owned `AvFrame` — every exit below drops it exactly once, releasing its ref
+        // on the pooled VAAPI surface. `av_hwframe_get_buffer` pulls that surface from the live
+        // non-null `self.hw.frames_ref`; `av_hwframe_transfer_data` uploads the staged NV12 into
+        // it. `avcodec_send_frame` takes its own ref, so the drop afterwards is the sole owning
+        // free. The encoder runs only on this thread (see `unsafe impl Send`), so no
+        // aliasing/data race.
         unsafe {
             let src_data: [*const u8; 4] = [bytes.as_ptr(), ptr::null(), ptr::null(), ptr::null()];
             let src_stride: [c_int; 4] = [src_row as c_int, 0, 0, 0];
             if ffi::sws_scale(
-                self.sws,
+                self.sws.as_ptr(),
                 src_data.as_ptr(),
                 src_stride.as_ptr(),
                 0,
                 h as c_int,
-                (*self.nv12).data.as_ptr(),
-                (*self.nv12).linesize.as_ptr(),
+                (*self.nv12.as_ptr()).data.as_ptr(),
+                (*self.nv12.as_ptr()).linesize.as_ptr(),
             ) < 0
             {
                 bail!("sws_scale RGB→NV12 failed");
             }
-            let mut hwf = ffi::av_frame_alloc();
-            if hwf.is_null() {
-                bail!("av_frame_alloc(hw) failed");
-            }
-            if ffi::av_hwframe_get_buffer(self.hw.frames_ref.as_ptr(), hwf, 0) < 0 {
-                ffi::av_frame_free(&mut hwf);
+            let hwf = AvFrame::alloc().context("av_frame_alloc(hw) failed")?;
+            if ffi::av_hwframe_get_buffer(self.hw.frames_ref.as_ptr(), hwf.as_ptr(), 0) < 0 {
                 bail!("av_hwframe_get_buffer(VAAPI) failed");
             }
-            if ffi::av_hwframe_transfer_data(hwf, self.nv12, 0) < 0 {
-                ffi::av_frame_free(&mut hwf);
+            if ffi::av_hwframe_transfer_data(hwf.as_ptr(), self.nv12.as_ptr(), 0) < 0 {
                 bail!("av_hwframe_transfer_data(→VAAPI) failed");
             }
-            (*hwf).pts = pts;
-            (*hwf).pict_type = if idr {
+            (*hwf.as_ptr()).pts = pts;
+            (*hwf.as_ptr()).pict_type = if idr {
                 ffi::AVPictureType::AV_PICTURE_TYPE_I
             } else {
                 ffi::AVPictureType::AV_PICTURE_TYPE_NONE
             };
-            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), hwf);
-            ffi::av_frame_free(&mut hwf);
+            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), hwf.as_ptr());
             if r < 0 {
                 bail!("avcodec_send_frame(VAAPI) failed ({r})");
             }
@@ -744,24 +730,10 @@ impl CpuInner {
     }
 }
 
-impl Drop for CpuInner {
-    fn drop(&mut self) {
-        // SAFETY: `self.nv12` (an owned `AVFrame`) and `self.sws` (an owned `SwsContext`) are each
-        // freed exactly once here, guarded by `is_null()` so a never-set pointer is skipped (no double
-        // free). `CpuInner` owns both exclusively and `Drop` runs once. `av_frame_free` takes `&mut`
-        // and nulls the pointer. `self.enc`/`self.hw` are freed afterward by their own `Drop` impls;
-        // the encoder holds its own `av_buffer_ref`'d device/frames copies, so field-drop order is
-        // irrelevant to soundness.
-        unsafe {
-            if !self.nv12.is_null() {
-                ffi::av_frame_free(&mut self.nv12);
-            }
-            if !self.sws.is_null() {
-                ffi::sws_freeContext(self.sws);
-            }
-        }
-    }
-}
+// No `Drop` for `CpuInner`: `nv12` (`AvFrame`) and `sws` (`AvSwsContext`) free themselves, in
+// field-declaration order — the same nv12-then-sws sequence the hand-written `Drop` performed
+// (see the field-order note on the struct). The encoder holds its own `av_buffer_ref`'d
+// device/frames copies, so their order against `enc`/`hw` is irrelevant to soundness.
 
 // ---------------------------------------------------------------------------------------------
 // Zero-copy dmabuf path: DRM-PRIME → hwmap(vaapi) → scale_vaapi(nv12) filter graph → encode.
@@ -1043,16 +1015,20 @@ impl DmabufInner {
         //    whole synchronous `submit`; we describe one object/layer/plane from its
         //    fourcc/modifier/offset/stride and its `lseek`-queried size. `libc::lseek` on that live
         //    fd only reads the description's size and returns it (or -1); it touches no Rust memory.
-        //  * `av_frame_alloc` → `drm` (null-checked); we set its scalar fields and
-        //    `hw_frames_ctx = av_buffer_ref(self.drm_frames)` (new ref of the live owned ctx).
+        //  * `drm`/`nv12` are owned `AvFrame`s — every exit drops each exactly once (the
+        //    hand-placed frees this replaced were branch-clean, but only by inspection). We set
+        //    `drm`'s scalar fields and `hw_frames_ctx = av_buffer_ref(self.drm_frames)` (new ref
+        //    of the live owned ctx).
         //  * `data[0] = Box::into_raw(desc)` transfers the box into the frame; `buf[0] =
         //    av_buffer_create(.., free_desc, ..)` registers a destructor that reclaims it exactly once
         //    when the buffer's refcount hits zero — matched alloc/free, no leak/double-free.
         //  * `av_buffersrc_add_frame_flags(self.src, drm, KEEP_REF)` pushes a ref into the live
-        //    buffersrc; KEEP_REF keeps our own `drm` ref, which we then `av_frame_free`. We pull the
-        //    converted surface with `av_buffersink_get_frame(self.sink, nv12)` BEFORE returning, so the
-        //    dmabuf (owned by the caller) is read while still valid. `nv12` is sent into the live owned
-        //    `self.enc` (takes its own ref) and our ref freed once. Single-threaded encoder → no race.
+        //    buffersrc; KEEP_REF keeps our own `drm` ref, dropped explicitly right after the push
+        //    (the same point the hand-written free sat, kept so the descriptor's release timing
+        //    across the pull does not change). We pull the converted surface with
+        //    `av_buffersink_get_frame(self.sink, nv12)` BEFORE returning, so the dmabuf (owned by
+        //    the caller) is read while still valid. `nv12` is sent into the live owned `self.enc`
+        //    (takes its own ref) and dropped. Single-threaded encoder → no race.
         unsafe {
             // Build a DRM-PRIME AVFrame describing the dmabuf (one object/fd, one layer/plane).
             let mut desc: Box<ffi::AVDRMFrameDescriptor> = Box::new(std::mem::zeroed());
@@ -1077,21 +1053,18 @@ impl DmabufInner {
             desc.layers[0].planes[0].offset = dmabuf.offset as isize;
             desc.layers[0].planes[0].pitch = dmabuf.stride as isize;
 
-            let mut drm = ffi::av_frame_alloc();
-            if drm.is_null() {
-                bail!("av_frame_alloc(drm) failed");
-            }
-            (*drm).format = ffi::AVPixelFormat::AV_PIX_FMT_DRM_PRIME as c_int;
-            (*drm).width = self.width as c_int;
-            (*drm).height = self.height as c_int;
+            let drm = AvFrame::alloc().context("av_frame_alloc(drm) failed")?;
+            (*drm.as_ptr()).format = ffi::AVPixelFormat::AV_PIX_FMT_DRM_PRIME as c_int;
+            (*drm.as_ptr()).width = self.width as c_int;
+            (*drm.as_ptr()).height = self.height as c_int;
             // The dmabuf is the compositor's rendered desktop: full-range RGB. Tag the frame so
             // the VPP's colour negotiation sees the real input instead of "unspecified" (an
             // untagged input lets the driver pick its own default for the RGB→NV12 conversion —
             // Mesa's is BT.601, contradicting the BT.709-limited VUI the encoder signals).
-            (*drm).color_range = ffi::AVColorRange::AVCOL_RANGE_JPEG;
-            (*drm).colorspace = ffi::AVColorSpace::AVCOL_SPC_RGB;
-            (*drm).hw_frames_ctx = ffi::av_buffer_ref(self.drm_frames.as_ptr());
-            (*drm).data[0] = Box::into_raw(desc) as *mut u8;
+            (*drm.as_ptr()).color_range = ffi::AVColorRange::AVCOL_RANGE_JPEG;
+            (*drm.as_ptr()).colorspace = ffi::AVColorSpace::AVCOL_SPC_RGB;
+            (*drm.as_ptr()).hw_frames_ctx = ffi::av_buffer_ref(self.drm_frames.as_ptr());
+            (*drm.as_ptr()).data[0] = Box::into_raw(desc) as *mut u8;
             // Own the descriptor so it frees with the frame (the fd is owned by the DmabufFrame,
             // which outlives this call — the graph reads the surface before submit returns).
             extern "C" fn free_desc(_opaque: *mut std::ffi::c_void, data: *mut u8) {
@@ -1102,8 +1075,8 @@ impl DmabufInner {
                 // reclaims it exactly once — no double-free. `_opaque` is unused (we passed null).
                 unsafe { drop(Box::from_raw(data as *mut ffi::AVDRMFrameDescriptor)) };
             }
-            (*drm).buf[0] = ffi::av_buffer_create(
-                (*drm).data[0],
+            (*drm.as_ptr()).buf[0] = ffi::av_buffer_create(
+                (*drm.as_ptr()).data[0],
                 std::mem::size_of::<ffi::AVDRMFrameDescriptor>(),
                 Some(free_desc),
                 ptr::null_mut(),
@@ -1113,45 +1086,40 @@ impl DmabufInner {
             // Push through hwmap → scale_vaapi; pull the NV12 surface back out.
             let r = ffi::av_buffersrc_add_frame_flags(
                 self.src,
-                drm,
+                drm.as_ptr(),
                 ffi::AV_BUFFERSRC_FLAG_KEEP_REF as c_int,
             );
-            ffi::av_frame_free(&mut drm);
-            // These two stages ARE the import: the push hands libav our DRM-PRIME descriptor, and
-            // the pull is where `hwmap` actually maps it into a VA surface (and `scale_vaapi` runs
-            // the CSC). A failure here means this driver would not take this compositor's dmabuf —
-            // which no encoder rebuild can fix — so tell the process-wide latch, and capture
-            // negotiates CPU frames from the next session on. `avcodec_send_frame` below is
-            // deliberately NOT counted: that one is the encoder stalling, which the in-place
-            // rebuild above us exists to recover, and disabling zero-copy over it would be a
-            // permanent penalty for a transient fault.
+            drop(drm); // release our ref where the hand-written free sat (see the SAFETY note)
+                       // These two stages ARE the import: the push hands libav our DRM-PRIME descriptor, and
+                       // the pull is where `hwmap` actually maps it into a VA surface (and `scale_vaapi` runs
+                       // the CSC). A failure here means this driver would not take this compositor's dmabuf —
+                       // which no encoder rebuild can fix — so tell the process-wide latch, and capture
+                       // negotiates CPU frames from the next session on. `avcodec_send_frame` below is
+                       // deliberately NOT counted: that one is the encoder stalling, which the in-place
+                       // rebuild above us exists to recover, and disabling zero-copy over it would be a
+                       // permanent penalty for a transient fault.
             if r < 0 {
                 let e = format!("av_buffersrc_add_frame failed ({r})");
                 pf_zerocopy::note_raw_dmabuf_import_failure(&e);
                 bail!("{e}");
             }
             t_push = t0.elapsed();
-            let mut nv12 = ffi::av_frame_alloc();
-            if nv12.is_null() {
-                bail!("av_frame_alloc(nv12) failed");
-            }
-            let r = ffi::av_buffersink_get_frame(self.sink, nv12);
+            let nv12 = AvFrame::alloc().context("av_frame_alloc(nv12) failed")?;
+            let r = ffi::av_buffersink_get_frame(self.sink, nv12.as_ptr());
             if r < 0 {
-                ffi::av_frame_free(&mut nv12);
                 let e = format!("av_buffersink_get_frame failed ({r})");
                 pf_zerocopy::note_raw_dmabuf_import_failure(&e);
                 bail!("{e}");
             }
             pf_zerocopy::note_raw_dmabuf_import_ok();
             t_pull = t0.elapsed() - t_push;
-            (*nv12).pts = pts;
-            (*nv12).pict_type = if idr {
+            (*nv12.as_ptr()).pts = pts;
+            (*nv12.as_ptr()).pict_type = if idr {
                 ffi::AVPictureType::AV_PICTURE_TYPE_I
             } else {
                 ffi::AVPictureType::AV_PICTURE_TYPE_NONE
             };
-            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), nv12);
-            ffi::av_frame_free(&mut nv12);
+            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), nv12.as_ptr());
             if r < 0 {
                 bail!("avcodec_send_frame(VAAPI) failed ({r})");
             }

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

@@ -17,7 +17,7 @@
 // child-module shape. External imports are this file's own; `vk_util` is a crate-root sibling,
 // so the path is `crate::`, not the parent-relative `super::` the parent uses.
 use super::*;
-use crate::vk_util::{find_mem, make_plain_image, make_view};
+use crate::vk_util::{ext_advertised, find_mem, make_plain_image, make_view};
 use anyhow::{bail, Result};
 use ash::vk;
 use std::ffi::c_void;
@@ -53,10 +53,10 @@ pub(super) unsafe fn probe_rgb_direct(
     let Ok(exts) = instance.enumerate_device_extension_properties(pd) else {
         return Err("probe-failed(ext-enum)");
     };
-    if !exts
-        .iter()
-        .any(|e| std::ffi::CStr::from_ptr(e.extension_name.as_ptr()) == vrgb::EXTENSION_NAME)
-    {
+    // Route through `vk_util::ext_advertised` rather than open-coding the walk a second time:
+    // this copy used the same unbounded `CStr::from_ptr` and had the same read-past-the-array
+    // hazard on a driver that fills all VK_MAX_EXTENSION_NAME_SIZE bytes without a NUL.
+    if !ext_advertised(&exts, vrgb::EXTENSION_NAME) {
         return Err("no-ext(mesa<26.0-or-no-efc)");
     }
     // 2. Feature bit.

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

@@ -19,11 +19,15 @@ use pf_frame::PixelFormat;
 /// barriers were used without the extension ever being enabled; `pf-presenter/dmabuf.rs` is the
 /// in-repo precedent that enables it).
 pub(super) fn ext_advertised(exts: &[vk::ExtensionProperties], name: &std::ffi::CStr) -> bool {
-    exts.iter().any(|e| {
-        // SAFETY: `extension_name` is a spec-guaranteed NUL-terminated UTF-8 byte array inside
-        // the driver-filled `VkExtensionProperties` (VK_MAX_EXTENSION_NAME_SIZE bound).
-        unsafe { std::ffi::CStr::from_ptr(e.extension_name.as_ptr()) == name }
-    })
+    // `extension_name_as_c_str()` is ash's BOUNDED accessor: it stops at
+    // `VK_MAX_EXTENSION_NAME_SIZE` and returns `Err` when the array holds no NUL, so a
+    // malformed driver entry is a non-match rather than a read past the array. The previous
+    // `CStr::from_ptr(e.extension_name.as_ptr())` had no in-Rust bound at all — its SAFETY
+    // comment asserted the spec guarantee instead of enforcing it, so a driver that filled all
+    // 256 bytes without a terminator ran the walk into the NEXT `ExtensionProperties` and, on
+    // the last element, past the allocation. Same accessor `pyrowave.rs` already uses for the
+    // identical job. No unsafe, no unchecked read, same answer on every well-formed driver.
+    exts.iter().any(|e| e.extension_name_as_c_str() == Ok(name))
 }
 
 pub(crate) fn color_range(layer: u32) -> vk::ImageSubresourceRange {
@@ -453,6 +457,29 @@ mod tests {
         ));
     }
 
+    /// A driver entry with NO terminator anywhere in `extension_name` must be a non-match, not a
+    /// read past the array.
+    ///
+    /// This is the case the old `CStr::from_ptr(e.extension_name.as_ptr())` could not survive:
+    /// with every one of VK_MAX_EXTENSION_NAME_SIZE bytes non-NUL it walked into the NEXT
+    /// `ExtensionProperties`, and on the LAST element past the allocation entirely. The old test
+    /// only ever built well-formed, NUL-terminated entries, so it proved nothing about the bound
+    /// — which is why the hazard survived a SAFETY comment that asserted the spec guarantee
+    /// rather than enforcing it.
+    #[test]
+    fn ext_advertised_rejects_unterminated_name_without_overrunning() {
+        let mut bad = ash::vk::ExtensionProperties::default();
+        bad.extension_name.fill(b'A' as std::ffi::c_char);
+        // Deliberately LAST, so an unbounded walk would leave the whole array.
+        let exts = [ash::vk::ExtensionProperties::default(), bad];
+        assert!(!super::ext_advertised(
+            &exts,
+            ash::ext::queue_family_foreign::NAME
+        ));
+        // And a name that is a prefix of the garbage still must not match.
+        assert!(!super::ext_advertised(&exts, c"AAAA"));
+    }
+
     use super::*;
 
     /// CSC mode (`bgra_target = false`): the 3→4 expand is a pure byte shuffle — no channel

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

@@ -41,9 +41,6 @@
 //! worker caches it, so the steady state passes **zero** descriptors (the PipeWire pool recycles a
 //! small buffer set).
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use anyhow::{Context, Result};
 use pf_frame::{CapturedFrame, CursorOverlay, DmabufFrame, FramePayload, PixelFormat};
 use pf_zerocopy::ipc;

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

@@ -5,12 +5,16 @@
 //! `libloading`), the device binding (D3D11 vs CUDA), input-surface registration, and the
 //! Windows-only async retrieve — stay in their backends. Sibling of [`super::nvenc_status`].
 
-// UNSAFE-LINT EXEMPTION (rationale + exit criteria: `unsafe_op_in_unsafe_fn` in the workspace
-// Cargo.toml). This body is raw `nvEncodeAPI` entry-table calls almost line for line; narrowing it
-// would add one `unsafe {}` plus one SAFETY comment per call that could only restate the signature.
-// Clearing this file means DELETING the markers that carry no caller contract, not wrapping the
-// calls — until then the lint is off HERE and enforced everywhere else.
-#![allow(unsafe_op_in_unsafe_fn)]
+// UNSAFE-LINT EXEMPTION REMOVED — the old fence rationale ("raw nvEncodeAPI entry-table calls
+// almost line for line") was false for this file: it makes ZERO FFI calls. Its unsafe surface is
+// C-union access whose soundness hangs entirely on which codec arm is active, and the 4:4:4 note
+// below records the shipped bug (hevcConfig bytes stamped onto an AV1 config) that per-operation
+// visibility makes findable. So this file runs the strictest discipline in the crate: every
+// union READ, borrow, or bitfield-setter call sits in its own `unsafe {}` block naming the codec
+// guard it relies on. (Plain union-arm field WRITES are safe by language rule — writing an arm
+// cannot itself be UB; the hazard is the mismatched read — so those stay bare, guarded by the
+// same codec matches.)
+#![deny(clippy::multiple_unsafe_ops_per_block)]
 
 use super::Codec;
 use nvidia_video_codec_sdk::sys::nvEncodeAPI as nv;
@@ -694,10 +698,9 @@ mod tests {
         };
         assert_eq!(cfg.profileGUID, nv::NV_ENC_HEVC_PROFILE_FREXT_GUID);
         // SAFETY: an HEVC session's union arm is `hevcConfig` — the one this path wrote.
-        unsafe {
-            assert_eq!(cfg.encodeCodecConfig.hevcConfig.chromaFormatIDC(), 3);
-            assert_eq!(cfg.encodeCodecConfig.hevcConfig.pixelBitDepthMinus8(), 2);
-        }
+        unsafe { assert_eq!(cfg.encodeCodecConfig.hevcConfig.chromaFormatIDC(), 3) };
+        // SAFETY: same HEVC arm as above.
+        unsafe { assert_eq!(cfg.encodeCodecConfig.hevcConfig.pixelBitDepthMinus8(), 2) };
     }
 
     #[test]
@@ -1210,6 +1213,8 @@ pub(super) unsafe fn apply_low_latency_config(cfg: &mut nv::NV_ENC_CONFIG, c: Lo
     // are the only accepted config). H.264 has no tier. Level 0 = autoselect for HEVC.
     match c.codec {
         Codec::H265 => {
+            // Plain union-arm writes are safe by language rule (the hazard is a mismatched
+            // READ later); the match on `c.codec` keeps the arm honest.
             cfg.encodeCodecConfig.hevcConfig.tier = 1;
             cfg.encodeCodecConfig.hevcConfig.level = 0;
         }
@@ -1264,21 +1269,29 @@ pub(super) unsafe fn apply_low_latency_config(cfg: &mut nv::NV_ENC_CONFIG, c: Lo
     }
     if want_444 && c.codec == Codec::H265 {
         cfg.profileGUID = nv::NV_ENC_HEVC_PROFILE_FREXT_GUID;
-        cfg.encodeCodecConfig.hevcConfig.set_chromaFormatIDC(3);
+        // SAFETY: HEVC session (guarded by `c.codec == Codec::H265` on this branch), so
+        // `hevcConfig` is the active arm.
+        unsafe { cfg.encodeCodecConfig.hevcConfig.set_chromaFormatIDC(3) };
         if c.bit_depth == 10 {
-            cfg.encodeCodecConfig.hevcConfig.set_pixelBitDepthMinus8(2); // Main 4:4:4 10
+            // SAFETY: same HEVC arm, same branch guard. (Main 4:4:4 10)
+            unsafe { cfg.encodeCodecConfig.hevcConfig.set_pixelBitDepthMinus8(2) };
         }
     } else if c.bit_depth == 10 {
         match c.codec {
             Codec::H265 => {
                 cfg.profileGUID = nv::NV_ENC_HEVC_PROFILE_MAIN10_GUID;
-                cfg.encodeCodecConfig.hevcConfig.set_pixelBitDepthMinus8(2);
+                // SAFETY: HEVC session (matched on `c.codec`), so `hevcConfig` is the active arm.
+                unsafe { cfg.encodeCodecConfig.hevcConfig.set_pixelBitDepthMinus8(2) };
             }
             Codec::Av1 => {
-                cfg.encodeCodecConfig.av1Config.set_pixelBitDepthMinus8(2);
-                cfg.encodeCodecConfig
-                    .av1Config
-                    .set_inputPixelBitDepthMinus8(c.av1_input_depth_minus8);
+                // SAFETY: AV1 session (matched on `c.codec`), so `av1Config` is the active arm.
+                unsafe { cfg.encodeCodecConfig.av1Config.set_pixelBitDepthMinus8(2) };
+                // SAFETY: same AV1 arm, same match guard.
+                unsafe {
+                    cfg.encodeCodecConfig
+                        .av1Config
+                        .set_inputPixelBitDepthMinus8(c.av1_input_depth_minus8)
+                };
             }
             Codec::H264 => {} // no 10-bit H.264 encode on NVENC — negotiation never asks
             Codec::PyroWave => unreachable!("PyroWave never opens the direct-NVENC backend"),
@@ -1306,7 +1319,9 @@ pub(super) unsafe fn apply_low_latency_config(cfg: &mut nv::NV_ENC_CONFIG, c: Lo
         };
         match c.codec {
             Codec::H265 => {
-                let vui = &mut cfg.encodeCodecConfig.hevcConfig.hevcVUIParameters;
+                // SAFETY: HEVC session (matched on `c.codec`), so `hevcConfig` is the active
+                // arm; the borrow is dropped before any other union access.
+                let vui = unsafe { &mut cfg.encodeCodecConfig.hevcConfig.hevcVUIParameters };
                 vui.videoSignalTypePresentFlag = 1;
                 vui.videoFullRangeFlag = 0;
                 vui.colourDescriptionPresentFlag = 1;
@@ -1315,7 +1330,9 @@ pub(super) unsafe fn apply_low_latency_config(cfg: &mut nv::NV_ENC_CONFIG, c: Lo
                 vui.colourMatrix = mat;
             }
             Codec::H264 => {
-                let vui = &mut cfg.encodeCodecConfig.h264Config.h264VUIParameters;
+                // SAFETY: H.264 session (matched on `c.codec`), so `h264Config` is the active
+                // arm; the borrow is dropped before any other union access.
+                let vui = unsafe { &mut cfg.encodeCodecConfig.h264Config.h264VUIParameters };
                 vui.videoSignalTypePresentFlag = 1;
                 vui.videoFullRangeFlag = 0;
                 vui.colourDescriptionPresentFlag = 1;
@@ -1324,7 +1341,9 @@ pub(super) unsafe fn apply_low_latency_config(cfg: &mut nv::NV_ENC_CONFIG, c: Lo
                 vui.colourMatrix = mat;
             }
             Codec::Av1 => {
-                let av1 = &mut cfg.encodeCodecConfig.av1Config;
+                // SAFETY: AV1 session (matched on `c.codec`), so `av1Config` is the active arm;
+                // the borrow is dropped before any other union access.
+                let av1 = unsafe { &mut cfg.encodeCodecConfig.av1Config };
                 av1.colorPrimaries = prim;
                 av1.transferCharacteristics = trc;
                 av1.matrixCoefficients = mat;

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

@@ -12,8 +12,6 @@
 //! defaulting to BT.709 limited — true of every punktfunk client (`csc_rows` falls back to 709 on
 //! "unspecified"), but NOT of vendor TV decoders, which guess colorimetry from RESOLUTION: an LG
 //! webOS panel reads a 4K SDR stream as BT.2020 and renders it visibly washed out.
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{EncodedFrame, Encoder};
 use anyhow::{bail, ensure, Context, Result};

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

@@ -49,8 +49,6 @@
 // restate the signature. Clearing this file means DELETING the markers that carry no caller
 // contract, not wrapping the calls — until then the lint is off HERE and enforced everywhere else.
 #![allow(unsafe_op_in_unsafe_fn)]
-// Every `unsafe` block / impl in this file carries a `// SAFETY:` proof; enforce it.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{ChromaFormat, Codec, EncodedFrame, Encoder, EncoderCaps};
 use anyhow::{anyhow, bail, Context, Result};
@@ -2239,38 +2237,22 @@ impl Encoder for AmfEncoder {
 mod tests {
     use super::*;
 
-    /// The mirrored `AMFVariantStruct` must match the C layout: 4-byte tag + 4 padding + 16-byte
-    /// union = 24 bytes, align 8, payload at offset 8 (it is passed BY VALUE across the FFI).
+    // The LAYOUT of `AmfVariant`, `AmfGuid` and `AmfHdrMetadata` is no longer asserted here.
+    // Those checks moved to `const _: ()` assertions beside the mirrors themselves in
+    // `amf_sys.rs`, together with per-slot offset guards for the five vtables. As `#[test]`s
+    // they only ran when someone ran pf-encode's tests, on Windows, with AMF enabled — never in
+    // a release build, which is precisely where a mis-mirrored `AMFVariantStruct` would do its
+    // damage. As const assertions they hold on EVERY build that compiles the module.
+    //
+    // What stays here is the part a layout check cannot express: that the little-endian packing
+    // of the union payload matches what the C side will read out of those bytes.
     #[test]
-    fn variant_layout_matches_c() {
-        assert_eq!(std::mem::size_of::<AmfVariant>(), 24);
-        assert_eq!(std::mem::align_of::<AmfVariant>(), 8);
-        assert_eq!(std::mem::offset_of!(AmfVariant, payload), 8);
+    fn variant_payload_packing_matches_c() {
         let v = AmfVariant::from_rate(60, 1);
         assert_eq!(v.payload[0], 60u64 | (1u64 << 32));
         assert_eq!(AmfVariant::from_i64(-1).payload[0], u64::MAX);
     }
 
-    /// `AMFGuid` is the flattened Win32-GUID layout (16 bytes).
-    #[test]
-    fn guid_layout_matches_c() {
-        assert_eq!(std::mem::size_of::<sys::AmfGuid>(), 16);
-    }
-
-    /// `AMFHDRMetadata` (components/ColorSpace.h): 8×u16 + 2×u32 + 2×u16 = 28 bytes, no padding.
-    #[test]
-    fn hdr_metadata_layout_matches_c() {
-        assert_eq!(std::mem::size_of::<sys::AmfHdrMetadata>(), 28);
-        assert_eq!(
-            std::mem::offset_of!(sys::AmfHdrMetadata, max_mastering_luminance),
-            16
-        );
-        assert_eq!(
-            std::mem::offset_of!(sys::AmfHdrMetadata, max_content_light_level),
-            24
-        );
-    }
-
     /// A representative HDR10 grade for the live tests (BT.2020 primaries, 1000-nit mastering)
     /// in [`HdrMeta`]'s ST.2086 wire units/order (primaries G, B, R).
     fn sample_hdr_meta() -> punktfunk_core::quic::HdrMeta {

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

@@ -409,6 +409,126 @@ pub struct AmfBufferVtbl {
     pub remove_observer_buffer: Slot,
 }
 
+// -- Layout guards ---------------------------------------------------------------------------
+//
+// THE CONTRACT, STATED ONCE. Everything above is a hand-written mirror of a C type this crate
+// does not own and cannot include. Two classes of drift are possible and NEITHER fails to
+// compile on its own:
+//
+//   1. A POD passed by value (`AmfVariant`, `AmfGuid`, `AmfHdrMetadata`) whose field offsets
+//      disagree with the C struct. The runtime then reads a tag or a payload out of the wrong
+//      bytes — `AmfVariant` crosses the FFI by value on EVERY `SetProperty`.
+//   2. A vtable slot inserted, removed or reordered. `amf.rs` dispatches BY POSITION through
+//      these mirrors, so a shifted slot calls an arbitrary function pointer through a
+//      mismatched signature. There is no compile error, no runtime signal, and the failure is
+//      whatever the neighbouring AMF entry point happens to do with our arguments.
+//
+// `AMF_MIN_VERSION` does not defend against either: it checks a version NUMBER, not a layout,
+// and it is a floor with no ceiling. The assertions below are the actual defence. They are
+// `const _: ()` rather than `#[cfg(test)]` deliberately — the three POD checks below used to
+// live only in `amf.rs`'s test module, which means they were verified only when someone ran
+// pf-encode's tests, on Windows, with AMF enabled, and NEVER in a release build. This is the
+// same hole `a8dd348b` closed for the cuda.h mirrors; it was missed here.
+//
+// Every slot index below was counted against the vtable declarations above. A slot is asserted
+// when `amf.rs` calls it — those are the ones whose displacement is directly exploitable — plus
+// the total size of each table, which catches an insertion PAST the last called slot (invisible
+// to a per-slot check, but still a sign the mirror has drifted from the header).
+
+/// One vtable slot. Every mirrored table is a flat array of these, so an offset in bytes is
+/// always `index * SLOT`.
+const SLOT: usize = core::mem::size_of::<Slot>();
+
+/// Byte offset of vtable slot `i`. A `const fn` rather than a bare `i * SLOT` expression because
+/// clippy's `erasing_op`/`identity_op` reject `0 * SLOT` and `1 * SLOT` under the `-D warnings`
+/// the Windows CI leg runs with — and writing those two as bare `0` and `SLOT` would be the one
+/// place the slot INDEX stops being visible, which is the entire readability of these assertions.
+const fn slot(i: usize) -> usize {
+    i * SLOT
+}
+
+// Every slot is a plain code pointer, so all five tables are pointer-sized-array-shaped. If this
+// ever fails, the tables are not flat arrays any more and every offset below is meaningless.
+const _: () = assert!(SLOT == core::mem::size_of::<usize>());
+const _: () = assert!(core::mem::align_of::<Slot>() == core::mem::align_of::<usize>());
+
+// -- PODs crossing the FFI by value --
+// `AMFVariantStruct`: 4-byte tag + 4 padding + 16-byte union = 24 bytes, payload at 8.
+const _: () = assert!(core::mem::size_of::<AmfVariant>() == 24);
+const _: () = assert!(core::mem::align_of::<AmfVariant>() == 8);
+const _: () = assert!(core::mem::offset_of!(AmfVariant, payload) == 8);
+// `AMFGuid`: the flattened Win32 GUID.
+const _: () = assert!(core::mem::size_of::<AmfGuid>() == 16);
+const _: () = assert!(core::mem::align_of::<AmfGuid>() == 4);
+// `AMFHDRMetadata` (components/ColorSpace.h): 8×u16 + 2×u32 + 2×u16 = 28 bytes, no padding.
+const _: () = assert!(core::mem::size_of::<AmfHdrMetadata>() == 28);
+const _: () = assert!(core::mem::offset_of!(AmfHdrMetadata, max_mastering_luminance) == 16);
+const _: () = assert!(core::mem::offset_of!(AmfHdrMetadata, max_content_light_level) == 24);
+
+// -- AMFFactory (7 slots) — `create_context` 0, `create_component` 1 --
+const _: () = assert!(core::mem::size_of::<AmfFactoryVtbl>() == slot(7));
+const _: () = assert!(core::mem::offset_of!(AmfFactoryVtbl, create_context) == slot(0));
+const _: () = assert!(core::mem::offset_of!(AmfFactoryVtbl, create_component) == slot(1));
+
+// -- AMFContext (55 slots) = AMFInterface(3) + AMFPropertyStorage(10) + AMFContext(42) --
+const _: () = assert!(core::mem::size_of::<AmfContextVtbl>() == slot(55));
+const _: () = assert!(core::mem::offset_of!(AmfContextVtbl, release) == slot(1));
+const _: () = assert!(core::mem::offset_of!(AmfContextVtbl, terminate) == slot(13));
+const _: () = assert!(core::mem::offset_of!(AmfContextVtbl, init_dx11) == slot(18));
+const _: () = assert!(core::mem::offset_of!(AmfContextVtbl, alloc_buffer) == slot(43));
+const _: () =
+    assert!(core::mem::offset_of!(AmfContextVtbl, create_surface_from_dx11_native) == slot(49));
+
+// -- AMFComponent (28 slots) = AMFInterface(3) + PropertyStorage(10) + StorageEx(4) + Component(11) --
+const _: () = assert!(core::mem::size_of::<AmfComponentVtbl>() == slot(28));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, release) == slot(1));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, set_property) == slot(3));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, init) == slot(17));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, terminate) == slot(19));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, drain) == slot(20));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, flush) == slot(21));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, submit_input) == slot(22));
+const _: () = assert!(core::mem::offset_of!(AmfComponentVtbl, query_output) == slot(23));
+
+// -- AMFData (23 slots) = AMFInterface(3) + AMFPropertyStorage(10) + AMFData(10) --
+const _: () = assert!(core::mem::size_of::<AmfDataVtbl>() == slot(23));
+const _: () = assert!(core::mem::offset_of!(AmfDataVtbl, release) == slot(1));
+const _: () = assert!(core::mem::offset_of!(AmfDataVtbl, query_interface) == slot(2));
+const _: () = assert!(core::mem::offset_of!(AmfDataVtbl, set_property) == slot(3));
+const _: () = assert!(core::mem::offset_of!(AmfDataVtbl, get_property) == slot(4));
+const _: () = assert!(core::mem::offset_of!(AmfDataVtbl, set_pts) == slot(19));
+
+// -- AMFBuffer (28 slots) = the AMFData prefix (23) + AMFBuffer(5) --
+const _: () = assert!(core::mem::size_of::<AmfBufferVtbl>() == slot(28));
+const _: () = assert!(core::mem::offset_of!(AmfBufferVtbl, release) == slot(1));
+const _: () = assert!(core::mem::offset_of!(AmfBufferVtbl, get_size) == slot(24));
+const _: () = assert!(core::mem::offset_of!(AmfBufferVtbl, get_native) == slot(25));
+
+// -- The shared-prefix agreement --
+// `AMFBuffer` derives from `AMFData`, and `create_surface_from_dx11_native` hands back an
+// `AMFSurface*` that this module drives through the `AmfData` mirror on the strength of that
+// single-inheritance prefix (see the comment on that slot). If the two mirrors ever disagree
+// about where a shared slot lives, that reinterpretation is silently wrong — so assert the
+// agreement rather than restating it in prose.
+const _: () = assert!(
+    core::mem::offset_of!(AmfDataVtbl, release) == core::mem::offset_of!(AmfBufferVtbl, release)
+);
+const _: () = assert!(
+    core::mem::offset_of!(AmfDataVtbl, set_property)
+        == core::mem::offset_of!(AmfBufferVtbl, set_property)
+);
+const _: () = assert!(
+    core::mem::offset_of!(AmfDataVtbl, get_property)
+        == core::mem::offset_of!(AmfBufferVtbl, get_property)
+);
+const _: () = assert!(
+    core::mem::offset_of!(AmfDataVtbl, set_pts) == core::mem::offset_of!(AmfBufferVtbl, set_pts)
+);
+const _: () = assert!(
+    core::mem::offset_of!(AmfDataVtbl, get_duration)
+        == core::mem::offset_of!(AmfBufferVtbl, get_duration)
+);
+
 // -- DLL entry points (core/Factory.h; AMF_CDECL_CALL) --------------------------------------
 pub type AmfQueryVersionFn = unsafe extern "C" fn(*mut u64) -> AmfResult;
 pub type AmfInitFn = unsafe extern "C" fn(u64, *mut *mut AmfFactory) -> AmfResult;

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

@@ -37,8 +37,6 @@
 //! through `ffmpeg::ffi` (= `ffmpeg_sys_next`), exactly as the Linux CUDA/VAAPI paths do. The
 //! `AVD3D11VADeviceContext`/`AVD3D11VAFramesContext` layouts are mirrored (the bindings don't
 //! allowlist `hwcontext_d3d11va.h`), as [`super::linux`] mirrors `AVCUDADeviceContext`.
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{ChromaFormat, Codec, EncodedFrame, Encoder};
 use anyhow::{anyhow, bail, Context, Result};
@@ -61,8 +59,8 @@ use windows::Win32::Graphics::Dxgi::Common::{
 };
 
 use super::libav::{
-    apply_low_latency_rc, pixel_to_av, poll_encoder, AvBuffer, PollOutcome, SWS_CS_BT2020,
-    SWS_CS_ITU709, SWS_POINT,
+    apply_low_latency_rc, pixel_to_av, poll_encoder, AvBuffer, AvFrame, AvSwsContext, PollOutcome,
+    SWS_CS_BT2020, SWS_CS_ITU709, SWS_POINT,
 };
 use ffmpeg::ffi; // = ffmpeg_sys_next
 
@@ -499,10 +497,14 @@ fn immediate_context(device: &ID3D11Device) -> ID3D11DeviceContext {
 
 struct SystemInner {
     enc: encoder::video::Encoder,
+    // FIELD ORDER IS LOAD-BEARING: the hand-written `Drop` this replaced freed `sw_frame`
+    // before `sws`, and field-DECLARATION order is what preserves that now (an offset_of assert
+    // cannot pin this — repr(Rust) may reorder memory independently of declaration order, and
+    // drop order follows declaration).
     /// Reusable software NV12/P010 frame: swscale dst / readback dst, and the `send_frame` src.
-    sw_frame: *mut ffi::AVFrame,
-    /// swscale ctx for the BGRA→NV12 fallback (built lazily; null for the YUV-readback path).
-    sws: *mut ffi::SwsContext,
+    sw_frame: AvFrame,
+    /// swscale ctx for the BGRA→NV12 fallback (built lazily; `None` for the YUV-readback path).
+    sws: Option<AvSwsContext>,
     /// CPU-readable staging texture for the D3D11 readback (built lazily on the captured device).
     staging: Option<ID3D11Texture2D>,
     ctx: Option<ID3D11DeviceContext>,
@@ -549,26 +551,18 @@ impl SystemInner {
                 ptr::null_mut(),
             )?
         };
-        // SAFETY: `av_frame_alloc` returns a freshly-allocated, uniquely-owned `AVFrame` (null-checked
-        // before any deref); writing `format`/`width`/`height` through `*f` stays inside that
-        // allocation. `av_frame_get_buffer(f, 0)` allocates the backing planes — on failure we
-        // `av_frame_free` the sole owner (no double-free) and bail; on success the raw `f` is moved into
-        // `self.sw_frame` and freed exactly once in `Drop`.
-        let sw_frame = unsafe {
-            let f = ffi::av_frame_alloc();
-            if f.is_null() {
-                bail!("av_frame_alloc(sw) failed");
-            }
-            (*f).format = sw_av as c_int;
-            (*f).width = width as c_int;
-            (*f).height = height as c_int;
-            if ffi::av_frame_get_buffer(f, 0) < 0 {
-                let mut f = f;
-                ffi::av_frame_free(&mut f);
+        let sw_frame = AvFrame::alloc().context("av_frame_alloc(sw) failed")?;
+        // SAFETY: writing `format`/`width`/`height` through the owned frame's pointer stays inside
+        // its allocation. `av_frame_get_buffer` allocates the backing planes — on failure the
+        // owned `sw_frame` simply drops (freed once, by the wrapper).
+        unsafe {
+            (*sw_frame.as_ptr()).format = sw_av as c_int;
+            (*sw_frame.as_ptr()).width = width as c_int;
+            (*sw_frame.as_ptr()).height = height as c_int;
+            if ffi::av_frame_get_buffer(sw_frame.as_ptr(), 0) < 0 {
                 bail!("av_frame_get_buffer(sw) failed");
             }
-            f
-        };
+        }
         tracing::info!(
             encoder = vendor.encoder_name(codec),
             "{} encode active ({width}x{height}@{fps}, system-memory {} path)",
@@ -578,7 +572,7 @@ impl SystemInner {
         Ok(SystemInner {
             enc,
             sw_frame,
-            sws: ptr::null_mut(),
+            sws: None,
             staging: None,
             ctx: None,
             format,
@@ -634,13 +628,13 @@ impl SystemInner {
         // frame and `self.enc`'s own context, both live for the call and neither retained by libav
         // (it references the frame's buffers itself).
         unsafe {
-            (*self.sw_frame).pts = pts;
-            (*self.sw_frame).pict_type = if idr {
+            (*self.sw_frame.as_ptr()).pts = pts;
+            (*self.sw_frame.as_ptr()).pict_type = if idr {
                 ffi::AVPictureType::AV_PICTURE_TYPE_I
             } else {
                 ffi::AVPictureType::AV_PICTURE_TYPE_NONE
             };
-            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), self.sw_frame);
+            let r = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), self.sw_frame.as_ptr());
             if r < 0 {
                 bail!("avcodec_send_frame({} system) failed ({r})", "ffmpeg_win");
             }
@@ -705,10 +699,10 @@ impl SystemInner {
             let total = pitch.saturating_mul(h + h.div_ceil(2));
             let mapped = std::slice::from_raw_parts(base, total);
             let chroma_off = pitch * h;
-            let y_dst = (*self.sw_frame).data[0];
-            let y_stride = (*self.sw_frame).linesize[0] as usize;
-            let uv_dst = (*self.sw_frame).data[1];
-            let uv_stride = (*self.sw_frame).linesize[1] as usize;
+            let y_dst = (*self.sw_frame.as_ptr()).data[0];
+            let y_stride = (*self.sw_frame.as_ptr()).linesize[0] as usize;
+            let uv_dst = (*self.sw_frame.as_ptr()).data[1];
+            let uv_stride = (*self.sw_frame.as_ptr()).linesize[1] as usize;
             for y in 0..h {
                 let s = &mapped[y * pitch..y * pitch + row_bytes];
                 ptr::copy_nonoverlapping(s.as_ptr(), y_dst.add(y * y_stride), row_bytes);
@@ -748,7 +742,7 @@ impl SystemInner {
             let pitch = map.RowPitch as usize;
             let h = self.height as usize;
             let base = map.pData as *const u8;
-            self.ensure_sws(
+            let sws = self.ensure_sws(
                 pixel_to_av(Pixel::BGRA),
                 ffi::AVPixelFormat::AV_PIX_FMT_NV12,
                 SWS_CS_ITU709,
@@ -756,13 +750,13 @@ impl SystemInner {
             let src_data: [*const u8; 4] = [base, ptr::null(), ptr::null(), ptr::null()];
             let src_stride: [c_int; 4] = [pitch as c_int, 0, 0, 0];
             let r = ffi::sws_scale(
-                self.sws,
+                sws,
                 src_data.as_ptr(),
                 src_stride.as_ptr(),
                 0,
                 h as c_int,
-                (*self.sw_frame).data.as_ptr(),
-                (*self.sw_frame).linesize.as_ptr(),
+                (*self.sw_frame.as_ptr()).data.as_ptr(),
+                (*self.sw_frame.as_ptr()).linesize.as_ptr(),
             );
             ctx.Unmap(&staging, 0);
             if r < 0 {
@@ -798,7 +792,7 @@ impl SystemInner {
             let h = self.height as usize;
             let base = map.pData as *const u8;
             // RGB(BT.2020 PQ) → YUV(BT.2020 PQ): a matrix-only repack (same PQ transfer), full→limited.
-            self.ensure_sws(
+            let sws = self.ensure_sws(
                 ffi::AVPixelFormat::AV_PIX_FMT_X2BGR10LE,
                 ffi::AVPixelFormat::AV_PIX_FMT_P010LE,
                 SWS_CS_BT2020,
@@ -806,13 +800,13 @@ impl SystemInner {
             let src_data: [*const u8; 4] = [base, ptr::null(), ptr::null(), ptr::null()];
             let src_stride: [c_int; 4] = [pitch as c_int, 0, 0, 0];
             let r = ffi::sws_scale(
-                self.sws,
+                sws,
                 src_data.as_ptr(),
                 src_stride.as_ptr(),
                 0,
                 h as c_int,
-                (*self.sw_frame).data.as_ptr(),
-                (*self.sw_frame).linesize.as_ptr(),
+                (*self.sw_frame.as_ptr()).data.as_ptr(),
+                (*self.sw_frame.as_ptr()).linesize.as_ptr(),
             );
             ctx.Unmap(&staging, 0);
             if r < 0 {
@@ -844,7 +838,7 @@ impl SystemInner {
         // `width`×`height`). `bytes` is borrowed for the call only and never aliases the owned
         // `sw_frame`. `send` then hands `sw_frame` to the encoder.
         unsafe {
-            self.ensure_sws(
+            let sws = self.ensure_sws(
                 pixel_to_av(sws_src(format)?),
                 ffi::AVPixelFormat::AV_PIX_FMT_NV12,
                 SWS_CS_ITU709,
@@ -852,13 +846,13 @@ impl SystemInner {
             let src_data: [*const u8; 4] = [bytes.as_ptr(), ptr::null(), ptr::null(), ptr::null()];
             let src_stride: [c_int; 4] = [src_row as c_int, 0, 0, 0];
             if ffi::sws_scale(
-                self.sws,
+                sws,
                 src_data.as_ptr(),
                 src_stride.as_ptr(),
                 0,
                 h as c_int,
-                (*self.sw_frame).data.as_ptr(),
-                (*self.sw_frame).linesize.as_ptr(),
+                (*self.sw_frame.as_ptr()).data.as_ptr(),
+                (*self.sw_frame.as_ptr()).linesize.as_ptr(),
             ) < 0
             {
                 bail!("sws_scale RGB→NV12 failed");
@@ -872,23 +866,24 @@ impl SystemInner {
     /// 10-bit RGB10→P010 BT.2020), so caching a single context is sound.
     ///
     /// Safe: every argument is a plain libav enum/int, and the context it caches belongs to `self`
-    /// (freed once in `Drop`).
+    /// (an owned `AvSwsContext`, freed by its own drop). Returns the borrowed pointer for the
+    /// caller's `sws_scale` — borrowed only, `self.sws` stays the owner.
     fn ensure_sws(
         &mut self,
         src_av: ffi::AVPixelFormat,
         dst_av: ffi::AVPixelFormat,
         cs: c_int,
-    ) -> Result<()> {
-        if !self.sws.is_null() {
-            return Ok(());
+    ) -> Result<*mut ffi::SwsContext> {
+        if let Some(sws) = &self.sws {
+            return Ok(sws.as_ptr());
         }
         // SAFETY: `sws_getContext` takes only scalars plus the documented "no filters, no params"
-        // null trio, and returns an owned context or null — which is checked before use, so
-        // `sws_setColorspaceDetails` and the store below only ever see a live one.
-        // `sws_getCoefficients` returns a pointer into libav's own static tables, valid for the
-        // process, and the call only reads it.
+        // null trio, and returns an owned context or null — `from_raw` rejects the null, so
+        // `sws_setColorspaceDetails` only ever sees a live one, and ownership passes to the
+        // `AvSwsContext`. `sws_getCoefficients` returns a pointer into libav's own static tables,
+        // valid for the process, and the call only reads it.
         let sws = unsafe {
-            let sws = ffi::sws_getContext(
+            let raw = ffi::sws_getContext(
                 self.width as c_int,
                 self.height as c_int,
                 src_av,
@@ -900,36 +895,22 @@ impl SystemInner {
                 ptr::null_mut(),
                 ptr::null(),
             );
-            if sws.is_null() {
+            let Some(owned) = AvSwsContext::from_raw(raw) else {
                 bail!("sws_getContext(RGB→YUV) failed");
-            }
+            };
             // Source full-range RGB → destination limited-range YUV (matches the limited-range VUI
             // we signal). For RGB input the src coefficient table is unused; pass dst for both.
             let coeff = ffi::sws_getCoefficients(cs);
-            ffi::sws_setColorspaceDetails(sws, coeff, 1, coeff, 0, 0, 1 << 16, 1 << 16);
-            sws
+            ffi::sws_setColorspaceDetails(owned.as_ptr(), coeff, 1, coeff, 0, 0, 1 << 16, 1 << 16);
+            owned
         };
-        self.sws = sws;
-        Ok(())
+        Ok(self.sws.insert(sws).as_ptr())
     }
 }
 
-impl Drop for SystemInner {
-    fn drop(&mut self) {
-        // SAFETY: `sw_frame` is the `AVFrame` allocated in `open` (or null) — `av_frame_free` drops it
-        // once and nulls the pointer through the `&mut`; `sws` is the cached `SwsContext` (or null) —
-        // `sws_freeContext` frees it once. This `Drop` runs exactly once and `SystemInner` owns both
-        // exclusively, so there is no double-free or use-after-free.
-        unsafe {
-            if !self.sw_frame.is_null() {
-                ffi::av_frame_free(&mut self.sw_frame);
-            }
-            if !self.sws.is_null() {
-                ffi::sws_freeContext(self.sws);
-            }
-        }
-    }
-}
+// No `Drop` for `SystemInner`: `sw_frame` (`AvFrame`) and `sws` (`Option<AvSwsContext>`) free
+// themselves, in field-declaration order — the same sw_frame-then-sws sequence the hand-written
+// `Drop` performed, pinned by the offset_of assert at the struct.
 
 // ---------------------------------------------------------------------------------------------
 // Zero-copy D3D11 path (the AMF default; QSV opt-in — see `zerocopy_enabled`): share the capture
@@ -1214,32 +1195,29 @@ impl ZeroCopyInner {
     }
 
     fn submit(&mut self, frame: &D3d11Frame, pts: i64, idr: bool) -> Result<()> {
-        // SAFETY: `d3d = av_frame_alloc()` is a fresh owned frame (null-checked) and is `av_frame_free`d
-        // exactly once on every path below. `av_hwframe_get_buffer` fills it from the pool — on failure
-        // we free it and bail. `(*d3d).data[0]` is the pool's texture-array and `data[1]` the array
-        // index; `from_raw_borrowed` borrows that `ID3D11Texture2D` WITHOUT taking ownership (no Release
-        // — the frame owns it) and is null-checked. `src` (the captured texture) and `dst` (the pooled
-        // slice) live on the SAME D3D11 device wrapped by `self.hw`, and the caller guarantees
-        // `captured.format == pool_format` before calling, so `CopySubresourceRegion(dst, dst_index, ..,
-        // src, 0, ..)` on the single-threaded immediate context `self.ctx` is a valid same-format GPU
-        // copy. For QSV the mapped `qsv` frame is a fresh owned frame whose `hw_frames_ctx` takes an
-        // `av_buffer_ref` of `self.qsv_frames`; it is `av_frame_free`d (releasing that ref) on both the
-        // map-failure and success paths. `avcodec_send_frame` only internally refs the input frame, so
-        // the `av_frame_free(d3d)`/`av_frame_free(qsv)` afterwards are the sole owning frees — no leak,
-        // no double-free, no use-after-free.
+        // SAFETY: `d3d`/`qsv` are owned `AvFrame`s, so EVERY exit — including the three `?` exits
+        // between the pool pull and the send, which as hand-placed frees previously leaked the
+        // frame plus one of the POOL-sized hwframe surfaces per failure (eight failures wedged
+        // the encoder permanently) — unrefs the pooled surface back to the pool. `(*d3d).data[0]`
+        // is the pool's texture-array and `data[1]` the array index; `from_raw_borrowed` borrows
+        // that `ID3D11Texture2D` WITHOUT taking ownership (no Release — the frame owns it) and is
+        // null-checked. `src` (the captured texture) and `dst` (the pooled slice) live on the
+        // SAME D3D11 device wrapped by `self.hw`, and the caller guarantees `captured.format ==
+        // pool_format` before calling, so `CopySubresourceRegion(dst, dst_index, .., src, 0, ..)`
+        // on the single-threaded immediate context `self.ctx` is a valid same-format GPU copy.
+        // For QSV the mapped `qsv` frame's `hw_frames_ctx` takes an `av_buffer_ref` of
+        // `self.qsv_frames`; its drop at the end of the arm releases that ref at the same point
+        // the hand-written free did. `avcodec_send_frame` only internally refs the input frame,
+        // so the drops are the sole owning frees — no leak, no double-free, no use-after-free.
         unsafe {
             // Pull a pooled D3D11 surface; its data[0] is the pool's texture-ARRAY, data[1] the slice.
-            let mut d3d = ffi::av_frame_alloc();
-            if d3d.is_null() {
-                bail!("av_frame_alloc(d3d11) failed");
-            }
-            let r = ffi::av_hwframe_get_buffer(self.hw.frames_ref.as_ptr(), d3d, 0);
+            let d3d = AvFrame::alloc().context("av_frame_alloc(d3d11) failed")?;
+            let r = ffi::av_hwframe_get_buffer(self.hw.frames_ref.as_ptr(), d3d.as_ptr(), 0);
             if r < 0 {
-                ffi::av_frame_free(&mut d3d);
                 bail!("av_hwframe_get_buffer(D3D11) failed ({r})");
             }
-            let dst_ptr = (*d3d).data[0] as *mut c_void;
-            let dst_index = (*d3d).data[1] as usize as u32;
+            let dst_ptr = (*d3d.as_ptr()).data[0] as *mut c_void;
+            let dst_index = (*d3d.as_ptr()).data[1] as usize as u32;
             let dst_tex = ID3D11Texture2D::from_raw_borrowed(&dst_ptr)
                 .ok_or_else(|| anyhow!("pooled D3D11 frame has null texture"))?;
             // GPU-local copy of the captured slice into the pooled array slice (like NVENC's CUDA
@@ -1249,58 +1227,50 @@ impl ZeroCopyInner {
             self.ctx
                 .CopySubresourceRegion(&dst, dst_index, 0, 0, 0, &src, 0, None);
 
-            (*d3d).pts = pts;
-            (*d3d).pict_type = if idr {
+            (*d3d.as_ptr()).pts = pts;
+            (*d3d.as_ptr()).pict_type = if idr {
                 ffi::AVPictureType::AV_PICTURE_TYPE_I
             } else {
                 ffi::AVPictureType::AV_PICTURE_TYPE_NONE
             };
 
             let send = match self.vendor {
-                WinVendor::Amf => ffi::avcodec_send_frame(self.enc.as_mut_ptr(), d3d),
+                WinVendor::Amf => ffi::avcodec_send_frame(self.enc.as_mut_ptr(), d3d.as_ptr()),
                 WinVendor::Qsv => {
                     // Map the D3D11 frame to a QSV surface (1:1, no copy), then send the mapped frame.
-                    let mut qsv = ffi::av_frame_alloc();
-                    if qsv.is_null() {
-                        ffi::av_frame_free(&mut d3d);
-                        bail!("av_frame_alloc(qsv) failed");
-                    }
+                    let qsv = AvFrame::alloc().context("av_frame_alloc(qsv) failed")?;
                     // Always `Some` on this arm — `open` fills the pair for `WinVendor::Qsv` and
                     // leaves it `None` only for AMF — but say so with a bail rather than an unwrap,
                     // matching the null check above it. The `Option` is what the raw pointer's
                     // "null means AMF" convention was already encoding.
                     let Some(qsv_frames) = self.qsv_frames.as_ref() else {
-                        ffi::av_frame_free(&mut qsv);
-                        ffi::av_frame_free(&mut d3d);
                         bail!("QSV send path without a derived QSV frames context");
                     };
-                    (*qsv).format = ffi::AVPixelFormat::AV_PIX_FMT_QSV as c_int;
-                    (*qsv).hw_frames_ctx = ffi::av_buffer_ref(qsv_frames.as_ptr());
+                    (*qsv.as_ptr()).format = ffi::AVPixelFormat::AV_PIX_FMT_QSV as c_int;
+                    (*qsv.as_ptr()).hw_frames_ctx = ffi::av_buffer_ref(qsv_frames.as_ptr());
                     // The map flags are a bindgen enum (no BitOr) — cast each to int before OR-ing.
                     let r = ffi::av_hwframe_map(
-                        qsv,
-                        d3d,
+                        qsv.as_ptr(),
+                        d3d.as_ptr(),
                         ffi::AV_HWFRAME_MAP_DIRECT as c_int | ffi::AV_HWFRAME_MAP_READ as c_int,
                     );
                     if r < 0 {
-                        ffi::av_frame_free(&mut qsv);
-                        ffi::av_frame_free(&mut d3d);
                         bail!("av_hwframe_map(D3D11→QSV) failed ({r})");
                     }
-                    (*qsv).pts = pts;
-                    (*qsv).pict_type = (*d3d).pict_type;
-                    let s = ffi::avcodec_send_frame(self.enc.as_mut_ptr(), qsv);
-                    ffi::av_frame_free(&mut qsv);
-                    s
+                    (*qsv.as_ptr()).pts = pts;
+                    (*qsv.as_ptr()).pict_type = (*d3d.as_ptr()).pict_type;
+                    ffi::avcodec_send_frame(self.enc.as_mut_ptr(), qsv.as_ptr())
+                    // `qsv` drops here — releasing the mapped frame and its frames-ctx ref at the
+                    // same point the hand-written `av_frame_free(&mut qsv)` did.
                 }
             };
-            ffi::av_frame_free(&mut d3d);
             if send < 0 {
                 bail!(
                     "avcodec_send_frame({}) failed ({send})",
                     self.vendor.label()
                 );
             }
+            // `d3d` drops here (and on every early exit above), returning the pooled surface.
         }
         Ok(())
     }

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

@@ -39,8 +39,6 @@
 // the signature. Clearing this file means DELETING the markers that carry no caller contract, not
 // wrapping the calls — until then the lint is off HERE and enforced everywhere else.
 #![allow(unsafe_op_in_unsafe_fn)]
-// Every `unsafe` block / impl in this file carries a `// SAFETY:` proof; enforce it.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::nvenc_core::{
     apply_low_latency_config, build_init_params, cached_ceiling, codec_guid, plan_range_recovery,

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

@@ -37,9 +37,6 @@
 //! it stays behind the same gate and falls back to IDR wherever the driver declines. 4:4:4 stays
 //! `false` until probed on real hardware (design §8.6).
 
-// Every `unsafe` block / impl in this file carries a `// SAFETY:` proof; enforce it.
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::{ChromaFormat, Codec, EncodedFrame, Encoder, EncoderCaps};
 use anyhow::{anyhow, bail, Context, Result};
 use libvpl_sys as vpl;

crates/pf-encode/src/lib.rs

@@ -12,7 +12,6 @@
 // `#[cfg(test)]` instead.
 // Every unsafe block in this module tree carries a `// SAFETY:` proof; enforce it (unsafe-proof
 // program). As a parent module this also covers the child modules (windows/linux backends).
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use anyhow::Result;
 use pf_frame::{CapturedFrame, PixelFormat};

crates/pf-frame/src/dxgi.rs

@@ -7,9 +7,6 @@
 //! The win32u GPU-preference hook, the HDR/video-engine converters, and the self-tests stay in the
 //! capture crate — they are capture mechanics, not shared identity.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use anyhow::{Context, Result};
 use windows::core::Interface;
 use windows::Win32::Foundation::{HMODULE, LUID};
@@ -158,18 +155,26 @@ enum PrioMode {
     Off,
     /// A fixed class the operator pinned (`normal`=2 / `high`=4 / `realtime`=5).
     Static(i32),
-    /// The default: HIGH immediately, then upgrade to REALTIME when it is safe — HAGS off, or
+    /// Opt-in (`auto`): HIGH immediately, then upgrade to REALTIME when it is safe — HAGS off, or
     /// HAGS on with comfortable VRAM headroom (with a monitor that downgrades the moment VRAM
-    /// tightens). REALTIME is the proven ceiling-raiser (it is how our brief encode preempts a
-    /// saturating game), but REALTIME + NVIDIA + HAGS + near-full VRAM is a documented NVENC
-    /// hang — the gate takes the win everywhere it cannot hit the hazard.
+    /// tightens). REALTIME is the T2.3 ceiling-raiser (a higher-priority context preempts at
+    /// pixel granularity), but it carries TWO field-proven hazards: REALTIME + NVIDIA + HAGS +
+    /// near-full VRAM is a documented NVENC hang (the VRAM gate covers that one), and on AMD the
+    /// upgrade itself produced a metronomic content-starving stall class (~3.6 s period, RX 9070
+    /// XT, 2026-08-12 A/B: pinning `high` removed it) that no VRAM gate can see — which is why
+    /// `auto` is no longer the default.
     Auto,
 }
 
-/// Resolve `PUNKTFUNK_GPU_PRIORITY_CLASS` (`off|normal|high|realtime|auto`, default **auto**).
+/// Resolve `PUNKTFUNK_GPU_PRIORITY_CLASS` (`off|normal|high|realtime|auto`, default **high**).
 /// D3DKMT_SCHEDULINGPRIORITYCLASS: IDLE 0, BELOW_NORMAL 1, NORMAL 2, ABOVE_NORMAL 3, HIGH 4,
 /// REALTIME 5. `realtime` pins REALTIME statically (no gate — the operator owns the hazard);
-/// `high` restores the pre-T2.3 static default.
+/// `auto` is the T2.3 gated-REALTIME mode, opt-in since the 2026-08-12 field A/B convicted the
+/// REALTIME upgrade of its own metronomic stall class on AMD (see [`PrioMode::Auto`]) — HIGH is
+/// the Sunshine/Apollo-parity lever that delivered the original decisive win, and the default
+/// must not hold REALTIME anywhere (the same inversion as the vdisplay driver's `PFVD_RT_GPU`
+/// ladder, which fixed the faster ~1.8 s metronome the same day). Unrecognized values read as
+/// the default, not as `auto` — a typo must not opt a box into the hazard.
 fn configured_gpu_priority_mode() -> PrioMode {
     match std::env::var("PUNKTFUNK_GPU_PRIORITY_CLASS")
         .ok()
@@ -177,9 +182,10 @@ fn configured_gpu_priority_mode() -> PrioMode {
     {
         Some("off") => PrioMode::Off,
         Some("normal") => PrioMode::Static(2),
-        Some("high") => PrioMode::Static(4),
         Some("realtime") => PrioMode::Static(5),
-        _ => PrioMode::Auto,
+        Some("auto") => PrioMode::Auto,
+        // `high`, unset, and anything unrecognized all land on the HIGH default.
+        _ => PrioMode::Static(4),
     }
 }
 
@@ -278,14 +284,17 @@ unsafe fn d3dkmt_set_scheduling_priority_class(
 /// GPU-saturated game our capture+encode process is starved of GPU time slices — NVENC sits ~idle but
 /// `lock_bitstream` waits ~20 ms for our context to be scheduled. Elevating the PROCESS GPU scheduling
 /// priority class (the strong cross-process lever — far more effective than `SetGPUThreadPriority`
-/// alone, which we measured as no help) lets our brief encode preempt the game. Default is the
-/// T2.3 `auto` mode: HIGH immediately here, then [`auto_priority_gate`] upgrades to REALTIME
-/// where the NVIDIA+HAGS+full-VRAM NVENC-hang hazard cannot bite (and a monitor downgrades when
-/// it could). Runs once per process; best-effort.
-/// `PUNKTFUNK_GPU_PRIORITY_CLASS = off|normal|high|realtime|auto` (default auto; `high` = the
-/// pre-gate static behavior; `realtime` = pinned, operator owns the hazard). Best-effort:
-/// silently no-ops under a UAC-filtered token (the process will not hold SE_INC_BASE_PRIORITY,
-/// so the D3DKMT call is a no-op).
+/// alone, which we measured as no help) lets our brief encode preempt the game. Default is a
+/// static HIGH — the class that delivered that win. The T2.3 `auto` mode (HIGH here, then
+/// [`auto_priority_gate`] upgrades to REALTIME behind the NVENC-hang VRAM gate) is opt-in since
+/// the 2026-08-12 field A/B: on AMD the REALTIME upgrade generated its own metronomic
+/// content-starving stall class (~3.6 s period) that the VRAM gate cannot see, and pinning HIGH
+/// removed it. Runs once per process; best-effort.
+/// `PUNKTFUNK_GPU_PRIORITY_CLASS = off|normal|high|realtime|auto` (default high; `auto` = the
+/// gated-REALTIME upgrade, operator opts into the AMD stall hazard for the extra ceiling;
+/// `realtime` = pinned, operator owns every hazard). Best-effort: silently no-ops under a
+/// UAC-filtered token (the process will not hold SE_INC_BASE_PRIORITY, so the D3DKMT call is a
+/// no-op).
 fn elevate_process_gpu_priority() {
     use std::sync::Once;
     static ONCE: Once = Once::new();
@@ -319,17 +328,23 @@ fn elevate_process_gpu_priority() {
     });
 }
 
-// --- REALTIME auto-gate (gpu-contention §5.C / latency plan T2.3) --------------------------------
+// --- REALTIME auto-gate (gpu-contention §5.C / latency plan T2.3) — OPT-IN since 2026-08-12 ------
 //
 // REALTIME GPU scheduling priority is the genuine cross-process ceiling-raiser under a saturating
 // game (a higher-priority context preempts at pixel granularity — the Async-TimeWarp mechanism),
-// and our SYSTEM service uniquely holds the SE_INC_BASE_PRIORITY it needs. The one documented
-// hazard: REALTIME + NVIDIA + HAGS-on + near-full VRAM can hang NVENC. So: probe HAGS once via
-// D3DKMT; HAGS off ⇒ REALTIME unconditionally; HAGS on ⇒ REALTIME gated on LOCAL-segment VRAM
-// headroom, with a monitor thread that downgrades to HIGH the moment usage crosses
-// [`VRAM_DOWNGRADE_PCT`] of the OS budget and restores REALTIME after it has stayed under
-// [`VRAM_RESTORE_PCT`] for [`VRAM_RESTORE_TICKS`] consecutive polls (hysteresis against flapping
-// on the boundary of the hazard window).
+// and our SYSTEM service uniquely holds the SE_INC_BASE_PRIORITY it needs. Two field-proven
+// hazards bound it. (1) REALTIME + NVIDIA + HAGS-on + near-full VRAM can hang NVENC — the VRAM
+// gate below exists for that one: probe HAGS once via D3DKMT; HAGS off ⇒ REALTIME
+// unconditionally; HAGS on ⇒ REALTIME gated on LOCAL-segment VRAM headroom, with a monitor
+// thread that downgrades to HIGH the moment usage crosses [`VRAM_DOWNGRADE_PCT`] of the OS
+// budget and restores REALTIME after it has stayed under [`VRAM_RESTORE_PCT`] for
+// [`VRAM_RESTORE_TICKS`] consecutive polls (hysteresis against flapping on the boundary of the
+// hazard window). (2) On AMD (RX 9070 XT A/B), a punktfunk process holding REALTIME generated a
+// metronomic content-starving stall class — every ~3.6 s ALL processes' presents paused
+// 150–800 ms with the GPU responsive — that no VRAM gate can see, and the vdisplay driver's
+// REALTIME swap-chain raise produced the same pathology on its own ~1.8 s beat. That second
+// hazard is why the whole gate now runs only under an explicit `auto`, and the default stays a
+// static HIGH.
 
 /// Downgrade REALTIME→HIGH when local VRAM usage exceeds this share of the OS budget.
 const VRAM_DOWNGRADE_PCT: u64 = 92;

crates/pf-frame/src/lib.rs

@@ -10,7 +10,6 @@
 //! tuning), and — on Windows — [`dxgi`] (the capture identity + D3D11 device creation).
 
 // Unsafe-proof program: every `unsafe {}` / `unsafe impl` must carry a `// SAFETY:` proof.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 pub mod hdr;
 pub mod metronome;

crates/pf-frame/src/session_tuning.rs

@@ -11,9 +11,6 @@
 //! state) auto-revert at thread exit (= session end); the process-wide bits revert at process exit.
 //! See `design/host-latency-plan.md` Tier 3A.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 #[cfg(target_os = "windows")]
 mod imp {
     #![allow(non_snake_case)]

crates/pf-frame/src/thread_qos.rs

@@ -3,9 +3,6 @@
 //! can't deschedule them; the native, GameStream, and direct-NVENC send threads all reach this the
 //! same way (`pf_frame::thread_qos::boost_thread_priority`).
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 /// Raise the current thread's OS scheduling priority so a CPU-heavy game can't deschedule our
 /// capture/encode/send threads. This matters even though our GPU work is already HIGH priority: the
 /// GPU scheduler can only favour commands we've actually SUBMITTED, so if a normal-priority thread is

crates/pf-gpu/src/lib.rs

@@ -23,7 +23,6 @@
 //! live session actually encodes on, for the console's "in use" display.
 
 // Unsafe-proof program: every `unsafe {}` in this leaf carries a `// SAFETY:` proof.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use anyhow::Result;
 use serde::{Deserialize, Serialize};

crates/pf-host-config/src/lib.rs

@@ -144,6 +144,13 @@ pub struct HostConfig {
     /// text ("Living Room PC"); the DNS-level `<label>.local.` target keeps using a sanitized
     /// machine-safe label, so a spacey display name can't produce an invalid mDNS record.
     pub host_name: Option<String>,
+    /// `PUNKTFUNK_GAMESTREAM` — enable the GameStream/Moonlight-compat planes (nvhttp pairing,
+    /// RTSP, ENet control, `_nvstream` mDNS) from `host.env`, equivalent to the `--gamestream`
+    /// CLI flag (either source turns it on). **Default OFF** — the secure native-only host: the
+    /// compat planes carry plain-HTTP pairing + the legacy GCM-nonce path (security-review
+    /// #5/#9), so stock-Moonlight support is opt-in on every route, and the packaged units ship
+    /// without the flag so this knob is how a package user opts in.
+    pub gamestream: bool,
     /// `PUNKTFUNK_ENCODER` — explicit encoder-backend override (lowercased; empty = auto-detect by GPU vendor).
     pub encoder_pref: String,
     /// `PUNKTFUNK_RENDER_ADAPTER` — discrete render-GPU pin by description substring (`Some` even when empty:
@@ -356,6 +363,9 @@ impl HostConfig {
             host_name: val("PUNKTFUNK_HOST_NAME")
                 .map(|s| s.trim().to_string())
                 .filter(|s| !s.is_empty()),
+            // Default OFF, explicit-on grammar: the Moonlight-compat planes are opt-in
+            // everywhere (see the field doc); `--gamestream` on the CLI also turns them on.
+            gamestream: env_on("PUNKTFUNK_GAMESTREAM").unwrap_or(false),
             encoder_pref: std::env::var("PUNKTFUNK_ENCODER")
                 .unwrap_or_default()
                 .to_ascii_lowercase(),

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

@@ -15,9 +15,6 @@
 //! `<linux/uinput.h>` on x86_64. `/dev/uinput` needs a udev rule + `input` group membership
 //! (see `scripts/60-punktfunk.rules`); creation fails with a clear error otherwise.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use crate::pad_slots::PadSlots;
 use anyhow::{bail, Result};
 use punktfunk_core::input::{gamepad, GamepadFrame, MAX_PADS};

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

@@ -17,8 +17,6 @@
 //! output's logical rectangle — the same shape the libei backend uses with its EI region.
 
 #![allow(clippy::all, dead_code, non_camel_case_types, non_snake_case, unused)]
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{gs_button_to_evdev, vk_to_evdev, InputEvent, InputInjector};
 use anyhow::{Context, Result};

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

@@ -6,9 +6,6 @@
 //! to evdev/US), and translate events into virtual pointer/keyboard requests, tracking modifier
 //! state so the compositor resolves shifted keysyms correctly.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use super::{gs_button_to_evdev, vk_to_evdev, InputEvent, InputInjector};
 use anyhow::{bail, Context, Result};
 use punktfunk_core::input::InputKind;

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

@@ -15,9 +15,6 @@
 //! with its position (never at a stale point), tip edges get their own DOWN/UP frames, and a
 //! range-leave is a final frame without `INRANGE`.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it.
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use anyhow::{Context, Result};
 use punktfunk_core::input::{InputEvent, InputKind};
 use punktfunk_core::quic::{

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

@@ -14,9 +14,6 @@
 //! user's, and any layout re-reads a *position* as a *character* — on a German host that is
 //! exactly the y↔z swap / ü-on-ö scramble.
 
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it.
-#![deny(clippy::undocumented_unsafe_blocks)]
-
 use anyhow::Result;
 use punktfunk_core::input::{InputEvent, InputKind};
 use std::mem::size_of;

crates/pf-inject/src/lib.rs

@@ -14,13 +14,6 @@
 
 // Scaffold: trait methods + per-OS backends are defined ahead of the target that uses them.
 #![allow(dead_code)]
-// Every unsafe block in this crate carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-// …and its companion: without this, an `unsafe fn` body needs no blocks, so an unproven FFI call
-// could hide inside one and still satisfy the deny above. The workspace keeps
-// `unsafe_op_in_unsafe_fn` at `warn` while the encoder backends are cleared; this crate is at zero.
-#![deny(unsafe_op_in_unsafe_fn)]
-
 use anyhow::Result;
 use punktfunk_core::input::{InputEvent, InputKind};
 

crates/pf-presenter/src/lib.rs

@@ -17,7 +17,6 @@
 //! the decode chain there is Vulkan → D3D11VA → software.
 
 // Unsafe-proof program: every `unsafe {}` in this crate carries a `// SAFETY:` proof.
-#![deny(clippy::undocumented_unsafe_blocks)]
 
 // THE VULKAN CONTRACT, stated once - most `// SAFETY:` proofs in this crate are an instance of it.
 //

crates/pf-update-check/src/lib.rs

@@ -14,6 +14,12 @@
 //! and per-platform; it lives with the product that does it (`punktfunk-host::update`,
 //! `pf-client-core::update`, and the root helper in `pf-update`).
 
+// This crate parses a SIGNED, NETWORK-FETCHED manifest and, per the header above, "owns the part
+// where being wrong is a security bug". Signature verification is worthless if the parser around
+// it can be made to read out of bounds, so the absence of unsafe here is a security property and
+// is now enforced rather than merely true today.
+#![forbid(unsafe_code)]
+
 /// The Ed25519 public keys trusted for update manifests — two slots, so a key rotation is
 /// "sign with the new one, ship builds trusting both, retire the old" (the plugin-store
 /// `OFFICIAL_KEYS` drill) rather than a flag day. The private half is the

crates/pf-update/Cargo.toml

@@ -18,3 +18,6 @@ path = "src/main.rs"
 [target.'cfg(target_os = "linux")'.dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+
+[lints]
+workspace = true

crates/pf-update/src/main.rs

@@ -25,6 +25,12 @@
 //! (root-written, world-readable) for the unprivileged caller to read; stdout/stderr land in
 //! the unit's journal.
 
+// ROOT RUNS THIS. `deny` rather than `forbid` only because of the single `geteuid` call in
+// `linux_main::effective_uid`, which carries the one localized `#[allow(unsafe_code)]` in the
+// crate and explains there why it is not worth a dependency to remove. Any NEW unsafe anywhere
+// in this helper is a build error.
+#![deny(unsafe_code)]
+
 #[cfg(target_os = "linux")]
 mod linux_main {
     use serde::Serialize;
@@ -313,8 +319,7 @@ mod linux_main {
         };
         // Effective root is required for every leg; refuse early with a clear message
         // rather than half-running.
-        // SAFETY: geteuid has no preconditions.
-        if unsafe { libc_geteuid() } != 0 {
+        if effective_uid() != 0 {
             eprintln!("pf-update: must run as root (start punktfunk-update.service)");
             std::process::exit(1);
         }
@@ -397,6 +402,20 @@ mod linux_main {
         #[link_name = "geteuid"]
         fn libc_geteuid() -> u32;
     }
+
+    /// The crate's ONLY unsafe operation, isolated so the crate-level `deny(unsafe_code)` can
+    /// stand and the exemption is one named function rather than a whole call site.
+    ///
+    /// Deliberately NOT rewritten to `rustix::process::geteuid()`: this crate's Cargo.toml states
+    /// that the zero-dependency posture *is* a security invariant of a root helper ("no HTTP
+    /// client, no TLS, no argument parsing"), so pulling in a general-purpose syscall crate to
+    /// delete one `unsafe` would trade a real property for a cosmetic one.
+    #[allow(unsafe_code)]
+    fn effective_uid() -> u32 {
+        // SAFETY: `geteuid` is a POSIX syscall wrapper that takes no arguments, reads no memory
+        // through a pointer, cannot fail, and has no preconditions whatsoever.
+        unsafe { libc_geteuid() }
+    }
 }
 
 #[cfg(target_os = "linux")]

crates/pf-vaadec/src/lib.rs

@@ -78,6 +78,13 @@
 //! a `VASurfaceID` rather than an index — so the conversion will take that table as
 //! a parameter and stay pure.
 
+// The header above states the crate's whole design constraint: it is the CPU-testable half, it
+// links no libva, and it compiles on macOS — "which is the point". That constraint is exactly
+// what `forbid(unsafe_code)` encodes. The crate is full of hand-declared libva `repr(C)` mirrors,
+// and the moment one of them gets dereferenced through a raw pointer here, the crate has quietly
+// become the other half and stops being testable off a Linux box with a GPU.
+#![forbid(unsafe_code)]
+
 pub mod config;
 pub mod drm;
 pub mod pic;

crates/pf-vdisplay/Cargo.toml

@@ -16,13 +16,9 @@ publish = false
 
 [dependencies]
 punktfunk-core = { path = "../punktfunk-core", features = ["quic"] }
-pf-frame = { path = "../pf-frame" }
-pf-gpu = { path = "../pf-gpu" }
 pf-host-config = { path = "../pf-host-config" }
 pf-paths = { path = "../pf-paths" }
 pf-win-display = { path = "../pf-win-display" }
-# The Windows admission gate consults NVENC's session budget (can_open_another_session).
-pf-encode = { path = "../pf-encode" }
 anyhow = "1"
 tracing = "0.1"
 # The platform-neutral policy/identity/custom-preset state is serde-serialized (persisted + the mgmt
@@ -41,8 +37,12 @@ hex = "0.4"
 # the shipped host's dependency closure through this crate is unchanged.
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 
-[target.'cfg(target_os = "linux")'.dependencies]
+# `proc`'s process-group tree guard is Unix-wide, not Linux-only: the module is compiled on every
+# platform and its tests run on whatever the developer is sitting at (macOS, here).
+[target.'cfg(unix)'.dependencies]
 libc = "0.2"
+
+[target.'cfg(target_os = "linux")'.dependencies]
 # The Mutter backend drives D-Bus RemoteDesktop + ScreenCast.RecordVirtual via ashpd on a tokio
 # runtime; the gamescope restore worker + portal handshakes use tokio too.
 ashpd = { version = "0.13", features = ["screencast", "remote_desktop"] }
@@ -61,6 +61,15 @@ bitflags = "2"
 x11rb = { version = "0.13", default-features = false }
 
 [target.'cfg(target_os = "windows")'.dependencies]
+# Windows-only, all three, and gated here rather than unconditionally so the LINUX build does not
+# drag their closures in for nothing: `pf-frame` for the DXGI capture identity + the CTA-861.3 HDR
+# luminance fields, `pf-gpu` for the render-adapter LUID, and `pf-encode` for the admission gate's
+# NVENC session budget (`can_open_another_session`, admission.rs, itself `#[cfg(windows)]`). Every
+# use site of all three is Windows-gated — verified by grep — and between them they pull FFmpeg,
+# ash and openh264, none of which a Linux host reaches through this crate.
+pf-frame = { path = "../pf-frame" }
+pf-gpu = { path = "../pf-gpu" }
+pf-encode = { path = "../pf-encode" }
 # The host<->driver wire contract for the pf-vdisplay IddCx backend (control IOCTLs + Pod structs).
 pf-driver-proto = { path = "../pf-driver-proto" }
 bytemuck = { version = "1.19", features = ["derive"] }

crates/pf-vdisplay/src/lib.rs

@@ -8,25 +8,37 @@
 //! * **KWin** — privileged `zkde_screencast_unstable_v1::stream_virtual_output` ([`kwin`]).
 //! * **wlroots/Sway** — `swaymsg create_output` + `output mode --custom` ([`wlroots`]).
 //! * **Mutter/GNOME** — D-Bus `RemoteDesktop` + `ScreenCast.RecordVirtual` ([`mutter`]).
+//! * **Hyprland** — `hyprctl output create headless` + the xdg-desktop-portal-hyprland ScreenCast
+//!   portal. Its own backend, not a wlroots dialect (`design/hyprland-support.md` D1).
+//! * **gamescope** — three sub-modes behind one backend ([`GamescopeRoute`]): bare
+//!   **spawn** of a nested headless session, host-**managed** `gamescope-session-plus`/SteamOS
+//!   takeover, and **attach** to a session somebody else started. By far the largest backend here,
+//!   because it owns session lifecycle rather than just minting an output.
+//! * **monitor mirror** — no virtual display at all: stream a PHYSICAL head the compositor already
+//!   has (the `PUNKTFUNK_CAPTURE_MONITOR` pin), reporting [`DisplayOwnership::External`] so none of
+//!   the lifecycle policy is applied to someone else's screen.
+//! * **Windows pf-vdisplay** — the all-Rust IddCx driver + its `manager`, the sole Windows backend.
+//!
+//! No list of file sizes here: it rots. The rule instead — the Linux backends plus the Windows
+//! manager are the bulk of this crate, and the platform-neutral half (`policy`, `registry`,
+//! `lifecycle`, `layout`, `identity`, `admission`, `monitors`, `session`, `routing`, `proc`,
+//! `portal_config`) is the minority that every platform's CI actually compiles and tests.
 //!
 //! [`VirtualDisplay::create`] returns a [`VirtualOutput`]: the PipeWire node to capture plus an
 //! owned keepalive whose `Drop` releases the output (RAII — no explicit `destroy`). Capture
 //! consumes the node via the host `capture::capture_virtual_output`.
 
-// `dead_code` is ENFORCED on Linux, where ~10k of this crate's ~17k lines live. Off elsewhere for
-// one structural reason: `proc`, `session`, `routing`, `monitors` and `lifecycle` are declared
-// unconditionally but exist to serve the Linux backends, so on Windows/macOS most of their surface
-// is legitimately unreferenced. Scoping it this way rather than crate-wide keeps the platform that
-// owns the code honest. (Was a bare crate-wide allow whose "scaffold, defined ahead of the target
-// that uses them" rationale had stopped being true.)
+// `dead_code` is ENFORCED on Linux, where the clear majority of this crate lives — every compositor
+// backend under `vdisplay/linux/` plus everything only they consume, which is roughly half the crate
+// on its own and the half that carries the session-lifecycle risk. Off elsewhere for one structural
+// reason: `proc`, `session`, `routing`, `monitors` and `lifecycle` are declared unconditionally but
+// exist to serve the Linux backends, so on Windows/macOS most of their surface is legitimately
+// unreferenced. Note what that waives: the Windows backend (`vdisplay/windows/`, itself thousands of
+// lines) gets NO dead-code enforcement, so an orphaned Windows path has to be found by review.
+// Scoping it this way rather than crate-wide still keeps the platform that owns most of the code
+// honest. (Was a bare crate-wide allow whose "scaffold, defined ahead of the target that uses them"
+// rationale had stopped being true.)
 #![cfg_attr(not(target_os = "linux"), allow(dead_code))]
-// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
-#![deny(clippy::undocumented_unsafe_blocks)]
-// …and that program only covers a whole `unsafe fn` body once the body needs its own block: in
-// edition 2021 `unsafe_op_in_unsafe_fn` is allow-by-default, which exempted this crate's hardest
-// FFI from the deny above — every IOCTL wrapper, and `restore_displays_ccd`, the call the whole
-// Windows teardown path depends on to give the operator their physical panels back.
-#![deny(unsafe_op_in_unsafe_fn)]
 
 use anyhow::Result;
 pub use punktfunk_core::Mode;
@@ -200,9 +212,16 @@ impl Compositor {
 /// The compositor backends usable on this host *right now*: gamescope wherever its binary is
 /// installed (it spawns a nested session — independent of the running desktop), plus the live
 /// session's own compositor (KWin / Mutter / wlroots / Hyprland) when the host runs inside it.
-/// Cheap, side-effect-free probes — safe to call per management request. A concrete client
-/// preference is validated against this set before it's honored (see the punktfunk/1 handshake's
-/// resolution).
+/// Side-effect-free, but **not cheap, and not memoized**: every call re-walks `/proc`
+/// ([`detect_active_session`]), and each backend probe that the live/pinned short-circuit below does
+/// not exempt does real work — `gamescope::is_available` FORKS `gamescope --version`,
+/// `kwin::is_available` does a Wayland registry roundtrip, `wlroots`/`hyprland` read a socket path
+/// and `mutter` a D-Bus name. So a console polling `/host/compositors` on a KDE box still forks a
+/// gamescope per poll, on a thread the caller must therefore not assume is cheap to block (mgmt
+/// calls it inline on the async runtime). Callers wanting a hot path should cache the answer;
+/// treating this as free is what the "cheap, safe per management request" claim this doc used to
+/// make invited. A concrete client preference is validated against this set before it's honored
+/// (see the punktfunk/1 handshake's resolution).
 ///
 /// The **live session is the primary signal**, ahead of each backend's own probe. Those probes read
 /// the process env (`XDG_CURRENT_DESKTOP` for Mutter, `WAYLAND_DISPLAY` for KWin's registry
@@ -311,7 +330,12 @@ pub fn detect() -> Result<Compositor> {
         if let Some(c) = compositor_for_kind(detect_active_session().kind) {
             return Ok(c);
         }
-        let desktop = std::env::var("XDG_CURRENT_DESKTOP")
+        // Under [`ENV_LOCK`]: `apply_session_env` `set_var`s — and, for a dead session,
+        // `remove_var`s — this very key from another session's `spawn_blocking`, and a glibc
+        // `getenv` concurrent with a `setenv` is the `environ` realloc data race ENV_LOCK exists
+        // for (it is UB regardless of which key each side touches, so "different variable" is no
+        // defence). Read-then-drop: only the read needs serializing.
+        let desktop = with_env_lock(|| std::env::var("XDG_CURRENT_DESKTOP"))
             .unwrap_or_default()
             .to_ascii_uppercase();
         if desktop.contains("KDE") {
@@ -559,13 +583,18 @@ pub fn effective_topology() -> policy::Topology {
         return resolve_topology(e.topology);
     }
     // Unconfigured: honor a legacy operator env if present (a host runs one desktop backend, so at
-    // most one of these is set), else the Auto default.
-    let legacy = [
-        "PUNKTFUNK_KWIN_VIRTUAL_PRIMARY",
-        "PUNKTFUNK_MUTTER_VIRTUAL_PRIMARY",
-    ]
-    .iter()
-    .find_map(|k| std::env::var(k).ok());
+    // most one of these is set), else the Auto default. Read under [`ENV_LOCK`] like every other
+    // env read on the session-setup path: this runs inside `create`, concurrent with another
+    // session's `apply_session_env` `set_var`s, and glibc's `environ` realloc makes a racing
+    // `getenv` UB no matter that these particular keys are ones nobody writes.
+    let legacy = with_env_lock(|| {
+        [
+            "PUNKTFUNK_KWIN_VIRTUAL_PRIMARY",
+            "PUNKTFUNK_MUTTER_VIRTUAL_PRIMARY",
+        ]
+        .iter()
+        .find_map(|k| std::env::var(k).ok())
+    });
     match legacy.as_deref().map(str::trim) {
         Some("1" | "true" | "yes" | "on") => policy::Topology::Exclusive,
         Some("0" | "false" | "no" | "off") => policy::Topology::Extend,
@@ -637,19 +666,92 @@ pub fn gamescope_composites_cursor() -> bool {
 ///
 /// A host-managed `gamescope-session-plus` / SteamOS session counts as a spawn: we own its
 /// `GAMESCOPE_BIN` wrapper (or PATH shim), so the flags are ours.
+///
+/// **Ask the resolved ROUTE, never the env.** This used to test the spawn-vs-attach term by reading
+/// `PUNKTFUNK_GAMESCOPE_NODE`, which worked only while `apply_input_env` PUBLISHED its decision into
+/// that key. Phase 2.3 deleted the publication (routing.rs: "Nothing is written back to the two
+/// knobs") and left the key as an operator override — rung 2 of a 6-rung ladder — so the session
+/// that reaches [`GamescopeRoute::Attach`] at the ladder's rung 5 instead (a foreign gamescope on an
+/// infra-less box), and the monitor-pin mirror that never consults the ladder at all, both answered
+/// "ours". The two consequences were silent and unrecoverable: the punktfunk/1 Welcome fixed the
+/// session at 10-bit BT.2020/PQ against a foreign 8-bit SDR composite, and the host skipped the
+/// XFixes cursor reconstruction for a session whose gamescope was never given
+/// `--pipewire-composite-cursor` — a stream with no pointer in it at all.
+///
+/// **Two residual gaps**, both of which need a route this crate cannot see from here:
+///
+/// * the ladder is re-run with `dedicated_launch = false`, since a capability query carries no
+///   session context — so it cannot see the one input that would move a session from
+///   Managed/Attach to Spawn. On a box with no session infrastructure AND a foreign gamescope
+///   running, a `game_session=dedicated` launch really takes rung 3 (`Spawn`) while this re-run
+///   takes rung 5 (`Attach`) and answers "foreign";
+/// * `create_managed_session` can degrade a resolved `Managed` to an ATTACH at create time (a
+///   mask-fragile DM it may not stop — it then mirrors the box's own game-mode session). That
+///   happens after this answer is due, and the ladder re-run here still says `Managed`, so such a
+///   session is still credited with flags it does not own.
+///
+/// The second over-promises. The first UNDER-promises, and `false` is the deliberate choice for an
+/// input we cannot see, because the two directions do not cost the same: over-promising fixes the
+/// punktfunk/1 Welcome at 10-bit PQ against an 8-bit SDR composite and leaves a stream with **no
+/// pointer at all**, while under-promising costs HDR and draws the pointer twice. But do not read
+/// that as "fails closed": it is not, for the cursor. `gamescope::cursor_args` adds
+/// `--pipewire-composite-cursor` from the BINARY probe alone, ungated by this answer, so on the
+/// bare spawn above gamescope paints the pointer into the node while the host's
+/// `session_plan::gamescope_needs_host_cursor` (`gamescope && !gamescope_composites_cursor()`) also
+/// blends the XFixes pointer on top — two pointers, plus the encoder pushed off its zero-copy arm.
+/// Do not "fix" that by re-running the ladder with a guessed `dedicated_launch = true`: that trades
+/// the mild failure for the severe one on every non-launching session. Both gaps close the same
+/// way, and only that way: give these two functions the session's own [`GamescopeRoute`] (which
+/// `SessionContext` already carries) and have the backend report the degrade — a change to two
+/// public signatures and every host call site, i.e. work outside this crate.
 fn gamescope_ours_and(#[cfg(target_os = "linux")] probe: fn() -> bool) -> bool {
     #[cfg(target_os = "linux")]
     {
-        let attaching = with_env_lock(|| std::env::var_os("PUNKTFUNK_GAMESCOPE_NODE").is_some());
-        !attaching && probe()
+        // `probe` first: it is memoized (the `--version` banner is parsed once per process), while
+        // the route resolution walks `/proc` for a foreign gamescope. On a box with a stock
+        // gamescope the answer is already `false` and the walk never happens.
+        probe()
+            && !session_is_a_foreign_gamescope(
+                capture_monitor().is_some(),
+                resolve_gamescope_route(Compositor::Gamescope, false).as_ref(),
+            )
     }
     #[cfg(not(target_os = "linux"))]
     false
 }
 
-// Platform-neutral per-client stable display-id map (Stage 3): Windows seeds the monitor EDID +
-// ConnectorIndex from the id; KWin names its output from it. `allow(dead_code)` because only Windows
-// consumes it in non-test code today — the KWin wiring is the next Stage-3 step.
+/// Pure predicate behind [`gamescope_ours_and`]: is the gamescope this session will use one
+/// SOMEBODY ELSE started, whose spawn flags we therefore cannot vouch for?
+///
+/// Two ways to land on a foreign session, and both must count:
+///
+/// * `mirror_pinned` — a `PUNKTFUNK_CAPTURE_MONITOR` pin routes [`open`] to the mirror backend,
+///   whose gamescope arm attaches to the node the RUNNING session already publishes without
+///   consulting the sub-mode ladder at all. On a Bazzite/SteamOS box that session is Game Mode's,
+///   i.e. by definition not ours.
+/// * a [`GamescopeRoute::Attach`] verdict — however the ladder reached it (operator override,
+///   or the foreign-gamescope rung).
+///
+/// [`GamescopeRoute::Managed`] is NOT foreign: the managed takeover starts the session through our
+/// own `GAMESCOPE_BIN` wrapper / PATH shim, so its flags are the ones we chose.
+///
+/// `mirror_pinned` is judged from the pin alone, not from whether the mirror actually took: [`open`]
+/// degrades a pin to the virtual-display path when the session reports no physical heads, and a
+/// pinned box that lands there is called foreign here although it will bare-spawn. That is the
+/// fail-closed direction — a capability withheld from a session that could have had it — and the
+/// alternative (enumerating heads from a capability query) would put a compositor roundtrip on a
+/// path that must answer before anything exists to ask.
+fn session_is_a_foreign_gamescope(mirror_pinned: bool, route: Option<&GamescopeRoute>) -> bool {
+    mirror_pinned || matches!(route, Some(GamescopeRoute::Attach { .. }))
+}
+
+// Platform-neutral per-client stable display-id map: Windows seeds the monitor EDID serial +
+// IddCx ConnectorIndex from the id; KWin names its output `Virtual-punktfunk-<id>` (kwin.rs's
+// `resolve_slot` call); Mutter cannot carry the id into its virtual monitor at all, so it keys the
+// host-persisted `ScaleMap` on the same identity key. All three are production call sites, so the
+// `allow(dead_code)` below no longer stands for "unwired yet" (it did when only Windows consumed the
+// map); it now covers whatever helpers no CURRENT backend reaches. Worth re-testing without it —
+// that has to happen on a Linux build, since this is the platform where dead_code is enforced.
 #[allow(dead_code)]
 #[path = "vdisplay/identity.rs"]
 pub(crate) mod identity;
@@ -735,6 +837,48 @@ mod tests {
         assert_eq!(compositor_for_kind(ActiveKind::None), None);
     }
 
+    /// The spawn-vs-attach term behind [`gamescope_hdr_available`] /
+    /// [`gamescope_composites_cursor`]. Both answers are IRREVOCABLE once the punktfunk/1 Welcome
+    /// has gone out (bit depth is fixed there; the session plan's cursor decision feeds the encoder
+    /// open), so an over-promise here is not recoverable at runtime — which is why the regression
+    /// this pins mattered: the term used to be read off `PUNKTFUNK_GAMESCOPE_NODE`, a key nothing
+    /// writes any more, so every foreign session answered "ours".
+    #[test]
+    fn only_a_session_we_start_can_promise_gamescope_capabilities() {
+        // Attach — however the ladder got there — is somebody else's session: unknown spawn flags.
+        assert!(session_is_a_foreign_gamescope(
+            false,
+            Some(&GamescopeRoute::Attach {
+                node: "auto".into()
+            })
+        ));
+        assert!(session_is_a_foreign_gamescope(
+            false,
+            Some(&GamescopeRoute::Attach { node: "42".into() })
+        ));
+        // A bare spawn is ours by definition; so is the managed takeover (it starts gamescope
+        // through our own GAMESCOPE_BIN wrapper / PATH shim, so the flags are the ones we chose).
+        assert!(!session_is_a_foreign_gamescope(
+            false,
+            Some(&GamescopeRoute::Spawn)
+        ));
+        assert!(!session_is_a_foreign_gamescope(
+            false,
+            Some(&GamescopeRoute::Managed {
+                client: "steam".into()
+            })
+        ));
+        // No route at all = not a gamescope session; the binary probe alone then decides.
+        assert!(!session_is_a_foreign_gamescope(false, None));
+        // A monitor pin bypasses the ladder entirely (mirror backend → attach to the node the
+        // RUNNING session publishes), so it is foreign whatever the ladder would have said.
+        assert!(session_is_a_foreign_gamescope(true, None));
+        assert!(session_is_a_foreign_gamescope(
+            true,
+            Some(&GamescopeRoute::Spawn)
+        ));
+    }
+
     #[test]
     fn detect_active_session_is_side_effect_free_and_terminates() {
         // A pure probe of /proc + the runtime dir: it must not panic and must return promptly on

crates/pf-vdisplay/src/vdisplay/admission.rs

@@ -136,7 +136,26 @@ pub fn admit(req_identity: Option<[u8; 32]>) -> Admission {
             !live.is_empty(),
         )
     };
-    let _ = any_live; // read only by the Windows budget block below
+    let _ = any_live; // read only by the budget blocks below
+
+    // The operator's `max_displays` ceiling (design §5.3). Applied HERE, once per connecting
+    // session, and deliberately NOT in the display create path: `acquire` runs again on every
+    // mid-stream rebuild (capture loss, a Game↔Desktop switch), and those rebuild before dropping
+    // the old display — so a ceiling enforced there counts the session against itself and refuses
+    // the recovery. Admission is reached once per connect, so it cannot.
+    #[cfg(target_os = "linux")]
+    if matches!(decision, Admission::Separate) && any_live {
+        // The Linux pool had no ceiling at all: its reuse key includes the CLIENT-SUPPLIED mode, so
+        // a client reconnecting at a different resolution misses reuse and mints a fresh display,
+        // and a handful of reconnects could row out an unbounded number of compositor outputs.
+        let max = policy::prefs().get().effective().max_displays;
+        let live = super::registry::live_display_count();
+        if live >= max {
+            return Admission::Reject(format!(
+                "host display budget exhausted: {live} display(s) live/kept, max_displays = {max}"
+            ));
+        }
+    }
     #[cfg(windows)]
     if matches!(decision, Admission::Separate) && any_live {
         let max = policy::prefs().get().effective().max_displays;