fix(vdisplay/driver,pf-frame): no punktfunk process holds REALTIME GPU priority by default

The RX 9070 XT field A/B (2026-08-11/12 logs) convicted BOTH of our REALTIME
GPU-scheduling levers of generating the metronomic capture-stall class the
stall program has chased for weeks — compose-silence holes of 150-800 ms in
which ETW shows NO process presenting while the GPU stays responsive:

- the vdisplay driver's IddCxSetRealtimeGPUPriority raise beat at ~1.75-1.78 s
  (PFVD_NO_RT_GPU=1 alone removed that metronome: ~0.35 stalls/s metronomic ->
  10 sparse aperiodic over 3.9 min);
- the host auto-gate's HIGH->REALTIME upgrade (pf-frame dxgi.rs, T2.3) beat at
  ~3.58 s in the AV1 sessions where it promoted (vram_pct=1, 12:59:26); pinning
  PUNKTFUNK_GPU_PRIORITY_CLASS=high removed that residual too (13:45 session:
  zero metronomic, stall rate at the clean-run baseline).

Neither period matches any punktfunk clock: the full periodic-actor census
(driver: event-paced drain + 16 ms E_PENDING wait, 33 ms cursor poll, 3 s
watchdog reap; host: 250 ms descriptor poll, 5/50/100 ms probes + ~2 s scanline
retarget, 2 s VRAM gate, 2 s exclusive re-assert, 3.33 s pinger, 1 s stats,
~1 Hz phase-lock, fps/2 LTR marks) has nothing in the 1.69-2.29 s band, and
every host-side actor ran unchanged in the A/B that killed the fast metronome.
The periodicity is emergent from holding an unreachable-priority queue against
the WDDM scheduler on this AMD family (the period even differs by which of our
processes holds REALTIME); it is not a punktfunk cadence being amplified, so
there is nothing punktfunk-periodic to fix - the fix is to stop holding
REALTIME by default, which is also canonical parity (no shipping IDD raises
it, and HIGH was the class that delivered the original Sunshine-parity encode
win).

- Driver: PFVD_NO_RT_GPU (default-ON, opt-OUT) becomes the PFVD_RT_GPU ladder,
  default OFF on every vendor: unset = no raise (canonical IDD behavior);
  =thread = SetGPUThreadPriority(+7), a graduated in-band middle rung for field
  A/B (not default: unmeasured here, and the host measured the same call as "no
  help" for its own starvation case); anything else = the old REALTIME DDI.
  PFVD_NO_RT_GPU stays recognized and WINS over the opt-in, so the field boxes
  that carry it through the default-ON era keep meaning OFF. Both directions
  remain A/B-able without a rebuild (machine env + device restart). The CPU
  half of the original branch-2 hardening (MMCSS / TIME_CRITICAL) is untouched
  - it addressed the delivery holes that were actually observed.
- Host: PUNKTFUNK_GPU_PRIORITY_CLASS default auto -> high. `auto` (the gated
  REALTIME upgrade) stays available as an explicit opt-in, `realtime` still
  pins; unrecognized values now land on the HIGH default instead of silently
  opting into the gate - a typo must not buy the hazard. The VRAM/HAGS gate
  machinery is unchanged for `auto`; it guards the NVENC-hang hazard but cannot
  see this one.
- stall.rs: the no-OS-event METRONOMIC warning now carries rt_gpu_driver /
  rt_gpu_host fields (the machine-env state of both levers) and names clearing
  them as the FIRST cure, ahead of the display-hardware suspects - a field log
  self-answers the triage question this program just spent a week on.

No console policy axis for the driver knob: the lever is default-safe now, the
driver reads config at WUDFHost scope where machine env already matches the
device-restart lifecycle, and a policy axis would need pf-driver-proto churn
(or a device-key registry write) for an experimental lever that only exists to
be A/B-ed. If the `thread` rung ever proves out as a default-worthy raise,
that is the moment to revisit.

.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

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": [
           {
@@ -4788,7 +4788,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 +4857,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 +5915,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 +6132,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 +6183,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 +6195,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 +6355,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/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/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

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; \
@@ -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),
@@ -661,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;
         }
     }
 

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-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;

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

@@ -225,9 +225,20 @@ pub trait VirtualDisplay: Send {
     /// ([`DisplayOwnership::Owned`], keep-alive-able) display? The registry consults this **before**
     /// its keep-alive reuse lookup, so it never hands a kept display of one flavor to a request of
     /// another — specifically a gamescope managed/attach acquire must not reuse a kept **bare-spawn**
-    /// (they share the backend name `"gamescope"`). Default `true`; only gamescope overrides it,
-    /// returning `false` when the env selects attach/managed (consistent with the `ownership` its
-    /// `create` will report). See `design/gamemode-and-dedicated-sessions.md` A1.
+    /// (they share the backend name `"gamescope"`). Overridden by gamescope, which reads the
+    /// resolved [`GamescopeRoute`](crate::GamescopeRoute) carried on the instance (`self.route`, NOT
+    /// env — the sub-mode stopped travelling through `PUNKTFUNK_GAMESCOPE_NODE`/`_SESSION` in Phase
+    /// 2.3): `false` for `Managed` and `Attach`, `true` for `Spawn` **and for no route at all**,
+    /// since `create`'s own `None` arm falls through to the bare spawn — so an instance nobody
+    /// called `set_gamescope_route` on (the operator-pinned `PUNKTFUNK_COMPOSITOR` path) is
+    /// poolable, and takes both the reuse lookup and the `max_displays` ceiling. Also overridden by
+    /// the mirror backend (`false` always). See `design/gamemode-and-dedicated-sessions.md` A1.
+    ///
+    /// The default `true` is a DEFAULT, not a fact: it happens to be right for every backend that
+    /// creates a display it owns, and it is wrong for any backend whose `create` reports something
+    /// other than [`DisplayOwnership::Owned`] — this answer and that one must agree, and nothing
+    /// enforces it. A required method would; making it one costs an impl in each of the five
+    /// per-compositor backends plus Windows.
     fn poolable_now(&self) -> bool {
         true
     }

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

@@ -21,6 +21,7 @@
 //! Persisted to `<config>/display-identity.json` (migrated from the legacy Windows
 //! `pf-vdisplay-identity.json`) so ids — and the client→config association — survive host restarts.
 
+use std::collections::BTreeSet;
 use std::path::PathBuf;
 use std::sync::{Mutex, OnceLock};
 
@@ -78,12 +79,38 @@ impl DisplayIdentityMap {
     pub(crate) fn load() -> Self {
         let dir = pf_paths::config_dir();
         let path = dir.join(FILE);
-        let bytes = std::fs::read(&path)
-            .or_else(|_| std::fs::read(dir.join(LEGACY_FILE)))
-            .ok();
-        let mut store = bytes
-            .and_then(|b| serde_json::from_slice::<Store>(&b).ok())
-            .unwrap_or_default();
+        let (from, bytes) = match std::fs::read(&path) {
+            Ok(b) => (path.clone(), Some(b)),
+            Err(_) => {
+                let legacy = dir.join(LEGACY_FILE);
+                match std::fs::read(&legacy) {
+                    Ok(b) => (legacy, Some(b)),
+                    // No file at all is the ordinary first-run case — not worth a word.
+                    Err(_) => (path.clone(), None),
+                }
+            }
+        };
+        let mut store = match bytes {
+            Some(b) => match serde_json::from_slice::<Store>(&b) {
+                Ok(s) => s,
+                Err(e) => {
+                    // An UNPARSEABLE map used to be swallowed into `Default::default()`, and the very
+                    // next `resolve` persisted that empty store OVER the file — silently discarding
+                    // every client's Windows EDID serial / KWin `Virtual-punktfunk-<id>` and the
+                    // per-display DPI the OS keyed to them. Say so, and move the file aside so the
+                    // damage is recoverable by hand (same treatment `display-presets.json` gets).
+                    tracing::warn!(
+                        path = %from.display(),
+                        error = %e,
+                        "display-identity map is unreadable — starting a fresh one; \
+                         the old file is kept as .bad (every client re-derives its display id once)"
+                    );
+                    let _ = std::fs::rename(&from, from.with_extension("json.bad"));
+                    Store::default()
+                }
+            },
+            None => Store::default(),
+        };
         // SANITIZE a hand-edited / corrupt / cross-version file before trusting it: resolve()'s
         // found-entry branch returns the stored id verbatim, so an out-of-range id (0 = the "auto"
         // sentinel, or > MAX_ID) or a duplicate id/key would flow straight into the display identity.
@@ -100,7 +127,17 @@ impl DisplayIdentityMap {
 
     /// The stable id (`1..=15`) for the client `key` ([`identity_key`]): its remembered id, or a
     /// freshly assigned one (lowest free, else LRU-evict at the cap). Bumps the entry to MRU and persists.
-    pub(crate) fn resolve(&mut self, key: &str) -> u32 {
+    ///
+    /// `live` is the set of ids that currently drive a REAL display (the Windows manager's slot keys
+    /// / the Linux pool's `identity_slot`s). An id in it is never evicted, and when every eviction
+    /// candidate is live this **refuses** (`None`) rather than handing the newcomer an id that is
+    /// already someone else's monitor. That is not hypothetical: the id keys the Windows manager's
+    /// slot map, whose plain-JOIN branch attaches an arriving session to whatever monitor the slot
+    /// already holds — so evicting a live id handed client B client A's streaming monitor, capture
+    /// target and all. Refusing costs the newcomer its stable identity (upstream falls back to the
+    /// shared/auto slot: `resolve_slot` → `None`, `slot_id_for` → `0`); evicting cost a live client
+    /// its session.
+    pub(crate) fn resolve(&mut self, key: &str, live: &BTreeSet<u32>) -> Option<u32> {
         self.store.tick = self.store.tick.wrapping_add(1);
         let now = self.store.tick;
 
@@ -108,32 +145,43 @@ impl DisplayIdentityMap {
             e.seen = now;
             let id = e.id;
             self.persist();
-            return id;
+            return Some(id);
         }
 
-        // New client: prefer the lowest free id in 1..=MAX_ID; if all are taken, evict the LRU entry and
-        // reuse its id (the evicted client re-establishes its scaling once on its next connect).
-        let id = (1..=MAX_ID)
-            .find(|i| !self.store.entries.iter().any(|e| e.id == *i))
-            .unwrap_or_else(|| {
+        // New client: prefer the lowest free id in 1..=MAX_ID; if all are taken, evict the
+        // least-recently-seen entry that is NOT live and reuse its id (that client re-establishes its
+        // scaling once on its next connect).
+        let id = match (1..=MAX_ID).find(|i| !self.store.entries.iter().any(|e| e.id == *i)) {
+            Some(free) => free,
+            None => {
                 let lru = self
                     .store
                     .entries
                     .iter()
                     .enumerate()
+                    .filter(|(_, e)| !live.contains(&e.id))
                     .min_by_key(|(_, e)| e.seen)
-                    .map(|(i, _)| i)
-                    .expect("entries are non-empty whenever every id 1..=MAX_ID is taken");
-                let evicted = self.store.entries.remove(lru);
-                evicted.id
-            });
+                    .map(|(i, _)| i);
+                let Some(lru) = lru else {
+                    tracing::warn!(
+                        cap = MAX_ID,
+                        live = live.len(),
+                        "display identity map is full and every id is driving a live display — \
+                         this client gets the shared/auto display identity (no persisted per-client \
+                         scaling) rather than displacing a live one"
+                    );
+                    return None;
+                };
+                self.store.entries.remove(lru).id
+            }
+        };
         self.store.entries.push(Entry {
             key: key.to_string(),
             id,
             seen: now,
         });
         self.persist();
-        id
+        Some(id)
     }
 
     /// Persist atomically (temp file + rename). Best-effort: a write failure just means a restart may
@@ -168,7 +216,8 @@ pub(crate) fn global() -> &'static Mutex<DisplayIdentityMap> {
 /// Resolve the connecting client's stable slot id per the `identity` policy. When no policy is
 /// configured, `default` applies — **PerClient on Windows / Shared on Linux**, preserving each
 /// platform's historical behavior (Windows always keyed monitors per-client; Linux used one shared
-/// output name). `None` ⇒ shared / anonymous → the backend uses its base name / auto slot.
+/// output name). `None` ⇒ shared / anonymous (or the map [refused](DisplayIdentityMap::resolve) an
+/// id because every one is live) → the backend uses its base name / auto slot.
 pub(crate) fn resolve_slot(
     fp: Option<[u8; 32]>,
     mode: (u32, u32),
@@ -185,12 +234,40 @@ pub(crate) fn resolve_slot(
         Identity::PerClientMode => true,
     };
     let fp = fp?;
-    Some(
-        global()
-            .lock()
-            .unwrap()
-            .resolve(&identity_key(fp, mode, per_client_mode)),
-    )
+    // Sample the live ids BEFORE taking the map lock, never under it: the sources below take the
+    // Windows manager's `state` lock / the Linux pool lock, and this map is reached from inside a
+    // backend `create` — a lock order of (display owner → identity map) in both directions would be
+    // a deadlock. One direction only, and the map lock stays a leaf.
+    let live = live_slot_ids();
+    global()
+        .lock()
+        .unwrap()
+        .resolve(&identity_key(fp, mode, per_client_mode), &live)
+}
+
+/// The identity slots currently driving a REAL display — the eviction guard for
+/// [`DisplayIdentityMap::resolve`]. Windows reads the manager's slot map (the key IS the identity
+/// slot); Linux reads the registry pool's per-entry `identity_slot`. Both include KEPT
+/// (lingering/pinned) displays on purpose: a kept display is a live compositor/driver resource whose
+/// owner is expected back, and the whole point of the id is that the reconnect finds it again.
+/// Anonymous (`0`) is not an identity and never blocks an assignment.
+fn live_slot_ids() -> BTreeSet<u32> {
+    #[cfg(target_os = "windows")]
+    {
+        crate::manager::snapshot()
+            .into_iter()
+            .map(|i| i.slot_id)
+            .filter(|s| *s != 0)
+            .collect()
+    }
+    #[cfg(target_os = "linux")]
+    {
+        crate::registry::live_identity_slots()
+    }
+    #[cfg(not(any(target_os = "windows", target_os = "linux")))]
+    {
+        BTreeSet::new()
+    }
 }
 
 // ---------------------------------------------------------------------------------------
@@ -306,24 +383,31 @@ mod tests {
         }
     }
 
+    /// Nothing is streaming — the ordinary case, where the live set never constrains anything.
+    fn nothing_live() -> BTreeSet<u32> {
+        BTreeSet::new()
+    }
+
     #[test]
     fn stable_across_calls_and_distinct_per_client() {
         let mut m = temp_map("stable");
-        let a1 = m.resolve(&identity_key(fp(1), (1920, 1080), false));
-        let b = m.resolve(&identity_key(fp(2), (1920, 1080), false));
-        let a2 = m.resolve(&identity_key(fp(1), (1280, 720), false)); // per-client: mode ignored
+        let a1 = m.resolve(&identity_key(fp(1), (1920, 1080), false), &nothing_live());
+        let b = m.resolve(&identity_key(fp(2), (1920, 1080), false), &nothing_live());
+        // per-client: mode ignored
+        let a2 = m.resolve(&identity_key(fp(1), (1280, 720), false), &nothing_live());
         assert_eq!(a1, a2, "same client → same id (per-client ignores mode)");
         assert_ne!(a1, b, "distinct clients → distinct ids");
-        assert!((1..=MAX_ID).contains(&a1) && (1..=MAX_ID).contains(&b));
+        assert!(a1.is_some_and(|i| (1..=MAX_ID).contains(&i)));
+        assert!(b.is_some_and(|i| (1..=MAX_ID).contains(&i)));
         let _ = std::fs::remove_file(&m.path);
     }
 
     #[test]
     fn per_client_mode_splits_by_resolution() {
         let mut m = temp_map("permode");
-        let hd = m.resolve(&identity_key(fp(1), (1920, 1080), true));
-        let uhd = m.resolve(&identity_key(fp(1), (3840, 2160), true));
-        let hd2 = m.resolve(&identity_key(fp(1), (1920, 1080), true));
+        let hd = m.resolve(&identity_key(fp(1), (1920, 1080), true), &nothing_live());
+        let uhd = m.resolve(&identity_key(fp(1), (3840, 2160), true), &nothing_live());
+        let hd2 = m.resolve(&identity_key(fp(1), (1920, 1080), true), &nothing_live());
         assert_ne!(hd, uhd, "same client, different resolution → different id");
         assert_eq!(hd, hd2, "same client + resolution → same id");
         let _ = std::fs::remove_file(&m.path);
@@ -333,16 +417,72 @@ mod tests {
     fn lru_eviction_reuses_an_id_at_the_cap() {
         let mut m = temp_map("lru");
         for n in 1..=15u8 {
-            m.resolve(&identity_key(fp(n), (1920, 1080), false));
+            m.resolve(&identity_key(fp(n), (1920, 1080), false), &nothing_live());
         }
-        let _ = m.resolve(&identity_key(fp(2), (1920, 1080), false)); // touch 2 so 1 is LRU
-        let id16 = m.resolve(&identity_key(fp(16), (1920, 1080), false));
+        // touch 2 so 1 is LRU
+        let _ = m.resolve(&identity_key(fp(2), (1920, 1080), false), &nothing_live());
+        let id16 = m
+            .resolve(&identity_key(fp(16), (1920, 1080), false), &nothing_live())
+            .expect("nothing is live → the LRU id is free to take");
         assert!((1..=MAX_ID).contains(&id16));
         assert_eq!(m.store.entries.len(), 15, "cap holds at 15 entries");
         assert!(m.store.entries.iter().all(|e| (1..=MAX_ID).contains(&e.id)));
         let _ = std::fs::remove_file(&m.path);
     }
 
+    /// 10.2: the LRU victim is chosen among ids that are NOT driving a display. Handing the LRU id
+    /// to a newcomer while its owner streams is what let the Windows manager's plain-JOIN branch
+    /// attach the newcomer to the live client's monitor.
+    #[test]
+    fn lru_eviction_never_takes_a_live_id() {
+        let mut m = temp_map("lru-live");
+        let mut ids = Vec::new();
+        for n in 1..=15u8 {
+            ids.push(
+                m.resolve(&identity_key(fp(n), (1920, 1080), false), &nothing_live())
+                    .unwrap(),
+            );
+        }
+        // fp(1) is the least-recently-seen — and it is the one that is streaming.
+        let lru_id = ids[0];
+        let live: BTreeSet<u32> = [lru_id].into_iter().collect();
+        let id16 = m
+            .resolve(&identity_key(fp(16), (1920, 1080), false), &live)
+            .expect("14 idle ids remain — one of them is the victim");
+        assert_ne!(id16, lru_id, "must not take the id of a live display");
+        assert_eq!(id16, ids[1], "the next-least-recently-seen IDLE id instead");
+        // The live client's mapping is untouched, so its reconnect still finds its own display.
+        assert_eq!(
+            m.resolve(&identity_key(fp(1), (1920, 1080), false), &live),
+            Some(lru_id)
+        );
+        let _ = std::fs::remove_file(&m.path);
+    }
+
+    /// Fail-closed at the extreme: every id live ⇒ refuse, rather than displace a streaming client.
+    /// The caller degrades to the shared/auto identity (`resolve_slot` → `None`, `slot_id_for` → 0).
+    #[test]
+    fn refuses_rather_than_evicting_when_every_id_is_live() {
+        let mut m = temp_map("lru-all-live");
+        let mut live = BTreeSet::new();
+        for n in 1..=15u8 {
+            live.insert(
+                m.resolve(&identity_key(fp(n), (1920, 1080), false), &BTreeSet::new())
+                    .unwrap(),
+            );
+        }
+        assert_eq!(
+            m.resolve(&identity_key(fp(16), (1920, 1080), false), &live),
+            None
+        );
+        assert_eq!(m.store.entries.len(), 15, "nothing was evicted");
+        // A KNOWN client is still resolved even when everything is live — it owns that id already.
+        assert!(m
+            .resolve(&identity_key(fp(3), (1920, 1080), false), &live)
+            .is_some());
+        let _ = std::fs::remove_file(&m.path);
+    }
+
     #[test]
     fn key_composition() {
         assert_eq!(identity_key(fp(0xab), (1920, 1080), false).len(), 64); // hex fp only

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

@@ -10,8 +10,16 @@
 //!   deterministic.
 //! * **manual** — per-identity-slot offsets from [`Layout::positions`] (console-arranged): a member
 //!   whose stable identity slot has a stored position sits there; a member with no pin (no stored
-//!   position, or a shared/anonymous identity that has no slot) falls back to its auto-row origin, so
-//!   a half-arranged group never collapses everything onto the origin.
+//!   position, or a shared/anonymous identity that has no slot) is **packed clear of the pins** —
+//!   rowed left-to-right starting past the rightmost pinned edge — so a half-arranged group neither
+//!   collapses everything onto the origin nor drops an unpinned display exactly on top of a pinned
+//!   one. The pins themselves are reproduced verbatim: where two of them overlap, that is the
+//!   operator's own arrangement and not ours to second-guess.
+//!
+//! Members carry no height, so "clear of the pins" is decided on the x axis alone and every pin
+//! counts regardless of its `y` — a vertically-stacked arrangement therefore packs further right than
+//! it strictly needs to. That is the conservative direction: a gap is a cosmetic waste of desktop
+//! coordinate space, an overlap is two desktops fighting over the same pixels.
 //!
 //! Group membership + acquire order live in the registry ([`super::registry`]); this file only turns
 //! that ordered member list into positions.
@@ -24,8 +32,18 @@ pub struct Member {
     /// Stable per-client identity slot — the manual-layout key. `None` for a shared/anonymous
     /// identity (no per-client slot), which can't carry a manual pin and therefore always auto-rows.
     pub identity_slot: Option<u32>,
-    /// Pixel width, for auto-row `x` accumulation. Clamped at 0 (a bogus negative never shifts a
-    /// sibling left).
+    /// The member's width **in the same coordinate space the resulting [`Placement`] is expressed
+    /// in**, for row `x` accumulation. Clamped at 0 (a bogus negative never shifts a sibling left).
+    ///
+    /// ⚠ Every fill site currently uses the requested *mode* width, i.e. pixels. On Windows
+    /// that is also the desktop space (CCD geometry is pixels), so the two agree; on KWin the
+    /// placement is handed to `config.position()`, which is the compositor's **logical** space — the
+    /// two coincide only at scale 1.0, and a per-output scale is exactly what the identity machinery
+    /// exists to make KDE reapply. A 150 %-scaled 2560-wide output occupies 1707 logical px, so
+    /// auto-rowing past it by 2560 leaves an 853-px dead band. Fixing that means dividing by the
+    /// output's applied scale at the KWin fill site (`kwin_output_mgmt` already reads `scale` into
+    /// its device state); this type stays unit-agnostic, and the contract is that whoever fills it
+    /// speaks the consumer's space.
     pub width: i32,
 }
 
@@ -37,30 +55,79 @@ pub struct Placement {
 }
 
 /// The auto-row origin of member `i`: the summed width of every prior member, top-aligned.
+/// `saturating_add` because the widths are client-supplied through the requested mode — an absurd
+/// one must produce an absurd coordinate, not a debug-build panic inside the state readout.
 fn auto_row_x(members: &[Member], i: usize) -> i32 {
-    members[..i].iter().map(|m| m.width.max(0)).sum()
+    members[..i]
+        .iter()
+        .fold(0i32, |x, m| x.saturating_add(m.width.max(0)))
+}
+
+/// The manual pin for `m`, if its identity slot carries one. The lookup is an exact string match on
+/// the canonical decimal slot id — `DisplayPolicy::sanitized` re-keys the table to that form on
+/// write, so a `"01"` typed into a hand-edited settings file still resolves here.
+fn pin_of(m: &Member, layout: &Layout) -> Option<Placement> {
+    m.identity_slot
+        .and_then(|slot| layout.positions.get(&slot.to_string()))
+        .map(|p| Placement { x: p.x, y: p.y })
 }
 
 /// Arrange `members` (in acquire order) per `layout`, returning one [`Placement`] per member in the
 /// same order. Pure — the single source of truth for auto-row / manual placement, shared by the
 /// state readout and (KWin) the per-backend position apply.
 pub fn arrange(members: &[Member], layout: &Layout) -> Vec<Placement> {
-    members
-        .iter()
-        .enumerate()
-        .map(|(i, m)| {
-            let auto = Placement {
+    match layout.mode {
+        LayoutMode::AutoRow => (0..members.len())
+            .map(|i| Placement {
                 x: auto_row_x(members, i),
                 y: 0,
-            };
-            match layout.mode {
-                LayoutMode::AutoRow => auto,
-                // A pinned member sits at its stored offset; an unpinned one falls back to auto-row.
-                LayoutMode::Manual => m
-                    .identity_slot
-                    .and_then(|slot| layout.positions.get(&slot.to_string()))
-                    .map(|p| Placement { x: p.x, y: p.y })
-                    .unwrap_or(auto),
+            })
+            .collect(),
+        LayoutMode::Manual => arrange_manual(members, layout),
+    }
+}
+
+/// Manual placement: pins verbatim, everything else rowed out past them.
+///
+/// The unpinned fallback used to be the unconditional auto-row prefix sum — computed as if the pins
+/// did not exist — so an unpinned display could land exactly on top of a pinned sibling with nothing
+/// downstream noticing (the arrangement is only ever *reported* and *applied*, never validated). One
+/// number in this crate's own fixture separated the tested case from that collision. Rowing the
+/// unpinned members from the rightmost pinned edge instead makes the overlap unrepresentable within
+/// one call, and keeps three of the fallback's properties: deterministic, acquire-ordered, and
+/// identical to plain auto-row when nothing is pinned.
+///
+/// ⚠ **The fourth property is gone, knowingly: incremental stability.** The prefix sum could not
+/// move member `i` when member `i+1` joined; this cursor is seeded from the pins of *all* members,
+/// so an already-placed unpinned member's computed `x` shifts the moment a pinned sibling arrives
+/// later in acquire order. Nothing re-applies it — `registry::position_for_new` takes only the
+/// `.last()` placement and the registry moves the newly-acquired display alone — so in that ordering
+/// `GET /display/state` reports a position the desktop never received (the pre-existing shape of
+/// this: an auto-row teardown already shifts every survivor's reported `x` with no re-apply; the
+/// packing widens the class to joins under `Manual`). It is not fixable here: the honest fix is for
+/// the registry to re-apply the WHOLE group's arrangement on any membership change under
+/// `LayoutMode::Manual`, the way `windows/manager.rs`'s `arrange_slots` already does, at which point
+/// this function is right in every ordering. Seeding the cursor from preceding pins only would buy
+/// incremental stability back by reintroducing the collision this exists to prevent — the wrong
+/// trade, since the common ordering (the pin exists, an unpinned client joins) does reach the apply
+/// path and is placed correctly.
+fn arrange_manual(members: &[Member], layout: &Layout) -> Vec<Placement> {
+    let pins: Vec<Option<Placement>> = members.iter().map(|m| pin_of(m, layout)).collect();
+    // Start the unpinned row at the desktop origin, or past the rightmost pinned edge when there is
+    // one. `max(0)` on the width keeps a bogus negative from pulling the cursor back over a pin.
+    let mut cursor = pins
+        .iter()
+        .zip(members)
+        .filter_map(|(pin, m)| pin.map(|p| p.x.saturating_add(m.width.max(0))))
+        .fold(0i32, i32::max);
+    pins.iter()
+        .zip(members)
+        .map(|(pin, m)| match pin {
+            Some(p) => *p,
+            None => {
+                let at = Placement { x: cursor, y: 0 };
+                cursor = cursor.saturating_add(m.width.max(0));
+                at
             }
         })
         .collect()
@@ -115,14 +182,153 @@ mod tests {
     }
 
     #[test]
-    fn manual_unpinned_and_slotless_fall_back_to_auto_row() {
+    fn manual_unpinned_and_slotless_pack_clear_of_the_pins() {
         let members = [m(Some(1), 2560), m(Some(9), 1920), m(None, 1280)];
         // Only slot 1 is pinned; slot 9 has no stored pin; the third has no slot at all.
         let layout = manual(&[("1", 100, 50)]);
         let out = arrange(&members, &layout);
         assert_eq!(out[0], Placement { x: 100, y: 50 }, "pinned");
-        assert_eq!(out[1], Placement { x: 2560, y: 0 }, "unpinned → auto-row");
-        assert_eq!(out[2], Placement { x: 4480, y: 0 }, "slotless → auto-row");
+        // The pin occupies [100, 2660); the unpinned members row out from its right edge in acquire
+        // order, NOT from the pin-blind prefix sum (which would have put the first one at 2560 —
+        // inside the pin).
+        assert_eq!(
+            out[1],
+            Placement { x: 2660, y: 0 },
+            "unpinned → past the pin"
+        );
+        assert_eq!(out[2], Placement { x: 4580, y: 0 }, "slotless → past both");
+    }
+
+    #[test]
+    fn manual_with_no_pins_at_all_is_plain_auto_row() {
+        // The fallback must not drift from auto-row when the manual table happens to be empty (the
+        // state a group is in the instant `manual` is selected and nothing has been arranged yet).
+        let members = [m(Some(1), 2560), m(Some(2), 1920), m(None, 1280)];
+        let out = arrange(&members, &manual(&[]));
+        assert_eq!(out, arrange(&members, &Layout::default()));
+    }
+
+    #[test]
+    fn a_manual_pin_that_would_collide_with_an_auto_row_sibling_is_packed_clear() {
+        // The exact geometry §13 11.8 names: a pin sitting where the pin-blind auto-row would have
+        // put the unpinned sibling. Two displays on one origin = two desktops on the same pixels.
+        let members = [m(Some(1), 2560), m(Some(9), 1920)];
+        let layout = manual(&[("1", 2560, 0)]);
+        let out = arrange(&members, &layout);
+        assert_eq!(out[0], Placement { x: 2560, y: 0 }, "pin honored verbatim");
+        assert_ne!(
+            out[1], out[0],
+            "the unpinned sibling must not land on the pin"
+        );
+        assert_eq!(
+            out[1],
+            Placement { x: 5120, y: 0 },
+            "past the pin's right edge"
+        );
+    }
+
+    #[test]
+    fn a_pin_left_of_the_origin_still_leaves_the_unpinned_row_at_zero() {
+        // A negative pin is legal (KWin's global space extends left of 0). Its right edge is what
+        // matters: at -3000+2560 = -440 it constrains nothing, so the row still starts at the origin.
+        let members = [m(Some(1), 2560), m(Some(9), 1920)];
+        let out = arrange(&members, &manual(&[("1", -3000, 0)]));
+        assert_eq!(out[0], Placement { x: -3000, y: 0 });
+        assert_eq!(out[1], Placement { x: 0, y: 0 });
+    }
+
+    #[test]
+    fn absurd_widths_saturate_instead_of_panicking() {
+        // Widths originate in the client-requested mode; a hostile or corrupt one must produce an
+        // absurd coordinate, not an overflow panic inside the `/display/state` readout.
+        let members = [m(Some(1), i32::MAX), m(Some(2), i32::MAX), m(None, 4096)];
+        let out = arrange(&members, &Layout::default());
+        assert_eq!(out[2], Placement { x: i32::MAX, y: 0 });
+        let out = arrange(&members, &manual(&[("1", i32::MAX, 0)]));
+        assert_eq!(out[2], Placement { x: i32::MAX, y: 0 });
+    }
+
+    /// Property (deterministic seeded walk): across arbitrary member widths, slot assignments and pin
+    /// tables, **no unpinned member may share desktop space with any sibling**. Overlap between two
+    /// *pins* is excluded from the invariant — that is the operator's own arrangement, faithfully
+    /// reproduced. Members carry no height, so "share space" is decided on the x interval alone,
+    /// which is the strictest reading available here.
+    #[test]
+    fn no_unpinned_member_overlaps_a_sibling_under_any_layout() {
+        // Tiny deterministic LCG (Numerical Recipes) — reproducible, no dependency. Same shape as
+        // `lifecycle`'s property walk.
+        let mut rng: u64 = 0x0bad_f00d_dead_beef;
+        let mut next = || {
+            rng = rng
+                .wrapping_mul(6364136223846793005)
+                .wrapping_add(1442695040888963407);
+            (rng >> 33) as u32
+        };
+
+        for _ in 0..20_000 {
+            let count = (next() % 6) as usize;
+            let members: Vec<Member> = (0..count)
+                .map(|_| {
+                    // A slot only sometimes, and from a small pool so collisions with the pin table
+                    // are frequent; widths include 0 and the odd negative.
+                    let slot = match next() % 4 {
+                        0 => None,
+                        _ => Some(next() % 6 + 1),
+                    };
+                    let width = match next() % 8 {
+                        0 => 0,
+                        1 => -((next() % 4000) as i32),
+                        _ => (next() % 4000) as i32,
+                    };
+                    m(slot, width)
+                })
+                .collect();
+            let mut pairs: Vec<(String, i32, i32)> = Vec::new();
+            for slot in 1..=6u32 {
+                if next() % 2 == 0 {
+                    let x = (next() % 8000) as i32 - 2000;
+                    let y = ((next() % 3) * 1440) as i32;
+                    pairs.push((slot.to_string(), x, y));
+                }
+            }
+            let borrowed: Vec<(&str, i32, i32)> =
+                pairs.iter().map(|(k, x, y)| (k.as_str(), *x, *y)).collect();
+
+            for layout in [Layout::default(), manual(&borrowed)] {
+                let out = arrange(&members, &layout);
+                assert_eq!(out.len(), members.len());
+                let pinned: Vec<bool> = members
+                    .iter()
+                    .map(|mem| pin_of(mem, &layout).is_some())
+                    .collect();
+                for i in 0..out.len() {
+                    for j in (i + 1)..out.len() {
+                        if pinned[i] && pinned[j] {
+                            continue; // the operator's own arrangement
+                        }
+                        let span = |k: usize| {
+                            let x = out[k].x as i64;
+                            (x, x + members[k].width.max(0) as i64)
+                        };
+                        let (ai, bi) = span(i);
+                        let (aj, bj) = span(j);
+                        // Empty spans (a zero/negative width) can't collide with anything.
+                        if ai >= bi || aj >= bj {
+                            continue;
+                        }
+                        assert!(
+                            bi <= aj || bj <= ai,
+                            "members {i} {:?} and {j} {:?} overlap under {layout:?} \
+                             (widths {} / {})",
+                            out[i],
+                            out[j],
+                            members[i].width,
+                            members[j].width
+                        );
+                    }
+                }
+            }
+        }
     }
 
     #[test]

crates/pf-vdisplay/src/vdisplay/linux/gamescope/discovery.rs

@@ -5,10 +5,18 @@
 
 use super::*;
 
-/// Wait for gamescope to report its PipeWire node. Authoritative source: gamescope's own log
-/// line `stream available on node ID: N` (its node carries `node.name=gamescope` on TWO objects
-/// — the adapter and the inner stream — and only the advertised id is the correct capture
-/// target). Falls back to `pw-dump` discovery if the log line doesn't show.
+/// Budget for a `pw-dump` snapshot. Two facts make an unbounded one the worst call in this file:
+/// it is polled every 300–500 ms from three separate 45 s loops, and it talks to the very daemon
+/// this module documents gamescope as head-blocking below [`MIN_GAMESCOPE`] — so the failure mode
+/// is not "slow", it is "never returns", on the session's own stream thread. Two seconds is far
+/// above a populated graph's real cost; every caller already has a "couldn't ask" path.
+const PW_DUMP_BUDGET: Duration = Duration::from_secs(2);
+
+/// Budget for a `gamescope --version` probe. It loads the binary and prints a banner — no Vulkan
+/// device, no daemon — so anything approaching this bound is a binary that cannot run at all,
+/// which is exactly what a `None`/`false` answer means to each caller.
+const VERSION_PROBE_BUDGET: Duration = Duration::from_secs(2);
+
 /// B2 (game-exit detection): confirm a **dedicated** gamescope session's game has exited. gamescope is
 /// a single-app compositor — it exits when its nested app exits — so once capture is lost, THIS
 /// session's `node_id` not reappearing within a short confirmation window means the game quit (vs. a
@@ -159,16 +167,51 @@ pub(super) fn poll_managed_node(timeout: Duration) -> Option<u32> {
     }
 }
 
+/// Wait for a freshly spawned gamescope to report its PipeWire node. Authoritative source:
+/// gamescope's own log line `stream available on node ID: N` (its node carries
+/// `node.name=gamescope` on TWO objects — the adapter and the inner stream — and only the
+/// advertised id is the correct capture target). Falls back, at the deadline, to `pw-dump`
+/// discovery SCOPED to this spawn's process tree (`child`'s pid, A5), so a coexisting gamescope's
+/// node is never mistaken for ours.
+///
+/// Takes the `Child` rather than a bare pid so it can **stop early when gamescope is already
+/// dead**. A gamescope that fails `vkCreateDevice` exits in under a second, and polling its corpse
+/// for the full 15 s bought nothing except a caller error that blamed the wrong thing ("headless
+/// capture is unsupported on this GPU/driver"). `try_wait` turns that into an immediate `None`
+/// while the log — which the caller names in the same error — still holds the real reason.
 pub(super) fn wait_for_node(
     timeout: Duration,
     log: &std::path::Path,
-    child_pid: u32,
+    child: &mut Child,
 ) -> Option<u32> {
+    let child_pid = child.id();
     let deadline = Instant::now() + timeout;
     loop {
         if let Some(id) = node_from_log(log) {
             return Some(id);
         }
+        // Check for a node FIRST, then for death: a gamescope that published its node and then
+        // exited in the same tick still gives us the id, and the caller's own liveness handling
+        // (the keepalive `Child`, `kept_display_alive`) owns what happens next.
+        match child.try_wait() {
+            // Still running — keep waiting.
+            Ok(None) => {}
+            // Exited. One last scoped look (the node line may have been written between the two
+            // reads above), then give up rather than poll a corpse to the deadline.
+            Ok(Some(status)) => {
+                tracing::warn!(
+                    pid = child_pid,
+                    %status,
+                    log = %log.display(),
+                    "gamescope: the spawned process exited before publishing a PipeWire node — \
+                     not waiting out the rest of the budget"
+                );
+                return node_from_log(log).or_else(|| find_gamescope_node_scoped(Some(child_pid)));
+            }
+            // `try_wait` itself failed (the child was reaped elsewhere, ECHILD): fall back to the
+            // old behaviour rather than inventing a death.
+            Err(_) => {}
+        }
         if Instant::now() >= deadline {
             // Last-resort fallback scoped to THIS spawn's process tree (A5), so a coexisting gamescope's
             // node isn't picked by mistake.
@@ -197,7 +240,10 @@ fn node_from_log(log: &std::path::Path) -> Option<u32> {
 /// keep-alive reuse liveness probe ([`GamescopeDisplay::kept_display_alive`]): a kept gamescope node
 /// vanishes when its nested game exits, so a missing id means "recreate, don't reuse the corpse".
 pub(super) fn gamescope_node_present(node_id: u32) -> bool {
-    let Ok(out) = Command::new("pw-dump").arg(node_id.to_string()).output() else {
+    let Ok(out) = crate::proc::output_within(
+        Command::new("pw-dump").arg(node_id.to_string()),
+        PW_DUMP_BUDGET,
+    ) else {
         // pw-dump unavailable → don't block reuse (mark_failed is the backstop on a genuinely dead node).
         return true;
     };
@@ -229,7 +275,7 @@ pub(super) fn find_gamescope_node() -> Option<u32> {
 /// belong to OUR gamescope's process tree, so a coexisting foreign / other-session gamescope node is
 /// never mistaken for ours). `None` = any gamescope node (the managed/attach paths, single-session).
 fn find_gamescope_node_scoped(scope: Option<u32>) -> Option<u32> {
-    let out = Command::new("pw-dump").output().ok()?;
+    let out = crate::proc::output_within(&mut Command::new("pw-dump"), PW_DUMP_BUDGET).ok()?;
     let dump: serde_json::Value = serde_json::from_slice(&out.stdout).ok()?;
     let nodes = dump.as_array()?;
     let node_props = |obj: &serde_json::Value| -> Option<(u32, String, String, Option<u32>)> {
@@ -302,7 +348,12 @@ fn find_gamescope_node_scoped(scope: Option<u32>) -> Option<u32> {
 /// most recently created (the live session). Returns the bare socket *name* (the injector
 /// resolves it against `XDG_RUNTIME_DIR`, matching libei's own `LIBEI_SOCKET` semantics).
 pub(super) fn find_gamescope_eis_socket() -> Option<String> {
-    let runtime = std::env::var("XDG_RUNTIME_DIR").ok()?;
+    // Under the shared env lock: `session::apply_session_env` `set_var`s XDG_RUNTIME_DIR from the
+    // connect thread, and glibc's setenv/getenv pair is a data race the crate's own `lib.rs`
+    // documents as UB. The lock is not reentrant, so this must stay a read taken HERE and not
+    // hoisted into a caller — the only caller, `point_injector_at_eis`, holds nothing (its
+    // `ei_socket_file()` takes and releases the same lock separately).
+    let runtime = crate::with_env_lock(|| std::env::var("XDG_RUNTIME_DIR").ok())?;
     let mut live: Vec<(std::time::SystemTime, String)> = Vec::new();
     for entry in std::fs::read_dir(&runtime).ok()?.flatten() {
         let name = entry.file_name().to_string_lossy().into_owned();
@@ -328,11 +379,12 @@ pub(super) fn find_gamescope_eis_socket() -> Option<String> {
 /// not require any particular desktop to be running. Quiet (no version warning — that's for the
 /// create path); just checks the binary executes.
 pub(crate) fn is_available() -> bool {
-    std::process::Command::new(gamescope_bin())
-        .arg("--version")
-        .output()
-        .map(|o| o.status.success())
-        .unwrap_or(false)
+    crate::proc::output_within(
+        Command::new(gamescope_bin()).arg("--version"),
+        VERSION_PROBE_BUDGET,
+    )
+    .map(|o| o.status.success())
+    .unwrap_or(false)
 }
 
 /// The gamescope binary this host spawns, resolved ONCE per process:
@@ -400,14 +452,20 @@ fn which_in_path(name: &str) -> Option<String> {
 ///
 /// Monotonic, so one probe answers every capability:
 /// * `1` — 10-bit BT.2020/PQ capture formats ([`gamescope_hdr_capable`]);
-/// * `2` — …and `--pipewire-composite-cursor` ([`gamescope_can_composite_cursor`]).
+/// * `2` — …and `--pipewire-composite-cursor` ([`gamescope_can_composite_cursor`]);
+/// * `3` — …and `--custom-refresh-rates` ([`gamescope_can_offer_refresh_rates`]);
+/// * `4` — …and `--pipewire-composite-external-overlay`
+///   ([`gamescope_can_composite_external_overlay`]).
 ///
 /// When upstream takes the functional patches this becomes a plain version floor, exactly like
 /// [`MIN_GAMESCOPE_OVERLAY`].
 fn gamescope_patch_level() -> u32 {
     static LEVEL: std::sync::OnceLock<u32> = std::sync::OnceLock::new();
     *LEVEL.get_or_init(|| {
-        let Ok(out) = Command::new(gamescope_bin()).arg("--version").output() else {
+        let Ok(out) = crate::proc::output_within(
+            Command::new(gamescope_bin()).arg("--version"),
+            VERSION_PROBE_BUDGET,
+        ) else {
             return 0;
         };
         // The banner goes to stderr on some builds, stdout on others (same as the version gate).
@@ -530,7 +588,8 @@ fn parse_patch_level(banner: &str) -> u32 {
 /// WSI-layer check has to compare TWO binaries — ours and the distro's — and a `None` there means
 /// "leave the layer alone", not "assume old".
 pub(super) fn gamescope_version_of(bin: &std::path::Path) -> Option<(u32, u32, u32)> {
-    let out = Command::new(bin).arg("--version").output().ok()?;
+    let out = crate::proc::output_within(Command::new(bin).arg("--version"), VERSION_PROBE_BUDGET)
+        .ok()?;
     // Same stdout/stderr split as the version gate: builds disagree on where the banner goes.
     let text = format!(
         "{}{}",
@@ -549,8 +608,15 @@ const MIN_GAMESCOPE: (u32, u32, u32) = (3, 16, 22);
 /// the overlay-window paint (gated on the consumer negotiating `gamescope_focus_appid == 0`, which
 /// we do by never advertising that property — see the capturer's EnumFormat builders) first ships
 /// in 3.16.23 (gamescope commits `ccd62074` + `f8b33d38`). Below this the overlay is *never* in the
-/// node, so it cannot appear in the stream no matter what the host does. The cursor and
-/// external-overlay / notification layers are excluded on *every* version (handled host-side).
+/// node, so it cannot appear in the stream no matter what the host does.
+///
+/// On a **stock** gamescope the cursor and external-overlay / notification layers are excluded from
+/// `paint_pipewire` on every version, and the host handles the cursor itself. punktfunk's own build
+/// puts both back: `--pipewire-composite-cursor` at patch level 2+
+/// ([`gamescope_can_composite_cursor`], which is what suppresses the host-side blend) and
+/// `--pipewire-composite-external-overlay` at 4+ ([`gamescope_can_composite_external_overlay`]) —
+/// see [`gamescope_patch_level`]. So "the overlay is missing from the stream" is a question about
+/// which flags reached the running compositor, not about host-side compositing.
 const MIN_GAMESCOPE_OVERLAY: (u32, u32, u32) = (3, 16, 23);
 
 /// Best-effort: warn if the installed gamescope is older than [`MIN_GAMESCOPE`] (capture is
@@ -558,10 +624,11 @@ const MIN_GAMESCOPE_OVERLAY: (u32, u32, u32) = (3, 16, 23);
 /// the stream). Parsing failures are silent (don't block a possibly-fine custom build) — this is a
 /// diagnostic, not a gate. Returns the parsed version when it could read one.
 pub(super) fn check_gamescope_version() -> Option<(u32, u32, u32)> {
-    let out = Command::new(gamescope_bin())
-        .arg("--version")
-        .output()
-        .ok()?;
+    let out = crate::proc::output_within(
+        Command::new(gamescope_bin()).arg("--version"),
+        VERSION_PROBE_BUDGET,
+    )
+    .ok()?;
     // gamescope prints the version banner to stderr on some builds, stdout on others.
     let text = format!(
         "{}{}",

crates/pf-vdisplay/src/vdisplay/linux/gamescope/heads.rs

@@ -34,24 +34,28 @@ pub(crate) fn list_monitors() -> anyhow::Result<Vec<PhysicalMonitor>> {
     Ok(heads_under(
         Path::new("/sys/class/drm"),
         &super::gamescope_argvs(),
-        super::current_gamescope_output_size(),
     ))
 }
 
 /// [`list_monitors`] against an arbitrary sysfs root and a supplied argv set — the unit-testable
-/// core. `output_size` is gamescope's own `-W`/`-H`, which OUTRANKS the EDID's preferred timing
-/// because it is the size the capture node actually produces.
-fn heads_under(
-    base: &Path,
-    argvs: &[Vec<String>],
-    output_size: Option<(u32, u32)>,
-) -> Vec<PhysicalMonitor> {
+/// core.
+///
+/// The head's size comes from the `-W`/`-H` of the argv selected HERE, which OUTRANKS the EDID's
+/// preferred timing because it is the size the capture node actually produces. It used to arrive as
+/// a parameter filled by a scan over ALL gamescopes on the box — including the nested child this
+/// function had just deliberately rejected, and any headless one the crate spawned itself. On a
+/// Deck driving eDP-1 at 1280x800 with a game nested at `-W 1920 -H 1080`, the panel was listed as
+/// 1920x1080, and `mirror::create` publishes that row verbatim as the `preferred_mode` the stream
+/// negotiates against — a mode the composited node never produces, and one `check_mirrorable` waves
+/// through because it only rejects `0x0`.
+fn heads_under(base: &Path, argvs: &[Vec<String>]) -> Vec<PhysicalMonitor> {
     // A gamescope that isn't on DRM has no head of its own. Any DRM-backed one qualifies the box:
     // a Deck streaming from Game Mode often has a second, nested gamescope running the game inside
     // the session one, and that child must not disqualify its parent.
     let Some(argv) = argvs.iter().find(|a| drives_drm(a)) else {
         return Vec::new();
     };
+    let output_size = super::gamescope_output_size(argv);
     let connected = connected_connectors(base);
     if connected.is_empty() {
         return Vec::new();
@@ -342,7 +346,6 @@ mod tests {
         let heads = heads_under(
             &base,
             &[argv("/usr/bin/gamescope --prefer-output HDMI-A-1 --steam")],
-            None,
         );
         assert_eq!(heads.len(), 1);
         assert_eq!(heads[0].connector, "HDMI-A-1");
@@ -366,12 +369,12 @@ mod tests {
             "gamescope --backend sdl",
         ] {
             assert!(
-                heads_under(&base, &[argv(a)], None).is_empty(),
+                heads_under(&base, &[argv(a)]).is_empty(),
                 "expected no heads for {a:?}"
             );
         }
         // No gamescope at all is the same answer, not an error.
-        assert!(heads_under(&base, &[], None).is_empty());
+        assert!(heads_under(&base, &[]).is_empty());
         std::fs::remove_dir_all(&base).unwrap();
     }
 
@@ -384,12 +387,15 @@ mod tests {
             &base,
             &[
                 argv("gamescope --backend wayland -W 1280 -H 800"),
-                argv("/usr/bin/gamescope --prefer-output *,eDP-1 --steam"),
+                argv("/usr/bin/gamescope --prefer-output *,eDP-1 -W 2560 -H 1440 --steam"),
             ],
-            None,
         );
         assert_eq!(heads.len(), 1);
         assert_eq!(heads[0].connector, "eDP-1");
+        // …and the size comes from the DRM PARENT, not from the nested child listed first. Reading
+        // it off any-gamescope-on-the-box is what published a 1280x800 panel as the mirror's
+        // preferred mode on a box where the game happened to be nested at a different size.
+        assert_eq!((heads[0].width, heads[0].height), (2560, 1440));
         std::fs::remove_dir_all(&base).unwrap();
     }
 
@@ -404,7 +410,7 @@ mod tests {
                 ("card1-HDMI-A-1", "connected\n", "enabled\n"),
             ],
         );
-        let heads = heads_under(&base, &[argv("gamescope --prefer-output *,eDP-1")], None);
+        let heads = heads_under(&base, &[argv("gamescope --prefer-output *,eDP-1")]);
         assert_eq!(heads.len(), 1);
         assert_eq!(heads[0].connector, "eDP-1");
         std::fs::remove_dir_all(&base).unwrap();
@@ -421,7 +427,7 @@ mod tests {
                 ("card1-HDMI-A-1", "connected\n", "enabled\n"),
             ],
         );
-        let heads = heads_under(&base, &[argv("gamescope --steam")], None);
+        let heads = heads_under(&base, &[argv("gamescope --steam")]);
         assert_eq!(
             heads
                 .iter()
@@ -440,7 +446,7 @@ mod tests {
             "unplugged",
             &[("card1-HDMI-A-1", "disconnected\n", "disabled\n")],
         );
-        assert!(heads_under(&base, &[argv("gamescope --steam")], None).is_empty());
+        assert!(heads_under(&base, &[argv("gamescope --steam")]).is_empty());
         std::fs::remove_dir_all(&base).unwrap();
     }
 
@@ -452,7 +458,6 @@ mod tests {
         let heads = heads_under(
             &base,
             &[argv("gamescope -W 2560 -H 1440 --prefer-output HDMI-A-1")],
-            Some((2560, 1440)),
         );
         assert_eq!((heads[0].width, heads[0].height), (2560, 1440));
         std::fs::remove_dir_all(&base).unwrap();
@@ -511,7 +516,6 @@ mod tests {
             &[argv(
                 "gamescope --nested-refresh 30 --prefer-output HDMI-A-1",
             )],
-            None,
         );
         assert_eq!(heads[0].refresh_mhz, 60_000);
         assert_eq!(heads[0].mode_label(), "1920x1080@60");
@@ -539,7 +543,7 @@ mod tests {
             "3840x2160\n1920x1080\n",
         )
         .unwrap();
-        let heads = heads_under(&base, &[argv("gamescope --steam")], None);
+        let heads = heads_under(&base, &[argv("gamescope --steam")]);
         assert_eq!((heads[0].width, heads[0].height), (3840, 2160));
         std::fs::remove_dir_all(&base).unwrap();
     }

crates/pf-vdisplay/src/vdisplay/linux/gamescope/splash.rs

@@ -143,17 +143,57 @@ pub(crate) fn run() -> Result<()> {
     }
 }
 
+/// How long the splash waits for the session's X server before giving up.
+const CONNECT_BUDGET: Duration = Duration::from_secs(10);
+
 /// Connect to the session's `DISPLAY`, retrying briefly — gamescope sets the variable before
 /// exec'ing the nested command, but a slow Xwayland under cold driver init gets a grace window.
+///
+/// The retry runs on a worker thread and the budget is enforced by `recv_timeout` rather than by
+/// re-checking a deadline between attempts. The difference is the whole point: `x11rb::connect`
+/// has no timeout of its own, so against an Xwayland that ACCEPTED the socket and then never
+/// answered the setup handshake it blocks indefinitely — and a deadline consulted only in the
+/// `Err` arm is never reached at all. That is the failure this module exists to prevent, from the
+/// inside: no painting client, no composite, no PipeWire buffers, and the capture dies on its 10 s
+/// first-frame timeout having never logged "gamescope splash: mapped", so the diagnosis points
+/// anywhere but here.
+///
+/// A worker still stuck in `connect` is abandoned rather than joined; it is one thread in a
+/// process whose whole job is this window, and the alternative is the hang.
 fn connect_with_retry() -> Result<(RustConnection, usize)> {
-    let deadline = std::time::Instant::now() + Duration::from_secs(10);
-    loop {
-        match x11rb::connect(None) {
-            Ok(ok) => return Ok(ok),
-            Err(e) if std::time::Instant::now() >= deadline => {
-                return Err(e).context("gamescope splash: could not connect to the session DISPLAY")
+    let (tx, rx) = std::sync::mpsc::channel();
+    std::thread::Builder::new()
+        .name("pf-splash-x11-connect".into())
+        .spawn(move || {
+            let deadline = std::time::Instant::now() + CONNECT_BUDGET;
+            loop {
+                match x11rb::connect(None) {
+                    Ok(ok) => {
+                        let _ = tx.send(Ok(ok));
+                        return;
+                    }
+                    Err(e) if std::time::Instant::now() >= deadline => {
+                        let _ = tx.send(Err(e));
+                        return;
+                    }
+                    Err(_) => std::thread::sleep(Duration::from_millis(200)),
+                }
             }
-            Err(_) => std::thread::sleep(Duration::from_millis(200)),
+        })
+        .context("gamescope splash: could not start the X connect thread")?;
+    // A little past the worker's own deadline, so a connect that merely finished slowly still wins
+    // and only a genuinely blocked one trips this.
+    match rx.recv_timeout(CONNECT_BUDGET + Duration::from_secs(1)) {
+        Ok(Ok(conn)) => Ok(conn),
+        Ok(Err(e)) => Err(e).context("gamescope splash: could not connect to the session DISPLAY"),
+        Err(_) => {
+            tracing::warn!(
+                secs = CONNECT_BUDGET.as_secs(),
+                "gamescope splash: the session's X server accepted no connection and never \
+                 answered — giving up. Nothing will paint in this gamescope, so it will composite \
+                 nothing and the capture will starve; the gamescope log is where the reason is."
+            );
+            anyhow::bail!("gamescope splash: connecting to the session DISPLAY did not return")
         }
     }
 }

crates/pf-vdisplay/src/vdisplay/linux/hyprland.rs

@@ -5,9 +5,10 @@
 //! protocols, so it shares the wlr virtual-input path with sway — but it needs its own IPC and
 //! portal, so it is a **distinct backend** from [`super::wlroots`], not a branch inside it (D1):
 //!
-//! 1. `hyprctl output create headless PF-<n>` adds a named headless output — Hyprland supports
+//! 1. `hyprctl output create headless PF-<pid>-<n>` adds a named headless output — Hyprland supports
 //!    **explicit names**, so no before/after diffing like sway's `HEADLESS-N` (D6). We poll
-//!    `hyprctl -j monitors` until the name shows up.
+//!    `hyprctl -j monitors` until the name shows up. The creator's pid rides in the name so a
+//!    crashed host's leftovers are attributable, and only those (see [`reclaim_leftovers_once`]).
 //! 2. A monitor rule sets the client's exact mode. [`set_monitor_rule`] uses `hyprctl keyword
 //!    monitor NAME,WxH@Hz,auto,1` (the hyprlang path — the default config manager on every current
 //!    release, ≥0.55 included) and falls back to the Lua `hyprctl eval 'hl.monitor{…}'` only for a
@@ -69,12 +70,46 @@ fn picker_selection_line(name: &str) -> String {
     format!("[SELECTION]screen:{name}\n")
 }
 
-/// Monotonic per-process counter for headless output names (`PF-1`, `PF-2`, …). Named outputs kill
-/// the before/after diff race sway needs (D6).
+/// Monotonic per-process counter for headless output names (`PF-<pid>-1`, `PF-<pid>-2`, …). Named
+/// outputs kill the before/after diff race sway needs (D6).
 static OUTPUT_SEQ: AtomicU32 = AtomicU32::new(0);
 
+/// The name for our next headless output: `PF-<pid>-<n>`.
+///
+/// The pid is not decoration. `OutputGuard::drop` is the only thing that removes an output, so a
+/// host that was SIGKILLed leaves its outputs in the compositor — and a bare `PF-<n>` counter starts
+/// again at `PF-1` in the next process, colliding with the corpses it just inherited. Stamping the
+/// creator's pid into the name makes a leftover both recognisable and *attributable*, which is what
+/// lets [`reclaim_leftovers_once`] remove only the ones whose owner is gone.
 fn next_output_name() -> String {
-    format!("PF-{}", OUTPUT_SEQ.fetch_add(1, Ordering::Relaxed) + 1)
+    format!(
+        "PF-{}-{}",
+        std::process::id(),
+        OUTPUT_SEQ.fetch_add(1, Ordering::Relaxed) + 1
+    )
+}
+
+/// Is `name` an output some punktfunk host created (`PF-<pid>-<n>`, or a legacy `PF-<n>`)? Pure —
+/// this is what [`list_monitors`] reports as `managed`, so a user's own monitor called `PF-office`
+/// must not qualify.
+fn is_managed_output(name: &str) -> bool {
+    let Some(rest) = name.strip_prefix("PF-") else {
+        return false;
+    };
+    !rest.is_empty()
+        && rest
+            .split('-')
+            .all(|part| !part.is_empty() && part.bytes().all(|b| b.is_ascii_digit()))
+}
+
+/// The pid of the host that created `name`, for `PF-<pid>-<n>` only. `None` for anything else —
+/// including a legacy `PF-<n>` from a host older than this naming scheme, which carries no owner and
+/// therefore may not be reclaimed on a guess.
+fn output_owner_pid(name: &str) -> Option<u32> {
+    let rest = name.strip_prefix("PF-")?;
+    let (pid, seq) = rest.split_once('-')?;
+    seq.parse::<u32>().ok()?;
+    pid.parse::<u32>().ok()
 }
 
 /// The Hyprland virtual-display driver. Stateless — each [`create`](VirtualDisplay::create) adds one
@@ -100,11 +135,24 @@ impl HyprlandDisplay {
 /// under `$XDG_RUNTIME_DIR/hypr/*/.socket.sock` (so the systemd `--user` host works without env
 /// import, unlike sway's `SWAYSOCK`; the signature is then exported by `apply_session_env`). Cheap,
 /// side-effect-free — safe on the enumeration path.
+///
+/// Both env reads take [`crate::with_env_lock`] — in ONE scope, so the pair is sampled from a single
+/// consistent view. This runs on a management worker (`/host/compositors` → [`crate::available`])
+/// concurrently with another connect's `apply_session_env`, which `set_var`s the signature for a
+/// live Hyprland session and `remove_var`s it for anything else; a glibc `getenv` racing that
+/// `setenv`/`unsetenv` is the `environ` realloc data race ENV_LOCK exists for. No caller holds the
+/// lock (it is not reentrant), and the `read_dir` below deliberately runs outside it.
 pub fn is_available() -> bool {
-    if std::env::var_os("HYPRLAND_INSTANCE_SIGNATURE").is_some() {
+    let (sig, runtime) = crate::with_env_lock(|| {
+        (
+            std::env::var_os("HYPRLAND_INSTANCE_SIGNATURE"),
+            std::env::var_os("XDG_RUNTIME_DIR"),
+        )
+    });
+    if sig.is_some() {
         return true;
     }
-    let dir = match std::env::var_os("XDG_RUNTIME_DIR") {
+    let dir = match runtime {
         Some(d) => std::path::PathBuf::from(d).join("hypr"),
         None => return false,
     };
@@ -147,6 +195,9 @@ impl VirtualDisplay for HyprlandDisplay {
     fn create(&mut self, mode: Mode) -> Result<VirtualOutput> {
         // Log the permission-system caveat once per process (silent black frames otherwise).
         preflight_once();
+        // Remove any output a PREVIOUS host left in this compositor, before we mint our first.
+        reclaim_leftovers_once();
+        warn_topology_is_extend_only();
 
         let name = next_output_name();
         hyprctl_dispatch(&["output", "create", "headless", &name]).with_context(|| {
@@ -181,7 +232,7 @@ impl VirtualDisplay for HyprlandDisplay {
             remote_fd: Some(fd),
             preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
             keepalive: Box::new(Keepalive {
-                _stop: StopGuard(stop),
+                _stop: stop,
                 _output: output,
             }),
             // Owned (the compositor output is ours to tear down), but not registry-poolable: the
@@ -212,6 +263,62 @@ impl Drop for StopGuard {
     }
 }
 
+/// Remove the `PF-<pid>-<n>` outputs left behind by host processes that are **gone**, once per
+/// process before we create our first.
+///
+/// [`OutputGuard::drop`] is the only unplug path there is, so a host that was SIGKILLed, OOM-killed
+/// or crashed leaves its headless outputs in the compositor for as long as the Hyprland session
+/// lives — a dead `PF-…` head in the operator's layout, forever, with the next host start happily
+/// adding more beside it. Reclaim is keyed on the OWNER pid in the name and only removes an output
+/// whose creator no longer exists, so a second live host on the same session (or this very process)
+/// can never have its output pulled out from under it. `Once` puts the sweep strictly before this
+/// process owns anything, and blocks a concurrent first `create` until it is done.
+fn reclaim_leftovers_once() {
+    static RECLAIMED: Once = Once::new();
+    RECLAIMED.call_once(|| {
+        let Ok(names) = monitor_names() else { return };
+        for name in names {
+            let Some(pid) = output_owner_pid(&name) else {
+                // Either not ours, or a legacy `PF-<n>` with no owner recorded — which we must not
+                // remove on a guess, because a still-running older host may be streaming it.
+                if is_managed_output(&name) {
+                    tracing::debug!(output = %name, "a managed headless output with no owner pid in \
+                         its name (an older host build) — left alone");
+                }
+                continue;
+            };
+            if pid == std::process::id() || std::path::Path::new(&format!("/proc/{pid}")).exists() {
+                continue;
+            }
+            match hyprctl_dispatch(&["output", "remove", &name]) {
+                Ok(()) => tracing::info!(output = %name, owner_pid = pid, "removed a headless \
+                     output left behind by a host that is no longer running"),
+                Err(e) => tracing::warn!(output = %name, owner_pid = pid, error = %format!("{e:#}"),
+                    "could not remove a leftover headless output"),
+            }
+        }
+    });
+}
+
+/// The configured [`crate::policy::Topology`] is not implemented on this backend — say so once per
+/// create instead of leaving the management API's echo as the only signal that the pin was dropped
+/// (sweep 13.18). The Hyprland headless output is always an EXTENSION: nothing here promotes it to
+/// primary or disables the operator's heads.
+fn warn_topology_is_extend_only() {
+    let topology = crate::effective_topology();
+    if !matches!(
+        topology,
+        crate::policy::Topology::Extend | crate::policy::Topology::Auto
+    ) {
+        tracing::warn!(
+            ?topology,
+            "hyprland: this backend implements EXTEND only — the headless output is added beside \
+             the operator's heads and nothing is promoted or disabled. Configure `topology: extend` \
+             to stop the console promising otherwise."
+        );
+    }
+}
+
 /// Owns the created headless output; dropping it removes it from Hyprland.
 struct OutputGuard(String);
 
@@ -226,14 +333,25 @@ impl Drop for OutputGuard {
     }
 }
 
+/// Budget for one `hyprctl` call ([`crate::proc`]).
+///
+/// `hyprctl` is a client of the compositor it drives — it connects to the instance socket and waits
+/// for a reply, so against a wedged Hyprland it never returns. These calls run on the session's
+/// stream thread, whose only way to end a session is to return, so one hung query used to wedge the
+/// session for good. Generous next to a healthy call (single-digit milliseconds), and every call
+/// site already has a failed-query path.
+const HYPRCTL_BUDGET: Duration = Duration::from_secs(5);
+
+/// Budget for the one-shot xdph restart. `systemctl --user try-restart` waits for the user manager's
+/// job to settle, so it is the slowest helper on this path — and its result is already ignored.
+const PORTAL_RESTART_BUDGET: Duration = Duration::from_secs(10);
+
 /// Run `hyprctl <args>`, returning stdout. `hyprctl` reads `HYPRLAND_INSTANCE_SIGNATURE` from the
 /// env (exported by `apply_session_env`) to reach the right instance socket. It exits non-zero on a
 /// hard failure, but for dispatch commands it can print an error with status 0 — see
 /// [`hyprctl_dispatch`].
 fn hyprctl(args: &[&str]) -> Result<String> {
-    let out = Command::new("hyprctl")
-        .args(args)
-        .output()
+    let out = crate::proc::output_within(Command::new("hyprctl").args(args), HYPRCTL_BUDGET)
         .context("run hyprctl (is Hyprland installed?)")?;
     if !out.status.success() {
         bail!(
@@ -251,12 +369,36 @@ fn hyprctl(args: &[&str]) -> Result<String> {
 /// write between ours and xdph's read would silently steer capture at the other session's output.
 static SELECTION_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
 
+/// The per-session selection file, removed when the handshake it steers is over.
+///
+/// Its lifetime is the HANDSHAKE, not the session: the shim cats it once, inside
+/// [`select_and_cast`]'s critical section, and everything after that is the cast's own business.
+/// Left behind (as it was) the stale `[SELECTION]screen:PF-…` outlives the output `Drop` has since
+/// removed, and it permanently shadows xdph's documented empty-read fallback — every later capture
+/// that reaches the picker without a session of ours is steered at an output that is gone. Tying
+/// removal to the CAST instead would be worse: the file is one per user, so a session ending hours
+/// later would delete a *sibling's* selection out from under its picker.
+struct SelectionFile(String);
+
+impl Drop for SelectionFile {
+    fn drop(&mut self) {
+        if let Err(e) = std::fs::remove_file(&self.0) {
+            if e.kind() != std::io::ErrorKind::NotFound {
+                tracing::debug!(path = %self.0, error = %e, "could not remove the xdph selection file");
+            }
+        }
+    }
+}
+
 /// Point xdph's custom picker at `output` and run the ScreenCast handshake, returning the portal fd
 /// + node id and the guard that stops the cast. The caller must hold [`SELECTION_LOCK`].
-fn select_and_cast(output: &str, hw_cursor: bool) -> Result<(OwnedFd, u32, Arc<AtomicBool>)> {
+fn select_and_cast(output: &str, hw_cursor: bool) -> Result<(OwnedFd, u32, StopGuard)> {
     ensure_xdph_config()?;
     let sel = selection_file();
     std::fs::write(&sel, picker_selection_line(output)).with_context(|| format!("write {sel}"))?;
+    // Owned from the write on: every arm below (and every `?`) leaves the handshake, which is the
+    // only thing that reads it.
+    let _sel_file = SelectionFile(sel);
     let (setup_tx, setup_rx) = std::sync::mpsc::channel::<Result<(OwnedFd, u32), String>>();
     let stop = Arc::new(AtomicBool::new(false));
     let stop_thread = stop.clone();
@@ -264,8 +406,16 @@ fn select_and_cast(output: &str, hw_cursor: bool) -> Result<(OwnedFd, u32, Arc<A
         .name("punktfunk-hypr-cast".into())
         .spawn(move || portal_thread(setup_tx, stop_thread, hw_cursor))
         .context("spawn hyprland portal thread")?;
+    // Built BEFORE the wait so EVERY error arm below sets the flag on its way out — as Mutter's
+    // `create` does. Returning the bare `Arc` and letting the CALLER wrap it left the two failure
+    // arms dropping an un-set flag: the thread's `send` can still LAND in the queue in the window
+    // between `recv_timeout` giving up and `setup_rx` being dropped, so it reports success and then
+    // parks forever on `while !stop`, holding a live ScreenCast session, its zbus connection, an
+    // `OwnedFd` and a 2-worker tokio runtime — one more set per slow-portal connect, for the host's
+    // lifetime, against an output that no longer exists.
+    let guard = StopGuard(stop);
     match setup_rx.recv_timeout(Duration::from_secs(20)) {
-        Ok(Ok((fd, node_id))) => Ok((fd, node_id, stop)),
+        Ok(Ok((fd, node_id))) => Ok((fd, node_id, guard)),
         Ok(Err(e)) => bail!("ScreenCast portal on {output} failed: {e}"),
         Err(_) => bail!("timed out waiting for the ScreenCast portal on {output}"),
     }
@@ -285,7 +435,7 @@ pub(crate) fn stream_existing_output(
     Ok(crate::mirror::MirrorStream {
         node_id,
         remote_fd: Some(fd),
-        keepalive: Box::new(StopGuard(stop)),
+        keepalive: Box::new(stop),
     })
 }
 
@@ -330,11 +480,12 @@ pub(crate) fn list_monitors() -> Result<Vec<crate::monitors::PhysicalMonitor>> {
                     .unwrap_or(1.0),
                 primary: m.get("focused").and_then(|v| v.as_bool()).unwrap_or(false),
                 enabled: !m.get("disabled").and_then(|v| v.as_bool()).unwrap_or(false),
-                // Our headless outputs are named `PF-<n>` (see `next_output_name`).
+                // Our headless outputs are named `PF-<pid>-<n>` (see `next_output_name`); the shape
+                // is checked, not just the prefix, so a user's own `PF-office` stays theirs.
                 managed: m
                     .get("name")
                     .and_then(|v| v.as_str())
-                    .is_some_and(|n| n.starts_with("PF-")),
+                    .is_some_and(is_managed_output),
             })
         })
         .collect();
@@ -382,6 +533,23 @@ fn wait_monitor_ready(name: &str, timeout: Duration) -> Result<()> {
     }
 }
 
+/// Every monitor name Hyprland reports, **disabled ones included** (`-j monitors all`) — a leftover
+/// output from a dead host may well have ended up disabled, and [`reclaim_leftovers_once`] must see
+/// it anyway.
+fn monitor_names() -> Result<Vec<String>> {
+    let out = hyprctl(&["-j", "monitors", "all"])?;
+    let monitors: serde_json::Value =
+        serde_json::from_str(&out).context("parse hyprctl -j monitors all")?;
+    Ok(monitors
+        .as_array()
+        .map(|a| {
+            a.iter()
+                .filter_map(|m| m.get("name").and_then(|n| n.as_str()).map(str::to_owned))
+                .collect()
+        })
+        .unwrap_or_default())
+}
+
 /// Is a monitor named `name` present in `hyprctl -j monitors` (JSON)?
 fn monitor_exists(name: &str) -> Result<bool> {
     let out = hyprctl(&["-j", "monitors"])?;
@@ -417,17 +585,33 @@ fn set_monitor_rule(name: &str, mode: Mode) -> Result<()> {
     );
     let keyword: Vec<&str> = vec!["keyword", "monitor", &spec];
     let eval: Vec<&str> = vec!["eval", &lua];
+    // What each form actually said. hyprctl reports a rejection in its OUTPUT TEXT ("eval is only
+    // supported with the lua config manager", "invalid monitor rule", a permission denial), and
+    // dropping it on the floor with `.is_err()` is what left the failure below guessing at GBM when
+    // the compositor had already named the real cause.
+    let mut attempts: Vec<String> = Vec::new();
     for a in [&keyword, &eval] {
         // A wrong-era command errors (`keyword` gone under Lua, or `eval` under hyprlang) — skip to
         // the other form. A command that's accepted then has up to the timeout to take effect.
-        if hyprctl_dispatch(a).is_err() {
+        if let Err(e) = hyprctl_dispatch(a) {
+            let said = format!("{e:#}");
+            tracing::debug!(output = %name, cmd = ?a, error = %said, "hyprctl rejected this monitor-rule form — trying the other config era");
+            attempts.push(said);
             continue;
         }
         if wait_exact_mode(name, mode, Duration::from_millis(1500)) {
             tracing::debug!(output = %name, cmd = ?a, w = mode.width, h = mode.height, "monitor adopted the requested mode");
             return Ok(());
         }
+        attempts.push(format!(
+            "hyprctl {a:?} was accepted but the mode never took effect"
+        ));
     }
+    let said = if attempts.is_empty() {
+        "nothing (no form was attempted)".to_string()
+    } else {
+        attempts.join("; ")
+    };
     // Neither form produced the exact mode. Distinguish "usable but different size" (proceed with a
     // warning — a working stream beats none) from "0×0 / gone" (the output has no framebuffer at all).
     match monitor_size(name)? {
@@ -436,14 +620,20 @@ fn set_monitor_rule(name: &str, mode: Mode) -> Result<()> {
                 output = %name,
                 requested = %format!("{}x{}", mode.width, mode.height),
                 got = %format!("{w}x{h}"),
+                hyprctl = %said,
                 "Hyprland did not adopt the exact requested mode — streaming at the output's current size"
             );
             Ok(())
         }
+        // The output has no framebuffer at all. Lead with what hyprctl SAID: if every form was
+        // rejected the cause is named right there (wrong config era, a permission denial, a bad
+        // rule) and no allocation was ever attempted; only a form that was accepted and still left
+        // the output at 0×0 points at the compositor failing to back the mode.
         _ => bail!(
             "headless output {name} never got a framebuffer (stayed 0x0) after the monitor rule for \
-             {}x{}@{hz} — the compositor could not back the mode, likely a headless GBM/dmabuf \
-             allocation failure (GPU driver; cf. Sunshine#4197). Check the Hyprland log.",
+             {}x{}@{hz}. hyprctl said: {said}. If a form was accepted, the compositor could not back \
+             the mode — likely a headless GBM/dmabuf allocation failure (GPU driver; cf. \
+             Sunshine#4197). Check the Hyprland log.",
             mode.width,
             mode.height
         ),
@@ -574,13 +764,17 @@ fn ensure_xdph_config() -> Result<()> {
         return Ok(());
     }
     tracing::info!(path = %path.display(), "pointed xdg-desktop-portal-hyprland at the managed picker shim");
-    let _ = Command::new("systemctl")
-        .args([
+    // Bounded: `systemctl --user` blocks on the user manager's job queue, and this runs on the
+    // session's stream thread. Its result was already ignored — a timeout just means xdph picks the
+    // new config up whenever it next starts.
+    let _ = crate::proc::status_within(
+        Command::new("systemctl").args([
             "--user",
             "try-restart",
             "xdg-desktop-portal-hyprland.service",
-        ])
-        .status();
+        ]),
+        PORTAL_RESTART_BUDGET,
+    );
     Ok(())
 }
 
@@ -702,6 +896,28 @@ mod tests {
         assert_ne!(a, b);
     }
 
+    /// The name carries the creating host's pid, which is what makes a leftover attributable — a
+    /// reclaim that could not tell whose output it was would have to remove a LIVE sibling's or
+    /// nothing at all.
+    #[test]
+    fn a_name_carries_its_owner_pid_and_only_ours_does() {
+        let mine = next_output_name();
+        assert_eq!(output_owner_pid(&mine), Some(std::process::id()));
+        assert!(is_managed_output(&mine));
+
+        // A legacy `PF-<n>` from an older host: recognisably managed, but with no owner recorded —
+        // so it may be reported, never reclaimed on a guess.
+        assert!(is_managed_output("PF-1"));
+        assert_eq!(output_owner_pid("PF-1"), None);
+
+        // Not ours: a user's own monitor name that happens to start with the prefix, and the
+        // connectors every wlr-family compositor mints.
+        for theirs in ["PF-office", "PF-", "PF-12-abc", "HEADLESS-1", "DP-1", ""] {
+            assert!(!is_managed_output(theirs), "{theirs:?} is not ours");
+            assert_eq!(output_owner_pid(theirs), None, "{theirs:?} has no owner");
+        }
+    }
+
     #[test]
     fn picker_line_carries_the_selection_marker() {
         // xdph requires the `[SELECTION]` prefix; a bare `screen:NAME` is rejected as strange output.