fix(ci): an unset HOST_CER_PATH is $null, and a null hash key is fatal — not an empty key

Azure signing produces no .cer, so HOST_CER_PATH is deliberately unset. The publish step then built
its alias map as a single hash literal containing $env:HOST_CER_PATH as a KEY, and an unset $env:
var is $null — "A null key is not allowed in a hash literal", which failed the whole step. Canary
run 18256: the installer signed fine and published to its versioned path, then this line killed the
alias refresh, so `canary/punktfunk-host-setup.exe` went stale.

I reasoned about this line while making the .cer optional and concluded an unset variable would give
an empty-string key, which is legal. It does not — that only happens through string interpolation.
The $files guard just above filters the missing .cer correctly; the hash literal ran before anything
could use it.

Build the map incrementally instead, adding the .cer entry only when there is one, so the legacy
.pfx modes still alias it.

windows-client.yml survived the same change only by accident: it writes "$($env:MSIX_CER_PATH)",
and interpolating $null yields an empty string, which IS a legal key. Made that explicit too rather
than leaving correctness resting on quotes someone could reasonably tidy away.

Verified under pwsh 7: the old literal reproduces the exact CI message with the var unset; the new
form yields one entry unset and two entries set, with the .cer alias intact.

.cargo/audit.toml

@@ -4,12 +4,21 @@
 # or an accepted, documented risk. Keep this list TIGHT and justify every entry — an ignore here
 # means the audit job stops flagging it, so the reasoning must hold up.
 #
-# NOTE: `cargo audit` (no `--deny warnings`) fails only on *vulnerabilities*, not on the
-# `unmaintained` warnings (audiopus_sys via opus, paste via utoipa-axum). Both are transitive, at
-# their latest published version with no successor, so there's nothing to bump — left visible on
-# purpose so we keep getting the maintenance signal; they do not fail CI. (rustls-pemfile was dropped
-# 2026-06-29 by removing axum-server's unused tls-rustls feature + moving our own PEM parsing to
-# rustls-pki-types; memmap2's unsoundness was fixed by the 0.9.11 bump.)
+# ⚠ NOTE: `cargo audit` (no `--deny warnings`) fails only on *vulnerabilities* — `unmaintained` AND
+# `unsound` advisories are warnings that do NOT fail CI. That is deliberate for the two unmaintained
+# crates below, but it does mean an unsoundness can sit here unnoticed: RUSTSEC-2026-0221
+# (event-listener) did exactly that until the 2026-08-13 sweep. Read the job's warnings, not just
+# its exit code.
+#
+# The two unmaintained ones, both transitive with no successor to bump to, left visible on purpose
+# so we keep getting the maintenance signal:
+#   * audiopus_sys via opus (opus itself IS maintained; only its -sys layer is stuck).
+#   * paste via BOTH utoipa-axum (host) and rav1d (client decode path) — an earlier version of this
+#     note named only utoipa-axum, which would have made dropping utoipa-axum look like it cleared
+#     paste. It would not: every client pulls it through rav1d.
+# (rustls-pemfile was dropped 2026-06-29 by removing axum-server's unused tls-rustls feature +
+# moving our own PEM parsing to rustls-pki-types; memmap2's unsoundness was fixed by the 0.9.11
+# bump.)
 
 [advisories]
 ignore = [
@@ -34,17 +43,8 @@ ignore = [
     # a constant-time rsa ships (then drop this), the host ever signs an attacker-chosen message with
     # this key, or any RSA decryption / key-transport using the private key is added.
     "RUSTSEC-2023-0071",
-
-    # quick-xml DoS advisories (RUSTSEC-2026-0194 quadratic-time duplicate-attribute check;
-    # RUSTSEC-2026-0195 unbounded namespace-declaration allocation in NsReader). Both are
-    # exploited by feeding attacker-controlled XML to a running parser. In this tree quick-xml is
-    # a BUILD-TIME-ONLY, transitive dependency of `wayland-scanner` (a proc-macro that parses the
-    # TRUSTED wayland protocol XML files shipped with the wayland-rs crates at compile time). It is
-    # never linked into any shipped binary and never parses runtime/attacker-controlled input, so
-    # neither DoS is reachable. There is no fix to bump to: wayland-scanner 0.31.10 (latest) pins
-    # `quick-xml ^0.39`, and the fixes only exist in quick-xml >=0.41. Revisit (drop these) when
-    # wayland-scanner releases against quick-xml >=0.41, or if quick-xml is ever pulled onto a
-    # runtime path that parses untrusted XML.
-    "RUSTSEC-2026-0194",
-    "RUSTSEC-2026-0195",
+    # The quick-xml DoS pair (RUSTSEC-2026-0194/0195) used to be ignored here, with the note
+    # "revisit when wayland-scanner releases against quick-xml >=0.41". It has: wayland-scanner
+    # 0.31.11 moved to `quick-xml ^0.41` and the lock is on 0.41.0 as of 2026-08-13, so both
+    # entries were dropped rather than left as permanent exceptions.
 ]

.cargo/config.toml

@@ -1,18 +1,39 @@
 # Workspace-wide build flags.
 #
-# aes_armv8: RustCrypto's `aes` 0.8.x enables ARMv8-Crypto hardware AES on aarch64 only behind
-# this cfg (x86_64 AES-NI is runtime-detected with no flag; the 0.9 line will make aarch64
-# automatic too). Without it every aarch64 client (all Apple + virtually all Android) ran
-# SOFTWARE AES on the per-packet decrypt path — measured 2026-07-14 on an M3 Ultra at
-# ~240 MiB/s/core (~7 µs per 1.4 KB datagram), which single-handedly capped receive throughput
-# at ~1.57 Gbps wire. The cfg still runtime-detects via `cpufeatures`, so a chip without the
-# extensions falls back safely.
+# THERE ARE DELIBERATELY NONE. This file is kept as a tombstone so the aarch64 AES cfgs are not
+# reintroduced — read this before adding rustflags here.
 #
-# NOTE: a RUSTFLAGS environment variable OVERRIDES config rustflags entirely — build scripts /
-# CI lanes that set RUSTFLAGS for aarch64 targets (cargo-ndk, xcframework) must carry
-# `--cfg aes_armv8` themselves.
-# polyval_armv8: same story for GCM's other half — `polyval` 0.6.x gates its PMULL (carry-less
-# multiply) GHASH path behind this cfg on aarch64. AES alone took open_in_place from 240 to
-# ~790 MiB/s on the M3 Ultra; software GHASH still dominated until this flag joined it.
-[target.'cfg(target_arch = "aarch64")']
-rustflags = ["--cfg", "aes_armv8", "--cfg", "polyval_armv8"]
+# Until 2026-08-13 this file carried:
+#
+#     [target.'cfg(target_arch = "aarch64")']
+#     rustflags = ["--cfg", "aes_armv8", "--cfg", "polyval_armv8"]
+#
+# because RustCrypto's `aes` 0.8.x enabled the ARMv8-Crypto hardware AES backend on aarch64 ONLY
+# behind `--cfg aes_armv8`, and `polyval` 0.6.x gated its PMULL (carry-less multiply) GHASH path
+# behind `--cfg polyval_armv8`. That was a live footgun, not just boilerplate: a RUSTFLAGS
+# ENVIRONMENT VARIABLE OVERRIDES CONFIG RUSTFLAGS ENTIRELY — it does not merge and does not
+# append — so every aarch64 lane that set its own RUSTFLAGS silently dropped both and fell back to
+# SOFTWARE AES on the per-packet decrypt path. cargo-ndk sets RUSTFLAGS internally for its linker
+# configuration, which means every Android arm64-v8a build was hitting exactly that.
+#
+# `aes` 0.9 removed the cfg: on aarch64 it runtime-detects with `cpufeatures::new!(features_aes,
+# "aes")` (lib.rs), the same way x86_64 AES-NI always did. `polyval` 0.7 likewise selects
+# `backend/intrinsics/armv8.rs` by `target_arch` alone. Neither cfg exists any more — passing them
+# is inert.
+#
+# Measured here before deleting them, `crypto/open_in_place` from benches/pipeline.rs (one 1408-byte
+# MTU shard, AES-128-GCM, single core, Mac15,14 M3 Ultra, all four runs back to back under the same
+# background load):
+#
+#     aes 0.8 + both cfgs      2.19 GiB/s      <- what the cfgs bought
+#     aes 0.8, cfgs stripped     225 MiB/s     <- the footgun: ~10x slower, software AES
+#     aes 0.9 + both cfgs      5.28 GiB/s
+#     aes 0.9, cfgs stripped   5.28 GiB/s      <- identical to 4 s.f.; the cfgs do nothing
+#
+# The ChaCha20-Poly1305 series of the same bench was the control: it moved 0.07% across the cfg
+# toggle at both versions, confirming the toggle reached only the AES path.
+#
+# So 0.9 without the cfgs is not merely as fast as 0.8 with them — it is ~2.4x faster, and ~24x
+# the software fallback. Do not re-add these flags; if a future aarch64 slowdown is suspected,
+# re-run `cargo bench -p punktfunk-core --bench pipeline -- in_place` and compare against the
+# table above rather than reaching for a cfg.

.gitea/workflows/android.yml

@@ -63,6 +63,15 @@ env:
   SCCACHE_REGION: home-central
   AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # The C/C++ half of the cache. The one that pays here is the CMake-built vendored libopus
+  # (audiopus_sys), which kit/build.gradle.kts drives through cargo-ndk once per ABI — three
+  # from-scratch libopus builds per run until now. The per-ABI compilers come from the NDK via
+  # cargo-ndk's own CC_<android-triple> vars, which this does not touch; CC_x86_64_unknown_linux_gnu
+  # covers only the HOST build scripts and proc macros.
+  CMAKE_C_COMPILER_LAUNCHER: sccache
+  CMAKE_CXX_COMPILER_LAUNCHER: sccache
+  CC_x86_64_unknown_linux_gnu: sccache cc
+  CXX_x86_64_unknown_linux_gnu: sccache c++
   # sccache and incremental compilation are mutually exclusive; CI wants the shared
   # cache, dev boxes keep incremental.
   CARGO_INCREMENTAL: "0"
@@ -265,7 +274,7 @@ jobs:
           retention-days: 30
 
       # Publish BEFORE the Play upload so artifacts land even while the Play step is still failing.
-      # Generic registry is public for reads — matches windows-msix.yml / deb.yml (REGISTRY_TOKEN, user enricobuehler).
+      # Generic registry is public for reads — matches windows-client.yml / deb.yml (REGISTRY_TOKEN, user enricobuehler).
       # main = canary store + `canary/` sideload alias; a `vX.Y.Z` tag = `latest/` alias + attached
       # to the unified Gitea Release.
       - name: Publish to generic registry + attach to Gitea release

.gitea/workflows/apple.yml

@@ -1,12 +1,86 @@
-# Apple client CI — runs on the self-hosted macOS runner (home-mac-mini-1, host mode;
-# see scripts/ci/setup-macos-runner.sh). Builds the Rust core into
-# PunktfunkCore.xcframework, then builds + tests the Swift package. Network-dependent
-# tests (RemoteFirstLightTests) self-skip without PUNKTFUNK_REMOTE_HOST.
+# Apple client CI **and** distribution — everything that runs on the self-hosted macOS runner
+# (home-mac-mini-1, host mode; see scripts/ci/setup-macos-runner.sh), in dependency order:
 #
-# A second job (`screenshots`) captures the App Store Connect screenshots of the REAL UI
-# (mac window + iOS/iPad/tvOS Simulators, see clients/apple/tools/screenshots.sh) and attaches
-# them to the run as a single zip artifact (`punktfunk-appstore-screenshots`). It is isolated
-# from the build/test job and best-effort, so a capture gap never reds the core signal.
+#   swift        — build the Rust core into PunktfunkCore.xcframework, then build + test the Swift
+#                  package. Network-dependent tests (RemoteFirstLightTests) self-skip without
+#                  PUNKTFUNK_REMOTE_HOST. Runs on pushes, tags AND pull requests.
+#   distribute   — needs: swift. The signed/notarized artifacts:
+#                    macOS (Developer ID) -> sandboxed, signed, notarized + stapled .dmg, attached
+#                              to the Gitea release on tag pushes
+#                    macOS (App Store)    -> archive + upload to TestFlight (App Store Connect)
+#                    iOS    -> archive + upload to TestFlight, plus an exported .ipa
+#                    tvOS   -> archive + upload to TestFlight (Rust core built from tier-3 targets,
+#                              nightly -Zbuild-std, in build-xcframework.sh)
+#   screenshots  — needs: swift. App Store Connect screenshots of the REAL UI, attached to the run
+#                  as a zip artifact. Best-effort, so a capture gap never reds the core signal.
+#
+# ⚠ WHY THIS FILE IS ONE FILE. `distribute` used to live in its own workflow called `release.yml` —
+# a name that described neither what it did (Apple only) nor how releases actually work here (every
+# platform's packaging workflow attaches to the same Gitea release on a v* tag, and announce.yml is
+# the manual "go"). The name was the smaller problem. The real one: Gitea has no cross-workflow
+# `needs`, so nothing sequenced it against apple.yml's tests — a canary main push uploaded iOS,
+# macOS and tvOS builds to TestFlight even when `swift test` had just failed on the same commit,
+# and the two files' `paths:` filters had already drifted apart, so it was possible for one to fire
+# without the other. Merging is what makes `needs: swift` expressible. Do not split them again.
+#
+# The trigger list is deliberately NARROW on crates/: everything here is built from
+# `crates/punktfunk-core` (via scripts/build-xcframework.sh) and nothing else in the workspace.
+# VERIFY THAT BEFORE WIDENING OR TRUSTING IT — punktfunk-core's only path dependency is its own
+# vendored fec-rs, under crates/punktfunk-core/vendor/:
+#     sed -n '/^\[dependencies\]/,/^\[/p' crates/punktfunk-core/Cargo.toml | grep path
+# If punktfunk-core ever gains a path dep on a sibling crate, add that crate here. Cargo.lock is a
+# partial safety net (it moves when the dep is ADDED) but not a complete one — later edits to that
+# crate would not fire this workflow. This is the same class of gap flatpak.yml documents.
+#
+# ── Signing / distribution notes (all of these belong to `distribute`) ────────────────────────────
+#
+# One App Store listing for all platforms (universal purchase): every target shares the
+# bundle ID io.unom.punktfunk.
+#
+# The macOS app is App-SANDBOXED for both channels (Config/Punktfunk-macOS.entitlements —
+# app-sandbox + network client/server + audio-input + bluetooth/usb device access; the
+# shared Config/Punktfunk.entitlements stays iOS/tvOS-only, where app-sandbox is invalid).
+# The Developer ID DMG is codesigned with the SAME macOS entitlements as the App Store build,
+# BUT it must ALSO embed a Developer ID provisioning profile: keychain-access-groups is a
+# MANAGED entitlement that AMFI only honors when an embedded profile authorizes it. A DMG
+# without one is SIGKILLed at spawn ("Launchd job spawn failed", POSIX errno 163) even though
+# it is validly signed AND notarized. ⌘R hides this (Xcode embeds a development profile); the
+# raw Developer ID codesign path does NOT, so ⌘R is NOT equivalent to the shipped DMG here.
+#
+# macOS App Store prerequisites (one-time, Apple portal — NOT done by this workflow; the
+# step is continue-on-error until they exist):
+#   * App Store Connect: add the macOS platform to the io.unom.punktfunk app record
+#     (universal purchase).
+#   * A "Punktfunk macOS App Store Distribution" provisioning profile installed on the
+#     runner (under ~/Library/Developer/Xcode/UserData/Provisioning Profiles/).
+#   * The "3rd Party Mac Developer Installer" (Mac Installer Distribution) certificate in
+#     the runner's login keychain, in addition to "Apple Distribution" — the App Store
+#     .pkg is installer-signed with it.
+#
+# macOS Developer ID (DMG) prerequisite (one-time, Apple portal — the DMG step embeds it):
+#   * A "Punktfunk macOS Developer ID" provisioning profile (Distribution -> Developer ID,
+#     App ID io.unom.punktfunk, with the Keychain Sharing capability) installed on the runner
+#     under ~/Library/Developer/Xcode/UserData/Provisioning Profiles/. It authorizes the
+#     managed keychain-access-groups entitlement; without it the DMG is SIGKILLed at launch
+#     (errno 163). If it is missing the DMG step warns and strips that entitlement (the app
+#     then uses ClientIdentityStore's legacy file-keychain fallback) so the build still ships
+#     a launchable app.
+#
+# Signing setup (NOT secret-based anymore): the runner is a LaunchAgent in the user's
+# logged-in Aqua session, so it uses the **login keychain** directly. Install the signing
+# identities there once via Xcode (Settings -> Accounts -> Manage Certificates): Developer
+# ID Application + Apple Distribution, with the WWDR intermediate present (so they show as
+# *valid*). xcodebuild/codesign then sign exactly like a local build — no throwaway keychain.
+# One-time, to avoid headless "codesign wants to use the key" prompts, grant codesign access:
+#   security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k <login-pw> \
+#     ~/Library/Keychains/login.keychain-db
+#
+# Secrets: only ASC_API_KEY_P8 / ASC_API_KEY_ID / ASC_API_ISSUER_ID (App Store Connect API
+# key — notarization, TestFlight upload, automatic-signing profile fetch).
+#
+# Needs a RELEASE Xcode on the runner (App Store rejects beta-SDK builds); the workflow
+# picks the first non-beta /Applications/Xcode*.app and only falls back to a beta with a
+# loud warning.
 name: apple
 # One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
 # it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
@@ -19,30 +93,39 @@ concurrency:
 
 on:
   push:
+    # Canary: a relevant main push builds + tests, then uploads the iOS + macOS + tvOS builds to
+    # TestFlight (Apple's own canary channel) — no notarized DMG (that's stable-only; see the
+    # per-step gates). Heavy on the shared mac-mini runner, hence the tight paths filter.
     branches: [main]
-    # Scope canary builds to what this artifact is built FROM — a docs-only or
-    # web-only push should not light up the whole fleet. Applies to branch pushes;
-    # tag runs are matched by `tags:` (proven by flatpak/windows-msix releases).
     paths:
-      - 'crates/**'
+      - 'crates/punktfunk-core/**'
       - 'clients/apple/**'
       - 'scripts/build-xcframework.sh'
+      - 'scripts/ci/**'
       - 'Cargo.toml'
       - 'Cargo.lock'
       - 'rust-toolchain.toml'
-      - 'scripts/ci/**'
       - '.gitea/workflows/apple.yml'
+    # Stable: a `vX.Y.Z` tag is THE release — notarized DMG attached to the unified Gitea Release
+    # + macOS/iOS/tvOS to TestFlight for manual promotion to the App Store. Tag runs are matched by
+    # `tags:` and are NOT subject to the paths filter above.
+    tags: ['v*']
   pull_request:
     paths:
-      - 'crates/**'
+      - 'crates/punktfunk-core/**'
       - 'clients/apple/**'
       - 'scripts/build-xcframework.sh'
+      - 'scripts/ci/**'
       - 'Cargo.toml'
       - 'Cargo.lock'
       - 'rust-toolchain.toml'
-      - 'scripts/ci/**'
       - '.gitea/workflows/apple.yml'
   workflow_dispatch:
+    inputs:
+      testflight:
+        description: "Upload the iOS/macOS/tvOS builds to TestFlight (true/false)"
+        required: false
+        default: "true"
 
 # Shared compile cache: sccache -> RustFS S3 (storage.unom.io — the mini resolves it via
 # the router, i.e. the hairpin path whose TLS always validated). Covers every cargo/rustc
@@ -61,11 +144,11 @@ env:
 
 jobs:
   # SECURITY: builds/tests PULL-REQUEST code on the host-mode, persistent `macos-arm64` runner shared
-  # with the release-signing job (release.yml, which loads the App Store Connect key). Untrusted PR
-  # code could persist on it or harvest signing material. Definitive fix is server-side: enable Gitea's
-  # "require approval for PRs from outside collaborators/forks", and/or isolate PR CI on ephemeral
-  # runners. The `if:` is a fail-open backstop — it skips fork PRs where Gitea reports the fork flag and
-  # still runs same-repo PRs (and where the flag is absent), so it never blocks internal PR CI.
+  # with the release-signing job below (which loads the App Store Connect key). Untrusted PR code could
+  # persist on it or harvest signing material. Definitive fix is server-side: enable Gitea's "require
+  # approval for PRs from outside collaborators/forks", and/or isolate PR CI on ephemeral runners. The
+  # `if:` is a fail-open backstop — it skips fork PRs where Gitea reports the fork flag and still runs
+  # same-repo PRs (and where the flag is absent), so it never blocks internal PR CI.
   swift:
     runs-on: macos-arm64
     if: >-
@@ -85,17 +168,10 @@ jobs:
           dirname "$RUSTUP" >> "$GITHUB_PATH"
           "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin
 
-      # Shared compile cache. ~/.local/bin is on the runner daemon's PATH; GITHUB_PATH is
-      # belt-and-braces. bsdtar (macOS) globs by default — no --wildcards.
+      # Shared compile cache. The script handles the macOS side (user-prefix install +
+      # GITHUB_PATH, bsdtar globbing) — see scripts/ci/ensure-sccache.sh.
       - name: sccache (self-healing install)
-        run: |
-          if ! command -v sccache >/dev/null; then
-            mkdir -p "$HOME/.local/bin"
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-aarch64-apple-darwin.tar.gz \
-              | tar -xz --strip-components=1 -C "$HOME/.local/bin" '*/sccache'
-          fi
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       # `punktfunk-core` now decodes Opus in-core for the Apple client (surround), pulling
       # `audiopus_sys`, which builds a vendored static libopus via CMake when pkg-config can't find a
@@ -127,24 +203,496 @@ jobs:
         working-directory: clients/apple
         run: swift test
 
+      - name: sccache stats (visibility only)
+        if: always()
+        run: sccache --show-stats
+
+  # ── Distribution ────────────────────────────────────────────────────────────────────────────────
+  # `needs: swift` is the entire reason this lives here rather than in its own file: it is what makes
+  # a failed `swift test` stop a TestFlight upload. Never demote it to a parallel job.
+  distribute:
+    needs: swift
+    # Pushes to main (canary), v* tags (stable) and manual dispatch — never pull requests.
+    if: gitea.event_name != 'pull_request'
+    runs-on: macos-arm64
+    timeout-minutes: 120
+    env:
+      TEAM_ID: F4H37KF6WC
+      PROJECT: clients/apple/Punktfunk.xcodeproj
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Select release Xcode
+        run: |
+          DEV_DIR=""
+          for app in /Applications/Xcode.app /Applications/Xcode_*.app /Applications/Xcode-*.app; do
+            case "$app" in *beta*|*Beta*) continue;; esac
+            [ -x "$app/Contents/Developer/usr/bin/xcodebuild" ] && DEV_DIR="$app/Contents/Developer" && break
+          done
+          if [ -z "$DEV_DIR" ]; then
+            for app in /Applications/Xcode*.app; do
+              [ -x "$app/Contents/Developer/usr/bin/xcodebuild" ] && DEV_DIR="$app/Contents/Developer" && break
+            done
+            echo "::warning::No release Xcode found — using $DEV_DIR. TestFlight/App Store REJECTS beta-SDK builds."
+          fi
+          [ -n "$DEV_DIR" ] || { echo "no usable Xcode found" >&2; exit 1; }
+          # Scoped to xcodebuild steps only (XCODE_DEV_DIR, not DEVELOPER_DIR): cargo must
+          # keep the system-default linker — a newer-than-OS Xcode's ld produces dylibs the
+          # running dyld rejects, killing proc-macro loads (see build-xcframework.sh).
+          echo "XCODE_DEV_DIR=$DEV_DIR" >> "$GITHUB_ENV"
+          DEVELOPER_DIR="$DEV_DIR" xcodebuild -version
+
+      - name: Version from tag
+        run: |
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE, PF_CHANNEL, PF_STABLE_TAG (single source of truth)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; V="${V%%-*}" ;;  # App Store marketing version is numeric X.Y.Z (drop -rc)
+            *)            V="$PF_BASE" ;;                             # canary marketing version = one minor ahead of the latest stable tag; the build number disambiguates
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          # GITHUB_RUN_NUMBER is REPO-WIDE in Gitea (not per-workflow as on GitHub): consecutive runs
+          # of different workflows get consecutive numbers. That is why folding the old release.yml
+          # into this file could not reset the build number and strand TestFlight, which rejects a
+          # non-increasing CFBundleVersion. It also means this climbs by ~8 per push rather than by 1
+          # — monotonic either way, which is all App Store Connect asks.
+          echo "BUILD_NUM=$GITHUB_RUN_NUMBER" >> "$GITHUB_ENV"
+          echo "version $V build $GITHUB_RUN_NUMBER (channel $PF_CHANNEL, latest stable ${PF_STABLE_TAG})"
+
+      - name: Rust toolchain (mac + iOS + tvOS slices)
+        run: |
+          RUSTUP="$(command -v rustup || echo "$HOME/.cargo/bin/rustup")"
+          dirname "$RUSTUP" >> "$GITHUB_PATH"
+          "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
+            aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
+          # tvOS targets are tier-3 (no prebuilt std) — build-xcframework.sh compiles them with
+          # nightly + -Zbuild-std, so ensure nightly + rust-src are present.
+          "$RUSTUP" toolchain install nightly --profile minimal
+          "$RUSTUP" component add rust-src --toolchain nightly
+
+      # The in-core Opus decode (surround) pulls audiopus_sys, which builds a vendored static libopus
+      # via CMake — keep the xcframework self-contained (no runtime libopus.dylib on end-user devices).
+      - name: CMake (for the vendored libopus audiopus_sys builds)
+        run: |
+          # Runner steps run with `bash --noprofile --norc`, so Homebrew's bin dir isn't on PATH —
+          # locate brew explicitly, install cmake if missing, and export its bin dir to GITHUB_PATH so
+          # the xcframework build step (audiopus_sys → vendored libopus) finds `cmake`.
+          for B in /opt/homebrew/bin/brew /usr/local/bin/brew; do [ -x "$B" ] && BREW="$B" && break; done
+          if [ -z "$BREW" ]; then echo "::error::Homebrew not found on the runner"; exit 1; fi
+          BREW_BIN="$(dirname "$BREW")"; export PATH="$BREW_BIN:$PATH"
+          command -v cmake >/dev/null || "$BREW" install cmake
+          echo "$BREW_BIN" >> "$GITHUB_PATH"
+          # Homebrew's CMake 4 dropped compatibility with the vendored libopus's pre-3.5
+          # `cmake_minimum_required`; treat 3.5 as the policy minimum (the cmake crate's child cmake
+          # inherits this from the env during the xcframework build).
+          echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"
+
+      # Shared compile cache. The script handles the macOS side — see scripts/ci/ensure-sccache.sh.
+      - name: sccache (self-healing install)
+        run: sh scripts/ci/ensure-sccache.sh
+
+      - name: Pin + prune Xcode DerivedData
+        # Without -derivedDataPath, xcodebuild derives its DerivedData directory name from the
+        # PROJECT'S ABSOLUTE PATH — and act_runner rotates its workspace
+        # (~/.cache/act/<hash>/hostexecutor), so each rotation minted a brand new ~760 MB tree
+        # under ~/Library that nothing ever collected. 31 of them piled up in three days
+        # (~32 GB with the shared ModuleCache), filled the runner's boot volume, and failed
+        # v0.16.0's xcframework build with "No space left on device". Pinning one path makes the
+        # tree REUSED instead of multiplied — it also keeps the module cache warm between runs.
+        #
+        # The directory is still named `release` after the workflow this job used to live in. Left
+        # alone deliberately: renaming it would orphan a warm ~760 MB tree and buy nothing.
+        run: |
+          DD="$HOME/ci/derived-data/release"
+          mkdir -p "$DD"
+          echo "DERIVED_DATA=$DD" >> "$GITHUB_ENV"
+          # Safety net for trees the pin does not own: the legacy per-path ones from before this
+          # change, and anything another job leaves in the default root. Untouched for a week ⇒ gone.
+          if [ -d "$HOME/Library/Developer/Xcode/DerivedData" ]; then
+            find "$HOME/Library/Developer/Xcode/DerivedData" -mindepth 1 -maxdepth 1 \
+              -mtime +7 -exec rm -rf {} + 2>/dev/null || true
+          fi
+          echo "disk after prune:"; df -h /System/Volumes/Data | tail -1
+
+      - name: Build PunktfunkCore.xcframework (mac + iOS + tvOS)
+        # tvOS is a tier-3 target (nightly -Zbuild-std): slow on the first build, then cached on
+        # the self-hosted runner. Built on canary too so the tvOS archive/upload below runs on the
+        # same track as iOS/macOS (the nightly toolchain is installed unconditionally above).
+        #
+        # This repeats the `swift` job's mac-slice build, and that is the intended trade: the two
+        # jobs share the runner's sccache and DerivedData, so the overlap is cheap, whereas passing
+        # an xcframework between jobs would mean uploading/downloading it through Gitea's artifact
+        # backend (the one that already forces upload-artifact@v3) on every run.
+        run: BUILD_IOS=1 BUILD_TVOS=1 bash scripts/build-xcframework.sh
+
+      - name: Stage App Store Connect API key
+        env:
+          ASC_P8: ${{ secrets.ASC_API_KEY_P8 }}
+        run: |
+          printf '%s' "$ASC_P8" > "$RUNNER_TEMP/asc.p8"
+          chmod 600 "$RUNNER_TEMP/asc.p8"
+
+      - name: macOS — archive, codesign Developer ID, notarize, DMG
+        # Stable releases only — the notarized DMG is a Gatekeeper/direct-download artifact, not
+        # relevant to TestFlight testers (the canary channel). Skipped on canary main pushes.
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        run: |
+          # Archive UNSIGNED, then codesign with the Developer ID Application identity from the
+          # login keychain. Unsigned archive sidesteps Xcode's keychain-access-groups
+          # provisioning-profile gate at archive time; we re-assert that authorization below by
+          # EMBEDDING a Developer ID profile before codesign (see the keychain note further down).
+          # Bundle is a single static binary.
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
+            -project "$PROJECT" -scheme Punktfunk \
+            -destination 'generic/platform=macOS' \
+            -archivePath "$RUNNER_TEMP/Punktfunk-macos.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
+            -skipMacroValidation -skipPackagePluginValidation \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            CODE_SIGNING_ALLOWED=NO
+          APP="$RUNNER_TEMP/Punktfunk-macos.xcarchive/Products/Applications/Punktfunk.app"
+          # Sandboxed Developer ID: sign with the SAME macOS entitlements the App Store build
+          # uses. codesign won't expand $(AppIdentifierPrefix) — resolve it to the team prefix.
+          RESOLVED="$RUNNER_TEMP/macos.entitlements"
+          sed "s/\$(AppIdentifierPrefix)/${TEAM_ID}./g" \
+            clients/apple/Config/Punktfunk-macOS.entitlements > "$RESOLVED"
+
+          # keychain-access-groups is a MANAGED (restricted) entitlement: App Sandbox and the
+          # network/device keys are self-asserted for Developer ID, but a keychain access group
+          # must be AUTHORIZED by an embedded provisioning profile. Without one, AMFI refuses to
+          # spawn the sandboxed process at launch — "Launchd job spawn failed" (POSIX errno 163),
+          # SIGKILL before main() — even though the bundle is validly signed and notarized. Embed
+          # a "Developer ID" distribution profile for io.unom.punktfunk (Keychain Sharing) so its
+          # entitlements authorize the access group, exactly like the App Store build's profile
+          # does. Located by profile Name among the profiles installed on the runner (see header).
+          DEVID_PROFILE_NAME="Punktfunk macOS Developer ID"
+          PROFILE_SRC=""
+          for p in "$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles/"*.provisionprofile \
+                   "$HOME/Library/MobileDevice/Provisioning Profiles/"*.provisionprofile; do
+            [ -e "$p" ] || continue
+            NAME=$(security cms -D -i "$p" 2>/dev/null | plutil -extract Name raw - 2>/dev/null || true)
+            [ "$NAME" = "$DEVID_PROFILE_NAME" ] && PROFILE_SRC="$p" && break
+          done
+          if [ -n "$PROFILE_SRC" ]; then
+            # Must land BEFORE codesign so it's sealed into the bundle.
+            cp "$PROFILE_SRC" "$APP/Contents/embedded.provisionprofile"
+            echo "embedded Developer ID profile: $PROFILE_SRC"
+          else
+            # Fallback so a missing/expired profile NEVER reships the errno-163 brick: drop the
+            # managed entitlement and let ClientIdentityStore fall back to the legacy file keychain
+            # (its errSecMissingEntitlement path). Degraded (one Keychain prompt) but launchable.
+            echo "::warning::Developer ID profile '$DEVID_PROFILE_NAME' not installed on the runner — stripping keychain-access-groups so the DMG still launches (legacy file keychain). Create it in the Apple portal + install it on the runner to restore the no-prompt data-protection keychain."
+            /usr/libexec/PlistBuddy -c "Delete :keychain-access-groups" "$RESOLVED" 2>/dev/null || true
+          fi
+
+          codesign --force --options runtime --timestamp \
+            --entitlements "$RESOLVED" \
+            --sign "Developer ID Application" "$APP"
+          codesign --verify --strict --verbose=2 "$APP"
+          # Notarized DMG.
+          STAGE="$RUNNER_TEMP/dmg-stage"
+          mkdir -p "$STAGE"
+          cp -R "$APP" "$STAGE/"
+          ln -s /Applications "$STAGE/Applications"
+          DMG="$RUNNER_TEMP/Punktfunk-$VERSION.dmg"
+          hdiutil create -volname "Punktfunk" -srcfolder "$STAGE" -ov -format UDZO "$DMG"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcrun notarytool submit "$DMG" --wait \
+            --key "$RUNNER_TEMP/asc.p8" \
+            --key-id "${{ secrets.ASC_API_KEY_ID }}" \
+            --issuer "${{ secrets.ASC_API_ISSUER_ID }}"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcrun stapler staple "$DMG"
+          echo "DMG=$DMG" >> "$GITHUB_ENV"
+
+      - name: Attach DMG to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          upsert_asset "$RID" "$DMG" "Punktfunk-$VERSION.dmg"
+
+      - name: macOS App Store — archive + upload to TestFlight
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        # Best-effort until the App Store Connect record has the macOS platform + the
+        # "Punktfunk macOS App Store Distribution" profile and the "3rd Party Mac Developer
+        # Installer" cert are on the runner (see the header). The macOS app is sandboxed
+        # (Config/Punktfunk-macOS.entitlements) — mandatory for the Mac App Store.
+        continue-on-error: true
+        run: |
+          # Separate archive from the Developer ID one above: App Store needs a signed, entitled
+          # archive that -exportArchive can re-sign for distribution, not the unsigned-then-codesign
+          # DMG path. Archive with AUTOMATIC signing (development). Why not a manually-specified
+          # profile (as this step used to do): the in-app license screens added a SwiftPM resource
+          # bundle (PunktfunkKit_PunktfunkKit), and a resource bundle is a product type that cannot
+          # carry a provisioning profile — a global PROVISIONING_PROFILE_SPECIFIER (here) or an
+          # sdk-scoped one (iOS/tvOS) lands on it and fails the archive ("does not support
+          # provisioning profiles"). Automatic signing assigns a profile only to the app and leaves
+          # the resource bundle (and the macOS-host macro plugins) alone, and bakes the sandbox
+          # entitlements in. -allowProvisioningUpdates lets Xcode sync the App ID capabilities and
+          # regenerate the managed *development* profile — needed because the App Groups capability
+          # (group.io.unom.punktfunk, in Config/Punktfunk-macOS.entitlements) invalidated the cached
+          # one. This is DEVELOPMENT signing against the Apple Development cert already in the
+          # keychain, so the App-Manager ASC key suffices. DISTRIBUTION signing happens in the export
+          # step below
+          # (manual, via the plist). Quit Xcode so it can't prune the manually-installed App Store
+          # distribution profile that export needs.
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
+          pkill -x Xcode 2>/dev/null || true
+          PROFILE="Punktfunk macOS App Store Distribution"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
+            -project "$PROJECT" -scheme Punktfunk \
+            -destination 'generic/platform=macOS' \
+            -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
+            -skipMacroValidation -skipPackagePluginValidation \
+            -allowProvisioningUpdates \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            CODE_SIGN_STYLE=Automatic \
+            DEVELOPMENT_TEAM="$TEAM_ID"
+          cat > "$RUNNER_TEMP/export-macos-appstore.plist" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>method</key><string>app-store-connect</string>
+            <key>destination</key><string>upload</string>
+            <key>teamID</key><string>$TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>signingCertificate</key><string>Apple Distribution</string>
+            <key>installerSigningCertificate</key><string>3rd Party Mac Developer Installer</string>
+            <key>provisioningProfiles</key>
+            <dict><key>io.unom.punktfunk</key><string>$PROFILE</string></dict>
+          </dict>
+          </plist>
+          EOF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
+            -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
+            -exportOptionsPlist "$RUNNER_TEMP/export-macos-appstore.plist" \
+            -exportPath "$RUNNER_TEMP/export-macos-appstore" \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
+
+      - name: iOS — archive + upload to TestFlight
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        # Best-effort until the App Store Connect app record for io.unom.punktfunk exists.
+        continue-on-error: true
+        run: |
+          # Archive with AUTOMATIC signing (development) — see the macOS App Store step for the full
+          # rationale. The SwiftPM resource bundle (PunktfunkKit_PunktfunkKit, added with the in-app
+          # license screens) builds for iphoneos, so even the sdk-scoped PROVISIONING_PROFILE_SPECIFIER
+          # this step used to set matched it and failed the archive ("does not support provisioning
+          # profiles"). Automatic signing profiles only the app and leaves the resource bundle (and
+          # the macOS-host macro plugins) alone. -allowProvisioningUpdates lets Xcode sync the App ID
+          # capabilities and regenerate the managed *development* profiles for both io.unom.punktfunk
+          # AND the embedded io.unom.punktfunk.widgets — needed because adding the App Groups
+          # capability (group.io.unom.punktfunk, shared with the Widget/Live-Activity extension)
+          # invalidated the cached managed dev profile, which had no widgets profile at all. This is
+          # DEVELOPMENT signing against the Apple Development cert already in the keychain — no cert
+          # creation, so the App-Manager ASC key is sufficient (it only manages App IDs/dev profiles).
+          # DISTRIBUTION signing is the export step below (manual, via the plist) and is unaffected.
+          # A running Xcode.app prunes unrecognized profiles — quit it so the manually-installed
+          # App Store distribution profile survives for export.
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
+          pkill -x Xcode 2>/dev/null || true
+          PROFILE="Punktfunk iOS App Store Distribution"
+          # The embedded PunktfunkWidgetsExtension (bundle io.unom.punktfunk.widgets) is a second
+          # distribution artifact in the .ipa, so manual signing must map its App ID to its own
+          # App Store profile too — else exportArchive fails ("no profile for io.unom.punktfunk.widgets").
+          WIDGET_PROFILE="Punktfunk iOS Widgets App Store Distribution"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
+            -project "$PROJECT" -scheme Punktfunk-iOS \
+            -destination 'generic/platform=iOS' \
+            -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
+            -skipMacroValidation -skipPackagePluginValidation \
+            -allowProvisioningUpdates \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            CODE_SIGN_STYLE=Automatic \
+            DEVELOPMENT_TEAM="$TEAM_ID"
+          cat > "$RUNNER_TEMP/export-appstore.plist" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>method</key><string>app-store-connect</string>
+            <key>destination</key><string>upload</string>
+            <key>teamID</key><string>$TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>signingCertificate</key><string>Apple Distribution</string>
+            <key>provisioningProfiles</key>
+            <dict>
+              <key>io.unom.punktfunk</key><string>$PROFILE</string>
+              <key>io.unom.punktfunk.widgets</key><string>$WIDGET_PROFILE</string>
+            </dict>
+          </dict>
+          </plist>
+          EOF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
+            -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
+            -exportOptionsPlist "$RUNNER_TEMP/export-appstore.plist" \
+            -exportPath "$RUNNER_TEMP/export-appstore" \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
+
+      - name: iOS — export .ipa (Gitea release + run artifact)
+        # The TestFlight step above uploads straight to App Store Connect (destination=upload) and
+        # leaves NO .ipa on disk. Re-export the SAME archive with destination=export to get an
+        # App Store distribution-signed .ipa for the Gitea release + the run artifacts. Same gate as
+        # that archive; a warn+skip (never fails the best-effort iOS leg) if the archive is absent,
+        # e.g. a workflow_dispatch with testflight=false. NOTE: an App Store-signed .ipa installs
+        # only via TestFlight/App Store, not by direct sideload — it's a release/archival artifact.
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        id: ios_ipa
+        run: |
+          ARCHIVE="$RUNNER_TEMP/Punktfunk-ios.xcarchive"
+          if [ ! -d "$ARCHIVE" ]; then
+            echo "::warning::iOS archive not found — skipping .ipa export"
+            exit 0
+          fi
+          PROFILE="Punktfunk iOS App Store Distribution"
+          WIDGET_PROFILE="Punktfunk iOS Widgets App Store Distribution"
+          # destination=export writes the .ipa to -exportPath; otherwise identical manual signing to
+          # the upload plist (both profiles, Apple Distribution). No ASC key needed — no network.
+          cat > "$RUNNER_TEMP/export-appstore-ipa.plist" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>method</key><string>app-store-connect</string>
+            <key>destination</key><string>export</string>
+            <key>teamID</key><string>$TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>signingCertificate</key><string>Apple Distribution</string>
+            <key>provisioningProfiles</key>
+            <dict>
+              <key>io.unom.punktfunk</key><string>$PROFILE</string>
+              <key>io.unom.punktfunk.widgets</key><string>$WIDGET_PROFILE</string>
+            </dict>
+          </dict>
+          </plist>
+          EOF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
+            -archivePath "$ARCHIVE" \
+            -exportOptionsPlist "$RUNNER_TEMP/export-appstore-ipa.plist" \
+            -exportPath "$RUNNER_TEMP/export-ipa"
+          SRC=$(ls "$RUNNER_TEMP/export-ipa/"*.ipa 2>/dev/null | head -1)
+          [ -n "$SRC" ] || { echo "::warning::no .ipa was produced by export"; exit 0; }
+          mkdir -p "$GITHUB_WORKSPACE/dist"
+          IPA="$GITHUB_WORKSPACE/dist/Punktfunk-$VERSION.ipa"
+          mv "$SRC" "$IPA"
+          echo "IPA=$IPA" >> "$GITHUB_ENV"
+          echo "ipa=dist/Punktfunk-$VERSION.ipa" >> "$GITHUB_OUTPUT"
+          echo "exported $IPA"
+
+      - name: Attach .ipa to the workflow run
+        if: steps.ios_ipa.outputs.ipa != ''
+        # v3, not v4: Gitea's artifact backend identifies as GHES, which upload-artifact@v4 refuses
+        # (same reason as android.yml / the screenshots job below). Download is a zip of the .ipa.
+        uses: actions/upload-artifact@v3
+        with:
+          name: punktfunk-ios-ipa
+          path: ${{ steps.ios_ipa.outputs.ipa }}
+          if-no-files-found: warn
+          retention-days: 30
+
+      - name: Attach .ipa to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v') && steps.ios_ipa.outputs.ipa != ''
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          upsert_asset "$RID" "$IPA" "Punktfunk-$VERSION.ipa"
+
+      - name: tvOS — archive + upload to TestFlight
+        # Canary + stable, the same track as iOS/macOS — the tvOS xcframework slice is now built
+        # on every apple push (above), so this matches the iOS step's gate exactly.
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        # Needs tvOS added to the App Store Connect app record + the tvOS platform installed
+        # on the runner (xcodebuild -downloadPlatform tvOS).
+        continue-on-error: true
+        run: |
+          # Archive with AUTOMATIC signing (development) — see the macOS App Store step. The SwiftPM
+          # resource bundle (PunktfunkKit_PunktfunkKit) builds for appletvos and rejected the
+          # sdk-scoped profile this step used to set; Automatic signing profiles only the app and
+          # leaves the resource bundle + the macOS-host macro plugins (OnceMacro/SwizzlingMacro/
+          # AssociationMacro) alone. -allowProvisioningUpdates lets Xcode sync the App ID capabilities
+          # and regenerate the managed *development* profile — the tvOS app carries the App Groups key
+          # (group.io.unom.punktfunk) too, which invalidated the cached one. DEVELOPMENT signing against
+          # the Apple Development cert already in the keychain, so the App-Manager ASC key suffices.
+          # DISTRIBUTION signing is the export step below (manual, plist).
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
+          pkill -x Xcode 2>/dev/null || true
+          PROFILE="Punktfunk tvOS App Store Distribution"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
+            -project "$PROJECT" -scheme Punktfunk-tvOS \
+            -destination 'generic/platform=tvOS' \
+            -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
+            -skipMacroValidation -skipPackagePluginValidation \
+            -allowProvisioningUpdates \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            CODE_SIGN_STYLE=Automatic \
+            DEVELOPMENT_TEAM="$TEAM_ID"
+          cat > "$RUNNER_TEMP/export-tvos.plist" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>method</key><string>app-store-connect</string>
+            <key>destination</key><string>upload</string>
+            <key>teamID</key><string>$TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>signingCertificate</key><string>Apple Distribution</string>
+            <key>provisioningProfiles</key>
+            <dict><key>io.unom.punktfunk</key><string>$PROFILE</string></dict>
+          </dict>
+          </plist>
+          EOF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
+            -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
+            -exportOptionsPlist "$RUNNER_TEMP/export-tvos.plist" \
+            -exportPath "$RUNNER_TEMP/export-tvos" \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
+
+      - name: sccache stats (visibility only)
+        if: always()
+        run: sccache --show-stats
+
   # App Store screenshots of the real UI, zipped and attached to the run as a build artifact.
   # Skipped on PRs (cost); runs on main pushes + manual dispatch. Needs the build/test job green
   # first, and is a separate job so a capture hiccup can never red the core signal.
   #
-  # Scope = the two REQUIRED iOS sizes (iPhone 6.9" + iPad 13"), captured on the Simulator
-  # (`simctl io screenshot`, no Screen Recording grant needed). macOS and tvOS are deliberately
-  # NOT in CI: the self-hosted runner is headless (no window-server session), so the mac window
-  # capture can't run there; tvOS needs the Tier-3 build-std slice. Generate those two locally on
-  # a GUI Mac with `clients/apple/tools/screenshots.sh macos tvos`.
+  # Scope = the two REQUIRED iOS sizes (iPhone 6.9" + iPad 13") + Apple TV (1920×1080), captured
+  # on the Simulator (`simctl io screenshot`, no Screen Recording grant needed). The tvOS slice is
+  # Tier-3 (nightly -Zbuild-std, same as the distribute job — slow cold, cached on the self-hosted
+  # runner). The tvOS scene list is explicit: the gamepad-console scenes are iOS/macOS-only, and an
+  # unknown scene name falls back to a NORMAL app launch — the capture would silently be of the
+  # real empty app. macOS stays deliberately NOT in CI: the runner is headless (no window-server
+  # session), so the mac window capture can't run there — generate it locally on a GUI Mac with
+  # `clients/apple/tools/screenshots.sh macos`.
   screenshots:
     needs: swift
     if: gitea.event_name != 'pull_request'
     runs-on: macos-arm64
-    timeout-minutes: 75
+    timeout-minutes: 90
     steps:
       - uses: actions/checkout@v4
 
-      - name: Rust toolchain + iOS Simulator targets
+      - name: Rust toolchain + iOS Simulator targets (+ nightly for the tvOS slices)
         run: |
           if ! command -v rustup >/dev/null && [ ! -x "$HOME/.cargo/bin/rustup" ]; then
             curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
@@ -154,18 +702,15 @@ jobs:
           dirname "$RUSTUP" >> "$GITHUB_PATH"
           "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
             aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
+          # tvOS targets are tier-3 (no prebuilt std) — build-xcframework.sh compiles them with
+          # nightly + -Zbuild-std, so ensure nightly + rust-src are present (see the swift job).
+          "$RUSTUP" toolchain install nightly --profile minimal
+          "$RUSTUP" component add rust-src --toolchain nightly
 
-      # Shared compile cache. ~/.local/bin is on the runner daemon's PATH; GITHUB_PATH is
-      # belt-and-braces. bsdtar (macOS) globs by default — no --wildcards.
+      # Shared compile cache. The script handles the macOS side (user-prefix install +
+      # GITHUB_PATH, bsdtar globbing) — see scripts/ci/ensure-sccache.sh.
       - name: sccache (self-healing install)
-        run: |
-          if ! command -v sccache >/dev/null; then
-            mkdir -p "$HOME/.local/bin"
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-aarch64-apple-darwin.tar.gz \
-              | tar -xz --strip-components=1 -C "$HOME/.local/bin" '*/sccache'
-          fi
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       # See the swift job: audiopus_sys (via the in-core Opus decode) builds vendored libopus with CMake.
       - name: CMake (for the vendored libopus audiopus_sys builds)
@@ -183,7 +728,7 @@ jobs:
           # inherits this from the env during the xcframework build).
           echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"
 
-      - name: Pin + prune DerivedData (same disease release.yml already cures)
+      - name: Pin + prune DerivedData (same disease the distribute job already cures)
         # screenshots.sh builds into a throwaway mktemp DerivedData per invocation — two
         # fresh ~1 GB trees per run, zero reuse. Pin one stable root (PF_SHOT_DERIVED_DATA,
         # honored by the script) so repeat runs are incremental, and GC anything a week old
@@ -197,10 +742,10 @@ jobs:
               -mtime +7 -exec rm -rf {} + 2>/dev/null || true
           fi
 
-      - name: Build PunktfunkCore.xcframework (mac + iOS slices)
-        run: BUILD_IOS=1 bash scripts/build-xcframework.sh
+      - name: Build PunktfunkCore.xcframework (mac + iOS + tvOS slices)
+        run: BUILD_IOS=1 BUILD_TVOS=1 bash scripts/build-xcframework.sh
 
-      - name: Capture screenshots (iPhone 6.9" + iPad 13"; auto-creates the Simulators)
+      - name: Capture screenshots (iPhone 6.9" + iPad 13" + Apple TV; auto-creates the Simulators)
         working-directory: clients/apple
         env:
           SETTLE: "8" # Simulators settle slower than a local run
@@ -208,6 +753,10 @@ jobs:
           # Independent invocations: one platform failing skips it, not the other.
           bash tools/screenshots.sh ios  || echo "::warning::iOS (iPhone 6.9\") screenshots skipped"
           bash tools/screenshots.sh ipad || echo "::warning::iPad 13\" screenshots skipped"
+          # tvOS shoots only the scenes that exist there — the 06–09 gamepad-console scenes are
+          # compiled out on tvOS (native focus engine), and an unknown name = a normal app launch.
+          SCENES="01-stream 02-hosts 05-settings 03-pair" \
+            bash tools/screenshots.sh tvos || echo "::warning::Apple TV screenshots skipped"
           echo "Produced:"; ls -la screenshots || true
 
       - name: Shut the Simulators down (leaked booted sims once piled up 846 deep)

.gitea/workflows/arch.yml

@@ -81,6 +81,14 @@ env:
   SCCACHE_REGION: home-central
   AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # The C/C++ half of the cache (aws-lc-sys, vendored libopus, openh264's C++). Safe at workflow
+  # level — no cross-compiling job here (see ci.yml's `rust` job for that trap). NOTE these ALSO
+  # have to be named in the makepkg step's `sudo -u builder env …` list: sudo's env_reset drops
+  # everything not listed, which is why the sccache vars are already spelled out there.
+  CMAKE_C_COMPILER_LAUNCHER: sccache
+  CMAKE_CXX_COMPILER_LAUNCHER: sccache
+  CC_x86_64_unknown_linux_gnu: sccache cc
+  CXX_x86_64_unknown_linux_gnu: sccache c++
   CARGO_INCREMENTAL: "0"
 
 jobs:
@@ -220,6 +228,39 @@ jobs:
           echo "REPO=$REPO" >> "$GITHUB_ENV"
           echo "pacman $V-$R -> repo '$REPO'"
 
+      # ── The web console, built once per (web+sdk content, bun) instead of once per job ─────────
+      # Shares deb.yml's key family — see the fuller note there. Unlike the RPM leg this needs no
+      # hand-off macro: makepkg builds with PF_SRCDIR pointing at this workspace, so a restored
+      # web/.output is already exactly where PKGBUILD's build-if-missing guard looks for it.
+      #
+      # Built here as root, BEFORE the makepkg step's `chown -R builder:` sweeps the tree, so the
+      # bundle ends up owned like everything else the builder user is handed.
+      - name: Web console cache key
+        run: echo "bunver=$(bun --version 2>/dev/null || echo none)" >> "$GITHUB_ENV"
+      - name: Cache the built web console
+        id: webconsole
+        uses: actions/cache@v4
+        with:
+          path: web/.output
+          key: web-console-linux-bun${{ env.bunver }}-${{ hashFiles('web/**', 'sdk/**') }}
+
+      - name: Build the web console (cache miss only)
+        if: steps.webconsole.outputs.cache-hit != 'true'
+        run: |
+          cd web
+          bun install --frozen-lockfile --ignore-scripts
+          bun run build
+
+      - name: The console must exist (cache hit or fresh build)
+        run: |
+          if [ ! -f web/.output/server/index.mjs ]; then
+            echo "::error::web/.output is missing — neither the cache restore nor the build produced it"
+            exit 1
+          fi
+          grep -q 'Bun\.serve' web/.output/server/index.mjs || {
+            echo "::error::web/.output is not a bun bundle (wrong nitro preset)"; exit 1; }
+          echo "web console present: $(du -sh web/.output | cut -f1)"
+
       - name: Build packages (makepkg)
         run: |
           git config --global --add safe.directory "$PWD"
@@ -252,8 +293,19 @@ jobs:
             SCCACHE_BUCKET="$SCCACHE_BUCKET" SCCACHE_ENDPOINT="$SCCACHE_ENDPOINT" \
             SCCACHE_REGION="$SCCACHE_REGION" \
             AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
+            CMAKE_C_COMPILER_LAUNCHER="$CMAKE_C_COMPILER_LAUNCHER" \
+            CMAKE_CXX_COMPILER_LAUNCHER="$CMAKE_CXX_COMPILER_LAUNCHER" \
+            CC_x86_64_unknown_linux_gnu="$CC_x86_64_unknown_linux_gnu" \
+            CXX_x86_64_unknown_linux_gnu="$CXX_x86_64_unknown_linux_gnu" \
             makepkg -f -d --holdver
           ls -lh "$GITHUB_WORKSPACE/dist"
+          # Visibility only. The stats have to be read as the SAME user that ran the compiles —
+          # sccache keeps its stats in a per-user server process, so a root `--show-stats` here
+          # would report an idle server and zero everything.
+          sudo -u builder env SCCACHE_BUCKET="$SCCACHE_BUCKET" SCCACHE_ENDPOINT="$SCCACHE_ENDPOINT" \
+            SCCACHE_REGION="$SCCACHE_REGION" \
+            AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
+            sccache --show-stats || true
 
       # The host must ship a VERSIONED libav soname dep, and nothing else in this pipeline proves
       # it. packaging/arch/PKGBUILD lists bare `libavcodec.so` etc. and relies on makepkg rewriting

.gitea/workflows/audit.yml

@@ -2,16 +2,21 @@
 # license-allowlist gate (CRA Annex I Part II: know your components; catch a bad dep the moment
 # it lands).
 #   * cargo-audit → the (network-facing, crypto-heavy) Rust tree, against the RustSec advisory DB.
+#                   ⚠ ALL FIVE Rust lockfiles, each named with its own `--file`: a bare `cargo audit`
+#                   reads only the root one, which is how the drivers lock went unscanned for so
+#                   long despite already being in this job's `paths:` filter.
 #   * bun audit   → each Bun-managed tree that ships or publishes: web (the mgmt console BFF —
 #                   login gate, session sealing, mgmt bearer token), sdk (@punktfunk/host),
 #                   plugin-kit (@punktfunk/plugin-kit).
 #   * pnpm audit  → clients/decky (the Steam Deck plugin).
-#   * docs-site   → scanned NON-blocking (continue-on-error): known transitive advisories ride in
-#                   via the CMS/UI chain (@unom/ui → payload → dompurify/monaco) and the nitropack
-#                   build chain (node-tar, brace-expansion); clearing them needs coordinated bumps
-#                   verified against the LIVE site (the docs don't build standalone) — tracked in
-#                   punktfunk-planning design/cra-readiness.md. Flip to blocking once clean.
-#   * cargo-about → license-allowlist gate over BOTH Rust workspaces (about.toml `accepted`);
+#   * docs-site   → scanned NON-blocking (continue-on-error). 2026-08-14: docs-site's own deps
+#                   are current (fumadocs/tanstack/react bumped; build + tsc + serve verified),
+#                   but every remaining advisory is pinned INSIDE @unom/ui 0.9.2's dependency
+#                   tree (@payloadcms/* → fast-uri/image-size/sharp, next 16.x, sass→immutable) —
+#                   nothing bumpable from this lockfile, and overrides would fork what the CMS
+#                   actually ships. The fix belongs in the @unom/ui package repo; flip this to
+#                   blocking after a ui release with a clean payload chain lands here.
+#   * cargo-about → license-allowlist gate over the host + driver workspaces (about.toml `accepted`);
 #                   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.)
@@ -47,6 +52,9 @@ on:
     paths:
       - 'Cargo.lock'
       - 'packaging/windows/drivers/Cargo.lock'
+      - 'packaging/windows/pf-vkhdr-layer/Cargo.lock'
+      - 'tools/win-input-matrix/Cargo.lock'
+      - 'tools/hid-descriptor-dump/Cargo.lock'
       - 'web/bun.lock'
       - 'docs-site/bun.lock'
       - 'sdk/bun.lock'
@@ -83,7 +91,15 @@ jobs:
         run: |
           git config --global --add safe.directory "$PWD"
           command -v cargo-audit >/dev/null 2>&1 || cargo install --locked cargo-audit
+          # Bare `cargo audit` scans ONLY the root Cargo.lock. The other three Rust workspaces are
+          # separate locks and were silently never scanned — the drivers one despite already being
+          # in this job's `paths:` filter, so edits to it triggered a run that then ignored it.
+          # Each needs its own `--file`. `pf-vkhdr-layer` had no lockfile at all until 2026-08-13.
           cargo audit
+          cargo audit --file packaging/windows/drivers/Cargo.lock
+          cargo audit --file packaging/windows/pf-vkhdr-layer/Cargo.lock
+          cargo audit --file tools/win-input-matrix/Cargo.lock
+          cargo audit --file tools/hid-descriptor-dump/Cargo.lock
 
   bun-audit:
     strategy:
@@ -355,9 +371,10 @@ jobs:
       # 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.
+      # ENTIRELY — it does not merge. That used to cost the aarch64 `--cfg aes_armv8` /
+      # `--cfg polyval_armv8` decrypt flags; the aes 0.9 / polyval 0.7 bump retired those cfgs
+      # (see the tombstone in .cargo/config.toml), so there is nothing left for an override to
+      # drop here. Keep the pin anyway: these target-features are meaningless off x86_64.
       # 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:

.gitea/workflows/bench.yml

@@ -38,14 +38,9 @@ jobs:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       - name: Prep
         run: |

.gitea/workflows/ci.yml

@@ -23,6 +23,12 @@ on:
 # Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
 # unbound). Keys include compiler hash + target + flags, so cross-OS/arch entries can
 # never collide; every Rust job on every host feeds and reads one warm cache.
+#
+# RUSTC_WRAPPER covers RUST compilations and nothing else. The C/C++ half of this workspace —
+# aws-lc-sys, openh264-sys2's vendored C++, the CMake-built libopus behind audiopus_sys, pyrowave —
+# was paid in full on every run until the CMAKE_*_COMPILER_LAUNCHER / CC_* wiring below existed.
+# Linking is the third phase and is cacheable by nothing: that one is addressed in the builder
+# images with mold (ci/cargo-config-mold.toml).
 env:
   RUSTC_WRAPPER: sccache
   SCCACHE_BUCKET: unom-ci-sccache
@@ -30,6 +36,11 @@ env:
   SCCACHE_REGION: home-central
   AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # Route CMake-driven C/C++ through the same cache. Safe at workflow level: it names no
+  # triple, and cmake-rs overrides it per-invocation with a `-D` flag when cc-rs reports a
+  # wrapper, so the two can never double-wrap into `sccache sccache cc`.
+  CMAKE_C_COMPILER_LAUNCHER: sccache
+  CMAKE_CXX_COMPILER_LAUNCHER: sccache
   # sccache and incremental compilation are mutually exclusive; CI wants the shared
   # cache, dev boxes keep incremental.
   CARGO_INCREMENTAL: "0"
@@ -40,18 +51,25 @@ jobs:
     container:
       image: 192.168.1.58:5010/punktfunk-rust-ci:latest
     timeout-minutes: 90
+    env:
+      # cc-rs recognises `sccache` as a compiler wrapper when it leads CC/CXX, and cmake-rs then
+      # forwards it as -DCMAKE_C_COMPILER_LAUNCHER, so this covers both build-script styles.
+      #
+      # ⚠ JOB-scoped, NOT workflow-scoped, and it must stay that way: the `rust-arm64` job below
+      # runs in the cross image, which sets CC_x86_64_unknown_linux_gnu=/usr/local/bin/pf-host-cc
+      # (ci/rust-ci-arm64cross.Dockerfile) — a wrapper that strips arm64 include dirs off
+      # HOST-targeted compiles so ffmpeg-sys-next's probe resolves against the amd64 headers.
+      # Setting this at workflow level would silently overwrite that wrapper and break the cross
+      # build in a way that looks like a header mismatch, not a CI config error.
+      CC_x86_64_unknown_linux_gnu: sccache cc
+      CXX_x86_64_unknown_linux_gnu: sccache c++
     steps:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       # punktfunk-client-linux link deps. Also baked into rust-ci.Dockerfile — but ci.yml
       # runs against the image from the PREVIOUS push (docker.yml bootstrap note), so this
@@ -105,8 +123,17 @@ jobs:
           # out of disk mid-build and actions/cache saved a truncated target/ (a dep's .rmeta
           # went missing -> E0463 "can't find crate"). A suffix bump wouldn't help — restore-keys
           # would fall back to the poisoned prefix — so the prefix itself is versioned.
-          key: cargo-target-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-target-v3-${{ env.rustc }}-
+          #
+          # `-debug-`: THIS JOB BUILDS DEBUG. deb.yml builds RELEASE and used to share this exact
+          # key, with a comment claiming the release build "reuses ci.yml's clean artifacts" — it
+          # never could. actions/cache is first-saver-wins on an exact key and this job is the
+          # faster of the two, so what landed under the shared key was always a debug-only target/
+          # (target/debug, no target/release). deb.yml restored a tree containing nothing it could
+          # use and, because the key was already taken, never got to save its own — so every
+          # release build re-linked from scratch, forever. Splitting the profiles into separate key
+          # families is the fix; do not merge them again, however tempting the dedupe looks.
+          key: cargo-target-debug-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-debug-v3-${{ env.rustc }}-
 
       - name: Format
         run: cargo fmt --all --check
@@ -187,7 +214,17 @@ jobs:
 
       - name: Verify generated header is committed & up to date
         run: |
-          cargo build -p punktfunk-core --locked
+          cargo build -p punktfunk-core --locked >/tmp/core-build.log 2>&1 \
+            || { cat /tmp/core-build.log; exit 1; }
+          cat /tmp/core-build.log
+          # build.rs demotes a cbindgen failure to a warning and then writes NOTHING — the
+          # checked-in header stays untouched and the drift check below stays green while the
+          # header is silently stale. So first assert the regeneration actually happened.
+          # (cargo replays build-script warnings from cache, so this holds on cached builds too.)
+          grep -q "punktfunk-core: wrote" /tmp/core-build.log
+          if grep -q "cbindgen failed" /tmp/core-build.log; then
+            echo "cbindgen failed to parse the ABI surface — header NOT regenerated" && exit 1
+          fi
           git config --global --add safe.directory "$PWD"
           git diff --exit-code include/punktfunk_core.h \
             || (echo "include/punktfunk_core.h is stale — commit the regenerated header" && exit 1)
@@ -210,14 +247,9 @@ jobs:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       - name: Cache keys
         run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
@@ -232,8 +264,16 @@ jobs:
         with:
           path: target
           # Its OWN prefix: aarch64 artifacts must never share the amd64 jobs' target cache.
-          key: cargo-target-arm64-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-target-arm64-v1-${{ env.rustc }}-
+          #
+          # `-debug-` in the name is load-bearing. This job builds DEBUG (clippy + a
+          # `cargo build`), while deb.yml's arm64 leg builds RELEASE into the same
+          # target/aarch64-unknown-linux-gnu tree. They used to share this exact key, and
+          # actions/cache is first-saver-wins on an exact key: this job finishes in ~1.5 min and
+          # saved a debug-only tree, so the .deb leg's release artifacts were NEVER persisted and
+          # it re-linked everything from sccache on every run. Same disease as the amd64 pair —
+          # see the note on deb.yml's `cargo-target-release-v1-` key.
+          key: cargo-target-arm64-debug-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-arm64-debug-v1-${{ env.rustc }}-
 
       - name: Clippy for aarch64 (deny warnings)
         run: |
@@ -249,6 +289,14 @@ jobs:
           cargo build --release --target aarch64-unknown-linux-gnu --locked \
             -p punktfunk-client-session --no-default-features
 
+      # Visibility only — but the ONLY way to tell a warm cache from a cold one after the fact.
+      # Every Rust job in this repo ends with this line for that reason; a hit rate that quietly
+      # collapses (a toolchain bump, a flag change, an S3 outage) is otherwise invisible and just
+      # looks like "CI got slower".
+      - name: sccache stats (visibility only)
+        if: always()
+        run: sccache --show-stats
+
   web:
     runs-on: ubuntu-24.04
     container:

.gitea/workflows/deb.yml

@@ -1,6 +1,6 @@
-# Build the punktfunk .debs and publish them to Gitea's Debian package registry, so Ubuntu
-# boxes get new builds via `apt update && apt upgrade`. Three jobs, all publishing to the same
-# apt distribution/component:
+# Build the punktfunk .debs and publish them to Gitea's Debian package registry, so Debian and
+# Ubuntu boxes get new builds via `apt update && apt upgrade`. Five jobs; the four builders all
+# publish to the same apt distribution/component, and the fifth checks the result:
 #
 #   build-publish       — client + web + scripting, on the Ubuntu 26.04 rust-ci image (the client
 #                         needs 24.04-absent libs: SDL3, GTK4 ≥ 4.20).
@@ -11,8 +11,17 @@
 #   build-publish-host  — the HOST, on the Ubuntu 24.04 rust-ci-noble image with a from-source
 #                         FFmpeg 8 BUNDLED into the .deb. This lowers the host's glibc floor to 2.39
 #                         and removes the hard `Depends: libavcodec62`, so the ONE host .deb installs
-#                         on Ubuntu 24.04 LTS through 26.04. (A 26.04-built host .deb is uninstallable
-#                         on 24.04 — the reason this job exists; see packaging/debian/README.md.)
+#                         on Ubuntu 24.04 LTS through 26.04 — and, for free, on Debian 13.
+#                         (A 26.04-built host .deb is uninstallable on 24.04 — the reason this job
+#                         exists; see packaging/debian/README.md.)
+#   build-publish-gamescope
+#                       — the patched `punktfunk-gamescope`, on DEBIAN 13. It lived in the host job
+#                         until 2026-08 and never once succeeded there: noble's wayland is 1.22.0
+#                         and the vendored wlroots floors it at 1.23.1, so v0.26.0 and v0.27.0 both
+#                         shipped without the package while the docs told apt users to install it.
+#   smoke-install       — installs what was just published, from the registry, in pristine
+#                         ubuntu:24.04 / ubuntu:26.04 / debian:trixie images. Nothing here used to
+#                         install a package it built, which is how both of the above survived.
 #
 # Both compute VERSION identically (scripts/ci/pf-version.sh is deterministic per commit), so the
 # host and client packages always share a version line. The release-attach helpers are race-safe
@@ -70,6 +79,11 @@ env:
   SCCACHE_REGION: home-central
   AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # CMake-driven C/C++ through the same cache (aws-lc-sys, the vendored libopus). Workflow level
+  # is safe — it names no triple; the CC_*/CXX_* half is per-job below, because the arm64 leg's
+  # image needs its own CC_x86_64 wrapper. See ci.yml's `rust` job for the full note.
+  CMAKE_C_COMPILER_LAUNCHER: sccache
+  CMAKE_CXX_COMPILER_LAUNCHER: sccache
   # sccache and incremental compilation are mutually exclusive; CI wants the shared
   # cache, dev boxes keep incremental.
   CARGO_INCREMENTAL: "0"
@@ -80,18 +94,18 @@ jobs:
     container:
       image: 192.168.1.58:5010/punktfunk-rust-ci:latest
     timeout-minutes: 90
+    env:
+      # ⚠ Job-scoped, never workflow-scoped: build-publish-client-arm64 runs in the cross image,
+      # whose own CC_x86_64_unknown_linux_gnu=pf-host-cc must survive. See ci.yml's `rust` job.
+      CC_x86_64_unknown_linux_gnu: sccache cc
+      CXX_x86_64_unknown_linux_gnu: sccache c++
     steps:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       - name: Version + channel
         # vX.Y.Z tag -> X.Y.Z, published to the `stable` apt distribution (a real release).
@@ -129,7 +143,9 @@ jobs:
           apt-get install -y --no-install-recommends dpkg-dev python3 \
             libgtk-4-dev libadwaita-1-dev libsdl3-dev
 
-      # Share ci.yml's cache keys so the release build reuses its registry + target artifacts.
+      # The cargo-home (registry/git) cache IS shared with ci.yml — those are pure downloads,
+      # profile-independent, and deduping them across the fleet is the whole point. The target
+      # cache is NOT; see below.
       - name: Cache keys
         run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
       - uses: actions/cache@v4
@@ -142,10 +158,20 @@ jobs:
       - uses: actions/cache@v4
         with:
           path: target
-          # -v3-: bypass a target cache poisoned by a disk-full build (see ci.yml). Shares the
-          # key with ci.yml so the release build reuses its clean artifacts.
-          key: cargo-target-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-target-v3-${{ env.rustc }}-
+          # -v3-: bypass a target cache poisoned by a disk-full build (see ci.yml).
+          #
+          # `-release-`, and NOT ci.yml's key. This step used to read
+          # `cargo-target-v3-<rustc>-<lock>` — byte-identical to ci.yml's — under a comment saying
+          # the release build "reuses its clean artifacts". It never did, and could not: ci.yml
+          # builds DEBUG, this job builds RELEASE, and actions/cache is first-saver-wins on an
+          # exact key. ci.yml's `rust` job finishes in ~6 min against this job's ~7-8, so ci.yml
+          # always won the save, this job always restored a target/ with an empty target/release,
+          # and — the expensive half — its own release artifacts were then never persisted,
+          # because the key it would have saved under was already taken. Every canary .deb has
+          # therefore been a from-scratch release build (sccache-assisted, but every link and
+          # every build script re-run) for as long as both keys have existed.
+          key: cargo-target-release-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-release-v3-${{ env.rustc }}-
 
       - name: Build release clients
         env:
@@ -163,7 +189,31 @@ jobs:
           cargo build --release --locked \
             -p punktfunk-client-linux -p punktfunk-client-session -p punktfunk-cli -p pf-update
 
+      # ── The web console, built ONCE per (web+sdk content, bun) rather than once per job ────────
+      # This bundle was being rebuilt six times on every push — ci.yml, here, both RPM legs, arch,
+      # and the docker app image — at ~2.5 min each, for output that is a pure function of web/ and
+      # sdk/. windows-host.yml has cached it this way for a while; this is the same arrangement for
+      # the Linux packaging legs, sharing one key family so a hit in one warms the others.
+      #
+      # The bun version is IN THE KEY. Each builder image installs its own bun (rust-ci, fedora-rpm
+      # and arch-ci each run the bun.sh installer at image-build time), so without it a bundle built
+      # by one image's bun could be shipped by a job running a different one. They are usually the
+      # same version and do share; when they diverge, they simply stop sharing instead of silently
+      # mixing.
+      - name: Web console cache key
+        run: echo "bunver=$(bun --version 2>/dev/null || echo none)" >> "$GITHUB_ENV"
+      - name: Cache the built web console
+        id: webconsole
+        uses: actions/cache@v4
+        with:
+          path: web/.output
+          key: web-console-linux-bun${{ env.bunver }}-${{ hashFiles('web/**', 'sdk/**') }}
+
       - name: Build + smoke-boot web console (bun preset)
+        # Skipped when the cache already holds this exact (web+sdk, bun) bundle — the assertion step
+        # below is what makes that safe. The bundle in the cache was smoke-booted by the run that
+        # produced it, and ci.yml's `web` job still builds and tests the console on every push.
+        if: steps.webconsole.outputs.cache-hit != 'true'
         # Gate the .deb on a real bun boot: the punktfunk-web .deb runs the Nitro `bun` preset
         # (our Bun.serve TLS entry), so prove the build IS a bun bundle and serves /login.
         # No TLS env here, so the custom entry binds plain HTTP — the smoke curl stays simple.
@@ -176,7 +226,12 @@ jobs:
           }
           export PATH="$HOME/.bun/bin:$PATH"
           cd web
-          bun install --frozen-lockfile
+          # --ignore-scripts, like every other web install in CI (ci.yml, web-screenshots.yml,
+          # windows-host.yml, the SDK installs). This was the ONE site still running lifecycle
+          # scripts, and web's `postinstall` is `bun2nix -o bun.nix` — a Nix codegen step this job
+          # neither consumes nor commits, whose only effect here is to make the install depend on
+          # bun2nix resolving. `build` re-runs its own `prebuild` codegen regardless.
+          bun install --frozen-lockfile --ignore-scripts
           bun run build
           if ! grep -q 'Bun\.serve' .output/server/index.mjs; then
             echo "ERROR: web build is not a bun bundle — need the 'bun' preset + custom entry"; exit 1
@@ -188,6 +243,22 @@ jobs:
           echo "web console smoke: /login -> $code"
           [ "$code" = 200 ] || { echo "ERROR: web console failed to boot under bun"; exit 1; }
 
+      # ⚠ NOT optional, and it must run on BOTH paths (cache hit and fresh build). The packaging
+      # scripts treat a missing web/.output as "build it yourself", which is right for a local run
+      # and wrong here: it would silently turn a broken cache restore into a slow, quiet rebuild, or
+      # — with the build step skipped and the restore empty — into a package with no console at all.
+      # windows-host.yml shipped exactly that in 0.22.1/0.22.2 (an unset WEB_OUTPUT_DIR behind a
+      # single Write-Host), which is why its equivalent step throws too. Fail loudly instead.
+      - name: The console must exist (cache hit or fresh build)
+        run: |
+          if [ ! -f web/.output/server/index.mjs ]; then
+            echo "::error::web/.output is missing — neither the cache restore nor the build produced it"
+            exit 1
+          fi
+          grep -q 'Bun\.serve' web/.output/server/index.mjs || {
+            echo "::error::web/.output is not a bun bundle (wrong nitro preset)"; exit 1; }
+          echo "web console present: $(du -sh web/.output | cut -f1)"
+
       - name: Build .debs
         run: |
           export PATH="$HOME/.bun/bin:$PATH"
@@ -198,6 +269,13 @@ jobs:
           # The plugin/script runner (bun-bundled Effect SDK) — same vendored-bun mechanics.
           VERSION="$VERSION" BUN_BIN="$(command -v bun || true)" bash packaging/debian/build-scripting-deb.sh
 
+      # Visibility only. With the target cache now actually saving release artifacts (see the
+      # cache key note above), this is how a regression in that arrangement becomes visible:
+      # a run that suddenly reports thousands of misses is a cache that stopped restoring.
+      - name: sccache stats (visibility only)
+        if: always()
+        run: sccache --show-stats
+
       - name: Publish to the Gitea apt registry
         env:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
@@ -242,18 +320,17 @@ jobs:
     container:
       image: 192.168.1.58:5010/punktfunk-rust-ci-noble:latest
     timeout-minutes: 90
+    env:
+      # ⚠ Job-scoped — see build-publish above and ci.yml's `rust` job.
+      CC_x86_64_unknown_linux_gnu: sccache cc
+      CXX_x86_64_unknown_linux_gnu: sccache c++
     steps:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       - name: Version + channel
         run: |
@@ -289,9 +366,12 @@ jobs:
         with:
           path: target
           # Own key: this target dir is built against 24.04's glibc/toolchain and must NOT share
-          # ci.yml's 26.04 target cache (mixing would poison both).
-          key: cargo-target-noble-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-target-noble-v1-${{ env.rustc }}-
+          # ci.yml's 26.04 target cache (mixing would poison both). It is also the only job using
+          # this prefix, so — unlike the amd64/arm64 pairs above — it has always been able to save
+          # and restore its own release artifacts. `-release-` is spelled out anyway so the whole
+          # file reads consistently and nobody "unifies" it back into a shared key later.
+          key: cargo-target-noble-release-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-noble-release-v1-${{ env.rustc }}-
 
       - name: Build release host
         env:
@@ -326,6 +406,12 @@ jobs:
         run: |
           VERSION="$VERSION" BUNDLE_FFMPEG=1 bash packaging/debian/build-deb.sh
 
+      # Visibility only — placed here, right after the last compile, rather than at the end of the
+      # job: the gamescope gate below must stay the final step (see its own note).
+      - name: sccache stats (visibility only)
+        if: always()
+        run: sccache --show-stats
+
       # Read the capability matrix out of the BUILT .deb before it is published. dpkg carries no
       # capability metadata — the postinst applies them — so this reads the postinst that will
       # actually run on a user's box, plus the payload. 0.26.0-1 granted the host cap_sys_nice=ep
@@ -337,82 +423,6 @@ jobs:
           bash scripts/ci/assert-cap-matrix.sh --self-test
           bash scripts/ci/assert-cap-matrix.sh dist/punktfunk-host_*.deb
 
-      # punktfunk-gamescope for apt. Same reasoning as the RPM leg in rpm.yml: without a packaged
-      # build, a Debian/Ubuntu box has no route to the patched gamescope except compiling it, and a
-      # stock gamescope streams SDR, cursorless, and tells every game its display is 60 Hz.
-      #
-      # CACHED on packaging/gamescope/** alone — it depends on nothing else in this repo, so a
-      # normal push restores a binary instead of spending ~10 minutes on someone else's tree.
-      - uses: actions/cache@v4
-        id: gamescope
-        with:
-          path: gs-cache
-          key: punktfunk-gamescope-noble-${{ hashFiles('packaging/gamescope/**') }}
-
-      - name: Build the patched gamescope
-        if: steps.gamescope.outputs.cache-hit != 'true'
-        # Best-effort, exactly like rpm.yml: the host packages above are the primary delivery and
-        # work without this binary, so a hiccup building an unrelated tree must not fail the job.
-        # `build-dep gamescope` resolves the distro's much older packaged version, so it can come up
-        # short — that is what the `|| true`s absorb, and the marker check downstream is what makes
-        # a half-built result impossible to ship.
-        run: |
-          set -x
-          apt-get update
-          apt-get install -y --no-install-recommends meson ninja-build glslc git || true
-          apt-get build-dep -y gamescope || true
-          # NOT best-effort. `build-dep gamescope` resolves the distro's much older packaged
-          # gamescope — where noble has one at all — so it misses what the master tree needs, and
-          # wayland-protocols is the gap that actually stops the build: meson dies in
-          # protocol/meson.build with "Neither a subproject directory nor a wayland-protocols.wrap
-          # file was found", because the tree has no wrap fallback for it. That is what happened on
-          # the v0.26.0 tag: the step warned and skipped, the job stayed green, and the release
-          # shipped with no gamescope .deb while the notes said it had one.
-          apt-get install -y --no-install-recommends wayland-protocols
-          # The remaining Arch makedepends the older packaged gamescope does not necessarily pull.
-          # Best-effort: meson falls back or does without, and a name that moves between Ubuntu
-          # releases should not fail the job. (No libstdc++ static package is needed here — g++
-          # ships libstdc++.a, which is why only Fedora tripped the sanity check.)
-          # `build-dep gamescope` gives noble almost nothing — the distro has no comparable package
-          # — so the tree's real dependency set has to be named outright. One `apt-get` per name on
-          # purpose: a single transaction aborts wholesale on one unknown package, which would
-          # install NOTHING and hide the real gap behind a name typo. Best-effort per package, with
-          # the missing one named; the end-of-job gate below is what actually decides.
-          for p in libxdamage-dev libxcomposite-dev libxrender-dev libxext-dev libxxf86vm-dev \
-                   libxtst-dev libx11-dev libxres-dev libxmu-dev libxcursor-dev libxi-dev \
-                   libxfixes-dev libxkbcommon-dev libxkbcommon-x11-dev libcap-dev libdrm-dev \
-                   libinput-dev libudev-dev libpipewire-0.3-dev libseat-dev libsdl2-dev \
-                   libluajit-5.1-dev libavif-dev libdecor-0-dev hwdata libglm-dev libbenchmark-dev \
-                   glslang-tools libvulkan-dev libwayland-dev libxcb1-dev libxcb-composite0-dev \
-                   libxcb-xfixes0-dev libxcb-res0-dev libxcb-ewmh-dev libxcb-icccm4-dev \
-                   libxcb-errors-dev libpixman-1-dev libdisplay-info-dev libgbm-dev libegl-dev \
-                   cmake xwayland; do
-            apt-get install -y --no-install-recommends "$p" \
-              || echo "::warning::no such noble package: $p (gamescope may still build without it)"
-          done
-          if bash packaging/gamescope/build-punktfunk-gamescope.sh \
-               --destdir "$PWD/gs-stage" --prefix /usr --jobs "$(nproc)"; then
-            install -Dm0755 gs-stage/usr/bin/punktfunk-gamescope gs-cache/punktfunk-gamescope
-          else
-            # Warn only, even on a tag. The hard gate moved to the END of this job: failing HERE
-            # skips the host .deb's own publish + release-attach steps below, which is how the
-            # v0.26.0 release ended up still carrying the pre-CAP_SYS_NICE host .deb from an
-            # earlier tag commit — a KDE-breaking artifact withheld from replacement by a gate
-            # meant to protect the release. Never let a missing EXTRA stop a good artifact
-            # shipping; go red afterwards instead.
-            echo "::warning::punktfunk-gamescope failed to build on noble — no .deb this run (gamescope sessions stay SDR)"
-          fi
-
-      - name: Build punktfunk-gamescope .deb
-        # Picked up by the publish loop below, which globs dist/*.deb.
-        run: |
-          if [ -x gs-cache/punktfunk-gamescope ] && gs-cache/punktfunk-gamescope --version >/dev/null 2>&1; then
-            bash packaging/debian/build-gamescope-deb.sh --binary gs-cache/punktfunk-gamescope
-          else
-            # Warn only — see the note on the build step. The gate is the last step of this job.
-            echo "::warning::no usable punktfunk-gamescope — skipping its .deb"
-          fi
-
       - name: Publish to the Gitea apt registry
         env:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
@@ -440,25 +450,111 @@ jobs:
             upsert_asset "$RID" "$DEB"
           done
 
-      # A release must not be able to make a claim its own CI silently dropped: v0.26.0's notes and
-      # docs-site said the patched gamescope was apt-installable while no .deb had ever been built,
-      # because every failure on this path was a `::warning::` that returned 0.
-      #
-      # ⚠ LAST step on purpose. The first version of this gate failed at the build step instead, and
-      # that skipped the host .deb's own publish + attach below — so the release kept the PREVIOUS
-      # tag commit's host .deb, which still carried the CAP_SYS_NICE postinst that breaks KDE. A
-      # gate protecting the release withheld the fix for it. Everything good ships first; the job
-      # goes red afterwards.
-      - name: A stable tag must ship the gamescope .deb
-        if: startsWith(gitea.ref, 'refs/tags/v')
+  # ---------------------------------------------------------------------------------------------
+  # `punktfunk-gamescope` for apt — the patched build that gives a gamescope session HDR, a cursor,
+  # and the client's real refresh rate instead of a hardcoded 60 Hz. Same reasoning as the RPM leg
+  # in rpm.yml: without a package, a Debian/Ubuntu box has no route to it except compiling by hand.
+  #
+  # ⚠ THIS IS ITS OWN JOB, ON DEBIAN 13, BECAUSE THE NOBLE BUILD COULD NEVER HAVE WORKED.
+  # It used to be a few best-effort steps inside build-publish-host (Ubuntu 24.04), where it failed
+  # every single time:
+  #     wlroots| Dependency wayland-server found: NO found 1.22.0 but need: '>=1.23.1'
+  # Our pin vendors wlroots 0.19.3, which floors wayland-server at 1.23.1; noble ships 1.22.0 and
+  # always will. v0.26.0 AND v0.27.0 both shipped with no gamescope .deb — while the release notes
+  # and docs-site told apt users to install it — because every rung of that path was a `::warning::`
+  # that returned 0, and the one hard gate ran last by design (so good artifacts still publish) and
+  # was simply never acted on. Moving it to trixie makes the build possible; making it a job of its
+  # own makes its failure visible instead of a footnote in someone else's log.
+  #
+  # Debian 13 is the OLDEST apt distro the tree configures on (wayland 1.23.1, libxcb-errors,
+  # libdisplay-info 0.2). The binary it produces needs GLIBC_2.38 and links no libstdc++, so what
+  # actually bounds it is wayland: Debian 13 and Ubuntu 26.04 YES, Ubuntu 24.04 NO — and 24.04
+  # could not run this binary however it was built, so nothing was lost by leaving noble.
+  build-publish-gamescope:
+    runs-on: ubuntu-24.04
+    container:
+      image: 192.168.1.58:5010/punktfunk-gamescope-trixie:latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      # Byte-identical to the other jobs' version step (pf-version.sh is deterministic per commit)
+      # — but only DISTRIBUTION is used here. The package version is the gamescope upstream
+      # version + our patch level, which build-gamescope-deb.sh derives itself; it deliberately
+      # does NOT follow the punktfunk version line, because this package moves on its own cadence.
+      - name: Channel
         run: |
-          shopt -s nullglob
-          built=(dist/punktfunk-gamescope_*.deb)
-          if [ ${#built[@]} -eq 0 ]; then
-            echo "::error::no punktfunk-gamescope .deb was built — a stable tag must not ship without it (the release notes and docs-site say it is apt-installable). Everything else in this job published normally; see the gamescope build step above for the meson error."
-            exit 1
-          fi
-          echo "gamescope .deb present: ${built[*]}"
+          git config --global --add safe.directory "$PWD"
+          case "$GITHUB_REF" in
+            refs/tags/v*) DIST=stable ;;
+            *)            DIST=canary ;;
+          esac
+          echo "DISTRIBUTION=$DIST" >> "$GITHUB_ENV"
+          echo "gamescope -> apt distribution '$DIST'"
+
+      # CACHED on packaging/gamescope/** alone — it depends on nothing else in this repo, so a
+      # normal push restores a binary instead of spending ~10 minutes on someone else's tree.
+      # Keyed `-trixie-` so the noble cache entries (which only ever held misses) can't be hit.
+      - uses: actions/cache@v4
+        id: gamescope
+        with:
+          path: gs-cache
+          key: punktfunk-gamescope-trixie-${{ hashFiles('packaging/gamescope/**') }}
+
+      # NOT best-effort, unlike the noble version of this step. Every dependency now comes from the
+      # image (which asserts the wayland floor at build time), so a failure here is a real
+      # regression in the tree or the pin — exactly the thing the previous arrangement hid.
+      - name: Build the patched gamescope
+        if: steps.gamescope.outputs.cache-hit != 'true'
+        # `--extra-fallback libdisplay-info` is what makes ONE .deb serve both Debian 13 and
+        # Ubuntu 26.04. Built against the distro's copy, the package picks up
+        # `Depends: libdisplay-info2 (>= 0.2.0)` on trixie — and Ubuntu 26.04 carries
+        # libdisplay-info **3** (0.3.0), so apt refuses it there ("Depends libdisplay-info2 …" —
+        # measured, not predicted). gamescope vendors the library as a submodule, so linking the
+        # vendored copy drops the dependency entirely. Same reasoning the build script already
+        # applies to wlroots: a binary we SHIP must not follow the build host's shared libraries.
+        run: |
+          bash packaging/gamescope/build-punktfunk-gamescope.sh \
+            --destdir "$PWD/gs-stage" --prefix /usr --jobs "$(nproc)" \
+            --extra-fallback libdisplay-info
+          # The WHOLE staged tree, not just the binary: it also carries the Vulkan WSI layer built
+          # beside the compositor, which is the only route to an HDR10 swapchain for a nested game.
+          mkdir -p gs-cache && cp -a gs-stage/. gs-cache/
+
+      # The binary must RUN, not merely link: `--version` is what the old job used as its ship
+      # gate, and it is the cheapest proof that the static-libstdc++ trick and the vendored wlroots
+      # actually produced a working compositor.
+      - name: Build the .deb
+        run: |
+          gs-cache/usr/bin/punktfunk-gamescope --version
+          bash packaging/debian/build-gamescope-deb.sh --stage gs-cache
+
+      - name: Publish to the Gitea apt registry
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          for DEB in dist/punktfunk-gamescope_*.deb; do
+            echo "uploading $DEB"
+            NAME=$(dpkg-deb -f "$DEB" Package)
+            VER=$(dpkg-deb -f "$DEB" Version)
+            ARCH=$(dpkg-deb -f "$DEB" Architecture)
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+              "https://$REGISTRY/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/$NAME/$VER/$ARCH" || true
+            curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$DEB" \
+              "https://$REGISTRY/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/upload"
+          done
+          echo "published gamescope to $OWNER/debian $DISTRIBUTION/$COMPONENT"
+
+      - name: Attach the gamescope .deb to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          for DEB in dist/punktfunk-gamescope_*.deb; do
+            upsert_asset "$RID" "$DEB"
+          done
 
   # ---------------------------------------------------------------------------------------------
   # The aarch64 CLIENT .deb. Cross-compiled on the ordinary amd64 runner in the
@@ -476,14 +572,14 @@ jobs:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
+      #
+      # NOTE this job deliberately sets no CC_x86_64_unknown_linux_gnu: the cross image already
+      # points it at /usr/local/bin/pf-host-cc, which is what keeps ffmpeg-sys-next's HOST probe
+      # from picking up arm64 include dirs. The target-side compiles go through
+      # CC_aarch64_unknown_linux_gnu (also set by the image) and are not sccache-wrapped.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       # Byte-identical to build-publish's version step (pf-version.sh is deterministic per
       # commit), so the arm64 package always shares the amd64 version line.
@@ -520,8 +616,13 @@ jobs:
           path: target
           # Its OWN key — these are aarch64 artifacts under target/aarch64-unknown-linux-gnu/
           # and must never share the amd64 jobs' target cache.
-          key: cargo-target-arm64-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-target-arm64-v1-${{ env.rustc }}-
+          #
+          # `-release-`: this key was previously identical to ci.yml's `rust-arm64` key, which
+          # builds DEBUG (clippy) and finishes in ~1.5 min against this job's ~5. Exactly the
+          # amd64 collision described on the release key above — ci.yml won every save, this job
+          # restored a tree with no release artifacts and could never persist its own.
+          key: cargo-target-arm64-release-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-arm64-release-v1-${{ env.rustc }}-
 
       - name: Build the arm64 client .deb
         env:
@@ -534,6 +635,10 @@ jobs:
           readelf -h target/aarch64-unknown-linux-gnu/release/punktfunk-session \
             | grep -q AArch64 || { echo "ERROR: session binary is not AArch64"; exit 1; }
 
+      - name: sccache stats (visibility only)
+        if: always()
+        run: sccache --show-stats
+
       - name: Publish to the Gitea apt registry
         env:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
@@ -560,3 +665,57 @@ jobs:
           for DEB in dist/*.deb; do
             upsert_asset "$RID" "$DEB"
           done
+
+  # ---------------------------------------------------------------------------------------------
+  # Does the thing we just published actually INSTALL? Nothing in this repo asked that before, and
+  # the cost of not asking was two independent, long-lived facts nobody knew:
+  #   * `punktfunk-host` has installed cleanly on Debian 13 for a long time — while docs-site said
+  #     "Debian isn't a supported target … nobody has verified it".
+  #   * `punktfunk-gamescope` was missing from apt entirely across two releases.
+  # Both are exactly what a five-minute install check catches, so it is now a job.
+  #
+  # It runs on the RUNNER (no `container:`) and drives docker directly — the same access
+  # docker.yml's image builds use — because the check must happen in a pristine distro image, not
+  # in a builder image with the deps already present.
+  #
+  # It installs FROM THE REGISTRY, after the publish jobs, rather than from a local .deb: that
+  # exercises the real path a user takes (repo key, apt distribution, dependency resolution against
+  # the distro's own package set), and it matches this workflow's established order — publish the
+  # good artifacts first, go red afterwards, never let a gate withhold a shipping fix.
+  smoke-install:
+    needs: [build-publish, build-publish-host, build-publish-gamescope]
+    # `needs` for ORDER only — this must still run when a builder went red, or the failure that
+    # matters most (a package that did not publish) is exactly the one that skips its own check and
+    # leaves the run looking merely "partly red" instead of saying what a user would hit.
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      # Recomputes the SAME version string the builder jobs stamped — pf-version.sh is
+      # deterministic per commit and GITHUB_RUN_NUMBER is shared across a run's jobs — so the check
+      # below can insist the registry is serving THIS run's build. Without that, a smoke job that
+      # beats the index regeneration installs the previous build, passes, and proves nothing.
+      - name: Channel + expected version
+        run: |
+          git config --global --add safe.directory "$PWD"
+          eval "$(bash scripts/ci/pf-version.sh)"
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; DIST=stable ;;
+            *)            V="${PF_BASE}~ci${GITHUB_RUN_NUMBER}.g${SHORT}"; DIST=canary ;;
+          esac
+          echo "DISTRIBUTION=$DIST" >> "$GITHUB_ENV"
+          echo "EXPECT_VERSION=$V" >> "$GITHUB_ENV"
+          echo "expecting $V in apt distribution '$DIST'"
+
+      # The support matrix, asserted rather than asserted-in-prose. Each row names the packages
+      # that MUST install on that distro; anything absent from the row is expected not to and is
+      # not checked here (the client's glibc 2.43 floor keeps it off 24.04 and Debian 13 —
+      # see docs-site/content/docs/debian.md).
+      - name: Install from the apt registry on every supported distro
+        run: bash scripts/ci/deb-install-smoke.sh
+        env:
+          PF_APT_DISTRIBUTION: ${{ env.DISTRIBUTION }}
+          PF_EXPECT_VERSION: ${{ env.EXPECT_VERSION }}

.gitea/workflows/docker.yml

@@ -96,6 +96,12 @@ jobs:
           # (rust-ci's 26.04 build is uninstallable there). Consumed by deb.yml's build-publish-host job.
           - image: punktfunk-rust-ci-noble
             dockerfile: ci/rust-ci-noble.Dockerfile
+          # Debian 13 gamescope builder. The gamescope .deb used to be built in the noble image
+          # and NEVER once succeeded there — noble's wayland is 1.22.0 and the vendored wlroots
+          # 0.19.3 floors it at 1.23.1, so two releases shipped without the package. trixie is the
+          # oldest apt distro the tree configures on. Consumed by deb.yml's build-publish-gamescope.
+          - image: punktfunk-gamescope-trixie
+            dockerfile: ci/gamescope-trixie.Dockerfile
           - image: punktfunk-fedora-rpm
             dockerfile: ci/fedora-rpm.Dockerfile
           # Fedora 44 builder (Fedora KDE spin): same Dockerfile, newer base → libavcodec.so.62.

.gitea/workflows/flatpak.yml

@@ -7,7 +7,7 @@
 # Gitea has NO flatpak/ostree registry, so the bundle lives in the generic registry:
 #   PUT  https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/<version>/<file>
 #   GET  https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/<version>/<file>
-# On tags the bundle is ALSO attached to the Gitea release (mirrors release.yml's DMG).
+# On tags the bundle is ALSO attached to the Gitea release (mirrors apple.yml's DMG).
 #
 # PRIVILEGED-BUILD CONSTRAINT: flatpak-builder runs bubblewrap, which needs user namespaces.
 # In a Gitea/act_runner Docker executor that means the job container must be --privileged
@@ -37,7 +37,7 @@ on:
     # binary's dependency closure must be listed here — including the native decode rungs, or a
     # commit that only touches the decoder never rebuilds the bundle and the Deck canary quietly
     # stops tracking it. pf-dxvadec is absent on purpose: it is `cfg(windows)` in pf-client-core
-    # and never enters the Linux closure (windows.yml / windows-msix.yml carry it instead).
+    # and never enters the Linux closure (windows-client.yml carries it instead).
     paths:
       - 'clients/linux/**'
       - 'clients/session/**'

.gitea/workflows/linux-client-screenshots.yml

@@ -29,6 +29,12 @@ env:
   SCCACHE_REGION: home-central
   AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # The C/C++ half of the cache — same wiring as ci.yml/deb.yml. Safe at workflow level: no
+  # cross-compiling job here.
+  CMAKE_C_COMPILER_LAUNCHER: sccache
+  CMAKE_CXX_COMPILER_LAUNCHER: sccache
+  CC_x86_64_unknown_linux_gnu: sccache cc
+  CXX_x86_64_unknown_linux_gnu: sccache c++
   # sccache and incremental compilation are mutually exclusive; CI wants the shared
   # cache, dev boxes keep incremental.
   CARGO_INCREMENTAL: "0"
@@ -45,14 +51,9 @@ jobs:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       # Client link deps (baked into the image; kept here so the job is green across image
       # rebuilds — a no-op once present) PLUS the headless-render extras: a virtual X server,
@@ -67,7 +68,8 @@ jobs:
             libgl1-mesa-dri mesa-vulkan-drivers \
             adwaita-icon-theme fonts-cantarell fonts-dejavu-core
 
-      # Reuse the workspace cargo caches (same keys as ci.yml/deb.yml).
+      # Reuse the workspace cargo caches. The cargo-home (download) cache is shared verbatim —
+      # it is profile-independent.
       - name: Cache keys
         run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
       - uses: actions/cache@v4
@@ -80,8 +82,20 @@ jobs:
       - uses: actions/cache@v4
         with:
           path: target
-          key: cargo-target-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-target-v3-${{ env.rustc }}-
+          # This job builds RELEASE (see the build step) in the same image and target layout as
+          # deb.yml's `build-publish`, so it wants THAT tree — it used to name ci.yml's key, which
+          # holds a debug build and gave it nothing. (Third participant in the collision documented
+          # on ci.yml's `cargo-target-debug-v3-` key.)
+          #
+          # Its OWN exact key with deb's prefix as a FALLBACK restore-key, deliberately: both
+          # workflows run on a v* tag, and an exact-key match would make them race for the single
+          # save slot — this job builds one crate, so if it won that race it would replace deb's
+          # full release tree with a nearly empty one for the rest of the lockfile's life. This way
+          # it always READS the warm tree and never blocks the job that fills it.
+          key: cargo-target-shots-release-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            cargo-target-shots-release-v1-${{ env.rustc }}-
+            cargo-target-release-v3-${{ env.rustc }}-
 
       - name: Build client
         run: cargo build --release -p punktfunk-client-linux --locked

.gitea/workflows/release.yml

@@ -1,555 +0,0 @@
-# Production Apple client builds — runs on the macos-arm64 runner (home-mac-mini-1).
-#
-#   Tag v* (or workflow_dispatch):
-#     macOS (Developer ID) -> sandboxed, signed, notarized + stapled .dmg, attached to a
-#               Gitea release on tag pushes
-#     macOS (App Store)    -> archive + upload to TestFlight (App Store Connect)
-#     iOS    -> archive + upload straight to TestFlight (App Store Connect)
-#     tvOS   -> archive + upload to TestFlight (Rust core built from tier-3 targets,
-#               nightly -Zbuild-std, in build-xcframework.sh)
-#
-# One App Store listing for all platforms (universal purchase): every target shares the
-# bundle ID io.unom.punktfunk.
-#
-# The macOS app is App-SANDBOXED for both channels (Config/Punktfunk-macOS.entitlements —
-# app-sandbox + network client/server + audio-input + bluetooth/usb device access; the
-# shared Config/Punktfunk.entitlements stays iOS/tvOS-only, where app-sandbox is invalid).
-# The Developer ID DMG is codesigned with the SAME macOS entitlements as the App Store build,
-# BUT it must ALSO embed a Developer ID provisioning profile: keychain-access-groups is a
-# MANAGED entitlement that AMFI only honors when an embedded profile authorizes it. A DMG
-# without one is SIGKILLed at spawn ("Launchd job spawn failed", POSIX errno 163) even though
-# it is validly signed AND notarized. ⌘R hides this (Xcode embeds a development profile); the
-# raw Developer ID codesign path does NOT, so ⌘R is NOT equivalent to the shipped DMG here.
-#
-# macOS App Store prerequisites (one-time, Apple portal — NOT done by this workflow; the
-# step is continue-on-error until they exist):
-#   * App Store Connect: add the macOS platform to the io.unom.punktfunk app record
-#     (universal purchase).
-#   * A "Punktfunk macOS App Store Distribution" provisioning profile installed on the
-#     runner (under ~/Library/Developer/Xcode/UserData/Provisioning Profiles/).
-#   * The "3rd Party Mac Developer Installer" (Mac Installer Distribution) certificate in
-#     the runner's login keychain, in addition to "Apple Distribution" — the App Store
-#     .pkg is installer-signed with it.
-#
-# macOS Developer ID (DMG) prerequisite (one-time, Apple portal — the DMG step embeds it):
-#   * A "Punktfunk macOS Developer ID" provisioning profile (Distribution -> Developer ID,
-#     App ID io.unom.punktfunk, with the Keychain Sharing capability) installed on the runner
-#     under ~/Library/Developer/Xcode/UserData/Provisioning Profiles/. It authorizes the
-#     managed keychain-access-groups entitlement; without it the DMG is SIGKILLed at launch
-#     (errno 163). If it is missing the DMG step warns and strips that entitlement (the app
-#     then uses ClientIdentityStore's legacy file-keychain fallback) so the build still ships
-#     a launchable app.
-#
-# Signing setup (NOT secret-based anymore): the runner is a LaunchAgent in the user's
-# logged-in Aqua session, so it uses the **login keychain** directly. Install the signing
-# identities there once via Xcode (Settings -> Accounts -> Manage Certificates): Developer
-# ID Application + Apple Distribution, with the WWDR intermediate present (so they show as
-# *valid*). xcodebuild/codesign then sign exactly like a local build — no throwaway keychain.
-# One-time, to avoid headless "codesign wants to use the key" prompts, grant codesign access:
-#   security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k <login-pw> \
-#     ~/Library/Keychains/login.keychain-db
-#
-# Secrets: only ASC_API_KEY_P8 / ASC_API_KEY_ID / ASC_API_ISSUER_ID (App Store Connect API
-# key — notarization, TestFlight upload, automatic-signing profile fetch).
-#
-# Needs a RELEASE Xcode on the runner (App Store rejects beta-SDK builds); the workflow
-# picks the first non-beta /Applications/Xcode*.app and only falls back to a beta with a
-# loud warning.
-name: release
-# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
-# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
-# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
-# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-
-on:
-  push:
-    # Canary: a relevant main push uploads the iOS + macOS + tvOS builds to TestFlight (Apple's
-    # own canary channel) — no notarized DMG (that's stable-only; see the per-step gates).
-    # Heavy on the shared mac-mini runner, so paths-filtered; the TestFlight steps are
-    # continue-on-error until the App Store Connect record exists, so this no-ops until then.
-    branches: [main]
-    paths:
-      - 'clients/apple/**'
-      - 'crates/punktfunk-core/**'
-      - 'scripts/build-xcframework.sh'
-      - 'Cargo.lock'
-      - '.gitea/workflows/release.yml'
-    # Stable: a `vX.Y.Z` tag is THE release — notarized DMG attached to the unified Gitea Release
-    # + macOS/iOS/tvOS to TestFlight for manual promotion to the App Store.
-    tags: ['v*']
-  workflow_dispatch:
-    inputs:
-      testflight:
-        description: "Upload the iOS build to TestFlight (true/false)"
-        required: false
-        default: "true"
-
-# Shared compile cache: sccache -> RustFS S3 (storage.unom.io — the mini resolves it via
-# the router, i.e. the hairpin path whose TLS always validated). Covers every cargo/rustc
-# invocation build-xcframework.sh makes, incl. the tvOS -Zbuild-std std builds; the Swift
-# side stays on DerivedData (sccache doesn't cache swiftc).
-env:
-  RUSTC_WRAPPER: sccache
-  SCCACHE_BUCKET: unom-ci-sccache
-  SCCACHE_ENDPOINT: https://storage.unom.io
-  SCCACHE_REGION: home-central
-  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
-  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
-  # sccache and incremental compilation are mutually exclusive; the shared cache makes the
-  # runner's persistent target/ disposable instead of precious.
-  CARGO_INCREMENTAL: "0"
-
-jobs:
-  apple:
-    runs-on: macos-arm64
-    timeout-minutes: 120
-    env:
-      TEAM_ID: F4H37KF6WC
-      PROJECT: clients/apple/Punktfunk.xcodeproj
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Select release Xcode
-        run: |
-          DEV_DIR=""
-          for app in /Applications/Xcode.app /Applications/Xcode_*.app /Applications/Xcode-*.app; do
-            case "$app" in *beta*|*Beta*) continue;; esac
-            [ -x "$app/Contents/Developer/usr/bin/xcodebuild" ] && DEV_DIR="$app/Contents/Developer" && break
-          done
-          if [ -z "$DEV_DIR" ]; then
-            for app in /Applications/Xcode*.app; do
-              [ -x "$app/Contents/Developer/usr/bin/xcodebuild" ] && DEV_DIR="$app/Contents/Developer" && break
-            done
-            echo "::warning::No release Xcode found — using $DEV_DIR. TestFlight/App Store REJECTS beta-SDK builds."
-          fi
-          [ -n "$DEV_DIR" ] || { echo "no usable Xcode found" >&2; exit 1; }
-          # Scoped to xcodebuild steps only (XCODE_DEV_DIR, not DEVELOPER_DIR): cargo must
-          # keep the system-default linker — a newer-than-OS Xcode's ld produces dylibs the
-          # running dyld rejects, killing proc-macro loads (see build-xcframework.sh).
-          echo "XCODE_DEV_DIR=$DEV_DIR" >> "$GITHUB_ENV"
-          DEVELOPER_DIR="$DEV_DIR" xcodebuild -version
-
-      - name: Version from tag
-        run: |
-          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE, PF_CHANNEL, PF_STABLE_TAG (single source of truth)
-          case "$GITHUB_REF" in
-            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; V="${V%%-*}" ;;  # App Store marketing version is numeric X.Y.Z (drop -rc)
-            *)            V="$PF_BASE" ;;                             # canary marketing version = one minor ahead of the latest stable tag; the build number disambiguates
-          esac
-          echo "VERSION=$V" >> "$GITHUB_ENV"
-          echo "BUILD_NUM=$GITHUB_RUN_NUMBER" >> "$GITHUB_ENV"
-          echo "version $V build $GITHUB_RUN_NUMBER (channel $PF_CHANNEL, latest stable ${PF_STABLE_TAG})"
-
-      - name: Rust toolchain (mac + iOS + tvOS slices)
-        run: |
-          RUSTUP="$(command -v rustup || echo "$HOME/.cargo/bin/rustup")"
-          dirname "$RUSTUP" >> "$GITHUB_PATH"
-          "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
-            aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
-          # tvOS targets are tier-3 (no prebuilt std) — build-xcframework.sh compiles them with
-          # nightly + -Zbuild-std, so ensure nightly + rust-src are present.
-          "$RUSTUP" toolchain install nightly --profile minimal
-          "$RUSTUP" component add rust-src --toolchain nightly
-
-      # The in-core Opus decode (surround) pulls audiopus_sys, which builds a vendored static libopus
-      # via CMake — keep the xcframework self-contained (no runtime libopus.dylib on end-user devices).
-      - name: CMake (for the vendored libopus audiopus_sys builds)
-        run: |
-          # Runner steps run with `bash --noprofile --norc`, so Homebrew's bin dir isn't on PATH —
-          # locate brew explicitly, install cmake if missing, and export its bin dir to GITHUB_PATH so
-          # the xcframework build step (audiopus_sys → vendored libopus) finds `cmake`.
-          for B in /opt/homebrew/bin/brew /usr/local/bin/brew; do [ -x "$B" ] && BREW="$B" && break; done
-          if [ -z "$BREW" ]; then echo "::error::Homebrew not found on the runner"; exit 1; fi
-          BREW_BIN="$(dirname "$BREW")"; export PATH="$BREW_BIN:$PATH"
-          command -v cmake >/dev/null || "$BREW" install cmake
-          echo "$BREW_BIN" >> "$GITHUB_PATH"
-          # Homebrew's CMake 4 dropped compatibility with the vendored libopus's pre-3.5
-          # `cmake_minimum_required`; treat 3.5 as the policy minimum (the cmake crate's child cmake
-          # inherits this from the env during the xcframework build).
-          echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"
-
-      # Shared compile cache. ~/.local/bin is on the runner daemon's PATH; GITHUB_PATH is
-      # belt-and-braces. bsdtar (macOS) globs by default — no --wildcards.
-      - name: sccache (self-healing install)
-        run: |
-          if ! command -v sccache >/dev/null; then
-            mkdir -p "$HOME/.local/bin"
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-aarch64-apple-darwin.tar.gz \
-              | tar -xz --strip-components=1 -C "$HOME/.local/bin" '*/sccache'
-          fi
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-          sccache --version
-
-      - name: Pin + prune Xcode DerivedData
-        # Without -derivedDataPath, xcodebuild derives its DerivedData directory name from the
-        # PROJECT'S ABSOLUTE PATH — and act_runner rotates its workspace
-        # (~/.cache/act/<hash>/hostexecutor), so each rotation minted a brand new ~760 MB tree
-        # under ~/Library that nothing ever collected. 31 of them piled up in three days
-        # (~32 GB with the shared ModuleCache), filled the runner's boot volume, and failed
-        # v0.16.0's xcframework build with "No space left on device". Pinning one path makes the
-        # tree REUSED instead of multiplied — it also keeps the module cache warm between runs.
-        run: |
-          DD="$HOME/ci/derived-data/release"
-          mkdir -p "$DD"
-          echo "DERIVED_DATA=$DD" >> "$GITHUB_ENV"
-          # Safety net for trees the pin does not own: the legacy per-path ones from before this
-          # change, and anything another job leaves in the default root. Untouched for a week ⇒ gone.
-          if [ -d "$HOME/Library/Developer/Xcode/DerivedData" ]; then
-            find "$HOME/Library/Developer/Xcode/DerivedData" -mindepth 1 -maxdepth 1 \
-              -mtime +7 -exec rm -rf {} + 2>/dev/null || true
-          fi
-          echo "disk after prune:"; df -h /System/Volumes/Data | tail -1
-
-      - name: Build PunktfunkCore.xcframework (mac + iOS + tvOS)
-        # tvOS is a tier-3 target (nightly -Zbuild-std): slow on the first build, then cached on
-        # the self-hosted runner. Built on canary too so the tvOS archive/upload below runs on the
-        # same track as iOS/macOS (the nightly toolchain is installed unconditionally above).
-        run: BUILD_IOS=1 BUILD_TVOS=1 bash scripts/build-xcframework.sh
-
-      - name: Stage App Store Connect API key
-        env:
-          ASC_P8: ${{ secrets.ASC_API_KEY_P8 }}
-        run: |
-          printf '%s' "$ASC_P8" > "$RUNNER_TEMP/asc.p8"
-          chmod 600 "$RUNNER_TEMP/asc.p8"
-
-      - name: macOS — archive, codesign Developer ID, notarize, DMG
-        # Stable releases only — the notarized DMG is a Gatekeeper/direct-download artifact, not
-        # relevant to TestFlight testers (the canary channel). Skipped on canary main pushes.
-        if: startsWith(gitea.ref, 'refs/tags/v')
-        run: |
-          # Archive UNSIGNED, then codesign with the Developer ID Application identity from the
-          # login keychain. Unsigned archive sidesteps Xcode's keychain-access-groups
-          # provisioning-profile gate at archive time; we re-assert that authorization below by
-          # EMBEDDING a Developer ID profile before codesign (see the keychain note further down).
-          # Bundle is a single static binary.
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
-            -project "$PROJECT" -scheme Punktfunk \
-            -destination 'generic/platform=macOS' \
-            -archivePath "$RUNNER_TEMP/Punktfunk-macos.xcarchive" \
-            -derivedDataPath "$DERIVED_DATA" \
-            -skipMacroValidation -skipPackagePluginValidation \
-            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
-            CODE_SIGNING_ALLOWED=NO
-          APP="$RUNNER_TEMP/Punktfunk-macos.xcarchive/Products/Applications/Punktfunk.app"
-          # Sandboxed Developer ID: sign with the SAME macOS entitlements the App Store build
-          # uses. codesign won't expand $(AppIdentifierPrefix) — resolve it to the team prefix.
-          RESOLVED="$RUNNER_TEMP/macos.entitlements"
-          sed "s/\$(AppIdentifierPrefix)/${TEAM_ID}./g" \
-            clients/apple/Config/Punktfunk-macOS.entitlements > "$RESOLVED"
-
-          # keychain-access-groups is a MANAGED (restricted) entitlement: App Sandbox and the
-          # network/device keys are self-asserted for Developer ID, but a keychain access group
-          # must be AUTHORIZED by an embedded provisioning profile. Without one, AMFI refuses to
-          # spawn the sandboxed process at launch — "Launchd job spawn failed" (POSIX errno 163),
-          # SIGKILL before main() — even though the bundle is validly signed and notarized. Embed
-          # a "Developer ID" distribution profile for io.unom.punktfunk (Keychain Sharing) so its
-          # entitlements authorize the access group, exactly like the App Store build's profile
-          # does. Located by profile Name among the profiles installed on the runner (see header).
-          DEVID_PROFILE_NAME="Punktfunk macOS Developer ID"
-          PROFILE_SRC=""
-          for p in "$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles/"*.provisionprofile \
-                   "$HOME/Library/MobileDevice/Provisioning Profiles/"*.provisionprofile; do
-            [ -e "$p" ] || continue
-            NAME=$(security cms -D -i "$p" 2>/dev/null | plutil -extract Name raw - 2>/dev/null || true)
-            [ "$NAME" = "$DEVID_PROFILE_NAME" ] && PROFILE_SRC="$p" && break
-          done
-          if [ -n "$PROFILE_SRC" ]; then
-            # Must land BEFORE codesign so it's sealed into the bundle.
-            cp "$PROFILE_SRC" "$APP/Contents/embedded.provisionprofile"
-            echo "embedded Developer ID profile: $PROFILE_SRC"
-          else
-            # Fallback so a missing/expired profile NEVER reships the errno-163 brick: drop the
-            # managed entitlement and let ClientIdentityStore fall back to the legacy file keychain
-            # (its errSecMissingEntitlement path). Degraded (one Keychain prompt) but launchable.
-            echo "::warning::Developer ID profile '$DEVID_PROFILE_NAME' not installed on the runner — stripping keychain-access-groups so the DMG still launches (legacy file keychain). Create it in the Apple portal + install it on the runner to restore the no-prompt data-protection keychain."
-            /usr/libexec/PlistBuddy -c "Delete :keychain-access-groups" "$RESOLVED" 2>/dev/null || true
-          fi
-
-          codesign --force --options runtime --timestamp \
-            --entitlements "$RESOLVED" \
-            --sign "Developer ID Application" "$APP"
-          codesign --verify --strict --verbose=2 "$APP"
-          # Notarized DMG.
-          STAGE="$RUNNER_TEMP/dmg-stage"
-          mkdir -p "$STAGE"
-          cp -R "$APP" "$STAGE/"
-          ln -s /Applications "$STAGE/Applications"
-          DMG="$RUNNER_TEMP/Punktfunk-$VERSION.dmg"
-          hdiutil create -volname "Punktfunk" -srcfolder "$STAGE" -ov -format UDZO "$DMG"
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcrun notarytool submit "$DMG" --wait \
-            --key "$RUNNER_TEMP/asc.p8" \
-            --key-id "${{ secrets.ASC_API_KEY_ID }}" \
-            --issuer "${{ secrets.ASC_API_ISSUER_ID }}"
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcrun stapler staple "$DMG"
-          echo "DMG=$DMG" >> "$GITHUB_ENV"
-
-      - name: Attach DMG to the Gitea release (stable tags only)
-        if: startsWith(gitea.ref, 'refs/tags/v')
-        env:
-          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-        run: |
-          . scripts/ci/gitea-release.sh
-          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
-          upsert_asset "$RID" "$DMG" "Punktfunk-$VERSION.dmg"
-
-      - name: macOS App Store — archive + upload to TestFlight
-        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
-        # Best-effort until the App Store Connect record has the macOS platform + the
-        # "Punktfunk macOS App Store Distribution" profile and the "3rd Party Mac Developer
-        # Installer" cert are on the runner (see the header). The macOS app is sandboxed
-        # (Config/Punktfunk-macOS.entitlements) — mandatory for the Mac App Store.
-        continue-on-error: true
-        run: |
-          # Separate archive from the Developer ID one above: App Store needs a signed, entitled
-          # archive that -exportArchive can re-sign for distribution, not the unsigned-then-codesign
-          # DMG path. Archive with AUTOMATIC signing (development). Why not a manually-specified
-          # profile (as this step used to do): the in-app license screens added a SwiftPM resource
-          # bundle (PunktfunkKit_PunktfunkKit), and a resource bundle is a product type that cannot
-          # carry a provisioning profile — a global PROVISIONING_PROFILE_SPECIFIER (here) or an
-          # sdk-scoped one (iOS/tvOS) lands on it and fails the archive ("does not support
-          # provisioning profiles"). Automatic signing assigns a profile only to the app and leaves
-          # the resource bundle (and the macOS-host macro plugins) alone, and bakes the sandbox
-          # entitlements in. -allowProvisioningUpdates lets Xcode sync the App ID capabilities and
-          # regenerate the managed *development* profile — needed because the App Groups capability
-          # (group.io.unom.punktfunk, in Config/Punktfunk-macOS.entitlements) invalidated the cached
-          # one. This is DEVELOPMENT signing against the Apple Development cert already in the
-          # keychain, so the App-Manager ASC key suffices. DISTRIBUTION signing happens in the export
-          # step below
-          # (manual, via the plist). Quit Xcode so it can't prune the manually-installed App Store
-          # distribution profile that export needs.
-          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
-          pkill -x Xcode 2>/dev/null || true
-          PROFILE="Punktfunk macOS App Store Distribution"
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
-            -project "$PROJECT" -scheme Punktfunk \
-            -destination 'generic/platform=macOS' \
-            -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
-            -derivedDataPath "$DERIVED_DATA" \
-            -skipMacroValidation -skipPackagePluginValidation \
-            -allowProvisioningUpdates \
-            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
-            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
-            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}" \
-            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
-            CODE_SIGN_STYLE=Automatic \
-            DEVELOPMENT_TEAM="$TEAM_ID"
-          cat > "$RUNNER_TEMP/export-macos-appstore.plist" <<EOF
-          <?xml version="1.0" encoding="UTF-8"?>
-          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-          <plist version="1.0">
-          <dict>
-            <key>method</key><string>app-store-connect</string>
-            <key>destination</key><string>upload</string>
-            <key>teamID</key><string>$TEAM_ID</string>
-            <key>signingStyle</key><string>manual</string>
-            <key>signingCertificate</key><string>Apple Distribution</string>
-            <key>installerSigningCertificate</key><string>3rd Party Mac Developer Installer</string>
-            <key>provisioningProfiles</key>
-            <dict><key>io.unom.punktfunk</key><string>$PROFILE</string></dict>
-          </dict>
-          </plist>
-          EOF
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
-            -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
-            -exportOptionsPlist "$RUNNER_TEMP/export-macos-appstore.plist" \
-            -exportPath "$RUNNER_TEMP/export-macos-appstore" \
-            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
-            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
-            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
-
-      - name: iOS — archive + upload to TestFlight
-        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
-        # Best-effort until the App Store Connect app record for io.unom.punktfunk exists.
-        continue-on-error: true
-        run: |
-          # Archive with AUTOMATIC signing (development) — see the macOS App Store step for the full
-          # rationale. The SwiftPM resource bundle (PunktfunkKit_PunktfunkKit, added with the in-app
-          # license screens) builds for iphoneos, so even the sdk-scoped PROVISIONING_PROFILE_SPECIFIER
-          # this step used to set matched it and failed the archive ("does not support provisioning
-          # profiles"). Automatic signing profiles only the app and leaves the resource bundle (and
-          # the macOS-host macro plugins) alone. -allowProvisioningUpdates lets Xcode sync the App ID
-          # capabilities and regenerate the managed *development* profiles for both io.unom.punktfunk
-          # AND the embedded io.unom.punktfunk.widgets — needed because adding the App Groups
-          # capability (group.io.unom.punktfunk, shared with the Widget/Live-Activity extension)
-          # invalidated the cached managed dev profile, which had no widgets profile at all. This is
-          # DEVELOPMENT signing against the Apple Development cert already in the keychain — no cert
-          # creation, so the App-Manager ASC key is sufficient (it only manages App IDs/dev profiles).
-          # DISTRIBUTION signing is the export step below (manual, via the plist) and is unaffected.
-          # A running Xcode.app prunes unrecognized profiles — quit it so the manually-installed
-          # App Store distribution profile survives for export.
-          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
-          pkill -x Xcode 2>/dev/null || true
-          PROFILE="Punktfunk iOS App Store Distribution"
-          # The embedded PunktfunkWidgetsExtension (bundle io.unom.punktfunk.widgets) is a second
-          # distribution artifact in the .ipa, so manual signing must map its App ID to its own
-          # App Store profile too — else exportArchive fails ("no profile for io.unom.punktfunk.widgets").
-          WIDGET_PROFILE="Punktfunk iOS Widgets App Store Distribution"
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
-            -project "$PROJECT" -scheme Punktfunk-iOS \
-            -destination 'generic/platform=iOS' \
-            -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
-            -derivedDataPath "$DERIVED_DATA" \
-            -skipMacroValidation -skipPackagePluginValidation \
-            -allowProvisioningUpdates \
-            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
-            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
-            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}" \
-            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
-            CODE_SIGN_STYLE=Automatic \
-            DEVELOPMENT_TEAM="$TEAM_ID"
-          cat > "$RUNNER_TEMP/export-appstore.plist" <<EOF
-          <?xml version="1.0" encoding="UTF-8"?>
-          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-          <plist version="1.0">
-          <dict>
-            <key>method</key><string>app-store-connect</string>
-            <key>destination</key><string>upload</string>
-            <key>teamID</key><string>$TEAM_ID</string>
-            <key>signingStyle</key><string>manual</string>
-            <key>signingCertificate</key><string>Apple Distribution</string>
-            <key>provisioningProfiles</key>
-            <dict>
-              <key>io.unom.punktfunk</key><string>$PROFILE</string>
-              <key>io.unom.punktfunk.widgets</key><string>$WIDGET_PROFILE</string>
-            </dict>
-          </dict>
-          </plist>
-          EOF
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
-            -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
-            -exportOptionsPlist "$RUNNER_TEMP/export-appstore.plist" \
-            -exportPath "$RUNNER_TEMP/export-appstore" \
-            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
-            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
-            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
-
-      - name: iOS — export .ipa (Gitea release + run artifact)
-        # The TestFlight step above uploads straight to App Store Connect (destination=upload) and
-        # leaves NO .ipa on disk. Re-export the SAME archive with destination=export to get an
-        # App Store distribution-signed .ipa for the Gitea release + the run artifacts. Same gate as
-        # that archive; a warn+skip (never fails the best-effort iOS leg) if the archive is absent,
-        # e.g. a workflow_dispatch with testflight=false. NOTE: an App Store-signed .ipa installs
-        # only via TestFlight/App Store, not by direct sideload — it's a release/archival artifact.
-        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
-        id: ios_ipa
-        run: |
-          ARCHIVE="$RUNNER_TEMP/Punktfunk-ios.xcarchive"
-          if [ ! -d "$ARCHIVE" ]; then
-            echo "::warning::iOS archive not found — skipping .ipa export"
-            exit 0
-          fi
-          PROFILE="Punktfunk iOS App Store Distribution"
-          WIDGET_PROFILE="Punktfunk iOS Widgets App Store Distribution"
-          # destination=export writes the .ipa to -exportPath; otherwise identical manual signing to
-          # the upload plist (both profiles, Apple Distribution). No ASC key needed — no network.
-          cat > "$RUNNER_TEMP/export-appstore-ipa.plist" <<EOF
-          <?xml version="1.0" encoding="UTF-8"?>
-          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-          <plist version="1.0">
-          <dict>
-            <key>method</key><string>app-store-connect</string>
-            <key>destination</key><string>export</string>
-            <key>teamID</key><string>$TEAM_ID</string>
-            <key>signingStyle</key><string>manual</string>
-            <key>signingCertificate</key><string>Apple Distribution</string>
-            <key>provisioningProfiles</key>
-            <dict>
-              <key>io.unom.punktfunk</key><string>$PROFILE</string>
-              <key>io.unom.punktfunk.widgets</key><string>$WIDGET_PROFILE</string>
-            </dict>
-          </dict>
-          </plist>
-          EOF
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
-            -archivePath "$ARCHIVE" \
-            -exportOptionsPlist "$RUNNER_TEMP/export-appstore-ipa.plist" \
-            -exportPath "$RUNNER_TEMP/export-ipa"
-          SRC=$(ls "$RUNNER_TEMP/export-ipa/"*.ipa 2>/dev/null | head -1)
-          [ -n "$SRC" ] || { echo "::warning::no .ipa was produced by export"; exit 0; }
-          mkdir -p "$GITHUB_WORKSPACE/dist"
-          IPA="$GITHUB_WORKSPACE/dist/Punktfunk-$VERSION.ipa"
-          mv "$SRC" "$IPA"
-          echo "IPA=$IPA" >> "$GITHUB_ENV"
-          echo "ipa=dist/Punktfunk-$VERSION.ipa" >> "$GITHUB_OUTPUT"
-          echo "exported $IPA"
-
-      - name: Attach .ipa to the workflow run
-        if: steps.ios_ipa.outputs.ipa != ''
-        # v3, not v4: Gitea's artifact backend identifies as GHES, which upload-artifact@v4 refuses
-        # (same reason as android.yml / apple.yml). Download is a zip of the .ipa.
-        uses: actions/upload-artifact@v3
-        with:
-          name: punktfunk-ios-ipa
-          path: ${{ steps.ios_ipa.outputs.ipa }}
-          if-no-files-found: warn
-          retention-days: 30
-
-      - name: Attach .ipa to the Gitea release (stable tags only)
-        if: startsWith(gitea.ref, 'refs/tags/v') && steps.ios_ipa.outputs.ipa != ''
-        env:
-          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-        run: |
-          . scripts/ci/gitea-release.sh
-          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
-          upsert_asset "$RID" "$IPA" "Punktfunk-$VERSION.ipa"
-
-      - name: tvOS — archive + upload to TestFlight
-        # Canary + stable, the same track as iOS/macOS — the tvOS xcframework slice is now built
-        # on every apple push (above), so this matches the iOS step's gate exactly.
-        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
-        # Needs tvOS added to the App Store Connect app record + the tvOS platform installed
-        # on the runner (xcodebuild -downloadPlatform tvOS).
-        continue-on-error: true
-        run: |
-          # Archive with AUTOMATIC signing (development) — see the macOS App Store step. The SwiftPM
-          # resource bundle (PunktfunkKit_PunktfunkKit) builds for appletvos and rejected the
-          # sdk-scoped profile this step used to set; Automatic signing profiles only the app and
-          # leaves the resource bundle + the macOS-host macro plugins (OnceMacro/SwizzlingMacro/
-          # AssociationMacro) alone. -allowProvisioningUpdates lets Xcode sync the App ID capabilities
-          # and regenerate the managed *development* profile — the tvOS app carries the App Groups key
-          # (group.io.unom.punktfunk) too, which invalidated the cached one. DEVELOPMENT signing against
-          # the Apple Development cert already in the keychain, so the App-Manager ASC key suffices.
-          # DISTRIBUTION signing is the export step below (manual, plist).
-          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
-          pkill -x Xcode 2>/dev/null || true
-          PROFILE="Punktfunk tvOS App Store Distribution"
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
-            -project "$PROJECT" -scheme Punktfunk-tvOS \
-            -destination 'generic/platform=tvOS' \
-            -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
-            -derivedDataPath "$DERIVED_DATA" \
-            -skipMacroValidation -skipPackagePluginValidation \
-            -allowProvisioningUpdates \
-            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
-            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
-            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}" \
-            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
-            CODE_SIGN_STYLE=Automatic \
-            DEVELOPMENT_TEAM="$TEAM_ID"
-          cat > "$RUNNER_TEMP/export-tvos.plist" <<EOF
-          <?xml version="1.0" encoding="UTF-8"?>
-          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-          <plist version="1.0">
-          <dict>
-            <key>method</key><string>app-store-connect</string>
-            <key>destination</key><string>upload</string>
-            <key>teamID</key><string>$TEAM_ID</string>
-            <key>signingStyle</key><string>manual</string>
-            <key>signingCertificate</key><string>Apple Distribution</string>
-            <key>provisioningProfiles</key>
-            <dict><key>io.unom.punktfunk</key><string>$PROFILE</string></dict>
-          </dict>
-          </plist>
-          EOF
-          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
-            -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
-            -exportOptionsPlist "$RUNNER_TEMP/export-tvos.plist" \
-            -exportPath "$RUNNER_TEMP/export-tvos" \
-            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
-            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
-            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"

.gitea/workflows/rpm.yml

@@ -51,6 +51,14 @@ env:
   SCCACHE_REGION: home-central
   AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # The C/C++ half of the cache (aws-lc-sys, the vendored libopus, openh264's C++). Safe at
+  # workflow level here: unlike ci.yml/deb.yml this workflow has no cross-compiling job whose
+  # image sets its own CC_x86_64_unknown_linux_gnu. See ci.yml's `rust` job for that trap.
+  # This matters twice per push — the f43 and f44 legs are the two longest jobs in the fleet.
+  CMAKE_C_COMPILER_LAUNCHER: sccache
+  CMAKE_CXX_COMPILER_LAUNCHER: sccache
+  CC_x86_64_unknown_linux_gnu: sccache cc
+  CXX_x86_64_unknown_linux_gnu: sccache c++
   # sccache and incremental compilation are mutually exclusive; CI wants the shared
   # cache, dev boxes keep incremental.
   CARGO_INCREMENTAL: "0"
@@ -80,14 +88,9 @@ jobs:
       - uses: actions/checkout@v4
 
       # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
-      # images; this fetch keeps the job green while the running :latest predates the bake.
+      # images; this heals the job while the running :latest predates the bake.
       - name: sccache (no-op once the image bakes it)
-        run: |
-          command -v sccache >/dev/null 2>&1 || {
-            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
-              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
-          }
-          sccache --version
+        run: sh scripts/ci/ensure-sccache.sh
 
       # rpmbuild + git archive need the checkout trusted; cache the crates download.
       # The client link deps are also baked into the fedora-rpm image, but this job runs
@@ -145,11 +148,63 @@ jobs:
           echo "GROUP=$GROUP" >> "$GITHUB_ENV"
           echo "rpm $V-$R -> group '$GROUP'"
 
+      # ── The web console, built once per (web+sdk content, bun) instead of once per leg ─────────
+      # Two legs run here (f43 + f44) and each built its own identical copy of a bundle that is a
+      # pure function of web/ and sdk/ — see the fuller note in deb.yml, whose key family this
+      # shares, so whichever job builds it first warms the rest of the fleet.
+      #
+      # ⚠ The build has to happen HERE, in the workspace, rather than being left to the spec. Two
+      # reasons, and both are load-bearing:
+      #   * build-rpm.sh packages a `git archive` tarball and web/.output is gitignored, so a
+      #     bundle sitting in the workspace is invisible to rpmbuild — it must be handed over by
+      #     absolute path (PF_PREBUILT_WEB_OUTPUT -> the spec's pf_prebuilt_web macro).
+      #   * the reverse direction is worse: the spec builds into rpmbuild's %{_topdir}, which
+      #     build-rpm.sh creates with mktemp and removes on EXIT. A console built in there is gone
+      #     before actions/cache's post step runs, so the cache would never populate and every run
+      #     would be a miss that quietly rebuilt — the cache would look present and do nothing.
+      - name: Web console cache key
+        run: echo "bunver=$(bun --version 2>/dev/null || echo none)" >> "$GITHUB_ENV"
+      - name: Cache the built web console
+        id: webconsole
+        uses: actions/cache@v4
+        with:
+          path: web/.output
+          key: web-console-linux-bun${{ env.bunver }}-${{ hashFiles('web/**', 'sdk/**') }}
+
+      - name: Build the web console (cache miss only)
+        if: steps.webconsole.outputs.cache-hit != 'true'
+        run: |
+          cd web
+          bun install --frozen-lockfile --ignore-scripts
+          bun run build
+
+      # Same mandatory assertion as deb.yml — a missing or wrong-preset bundle must fail here, not
+      # become a quietly console-less RPM. The spec re-checks the marker on whatever it packages.
+      - name: The console must exist (cache hit or fresh build)
+        run: |
+          if [ ! -f web/.output/server/index.mjs ]; then
+            echo "::error::web/.output is missing — neither the cache restore nor the build produced it"
+            exit 1
+          fi
+          grep -q 'Bun\.serve' web/.output/server/index.mjs || {
+            echo "::error::web/.output is not a bun bundle (wrong nitro preset)"; exit 1; }
+          echo "web console present: $(du -sh web/.output | cut -f1)"
+
       - name: Build RPM
         # PF_WITH_WEB=1 / PF_WITH_SCRIPTING=1 → also build the punktfunk-web console + the
         # punktfunk-scripting runner subpackages (the publish loop globs them in; the host RPM
         # Recommends both). Both need bun (ensured in Prep).
-        run: PF_VERSION="$PF_VERSION" PF_RELEASE="$PF_RELEASE" PF_WITH_WEB=1 PF_WITH_SCRIPTING=1 bash packaging/rpm/build-rpm.sh
+        run: |
+          PF_VERSION="$PF_VERSION" PF_RELEASE="$PF_RELEASE" \
+            PF_WITH_WEB=1 PF_WITH_SCRIPTING=1 \
+            PF_PREBUILT_WEB_OUTPUT="$GITHUB_WORKSPACE/web/.output" \
+            bash packaging/rpm/build-rpm.sh
+
+      # Visibility only — the two RPM legs are the longest jobs in the fleet, so a cache
+      # regression here is the most expensive one to leave undetected.
+      - name: sccache stats (visibility only)
+        if: always()
+        run: sccache --show-stats
 
       # Signs with packages@unom.io (org secret) and self-verifies before publish. On a v* tag a
       # missing key FAILS the build rather than publishing unsigned RPMs into a gpgcheck=1 repo.
@@ -238,7 +293,11 @@ jobs:
           dnf -y install wayland-protocols-devel glm-devel cmake libXcursor-devel || true
           if bash packaging/gamescope/build-punktfunk-gamescope.sh \
                --destdir "$PWD/gs-stage" --prefix /usr --jobs "$(nproc)"; then
-            install -Dm0755 gs-stage/usr/bin/punktfunk-gamescope gs-cache/punktfunk-gamescope
+            # The WHOLE staged tree, not just the binary: it also carries the Vulkan WSI layer built
+            # beside the compositor, which is the only thing that can give a nested game an HDR10
+            # swapchain. Caching the tree rather than a file per artifact is what keeps the next
+            # addition from needing a change here as well as in every packaging script.
+            mkdir -p gs-cache && cp -a gs-stage/. gs-cache/
           else
             # Warn only, even on a tag — the hard gate is the LAST step of this job. Failing here
             # would skip the sysext build, the sysext feed, AND the release attach below, so a
@@ -256,9 +315,9 @@ jobs:
       # existing SDR/host-composited path. The spec re-checks the +pfhdr marker itself.
       - name: Package punktfunk-gamescope as an RPM
         run: |
-          if [ -x gs-cache/punktfunk-gamescope ] && gs-cache/punktfunk-gamescope --version >/dev/null 2>&1; then
+          if [ -x gs-cache/usr/bin/punktfunk-gamescope ] && gs-cache/usr/bin/punktfunk-gamescope --version >/dev/null 2>&1; then
             bash packaging/gamescope/build-gamescope-rpm.sh \
-              --binary gs-cache/punktfunk-gamescope \
+              --stage gs-cache \
               --release "$PF_RELEASE"
           else
             # Warn only — see the note on the build step. The gate is the last step of this job.
@@ -317,9 +376,9 @@ jobs:
           # whose runtime libs are missing from this container must cost the image its HDR, not the
           # image itself.
           gs=()
-          if [ -x gs-cache/punktfunk-gamescope ] && gs-cache/punktfunk-gamescope --version >/dev/null 2>&1; then
-            gs=(--gamescope gs-cache/punktfunk-gamescope)
-            echo "folding in $(gs-cache/punktfunk-gamescope --version 2>&1 | head -1)"
+          if [ -x gs-cache/usr/bin/punktfunk-gamescope ] && gs-cache/usr/bin/punktfunk-gamescope --version >/dev/null 2>&1; then
+            gs=(--gamescope-stage gs-cache)
+            echo "folding in $(gs-cache/usr/bin/punktfunk-gamescope --version 2>&1 | head -1)"
           else
             echo "::warning::no usable punktfunk-gamescope for f${{ matrix.fedver }} — the sysext ships without it (gamescope sessions stay SDR)"
           fi

.gitea/workflows/sbom.yml

@@ -67,7 +67,7 @@ jobs:
           . scripts/ci/gitea-release.sh
           RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
           upsert_asset "$RID" "$SBOM_FILE"
-      # v3, not v4: Gitea's artifact backend rejects upload-artifact@v4 (see release.yml).
+      # v3, not v4: Gitea's artifact backend rejects upload-artifact@v4 (see apple.yml).
       - name: Upload artifact (non-tag runs)
         if: "!startsWith(github.ref, 'refs/tags/')"
         uses: actions/upload-artifact@v3

.gitea/workflows/windows-client.yml

@@ -0,0 +1,334 @@
+# Windows CLIENT — build, lint, test and package, on a self-hosted windows-amd64 runner (host mode;
+# the generic runner + MSVC/WinUI toolchain come from unom/infra's windows-runner/, punktfunk's own
+# extras — WDK, Inno Setup, the ARM64 rustup target — self-provision via the "Ensure Windows
+# toolchain" step, a fast no-op once present, so any runner with that label works).
+#
+# Covers BOTH client binaries: the WinUI 3 shell (windows-reactor + WASAPI + SDL3) and the
+# punktfunk-session Vulkan client (pf-presenter/pf-client-core/pf-console-ui — every stream runs in
+# it, spawned by the shell), plus punktfunk-cli, whose `punktfunk.exe` alias the MSIX manifest
+# references.
+#
+# ⚠ WHY THIS IS ONE FILE. This was `windows.yml` (build+lint+test, DEBUG, x64 + arm64) and
+# `windows-msix.yml` (build+package, RELEASE, x64 + arm64) — four full compiles of the same crates
+# per client push, on ONE runner, from three copies of the same `paths:` list that had already
+# started to drift. windows-host.yml learned the hard way that debug trees on this machine are pure
+# liability: a second dep tree tips it into `cabac_decoder.cpp: fatal error C1069` building
+# openh264-sys2's vendored C++, which is disk/temp exhaustion, not a source error. So there is now
+# ONE release build per arch, and clippy/fmt/test run against it. Do not reintroduce a debug leg.
+#
+# Renamed from windows-msix.yml deliberately, and safely: `github.run_number` is REPO-WIDE in Gitea
+# (consecutive runs of DIFFERENT workflows get consecutive numbers), so the canary MSIX version
+# `<minor>.<run>.0` keeps climbing across the rename — on GitHub, where run_number is per-workflow,
+# this same rename would have reset it to 1 and made every canary sort below the published ones.
+#
+# Two architectures from ONE x64 runner: x86_64-pc-windows-msvc natively and aarch64-pc-windows-msvc
+# by cross-compiling. The x64 MSVC toolset ships an ARM64 cross compiler
+# (VC\Tools\MSVC\<ver>\bin\Hostx64\arm64\cl.exe) and aarch64-pc-windows-msvc is a tier-2 Rust target
+# with host tools, so no ARM64 runner is needed — the cc/cmake crates pick the ARM64 compiler from
+# the target triple (SDL3 + libopus build-from-source cross-compile fine). The one thing the aarch64
+# build can't do is *run* on the x64 host, so fmt + test run only for x64.
+#
+# ARM64 note: rust-skia publishes no aarch64-pc-windows-msvc prebuilt binaries, so the session builds
+# --no-default-features there (no Skia console UI; streaming is unaffected) — flip when
+# skia-binaries adds the target.
+#
+# NO FFmpeg here since M10 (design/client-native-decode.md §6): the client decodes with
+# pf-vkdecode / pf-dxvadec / openh264+rav1d and links no libav* at all, so this workflow sets
+# no FFMPEG_DIR, no PF_FFVK_VULKAN_INCLUDE and prepends nothing to PATH. The provisioning
+# script still fetches the FFmpeg trees because the HOST keeps FFmpeg — windows-host.yml's
+# `amf-qsv` leg link-imports them.
+#
+# The MSVC/WinUI toolchain (cargo/rustup on ASCII paths, NASM, CMake, LLVM, CARGO_HOME,
+# CMAKE_POLICY_VERSION_MINIMUM, …) is baked into the runner's daemon env. Per-checkout / per-arch
+# vars are set in a step:
+#   - CARGO_TARGET_DIR=C:\t…  the runner's host workdir is buried deep under
+#                          C:\Windows\System32\config\systemprofile\.cache\act\<hash>\hostexecutor\,
+#                          so the default target\ path blows past Windows' MAX_PATH (260) inside the
+#                          CMake-from-source builds (audiopus_sys / SDL3) — MSBuild's tracker then
+#                          can't create its .tlog (DirectoryNotFoundException -> MSB6003). A short
+#                          root keeps every nested path well under the limit (per-arch so the two
+#                          matrix legs don't share a target dir).
+#
+# Steps use `shell: pwsh` (PowerShell 7) deliberately: Windows PowerShell 5.1's
+# `Out-File -Encoding utf8` prepends a UTF-8 BOM that corrupts the first GITHUB_ENV line (that
+# var silently never gets set). pwsh writes no BOM.
+# The runner's daemon wrapper puts C:\Program Files\PowerShell\7 on PATH so the job finds pwsh.
+#
+# ── Packaging (the `Pack + sign MSIX` step onward; skipped on pull requests) ──────────────────────
+#
+# Publishes signed MSIX packages (x64 + ARM64) to Gitea's generic package registry, so Windows boxes
+# can install a real package (Start tile, clean install/uninstall) instead of a loose exe.
+#
+# Registry (public, unom org): https://git.unom.io/unom/-/packages  (generic group)
+# Packaging internals: clients/windows/packaging/README.md.
+#
+# Versioning — single project version; MSIX requires a strictly 4-part numeric version, so:
+#   vX.Y.Z tag -> X.Y.Z.0  (THE release; any -rc/+meta pre-release suffix is dropped for MSIX).
+#                Published to the generic registry + the stable `latest/` alias + attached to the
+#                unified Gitea Release alongside every other platform's artifact.
+#   main push / dispatch -> <next-minor>.<run_number>.0  (canary; base is one minor ahead of the
+#                latest stable tag via scripts/ci/pf-version.ps1, run number climbs monotonically).
+# Both arches share the version; artifacts are arch-suffixed (..._x64.msix / ..._arm64.msix).
+#
+# Signing (clients/windows/packaging/pack-msix.ps1): if the MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD
+# Actions secrets are set (a real or shared code-signing .pfx whose subject DN == Publisher), the
+# package is signed with them. Otherwise an ephemeral self-signed cert is generated and its public
+# .cer is published next to the .msix (users import it to Trusted People before install).
+#
+# That fallback is for canary/CI ONLY. On a v* tag the pack script FAILS CLOSED — a missing secret
+# aborts the build instead of quietly shipping a release signed by a per-build throwaway cert that
+# no one can pin. Nothing to opt into here: the script reads GITHUB_REF itself.
+name: windows-client
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+
+on:
+  push:
+    branches: [main]
+    # ONE list now, not three. The old windows.yml + windows-msix.yml pair carried this same set
+    # three times (push, pull_request, and the second file), which is exactly how a crate goes
+    # missing from one copy — windows-host.yml documents the "Cargo.lock luck" gap that produced.
+    paths:
+      - 'clients/windows/**'
+      - 'clients/session/**'
+      - 'crates/punktfunk-core/**'
+      - 'crates/pf-client-core/**'
+      - 'crates/pf-presenter/**'
+      - 'crates/pf-console-ui/**'
+      - 'crates/pf-bitstream/**'
+      - 'crates/pf-vkdecode/**'
+      - 'crates/pf-dxvadec/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows-client.yml'
+    tags: ['v*']
+  pull_request:
+    paths:
+      - 'clients/windows/**'
+      - 'clients/session/**'
+      - 'crates/punktfunk-core/**'
+      - 'crates/pf-client-core/**'
+      - 'crates/pf-presenter/**'
+      - 'crates/pf-console-ui/**'
+      - 'crates/pf-bitstream/**'
+      - 'crates/pf-vkdecode/**'
+      - 'crates/pf-dxvadec/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows-client.yml'
+  workflow_dispatch:
+
+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
+# unbound). Keys include compiler hash + target + flags, so cross-OS/arch entries can
+# never collide; every Rust job on every host feeds and reads one warm cache.
+#
+# NOTE the C/C++ launcher wiring the Linux workflows carry (CMAKE_*_COMPILER_LAUNCHER, CC_*) is
+# deliberately NOT set here. This runner's failure mode under extra compiler processes is the
+# C1069 disk/temp exhaustion documented in windows-host.yml, so sccache-for-MSVC is its own
+# change, to be made with a measurement rather than folded into a reorganisation.
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+  PKG: punktfunk-client-windows
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"
+
+jobs:
+  # SECURITY: this job builds PULL-REQUEST code (attacker-controllable build.rs / cargo build) on the
+  # host-mode, persistent `windows-amd64` runner that the release-SIGNING steps below and
+  # windows-host.yml (which decrypt MSIX_CERT_PFX_B64 + REGISTRY_TOKEN to disk) also run on. Untrusted
+  # PR code could therefore persist on that machine or harvest signing material a later job exposes.
+  # The DEFINITIVE fix is operational and lives outside this file: enable Gitea's "require approval to
+  # run workflows for PRs from outside collaborators/forks", and/or route PR CI to isolated ephemeral
+  # runners. The `if:` below is only a backstop — it skips fork PRs where Gitea reports the fork flag,
+  # and FAILS OPEN (still runs) for same-repo PRs and on Gitea versions that don't populate it, so it
+  # never blocks internal PR CI.
+  client:
+    runs-on: windows-amd64
+    if: >-
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.head.repo.fork != true
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x64
+            target: x86_64-pc-windows-msvc
+            td: C:\t
+            session_flags: ''
+          - arch: arm64
+            target: aarch64-pc-windows-msvc
+            td: C:\t-a64
+            # No skia-binaries prebuilt for aarch64-pc-windows-msvc: the session ships
+            # without the Skia console UI on ARM64 (streaming unaffected) — flip when
+            # rust-skia adds the target.
+            session_flags: '--no-default-features'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Ensure Windows toolchain (WDK, Inno Setup, ARM64 target)
+        shell: pwsh
+        run: ./scripts/ci/ensure-windows-toolchain.ps1
+
+      - name: Configure + version
+        shell: pwsh
+        run: |
+          # CARGO_TARGET_DIR (per-arch, short) dodges the MAX_PATH wall in the CMake-from-source
+          # crates (see this file's header). No FFMPEG_DIR: nothing in this package links libav*
+          # (M10), and pack-msix.ps1 no longer copies runtime DLLs from one.
+          "CARGO_TARGET_DIR=${{ matrix.td }}" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          rustup target add ${{ matrix.target }}
+          rustc --version
+          cargo --version
+          $pf = & "$env:GITHUB_WORKSPACE/scripts/ci/pf-version.ps1"   # single source of truth: base is one minor ahead of the latest stable tag
+          $parts = if ($env:GITHUB_REF -like 'refs/tags/v*') {
+            # MSIX needs a purely-numeric 4-part version: drop any -rc/+meta pre-release suffix.
+            (($env:GITHUB_REF_NAME -replace '^v', '') -replace '[-+].*$', '').Split('.')
+          } else {
+            # Canary: <major>.<minor>.<run>.0 — major.minor track one minor ahead of stable, run climbs monotonically.
+            @($pf.PF_MAJOR, $pf.PF_MINOR, $env:GITHUB_RUN_NUMBER)
+          }
+          while ($parts.Count -lt 4) { $parts += '0' }
+          $v = ($parts[0..3] -join '.')
+          "MSIX_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          Write-Output "MSIX version $v  arch ${{ matrix.arch }}  target ${{ matrix.target }}  target-dir ${{ matrix.td }}"
+
+      # All three client binaries, ONCE, in release. The shell spawns punktfunk-session.exe (a
+      # package sibling) for every stream, and punktfunk-cli builds the `punktfunk.exe` the manifest
+      # aliases and pack-msix.ps1 requires (bf981027 added the requirement without the build — the
+      # same gap 90c84ef4 closed for deb). --no-default-features on ARM64 is a no-op for the shell.
+      #
+      # Release, not debug, even for the lint/test legs below: a debug build here would compile the
+      # whole dep tree into a SECOND target dir and re-run openh264-sys2's vendored C++ through
+      # cc-rs's cl.exe fan-out, which is what tips this runner into C1069 (see the header).
+      - name: Build (release)
+        shell: pwsh
+        run: cargo build --release -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli ${{ matrix.session_flags }} --target ${{ matrix.target }}
+
+      - name: Clippy (-D warnings)
+        shell: pwsh
+        run: |
+          # Every crate in the `paths:` trigger above is named here: `cargo clippy -p X` BUILDS a
+          # dependency but only LINTS the packages it is given, so a decode crate that starts the
+          # run but is missing from this list would be gated by nothing.
+          $pkgs = @('-p','punktfunk-client-windows','-p','punktfunk-client-session','-p','punktfunk-cli','-p','pf-client-core','-p','pf-presenter','-p','pf-bitstream','-p','pf-vkdecode','-p','pf-dxvadec')
+          $sf = @()
+          if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { $sf = @('--no-default-features') } else { $pkgs += @('-p','pf-console-ui') }
+          cargo clippy --release @pkgs --all-targets @sf --target ${{ matrix.target }} -- -D warnings
+          if ($LASTEXITCODE) { throw "clippy" }
+
+      - name: Rustfmt check
+        if: matrix.arch == 'x64'
+        shell: pwsh
+        run: |
+          cargo fmt -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-dxvadec -- --check
+          if ($LASTEXITCODE) { throw "rustfmt" }
+
+      - name: Test
+        # x64 only: the aarch64 binaries cross-compile here but cannot RUN on this host.
+        if: matrix.arch == 'x64'
+        shell: pwsh
+        run: |
+          cargo test --release -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-dxvadec --target ${{ matrix.target }}
+          if ($LASTEXITCODE) { throw "tests" }
+
+      - name: sccache stats (visibility only)
+        if: always()
+        shell: pwsh
+        run: sccache --show-stats
+
+      # ── Packaging: pushes, tags and dispatch only. A PR gets the build/lint/test signal above and
+      # stops there — packing would sign with a throwaway cert and publish nothing.
+      - name: Pack + sign MSIX
+        if: github.event_name != 'pull_request'
+        shell: pwsh
+        env:
+          # Azure Artifact Signing (formerly Trusted Signing) — takes precedence over MSIX_CERT_*
+          # when all three are set. Not secret: an account/profile name and a regional endpoint,
+          # inert without the credentials below. The profile's verified subject is also the MSIX
+          # manifest Publisher; pack-msix.ps1 reads the signature back and fails on a mismatch.
+          AZURE_CODESIGNING_ENDPOINT: https://neu.codesigning.azure.net/
+          AZURE_CODESIGNING_ACCOUNT: unomsigning
+          AZURE_CODESIGNING_PROFILE: unom-io
+          # Service principal 'punktfunk-ci-signing', holding ONLY the Artifact Signing Certificate
+          # Profile Signer role, scoped to the unom-io profile — it can sign and nothing else.
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+          # Legacy self-signed path, kept as the fallback for builds without Azure access.
+          MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
+          MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
+        run: |
+          & clients/windows/packaging/pack-msix.ps1 `
+            -Version $env:MSIX_VERSION -Arch ${{ matrix.arch }} `
+            -TargetDir ${{ matrix.td }}\${{ matrix.target }}\release -OutDir ${{ matrix.td }}\msix
+
+      - name: Publish to Gitea generic registry
+        if: github.event_name != 'pull_request'
+        shell: pwsh
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          $PSNativeCommandUseErrorActionPreference = $false
+          $base = "https://$($env:REGISTRY)/api/packages/$($env:OWNER)/generic/$($env:PKG)"
+          # stable release -> `latest/` alias; canary main build -> `canary/` alias.
+          $alias = if ($env:GITHUB_REF -like 'refs/tags/v*') { 'latest' } else { 'canary' }
+          # version-less, arch-suffixed alias names so each channel keeps one predictable URL.
+          # Under Azure signing there is no .cer, so MSIX_CER_PATH is unset. The quotes below are
+          # load-bearing: "$($env:UNSET)" interpolates to an empty string (a legal key), whereas a
+          # BARE $env:UNSET is $null and a null key is a hard error in a hash literal — which is
+          # exactly how windows-host.yml's publish step broke. Added explicitly rather than relying
+          # on that accident, so removing the quotes can't silently reintroduce it.
+          $aliasNames = @{ "$($env:MSIX_PATH)" = "$($env:PKG)_${{ matrix.arch }}.msix" }
+          if ($env:MSIX_CER_PATH) { $aliasNames[$env:MSIX_CER_PATH] = "$($env:PKG)_${{ matrix.arch }}.cer" }
+          $files = @($env:MSIX_PATH, $env:MSIX_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
+          if (-not $files) { throw "pack produced no artifacts to publish" }
+          function Put($f, $url) {
+            # The generic registry makes a versioned path immutable and 409s a re-upload, so a tag
+            # re-run re-publishing the identical artifact must be tolerated as a no-op. (The channel
+            # alias below is delete-then-reuploaded and never 409s.) No curl -f, so we can read the
+            # status code instead of aborting on it.
+            $code = [int](curl.exe -sS -o NUL -w "%{http_code}" --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url")
+            if ($LASTEXITCODE -ne 0) { throw "upload failed (curl exit $LASTEXITCODE): $url" }
+            if ($code -eq 409) { Write-Output "already published (409, immutable): $url"; return }
+            if ($code -lt 200 -or $code -ge 300) { throw "upload failed (HTTP $code): $url" }
+            Write-Output "published ($code): $url"
+          }
+          foreach ($f in $files) {
+            $name = Split-Path $f -Leaf
+            # 1) immutable, versioned path
+            Put $f "$base/$($env:MSIX_VERSION)/$name"
+            # 2) channel alias (delete-then-reupload; the generic registry 409s on an existing file)
+            $an = $aliasNames["$f"]
+            curl.exe -fsS -o NUL --user "enricobuehler:$($env:REGISTRY_TOKEN)" -X DELETE "$base/$alias/$an" 2>$null
+            Put $f "$base/$alias/$an"
+          }
+
+      # On a real release, also attach the MSIX (+ its .cer) to the unified Gitea Release. Both
+      # arch legs attach to the same release concurrently — the helper's create-or-fetch handles
+      # the race, and x64/arm64 filenames differ so the assets don't collide.
+      - name: Attach MSIX to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        shell: pwsh
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.ps1
+          $rid = Ensure-GiteaRelease -Tag $env:GITHUB_REF_NAME -Name $env:GITHUB_REF_NAME -Prerelease 'auto'
+          foreach ($f in @($env:MSIX_PATH, $env:MSIX_CER_PATH)) {
+            if ($f -and (Test-Path $f)) { Upsert-GiteaAsset -ReleaseId $rid -File $f }
+          }

.gitea/workflows/windows-drivers.yml

@@ -9,7 +9,7 @@
 # only live NVENC encode does, which defers to the RTX box.
 #
 # shell: pwsh deliberately (PowerShell 5.1's Out-File -Encoding utf8 prepends a BOM that corrupts the
-# first GITHUB_ENV line — see windows.yml).
+# first GITHUB_ENV line — see windows-client.yml).
 name: windows-drivers
 # One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
 # it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
@@ -39,7 +39,7 @@ on:
 
 jobs:
   # SECURITY: builds PULL-REQUEST code on the host-mode, persistent `windows-amd64` runner shared with
-  # the release-signing jobs (windows-host.yml / windows-msix.yml). See windows.yml for the full
+  # the release-signing jobs (windows-host.yml / windows-client.yml). See windows-client.yml for the full
   # rationale. Definitive fix is server-side (Gitea outside-collaborator approval + isolated PR
   # runners); the `if:` is a fail-open backstop that never blocks internal PR CI.
   probe-and-proto:
@@ -111,7 +111,7 @@ jobs:
 
       - name: Build + test pf-driver-proto (MSVC)
         run: |
-          # Short target dir to dodge MAX_PATH inside the deep act host workdir (see windows.yml).
+          # Short target dir to dodge MAX_PATH inside the deep act host workdir (see windows-client.yml).
           $env:CARGO_TARGET_DIR = "C:\t\drv"
           cargo build -p pf-driver-proto
           cargo test  -p pf-driver-proto
@@ -144,7 +144,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Ensure Windows toolchain (WDK, FFmpeg, Inno Setup, ARM64 target)
-        # Shared self-provision step (also used by windows.yml/windows-msix.yml/windows-host.yml) so
+        # Shared self-provision step (also used by windows-client.yml/windows-host.yml) so
         # driver-build is self-sufficient on any windows-amd64 runner and never races a manually
         # dispatched provisioning workflow landing on a different one. Path is relative to the job
         # working-directory (packaging/windows/drivers). Near-noop once the toolchain is present.

.gitea/workflows/windows-host.yml

@@ -3,7 +3,7 @@
 # pf-vdisplay virtual-display driver + the web management console + the opt-in plugin/script runner,
 # run by scheduled tasks on a bundled bun) from one signed setup.exe. Runs on a self-hosted
 # windows-amd64 runner
-# (host mode; same MSVC/Windows-SDK/LLVM env as windows.yml — generic from unom/infra's
+# (host mode; same MSVC/Windows-SDK/LLVM env as windows-client.yml — generic from unom/infra's
 # windows-runner/, FFmpeg/Inno Setup self-provision via the "Ensure Windows toolchain" step below).
 #
 # Why an installer and not MSIX (like the client): the host installs a LocalSystem SCM service that
@@ -20,12 +20,18 @@
 #   main push / dispatch -> <next-minor>.<run_number>  (canary; `canary/` alias; base one minor
 #                          ahead of the latest stable tag via scripts/ci/pf-version.ps1, run climbs).
 #
-# Signing reuses the client's MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD secrets (CN=unom). Without them
-# an ephemeral self-signed cert is generated and its public .cer published next to the installer
-# (import once to LocalMachine\TrustedPublisher). That fallback is for canary/CI ONLY — on a v* tag
+# Signing goes through Azure Artifact Signing (account `unomsigning`, profile `unom-io`) — a publicly
+# trusted CA, so there is no .cer for users to import and no SmartScreen "unknown publisher" prompt.
+# It falls back to the old MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD self-signed cert, and then to an
+# ephemeral one, for builds without Azure access. Those fallbacks are for canary/CI ONLY — on a v* tag
 # the pack script FAILS CLOSED rather than ship a release signed by a per-build throwaway cert.
 # See packaging/windows/pack-host-installer.ps1.
 #
+# The bundled DRIVERS are NOT signed by Azure — they keep their own DRIVER_CERT_* cert and are still
+# trusted by planting that cert in the machine Root store at install time. Independent by design:
+# Windows checks the installer's signature via SmartScreen/UAC and driver catalogs via PnP, and never
+# requires a common signer. See packaging/windows/README.md for why that root-plant is still there.
+#
 # GPU backends: the host builds with --features nvenc,amf-qsv,qsv = all three vendors in one installer.
 #  - NVENC (NVIDIA, direct SDK): nothing needed at build time — the entry points are resolved at
 #    RUNTIME from the driver's nvEncodeAPI64.dll (a link-time import would kill the binary on
@@ -143,7 +149,7 @@ jobs:
           "CMAKE_POLICY_VERSION_MINIMUM=3.5" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           # FFMPEG_DIR: the BtbN lgpl-shared x64 tree, provisioned by
           # scripts/ci/provision-windows-punktfunk-extras.ps1. The CLIENT used to link it too; since M10
-          # it links no libav* at all (windows.yml sets no FFMPEG_DIR), so this tree is the HOST's alone
+          # it links no libav* at all (windows-client.yml sets no FFMPEG_DIR), so this tree is the HOST's alone
           # and the provisioning step keeps fetching it for that reason. The host's AMD/Intel AMF/QSV encode backend
           # (--features amf-qsv) link-imports avcodec/avutil/swscale from it; pack-host-installer.ps1
           # then bundles its bin\*.dll into the installer. LIBCLANG_PATH is in the runner daemon env.
@@ -415,12 +421,26 @@ jobs:
       - name: Pack + sign installer
         shell: pwsh
         env:
+          # Azure Artifact Signing (formerly Trusted Signing) — takes precedence over MSIX_CERT_*
+          # when all three of these are set. Not secret: an account/profile name and a regional
+          # endpoint, all inert without the credentials below, so they live here where a reviewer
+          # can see which profile a release was signed by.
+          AZURE_CODESIGNING_ENDPOINT: https://neu.codesigning.azure.net/
+          AZURE_CODESIGNING_ACCOUNT: unomsigning
+          AZURE_CODESIGNING_PROFILE: unom-io
+          # Service principal 'punktfunk-ci-signing', holding ONLY the Artifact Signing Certificate
+          # Profile Signer role, scoped to the unom-io profile — it can sign and nothing else.
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+          # Legacy self-signed path, kept as the fallback for builds without Azure access.
           MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
           MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
           # The DRIVER cert is separate from the host/MSIX one and reaches the two driver build
           # scripts through the environment (pack-host-installer.ps1 invokes them, they read
           # $env:DRIVER_CERT_PFX_B64 themselves). Without it they sign with a per-build throwaway,
           # which the installer then trusts as a machine root — see packaging/windows/README.md.
+          # NOT moved to Azure: driver catalogs are a separate track, see that README.
           DRIVER_CERT_PFX_B64: ${{ secrets.DRIVER_CERT_PFX_B64 }}
           DRIVER_CERT_PASSWORD: ${{ secrets.DRIVER_CERT_PASSWORD }}
         run: |
@@ -452,7 +472,13 @@ jobs:
           # Refresh the channel alias (delete-then-reupload, like flatpak.yml/decky.yml) for a
           # predictable download URL: stable release -> `latest/`, canary main build -> `canary/`.
           $alias = if ($env:GITHUB_REF -like 'refs/tags/v*') { 'latest' } else { 'canary' }
-          $aliasNames = @{ $env:HOST_SETUP_PATH = 'punktfunk-host-setup.exe'; $env:HOST_CER_PATH = 'punktfunk-host-windows.cer' }
+          # Build this incrementally, NOT as one literal: under Azure signing there is no .cer, so
+          # HOST_CER_PATH is unset — and an unset $env: var is $null, which is a HARD ERROR as a hash
+          # literal key ("A null key is not allowed in a hash literal"), not the empty-string key it
+          # looks like it should be. The $files guard above filters the missing .cer out just fine;
+          # this line ran before anything could use it and failed the whole publish step.
+          $aliasNames = @{ $env:HOST_SETUP_PATH = 'punktfunk-host-setup.exe' }
+          if ($env:HOST_CER_PATH) { $aliasNames[$env:HOST_CER_PATH] = 'punktfunk-host-windows.cer' }
           foreach ($f in $files) {
             $an = $aliasNames[$f]; if (-not $an) { continue }
             curl.exe -fsS -o NUL --user "enricobuehler:$($env:REGISTRY_TOKEN)" -X DELETE "$base/$alias/$an" 2>$null

.gitea/workflows/windows-msix.yml

@@ -1,196 +0,0 @@
-# Build the punktfunk Windows client as signed MSIX packages (x64 + ARM64) and publish them to
-# Gitea's generic package registry, so Windows boxes can download + install a real package (Start
-# tile, clean install/uninstall) instead of a loose exe. Runs on a self-hosted windows-amd64
-# runner (host mode; the MSVC/WinUI toolchain comes from unom/infra's windows-runner/, the rest
-# self-provisions via the "Ensure Windows toolchain" step below, same as windows.yml) — the
-# Windows SDK's makeappx/signtool are baked into the runner's daemon env.
-#
-# Both arches come off the ONE x64 runner: x86_64 natively, aarch64 cross-compiled (the x64 MSVC
-# toolset has the ARM64 cross compiler). See windows.yml for the cross-build rationale + the
-# BOM/MAX_PATH runner gotchas.
-#
-# NO FFmpeg since M10 (design/client-native-decode.md §6): the client decodes natively, so the
-# package carries no libav* DLLs and this workflow sets no FFMPEG_DIR. The host installer
-# (windows-host.yml) is unchanged.
-#
-# Registry (public, unom org): https://git.unom.io/unom/-/packages  (generic group)
-# Packaging internals: clients/windows/packaging/README.md.
-#
-# Versioning — single project version; MSIX requires a strictly 4-part numeric version, so:
-#   vX.Y.Z tag -> X.Y.Z.0  (THE release; any -rc/+meta pre-release suffix is dropped for MSIX).
-#                Published to the generic registry + the stable `latest/` alias + attached to the
-#                unified Gitea Release alongside every other platform's artifact.
-#   main push / dispatch -> <next-minor>.<run_number>.0  (canary; base is one minor ahead of the
-#                latest stable tag via scripts/ci/pf-version.ps1, run number climbs monotonically).
-#                Published to the generic registry + the `canary/` alias.
-# Both arches share the version; artifacts are arch-suffixed (..._x64.msix / ..._arm64.msix).
-#
-# Signing (clients/windows/packaging/pack-msix.ps1): if the MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD
-# Actions secrets are set (a real or shared code-signing .pfx whose subject DN == Publisher), the
-# package is signed with them. Otherwise an ephemeral self-signed cert is generated and its public
-# .cer is published next to the .msix (users import it to Trusted People before install).
-#
-# That fallback is for canary/CI ONLY. On a v* tag the pack script FAILS CLOSED — a missing secret
-# aborts the build instead of quietly shipping a release signed by a per-build throwaway cert that
-# no one can pin. Nothing to opt into here: the script reads GITHUB_REF itself.
-name: windows-msix
-# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
-# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
-# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
-# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'clients/windows/**'
-      - 'clients/session/**'
-      - 'crates/punktfunk-core/**'
-      - 'crates/pf-client-core/**'
-      - 'crates/pf-presenter/**'
-      - 'crates/pf-console-ui/**'
-      - 'crates/pf-bitstream/**'
-      - 'crates/pf-vkdecode/**'
-      - 'crates/pf-dxvadec/**'
-      - 'Cargo.lock'
-      - 'Cargo.toml'
-      - '.gitea/workflows/windows-msix.yml'
-    tags: ['v*']
-  workflow_dispatch:
-
-env:
-  REGISTRY: git.unom.io
-  OWNER: unom
-  PKG: punktfunk-client-windows
-  RUSTC_WRAPPER: sccache
-  SCCACHE_BUCKET: unom-ci-sccache
-  SCCACHE_ENDPOINT: https://storage.unom.io
-  SCCACHE_REGION: home-central
-  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
-  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
-  # sccache and incremental compilation are mutually exclusive; CI wants the shared
-  # cache, dev boxes keep incremental.
-  CARGO_INCREMENTAL: "0"
-
-jobs:
-  package:
-    runs-on: windows-amd64
-    timeout-minutes: 90
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - arch: x64
-            target: x86_64-pc-windows-msvc
-            td: C:\t
-            session_flags: ''
-          - arch: arm64
-            target: aarch64-pc-windows-msvc
-            td: C:\t-a64
-            # No skia-binaries prebuilt for aarch64-pc-windows-msvc: the session ships
-            # without the Skia console UI on ARM64 (streaming unaffected) — flip when
-            # rust-skia adds the target.
-            session_flags: '--no-default-features'
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Ensure Windows toolchain (WDK, Inno Setup, ARM64 target)
-        shell: pwsh
-        run: ./scripts/ci/ensure-windows-toolchain.ps1
-
-      - name: Configure + version
-        shell: pwsh
-        run: |
-          # CARGO_TARGET_DIR (per-arch, short) dodges the MAX_PATH wall in the CMake-from-source
-          # crates (see windows.yml). No FFMPEG_DIR: nothing in this package links libav* (M10),
-          # and pack-msix.ps1 no longer copies runtime DLLs from one.
-          "CARGO_TARGET_DIR=${{ matrix.td }}" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
-          rustup target add ${{ matrix.target }}
-          $pf = & "$env:GITHUB_WORKSPACE/scripts/ci/pf-version.ps1"   # single source of truth: base is one minor ahead of the latest stable tag
-          $parts = if ($env:GITHUB_REF -like 'refs/tags/v*') {
-            # MSIX needs a purely-numeric 4-part version: drop any -rc/+meta pre-release suffix.
-            (($env:GITHUB_REF_NAME -replace '^v', '') -replace '[-+].*$', '').Split('.')
-          } else {
-            # Canary: <major>.<minor>.<run>.0 — major.minor track one minor ahead of stable, run climbs monotonically.
-            @($pf.PF_MAJOR, $pf.PF_MINOR, $env:GITHUB_RUN_NUMBER)
-          }
-          while ($parts.Count -lt 4) { $parts += '0' }
-          $v = ($parts[0..3] -join '.')
-          "MSIX_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
-          Write-Output "MSIX version $v  arch ${{ matrix.arch }}  target ${{ matrix.target }}"
-
-      # All three client binaries — the shell spawns punktfunk-session.exe (a package
-      # sibling) for every stream, and punktfunk-console.exe is the couch Start-menu tile's
-      # hand-off shim. --no-default-features on ARM64 is a no-op for the shell.
-      - name: Build (release)
-        shell: pwsh
-        # punktfunk-cli builds the `punktfunk.exe` the manifest aliases and pack-msix.ps1
-        # requires (bf981027 added the requirement without the build — same gap 90c84ef4
-        # closed for deb).
-        run: cargo build --release -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli ${{ matrix.session_flags }} --target ${{ matrix.target }}
-
-      - name: Pack + sign MSIX
-        shell: pwsh
-        env:
-          MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
-          MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
-        run: |
-          & clients/windows/packaging/pack-msix.ps1 `
-            -Version $env:MSIX_VERSION -Arch ${{ matrix.arch }} `
-            -TargetDir ${{ matrix.td }}\${{ matrix.target }}\release -OutDir ${{ matrix.td }}\msix
-
-      - name: Publish to Gitea generic registry
-        shell: pwsh
-        env:
-          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-        run: |
-          $PSNativeCommandUseErrorActionPreference = $false
-          $base = "https://$($env:REGISTRY)/api/packages/$($env:OWNER)/generic/$($env:PKG)"
-          # stable release -> `latest/` alias; canary main build -> `canary/` alias.
-          $alias = if ($env:GITHUB_REF -like 'refs/tags/v*') { 'latest' } else { 'canary' }
-          # version-less, arch-suffixed alias names so each channel keeps one predictable URL.
-          $aliasNames = @{
-            "$($env:MSIX_PATH)"     = "$($env:PKG)_${{ matrix.arch }}.msix"
-            "$($env:MSIX_CER_PATH)" = "$($env:PKG)_${{ matrix.arch }}.cer"
-          }
-          $files = @($env:MSIX_PATH, $env:MSIX_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
-          if (-not $files) { throw "pack produced no artifacts to publish" }
-          function Put($f, $url) {
-            # The generic registry makes a versioned path immutable and 409s a re-upload, so a tag
-            # re-run re-publishing the identical artifact must be tolerated as a no-op. (The channel
-            # alias below is delete-then-reuploaded and never 409s.) No curl -f, so we can read the
-            # status code instead of aborting on it.
-            $code = [int](curl.exe -sS -o NUL -w "%{http_code}" --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url")
-            if ($LASTEXITCODE -ne 0) { throw "upload failed (curl exit $LASTEXITCODE): $url" }
-            if ($code -eq 409) { Write-Output "already published (409, immutable): $url"; return }
-            if ($code -lt 200 -or $code -ge 300) { throw "upload failed (HTTP $code): $url" }
-            Write-Output "published ($code): $url"
-          }
-          foreach ($f in $files) {
-            $name = Split-Path $f -Leaf
-            # 1) immutable, versioned path
-            Put $f "$base/$($env:MSIX_VERSION)/$name"
-            # 2) channel alias (delete-then-reupload; the generic registry 409s on an existing file)
-            $an = $aliasNames["$f"]
-            curl.exe -fsS -o NUL --user "enricobuehler:$($env:REGISTRY_TOKEN)" -X DELETE "$base/$alias/$an" 2>$null
-            Put $f "$base/$alias/$an"
-          }
-
-      # On a real release, also attach the MSIX (+ its .cer) to the unified Gitea Release. Both
-      # arch legs attach to the same release concurrently — the helper's create-or-fetch handles
-      # the race, and x64/arm64 filenames differ so the assets don't collide.
-      - name: Attach MSIX to the Gitea release (stable tags only)
-        if: startsWith(gitea.ref, 'refs/tags/v')
-        shell: pwsh
-        env:
-          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-        run: |
-          . scripts/ci/gitea-release.ps1
-          $rid = Ensure-GiteaRelease -Tag $env:GITHUB_REF_NAME -Name $env:GITHUB_REF_NAME -Prerelease 'auto'
-          foreach ($f in @($env:MSIX_PATH, $env:MSIX_CER_PATH)) {
-            if ($f -and (Test-Path $f)) { Upsert-GiteaAsset -ReleaseId $rid -File $f }
-          }

.gitea/workflows/windows.yml

@@ -1,169 +0,0 @@
-# Windows client CI — runs on a self-hosted windows-amd64 runner (host mode; the generic runner +
-# toolchain come from unom/infra's windows-runner/; punktfunk's own extras - WDK, Inno Setup,
-# the ARM64 rustup target - self-provision via the "Ensure Windows toolchain" step below, a fast
-# no-op once already present, so any runner with that label works with no manual dispatch step
-# first). Build + clippy + fmt + test BOTH client binaries: the WinUI 3 shell
-# (windows-reactor + WASAPI + SDL3) and the punktfunk-session Vulkan client
-# (pf-presenter/pf-client-core/pf-console-ui — every stream runs in it, spawned by the
-# shell). ARM64 note: rust-skia publishes no aarch64-pc-windows-msvc prebuilt binaries, so the
-# session builds --no-default-features there (no Skia console UI; streaming is unaffected) —
-# flip when skia-binaries adds the target.
-#
-# NO FFmpeg here since M10 (design/client-native-decode.md §6): the client decodes with
-# pf-vkdecode / pf-dxvadec / openh264+rav1d and links no libav* at all, so this workflow sets
-# no FFMPEG_DIR, no PF_FFVK_VULKAN_INCLUDE and prepends nothing to PATH. The provisioning
-# script still fetches the FFmpeg trees because the HOST keeps FFmpeg — windows-host.yml's
-# `amf-qsv` leg link-imports them.
-#
-# Two architectures from ONE x64 runner: x86_64-pc-windows-msvc natively and
-# aarch64-pc-windows-msvc by cross-compiling. The x64 MSVC toolset ships an ARM64 cross compiler
-# (VC\Tools\MSVC\<ver>\bin\Hostx64\arm64\cl.exe) and aarch64-pc-windows-msvc is a tier-2 Rust
-# target with host tools, so no ARM64 runner is needed — the cc/cmake crates pick the ARM64
-# compiler from the target triple (SDL3 + libopus build-from-source cross-compile fine). The one
-# thing the aarch64 build can't do is *run* on the x64 host, so fmt + test run only for x64.
-#
-# The MSVC/WinUI toolchain (cargo/rustup on ASCII paths, NASM, CMake, LLVM, CARGO_HOME,
-# CMAKE_POLICY_VERSION_MINIMUM, …) is baked into the runner's daemon env. Per-checkout
-# / per-arch vars are set in a step:
-#   - CARGO_TARGET_DIR=C:\t…  the runner's host workdir is buried deep under
-#                          C:\Windows\System32\config\systemprofile\.cache\act\<hash>\hostexecutor\,
-#                          so the default target\ path blows past Windows' MAX_PATH (260) inside the
-#                          CMake-from-source builds (audiopus_sys / SDL3) — MSBuild's tracker then
-#                          can't create its .tlog (DirectoryNotFoundException -> MSB6003). A short
-#                          root keeps every nested path well under the limit (per-arch so the two
-#                          matrix legs don't share a target dir).
-#
-# Steps use `shell: pwsh` (PowerShell 7) deliberately: Windows PowerShell 5.1's
-# `Out-File -Encoding utf8` prepends a UTF-8 BOM that corrupts the first GITHUB_ENV line (that
-# var silently never gets set). pwsh writes no BOM.
-# The runner's daemon wrapper puts C:\Program Files\PowerShell\7 on PATH so the job finds pwsh.
-name: windows
-# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
-# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
-# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
-# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'clients/windows/**'
-      - 'clients/session/**'
-      - 'crates/punktfunk-core/**'
-      - 'crates/pf-client-core/**'
-      - 'crates/pf-presenter/**'
-      - 'crates/pf-console-ui/**'
-      - 'crates/pf-bitstream/**'
-      - 'crates/pf-vkdecode/**'
-      - 'crates/pf-dxvadec/**'
-      - 'Cargo.lock'
-      - 'Cargo.toml'
-      - '.gitea/workflows/windows.yml'
-  pull_request:
-    paths:
-      - 'clients/windows/**'
-      - 'clients/session/**'
-      - 'crates/punktfunk-core/**'
-      - 'crates/pf-client-core/**'
-      - 'crates/pf-presenter/**'
-      - 'crates/pf-console-ui/**'
-      - 'crates/pf-bitstream/**'
-      - 'crates/pf-vkdecode/**'
-      - 'crates/pf-dxvadec/**'
-      - 'Cargo.lock'
-      - 'Cargo.toml'
-      - '.gitea/workflows/windows.yml'
-  workflow_dispatch:
-
-# Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
-# unbound). Keys include compiler hash + target + flags, so cross-OS/arch entries can
-# never collide; every Rust job on every host feeds and reads one warm cache.
-env:
-  RUSTC_WRAPPER: sccache
-  SCCACHE_BUCKET: unom-ci-sccache
-  SCCACHE_ENDPOINT: https://storage.unom.io
-  SCCACHE_REGION: home-central
-  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
-  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
-  # sccache and incremental compilation are mutually exclusive; CI wants the shared
-  # cache, dev boxes keep incremental.
-  CARGO_INCREMENTAL: "0"
-
-jobs:
-  # SECURITY: this job builds PULL-REQUEST code (attacker-controllable build.rs / cargo build) on the
-  # host-mode, persistent `windows-amd64` runner that the release-SIGNING jobs (windows-host.yml /
-  # windows-msix.yml, which decrypt MSIX_CERT_PFX_B64 + REGISTRY_TOKEN to disk) also run on. Untrusted
-  # PR code could therefore persist on that machine or harvest signing material a later job exposes.
-  # The DEFINITIVE fix is operational and lives outside this file: enable Gitea's "require approval to
-  # run workflows for PRs from outside collaborators/forks", and/or route PR CI to isolated ephemeral
-  # runners. The `if:` below is only a backstop — it skips fork PRs where Gitea reports the fork flag,
-  # and FAILS OPEN (still runs) for same-repo PRs and on Gitea versions that don't populate it, so it
-  # never blocks internal PR CI.
-  build:
-    runs-on: windows-amd64
-    if: >-
-      github.event_name != 'pull_request' ||
-      github.event.pull_request.head.repo.fork != true
-    timeout-minutes: 90
-    strategy:
-      fail-fast: false
-      matrix:
-        target: [x86_64-pc-windows-msvc, aarch64-pc-windows-msvc]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Ensure Windows toolchain (WDK, Inno Setup, ARM64 target)
-        shell: pwsh
-        run: ./scripts/ci/ensure-windows-toolchain.ps1
-
-      - name: Configure + toolchain versions
-        shell: pwsh
-        run: |
-          # Per-arch short target root (dodges MAX_PATH; keeps the two legs from sharing target\).
-          $td = if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { 'C:\t-a64' } else { 'C:\t' }
-          "CARGO_TARGET_DIR=$td" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
-          # No FFMPEG_DIR / PF_FFVK_VULKAN_INCLUDE / PATH prepend: the client links no libav*
-          # since M10 (see this file's header), so nothing here needs import libs or runtime DLLs.
-          # The HOST still does — windows-host.yml sets them for its amf-qsv leg.
-          rustup target add ${{ matrix.target }}
-          rustc --version
-          cargo --version
-          Write-Output "target ${{ matrix.target }}  target-dir $td"
-
-      # Both client binaries. ARM64: no skia-binaries prebuilt for the target, so the session
-      # drops its `ui` feature there (pf-console-ui excluded; --no-default-features is a no-op
-      # for the shell, which has no features).
-      # punktfunk-cli is in every gate: windows-msix.yml ships its `punktfunk.exe` alias, so
-      # a CLI that only the release workflow compiles is a release-day surprise. Its tests
-      # RUN the binary (help contract), as the session's contract_smoke runs the session —
-      # the gate class that catches a compiling-but-wrong binary (the 0.22.0 clobber).
-      - name: Build
-        shell: pwsh
-        run: |
-          $sf = @(); if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { $sf = @('--no-default-features') }
-          cargo build -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli @sf --target ${{ matrix.target }}
-
-      - name: Clippy (-D warnings)
-        shell: pwsh
-        run: |
-          # Every crate in the `paths:` trigger above is named here: `cargo clippy -p X` BUILDS a
-          # dependency but only LINTS the packages it is given, so a decode crate that starts the
-          # run but is missing from this list would be gated by nothing.
-          $pkgs = @('-p','punktfunk-client-windows','-p','punktfunk-client-session','-p','punktfunk-cli','-p','pf-client-core','-p','pf-presenter','-p','pf-bitstream','-p','pf-vkdecode','-p','pf-dxvadec')
-          $sf = @()
-          if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { $sf = @('--no-default-features') } else { $pkgs += @('-p','pf-console-ui') }
-          cargo clippy @pkgs --all-targets @sf --target ${{ matrix.target }} -- -D warnings
-
-      - name: Rustfmt check
-        if: matrix.target == 'x86_64-pc-windows-msvc'
-        shell: pwsh
-        run: cargo fmt -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-dxvadec -- --check
-
-      - name: Test
-        if: matrix.target == 'x86_64-pc-windows-msvc'
-        shell: pwsh
-        run: cargo test -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-dxvadec --target ${{ matrix.target }}

Cargo.toml

@@ -65,9 +65,9 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.27.0"
-edition = "2021"
-rust-version = "1.82"
+version = "0.28.1"
+edition = "2024"
+rust-version = "1.85"
 license = "MIT OR Apache-2.0"
 authors = ["unom"]
 repository = "https://git.unom.io/unom/punktfunk"

README.md

@@ -100,7 +100,7 @@ installer (all-vendor: NVIDIA, AMD, Intel).
 
 | Platform | Install | Guide |
 |--------|---------|-------|
-| **Ubuntu / Debian** (apt) | `sudo apt install punktfunk-host` *(after adding the repo)* | [Ubuntu / Debian](https://docs.punktfunk.unom.io/docs/ubuntu) · [packaging/debian](packaging/debian/README.md) |
+| **Ubuntu 26.04+ / Debian 13+** (apt) | `sudo apt install punktfunk-host` *(after adding the repo)* | [Ubuntu](https://docs.punktfunk.unom.io/docs/ubuntu) · [Debian](https://docs.punktfunk.unom.io/docs/debian) · [packaging/debian](packaging/debian/README.md) |
 | **Bazzite / Fedora Atomic** (systemd-sysext) | `curl -fsSLO https://git.unom.io/unom/punktfunk/raw/branch/main/packaging/bazzite/punktfunk-sysext.sh && sudo bash punktfunk-sysext.sh install` *(no layering, no reboot; rpm-ostree + bootc also supported)* | [Bazzite](https://docs.punktfunk.unom.io/docs/bazzite) |
 | **Fedora** (dnf) | `sudo dnf install punktfunk` *(after adding the repo; the console comes with it)* | [Fedora](https://docs.punktfunk.unom.io/docs/fedora) · [packaging/rpm](packaging/rpm/README.md) |
 | **Arch / CachyOS** (pacman) | `sudo pacman -Syu punktfunk-host` *(binary repo — always a full `-Syu`)* | [Arch Linux](https://docs.punktfunk.unom.io/docs/arch) · [packaging/arch](packaging/arch/README.md) |

SECURITY.md

@@ -5,13 +5,17 @@ machine, so we take security reports seriously and appreciate responsible disclo
 
 ## Supported versions
 
-Punktfunk ships on two tracks — **stable** (a `vX.Y.Z` tag; the current line is **0.22.x**) and
+Punktfunk ships on two tracks — **stable** (a `vX.Y.Z` tag) and
 **canary** (built from `main`). Fixes ship as a new release on those tracks; in practice
 we don't backport to older minor versions, so the supported versions are the latest stable release
 and the current canary build. If you're on an older build, please check that the issue still
 reproduces on the latest stable before reporting it. See
 [Release Channels](https://docs.punktfunk.unom.io/docs/channels).
 
+Security fixes are **free of charge**, ship **without undue delay**, and are **separated from
+feature updates where feasible**: on the stable track they arrive as patch releases (`vX.Y.Z+1`)
+that carry the fix rather than waiting on the next feature release.
+
 ## Reporting a vulnerability
 
 **Please report security issues privately by email to security@punktfunk.com.**

about.toml

@@ -40,7 +40,6 @@ accepted = [
     "CC0-1.0",
     "Unlicense",
     "WTFPL",
-    "OpenSSL",
 ]
 
 # cbindgen is MPL-2.0 but it is a BUILD-ONLY codegen tool that never links into a shipped artifact
@@ -57,7 +56,8 @@ ignore-dev-dependencies = true
 # accepted arm on its own (MIT/Apache-2.0 are globally accepted), so it needs no entry. (It is
 # also UEFI-target-gated out of every shipped build.)
 #
-# ring's license is an AND of permissive terms including the OpenSSL license; accept the
-# OpenSSL/ISC parts for this crate only, not globally.
-[ring]
-accepted = ["OpenSSL", "ISC"]
+# There is deliberately NO per-crate entry here any more. `ring` used to need one (its licence is an
+# AND that includes the OpenSSL licence, which was accepted for that crate alone), but the crypto
+# backend moved to aws-lc-rs and the ureq 2 → 3 upgrade removed ring from every target we build.
+# aws-lc-sys 0.44's SPDX is an AND of ISC / Apache-2.0 / MIT / BSD-3-Clause / MIT-0 — all globally
+# accepted above — and carries no OpenSSL clause, so `OpenSSL` left the global list with ring.

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "paths": {
     "/api/v1/clients": {
@@ -45,6 +45,36 @@
             }
           }
         }
+      },
+      "delete": {
+        "tags": [
+          "clients"
+        ],
+        "summary": "Unpair every client",
+        "description": "The collection form of [`unpair_client`]: empties the pairing store in ONE persisted write,\ncarrying the same revocation guarantees across the whole set. A LIVE GameStream session is\nended (its owning certificate is necessarily one of those just removed), and the ENet control\nport (UDP 47999) closes, because no pairing is left to hold it open.\n\nIdempotent, and so a 200 rather than the single unpair's 204/404 pair: \"unpair everything\" is\nsatisfied by an already-empty store, and the operator still wants to know whether that meant\nthree devices or none.",
+        "operationId": "unpairAllClients",
+        "responses": {
+          "200": {
+            "description": "Every client unpaired (possibly none)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnpairAllResult"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/api/v1/clients/{fingerprint}": {
@@ -997,7 +1027,7 @@
           "library"
         ],
         "summary": "List the game library",
-        "description": "Every installed-store title (Steam, read from the host's local files — no Steam API key)\nmerged with the user's custom entries, sorted by title. Artwork fields are URLs the client\nfetches directly (the public Steam CDN for Steam titles). `?provider=` narrows to the\nentries a given external provider owns; `?platform=` to one platform (case-insensitive —\ninstalled-store titles are `PC`, custom/provider entries carry whatever was authored).\n\n**The operator's own lane additionally sees the titles they have HIDDEN**, each carrying\n`hidden: true`; every other lane gets them filtered out upstream and cannot tell they exist. The\nconsole needs them to offer \"un-hide\", and it is the only surface that does.",
+        "description": "Every title this host knows about, sorted by title: the entries each installed library plugin\nhas synced (Steam, Lutris, Heroic, Epic, GOG, Xbox, Playnite, ROM managers, …) plus the user's\nown custom entries. Artwork fields are URLs the client fetches directly, except local files on\nthe host, which are rewritten to this API's own art proxy. `?provider=` narrows to the entries a\ngiven external provider owns; `?platform=` to one platform (case-insensitive — whatever the\nsource authored, conventionally `PC` for desktop stores).\n\n**The operator's own lane additionally sees the titles they have HIDDEN**, each carrying\n`hidden: true`; every other lane gets them filtered out upstream and cannot tell they exist. The\nconsole needs them to offer \"un-hide\", and it is the only surface that does.",
         "operationId": "getLibrary",
         "parameters": [
           {
@@ -1052,7 +1082,7 @@
           "library"
         ],
         "summary": "Fetch one cover-art image for a library entry",
-        "description": "Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams\nthe image bytes. Any id stored in the host's catalog (manual entries, provider-synced entries,\nand a library plugin's claimed-store entries) serves its local art file. A Steam title falls back\nto the in-host scanner's resolver: the host's own local Steam cache first (exact — it's what the\nuser's Steam client already shows for it), the public Steam CDN's flat URL convention second\n(newer titles' CDN assets can live at a per-asset-hash path the host can't predict, in which case\nthis 404s and the client falls through to its next art candidate).",
+        "description": "Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams\nthe image bytes. Any id stored in the host's catalog (manual entries, provider-synced entries,\nand a library plugin's claimed-store entries) serves its local art file; anything else 404s and\nthe client falls through to its next art candidate.\n\nThe host fetches nothing here. Art a plugin published as an `http(s)` URL is fetched by the\nclient directly — this proxy exists for the *local* files a plugin finds on the host's own disk\n(a launcher's cover cache), which a client has no way to read.",
         "operationId": "getLibraryArt",
         "parameters": [
           {
@@ -1380,7 +1410,7 @@
           "library"
         ],
         "summary": "Replace a provider's library entries (declarative reconcile)",
-        "description": "Atomically replaces the full entry set owned by `{provider}` (RFC §8): the payload is the\nprovider's desired list, keyed by its own stable `external_id` — the host diffs, keeps each\nsurviving title's host id stable across reconciles, drops orphans, and never touches manual\nentries or other providers'. An empty array removes everything the provider owns. Emits\n`library.changed` with the provider as `source`.\n\n`?store=` additionally **claims** that store for the provider: its entries then surface with\ndeterministic `<store>:<external_id>` ids and the store's own badge, instead of opaque\n`custom:<id>` ones — which is what lets a library plugin reproduce the entries an in-host scanner\nused to produce, right down to the GameStream app ids and client-side art caches. One provider\nper store; a second claimant gets 409. While a claim is held the matching built-in scanner is\nsuppressed, so the two never double-list. The claim is released by `DELETE`, not by an empty\nreconcile (a store can legitimately have zero installed titles).",
+        "description": "Atomically replaces the full entry set owned by `{provider}` (RFC §8): the payload is the\nprovider's desired list, keyed by its own stable `external_id` — the host diffs, keeps each\nsurviving title's host id stable across reconciles, drops orphans, and never touches manual\nentries or other providers'. An empty array removes everything the provider owns. Emits\n`library.changed` with the provider as `source`.\n\n`?store=` additionally **claims** that store for the provider: its entries then surface with\ndeterministic `<store>:<external_id>` ids and the store's own badge, instead of opaque\n`custom:<id>` ones — which is what let a library plugin reproduce the entries the in-host scanner\nused to produce, right down to the GameStream app ids and client-side art caches, and is why\nremoving those scanners changed nothing downstream. One provider per store; a second claimant\ngets 409. The claim is released by `DELETE`, not by an empty reconcile (a store can legitimately\nhave zero installed titles).",
         "operationId": "reconcileProviderEntries",
         "parameters": [
           {
@@ -1538,8 +1568,8 @@
         "tags": [
           "library"
         ],
-        "summary": "List the library scanners",
-        "description": "The installed-store scanners this host supports — the list is platform-dependent (Steam\neverywhere; Lutris + Heroic on Linux; Epic, GOG, and Xbox/Game Pass on Windows), so the console\nrenders a toggle only for scanners that can do anything here. Scanners default to enabled;\ndisabling one hides its titles from every library surface from the next read. The user-curated\ncustom store is not a scanner and is always on.",
+        "summary": "List the library sources",
+        "description": "Every game source on this host with its enable state — one row per installed library plugin\n(Steam, Lutris, Heroic, Epic, GOG, Xbox, Playnite, ROM managers, …), so the list reflects what\nthe operator has actually installed rather than what this build happens to support. Sources\ndefault to enabled; disabling one hides its titles from every library surface from the next\nread. The user-curated custom store is not a source and is always on.\n\nOlder hosts (≤ v0.27.x) also listed the six scanners built into the host binary, with\n`origin: \"builtin\"`. Those are gone; every row now reports `origin: \"plugin\"`.",
         "operationId": "listLibraryScanners",
         "responses": {
           "200": {
@@ -1573,8 +1603,8 @@
         "tags": [
           "library"
         ],
-        "summary": "Enable or disable a library scanner",
-        "description": "Persists the toggle and applies it from the next library read (no restart). Disabling a scanner\nhides its titles everywhere — the console grid, native clients, and the GameStream app list —\nand re-enabling brings them straight back (nothing is deleted; the scan just runs again). Emits\n`library.changed` with the scanner id as `source` when the state changed.",
+        "summary": "Enable or disable a library source",
+        "description": "Persists the toggle and applies it from the next library read (no restart). Disabling a source\nhides its titles everywhere — the console grid, native clients, and the GameStream app list —\nand re-enabling brings them straight back. Nothing is deleted: the plugin may keep reconciling\nwhile its source is off, and those entries simply aren't surfaced. Emits `library.changed` with\nthe source id as `source` when the state changed.",
         "operationId": "setLibraryScanner",
         "parameters": [
           {
@@ -1767,6 +1797,56 @@
             }
           }
         }
+      },
+      "delete": {
+        "tags": [
+          "native"
+        ],
+        "summary": "Unpair every native client",
+        "description": "The collection form of [`unpair_native_client`]: empties the punktfunk/1 trust store in ONE\npersisted write (not a loop of them — a failure partway would leave a half-emptied store), and\nends every live native session the removed clients own.\n\nIdempotent, hence a 200 rather than the single unpair's 204/404: an already-empty store\nsatisfies the request, and the count still tells the operator what it meant.",
+        "operationId": "unpairAllNativeClients",
+        "responses": {
+          "200": {
+            "description": "Every native client unpaired (possibly none)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnpairAllResult"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Could not persist the trust store",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Native host not enabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/api/v1/native/clients/{fingerprint}": {
@@ -5397,7 +5477,7 @@
                   "string",
                   "null"
                 ],
-                "description": "The external provider owning this entry (custom-store entries synced by a provider\nplugin, RFC §8) — `None` for installed-store titles and manual custom entries. The\nconsole uses it for attribution; `GET /library?provider=` filters on it."
+                "description": "The external provider owning this entry (entries synced by a provider plugin, RFC §8) —\n`None` only for the manual entries the operator typed in. The console uses it for\nattribution; `GET /library?provider=` filters on it."
               },
               "role": {
                 "$ref": "#/components/schemas/GameRole",
@@ -7143,7 +7223,7 @@
           },
           "origin": {
             "$ref": "#/components/schemas/SourceOrigin",
-            "description": "Where the source comes from: `builtin` (a scanner in this host build) or `plugin`."
+            "description": "Where the source comes from. Always `plugin` from this host build onward — see\n[`SourceOrigin`]."
           },
           "provider": {
             "type": [
@@ -7163,7 +7243,7 @@
         "properties": {
           "enabled": {
             "type": "boolean",
-            "description": "Whether the scanner should run on this host."
+            "description": "Whether this source should contribute titles on this host."
           }
         }
       },
@@ -7687,6 +7767,22 @@
           }
         }
       },
+      "UnpairAllResult": {
+        "type": "object",
+        "description": "What a bulk unpair removed. Shared by the two collection DELETEs (`/clients` and\n`/native/clients`) so the console sees one schema across both pairing planes.\n\nA count rather than 204: \"unpair everything\" is idempotent, so an empty store is a success, and\nthe operator still wants to be told whether that meant three devices or none.",
+        "required": [
+          "unpaired"
+        ],
+        "properties": {
+          "unpaired": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Clients removed from the trust store — 0 when nothing was paired.",
+            "example": 3,
+            "minimum": 0
+          }
+        }
+      },
       "UpdateJobInfo": {
         "type": "object",
         "description": "A running apply job (or a spawned installer that hasn't resolved yet).",
@@ -7958,7 +8054,7 @@
     },
     {
       "name": "library",
-      "description": "Game library: installed-store titles (Steam) plus user-curated custom entries"
+      "description": "Game library: the titles each installed library plugin syncs, plus user-curated custom entries"
     },
     {
       "name": "stats",

ci/arch-ci.Dockerfile

@@ -48,6 +48,11 @@ RUN pacman -Syu --noconfirm --needed \
         hwdata luajit seatd sdl2-compat vulkan-icd-loader \
         xcb-util-errors xcb-util-wm xorg-xwayland \
         meson glm wayland-protocols benchmark libxcursor \
+        # mold: link-phase accelerator (sccache cannot cache linking). makepkg links the release
+        # host, client, worker and tray on every arch.yml run. Wired via cargo-config-mold.toml
+        # below. It does NOT affect the gamescope companion leg — that is meson + its own linker,
+        # and its `-static-libstdc++` link is untouched.
+        mold \
     && pacman -Scc --noconfirm
 
 # bun builds the punktfunk-web console + the punktfunk-scripting runner AND is vendored
@@ -64,3 +69,16 @@ ARG SCCACHE_VERSION=0.10.0
 RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
     | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
     && sccache --version
+
+# CARGO_HOME is declared here only so this image agrees with what arch.yml already sets at job
+# level (and so `cargo` finds the config below when the image is used by hand). The workflow still
+# passes CARGO_HOME explicitly across the `sudo -u builder env …` boundary, which strips ambient
+# env — that is why the C/C++ sccache wiring has to be re-exported there by name while THIS file,
+# being a file, crosses the boundary for free.
+ENV CARGO_HOME=/usr/local/cargo
+RUN mkdir -p /usr/local/cargo && chmod -R a+w /usr/local/cargo
+
+# Link x86_64 with mold — see cargo-config-mold.toml's header for the rustflags traps, and
+# rust-ci.Dockerfile for why the `mold --version` assertion sits next to the COPY.
+COPY cargo-config-mold.toml /usr/local/cargo/config.toml
+RUN mold --version && test -r /usr/local/cargo/config.toml

ci/cargo-config-mold.toml

@@ -0,0 +1,41 @@
+# Installed as $CARGO_HOME/config.toml in every Linux CI builder image (ci/*.Dockerfile).
+#
+# WHAT: link the x86_64 Linux targets with mold instead of GNU ld. Linking is the one phase of a
+# Rust build that sccache CANNOT cache — every job relinks punktfunk-host, punktfunk-client-linux,
+# punktfunk-client-session, punktfunk-cli, pf-update and punktfunk-encode-worker from scratch on
+# every run, and the packaging legs (deb/rpm/arch) do it for release binaries with full debug info.
+# mold is the only lever that touches that phase.
+#
+# ⚠ THE TRAP THIS FILE HAS TO STAY CLEAR OF — read before editing, and before adding rustflags
+# anywhere else in this repo:
+#
+#   1. A `RUSTFLAGS` ENVIRONMENT VARIABLE OVERRIDES CONFIG RUSTFLAGS ENTIRELY. It does not merge
+#      and it does not append. Any job that sets RUSTFLAGS silently loses mold here — it still
+#      builds, just with the default linker. Never "simplify" this file into a RUSTFLAGS export.
+#      (This trap used to be far worse: the workspace .cargo/config.toml carried aarch64
+#      `--cfg aes_armv8` / `--cfg polyval_armv8`, worth ~10x on the decrypt path, and an override
+#      dropped those too. The RustCrypto aes 0.9 / polyval 0.7 bump retired both cfgs — see the
+#      tombstone in .cargo/config.toml — so today only mold is at stake here.)
+#
+#   2. CONFIG FILES MERGE PER KEY, HIGHEST-PRECEDENCE FILE WINS — they do not concatenate. The
+#      workspace's .cargo/config.toml outranks this one ($CARGO_HOME is the LOWEST precedence).
+#      Today that is harmless because the workspace file defines NO rustflags at all and this one
+#      defines only `target.x86_64-unknown-linux-gnu.rustflags`. But the moment someone adds an
+#      x86_64 rustflags entry to the workspace .cargo/config.toml, IT WINS and mold silently stops
+#      being used here. If that ever happens, move the link-arg into that file instead of
+#      duplicating it.
+#
+#   3. aarch64 IS DELIBERATELY NOT WIRED. The cross image links with aarch64-linux-gnu-gcc against a
+#      multiarch sysroot (ci/rust-ci-arm64cross.Dockerfile); pointing that driver at mold is a
+#      separate thing to prove, and those legs are already the fast ones (~1.5 min of clippy, ~5 min
+#      for the arm64 .deb). Add it only with a measurement, and in a commit of its own.
+#
+# Requires GCC >= 12.1 (or clang) for `-fuse-ld=mold`; every base here ships far newer. mold itself
+# is installed in the same Dockerfile layer that copies this file, so an image can never carry the
+# flag without the linker — see the `mold --version` assertion there.
+#
+# NOTE this affects the HOST-targeted compiles of build scripts and proc macros too (they are
+# x86_64-unknown-linux-gnu), which is exactly what we want: those link constantly and are pure
+# overhead.
+[target.x86_64-unknown-linux-gnu]
+rustflags = ["-C", "link-arg=-fuse-ld=mold"]

ci/fedora-rpm.Dockerfile

@@ -22,6 +22,12 @@ RUN dnf -y install \
       rpm-build rpmdevtools systemd-rpm-macros git tar gzip nodejs unzip \
       # build toolchain + bindgen
       gcc gcc-c++ clang clang-devel cmake nasm pkgconf-pkg-config curl ca-certificates \
+      # mold: link-phase accelerator (sccache cannot cache linking). This image links the release
+      # host, client, worker and tray on every rpm.yml run, TWICE per push (f43 + f44). Wired via
+      # cargo-config-mold.toml below. Note the linker DRIVER is unchanged — still gcc, so Fedora's
+      # default `-Wl,--build-id` still reaches the link and rpmbuild's debuginfo extraction (which
+      # hard-requires a build-id) behaves exactly as before; mold implements --build-id natively.
+      mold \
       # ffmpeg (NVENC), capture/audio/display link deps
       ffmpeg-devel pipewire-devel wayland-devel libxkbcommon-devel opus-devel \
       mesa-libGL-devel mesa-libgbm-devel \
@@ -76,3 +82,8 @@ ARG SCCACHE_VERSION=0.10.0
 RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
     | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
     && sccache --version
+
+# Link x86_64 with mold — see cargo-config-mold.toml's header for the rustflags traps, and
+# rust-ci.Dockerfile for why the `mold --version` assertion sits next to the COPY.
+COPY cargo-config-mold.toml /usr/local/cargo/config.toml
+RUN mold --version && test -r /usr/local/cargo/config.toml

ci/gamescope-trixie.Dockerfile

@@ -0,0 +1,83 @@
+# Builder for the `punktfunk-gamescope` .deb — Debian 13 (trixie).
+#
+# WHY THIS EXISTS, AND WHY IT IS NOT THE NOBLE IMAGE:
+# The gamescope .deb was built in the host job's Ubuntu 24.04 (noble) image, and it has NEVER once
+# succeeded there — v0.26.0 and v0.27.0 both shipped with no gamescope package while the release
+# notes and docs-site said it was apt-installable. The failure is structural, not a flaky dep:
+#
+#   wlroots| Dependency wayland-server found: NO found 1.22.0 but need: '>=1.23.1'
+#   subprojects/wlroots/meson.build:96:17: ERROR: Dependency 'wayland-server' is required but not found
+#
+# Our gamescope pin vendors wlroots 0.19.3, which floors wayland-server at 1.23.1. Noble ships
+# 1.22.0 and will never ship more — so no amount of `apt-get install` in that image can fix it.
+# Noble also has no `libxcb-errors-dev` at all and only libdisplay-info 0.1.1 (the tree wants 0.2).
+#
+# Debian 13 ships wayland 1.23.1 exactly, libxcb-errors 1.0.1 and libdisplay-info 0.2.0 — the
+# oldest apt distro the tree actually builds on. Building HERE rather than on Ubuntu 26.04
+# (wayland 1.24, libdisplay-info 0.3) is deliberate twice over: it keeps the glibc floor low, and
+# it stays on the libdisplay-info 0.2 line the pin was developed against.
+#
+# WHAT THE RESULTING BINARY RUNS ON — verified by building it and reading the ELF:
+#   * glibc floor  GLIBC_2.38  (the C++ runtime is linked statically by
+#     build-punktfunk-gamescope.sh, so libstdc++ never enters the NEEDED list)
+#   * NEEDED       libwayland-server.so.0 / libwayland-client.so.0 — wlroots 0.19 calls symbols
+#                  added in 1.23.1, so THAT, not glibc, is the real floor.
+#   ⇒ Debian 13 (1.23.1) and Ubuntu 26.04 (1.24.0) YES; Ubuntu 24.04 (1.22.0) NO — and 24.04
+#     could not run this binary however it was built, so nothing is lost by moving off noble.
+#
+# Rebuilt+pushed by .gitea/workflows/docker.yml (matrix: punktfunk-gamescope-trixie); consumed by
+# the `build-publish-gamescope` job in .gitea/workflows/deb.yml. Bootstrap: like rust-ci-noble, the
+# first deb.yml run after this image is added needs the image to already exist — seed it once by
+# hand (docker build -f ci/gamescope-trixie.Dockerfile -t <registry>/punktfunk-gamescope-trixie:latest ci
+# && docker push …) before that job can run.
+FROM debian:trixie
+ENV DEBIAN_FRONTEND=noninteractive
+
+# nodejs is not optional: the Gitea runner executes the JS actions (checkout/cache) INSIDE this
+# container, so an image without it fails before the first `run:` step ever starts.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential pkg-config cmake meson ninja-build git curl ca-certificates nodejs \
+    # .deb assembly (dpkg-shlibdeps computes the runtime Depends from the built binary)
+    dpkg-dev \
+    # shader compilers gamescope's meson looks for
+    glslc glslang-tools \
+    # wayland + protocols. libwayland-dev 1.23.1 is the whole reason this image is Debian.
+    libwayland-dev wayland-protocols \
+    # gamescope's own dependency set. `apt-get build-dep gamescope` is useless here — Debian has
+    # no gamescope package to derive it from — so the tree's needs are named outright, exactly as
+    # the noble job had to. Kept as ONE transaction on purpose: in an image build a missing name
+    # SHOULD fail loudly at build time, unlike the workflow's per-package best-effort loop where a
+    # rename would have silently dropped a dep into a warning nobody reads.
+    libxdamage-dev libxcomposite-dev libxrender-dev libxext-dev libxxf86vm-dev \
+    libxtst-dev libx11-dev libxres-dev libxmu-dev libxcursor-dev libxi-dev \
+    libxfixes-dev libxkbcommon-dev libxkbcommon-x11-dev libcap-dev libdrm-dev \
+    # x11-xcb is needed by the VULKAN WSI LAYER (layer/meson.build), not by the compositor — so it
+    # was not missed until v0.28.1 started building the layer beside the binary. Debian is the only
+    # channel that needs it named: Arch's libx11 and Fedora's libX11-devel both carry x11-xcb.pc
+    # themselves, while Debian splits it into its own -dev package.
+    libx11-xcb-dev \
+    libinput-dev libudev-dev libpipewire-0.3-dev libseat-dev libsdl2-dev \
+    libluajit-5.1-dev libavif-dev libdecor-0-dev hwdata libglm-dev libbenchmark-dev \
+    libvulkan-dev libxcb1-dev libxcb-composite0-dev libxcb-xfixes0-dev libxcb-res0-dev \
+    libxcb-ewmh-dev libxcb-icccm4-dev libxcb-errors-dev libxcb-shape0-dev \
+    libpixman-1-dev libdisplay-info-dev libgbm-dev libegl-dev xwayland \
+    && rm -rf /var/lib/apt/lists/*
+
+# Assert the ONE version that decides whether this image can do its job, so a future Debian base
+# bump that regressed it fails HERE (loudly, at image build) instead of in a deb.yml run whose
+# gamescope failure has historically been a `::warning::` nobody saw.
+RUN set -eux; \
+    have="$(pkg-config --modversion wayland-server)"; \
+    pkg-config --atleast-version=1.23.1 wayland-server \
+      || { echo "wayland-server $have < 1.23.1 — the vendored wlroots will not configure" >&2; exit 1; }; \
+    echo "wayland-server $have — OK"
+
+# The layer's own floor, asserted for the same reason: a missing x11-xcb does not fail the
+# COMPOSITOR build, it fails `layer/meson.build` — and the layer is the only route to an HDR10
+# swapchain for a nested game, so losing it silently ships a package that looks healthy and denies
+# every game HDR. This is exactly how v0.28.1's deb leg broke, one release after the layer was
+# added; assert it here so the next dep the layer grows fails at image build, not mid-release.
+RUN set -eux; \
+    pkg-config --exists x11-xcb \
+      || { echo "x11-xcb absent — the Vulkan WSI layer will not configure (need libx11-xcb-dev)" >&2; exit 1; }; \
+    echo "x11-xcb $(pkg-config --modversion x11-xcb) — OK"

ci/rust-ci-noble.Dockerfile

@@ -26,6 +26,9 @@ ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install -y --no-install-recommends \
     # toolchain + bindgen; nodejs runs the JS actions (checkout/cache); unzip for the rustup installer's deps
     build-essential clang libclang-dev pkg-config cmake git curl ca-certificates nodejs unzip \
+    # mold: link-phase accelerator (sccache cannot cache linking). This image links the release
+    # host + encode worker on every deb.yml run. Wired via cargo-config-mold.toml below.
+    mold \
     # .deb assembly: dpkg-shlibdeps/dpkg-deb; patchelf repoints the binary's rpath at the bundled FFmpeg
     dpkg-dev patchelf \
     # FFmpeg 8 build deps: nasm (asm), VAAPI (libva/libdrm) so the built libav* keep the AMD/Intel
@@ -99,3 +102,10 @@ ARG SCCACHE_VERSION=0.10.0
 RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
     | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
     && sccache --version
+
+# Link x86_64 with mold — see cargo-config-mold.toml's header for the rustflags traps, and
+# rust-ci.Dockerfile for why the `mold --version` assertion sits next to the COPY.
+# ⚠ This does NOT touch the from-source FFmpeg built above: that is a plain ./configure && make in
+# an earlier layer, linked by GNU ld exactly as before. Only cargo's links move to mold.
+COPY cargo-config-mold.toml /usr/local/cargo/config.toml
+RUN mold --version && test -r /usr/local/cargo/config.toml

ci/rust-ci.Dockerfile

@@ -13,6 +13,9 @@ ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install -y --no-install-recommends \
     # toolchain + bindgen; nodejs runs the JS actions (checkout/cache); unzip is for the bun installer
     build-essential clang libclang-dev pkg-config cmake git curl ca-certificates nodejs unzip \
+    # mold: the link-phase accelerator. Linking is the one thing sccache cannot cache, and this
+    # image relinks the whole workspace on every job. Wired via cargo-config-mold.toml below.
+    mold \
     # ffmpeg-next 9, built against whatever libav* 26.04 ships (FFmpeg 8 / libavcodec 62 today).
     # The crate major is a CEILING — ffmpeg-sys-next 9 spans libavcodec 56..63 — so this image does
     # not need to move in lockstep with Arch's FFmpeg 9; it just links what the distro has.
@@ -61,3 +64,12 @@ ARG SCCACHE_VERSION=0.10.0
 RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
     | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
     && sccache --version
+
+# Link x86_64 with mold (see the file's own header for the rustflags-precedence traps).
+#
+# The assertion is the point: an image carrying the flag but NOT the linker would fail every cargo
+# invocation in every consuming job, which is a catastrophic way to find out that a base image
+# renamed the package. `mold --version` fails the docker build instead, so nothing is pushed and
+# `:latest` keeps pointing at the previous working image — consumers never see it.
+COPY cargo-config-mold.toml /usr/local/cargo/config.toml
+RUN mold --version && test -r /usr/local/cargo/config.toml

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

@@ -32,20 +32,12 @@ import androidx.compose.animation.core.LinearEasing
 import androidx.compose.animation.core.animateFloatAsState
 import androidx.compose.animation.core.tween
 import androidx.compose.foundation.background
-import androidx.compose.foundation.clickable
 import androidx.compose.foundation.layout.Box
-import androidx.compose.foundation.layout.Row
-import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.aspectRatio
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
-import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.shape.RoundedCornerShape
-import androidx.compose.material.icons.Icons
-import androidx.compose.material.icons.filled.Mic
-import androidx.compose.material.icons.filled.MicOff
-import androidx.compose.material3.Icon
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
@@ -57,7 +49,6 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.alpha
-import androidx.compose.ui.draw.clip
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.input.pointer.pointerInput
 import androidx.compose.ui.platform.LocalContext
@@ -130,12 +121,12 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
     // it, and survives the same recreate because the composition outlives the surface.
     var micMuted by remember(handle) { mutableStateOf(false) }
     // Whether a capture is actually RUNNING, not merely wanted — set from surfaceCreated on what
-    // nativeMicActive reports. A device that refused every AAudio input rung gets no mute control
-    // rather than one that lies about a mic being heard.
+    // nativeMicActive reports. A device that refused every AAudio input rung gets no mute chord and
+    // no chord line in the start banner, rather than an offer to mute a mic nobody is hearing.
     var micRunning by remember(handle) { mutableStateOf(false) }
-    // Transient confirmation of a mic-chord toggle (null = nothing showing). Only the gamepad path
-    // needs it: the touch button confirms itself by changing under the finger, but a chord has no
-    // on-screen state of its own, and "did that register?" is exactly the doubt to answer.
+    // Transient confirmation of a mic-chord toggle (null = nothing showing). With no standing mic
+    // element on screen, this is mute's only feedback: a chord has no on-screen state of its own,
+    // and "did that register?" is exactly the doubt to answer.
     var micHint by remember { mutableStateOf<String?>(null) }
     LaunchedEffect(micHint) {
         if (micHint != null) {
@@ -413,9 +404,9 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
         // Show a "hold to quit" hint the moment the chord completes (the router debounces the actual
         // exit); it clears when the buttons release early or the hold elapses. Runs on the main thread.
         router.onExitArmed = { armed -> exitArming = armed }
-        // Select + Y toggles the mic — the couch reach for the on-screen mute button, which a
-        // gamepad/TV user has no pointer for. Ignored when no capture is running (there is nothing
-        // to mute, and claiming otherwise would be the lie the control exists to avoid).
+        // Select + Y toggles the mic — with no on-screen mute element, this chord is the whole of
+        // the control. Ignored when no capture is running (there is nothing to mute, and a hint
+        // saying "Microphone muted" over a mic nobody opened would be a lie).
         // A captured Sony pad whose motion this session cannot carry. Fires once per pad, at the
         // moment it is claimed, on the main thread.
         router.onMotionUnreachable = { motionHint = true }
@@ -825,7 +816,7 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                                     ?: (runCatching { context.display }.getOrNull()?.refreshRate ?: 0f)
                                         .roundToInt(),
                             )
-                            NativeBridge.nativeStartAudio(handle, lowLatencyMode)
+                            NativeBridge.nativeStartAudio(handle, lowLatencyMode, isTv)
                             if (micWanted) {
                                 val sessionId =
                                     NativeBridge.nativeStartMic(handle, initialSettings.echoCancel)
@@ -981,19 +972,12 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                 }
             },
         )
-        // Mic mute, LAST in the stack — the one in-stream control, so unlike the purely visual
-        // overlays above it has to sit on top of the gesture layer to receive its own taps (it
-        // costs the stream that small corner of touch area, which is why it exists only while a
-        // capture actually runs). On TV it is the indicator alone: the Select + Y chord is the
-        // control there, and a focusable button would fight the game for the D-pad.
-        if (micRunning && (micMuted || !isTv)) {
-            MicMuteControl(
-                muted = micMuted,
-                onToggle = if (isTv) null else ({ setMicMuted(!micMuted) }),
-                modifier = Modifier.align(Alignment.TopEnd).padding(12.dp),
-            )
-        }
-        // Chord confirmation (gamepad/TV) — the counterpart to the button changing under a finger.
+        // No standing mic element here: the in-stream mute control is deliberately absent until the
+        // on-screen overlay UI lands and can carry it as one of its controls. Mute itself is intact
+        // — the Select + Y chord toggles it, and the hint below is what confirms the toggle.
+        // Chord confirmation (gamepad/TV) — mute has no standing indicator, so this is the whole
+        // of its feedback: a toggle that showed nothing at all would be indistinguishable from one
+        // that never registered.
         micHint?.let { MicChordHint(it, Modifier.align(Alignment.TopCenter).padding(top = 16.dp)) }
         // Bottom, not top: this can coincide with a mic-chord confirmation or the exit cue, and a
         // notice landing on top of one of those would cost the user both.
@@ -1030,47 +1014,8 @@ private fun releaseMicEffects(effects: MutableList<AudioEffect>) {
 }
 
 /**
- * The in-stream mic control and its muted indicator, in one element: a dim mic glyph while the
- * uplink is live, a red **Muted** badge while it isn't — so the state that matters is the loud one,
- * readable at couch distance and impossible to mistake for the stream's own picture.
- *
- * [onToggle] `null` makes it a pure indicator (the TV/gamepad surface, where the Select + Y chord
- * is the control); non-null makes the badge itself the touch target. Rendering it at all is the
- * caller's decision — it means a capture is genuinely running.
- */
-@Composable
-private fun MicMuteControl(muted: Boolean, onToggle: (() -> Unit)?, modifier: Modifier = Modifier) {
-    val shape = RoundedCornerShape(10.dp)
-    Row(
-        modifier = modifier
-            .clip(shape)
-            .background(if (muted) Color(0xE0B3261E) else Color.Black.copy(alpha = 0.45f))
-            .then(if (onToggle != null) Modifier.clickable(onClick = onToggle) else Modifier)
-            .padding(horizontal = 12.dp, vertical = 10.dp),
-        verticalAlignment = Alignment.CenterVertically,
-    ) {
-        Icon(
-            imageVector = if (muted) Icons.Filled.MicOff else Icons.Filled.Mic,
-            // Spoken state first, then the action — a talkback user needs to know they are muted
-            // before they need to know how to stop being muted.
-            contentDescription = if (muted) {
-                "Microphone muted. Activate to unmute."
-            } else {
-                "Microphone live. Activate to mute."
-            },
-            tint = Color.White,
-            modifier = Modifier.size(20.dp),
-        )
-        if (muted) {
-            Spacer(Modifier.width(6.dp))
-            Text("Muted", color = Color.White, fontSize = 14.sp)
-        }
-    }
-}
-
-/**
- * Transient confirmation that the mic chord (Select + Y) registered. The badge above already says
- * *muted*, but nothing on screen says *un*muted — and "did that press do anything?" is the whole
+ * Transient confirmation that the mic chord (Select + Y) registered. Nothing else on screen says
+ * *muted* or *un*muted, so this pill carries both — "did that press do anything?" is the whole
  * doubt a chord with no button under the finger creates. Same pill vocabulary as the other
  * in-stream cues; the caller clears it after a beat.
  */

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

@@ -0,0 +1,55 @@
+package io.unom.punktfunk.screenshots
+
+import androidx.activity.ComponentActivity
+import androidx.compose.ui.test.junit4.createAndroidComposeRule
+import androidx.compose.ui.test.onRoot
+import com.github.takahirom.roborazzi.captureRoboImage
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.GraphicsMode
+
+/**
+ * The same Roborazzi harness as ScreenshotTest, at Android TV geometry: 960×540dp in the
+ * `television` UI mode at xhdpi (2.0×) = 1920×1080 px — the Play Store's 16:9 TV screenshot size,
+ * captured 1:1 with no resampling. Only the screens that exist on a TV are shot here: the
+ * gamepad-console shell (what LEANBACK_LAUNCHER opens into) and the in-stream view. Files are
+ * prefixed `tv-` so the artifact separates the form factors.
+ */
+@RunWith(RobolectricTestRunner::class)
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+@Config(sdk = [36], qualifiers = "w960dp-h540dp-television-xhdpi")
+class TvScreenshotTest {
+    @get:Rule
+    val compose = createAndroidComposeRule<ComponentActivity>()
+
+    private val out = "build/outputs/roborazzi"
+
+    private fun shootRoot(name: String, content: @androidx.compose.runtime.Composable () -> Unit) {
+        compose.mainClock.autoAdvance = false
+        compose.setContent { ShotTheme(content) }
+        compose.mainClock.advanceTimeBy(800)
+        compose.onRoot().captureRoboImage("$out/tv-$name.png")
+    }
+
+    @Test
+    fun stream() = shootRoot("stream") { StreamScene(io.unom.punktfunk.StatsVerbosity.COMPACT) }
+
+    @Test
+    fun streamDetailed() =
+        shootRoot("stream-detailed") { StreamScene(io.unom.punktfunk.StatsVerbosity.DETAILED) }
+
+    @Test
+    fun consoleHome() = shootRoot("console-home") { ConsoleHomeScene() }
+
+    @Test
+    fun consoleSettings() = shootRoot("console-settings") { ConsoleSettingsScene() }
+
+    @Test
+    fun consoleControllers() = shootRoot("console-controllers") { ConsoleControllersScene() }
+
+    @Test
+    fun connectingConsole() = shootRoot("connecting-console") { ConnectConsoleScene() }
+}

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/NativeBridge.kt

@@ -302,12 +302,17 @@ object NativeBridge {
     external fun nativeSetVideoStatsEnabled(handle: Long, enabled: Boolean)
 
     /**
-     * Start host→client audio: Opus decode → jitter ring → AAudio (LowLatency), all in Rust.
+     * Start host→client audio: Opus decode → jitter ring → AAudio, all in Rust.
      * [lowLatencyMode] (the experimental toggle) additionally tags the stream usage=Game for the
      * HAL's game-audio routing. No-op if already started. Best-effort — a failure leaves video
      * streaming.
+     *
+     * [isTv] steers the AAudio open ladder: a TV box starts at Shared rather than betting the
+     * audio plane on an Exclusive/MMAP path whose routing we cannot verify from inside the
+     * process. Passed from `FEATURE_LEANBACK` (same source as [nativeStartVideo]) because the
+     * native side's own `ro.build.characteristics` check is not answered by every TV device.
      */
-    external fun nativeStartAudio(handle: Long, lowLatencyMode: Boolean)
+    external fun nativeStartAudio(handle: Long, lowLatencyMode: Boolean, isTv: Boolean)
 
     /** Stop + join the audio thread and close AAudio, without closing the session. No-op on `0`. */
     external fun nativeStopAudio(handle: Long)

clients/android/native/Cargo.toml

@@ -15,22 +15,41 @@ crate-type = ["cdylib"]
 
 [dependencies]
 # The whole protocol/transport/FEC/crypto + the embeddable NativeClient connector. `quic` pulls
-# the punktfunk/1 control plane (now ring-only — no aws-lc, see punktfunk-core/Cargo.toml).
+# the punktfunk/1 control plane, whose TLS runs on aws-lc-rs (see punktfunk-core/Cargo.toml) —
+# aws-lc-sys cross-compiles for all three ABIs with the NDK clang cargo-ndk already exports.
 punktfunk-core = { path = "../../../crates/punktfunk-core", features = ["quic"] }
-jni = "0.21"
+# 0.22, NOT 0.21 — and the version is load-bearing beyond currency: `rustls-platform-verifier`
+# (via quinn-proto, for Android cert verification) already depends on jni 0.22, so pinning 0.21
+# here compiled TWO jni copies into the one .so. Matching it collapses them and, with them, the
+# whole windows-rs 0.42 generation jni 0.21 dragged in behind `cfg(windows)` (windows-sys 0.45 —
+# the oldest crate in the tree — plus windows-targets 0.42.2 and its seven per-arch import libs)
+# and jni 0.21's `cesu8`: 11 crates, for a dependency that never even builds on Android.
+#
+# NOTE for whoever next tries to retire thiserror 1.0 or the jni-sys 0.3/0.4 split: jni is no
+# longer why they are here. Both now come solely from `vendor/ndk` 0.9.0 (thiserror 1.0.23,
+# jni-sys 0.3) and the crates.io `ndk-sys` 0.6 (jni-sys 0.3). jni-sys 0.3.1 is itself a facade
+# over 0.4.1, so the "split" cannot close until ndk + ndk-sys move — and ndk is vendored for one
+# visibility patch, so bumping its deps would mean rewriting the vendor rather than a version edit.
+jni = "0.22"
 log = "0.4"
 # LAN host discovery: browse the host's `_punktfunk._udp` mDNS advert — the SAME crate + service the
 # Linux/Windows clients use (`crates/pf-client-core/src/discovery.rs`), replacing Android's per-OEM
 # `NsdManager` system daemon with one tested browse path. Pure Rust (socket2/if-addrs/mio), so it
 # cross-compiles to the Android targets AND builds on the host (the JNI seam links into
 # `cargo build --workspace`). Kotlin keeps only the Wi-Fi `MulticastLock` + permission UX.
-mdns-sd = "0.20"
+mdns-sd = "0.21"
 
 # Android-only deps. Gated so `cargo build --workspace` on the Linux/macOS dev boxes + CI still
 # compiles this crate (as a host cdylib) — the Android-framework glue (logging, AMediaCodec + AAudio
 # via `ndk`, the Opus codec) is only pulled in for the real `*-linux-android` targets.
 [target.'cfg(target_os = "android")'.dependencies]
-android_logger = "0.14"
+# Default features only, DELIBERATELY: 0.15 added an opt-in `android-api-30` feature that routes
+# level filtering through `__android_log_is_loggable_len` so logcat's system-wide/process-wide
+# level overrides (`setprop log.tag.*`) are honoured. That symbol is API 30 and the feature
+# HARD-LINKS it — on our minSdk-28 floor (Android 9/10) `System.loadLibrary` would fail outright,
+# the same way ndk 0.9.0 hard-linking `AMediaCodec_setOnFrameRenderedCallback` broke every
+# pre-Android-13 device (see the `ndk-sys` note below). Do not enable it while minSdk is 28.
+android_logger = "0.15"
 # Feature bridge, no code here: punktfunk-core logs through `tracing`, but this client only
 # installs `android_logger` (a `log` backend). Core transport warnings (e.g. "UDP socket buffer
 # capped well below target") reach logcat only via tracing's "log" feature, which forwards events

clients/android/native/src/discovery.rs

@@ -16,9 +16,10 @@
 //! wrong, and 1 Hz is plenty for a host picker.
 
 use crate::session::jni_guard;
-use jni::objects::JObject;
+use jni::errors::LogErrorAndDefault;
+use jni::objects::{JObject, JString};
 use jni::sys::jlong;
-use jni::JNIEnv;
+use jni::EnvUnowned;
 use mdns_sd::{ResolvedService, ServiceDaemon, ServiceEvent};
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
@@ -200,9 +201,9 @@ fn resolve(info: &ResolvedService) -> Option<Host> {
 /// hold the Wi-Fi `MulticastLock` for the browse lifetime.
 ///
 /// [`nativeDiscoveryStop`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
 ) -> jlong {
     jni_guard(0, || match Discovery::start() {
@@ -214,13 +215,16 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoverySt
 /// `NativeBridge.nativeDiscoveryPoll(handle): String` — the current resolved-host snapshot,
 /// newline-joined records of `key␟name␟addr␟port␟fp␟pair␟mac␟os` (`␟` = U+001F). Empty string = no hosts /
 /// `0` handle. Poll ~1 Hz from the UI thread (cheap: a mutex lock + string build).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPoll<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     handle: jlong,
-) -> jni::sys::jstring {
-    jni_guard(std::ptr::null_mut(), || {
+) -> JString<'local> {
+    // `with_env` subsumes the `jni_guard` this used to carry: it catches panics at the boundary and
+    // `LogErrorAndDefault` logs then yields `JString::default()` — the null reference the old
+    // `std::ptr::null_mut()` default returned. Kotlin still sees a null String on failure.
+    env.with_env(|env| -> jni::errors::Result<JString<'local>> {
         let out = if handle == 0 {
             String::new()
         } else {
@@ -229,11 +233,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPo
             let d = unsafe { &*(handle as *const Discovery) };
             d.snapshot()
         };
-        match env.new_string(out) {
-            Ok(s) => s.into_raw(),
-            Err(_) => std::ptr::null_mut(),
-        }
+        env.new_string(out)
     })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeDiscoveryStop(handle)` — stop the browse, shut the daemon down and join its
@@ -245,9 +247,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPo
 ///
 /// [`nativeDiscoveryStart`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart
 /// [`nativeDiscoveryPoll`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPoll
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {

clients/android/native/src/feedback.rs

@@ -8,9 +8,10 @@
 //! compile on the host build too (parity with the input shims in [`crate::session`]).
 
 use crate::session::{jni_guard, SessionHandle};
+use jni::errors::LogErrorAndDefault;
 use jni::objects::{JByteBuffer, JObject};
 use jni::sys::{jint, jlong};
-use jni::JNIEnv;
+use jni::EnvUnowned;
 use punktfunk_core::quic::HidOutput;
 use std::time::Duration;
 
@@ -60,9 +61,9 @@ const TAG_HID_RAW: u8 = 0x05;
 /// closed (all packed values are positive, so `-1` stays unambiguous). Kotlin routes the command
 /// back to the controller holding that wire `pad` index (multi-pad rumble). Run from a Kotlin
 /// poll thread.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jlong {
@@ -99,96 +100,105 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
 ///   PlayerLeds → `[pad][0x02][bits]`            (len 3)
 ///   Trigger    → `[pad][0x03][which][effect…]`  (len 3 + effect.len())
 /// Returns the byte count written, or `-1` on timeout / session closed / buffer too small.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
-    env: JNIEnv,
+    mut env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     buf: JByteBuffer,
 ) -> jint {
     // Runs on a Kotlin poll thread, so a panic here would abort the process; guard the boundary.
+    //
+    // Deliberately `with_env_no_catch` INSIDE `jni_guard`, not the usual `with_env`: every error
+    // policy resolves a failure to `T::default()`, and `jint::default()` is 0 — a *valid* byte
+    // count — whereas this method's contract says -1. Letting the panic travel out to `jni_guard`
+    // keeps the -1 sentinel exact. Every non-panic failure path below likewise returns `Ok(-1)`
+    // rather than `Err`, so the policy's default is unreachable by construction.
     jni_guard(-1, || {
-        if handle == 0 {
-            return -1;
-        }
-        // SAFETY: live handle per the contract; next_hidout is &self on the Sync connector.
-        let h = unsafe { &*(handle as *const SessionHandle) };
-        let ev = match h.client.next_hidout(PULL_TIMEOUT) {
-            Ok(ev) => ev,
-            Err(_) => return -1, // timeout or closed — Kotlin loops
-        };
+        env.with_env_no_catch(|env| -> jni::errors::Result<jint> {
+            if handle == 0 {
+                return Ok(-1);
+            }
+            // SAFETY: live handle per the contract; next_hidout is &self on the Sync connector.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            let ev = match h.client.next_hidout(PULL_TIMEOUT) {
+                Ok(ev) => ev,
+                Err(_) => return Ok(-1), // timeout or closed — Kotlin loops
+            };
 
-        // The caller passes a direct ByteBuffer (allocateDirect) so we write its backing store directly.
-        let cap = match env.get_direct_buffer_capacity(&buf) {
-            Ok(c) => c,
-            Err(_) => return -1,
-        };
-        let ptr = match env.get_direct_buffer_address(&buf) {
-            Ok(p) if !p.is_null() => p,
-            _ => return -1,
-        };
-        // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call.
-        let out = unsafe { std::slice::from_raw_parts_mut(ptr, cap) };
+            // The caller passes a direct ByteBuffer (allocateDirect) so we write its backing store directly.
+            let cap = match env.get_direct_buffer_capacity(&buf) {
+                Ok(c) => c,
+                Err(_) => return Ok(-1),
+            };
+            let ptr = match env.get_direct_buffer_address(&buf) {
+                Ok(p) if !p.is_null() => p,
+                _ => return Ok(-1),
+            };
+            // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call.
+            let out = unsafe { std::slice::from_raw_parts_mut(ptr, cap) };
 
-        // out[0] = wire pad index; out[1] = kind tag; the rest is the per-kind payload.
-        let n = match ev {
-            HidOutput::Led { pad, r, g, b } => {
-                if cap < 5 {
-                    return -1;
+            // out[0] = wire pad index; out[1] = kind tag; the rest is the per-kind payload.
+            let n = match ev {
+                HidOutput::Led { pad, r, g, b } => {
+                    if cap < 5 {
+                        return Ok(-1);
+                    }
+                    out[0] = pad;
+                    out[1] = TAG_LED;
+                    out[2] = r;
+                    out[3] = g;
+                    out[4] = b;
+                    5
                 }
-                out[0] = pad;
-                out[1] = TAG_LED;
-                out[2] = r;
-                out[3] = g;
-                out[4] = b;
-                5
-            }
-            HidOutput::PlayerLeds { pad, bits } => {
-                if cap < 3 {
-                    return -1;
+                HidOutput::PlayerLeds { pad, bits } => {
+                    if cap < 3 {
+                        return Ok(-1);
+                    }
+                    out[0] = pad;
+                    out[1] = TAG_PLAYER_LEDS;
+                    out[2] = bits;
+                    3
                 }
-                out[0] = pad;
-                out[1] = TAG_PLAYER_LEDS;
-                out[2] = bits;
-                3
-            }
-            HidOutput::Trigger { pad, which, effect } => {
-                let n = 3 + effect.len();
-                if cap < n {
-                    return -1; // the raw DS5 trigger block is ~11 bytes; Kotlin allocates 64
+                HidOutput::Trigger { pad, which, effect } => {
+                    let n = 3 + effect.len();
+                    if cap < n {
+                        return Ok(-1); // the raw DS5 trigger block is ~11 bytes; Kotlin allocates 64
+                    }
+                    out[0] = pad;
+                    out[1] = TAG_TRIGGER;
+                    out[2] = which;
+                    out[3..n].copy_from_slice(&effect);
+                    n
                 }
-                out[0] = pad;
-                out[1] = TAG_TRIGGER;
-                out[2] = which;
-                out[3..n].copy_from_slice(&effect);
-                n
-            }
-            HidOutput::TrackpadHaptic { .. } => {
-                // Steam Controller trackpad-coil haptics — no Android equivalent; drop it (motor
-                // rumble already rides the universal 0xCA plane).
-                return -1;
-            }
-            HidOutput::HidRaw { pad, kind, data } => {
-                // As-is SC2 passthrough: the host's hidraw consumer (Steam) wrote this report to
-                // the virtual pad; Kotlin replays it verbatim on the physical controller.
-                // `[pad][0x05][kind][report…]` — kind 0 = output report, 1 = feature report.
-                let n = 3 + data.len();
-                if cap < n {
-                    return -1; // reports are ≤ 64 bytes; Kotlin allocates 128
+                HidOutput::TrackpadHaptic { .. } => {
+                    // Steam Controller trackpad-coil haptics — no Android equivalent; drop it (motor
+                    // rumble already rides the universal 0xCA plane).
+                    return Ok(-1);
                 }
-                out[0] = pad;
-                out[1] = TAG_HID_RAW;
-                out[2] = kind;
-                out[3..n].copy_from_slice(&data);
-                n
-            }
-            HidOutput::AudioCtl { .. } => {
-                // DS5 pad-audio routing/volumes — no Android replay path yet (the 0xD1 sample
-                // plane isn't rendered here either); drop it like TrackpadHaptic.
-                return -1;
-            }
-        };
-        n as jint
+                HidOutput::HidRaw { pad, kind, data } => {
+                    // As-is SC2 passthrough: the host's hidraw consumer (Steam) wrote this report to
+                    // the virtual pad; Kotlin replays it verbatim on the physical controller.
+                    // `[pad][0x05][kind][report…]` — kind 0 = output report, 1 = feature report.
+                    let n = 3 + data.len();
+                    if cap < n {
+                        return Ok(-1); // reports are ≤ 64 bytes; Kotlin allocates 128
+                    }
+                    out[0] = pad;
+                    out[1] = TAG_HID_RAW;
+                    out[2] = kind;
+                    out[3..n].copy_from_slice(&data);
+                    n
+                }
+                HidOutput::AudioCtl { .. } => {
+                    // DS5 pad-audio routing/volumes — no Android replay path yet (the 0xD1 sample
+                    // plane isn't rendered here either); drop it like TrackpadHaptic.
+                    return Ok(-1);
+                }
+            };
+            Ok(n as jint)
+        })
+        .resolve::<LogErrorAndDefault>()
     })
 }
 

clients/android/native/src/lib.rs

@@ -21,9 +21,10 @@
 //! surface, the per-plane pumps (video → AMediaCodec, audio ↔ AAudio, mic uplink), input, and
 //! rumble/HID feedback ([`feedback`]). Mode renegotiation is still TODO (see [`session`]).
 
-use jni::objects::JObject;
+use jni::errors::LogErrorAndDefault;
+use jni::objects::{JObject, JString};
 use jni::sys::jint;
-use jni::JNIEnv;
+use jni::EnvUnowned;
 
 #[cfg(target_os = "android")]
 mod adpf;
@@ -54,7 +55,7 @@ mod probe;
 /// on via quinn's defaults — forwards them as `log` records since no tracing subscriber is ever
 /// installed. Android-only — there is no JVM (and no logcat) on the host build.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn JNI_OnLoad(
     _vm: *mut jni::sys::JavaVM,
     _reserved: *mut std::ffi::c_void,
@@ -74,22 +75,20 @@ pub extern "system" fn JNI_OnLoad(
 /// `NativeBridge.abiVersion(): Int` — the core's C-ABI version. A non-error return is the
 /// scaffold's proof that `System.loadLibrary` found the `.so`, the JNI symbol resolved, and the
 /// linked `punktfunk-core` is the one we expect.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_abiVersion(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
 ) -> jint {
     punktfunk_core::ABI_VERSION as jint
 }
 
 /// `NativeBridge.coreVersion(): String` — the crate version, proving JNI string marshaling works.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_coreVersion<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
-) -> jni::sys::jstring {
-    match env.new_string(env!("CARGO_PKG_VERSION")) {
-        Ok(s) => s.into_raw(),
-        Err(_) => JObject::null().into_raw(),
-    }
+) -> JString<'local> {
+    env.with_env(|env| env.new_string(env!("CARGO_PKG_VERSION")))
+        .resolve::<LogErrorAndDefault>()
 }

clients/android/native/src/probe.rs

@@ -5,32 +5,29 @@
 //! advertise on mDNS (reached over Tailscale / VPN / another subnet) — the display-side companion
 //! to the dial-first connect fix.
 
+use jni::errors::LogErrorAndDefault;
 use jni::objects::{JObject, JString};
 use jni::sys::{jboolean, jint};
-use jni::JNIEnv;
+use jni::EnvUnowned;
 use punktfunk_core::client::NativeClient;
 use std::time::Duration;
 
 /// `NativeBridge.nativeProbe(host, port, timeoutMs): Boolean` — true if `host:port` completed a
 /// QUIC handshake within `timeoutMs`. No pin/identity presented (trust-agnostic), mDNS-independent.
 /// Blocking (builds its own runtime) — Kotlin runs it on `Dispatchers.IO`, never the main thread.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeProbe<'local>(
-    mut env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     host: JString<'local>,
     port: jint,
     timeout_ms: jint,
 ) -> jboolean {
-    let host: String = match env.get_string(&host) {
-        Ok(s) => s.into(),
-        Err(_) => return 0,
-    };
-    let port = port.clamp(0, u16::MAX as jint) as u16;
-    let timeout = Duration::from_millis(timeout_ms.max(0) as u64);
-    if NativeClient::probe(&host, port, timeout) {
-        1
-    } else {
-        0
-    }
+    env.with_env(|env| -> jni::errors::Result<bool> {
+        let host: String = host.try_to_string(env)?;
+        let port = port.clamp(0, u16::MAX as jint) as u16;
+        let timeout = Duration::from_millis(timeout_ms.max(0) as u64);
+        Ok(NativeClient::probe(&host, port, timeout))
+    })
+    .resolve::<LogErrorAndDefault>()
 }

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

@@ -15,9 +15,10 @@
 
 use std::time::Duration;
 
+use jni::errors::LogErrorAndDefault;
 use jni::objects::{JObject, JString};
-use jni::sys::{jboolean, jint, jlong, jstring};
-use jni::JNIEnv;
+use jni::sys::{jboolean, jint, jlong};
+use jni::EnvUnowned;
 use punktfunk_core::clipboard::ClipEventCore;
 use punktfunk_core::error::PunktfunkError;
 use punktfunk_core::quic::{ClipKind, CLIP_FILE_INDEX_NONE, HOST_CAP_CLIPBOARD};
@@ -40,37 +41,35 @@ fn client(handle: jlong) -> Option<&'static SessionHandle> {
 }
 
 /// `NativeBridge.nativeClipSupported(handle)` — the host advertised `HOST_CAP_CLIPBOARD`.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipSupported(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jboolean {
-    client(handle).map_or(0, |h| {
-        u8::from(h.client.host_caps() & HOST_CAP_CLIPBOARD != 0)
-    })
+    client(handle).is_some_and(|h| h.client.host_caps() & HOST_CAP_CLIPBOARD != 0)
 }
 
 /// `NativeBridge.nativeClipControl(handle, enabled)` — session-level opt-in/out. Nothing
 /// clipboard-related happens on either side until an `enabled: true` crosses.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipControl(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     enabled: jboolean,
 ) {
     if let Some(h) = client(handle) {
-        let _ = h.client.clip_control(enabled != 0, 0);
+        let _ = h.client.clip_control(enabled, 0);
     }
 }
 
 /// `NativeBridge.nativeClipOfferText(handle, seq)` — announce "the Android clipboard now holds
 /// text" (format list only; bytes cross when the host fetches). `seq` is Kotlin's monotonic
 /// counter, newest wins.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipOfferText(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     seq: jint,
@@ -88,9 +87,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipOfferTe
 
 /// `NativeBridge.nativeClipFetchText(handle, seq)` — pull the text of the host's offer `seq`.
 /// Returns the transfer id echoed on the matching `data:`/`error:` event, or −1.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipFetchText(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     seq: jint,
@@ -106,28 +105,34 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipFetchTe
 
 /// `NativeBridge.nativeClipServeText(handle, reqId, text)` — answer a `fetch:` event with the
 /// clipboard's current text (the host is pasting our offer).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipServeText(
-    mut env: JNIEnv,
+    mut env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     req_id: jint,
     text: JString,
 ) {
-    let Some(h) = client(handle) else { return };
-    let Ok(s) = env.get_string(&text) else {
-        let _ = h.client.clip_cancel(req_id as u32);
-        return;
-    };
-    let _ = h
-        .client
-        .clip_serve(req_id as u32, String::from(s).into_bytes(), true);
+    env.with_env(|env| -> jni::errors::Result<()> {
+        let Some(h) = client(handle) else {
+            return Ok(());
+        };
+        // An unreadable payload still has to answer the host's `fetch:` — leaving it unanswered
+        // stalls the paste — so cancel the transfer rather than propagating the error.
+        let Ok(s) = text.try_to_string(env) else {
+            let _ = h.client.clip_cancel(req_id as u32);
+            return Ok(());
+        };
+        let _ = h.client.clip_serve(req_id as u32, s.into_bytes(), true);
+        Ok(())
+    })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeClipCancel(handle, id)` — abort a transfer (either direction).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipCancel(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     id: jint,
@@ -144,39 +149,42 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipCancel(
 /// Text payloads ride `data:<xfer_id>:<text>` decoded lossily — safe because the phase-0
 /// clipboard task delivers a whole payload in ONE event (`last = true`), so a chunk boundary
 /// can never split a UTF-8 sequence.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextClip(
-    env: JNIEnv,
-    _this: JObject,
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextClip<'local>(
+    mut env: EnvUnowned<'local>,
+    _this: JObject<'local>,
     handle: jlong,
-) -> jstring {
-    let Some(h) = client(handle) else {
-        return std::ptr::null_mut();
-    };
-    let msg = match h.client.next_clip(Duration::from_millis(250)) {
-        Ok(ClipEventCore::State { enabled, .. }) => format!("state:{}", u8::from(enabled)),
-        Ok(ClipEventCore::RemoteOffer { seq, kinds }) => {
-            let has_text = kinds.iter().any(|k| k.mime.starts_with("text/plain"));
-            format!("offer:{seq}:{}", u8::from(has_text))
-        }
-        Ok(ClipEventCore::FetchRequest { req_id, mime, .. }) => {
-            if mime.starts_with("text/plain") {
-                format!("fetch:{req_id}")
-            } else {
-                // We only ever offer text; cancel anything else rather than stall the host.
-                let _ = h.client.clip_cancel(req_id);
-                return std::ptr::null_mut();
+) -> JString<'local> {
+    // `JString::default()` is the null reference the old `std::ptr::null_mut()` returned, so the
+    // "null on timeout" contract in the doc comment above is unchanged.
+    env.with_env(|env| -> jni::errors::Result<JString<'local>> {
+        let Some(h) = client(handle) else {
+            return Ok(JString::default());
+        };
+        let msg = match h.client.next_clip(Duration::from_millis(250)) {
+            Ok(ClipEventCore::State { enabled, .. }) => format!("state:{}", u8::from(enabled)),
+            Ok(ClipEventCore::RemoteOffer { seq, kinds }) => {
+                let has_text = kinds.iter().any(|k| k.mime.starts_with("text/plain"));
+                format!("offer:{seq}:{}", u8::from(has_text))
             }
-        }
-        Ok(ClipEventCore::Data { xfer_id, bytes, .. }) => {
-            format!("data:{xfer_id}:{}", String::from_utf8_lossy(&bytes))
-        }
-        Ok(ClipEventCore::Cancelled { id }) => format!("cancel:{id}"),
-        Ok(ClipEventCore::Error { id, code }) => format!("error:{id}:{code}"),
-        Err(PunktfunkError::NoFrame) => return std::ptr::null_mut(),
-        Err(_) => "closed".into(),
-    };
-    env.new_string(msg)
-        .map(|s| s.into_raw())
-        .unwrap_or(std::ptr::null_mut())
+            Ok(ClipEventCore::FetchRequest { req_id, mime, .. }) => {
+                if mime.starts_with("text/plain") {
+                    format!("fetch:{req_id}")
+                } else {
+                    // We only ever offer text; cancel anything else rather than stall the host.
+                    let _ = h.client.clip_cancel(req_id);
+                    return Ok(JString::default());
+                }
+            }
+            Ok(ClipEventCore::Data { xfer_id, bytes, .. }) => {
+                format!("data:{xfer_id}:{}", String::from_utf8_lossy(&bytes))
+            }
+            Ok(ClipEventCore::Cancelled { id }) => format!("cancel:{id}"),
+            Ok(ClipEventCore::Error { id, code }) => format!("error:{id}:{code}"),
+            Err(PunktfunkError::NoFrame) => return Ok(JString::default()),
+            Err(_) => "closed".into(),
+        };
+        env.new_string(msg)
+    })
+    .resolve::<LogErrorAndDefault>()
 }

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

@@ -1,9 +1,10 @@
 //! Connect lifecycle + the trust surface: identity mint, connect (TOFU / pinned), close,
 //! host-fingerprint read, and the SPAKE2 PIN pairing ceremony.
 
+use jni::errors::LogErrorAndDefault;
 use jni::objects::{JObject, JString};
 use jni::sys::{jboolean, jint, jlong};
-use jni::JNIEnv;
+use jni::EnvUnowned;
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
 use std::sync::{Arc, Mutex};
@@ -36,26 +37,24 @@ fn note_error(e: &punktfunk_core::error::PunktfunkError) {
 /// `NativeBridge.nativeTakeLastError(): String` — the machine token of the most recent failed
 /// `nativeConnect`/`nativePair`, cleared on read (`""` when none). Call right after a `0`
 /// handle / `""` fingerprint.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeTakeLastError<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
-) -> jni::sys::jstring {
+) -> JString<'local> {
     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(),
-    }
+    env.with_env(|env| env.new_string(token))
+        .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
 /// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
 /// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIdentity<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
-) -> jni::sys::jstring {
+) -> JString<'local> {
     let out = match punktfunk_core::quic::endpoint::generate_identity() {
         Ok((cert, key)) => format!("{cert}\n-----PUNKTFUNK-KEY-----\n{key}"),
         Err(e) => {
@@ -63,10 +62,8 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIde
             String::new()
         }
     };
-    match env.new_string(out) {
-        Ok(s) => s.into_raw(),
-        Err(_) => JObject::null().into_raw(),
-    }
+    env.with_env(|env| env.new_string(out))
+        .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeSetLowLatencyMode(enabled)` — apply the user's "Low-latency mode
@@ -74,13 +71,13 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIde
 /// the media sockets. Must be called BEFORE `nativeConnect` (the tag is applied at socket
 /// creation); Kotlin's one connect choke point (`HostConnect.connectToHost`) does. The rest of the
 /// toggle rides explicit per-session parameters (`nativeStartVideo` / `nativeStartAudio`).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetLowLatencyMode(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     enabled: jboolean,
 ) {
-    punktfunk_core::transport::set_dscp_default(enabled != 0);
+    punktfunk_core::transport::set_dscp_default(enabled);
 }
 
 /// `debug.punktfunk.force_parts` = 1: arm slice-progressive parts delivery even when the
@@ -120,10 +117,10 @@ fn force_parts_sysprop() -> bool {
 /// budget: the normal path passes a short value, the no-PIN "request access" path a long one (≥ the
 /// host's approval-park window) so a slow operator approval lands on this same parked connection
 /// rather than timing the client out first. Returns an opaque handle, or 0 on failure.
-#[no_mangle]
+#[unsafe(no_mangle)]
 #[allow(clippy::too_many_arguments)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'local>(
-    mut env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     host: JString<'local>,
     port: jint,
@@ -147,31 +144,44 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
     device_name: JString<'local>,
     pad_audio_ok: jboolean,
 ) -> jlong {
-    let host: String = match env.get_string(&host) {
-        Ok(s) => s.into(),
-        Err(_) => return 0,
+    // Every JNI string this method needs, read up front in the one `Env` scope jni 0.22 grants a
+    // native method; everything below is pure Rust over owned `String`s. `None` = the mandatory
+    // `host` could not be read, which is the old `Err(_) => return 0` arm.
+    type ConnectStrings = Option<(
+        String,
+        String,
+        String,
+        String,
+        Option<String>,
+        Option<String>,
+    )>;
+    let strings: ConnectStrings = env
+        .with_env(|env| -> jni::errors::Result<ConnectStrings> {
+            let Ok(host) = host.try_to_string(env) else {
+                return Ok(None);
+            };
+            let cert: String = cert_pem.try_to_string(env).unwrap_or_default();
+            let key: String = key_pem.try_to_string(env).unwrap_or_default();
+            let pin_hex: String = pin_hex.try_to_string(env).unwrap_or_default();
+            // A store-qualified library id (`steam:<appid>` / `custom:<id>`) to boot straight into a
+            // game; null / empty ⇒ None (a plain desktop connect). Rides the Hello as `launch`.
+            let launch: Option<String> = launch
+                .try_to_string(env)
+                .ok()
+                .filter(|s: &String| !s.is_empty());
+            // The host's approval-list / trust-store label for this device; null / blank ⇒ None (the
+            // host falls back to its fingerprint-derived "device abcd1234" placeholder).
+            let device_name: Option<String> = device_name
+                .try_to_string(env)
+                .ok()
+                .map(|s: String| s.trim().to_string())
+                .filter(|s| !s.is_empty());
+            Ok(Some((host, cert, key, pin_hex, launch, device_name)))
+        })
+        .resolve::<LogErrorAndDefault>();
+    let Some((host, cert, key, pin_hex, launch, device_name)) = strings else {
+        return 0;
     };
-    let cert: String = env
-        .get_string(&cert_pem)
-        .map(Into::into)
-        .unwrap_or_default();
-    let key: String = env.get_string(&key_pem).map(Into::into).unwrap_or_default();
-    let pin_hex: String = env.get_string(&pin_hex).map(Into::into).unwrap_or_default();
-    // A store-qualified library id (`steam:<appid>` / `custom:<id>`) to boot straight into a game;
-    // null / empty ⇒ None (a plain desktop connect). Rides the Hello as `launch`.
-    let launch: Option<String> = env
-        .get_string(&launch)
-        .map(Into::into)
-        .ok()
-        .filter(|s: &String| !s.is_empty());
-    // The host's approval-list / trust-store label for this device; null / blank ⇒ None (the host
-    // falls back to its fingerprint-derived "device abcd1234" placeholder).
-    let device_name: Option<String> = env
-        .get_string(&device_name)
-        .map(Into::into)
-        .ok()
-        .map(|s: String| s.trim().to_string())
-        .filter(|s| !s.is_empty());
 
     let identity: Option<(String, String)> = if cert.is_empty() || key.is_empty() {
         None
@@ -184,16 +194,16 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
     // the feature? (`adb shell setprop debug.punktfunk.force_parts 1` + stream restart; a codec
     // that can't take parts errors recoverably and the reanchor gate + keyframe path recovers.)
     let force_parts = force_parts_sysprop();
-    let frame_parts = frame_parts_ok != 0 || force_parts;
+    let frame_parts = frame_parts_ok || force_parts;
     // The connect-time capability readout (`adb logcat -s pf.caps`): the P2 slice pipeline is
     // inert client-side unless BOTH probes pass — this line is the one place that says which.
     log::info!(
         target: "pf.caps",
         "decoder caps: multi_slice={} partial_frame={}{} hdr={} codec_bits={:#x}",
-        multi_slice_ok != 0,
-        frame_parts_ok != 0,
+        multi_slice_ok,
+        frame_parts_ok,
         if force_parts { " (FORCED by sysprop)" } else { "" },
-        hdr_enabled != 0,
+        hdr_enabled,
         video_codecs,
     );
     let pin: Option<[u8; 32]> = if pin_hex.is_empty() {
@@ -229,11 +239,11 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
         // decoder this device would use (`VideoDecoders.multiSliceTolerant` — Amlogic wedges the
         // whole device on multi-slice AUs, the 0.17.0 field regression) and only then may the
         // host default to >1 slice per frame (its sub-frame readback / the P2 slice pipeline).
-        (if hdr_enabled != 0 {
+        (if hdr_enabled {
             punktfunk_core::quic::VIDEO_CAP_10BIT | punktfunk_core::quic::VIDEO_CAP_HDR
         } else {
             0
-        }) | (if multi_slice_ok != 0 {
+        }) | (if multi_slice_ok {
             punktfunk_core::quic::VIDEO_CAP_MULTI_SLICE
         } else {
             0
@@ -274,7 +284,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
         // so declaring a pad's render caps later would have nothing to gate. Gated on the
         // settings so a user with pad audio off does not make the host provision endpoints.
         punktfunk_core::quic::CLIENT_CAP_PHASE_LOCK
-            | if pad_audio_ok != 0 {
+            | if pad_audio_ok {
                 punktfunk_core::quic::CLIENT_CAP_PAD_AUDIO
             } else {
                 0
@@ -322,9 +332,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
 /// # Safety contract
 /// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
 /// closed exactly once and not concurrently with other calls on the same handle (Kotlin owns this).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -344,9 +354,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
 /// # Safety contract
 /// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
 /// not freed / closed concurrently with this call (Kotlin still owns it and closes it via `nativeClose`).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDisconnectQuit(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -363,12 +373,12 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDisconnectQ
 /// `NativeBridge.nativeHostFingerprint(handle): String` — the SHA-256 (64-hex) of the cert the host
 /// presented on this connection. Valid after a successful `nativeConnect`; Kotlin pins it on a TOFU
 /// connect. `""` on a `0` handle.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerprint<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     handle: jlong,
-) -> jni::sys::jstring {
+) -> JString<'local> {
     let out = if handle == 0 {
         String::new()
     } else {
@@ -376,10 +386,8 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerp
         let h = unsafe { &*(handle as *const SessionHandle) };
         hex32(&h.client.host_fingerprint)
     };
-    match env.new_string(out) {
-        Ok(s) => s.into_raw(),
-        Err(_) => JObject::null().into_raw(),
-    }
+    env.with_env(|env| env.new_string(out))
+        .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeSessionEnded(handle): Boolean` — has the underlying QUIC session ended?
@@ -388,19 +396,19 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerp
 /// Kotlin's stream watchdog polls this (~1 Hz) to leave a dead stream and return to the menu (where
 /// the user can Wake-on-LAN the host) instead of stranding them on a frozen frame. `false` on a `0`
 /// handle. Cheap (one atomic load); safe on the UI thread.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSessionEnded(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jboolean {
-    jni_guard(0, || {
+    jni_guard(false, || {
         if handle == 0 {
-            return 0;
+            return false;
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
-        jboolean::from(h.client.is_session_ended())
+        h.client.is_session_ended()
     })
 }
 
@@ -413,9 +421,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSessionEnde
 /// this existed the watchdog worded them identically ("the host may be asleep"), which is wrong for
 /// every deliberate ending. `0` (NONE) on a `0` handle or before the session ends. Cheap (one
 /// atomic load); safe on the UI thread.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeEndReason(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jint {
@@ -433,10 +441,10 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeEndReason(
 /// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
 /// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns
 /// `""` (logged). Blocking — Kotlin calls it off the UI thread.
-#[no_mangle]
+#[unsafe(no_mangle)]
 #[allow(clippy::too_many_arguments)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local>(
-    mut env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     host: JString<'local>,
     port: jint,
@@ -444,40 +452,40 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local
     key_pem: JString<'local>,
     pin: JString<'local>,
     name: JString<'local>,
-) -> jni::sys::jstring {
-    let g = |e: &mut JNIEnv<'local>, j: &JString<'local>| -> String {
-        e.get_string(j).map(Into::into).unwrap_or_default()
-    };
-    let host = g(&mut env, &host);
-    let cert = g(&mut env, &cert_pem);
-    let key = g(&mut env, &key_pem);
-    let pin = g(&mut env, &pin);
-    let name = g(&mut env, &name);
+) -> JString<'local> {
+    env.with_env(|env| -> jni::errors::Result<JString<'local>> {
+        let g = |e: &jni::Env<'local>, j: &JString<'local>| -> String {
+            j.try_to_string(e).unwrap_or_default()
+        };
+        let host = g(env, &host);
+        let cert = g(env, &cert_pem);
+        let key = g(env, &key_pem);
+        let pin = g(env, &pin);
+        let name = g(env, &name);
 
-    let out = if host.is_empty() || cert.is_empty() || key.is_empty() {
-        log::error!("nativePair: missing host/identity");
-        String::new()
-    } else {
-        match NativeClient::pair(
-            &host,
-            port as u16,
-            (&cert, &key), // borrowed identity
-            &pin,
-            &name,
-            Duration::from_secs(60),
-        ) {
-            Ok(host_fp) => hex32(&host_fp),
-            Err(e) => {
-                // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
-                // The token lets Kotlin say WHICH (`nativeTakeLastError`).
-                log::error!("nativePair to {host}:{port} failed: {e}");
-                note_error(&e);
-                String::new()
+        let out = if host.is_empty() || cert.is_empty() || key.is_empty() {
+            log::error!("nativePair: missing host/identity");
+            String::new()
+        } else {
+            match NativeClient::pair(
+                &host,
+                port as u16,
+                (&cert, &key), // borrowed identity
+                &pin,
+                &name,
+                Duration::from_secs(60),
+            ) {
+                Ok(host_fp) => hex32(&host_fp),
+                Err(e) => {
+                    // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
+                    // The token lets Kotlin say WHICH (`nativeTakeLastError`).
+                    log::error!("nativePair to {host}:{port} failed: {e}");
+                    note_error(&e);
+                    String::new()
+                }
             }
-        }
-    };
-    match env.new_string(out) {
-        Ok(s) => s.into_raw(),
-        Err(_) => JObject::null().into_raw(),
-    }
+        };
+        env.new_string(out)
+    })
+    .resolve::<LogErrorAndDefault>()
 }

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

@@ -6,9 +6,10 @@
 //! conventions: buttons 1=left/2=middle/3=right/4=X1/5=X2; scroll axis 0=vertical/1=horizontal,
 //! signed 120-unit delta, +=up/right; keys are Windows VK (mapped from KEYCODE_* on the Kotlin side).
 
+use jni::errors::LogErrorAndDefault;
 use jni::objects::{JByteBuffer, JFloatArray, JObject, JString};
 use jni::sys::{jboolean, jint, jlong};
-use jni::JNIEnv;
+use jni::EnvUnowned;
 use punktfunk_core::input::{InputEvent, InputKind};
 use punktfunk_core::quic::{
     PenSample, PenTool, RichInput, HID_REPORT_MAX, HOST_CAP_PEN, HOST_CAP_TEXT_INPUT,
@@ -35,9 +36,9 @@ fn send_event(handle: jlong, kind: InputKind, code: u32, x: i32, y: i32, flags:
 }
 
 /// `NativeBridge.nativeSendPointerMove(handle, dx, dy)` — relative mouse motion (screen +y down).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerMove(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     dx: jint,
@@ -51,9 +52,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointer
 /// normalizing against the size packed into `flags` as `(w << 16) | h` and mapping into the output
 /// region (it drops the event if that size is zero). This is the touch "direct pointing" path — the
 /// cursor jumps to the finger — and matches the Apple client's absolute touch forwarding.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerAbs(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     x: jint,
@@ -68,15 +69,15 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointer
 
 /// `NativeBridge.nativeSendPointerButton(handle, button, down)` — one button transition.
 /// `button`: GameStream id (1=left, 2=middle, 3=right, 4=X1, 5=X2). `down`: 1=press, 0=release.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerButton(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     button: jint,
     down: jboolean,
 ) {
-    let kind = if down != 0 {
+    let kind = if down {
         InputKind::MouseButtonDown
     } else {
         InputKind::MouseButtonUp
@@ -86,9 +87,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointer
 
 /// `NativeBridge.nativeSendScroll(handle, axis, delta)` — one scroll step. `axis`: 0=vertical,
 /// 1=horizontal. `delta`: signed, WHEEL_DELTA(120)-scaled, +=up/right.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     axis: jint,
@@ -103,9 +104,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
 /// surface, whose size rides in `flags` so the host can rescale into the output (identical
 /// packing to MouseMoveAbs). On up only the id matters. The host injects a real touch contact
 /// (libei touchscreen / wlroots / SendInput).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendTouch(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     id: jint,
@@ -128,9 +129,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendTouch(
 /// `NativeBridge.nativeSendKey(handle, vk, down, mods)` — one key transition. `vk`: Windows
 /// Virtual-Key code (0 = unmapped → dropped). `down`: 1=press, 0=release. `mods`: VK modifier
 /// bitmask (0 for now — the host folds modifiers from the L/R modifier key events themselves).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     vk: jint,
@@ -140,7 +141,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
     if vk == 0 {
         return;
     }
-    let kind = if down != 0 {
+    let kind = if down {
         InputKind::KeyDown
     } else {
         InputKind::KeyUp
@@ -151,35 +152,35 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
 /// `NativeBridge.nativeTextInputSupported(handle)` — whether the host advertised
 /// `HOST_CAP_TEXT_INPUT` (its inject backend types committed text), so the Kotlin side can pick
 /// the real IME `InputConnection` over the TYPE_NULL raw-key fallback. `0` handle → false.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeTextInputSupported(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jboolean {
     if handle == 0 {
-        return 0;
+        return false;
     }
     // SAFETY: live handle per the nativeConnect/nativeClose contract; host_caps is &self.
     let h = unsafe { &*(handle as *const SessionHandle) };
-    u8::from(h.client.host_caps() & HOST_CAP_TEXT_INPUT != 0)
+    h.client.host_caps() & HOST_CAP_TEXT_INPUT != 0
 }
 
 /// `NativeBridge.nativeHostSupportsPen(handle)` — the host advertised `HOST_CAP_PEN`, so the
 /// Kotlin side splits stylus pointers out of the touch path onto the pen plane
 /// (design/pen-tablet-input.md §7). `0` handle → false.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostSupportsPen(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jboolean {
     if handle == 0 {
-        return 0;
+        return false;
     }
     // SAFETY: live handle per the nativeConnect/nativeClose contract; host_caps is &self.
     let h = unsafe { &*(handle as *const SessionHandle) };
-    u8::from(h.client.host_caps() & HOST_CAP_PEN != 0)
+    h.client.host_caps() & HOST_CAP_PEN != 0
 }
 
 /// Floats per sample in the `nativeSendPen` flat array.
@@ -197,89 +198,97 @@ const PEN_JNI_MAX_SAMPLES: usize = PEN_BATCH_MAX * 8;
 /// normalized 0..1; `distance`/`tilt_deg`/`azimuth_deg`/`roll_deg` < 0 = unknown. Call only
 /// against a [`nativeHostSupportsPen`] host; the client heartbeats the last sample ≤100 ms
 /// while in range (Kotlin side — see `StylusStream`).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPen(
-    env: JNIEnv,
+    mut env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     samples: JFloatArray,
     count: jint,
 ) {
-    if handle == 0 || count <= 0 {
-        return;
-    }
-    let count = (count as usize).min(PEN_JNI_MAX_SAMPLES);
-    let mut buf = [0f32; PEN_JNI_MAX_SAMPLES * PEN_JNI_STRIDE];
-    let flat = &mut buf[..count * PEN_JNI_STRIDE];
-    if env.get_float_array_region(&samples, 0, flat).is_err() {
-        return; // short array — a bridge bug, never worth a crash on the input path
-    }
-    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_pen is &self.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut batch = [PenSample::default(); PEN_BATCH_MAX];
-    for run in flat.chunks(PEN_BATCH_MAX * PEN_JNI_STRIDE) {
-        let n = run.len() / PEN_JNI_STRIDE;
-        for (slot, s) in batch.iter_mut().zip(run.chunks_exact(PEN_JNI_STRIDE)) {
-            if !s[2].is_finite() || !s[3].is_finite() {
-                return; // never forward a NaN coordinate
-            }
-            *slot = PenSample {
-                state: s[0] as u8,
-                tool: if s[1] as u8 == 1 {
-                    PenTool::Eraser
-                } else {
-                    PenTool::Pen
-                },
-                x: s[2].clamp(0.0, 1.0),
-                y: s[3].clamp(0.0, 1.0),
-                pressure: (s[4].clamp(0.0, 1.0) * 65535.0) as u16,
-                distance: if s[5] < 0.0 {
-                    PEN_DISTANCE_UNKNOWN
-                } else {
-                    (s[5].clamp(0.0, 1.0) * 65534.0) as u16
-                },
-                tilt_deg: if s[6] < 0.0 {
-                    PEN_TILT_UNKNOWN
-                } else {
-                    (s[6].clamp(0.0, 90.0)) as u8
-                },
-                azimuth_deg: if s[7] < 0.0 {
-                    PEN_ANGLE_UNKNOWN
-                } else {
-                    (s[7] as u16) % 360
-                },
-                roll_deg: if s[8] < 0.0 {
-                    PEN_ANGLE_UNKNOWN
-                } else {
-                    (s[8] as u16) % 360
-                },
-                dt_us: s[9].clamp(0.0, 65535.0) as u16,
-            };
+    env.with_env(|env| -> jni::errors::Result<()> {
+        if handle == 0 || count <= 0 {
+            return Ok(());
         }
-        let _ = h.client.send_pen(&batch[..n]);
-    }
+        let count = (count as usize).min(PEN_JNI_MAX_SAMPLES);
+        let mut buf = [0f32; PEN_JNI_MAX_SAMPLES * PEN_JNI_STRIDE];
+        let flat = &mut buf[..count * PEN_JNI_STRIDE];
+        if samples.get_region(env, 0, flat).is_err() {
+            return Ok(()); // short array — a bridge bug, never worth a crash on the input path
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract; send_pen is &self.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        let mut batch = [PenSample::default(); PEN_BATCH_MAX];
+        for run in flat.chunks(PEN_BATCH_MAX * PEN_JNI_STRIDE) {
+            let n = run.len() / PEN_JNI_STRIDE;
+            for (slot, s) in batch.iter_mut().zip(run.chunks_exact(PEN_JNI_STRIDE)) {
+                if !s[2].is_finite() || !s[3].is_finite() {
+                    return Ok(()); // never forward a NaN coordinate
+                }
+                *slot = PenSample {
+                    state: s[0] as u8,
+                    tool: if s[1] as u8 == 1 {
+                        PenTool::Eraser
+                    } else {
+                        PenTool::Pen
+                    },
+                    x: s[2].clamp(0.0, 1.0),
+                    y: s[3].clamp(0.0, 1.0),
+                    pressure: (s[4].clamp(0.0, 1.0) * 65535.0) as u16,
+                    distance: if s[5] < 0.0 {
+                        PEN_DISTANCE_UNKNOWN
+                    } else {
+                        (s[5].clamp(0.0, 1.0) * 65534.0) as u16
+                    },
+                    tilt_deg: if s[6] < 0.0 {
+                        PEN_TILT_UNKNOWN
+                    } else {
+                        (s[6].clamp(0.0, 90.0)) as u8
+                    },
+                    azimuth_deg: if s[7] < 0.0 {
+                        PEN_ANGLE_UNKNOWN
+                    } else {
+                        (s[7] as u16) % 360
+                    },
+                    roll_deg: if s[8] < 0.0 {
+                        PEN_ANGLE_UNKNOWN
+                    } else {
+                        (s[8] as u16) % 360
+                    },
+                    dt_us: s[9].clamp(0.0, 65535.0) as u16,
+                };
+            }
+            let _ = h.client.send_pen(&batch[..n]);
+        }
+        Ok(())
+    })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeSendText(handle, text)` — committed IME text, one `TextInput` event per
 /// Unicode scalar (`code` = the scalar; multi-char commits are consecutive events in order).
 /// Control characters are skipped — Enter/Backspace/Tab ride the VK key path. Call only when
 /// [`Java_io_unom_punktfunk_kit_NativeBridge_nativeTextInputSupported`] returned true.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendText(
-    mut env: JNIEnv,
+    mut env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     text: JString,
 ) {
-    if handle == 0 {
-        return;
-    }
-    let Ok(s) = env.get_string(&text) else {
-        return;
-    };
-    for ch in String::from(s).chars().filter(|c| !c.is_control()) {
-        send_event(handle, InputKind::TextInput, ch as u32, 0, 0, 0);
-    }
+    env.with_env(|env| -> jni::errors::Result<()> {
+        if handle == 0 {
+            return Ok(());
+        }
+        let Ok(s) = text.try_to_string(env) else {
+            return Ok(());
+        };
+        for ch in s.chars().filter(|c| !c.is_control()) {
+            send_event(handle, InputKind::TextInput, ch as u32, 0, 0, 0);
+        }
+        Ok(())
+    })
+    .resolve::<LogErrorAndDefault>()
 }
 
 // ---- Gamepad: Kotlin captures (KeyEvent/MotionEvent) → NativeClient::send_input ---------------
@@ -296,9 +305,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendText(
 /// `NativeBridge.nativeSendGamepadButton(handle, bit, down, pad)` — one gamepad button transition on
 /// wire pad index `pad`. `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press,
 /// 0=release. `pad`: wire pad index 0..15 (rides `flags`).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadButton(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     bit: jint,
@@ -309,7 +318,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
         handle,
         InputKind::GamepadButton,
         bit as u32,
-        i32::from(down != 0),
+        i32::from(down),
         0,
         pad as u32,
     );
@@ -318,9 +327,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 /// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value, pad)` — one gamepad axis update on wire
 /// pad index `pad`. `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16
 /// (−32768..32767, +y=up) or trigger 0..255. `pad`: wire pad index 0..15 (rides `flags`).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadAxis(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     axis_id: jint,
@@ -343,9 +352,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 /// index 0..15 (rides `flags`). Sent ONCE when a pad opens, BEFORE any of its input; the core re-sends
 /// it a few times against datagram loss, and an older host ignores the unknown tag (that pad then uses
 /// the session-default kind from the handshake — the pre-existing single-pad behaviour on pad 0).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadArrival(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pref: jint,
@@ -373,35 +382,35 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 ///
 /// A `0` handle answers `true` — "don't suppress" is the safe answer when we cannot tell, matching
 /// the `Auto` rule inside the predicate itself.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePadMotionReaches(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     declared_pref: jint,
 ) -> jboolean {
     if handle == 0 {
-        return 1;
+        return true;
     }
     // SAFETY: live handle per the nativeConnect/nativeClose contract; both fields are plain Copy
     // values read behind `&self`.
     let h = unsafe { &*(handle as *const SessionHandle) };
     let declared =
         punktfunk_core::config::GamepadPref::from_u8(declared_pref.clamp(0, u8::MAX as jint) as u8);
-    u8::from(punktfunk_core::config::pad_motion_reaches(
+    punktfunk_core::config::pad_motion_reaches(
         declared,
         h.client.requested_gamepad,
         h.client.resolved_gamepad,
-    ))
+    )
 }
 
 /// `NativeBridge.nativeSendGamepadRemove(handle, pad)` — signal that wire pad index `pad` was
 /// unplugged so the host tears its virtual device down. `pad` (rides `flags`) is the only field; the
 /// core stamps the per-pad seq (in the snapshot seq space, so a reordered snapshot can't resurrect the
 /// pad) and arms a re-send burst against datagram loss. An older host ignores the unknown tag.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadRemove(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pad: jint,
@@ -415,38 +424,42 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 /// `len` bytes are the report, id byte first (`0x42`/`0x45`/`0x47` state, `0x43` battery, …);
 /// `len` is clamped to the 64-byte wire body. Called from the capture thread at the controller's
 /// own report rate (~250–500 Hz) — the direct-buffer read avoids a JNI array copy per report.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadHidReport(
-    env: JNIEnv,
+    mut env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pad: jint,
     buf: JByteBuffer,
     len: jint,
 ) {
-    if handle == 0 || len <= 0 {
-        return;
-    }
-    let cap = match env.get_direct_buffer_capacity(&buf) {
-        Ok(c) => c,
-        Err(_) => return,
-    };
-    let ptr = match env.get_direct_buffer_address(&buf) {
-        Ok(p) if !p.is_null() => p,
-        _ => return,
-    };
-    let n = (len as usize).min(cap).min(HID_REPORT_MAX);
-    let mut data = [0u8; HID_REPORT_MAX];
-    // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call;
-    // `n` is bounded by both the buffer capacity and the fixed wire body.
-    data[..n].copy_from_slice(unsafe { std::slice::from_raw_parts(ptr, n) });
-    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_rich_input is &self.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let _ = h.client.send_rich_input(RichInput::HidReport {
-        pad: (pad as u32 & 0xF) as u8,
-        len: n as u8,
-        data,
-    });
+    env.with_env(|env| -> jni::errors::Result<()> {
+        if handle == 0 || len <= 0 {
+            return Ok(());
+        }
+        let cap = match env.get_direct_buffer_capacity(&buf) {
+            Ok(c) => c,
+            Err(_) => return Ok(()),
+        };
+        let ptr = match env.get_direct_buffer_address(&buf) {
+            Ok(p) if !p.is_null() => p,
+            _ => return Ok(()),
+        };
+        let n = (len as usize).min(cap).min(HID_REPORT_MAX);
+        let mut data = [0u8; HID_REPORT_MAX];
+        // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call;
+        // `n` is bounded by both the buffer capacity and the fixed wire body.
+        data[..n].copy_from_slice(unsafe { std::slice::from_raw_parts(ptr, n) });
+        // SAFETY: live handle per the nativeConnect/nativeClose contract; send_rich_input is &self.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        let _ = h.client.send_rich_input(RichInput::HidReport {
+            pad: (pad as u32 & 0xF) as u8,
+            len: n as u8,
+            data,
+        });
+        Ok(())
+    })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeSendPadTouch(handle, pad, finger, active, x, y)` — one touchpad contact
@@ -455,9 +468,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadHidR
 /// SCREEN convention (+y down — the wire's fixed meaning); `active` 0 lifts the finger. The
 /// host's DualSense-family backends scale onto the virtual pad's touch surface. On-change only —
 /// the capture diffs, the host holds per-slot state.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadTouch(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pad: jint,
@@ -474,7 +487,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadTouc
     let _ = h.client.send_rich_input(RichInput::Touchpad {
         pad: (pad as u32 & 0xF) as u8,
         finger: (finger as u32 & 0x1) as u8,
-        active: active != 0,
+        active,
         x: (x as i64).clamp(0, 65535) as u16,
         y: (y as i64).clamp(0, 65535) as u16,
     });
@@ -485,10 +498,10 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadTouc
 /// raw signed-16 values in the pad's own units, passed straight into the host's virtual
 /// DualSense report (the wire is a unit passthrough). Called from the capture thread at the
 /// controller's report rate.
-#[no_mangle]
+#[unsafe(no_mangle)]
 #[allow(clippy::too_many_arguments)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadMotion(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pad: jint,

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

@@ -1,12 +1,10 @@
 //! Plane start/stop: video (HEVC decode → Surface), host→client audio, mic uplink — plus the
 //! ~1 Hz decode-stats drain for the HUD.
 
-use jni::objects::JObject;
-// Used only by the android-gated `nativeStartVideo`; on the host build that fn is cfg'd out.
-#[cfg(target_os = "android")]
-use jni::objects::JString;
-use jni::sys::{jboolean, jdoubleArray, jintArray, jlong, jsize, jstring};
-use jni::JNIEnv;
+use jni::errors::LogErrorAndDefault;
+use jni::objects::{JDoubleArray, JIntArray, JObject, JString};
+use jni::sys::{jboolean, jlong};
+use jni::EnvUnowned;
 
 use super::{jni_guard, lock_recover, SessionHandle};
 
@@ -19,9 +17,9 @@ use super::{jni_guard, lock_recover, SessionHandle};
 /// presenter's intent (0 = lowest latency / 1 = smoothness; buffer 0 = auto, 1..=3 frames).
 /// No-op if already started.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
-    mut env: JNIEnv,
+    mut env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     surface: JObject,
@@ -37,53 +35,58 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
     use std::sync::atomic::AtomicBool;
     use std::sync::Arc;
 
-    if handle == 0 {
-        return;
-    }
-    // The decoder name Kotlin picked (empty string / read failure ⇒ None ⇒ default resolver).
-    let decoder = env
-        .get_string(&decoder_name)
-        .ok()
-        .map(String::from)
-        .filter(|s| !s.is_empty());
-    // SAFETY: live handle per the nativeConnect/nativeClose contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut guard = lock_recover(&h.video);
-    if guard.is_some() {
-        return; // already streaming
-    }
-    // SAFETY: `env`/`surface` are valid JNI pointers for this call. `as *mut _` bridges any
-    // jni-sys version skew between the `jni` and `ndk` crates (both are raw `*mut _` pointers).
-    let window = match unsafe {
-        ndk::native_window::NativeWindow::from_surface(
-            env.get_native_interface() as *mut _,
-            surface.as_raw() as *mut _,
-        )
-    } {
-        Some(w) => w,
-        None => {
-            log::error!("nativeStartVideo: no ANativeWindow from Surface");
-            return;
+    env.with_env(|env| -> jni::errors::Result<()> {
+        if handle == 0 {
+            return Ok(());
         }
-    };
-    let shutdown = Arc::new(AtomicBool::new(false));
-    let client = h.client.clone();
-    let sd = shutdown.clone();
-    let st = h.stats.clone(); // session-lifetime stats (gate survives surface recreate)
-    let opts = crate::decode::DecodeOptions {
-        decoder_name: decoder,
-        ll_feature: ll_feature != 0,
-        low_latency_mode: low_latency_mode != 0,
-        is_tv: is_tv != 0,
-        present_priority,
-        smooth_buffer,
-        panel_hz: panel_fps,
-    };
-    let join = std::thread::Builder::new()
-        .name("pf-decode".into())
-        .spawn(move || crate::decode::run(client, window, sd, st, opts))
-        .ok();
-    *guard = Some(VideoThread { shutdown, join });
+        // The decoder name Kotlin picked (empty string / read failure ⇒ None ⇒ default resolver).
+        let decoder = decoder_name
+            .try_to_string(env)
+            .ok()
+            .filter(|s| !s.is_empty());
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        let mut guard = lock_recover(&h.video);
+        if guard.is_some() {
+            return Ok(()); // already streaming
+        }
+        // SAFETY: `env`/`surface` are valid JNI pointers for this call. `as *mut _` bridges any
+        // jni-sys version skew between the `jni` and `ndk` crates (both are raw `*mut _` pointers)
+        // — a real skew here, not a hypothetical one: `jni` is on jni-sys 0.4 while the vendored
+        // `ndk` is still on 0.3.
+        let window = match unsafe {
+            ndk::native_window::NativeWindow::from_surface(
+                env.get_raw() as *mut _,
+                surface.as_raw() as *mut _,
+            )
+        } {
+            Some(w) => w,
+            None => {
+                log::error!("nativeStartVideo: no ANativeWindow from Surface");
+                return Ok(());
+            }
+        };
+        let shutdown = Arc::new(AtomicBool::new(false));
+        let client = h.client.clone();
+        let sd = shutdown.clone();
+        let st = h.stats.clone(); // session-lifetime stats (gate survives surface recreate)
+        let opts = crate::decode::DecodeOptions {
+            decoder_name: decoder,
+            ll_feature,
+            low_latency_mode,
+            is_tv,
+            present_priority,
+            smooth_buffer,
+            panel_hz: panel_fps,
+        };
+        let join = std::thread::Builder::new()
+            .name("pf-decode".into())
+            .spawn(move || crate::decode::run(client, window, sd, st, opts))
+            .ok();
+        *guard = Some(VideoThread { shutdown, join });
+        Ok(())
+    })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeVideoMime(handle): String` — the MediaCodec MIME for the codec the host
@@ -91,23 +94,21 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
 /// decoders for it before calling [`Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo`].
 /// Empty string on a `0` handle. Cheap; safe on the UI thread.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoMime<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     handle: jlong,
-) -> jstring {
-    jni_guard(std::ptr::null_mut(), || {
+) -> JString<'local> {
+    env.with_env(|env| -> jni::errors::Result<JString<'local>> {
         if handle == 0 {
-            return std::ptr::null_mut();
+            return Ok(JString::default());
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
-        match env.new_string(crate::decode::codec_mime(h.client.codec)) {
-            Ok(s) => s.into_raw(),
-            Err(_) => std::ptr::null_mut(),
-        }
+        env.new_string(crate::decode::codec_mime(h.client.codec))
     })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeVideoCodecLabel(handle): String` — a short human label for the codec the
@@ -116,23 +117,21 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoMime<'
 /// collapses PyroWave onto `video/hevc` and can't name it. Empty string on a `0` handle. Cheap;
 /// safe on the UI thread. Android-gated (reads `crate::decode`), matching `nativeVideoMime`.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoCodecLabel<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     handle: jlong,
-) -> jstring {
-    jni_guard(std::ptr::null_mut(), || {
+) -> JString<'local> {
+    env.with_env(|env| -> jni::errors::Result<JString<'local>> {
         if handle == 0 {
-            return std::ptr::null_mut();
+            return Ok(JString::default());
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
-        match env.new_string(crate::decode::codec_label(h.client.codec)) {
-            Ok(s) => s.into_raw(),
-            Err(_) => std::ptr::null_mut(),
-        }
+        env.new_string(crate::decode::codec_label(h.client.codec))
     })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeVideoDecoderLabel(handle): String` — the resolved decoder identity for the
@@ -140,30 +139,28 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoCodecL
 /// One-shot (the decoder is fixed for the session); poll once after the HUD appears. Not
 /// android-gated — pure `jni` + a lock, so it links on the host build too (Kotlin only calls it on
 /// device).
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoDecoderLabel<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     handle: jlong,
-) -> jstring {
-    jni_guard(std::ptr::null_mut(), || {
+) -> JString<'local> {
+    env.with_env(|env| -> jni::errors::Result<JString<'local>> {
         if handle == 0 {
-            return std::ptr::null_mut();
+            return Ok(JString::default());
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
-        match env.new_string(h.stats.decoder_label()) {
-            Ok(s) => s.into_raw(),
-            Err(_) => std::ptr::null_mut(),
-        }
+        env.new_string(h.stats.decoder_label())
     })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
 /// session). No-op on `0`.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -210,20 +207,20 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
 /// Poll ~1 Hz from the UI; each call
 /// resets the measurement window. Not android-gated — pure `jni` + connector reads, so it links on
 /// the host build too (Kotlin only ever calls it on device).
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
-    env: JNIEnv,
-    _this: JObject,
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats<'local>(
+    mut env: EnvUnowned<'local>,
+    _this: JObject<'local>,
     handle: jlong,
-) -> jdoubleArray {
-    jni_guard(std::ptr::null_mut(), || {
+) -> JDoubleArray<'local> {
+    env.with_env(|env| -> jni::errors::Result<JDoubleArray<'local>> {
         if handle == 0 {
-            return std::ptr::null_mut();
+            return Ok(JDoubleArray::default());
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
         if lock_recover(&h.video).is_none() {
-            return std::ptr::null_mut(); // not streaming → no stats
+            return Ok(JDoubleArray::default()); // not streaming → no stats
         }
         let snap = h
             .stats
@@ -294,15 +291,11 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
             h.client.audio_buffer_ms() as f64,
             h.client.audio_av_offset_ms() as f64,
         ];
-        let arr = match env.new_double_array(buf.len() as jsize) {
-            Ok(a) => a,
-            Err(_) => return std::ptr::null_mut(),
-        };
-        if env.set_double_array_region(&arr, 0, &buf).is_err() {
-            return std::ptr::null_mut();
-        }
-        arr.into_raw()
+        let arr = env.new_double_array(buf.len())?;
+        arr.set_region(env, 0, &buf)?;
+        Ok(arr)
     })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeVideoSize(handle): IntArray?` — the negotiated video mode as
@@ -312,15 +305,15 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
 /// trailing `refreshHz` was appended later — old readers index only 0/1 and never see it. `null`
 /// on a `0` handle. Not android-gated — pure `jni` + a connector read, so it links on the host
 /// build too. Cheap; safe on the UI thread.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoSize(
-    env: JNIEnv,
-    _this: JObject,
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoSize<'local>(
+    mut env: EnvUnowned<'local>,
+    _this: JObject<'local>,
     handle: jlong,
-) -> jintArray {
-    jni_guard(std::ptr::null_mut(), || {
+) -> JIntArray<'local> {
+    env.with_env(|env| -> jni::errors::Result<JIntArray<'local>> {
         if handle == 0 {
-            return std::ptr::null_mut();
+            return Ok(JIntArray::default());
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
@@ -330,15 +323,11 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoSize(
             mode.height as i32,
             mode.refresh_hz as i32,
         ];
-        let arr = match env.new_int_array(buf.len() as jsize) {
-            Ok(a) => a,
-            Err(_) => return std::ptr::null_mut(),
-        };
-        if env.set_int_array_region(&arr, 0, &buf).is_err() {
-            return std::ptr::null_mut();
-        }
-        arr.into_raw()
+        let arr = env.new_int_array(buf.len())?;
+        arr.set_region(env, 0, &buf)?;
+        Ok(arr)
     })
+    .resolve::<LogErrorAndDefault>()
 }
 
 /// `NativeBridge.nativeSetVideoStatsEnabled(handle, enabled)` — gate per-frame stats sampling on the
@@ -346,9 +335,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoSize(
 /// Enabling resets the measurement window so a later show never reports stale data. Sticky for the
 /// session (survives video stop/start across surface recreation). No-op on `0`. Not android-gated —
 /// pure `jni` + an atomic store, so it links on the host build too.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetVideoStatsEnabled(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     enabled: jboolean,
@@ -360,7 +349,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetVideoSta
             // The current cumulative counters seed the window baselines, so the first snapshot's
             // `lost`/`FEC` cover only time the HUD was actually up.
             h.stats.set_enabled(
-                enabled != 0,
+                enabled,
                 h.client.frames_dropped(),
                 h.client.fec_recovered_shards(),
             );
@@ -368,17 +357,18 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetVideoSta
     })
 }
 
-/// `NativeBridge.nativeStartAudio(handle, lowLatencyMode)` — start the Opus→AAudio playback thread.
-/// `lowLatencyMode` (the experimental toggle) tags the stream usage=Game for the HAL's game-audio
-/// routing. No-op if already started or on a `0` handle. Best-effort: a failure leaves video
-/// streaming.
+/// `NativeBridge.nativeStartAudio(handle, lowLatencyMode, isTv)` — start the Opus→AAudio playback
+/// supervisor. `lowLatencyMode` (the experimental toggle) tags the stream usage=Game for the HAL's
+/// game-audio routing; `isTv` steers the AAudio open ladder (see `crate::audio::open_ladder`).
+/// No-op if already started or on a `0` handle. Best-effort: a failure leaves video streaming.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     low_latency_mode: jboolean,
+    is_tv: jboolean,
 ) {
     if handle == 0 {
         return;
@@ -389,7 +379,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
     if guard.is_some() {
         return; // already playing
     }
-    match crate::audio::AudioPlayback::start(h.client.clone(), low_latency_mode != 0) {
+    match crate::audio::AudioPlayback::start(h.client.clone(), low_latency_mode, is_tv) {
         Some(p) => *guard = Some(p),
         None => log::error!("nativeStartAudio: playback init failed (video unaffected)"),
     }
@@ -398,9 +388,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
 /// `NativeBridge.nativeStopAudio(handle)` — stop + join the audio thread and close AAudio (without
 /// closing the session). No-op on `0`.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -422,9 +412,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
 /// the running capture's id. Caller MUST hold RECORD_AUDIO; a failure (e.g. no permission) leaves
 /// the rest of the session streaming.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     echo_cancel: jboolean,
@@ -440,7 +430,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
     }
     // The capture SHARES the session's mute flag, so one started while muted stays muted (and
     // sends nothing) from its very first frame — see `SessionHandle::mic_muted`.
-    match crate::mic::MicCapture::start(h.client.clone(), echo_cancel != 0, h.mic_muted.clone()) {
+    match crate::mic::MicCapture::start(h.client.clone(), echo_cancel, h.mic_muted.clone()) {
         Some(m) => {
             let session_id = m.session_id();
             *guard = Some(m);
@@ -457,9 +447,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
 /// stream (without closing the session). No-op on `0`. Leaves the session's mute state alone: a
 /// surface recreate stops and restarts the mic, and a user who muted must stay muted through it.
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -484,10 +474,10 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
 /// start. A kernel that refuses the interface claim is NOT reported here — the renderer discovers
 /// that on its own thread and degrades to tier C, because some OEM kernels refuse and there is no
 /// app-side fix worth blocking a session on.
-#[no_mangle]
+#[unsafe(no_mangle)]
 #[cfg(target_os = "android")]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartPadAudio(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pad: jni::sys::jint,
@@ -495,9 +485,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartPadAud
     haptics: jboolean,
     speaker: jboolean,
 ) -> jboolean {
-    jni_guard(0, || {
+    jni_guard(false, || {
         if handle == 0 || fd < 0 || !(0..16).contains(&pad) {
-            return 0;
+            return false;
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
@@ -512,14 +502,14 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartPadAud
             std::sync::Arc::clone(&h.client),
             pad as u8,
             fd,
-            haptics != 0,
-            speaker != 0,
+            haptics,
+            speaker,
         ) {
             Some(p) => {
                 *lock_recover(&h.pad_audio) = Some(p);
-                1
+                true
             }
-            None => 0,
+            None => false,
         }
     })
 }
@@ -530,10 +520,10 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartPadAud
 /// The check a standalone harness cannot make: it owns its descriptor by construction, so it can
 /// never reveal that the client handed the renderer a descriptor something else was already
 /// driving. Returns sample frames written, or negative on failure (see `pad_audio::SelfTest`).
-#[no_mangle]
+#[unsafe(no_mangle)]
 #[cfg(target_os = "android")]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePadAudioSelfTest(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     fd: jni::sys::jint,
     seconds: jni::sys::jint,
@@ -553,10 +543,10 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePadAudioSel
 ///
 /// Returns only once the render thread is joined, which is the point: Kotlin may close the
 /// `UsbDeviceConnection` as soon as this returns and not before.
-#[no_mangle]
+#[unsafe(no_mangle)]
 #[cfg(target_os = "android")]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopPadAudio(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pad: jni::sys::jint,
@@ -594,9 +584,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopPadAudi
 /// One honest consequence of keeping the stream open: the platform's own recording indicator stays
 /// lit while muted, because the mic really is still open. What stops is the encode and the send —
 /// no captured audio leaves the process.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetMicMuted(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     muted: jboolean,
@@ -606,7 +596,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetMicMuted
             // SAFETY: live handle per the nativeConnect/nativeClose contract.
             let h = unsafe { &*(handle as *const SessionHandle) };
             h.mic_muted
-                .store(muted != 0, std::sync::atomic::Ordering::Relaxed);
+                .store(muted, std::sync::atomic::Ordering::Relaxed);
         }
     })
 }
@@ -617,18 +607,18 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetMicMuted
 /// refused every AAudio input rung (or a missing RECORD_AUDIO grant) shows no control instead of a
 /// lie about a mic that is being heard. `false` on a `0` handle. Cheap (one uncontended lock).
 #[cfg(target_os = "android")]
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeMicActive(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jboolean {
-    jni_guard(0, || {
+    jni_guard(false, || {
         if handle == 0 {
-            return 0;
+            return false;
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
-        jboolean::from(lock_recover(&h.mic).is_some())
+        lock_recover(&h.mic).is_some()
     })
 }

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

@@ -10,9 +10,10 @@
 //! coroutine on the main thread the way it polls the stats HUD.
 
 use super::{jni_guard, SessionHandle};
-use jni::objects::JObject;
-use jni::sys::{jboolean, jdoubleArray, jint, jlong};
-use jni::JNIEnv;
+use jni::errors::LogErrorAndDefault;
+use jni::objects::{JDoubleArray, JObject};
+use jni::sys::{jboolean, jint, jlong};
+use jni::EnvUnowned;
 
 /// The `DoubleArray` [`Java_io_unom_punktfunk_kit_NativeBridge_nativeProbeResult`] returns. Kept in
 /// one place because Kotlin indexes it positionally; see the Kotlin doc for the field order.
@@ -23,27 +24,27 @@ const PROBE_RESULT_LEN: usize = 6;
 /// **briefly pausing video**. Non-blocking: poll
 /// [`Java_io_unom_punktfunk_kit_NativeBridge_nativeProbeResult`] until its `done` element is 1.
 /// Starting a probe resets any prior measurement. `false` on a `0` handle or a closed session.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSpeedTest(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     target_kbps: jint,
     duration_ms: jint,
 ) -> jboolean {
-    jni_guard(0, || {
+    jni_guard(false, || {
         if handle == 0 {
-            return 0;
+            return false;
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
         let target = target_kbps.clamp(0, i32::MAX) as u32;
         let duration = duration_ms.clamp(0, i32::MAX) as u32;
         match h.client.request_probe(target, duration) {
-            Ok(()) => 1,
+            Ok(()) => true,
             Err(e) => {
                 log::warn!("speed test: could not ask the host to probe: {e:?}");
-                0
+                false
             }
         }
     })
@@ -54,15 +55,17 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSpeedTest(
 ///
 /// Layout (doubles so one array carries both the counts and the percentages):
 /// `[done, throughputKbps, lossPct, hostDropPct, elapsedMs, recvBytes]`.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeProbeResult<'local>(
-    env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     handle: jlong,
-) -> jdoubleArray {
-    jni_guard(JObject::null().into_raw(), || {
+) -> JDoubleArray<'local> {
+    // `JDoubleArray::default()` is the null reference the old `JObject::null().into_raw()` returned,
+    // so Kotlin still reads `null` on every failure path.
+    env.with_env(|env| -> jni::errors::Result<JDoubleArray<'local>> {
         if handle == 0 {
-            return JObject::null().into_raw();
+            return Ok(JDoubleArray::default());
         }
         // SAFETY: live handle per the nativeConnect/nativeClose contract.
         let h = unsafe { &*(handle as *const SessionHandle) };
@@ -75,14 +78,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeProbeResult
             f64::from(r.elapsed_ms),
             r.recv_bytes as f64,
         ];
-        match env.new_double_array(PROBE_RESULT_LEN as i32) {
-            Ok(arr) => {
-                if env.set_double_array_region(&arr, 0, &values).is_err() {
-                    return JObject::null().into_raw();
-                }
-                arr.into_raw()
-            }
-            Err(_) => JObject::null().into_raw(),
-        }
+        let arr = env.new_double_array(PROBE_RESULT_LEN)?;
+        arr.set_region(env, 0, &values)?;
+        Ok(arr)
     })
+    .resolve::<LogErrorAndDefault>()
 }

clients/android/native/src/wol.rs

@@ -3,38 +3,35 @@
 //! host has no ARP entry, so the broadcast the core sends is what wakes it, and Kotlin calls this
 //! just before connecting to an offline saved host.
 
+use jni::errors::LogErrorAndDefault;
 use jni::objects::{JObject, JString};
-use jni::JNIEnv;
+use jni::EnvUnowned;
 
 /// `NativeBridge.nativeWakeOnLan(macsCsv: String, lastIp: String): Boolean` — send a Wake-on-LAN
 /// magic packet. `macsCsv` is comma-separated MACs (`aa:bb:..,cc:dd:..`, learned from the host's
 /// mDNS `mac` TXT while it was online); `lastIp` is the host's last-known IPv4 (or empty).
 /// Returns true if at least one datagram went out.
-#[no_mangle]
+#[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeWakeOnLan<'local>(
-    mut env: JNIEnv<'local>,
+    mut env: EnvUnowned<'local>,
     _this: JObject<'local>,
     macs_csv: JString<'local>,
     last_ip: JString<'local>,
 ) -> jni::sys::jboolean {
-    let macs_csv: String = match env.get_string(&macs_csv) {
-        Ok(s) => s.into(),
-        Err(_) => return 0,
-    };
-    let last_ip: String = env
-        .get_string(&last_ip)
-        .map(Into::<String>::into)
-        .unwrap_or_default();
-    let macs: Vec<[u8; 6]> = macs_csv
-        .split(',')
-        .filter_map(|s| punktfunk_core::wol::parse_mac(s.trim()))
-        .collect();
-    if macs.is_empty() {
-        return 0;
-    }
-    let ip = last_ip.trim().parse::<std::net::Ipv4Addr>().ok();
-    match punktfunk_core::wol::send_magic_packet(&macs, ip) {
-        Ok(()) => 1,
-        Err(_) => 0,
-    }
+    env.with_env(|env| -> jni::errors::Result<bool> {
+        let macs_csv: String = macs_csv.try_to_string(env)?;
+        // Unlike `macs_csv`, an unreadable `lastIp` is not fatal: the core falls back to the
+        // subnet broadcast when it has no address, so keep the old lenient default.
+        let last_ip: String = last_ip.try_to_string(env).unwrap_or_default();
+        let macs: Vec<[u8; 6]> = macs_csv
+            .split(',')
+            .filter_map(|s| punktfunk_core::wol::parse_mac(s.trim()))
+            .collect();
+        if macs.is_empty() {
+            return Ok(false);
+        }
+        let ip = last_ip.trim().parse::<std::net::Ipv4Addr>().ok();
+        Ok(punktfunk_core::wol::send_magic_packet(&macs, ip).is_ok())
+    })
+    .resolve::<LogErrorAndDefault>()
 }

clients/apple/App/Assets.xcassets/AboutAppIcon.imageset/Contents.json

@@ -0,0 +1,18 @@
+{
+  "images" : [
+    {
+      "filename" : "about-icon@1x.png",
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "about-icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -83,14 +83,6 @@ struct ContentView: View {
     /// never covers the video.
     @State private var isFullscreen = false
     #endif
-    #if os(macOS) || os(tvOS)
-    /// Shows the start-of-stream shortcut banner (the Windows client's discoverability
-    /// pattern): raised on every transition to `.streaming`, dropped by the banner's own
-    /// 6-second task. Independent of the stats HUD so the keys are discoverable even with
-    /// statistics off. On tvOS it carries the ONLY exits (hold Back / the pad chord) plus
-    /// the remote-as-pointer controls, so it must be seen at least once per session.
-    @State private var showShortcutHint = false
-    #endif
     #if os(iOS)
     /// The stats-OFF tier's touch-exit disc window (see the overlay in `stream(captureEnabled:)`
     /// — the disc must LEAVE the hierarchy so nothing composites over the metal layer).
@@ -347,9 +339,6 @@ struct ContentView: View {
         .onChange(of: model.phase) { _, phase in
             switch phase {
             case .streaming:
-                #if os(macOS) || os(tvOS)
-                showShortcutHint = true // the 6 s shortcut banner, per session start
-                #endif
                 #if os(iOS)
                 showTouchExit = true // the off-tier exit disc's 8 s window, per session start
                 #endif
@@ -453,6 +442,10 @@ struct ContentView: View {
                 LibraryView(store: store, target: shelf, onLaunch: { launchTitle(shelf, $0) })
             }
             .frame(minWidth: 940, minHeight: 620)
+            // The stack draws the title, and it sits outside LibraryView's own ink — see the tvOS
+            // cover. Gated, because this sheet is BOTH modes' library on macOS and the touch
+            // grid's title belongs to the system background.
+            .gamepadPaletteInk(gamepadUIActive)
         }
         #else
         // iOS: the cover is the TOUCH UI's presentation only. In gamepad mode the library is one
@@ -822,6 +815,7 @@ struct ContentView: View {
                     onPaired: handlePaired, waker: waker,
                     connect: { connect($0, profile: $1) }, connectDiscovered: connectDiscovered,
                     launchTitle: launchTitle,
+                    wakeOnly: { wakeOnly($0) },
                     promptActive: consolePromptShowing)
             } else {
                 HomeView(
@@ -841,6 +835,7 @@ struct ContentView: View {
                     onPaired: handlePaired, waker: waker,
                     connect: { connect($0, profile: $1) }, connectDiscovered: connectDiscovered,
                     launchTitle: launchTitle,
+                    wakeOnly: { wakeOnly($0) },
                     promptActive: consolePromptShowing)
                 // On tvOS pairing/library normally present from HomeView's navigationDestinations
                 // — which aren't mounted while the gamepad launcher is up. Give the launcher its
@@ -851,12 +846,29 @@ struct ContentView: View {
                 .fullScreenCover(item: $pairingTarget) { host in
                     PairSheet(host: host) { fingerprint in handlePaired(host, fingerprint: fingerprint) }
                         .onExitCommand { pairingTarget = nil }
+                        // A tvOS cover draws NO background of its own, and this one is attached
+                        // outside the launcher's `gamepadPaletteInk` — so the pairing screen used
+                        // to render the system's dark chrome directly over the launcher showing
+                        // through it, which under a pale palette is white text on a bright field
+                        // (the PIN prompt was all but invisible). Give it the console's own field
+                        // and the palette's ink, like every other screen the launcher opens. Only
+                        // this branch: `HomeView`'s route to the same sheet is the TOUCH UI, which
+                        // sits on the system background and has no palette.
+                        .frame(maxWidth: .infinity, maxHeight: .infinity)
+                        .background { GamepadFormBackground() }
+                        .gamepadPaletteInk()
                 }
                 .fullScreenCover(item: $libraryTarget) { shelf in
                     NavigationStack {
                         LibraryView(store: store, target: shelf, onLaunch: { launchTitle(shelf, $0) })
                     }
                     .onExitCommand { libraryTarget = nil }
+                    // On the STACK, not just inside LibraryView: the navigation title is drawn by
+                    // the stack, which wraps that view from outside its own `gamepadPaletteInk` —
+                    // so the shelf's name stayed white over a pale field while the content below
+                    // it had already gone dark. Unconditional here because this cover only exists
+                    // in the launcher's branch, where the console UI is by definition drawing.
+                    .gamepadPaletteInk()
                 }
                 #endif
             } else {
@@ -973,9 +985,15 @@ struct ContentView: View {
                         model?.disconnect() // the captured-state ⌃⌥⇧D combo
                     },
                     onFrame: { [meter = model.meter, latency = model.latency,
-                                split = model.latencySplit, queue = model.clientQueue,
-                                offset = conn.clockOffsetNs] au in
+                                split = model.latencySplit, queue = model.clientQueue] au in
                         meter.note(byteCount: au.data.count)
+                        // Read the offset PER AU (an atomic load), never in the capture list: a
+                        // capture-list `offset =` froze the connect-time estimate for the whole
+                        // session, and on a host whose wall clock steps (VM + NTP) that frozen
+                        // value shifted hostnet/e2e by ~15 ms between sessions while the meter's
+                        // impossible-sample guard hid the damage (field 2026-08-13). See
+                        // `PunktfunkConnection.clockOffsetNs`.
+                        let offset = conn.clockOffsetNs
                         latency.record(ptsNs: au.ptsNs, offsetNs: offset)
                         // The same receipt, keyed by pts, awaiting its 0xCF host timing (the
                         // host/network split — drained by the 1 s stats tick). receivedNs is
@@ -1048,31 +1066,15 @@ struct ContentView: View {
                                 .transition(.opacity.combined(with: .scale(scale: 0.9)))
                         }
                         #endif
-                        #if os(macOS) || os(tvOS)
-                        // The start-of-stream shortcut banner (Windows-client parity): the
+                        // The start-of-stream shortcut banner used to sit here (macOS/tvOS): the
                         // platform's reserved controls on a glass pill for the first 6 seconds of
-                        // every session — independent of the stats HUD, so the keys are
-                        // discoverable even with statistics off. The banner's own task drops it
-                        // (cancelled cleanly if the session view goes away first). On tvOS it
-                        // carries the ONLY exits — Menu/B is swallowed during a session (the
-                        // `.onExitCommand {}` in the tvOS session branch), so the hold gestures
-                        // must be told to the user.
-                        if captureEnabled && showShortcutHint {
-                            Text(shortcutHintText)
-                                .font(.geist(Self.shortcutHintFont, relativeTo: .caption))
-                                .foregroundStyle(.secondary)
-                                .padding(.horizontal, 14)
-                                .padding(.vertical, 8)
-                                .glassBackground(Capsule())
-                                .transition(.opacity)
-                                .task {
-                                    try? await Task.sleep(for: .seconds(6))
-                                    withAnimation(.easeOut(duration: 0.6)) {
-                                        showShortcutHint = false
-                                    }
-                                }
-                        }
-                        #endif
+                        // every session. It is now a page you can OPEN — About ▸ Shortcuts, on
+                        // both the touch and the controller surface (ShortcutsCatalog) — because
+                        // a message that shows once, over the stream you have just connected to,
+                        // is unavailable at the moment the question is actually asked. It also
+                        // put a composited overlay above the stream for those 6 seconds, which on
+                        // this path costs a refresh of display latency (see the iOS exit disc's
+                        // note below); the reference page costs nothing during a session.
                     }
                     .padding(.bottom, 24)
                     .animation(.easeOut(duration: 0.2), value: model.micMuted)
@@ -1139,23 +1141,10 @@ struct ContentView: View {
     }
     #endif
 
-    #if os(macOS)
-    /// The reserved combos, told once per session. The mute segment appears only when the session
-    /// actually sends a microphone — teaching a shortcut for a mic that isn't on would be a lie.
-    private var shortcutHintText: String {
-        let base =
-            "Click the stream to capture · ⌃⌥⇧Q releases the mouse · ⌃⌥⇧D disconnects · ⌃⌥⇧S stats"
-        return model.micAvailable ? base + " · ⌃⌥⇧A mutes the mic" : base
-    }
-    private static let shortcutHintFont: CGFloat = 12
-    #elseif os(tvOS)
-    private var shortcutHintText: String {
-        "Hold the remote's Back button — or L1+R1+Start+Select on a controller — to disconnect"
-        + " · Touch surface moves the pointer · press clicks · Play/Pause right-clicks"
-        + " · Hold Play/Pause, or Select+X on a controller, for statistics"
-    }
-    private static let shortcutHintFont: CGFloat = 22 // read from the couch
-    #endif
+    // The two `shortcutHintText` strings that used to live here — one per platform, told once per
+    // session by the banner above — are now `ShortcutsCatalog.groups`, which both About pages
+    // render. The mic line is still conditional there for the same reason it was here: teaching a
+    // shortcut for a microphone that isn't on would be a lie.
 
     // MARK: - Connect
 

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

@@ -12,7 +12,10 @@ import SwiftUI
 #if os(iOS) || os(macOS) || os(tvOS)
 
 struct GamepadAddHostView: View {
-    @Environment(\.gamepadInk) private var ink
+    /// Resolved from the stored palette, NOT from `\.gamepadInk` — this screen publishes that
+    /// value itself and so sits above its own copy (see `GamepadInk.stored`).
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+    private var ink: GamepadInk { .stored(paletteID) }
     @Environment(\.gamepadMetrics) private var metrics
     @Environment(\.displayBottomInset) private var displayBottomInset
     @Environment(\.dismiss) private var dismiss
@@ -25,6 +28,18 @@ struct GamepadAddHostView: View {
     /// Whether this screen owns the controller — false while the shell is mid-transition or the
     /// connect takeover is up (see GamepadSettingsView's twin).
     var controllerActive = true
+    /// Non-nil ⇒ this screen is EDITING that saved host rather than registering a new one: the
+    /// fields start on its values and `onAdd` receives it back with only name/address/port
+    /// changed, so the fingerprint, pins, binding and MACs it carries survive the edit. A
+    /// re-typed address is the whole point of the screen (a host that moved), so nothing here
+    /// re-derives identity from it — that is the trust store's job, not this form's.
+    ///
+    /// Declared after the closures for the same trailing-closure reason as `close`, and it is a
+    /// plain value besides, so it can never capture one.
+    var editingHost: StoredHost?
+    /// One-shot seed guard: `@State` cannot be initialised from a property without a custom init,
+    /// and a custom init would break every existing trailing-closure call site.
+    @State private var seeded = false
 
     #if os(iOS)
     /// `.compact` in a landscape phone window — tighter chrome so the keyboard tray still fits.
@@ -57,12 +72,15 @@ struct GamepadAddHostView: View {
         .safeAreaInset(edge: .top, spacing: 0) {
             VStack(alignment: .leading, spacing: gamepadHeaderSpacing(compact: compact)) {
                 // Leading, like every gamepad heading — and no close chrome (B is the exit).
-                Text("Add Host")
+                Text(editingHost == nil ? "Add Host" : "Edit Host")
                     .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
                     .foregroundStyle(ink.fg)
                 if !compact {
-                    Text("Hosts on this network appear automatically — add one by address "
-                        + "for everything else.")
+                    Text(editingHost == nil
+                        ? "Hosts on this network appear automatically — add one by address "
+                            + "for everything else."
+                        : "Rename this host, or point it at a new address — its pairing and "
+                            + "pinned cards are kept.")
                         .font(.geist(metrics.detailFont, relativeTo: .caption))
                         .foregroundStyle(ink.fg(0.55))
                         .multilineTextAlignment(.leading)
@@ -98,6 +116,17 @@ struct GamepadAddHostView: View {
         .onChange(of: port) { _, value in
             if value.count > 5 { port = String(value.prefix(5)) }
         }
+        // Seed the fields from the host being edited, exactly once: re-seeding on a later appear
+        // (the shell re-mounts a layer when the app returns from the background) would silently
+        // throw away whatever had been typed.
+        .onAppear {
+            guard !seeded else { return }
+            seeded = true
+            guard let host = editingHost else { return }
+            name = host.name
+            address = host.address
+            port = String(host.port)
+        }
         #if !os(tvOS)
         // The visible close ✕ is gone (a gamepad UI exits with B) — this keeps a hardware
         // keyboard's Esc and the macOS sheet's cancel working without chrome.
@@ -202,7 +231,9 @@ struct GamepadAddHostView: View {
             Row(id: "name", label: "Name", value: name, placeholder: "Optional — e.g. Living Room"),
             Row(id: "address", label: "Address", value: address, placeholder: "IP or hostname"),
             Row(id: "port", label: "Port", value: port, placeholder: "9777"),
-            Row(id: "add", label: "Add Host", isAction: true),
+            Row(
+                id: "add", label: editingHost == nil ? "Add Host" : "Save Changes",
+                isAction: true),
         ]
     }
 
@@ -261,10 +292,21 @@ struct GamepadAddHostView: View {
                 openKeyboard("address")
                 return
             }
-            onAdd(StoredHost(
-                name: name.trimmingCharacters(in: .whitespaces),
-                address: address.trimmingCharacters(in: .whitespaces),
-                port: UInt16(port) ?? 9777))
+            let typedName = name.trimmingCharacters(in: .whitespaces)
+            let typedAddress = address.trimmingCharacters(in: .whitespaces)
+            let typedPort = UInt16(port) ?? 9777
+            if var host = editingHost {
+                // Mutate a COPY of the stored record rather than building a fresh one: everything
+                // this form does not show — the pinned fingerprint, WoL MACs, pinned profile
+                // cards, the default binding, `addedAt` — has to survive a rename.
+                host.name = typedName
+                host.address = typedAddress
+                host.port = typedPort
+                onAdd(host)
+            } else {
+                onAdd(StoredHost(
+                    name: typedName, address: typedAddress, port: typedPort))
+            }
             performClose()
         default:
             openKeyboard(id)

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

@@ -48,6 +48,13 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
     var onTertiary: (() -> Void)?
     /// B → back/dismiss; nil disables it (e.g. the root launcher has nowhere to go back to).
     var onBack: (() -> Void)?
+    /// UP → the focused item's own menu (the launcher's host options). Wiring it takes the whole
+    /// VERTICAL axis away from scrolling: up opens the menu and down goes inert, rather than up
+    /// meaning "menu" while down still stepped the strip. A horizontal carousel has no vertical
+    /// travel to spend, and the desktop and Android consoles both read the axis this way — one
+    /// meaning per direction is what makes the gesture learnable across the three of them.
+    /// nil leaves up/down as a second way to step (what every carousel without a menu still does).
+    var onUp: (() -> Void)?
     /// L1/R1 → jump this many items at once (clamped to the ends); 0 disables the shoulders.
     var shoulderJump: Int = 0
     /// Whether this carousel currently owns controller input. A presenting screen (e.g. the host
@@ -301,6 +308,17 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
         // The poll carries only the buttons focus has no concept of: Y/X, the screen actions.
         input.onSecondary = onSecondary
         input.onTertiary = onTertiary
+        // UP is the one direction the poll may also read here, and ONLY to open the menu — it
+        // never calls `step`, so it cannot double-move against the focus engine. Routing it
+        // through `.onMoveCommand` instead was the obvious alternative and the wrong one: that
+        // stream is 4-way and its interception is input-source-dependent on real hardware (see
+        // GamepadMenuList's tvOS note), so claiming up there risks left/right focus with it.
+        // Nothing sits above the strip for the engine to move to, so this direction is free.
+        if let onUp {
+            input.onMove = { direction in
+                if direction == .up { onUp() }
+            }
+        }
         #else
         input.onMove = { move($0) }
         input.onConfirm = { activate() }
@@ -312,6 +330,14 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
     }
 
     private func move(_ direction: GamepadMenuInput.Direction) {
+        // With a menu wired, vertical is the menu's axis, not a second scroll axis — see `onUp`.
+        if let onUp {
+            switch direction {
+            case .up: return onUp()
+            case .down: return
+            case .left, .right: break
+            }
+        }
         let forward = direction == .right || direction == .down
         step(by: forward ? 1 : -1, clampAtEnds: false)
     }

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

@@ -430,7 +430,12 @@ private struct HintCellStyle: ButtonStyle {
 /// can't inflate the caller's layout past the safe area (see the layout note in GamepadHomeView's
 /// header). Honors Reduce Motion by freezing the field at a fixed phase.
 struct GamepadScreenBackground: View {
-    @Environment(\.gamepadInk) private var ink
+    /// Resolved from `paletteID` below rather than `\.gamepadInk`: this is mounted as a screen's
+    /// `.background { }`, which the screen attaches BEFORE its own `gamepadPaletteInk()`, so the
+    /// environment here is the screen's parent's — the dark default under a cover or a sheet. It
+    /// only feeds a pale palette's scrim, so the symptom was subtle: the field bleached toward
+    /// white instead of settling onto its own ink. (see `GamepadInk.stored`)
+    private var ink: GamepadInk { .stored(paletteID) }
     /// How far toward the form screens' quiet the field sits: 0 = the launcher's full aurora,
     /// 1 = calm, fractional mid-chase. Continuous (not a Bool) so the in-place shell can CHASE
     /// it during a push/pop — the console does the same with its `bg_mix` — and every

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

@@ -64,7 +64,10 @@ private struct HomeTile: Identifiable {
 }
 
 struct GamepadHomeView: View {
-    @Environment(\.gamepadInk) private var ink
+    /// Resolved from the stored palette, NOT from `\.gamepadInk` — this screen publishes that
+    /// value itself and so sits above its own copy (see `GamepadInk.stored`).
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+    private var ink: GamepadInk { .stored(paletteID) }
     /// Published by ContentView at the app ROOT, so this reads its own window's tier — this screen
     /// applies `gamepadPaletteInk` itself and so sits above its own copy of the environment.
     @Environment(\.gamepadMetrics) private var metrics
@@ -91,6 +94,10 @@ struct GamepadHomeView: View {
     /// 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: (LibraryTarget, String) -> Void
+    /// Wake a host WITHOUT connecting (ContentView's `wakeOnly`) — the host menu's Wake row. The
+    /// tile's own A already wakes-and-connects; this is the other half, for bringing a machine up
+    /// to look at it rather than to stream from it right now.
+    let wakeOnly: (StoredHost) -> 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
@@ -119,6 +126,11 @@ struct GamepadHomeView: View {
     @State private var selection: GamepadHomeTarget?
     @State private var showSettings = false
     @State private var showAddHost = false
+    /// The card whose options menu is up (UP on a saved tile) — see GamepadHostOptionsView.
+    @State private var hostOptionsTarget: HostOptionsTarget?
+    /// The host being edited. Set from the options menu, which closes itself as it opens this so
+    /// the two are never stacked — depth stays ≤ 1, which is what `GamepadScreen` assumes.
+    @State private var editTarget: StoredHost?
     /// The console's input drop: true for the transition's 0.26 s, during which NO layer polls
     /// the controller — a double-tapped A can't push two screens, and the held button that
     /// caused the change is long released before the next poller starts (whose own
@@ -201,19 +213,37 @@ struct GamepadHomeView: View {
         // shell's layers above ARE the presentation.
         #if os(macOS)
         .sheet(isPresented: $showSettings) {
-            GamepadSettingsView(store: store)
+            GamepadSettingsView(store: store, micAvailable: model.micAvailable)
                 .frame(width: 720, height: 640)
         }
         .sheet(isPresented: $showAddHost) {
             GamepadAddHostView { store.add($0) }
                 .frame(width: 660, height: 620)
         }
+        // Shorter than the forms above: a menu is five rows, and a sheet sized for a settings
+        // screen would be mostly empty field under them.
+        .sheet(item: $hostOptionsTarget) { target in
+            hostOptionsView(target, active: true)
+                .frame(width: 620, height: 460)
+        }
+        .sheet(item: $editTarget) { host in
+            editHostView(host, active: true)
+                .frame(width: 660, height: 620)
+        }
         .frame(minWidth: 640, minHeight: 420)
         #elseif os(tvOS)
-        .fullScreenCover(isPresented: $showSettings) { GamepadSettingsView(store: store) }
+        .fullScreenCover(isPresented: $showSettings) {
+            GamepadSettingsView(store: store, micAvailable: model.micAvailable)
+        }
         .fullScreenCover(isPresented: $showAddHost) {
             GamepadAddHostView { store.add($0) }
         }
+        .fullScreenCover(item: $hostOptionsTarget) { target in
+            hostOptionsView(target, active: true)
+        }
+        .fullScreenCover(item: $editTarget) { host in
+            editHostView(host, active: true)
+        }
         #endif
     }
 
@@ -261,6 +291,10 @@ struct GamepadHomeView: View {
         // can be raised from ON TOP of the library (launching a title on an unpaired host), where
         // it has to win. Backing out of it reveals whatever it interrupted.
         if let host = pairingTarget { return .pair(host) }
+        // Editing leads the menu that raised it: the menu clears itself on the way, so the two are
+        // never both set, and if they somehow were, the screen the user asked for last should win.
+        if let host = editTarget { return .editHost(host) }
+        if let target = hostOptionsTarget { return .hostOptions(target) }
         if showSettings { return .settings }
         if showAddHost { return .addHost }
         if let shelf = libraryTarget { return .library(shelf) }
@@ -277,12 +311,17 @@ struct GamepadHomeView: View {
                 GamepadSettingsView(
                     store: store,
                     close: { if !transitioning { showSettings = false } },
-                    controllerActive: active)
+                    controllerActive: active,
+                    micAvailable: model.micAvailable)
             case .addHost:
                 GamepadAddHostView(
                     onAdd: { store.add($0) },
                     close: { if !transitioning { showAddHost = false } },
                     controllerActive: active)
+            case .hostOptions(let target):
+                hostOptionsView(target, active: active)
+            case .editHost(let host):
+                editHostView(host, active: active)
             case .pair(let host):
                 GamepadPairView(
                     host: host,
@@ -414,6 +453,7 @@ struct GamepadHomeView: View {
             onActivate: { $0.activate() },
             onSecondary: { openLibraryForSelected() },
             onTertiary: { showSettings = true },
+            onUp: { openOptionsForSelected() },
             isActive: homeOwnsController
         ) { tile, entrance in
             hostCard(tile, size: CGSize(width: cardWidth, height: cardHeight), entrance: entrance)
@@ -469,6 +509,14 @@ struct GamepadHomeView: View {
                 glyph: buttonGlyph(\.buttonY, fallback: "y.circle"), text: "Library",
                 action: { openLibraryForSelected() }))
         }
+        // Only a saved card has a menu, so the cell appears only where the press does something —
+        // the same honesty rule the Library cell above follows. A direction, not a button, so it
+        // is a plain arrow rather than a `buttonGlyph` (see the settings screen's "Adjust").
+        if case .saved = selected?.id {
+            hints.append(.init(
+                glyph: "arrow.up", text: "Options",
+                action: { openOptionsForSelected() }))
+        }
         hints.append(.init(
             glyph: buttonGlyph(\.buttonX, fallback: "x.circle"), text: "Settings",
             action: { showSettings = true }))
@@ -543,6 +591,60 @@ struct GamepadHomeView: View {
     /// `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.
+    /// The host menu, built once for all three presentations (the iOS shell layer, the macOS
+    /// sheet, the tvOS cover) so the actions can't drift between them.
+    ///
+    /// Edit REPLACES this menu rather than stacking on it — `hostOptionsTarget` is cleared as
+    /// `editTarget` is set — which is the desktop console's `Nav::Replace` and what keeps the
+    /// shell's "depth ≤ 1 by construction" claim true.
+    @ViewBuilder
+    private func hostOptionsView(_ target: HostOptionsTarget, active: Bool) -> some View {
+        let host = target.host
+        GamepadHostOptionsView(
+            host: host,
+            pinnedProfile: target.profile,
+            isOnline: discovery.advertises(host) || store.probedOnline.contains(host.id),
+            canWake: autoWakeEnabled && PunktfunkConnection.wakeOnLANAvailable
+                && !host.wakeMacs.isEmpty,
+            onEdit: {
+                guard !transitioning else { return }
+                hostOptionsTarget = nil
+                editTarget = host
+            },
+            onWake: { wakeOnly(host) },
+            onForgetPairing: { store.forgetIdentity(host) },
+            onRemove: { store.remove(host) },
+            onUnpin: {
+                guard let profile = target.profile else { return }
+                store.setPinned(host.id, profileID: profile.id, pinned: false)
+            },
+            close: { if !transitioning { hostOptionsTarget = nil } },
+            controllerActive: active)
+    }
+
+    /// The add-host form in edit mode. `store.update` writes the record back by id, so the
+    /// fingerprint, MACs, pins and binding the form never shows are preserved.
+    @ViewBuilder
+    private func editHostView(_ host: StoredHost, active: Bool) -> some View {
+        GamepadAddHostView(
+            onAdd: { store.update($0) },
+            close: { if !transitioning { editTarget = nil } },
+            controllerActive: active,
+            editingHost: host)
+    }
+
+    /// UP on a saved tile opens that card's menu. Only SAVED hosts have one: a discovered-but-
+    /// unsaved host is not ours to rename or remove, and the two action tiles have nothing to
+    /// offer — the same `HostOptionsScreen::available` gate the desktop console applies.
+    private func openOptionsForSelected() {
+        guard case .saved(let id, let profileID) = selection,
+              let host = store.hosts.first(where: { $0.id == id })
+        else { return }
+        hostOptionsTarget = HostOptionsTarget(
+            host: host,
+            profile: profileID.flatMap { pid in profiles.profiles.first { $0.id == pid } })
+    }
+
     private func openLibraryForSelected() {
         guard libraryEnabled, case .saved(let id, let profileID) = selection,
               let host = store.hosts.first(where: { $0.id == id })
@@ -657,6 +759,12 @@ private struct GamepadHostTile: View {
 
     private var monogramBadge: some View {
         let shape = RoundedRectangle(cornerRadius: Self.badgeCorner, style: .continuous)
+        // What the glyph is drawn ON: a filled badge IS the accent, so its mark takes `onAccent`
+        // — the colour picked by the accent's own luminance — exactly as the settings screen's
+        // selected tab pill does. It used to take `fg`, which is chosen against the FIELD, and the
+        // two disagree at both ends of the set: a pale palette put near-black on a deep accent, and
+        // Graphite (accent luma ≈ 0.80) put white on a light grey.
+        let glyph = tile.filled ? ink.onAccent : ink.accent
         return ZStack {
             shape.fill(tile.filled
                 ? AnyShapeStyle(LinearGradient(
@@ -664,7 +772,7 @@ private struct GamepadHostTile: View {
                     startPoint: .top, endPoint: .bottom))
                 : AnyShapeStyle(ink.accent(0.16)))
             if tile.isConnecting {
-                ProgressView().tint(ink.fg)
+                ProgressView().tint(glyph)
             } else if let icon = tile.icon {
                 Image(systemName: icon)
                     .font(.system(size: Self.iconFont, weight: .semibold))
@@ -676,12 +784,12 @@ private struct GamepadHostTile: View {
                     .resizable()
                     .scaledToFit()
                     .frame(width: Self.monogramFont, height: Self.monogramFont)
-                    .foregroundStyle(tile.filled ? ink.fg : ink.accent)
+                    .foregroundStyle(glyph)
                     .accessibilityLabel(tile.osChain ?? "")
             } else {
                 Text(monogram(tile.title))
                     .font(.geistFixed(Self.monogramFont, .bold))
-                    .foregroundStyle(tile.filled ? ink.fg : ink.accent)
+                    .foregroundStyle(glyph)
             }
         }
         .frame(width: Self.badgeSide, height: Self.badgeSide)

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

@@ -0,0 +1,321 @@
+// A saved host's own actions — Wake, Copy link, Edit…, Forget pairing, Remove — reached with UP on
+// its carousel tile. The console's answer to the overflow menu the touch grid hangs off every host
+// card (HostCardView's context menu), and the Apple port of `pf-console-ui`'s HostOptionsScreen.
+//
+// Until now the gamepad UI could add a host and connect to one, and that was all: a renamed machine
+// or a host typed in with a fat-fingered address stayed wrong forever, because the only surface
+// that could edit or remove one was the touch UI. The tile is where a host is, so the tile is where
+// its actions belong.
+//
+// UP is the gesture because the carousel is horizontal — left/right are spoken for and up is free —
+// and because the desktop console and the Android console already do exactly this, so the three are
+// learned once. A pinned profile card offers only Unpin: it is a shortcut, not a second host, and
+// offering to remove the host from it would blur precisely the distinction a pin exists to draw.
+//
+// Vocabulary note: this screen says "Forget pairing" and "Remove host" where the desktop console
+// says one word, "Forget". The console has only the one action; Apple has both (HostCardView calls
+// them `onForget` = drop the pinned fingerprint and `onRemove` = delete the record), and two
+// different actions cannot share a name on the surface that offers both. The touch card's words
+// win over the other consoles' here — a user meets both Apple surfaces, and only one of them is
+// cross-platform.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS) || os(tvOS)
+
+/// Which card the menu was opened on. Carries the host BY VALUE for the same reason the screen
+/// does — the carousel is rebuilt on every discovery pass, and a target that re-resolved itself
+/// could hand "Remove" a different host than the one the user was looking at.
+struct HostOptionsTarget: Identifiable {
+    let host: StoredHost
+    /// Non-nil ⇒ a pinned profile card rather than the host's own tile.
+    var profile: StreamProfile?
+
+    /// Keyed on the CARD, not the host: a host and each of its pinned cards open different menus,
+    /// and sharing an id would let one stand in for another mid-transition (the same rule
+    /// `GamepadScreen.library` follows).
+    var id: String { "\(host.id.uuidString)-\(profile?.id ?? "")" }
+}
+
+struct GamepadHostOptionsView: View {
+    /// Resolved from the stored palette, NOT from `\.gamepadInk` — this screen publishes that
+    /// value itself and so sits above its own copy (see `GamepadInk.stored`).
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+    private var ink: GamepadInk { .stored(paletteID) }
+    @Environment(\.gamepadMetrics) private var metrics
+    @Environment(\.displayBottomInset) private var displayBottomInset
+    @Environment(\.gamepadHostedInShell) private var hostedInShell
+    @Environment(\.dismiss) private var dismiss
+
+    /// The host this menu was opened on, BY VALUE. Discovery rewrites the carousel on every
+    /// service pass; holding an index or a live lookup would let the menu retarget itself onto
+    /// whichever host slid into that slot, and "Remove" must never be able to do that.
+    let host: StoredHost
+    /// Non-nil ⇒ opened on a pinned profile card rather than the host's own tile.
+    var pinnedProfile: StreamProfile?
+    /// Whether the host is reachable right now — decides whether Wake is worth offering.
+    var isOnline = false
+    /// Whether waking is possible at all (the setting is on, WoL is available, a MAC is known).
+    var canWake = false
+    let onEdit: () -> Void
+    let onWake: () -> Void
+    /// Drop the pinned fingerprint — the host stays saved, and the next connect re-pairs.
+    let onForgetPairing: () -> Void
+    /// Delete the saved record outright.
+    let onRemove: () -> Void
+    let onUnpin: () -> Void
+    var close: (() -> Void)?
+    var controllerActive = true
+
+    #if os(iOS)
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false
+    #endif
+
+    /// Removing is the one action here with no undo, so its row ARMS on the first press and only
+    /// fires on the second. The touch grid removes behind a system confirmation dialog; a console
+    /// is driven by a thumbstick from across a room, which is a good reason to be at least as
+    /// strict as it is, and none at all to be looser.
+    @State private var armed = false
+    @State private var copied = false
+    @State private var focusID: String?
+
+    private enum Action: String {
+        case wake
+        case copyLink
+        case edit
+        case forgetPairing
+        case remove
+        case unpin
+        case cancel
+    }
+
+    var body: some View {
+        GamepadMenuList(
+            items: rows,
+            focusID: $focusID,
+            onActivate: { run($0.action) },
+            onBack: { performClose() },
+            isActive: controllerActive
+        ) { row, focused in
+            rowView(row, focused: focused)
+                .frame(maxWidth: metrics.rowMaxWidth)
+                .padding(.horizontal, 24)
+        }
+        .frame(maxWidth: .infinity)
+        .safeAreaInset(edge: .top, spacing: 0) {
+            VStack(alignment: .leading, spacing: gamepadHeaderSpacing(compact: compact)) {
+                Text(title)
+                    .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
+                    .foregroundStyle(ink.fg)
+                    .lineLimit(1)
+                if !compact {
+                    Text("\(host.address):\(String(host.port))")
+                        .font(.geistFixed(metrics.detailFont, .medium))
+                        .foregroundStyle(ink.fg(0.55))
+                }
+            }
+            .padding(.horizontal, 24)
+            .padding(.top, gamepadTitleTopPadding(compact: compact))
+            .padding(.bottom, gamepadTitleBottomPadding(compact: compact))
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background { GamepadTrayBlur(edge: .top) }
+        }
+        .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
+            VStack(alignment: .leading, spacing: 8) {
+                Text(detail)
+                    .font(.geist(metrics.detailFont, relativeTo: .caption))
+                    .foregroundStyle(ink.fg(0.55))
+                    .lineLimit(2, reservesSpace: true)
+                    .animation(.smooth(duration: 0.2), value: focusID)
+                GamepadHintBar(hints: hints)
+            }
+            .padding(.leading, compact ? 12 : 18)
+            .padding(.trailing, 22)
+            .padding(
+                .bottom,
+                gamepadLegendBottomPadding(
+                    compact ? 12 : 18, tier: metrics.tier, displayBottom: displayBottomInset))
+            .padding(.top, compact ? 6 : 10)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background { GamepadTrayBlur(edge: .bottom) }
+        }
+        .background {
+            if !hostedInShell { GamepadFormBackground() }
+        }
+        .gamepadPaletteInk()
+        // Moving the focus off the armed Remove row disarms it: an arming that outlives the row it
+        // was made on is a trap, and the thumb that wandered away is exactly the hesitation the
+        // two-press rule exists to catch.
+        .onChange(of: focusID) { _, id in
+            if id != Action.remove.rawValue { armed = false }
+        }
+        #if !os(tvOS)
+        .background {
+            Button("Cancel") { performClose() }
+                .keyboardShortcut(.cancelAction)
+                .buttonStyle(.plain)
+                .frame(width: 0, height: 0)
+                .opacity(0)
+                .accessibilityHidden(true)
+        }
+        #endif
+    }
+
+    private var title: String {
+        pinnedProfile.map { "\(host.displayName) · \($0.name)" } ?? host.displayName
+    }
+
+    // MARK: - Rows
+
+    private struct Row: Identifiable {
+        let action: Action
+        let label: String
+        var icon: String
+        var isDestructive = false
+        var id: String { action.rawValue }
+    }
+
+    private var rows: [Row] {
+        // A pinned card is a shortcut, not a host: everything host-level is deliberately absent.
+        if pinnedProfile != nil {
+            return [
+                Row(action: .unpin, label: "Unpin card", icon: "pin.slash"),
+                Row(action: .copyLink, label: copied ? "Copied" : "Copy link", icon: "link"),
+                Row(action: .cancel, label: "Cancel", icon: "xmark"),
+            ]
+        }
+        var list: [Row] = []
+        // Waking a host that is already answering would just sit there counting seconds.
+        if canWake, !isOnline {
+            list.append(Row(action: .wake, label: "Wake host", icon: "power"))
+        }
+        list.append(Row(action: .copyLink, label: copied ? "Copied" : "Copy link", icon: "link"))
+        list.append(Row(action: .edit, label: "Edit\u{2026}", icon: "pencil"))
+        // Only a paired host has a pairing to drop.
+        if host.pinnedSHA256 != nil {
+            list.append(Row(
+                action: .forgetPairing, label: "Forget pairing", icon: "lock.open"))
+        }
+        list.append(Row(
+            action: .remove,
+            label: armed ? "Remove host \u{2014} press again" : "Remove host",
+            icon: "trash", isDestructive: true))
+        list.append(Row(action: .cancel, label: "Cancel", icon: "xmark"))
+        return list
+    }
+
+    /// The explainer under the list — the same band the settings screen uses, and the only place a
+    /// destructive action can say what it will actually do before it is pressed.
+    private var detail: String {
+        switch rows.first(where: { $0.id == focusID })?.action {
+        case .wake:
+            return "Send a Wake-on-LAN packet and wait for this host to answer."
+        case .copyLink:
+            return "Copy a punktfunk:// link to this host — paste it anywhere to connect."
+        case .edit:
+            return "Rename this host or change its address. Pairing and pinned cards are kept."
+        case .forgetPairing:
+            return "Drop the stored fingerprint. The host stays saved and the next connect "
+                + "pairs again."
+        case .remove:
+            return armed
+                ? "Press again to remove — this cannot be undone."
+                : "Delete this host, its pairing and its pinned cards from this device."
+        case .unpin:
+            return "Remove this profile's card. The profile itself and the host are untouched."
+        case .cancel, .none:
+            return ""
+        }
+    }
+
+    private var hints: [GamepadHint] {
+        [
+            .init(
+                glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Select",
+                action: { if let id = focusID, let row = rows.first(where: { $0.id == id }) {
+                    run(row.action)
+                } }),
+            .init(
+                glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Back",
+                action: { performClose() }),
+        ]
+    }
+
+    // MARK: - Actions
+
+    private func run(_ action: Action) {
+        switch action {
+        case .wake:
+            onWake()
+            performClose()
+        case .copyLink:
+            LinkClipboard.copy(
+                DeepLink.forHost(host, profile: pinnedProfile?.id).urlString)
+            // No toast machinery on this surface — the row says so itself, which is the same
+            // acknowledgement in the place the user is already looking.
+            withAnimation(.smooth(duration: 0.2)) { copied = true }
+        case .edit:
+            onEdit()
+        case .forgetPairing:
+            onForgetPairing()
+            performClose()
+        case .remove:
+            guard armed else {
+                withAnimation(.smooth(duration: 0.2)) { armed = true }
+                return
+            }
+            onRemove()
+            performClose()
+        case .unpin:
+            onUnpin()
+            performClose()
+        case .cancel:
+            performClose()
+        }
+    }
+
+    private func performClose() {
+        if let close { close() } else { dismiss() }
+    }
+
+    // MARK: - Row rendering
+
+    private func rowView(_ row: Row, focused: Bool) -> some View {
+        let m = metrics
+        // The destructive row wears the warning colour only once ARMED: red on a row that still
+        // needs a second press reads as "this already happened".
+        let danger = row.isDestructive && armed
+        return HStack(spacing: 14) {
+            Image(systemName: row.icon)
+                .font(.system(size: m.iconFont))
+                .foregroundStyle(
+                    danger ? GamepadInk.warningRed : (focused ? ink.accent : ink.fg(0.55)))
+                .frame(width: m.iconWidth)
+            Text(row.label)
+                .font(.geist(m.labelFont, .semibold, relativeTo: .body))
+                .foregroundStyle(danger ? GamepadInk.warningRed : ink.fg)
+                .lineLimit(1)
+            Spacer(minLength: 12)
+        }
+        .padding(.horizontal, m.rowHPad)
+        .padding(.vertical, m.rowVPad)
+        .consoleGlass(
+            RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous),
+            tint: focused ? (danger ? GamepadInk.warningRed.opacity(0.3) : ink.accent(0.30)) : nil,
+            interactive: focused)
+        .overlay {
+            RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous)
+                .strokeBorder(
+                    danger ? GamepadInk.warningRed.opacity(0.7) : ink.fg(focused ? 0.28 : 0.06),
+                    lineWidth: 1)
+        }
+        .scaleEffect(focused ? 1.0 : 0.98)
+        .animation(.smooth(duration: 0.18), value: focused)
+        .animation(.smooth(duration: 0.18), value: armed)
+    }
+}
+#endif

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

@@ -67,9 +67,32 @@ struct GamepadInk: Equatable, Sendable {
     /// The shipped dark look — what a preview or a test composition gets.
     static let dark = GamepadInk.of(GamepadPalette.named("violet"))
 
+    /// The ink for a stored `ui_palette` id, resolved WITHOUT the environment.
+    ///
+    /// For the screens that publish their own ink with `gamepadPaletteInk()`. A view's
+    /// `@Environment` resolves against its PARENT — the modifier a screen applies to its own body
+    /// covers its descendants, never the body's own `ink.…` references — so such a screen reads
+    /// whatever was published ABOVE it. Nested inside another gamepad screen (the iOS shell's
+    /// layers) that happens to be right; presented as a cover or a sheet (tvOS, macOS) there is
+    /// nothing above it and it gets the bare dark default. That is precisely how a pale palette
+    /// came out with a WHITE title, white row labels and a violet focus wash on an Apple TV, while
+    /// the child views in the same screen — the hint bar, the host tiles, the glass — were
+    /// correctly dark-on-pale.
+    ///
+    /// Declare it beside an `@AppStorage(DefaultsKey.uiPalette)`, which is what re-renders the
+    /// screen when the setting changes (`GamepadInkModifier` reads the same key).
+    static func stored(_ paletteID: String) -> GamepadInk {
+        .of(GamepadPalette.named(paletteID))
+    }
+
     /// The online pip — deliberately NOT palette-derived: a status colour must not change
     /// meaning with the wallpaper (the console's rule; this is its `ONLINE_GREEN` verbatim).
     static let onlineGreen = Color(red: 0.20, green: 0.84, blue: 0.29)
+    /// An armed destructive action (the host menu's Remove). Palette-independent for exactly the
+    /// same reason as the pip above, and the more strongly so: the one colour on this UI that
+    /// means "this does not come back" cannot be allowed to drift toward the wallpaper on a warm
+    /// palette, or read as a highlight on a red one.
+    static let warningRed = Color(red: 0.94, green: 0.28, blue: 0.26)
 }
 
 private struct GamepadInkKey: EnvironmentKey {

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

@@ -10,7 +10,10 @@ import SwiftUI
 #if os(iOS)
 
 struct GamepadLibraryScreen: View {
-    @Environment(\.gamepadInk) private var ink
+    /// Resolved from the stored palette, NOT from `\.gamepadInk` — this screen publishes that
+    /// value itself and so sits above its own copy (see `GamepadInk.stored`).
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+    private var ink: GamepadInk { .stored(paletteID) }
     @ObservedObject var store: HostStore
     let target: LibraryTarget
     let onLaunch: (String) -> Void

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

@@ -21,6 +21,8 @@ import SwiftUI
 enum GamepadScreen: Identifiable {
     case settings
     case addHost
+    case hostOptions(HostOptionsTarget)
+    case editHost(StoredHost)
     case pair(StoredHost)
     case library(LibraryTarget)
 
@@ -28,6 +30,10 @@ enum GamepadScreen: Identifiable {
         switch self {
         case .settings: return "settings"
         case .addHost: return "addHost"
+        // Keyed on the CARD (host + pinned profile), for the same reason the library is keyed on
+        // the shelf — see `HostOptionsTarget.id`.
+        case .hostOptions(let target): return "hostOptions-\(target.id)"
+        case .editHost(let host): return "editHost-\(host.id.uuidString)"
         case .pair(let host): return "pair-\(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.
@@ -39,7 +45,7 @@ enum GamepadScreen: Identifiable {
     /// (`Bg::Form` in the console); the library keeps the launcher's full aurora.
     var isForm: Bool {
         switch self {
-        case .settings, .addHost, .pair: return true
+        case .settings, .addHost, .hostOptions, .editHost, .pair: return true
         case .library: return false
         }
     }

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

@@ -19,7 +19,10 @@ import SwiftUI
 import GameController
 
 struct LibraryCoverflowView: View {
-    @Environment(\.gamepadInk) private var ink
+    /// Resolved from the stored palette, NOT from `\.gamepadInk` — this screen publishes that
+    /// value itself and so sits above its own copy (see `GamepadInk.stored`).
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+    private var ink: GamepadInk { .stored(paletteID) }
     let games: [GameEntry]
     let artLoader: LibraryArtLoader?
     var onLaunch: ((String) -> Void)?

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

@@ -94,6 +94,9 @@ struct LibraryView: View {
             gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled,
             mode: gamepadUIMode)
     }
+    /// True when the iOS shell already draws one persistent field behind its layers — mounting a
+    /// second would double the mesh (the same rule the coverflow and the settings screen follow).
+    @Environment(\.gamepadHostedInShell) private var hostedInShell
     #endif
 
     var body: some View {
@@ -150,12 +153,13 @@ struct LibraryView: View {
 
     @ViewBuilder private var content: some View {
         if loading && games.isEmpty {
-            ProgressView("Loading library…")
-                .frame(maxWidth: .infinity, maxHeight: .infinity)
+            consoleField(
+                ProgressView("Loading library…")
+                    .frame(maxWidth: .infinity, maxHeight: .infinity))
         } else if let errorText, games.isEmpty {
-            errorState(errorText)
+            consoleField(errorState(errorText))
         } else if games.isEmpty {
-            emptyState
+            consoleField(emptyState)
         } else {
             if gamepadUIActive {
                 LibraryCoverflowView(
@@ -168,6 +172,24 @@ struct LibraryView: View {
         }
     }
 
+    /// The console field behind the three states that are NOT the coverflow — loading, error,
+    /// empty. The coverflow mounts its own backdrop; these mounted nothing, so wherever this view
+    /// is a COVER over the launcher (tvOS, macOS) they drew straight onto it: the spinner and its
+    /// label sat on the launcher's own aurora with the host tiles still showing through. The same
+    /// field as the coverflow's (not the calmed form one), so nothing shifts under the content when
+    /// the titles land and the coverflow takes over.
+    ///
+    /// Only in gamepad mode: the plain grid's states belong on the system background, as before.
+    @ViewBuilder private func consoleField(_ view: some View) -> some View {
+        #if os(iOS) || os(macOS) || os(tvOS)
+        view.background {
+            if gamepadUIActive, !hostedInShell { GamepadScreenBackground() }
+        }
+        #else
+        view
+        #endif
+    }
+
     private var grid: some View {
         // Design D4: launcher entries get their own section above the titles, never interleaved.
         // Both headers appear only when both groups exist, so a library without launcher entries

clients/apple/Sources/PunktfunkClient/Screenshots/ScreenshotScenes.swift

@@ -244,7 +244,8 @@ private struct ShotGamepadHome: View {
             store: store, model: model, discovery: discovery,
             libraryTarget: .constant(nil), pairingTarget: .constant(nil),
             onPaired: { _, _ in }, waker: waker,
-            connect: { _, _ in }, connectDiscovered: { _ in }, launchTitle: { _, _ in })
+            connect: { _, _ in }, connectDiscovered: { _ in }, launchTitle: { _, _ in },
+            wakeOnly: { _ in })
     }
 }
 
@@ -303,7 +304,8 @@ private struct ShotConnect: View {
                 store: store, model: model, discovery: discovery,
                 libraryTarget: .constant(nil), pairingTarget: .constant(nil),
             onPaired: { _, _ in }, waker: waker,
-                connect: { _, _ in }, connectDiscovered: { _ in }, launchTitle: { _, _ in })
+                connect: { _, _ in }, connectDiscovered: { _ in }, launchTitle: { _, _ in },
+            wakeOnly: { _ in })
         } else {
             ShotHome()
         }

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

@@ -20,6 +20,18 @@ import SwiftUI
 /// instrument: any visible overlay forces the metal layer through the compositor, which costs a
 /// refresh period on the vsync-latched platforms — this is how to measure with it off.
 private let statsLog = Logger(subsystem: "io.unom.punktfunk", category: "stats")
+/// Mirror the 1 Hz vitals line to STDOUT as well as the unified log.
+///
+/// Exists for **tvOS, where the unified log is unreachable**: `log stream --device` is gone from
+/// modern macOS, `log collect --device-name` needs root and then fails "Device not configured"
+/// (an Apple TV has no USB to fall back to), and libimobiledevice pairs against a different
+/// database than Xcode. Stdout, however, IS bridged — `xcrun devicectl device process launch
+/// --console -e '{"PUNKTFUNK_STATS_STDOUT":"1"}' io.unom.punktfunk` streams these lines straight
+/// to the Mac. That is the only way to read a session's numbers with the **stats overlay OFF**,
+/// which matters because the overlay is itself a composited layer over the Metal one — i.e. a
+/// plausible cause of the very present-floor inflation the overlay is used to measure.
+/// Env-gated: no cost, and no stdout noise, unless someone is deliberately measuring.
+private let statsToStdout = ProcessInfo.processInfo.environment["PUNKTFUNK_STATS_STDOUT"] == "1"
 
 /// Pump-thread-side frame counters; a 1 Hz main-actor timer drains them into @Published
 /// values. NSLock instead of an actor — the writer is the (non-async) pump thread.
@@ -137,6 +149,25 @@ final class SessionModel: ObservableObject {
     /// and under stage-1.
     @Published var osFloorP50Ms = 0.0
     @Published var osFloorValid = false
+    /// The deadline link's `preferredFrameLatency` ASK beside its property READBACK (see
+    /// `PresentLinkInfo` — it exists because tvOS has no reachable log). ⚠ The readback is NOT
+    /// a grant: it is a plain float property, so it echoes whatever was stored unless the
+    /// system clamps the setter. readback ≠ ask ⇒ a visible clamp (the one signal the API can
+    /// give); readback == ask proves nothing — `osFloorP50Ms` (the measured vend lead) is the
+    /// truth-teller (field 2026-08-13: readback 1.00 beside a 32.5 ms floor).
+    @Published var linkLatencyAskFrames: Float = 0
+    @Published var linkLatencyFrames: Float = 0
+    @Published var linkRangeMinHz: Float = 0
+    @Published var linkRangeMaxHz: Float = 0
+    @Published var linkDrawables = 0
+    @Published var linkInfoValid = false
+    /// Impossible samples the HOST-ANCHORED meters (host+network, end-to-end) refused this
+    /// second (`LatencyMeter.drainTrimmed`). Nonzero means the clock offset is lying and every
+    /// host-anchored p50/p95 this window is a TRUNCATED distribution — the HUD marks the window
+    /// suspect instead of letting a trimmed tail pose as a healthy small number (the field
+    /// "e2e 0–3 ms" reading, 2026-08-13). Client-local stages can't go negative, so they carry
+    /// no such term.
+    @Published var skewTrimPerS = 0
     /// The AUDIO plane's latency, from the playback ring (`SessionAudio.Stats`): how much decoded
     /// audio is queued ahead of the speaker, and where that PUTS it relative to the picture
     /// (positive = audio behind). `audioValid` is false until playback runs.
@@ -683,6 +714,10 @@ final class SessionModel: ObservableObject {
         displayValid = false
         clientQueueValid = false
         osFloorValid = false
+        linkInfoValid = false
+        // Drop the previous session's grant too — the shared box outlives the session, and a new
+        // link may never come up (a non-deadline rung has none at all).
+        PresentLinkInfo.shared.clear()
         audioValid = false
         lostFrames = 0
         lostPct = 0
@@ -904,6 +939,10 @@ final class SessionModel: ObservableObject {
                 } else {
                     self.endToEndValid = false
                 }
+                // Drained even when the stats drains came back empty — with a badly wrong offset
+                // an entire window is refused and only this counter still tells the story.
+                self.skewTrimPerS =
+                    self.latency.drainTrimmed() + self.endToEnd.drainTrimmed()
                 if let d = self.decodeStage.drain() {
                     self.decodeP50Ms = d.p50Ms
                     self.decodeValid = true
@@ -923,6 +962,18 @@ final class SessionModel: ObservableObject {
                 } else {
                     self.osFloorValid = false
                 }
+                // The display link's latency ask + property readback (deadline rung only) — a
+                // LEVEL, not a window, so it is read rather than drained.
+                if let l = PresentLinkInfo.shared.snapshot() {
+                    self.linkLatencyAskFrames = l.ask
+                    self.linkLatencyFrames = l.latency
+                    self.linkRangeMinHz = l.rangeMin
+                    self.linkRangeMaxHz = l.rangeMax
+                    self.linkDrawables = l.drawables
+                    self.linkInfoValid = true
+                } else {
+                    self.linkInfoValid = false
+                }
                 if let q = self.clientQueue.drain() {
                     self.clientQueueP50Ms = q.p50Ms
                     self.clientQueueValid = true
@@ -951,6 +1002,14 @@ final class SessionModel: ObservableObject {
                         // Swift Int is 64-bit → %lld, NOT %d (which is a 32-bit C int); macOS 26's
                         // strict String(format:) validator rejects the %d/Int mismatch and drops
                         // the whole line (a cascade error that also mis-blames the float args).
+                        //
+                        // ⚠ Every invalid-field fallback below MUST be a typed `-1.0` (or a
+                        // `Double(...)`-wrapped value), never a bare `-1`: in this variadic
+                        // `CVarArg` context the ternary does NOT unify to Double — the untyped
+                        // literal goes in as Int, and `%f` then reads Int64(-1)'s all-ones bit
+                        // pattern, which IS a quiet NaN. Field 2026-08-13 (tvOS, stage-1, the
+                        // first session ever to have invalid fields while frames flowed): every
+                        // fallback printed `nan`. Latent since the line was added.
                         format: "fps=%lld presents=%lld e2e_p50=%.1f e2e_p95=%.1f hostnet_p50=%.1f "
                             + "decode_p50=%.1f display_p50=%.1f lost=%lld "
                             + "floor_p50=%.1f display_adj=%.1f e2e_adj=%.1f queue_p50=%.1f "
@@ -958,22 +1017,35 @@ final class SessionModel: ObservableObject {
                             // In the log as well as on the HUD because the overlay is only up when
                             // someone thought to turn it on, and the reports that need these
                             // numbers arrive after the fact.
-                            + "audio_buffer=%lld audio_av_offset=%lld",
+                            + "audio_buffer=%lld audio_av_offset=%lld "
+                            // The deadline link's latency ask + property readback (both -1 on
+                            // non-deadline rungs) — appended so the PUNKTFUNK_FRAME_LATENCY
+                            // ladder is readable over the stdout channel with the HUD off,
+                            // which is the only honest way to run it on a tvOS device.
+                            + "link_ask=%.2f link_readback=%.2f "
+                            // Impossible samples the host-anchored meters refused this window:
+                            // nonzero ⇒ the clock offset is lying and e2e/hostnet above are
+                            // truncated distributions — disregard their p50/p95.
+                            + "skew_trim=%lld",
                         frames,
                         displayWindow?.count ?? 0,
-                        self.endToEndValid ? self.endToEndP50Ms : -1,
-                        self.endToEndValid ? self.endToEndP95Ms : -1,
-                        self.hostNetworkValid ? self.hostNetworkP50Ms : -1,
-                        self.decodeValid ? self.decodeP50Ms : -1,
-                        self.displayValid ? self.displayP50Ms : -1,
+                        self.endToEndValid ? self.endToEndP50Ms : -1.0,
+                        self.endToEndValid ? self.endToEndP95Ms : -1.0,
+                        self.hostNetworkValid ? self.hostNetworkP50Ms : -1.0,
+                        self.decodeValid ? self.decodeP50Ms : -1.0,
+                        self.displayValid ? self.displayP50Ms : -1.0,
                         lost,
-                        self.osFloorValid ? self.osFloorP50Ms : -1,
-                        self.displayValid ? self.displayAdjP50Ms : -1,
-                        self.endToEndValid ? self.endToEndAdjP50Ms : -1,
-                        self.clientQueueValid ? self.clientQueueP50Ms : -1,
+                        self.osFloorValid ? self.osFloorP50Ms : -1.0,
+                        self.displayValid ? self.displayAdjP50Ms : -1.0,
+                        self.endToEndValid ? self.endToEndAdjP50Ms : -1.0,
+                        self.clientQueueValid ? self.clientQueueP50Ms : -1.0,
                         self.audioValid ? self.audioBufferMs : -1,
-                        self.audioValid ? self.audioAvOffsetMs : 0)
+                        self.audioValid ? self.audioAvOffsetMs : 0,
+                        self.linkInfoValid ? Double(self.linkLatencyAskFrames) : -1.0,
+                        self.linkInfoValid ? Double(self.linkLatencyFrames) : -1.0,
+                        self.skewTrimPerS)
                     statsLog.info("\(line, privacy: .public)")
+                    if statsToStdout { print("pf.stats \(line)") }
                 }
             }
         }

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

@@ -128,6 +128,29 @@ struct StreamHUDView: View {
                             .font(.system(.caption2, design: .monospaced))
                             .foregroundStyle(.tertiary)
                     }
+                    // The deadline link's frame-latency ASK beside its property READBACK. ⚠ The
+                    // readback is NOT a grant — the property echoes whatever we stored (field
+                    // 2026-08-13: 1.00 beside a 32.5 ms `os present` floor). The line earns its
+                    // place because a readback that DIFFERS from the ask is the one clamp signal
+                    // the API can give, and on tvOS the screen is the only place to read either
+                    // (no log is reachable on an Apple TV; see PresentLinkInfo).
+                    if model.linkInfoValid {
+                        Text("link latency ask \(model.linkLatencyAskFrames, specifier: "%.2f") readback \(model.linkLatencyFrames, specifier: "%.2f") · range \(model.linkRangeMinHz, specifier: "%.0f")-\(model.linkRangeMaxHz, specifier: "%.0f") Hz · drawables \(model.linkDrawables)")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.tertiary)
+                    }
+                    // The clock-offset tripwire: host-anchored meters refused samples as
+                    // impossible (≤ 0 after offset correction) this second. When this shows,
+                    // e2e and host+network above are TRUNCATED distributions — a wrong skew
+                    // offset shifted them and the impossible half was trimmed — so their
+                    // p50/p95 flatter the stream (the field "e2e 0–3 ms" reading). Orange on
+                    // purpose: every other stat here stays legible-quiet, but a number that
+                    // has stopped meaning anything must not.
+                    if model.skewTrimPerS > 0 {
+                        Text("clock offset suspect — \(model.skewTrimPerS)/s impossible samples trimmed; e2e & host+network unreliable")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.orange)
+                    }
                     // Client-queue wait (reassembly receipt → decode pull, ABI v9 split): ~0 on
                     // a healthy stream and hidden as noise; shown from 2 ms — a persistent value
                     // is a client-side standing backlog that pre-split builds displayed as

clients/apple/Sources/PunktfunkClient/Settings/AboutView.swift

@@ -28,6 +28,10 @@ struct AboutView: View {
 
     #if !os(tvOS)
     @State private var showAcknowledgements = false
+    /// The in-session controls. They used to announce themselves in a 6-second banner at the start
+    /// of every stream; that banner is gone, so this page is where they live now — including for
+    /// touch users on a Mac, who saw it too.
+    @State private var showShortcuts = false
     #endif
 
     var body: some View {
@@ -44,6 +48,9 @@ struct AboutView: View {
                     .listRowInsets(EdgeInsets())
                     .listRowBackground(Color.clear)
             }
+            Section {
+                shortcutsRow
+            }
             Section {
                 linkRow("Documentation", systemImage: "book", url: Destination.docs)
                 linkRow("Community", systemImage: "bubble.left.and.bubble.right",
@@ -63,6 +70,21 @@ struct AboutView: View {
         // A SHEET, not a push — on iPad the settings detail column is deliberately not a
         // NavigationStack (an inner one doubles the title bar), so a NavigationLink from here
         // pushed into a context with no back button and stranded the licenses on screen.
+        // A sheet for the same reason Acknowledgements is one — see that modifier's note on the
+        // iPad detail column not being a NavigationStack.
+        .sheet(isPresented: $showShortcuts) {
+            NavigationStack {
+                ShortcutsView(micAvailable: ShortcutsCatalog.micPlausible)
+                    .toolbar {
+                        ToolbarItem(placement: .confirmationAction) {
+                            Button("Done") { showShortcuts = false }
+                        }
+                    }
+            }
+            #if os(macOS)
+            .frame(width: 560, height: 460)
+            #endif
+        }
         .sheet(isPresented: $showAcknowledgements) {
             NavigationStack {
                 AcknowledgementsView()
@@ -135,6 +157,24 @@ struct AboutView: View {
         .foregroundStyle(.primary)
     }
 
+    private var shortcutsRow: some View {
+        Button {
+            showShortcuts = true
+        } label: {
+            HStack {
+                Label("Shortcuts", systemImage: "command")
+                Spacer(minLength: 8)
+                Image(systemName: "chevron.right")
+                    .font(.footnote.weight(.semibold))
+                    .foregroundStyle(.tertiary)
+                    .accessibilityHidden(true)
+            }
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(.plain)
+        .foregroundStyle(.primary)
+    }
+
     private var acknowledgementsRow: some View {
         Button {
             showAcknowledgements = true
@@ -168,6 +208,11 @@ struct AboutView: View {
                     tvAddress("Community", Destination.community)
                     tvAddress("Source code", Destination.source)
                 }
+                // Both push here: this page really is inside a navigation stack on tvOS, which is
+                // the case the sheets above exist to work around elsewhere.
+                NavigationLink("Shortcuts") {
+                    ShortcutsView(micAvailable: false) // tvOS has no app-accessible mic
+                }
                 NavigationLink("Acknowledgements") { AcknowledgementsView() }
                 Text("Punktfunk's source is open under MIT or Apache-2.0.")
                     .font(.geist(20, relativeTo: .caption))
@@ -219,21 +264,39 @@ struct AppIconView: View {
     var body: some View {
         Group {
             if let icon = Self.bundleIcon {
-                icon.image
-                    .resizable()
-                    .interpolation(.high)
-                    .aspectRatio(contentMode: .fit)
-                    // iOS ships the icon UNMASKED — the springboard applies the rounded shape at
-                    // draw time, so used raw it is a hard-cornered square. macOS bakes its own
-                    // shape (and margins) into the image, and clipping that would cut into it.
-                    .clipShape(RoundedRectangle(
-                        cornerRadius: icon.needsMask ? side * Self.iOSCornerRatio : 0,
-                        style: .continuous))
+                // The mask is applied ONLY where it is wanted. A `cornerRadius: 0` RoundedRectangle
+                // is not a no-op — it still clips to the layout frame, which crops any art whose
+                // aspect ratio isn't the frame's (the TV's 400x240 icon lost its ends to it).
+                // iOS ships the icon UNMASKED — the springboard applies the rounded shape at draw
+                // time, so used raw it is a hard-cornered square. macOS bakes its own shape (and
+                // margins) into the image, and clipping that would cut into it.
+                if icon.needsMask {
+                    icon.image
+                        .resizable()
+                        .interpolation(.high)
+                        .aspectRatio(contentMode: .fit)
+                        .clipShape(RoundedRectangle(
+                            cornerRadius: side * Self.iOSCornerRatio, style: .continuous))
+                } else {
+                    icon.image
+                        .resizable()
+                        .interpolation(.high)
+                        .aspectRatio(contentMode: .fit)
+                }
             } else {
                 monogram
             }
         }
+        // tvOS's icon is a 400×240 rectangle, not a squircle — framing it square would letterbox
+        // it inside a box two thirds empty. `side` means HEIGHT there, and the width follows the
+        // real 5:3 art. A MAX frame rather than a fixed one: with a fixed width the image cannot
+        // shrink when its row is tight, so it overflows and is clipped by whatever is above it
+        // instead — `.fit` inside a max frame gives back the whole icon, just smaller.
+        #if os(tvOS)
+        .frame(maxWidth: side * (400.0 / 240.0), maxHeight: side)
+        #else
         .frame(width: side, height: side)
+        #endif
         .accessibilityHidden(true) // the app's name is the next line
     }
 
@@ -267,7 +330,14 @@ struct AppIconView: View {
         else { return nil }
         return (Image(uiImage: image), true)
         #else
-        return nil // tvOS: layered icons have no single image to load
+        // tvOS ships the icon as a parallax image STACK (Back/Circle1/Circle2/Front), which has
+        // no single image to load — which is why this used to return nil and every About page on
+        // the TV drew the "P" monogram instead of the app's own mark. `AboutAppIcon` is those
+        // four layers flattened into one asset, generated from the SAME art the stack uses so it
+        // cannot drift into being a second, subtly different icon. Already masked and composited,
+        // so it needs no rounding of ours.
+        guard let image = UIImage(named: "AboutAppIcon") else { return nil }
+        return (Image(uiImage: image), false)
         #endif
     }
 }

clients/apple/Sources/PunktfunkClient/Settings/GamepadSettingsView.swift

@@ -42,14 +42,22 @@ enum GpSettingsTab: String, CaseIterable, Hashable {
     case controller = "Controller"
     case interface = "Interface"
     case profiles = "Profiles"
+    /// Trailing, like Profiles: both are built from something other than the settings store, and
+    /// About is where the strip ends because it is the one section that changes nothing.
+    case about = "About"
 }
 
 struct GamepadSettingsView: View {
-    @Environment(\.gamepadInk) private var ink
+    /// Resolved from `paletteID` below, NOT from `\.gamepadInk` — this screen publishes that value
+    /// itself and so sits above its own copy (see `GamepadInk.stored`). Reading the environment
+    /// here is what left the title, the tab pills and every row label white-on-pale on tvOS.
+    private var ink: GamepadInk { .stored(paletteID) }
     @Environment(\.gamepadMetrics) private var metrics
     @Environment(\.displayBottomInset) private var displayBottomInset
     @Environment(\.dismiss) private var dismiss
     @Environment(\.gamepadHostedInShell) private var hostedInShell
+    /// The About section's link rows (never used on tvOS, which has no browser).
+    @Environment(\.openURL) private var openURL
     /// The saved-host store — the pin picker writes `setPinned` through it and the profile rows
     /// count pins from its live hosts. Threaded in from GamepadHomeView like the home screen
     /// itself (ContentView owns the instance).
@@ -61,6 +69,9 @@ struct GamepadSettingsView: View {
     /// console's input drop) and while the connect takeover is up; a system presentation never
     /// needs the gate and keeps the default.
     var controllerActive = true
+    /// Whether this device has a microphone at all — passed through to the About page's shortcuts
+    /// reference, which must not list a mute key on a device that can't mute anything.
+    var micAvailable = true
     @AppStorage(DefaultsKey.streamWidth) private var width = 1920
     @AppStorage(DefaultsKey.streamHeight) private var height = 1080
     @AppStorage(DefaultsKey.streamHz) private var hz = 60
@@ -132,6 +143,14 @@ struct GamepadSettingsView: View {
     /// The direction of the last value step (+1 right/forward, -1 left) — picks which edge the
     /// changed value slides in from, so the animation follows the user's motion.
     @State private var lastAdjustDelta = 1
+    /// A reading surface opened from the About tab, replacing the row list the way the pin picker
+    /// does. Depth is 1: neither page opens anything further.
+    private enum AboutPage: Equatable {
+        case shortcuts
+        case licenses
+    }
+
+    @State private var aboutPage: AboutPage?
 
     var body: some View {
         GamepadMenuList(
@@ -157,9 +176,9 @@ struct GamepadSettingsView: View {
                     .foregroundStyle(ink.fg)
                     .frame(maxWidth: .infinity, alignment: .leading)
                     .padding(.horizontal, 24)
-                // The picker is one layer deeper — its rows aren't sections of anything, so the
-                // strip would be a control that does nothing while it's up.
-                if pinTarget == nil { tabStrip }
+                // The picker and the About reading pages are one layer deeper — their rows aren't
+                // sections of anything, so the strip would be a control that does nothing.
+                if pinTarget == nil, aboutPage == nil { tabStrip }
             }
             .padding(.top, gamepadTitleTopPadding(compact: compact))
             .padding(.bottom, gamepadTitleBottomPadding(compact: compact))
@@ -326,16 +345,62 @@ struct GamepadSettingsView: View {
         if let close { close() } else { dismiss() }
     }
 
+    /// Where the product actually lives — kept together so the three can be checked against the
+    /// README in one glance (the touch `AboutView` holds the same three).
+    private enum Destination {
+        static let docs = URL(string: "https://docs.punktfunk.unom.io")!
+        static let community = URL(string: "https://discord.gg/kaPNvzMuGU")!
+        static let source = URL(string: "https://git.unom.io/unom/punktfunk")!
+    }
+
+    /// "Version 0.29.0 (100000)" — the build number only when it says something the version does
+    /// not. Mirrors `AboutView.versionLine`; a bug report is worth more with it.
+    private static var versionLine: String {
+        let info = Bundle.main.infoDictionary
+        let short = info?["CFBundleShortVersionString"] as? String ?? "—"
+        let build = info?["CFBundleVersion"] as? String
+        guard let build, !build.isEmpty, build != short else { return "Version \(short)" }
+        return "Version \(short) (\(build))"
+    }
+
     /// "Settings", or "Pin “Work”" while the pin picker is up — the title is what says which
     /// layer the row list currently is.
     private var title: String {
-        pinTarget.map { "Pin “\($0.name)”" } ?? "Settings"
+        if let profile = pinTarget { return "Pin “\(profile.name)”" }
+        switch aboutPage {
+        case .shortcuts: return "Shortcuts"
+        case .licenses: return "Acknowledgements"
+        case nil: return "Settings"
+        }
     }
 
     /// The legend follows the layer: value-editing hints on the settings rows, pin/unpin on the
     /// picker — where B reads "Back" (it peels to the settings rows, GamepadAddHostView's "one
     /// layer" rule), and a hostless picker has nothing to pin, so only Back remains.
     private var hints: [GamepadHint] {
+        // A reading page is scrolled, not operated: offering A would be the same lie a dimmed row
+        // used to tell. Only Back remains.
+        if aboutPage != nil {
+            return [.init(
+                glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Back",
+                action: { back() })]
+        }
+        // The About rows open things rather than change them, so A reads "Open" and there is no
+        // Adjust cell — left/right genuinely does nothing there.
+        if pinTarget == nil, tab == .about {
+            let sections: [GamepadHint] = showsSectionHint
+                ? [.init(glyph: buttonGlyph(\.leftShoulder, fallback: "l1.rectangle.roundedbottom"),
+                         text: "Section", action: { step(tabBy: 1) })]
+                : []
+            return sections + [
+                .init(
+                    glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Open",
+                    action: { if let focusID { activate(id: focusID) } }),
+                .init(
+                    glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done",
+                    action: { back() }),
+            ]
+        }
         guard pinTarget != nil else {
             // The shoulders change section, so that cell leads — where it fits and where the
             // shoulders exist at all (see `showsSectionHint`).
@@ -383,6 +448,9 @@ struct GamepadSettingsView: View {
         if let profile = pinTarget {
             pinTarget = nil
             focusID = "profile-\(profile.id)"
+        } else if let page = aboutPage {
+            aboutPage = nil
+            focusID = page == .shortcuts ? "shortcuts" : "licenses"
         } else {
             performClose()
         }
@@ -390,7 +458,53 @@ struct GamepadSettingsView: View {
 
     // MARK: - Row rendering
 
+    @ViewBuilder
     private func rowView(_ row: Row, focused: Bool) -> some View {
+        switch row.kind {
+        case .control: controlRow(row, focused: focused)
+        case .footer:
+            Text(row.label)
+                .font(.geist(metrics.detailFont, .medium, relativeTo: .caption))
+                .monospacedDigit()
+                .foregroundStyle(ink.fg(focused ? 0.7 : 0.45))
+                .frame(maxWidth: .infinity, alignment: .center)
+                .padding(.top, 18)
+                .animation(.smooth(duration: 0.18), value: focused)
+        case .heading:
+            Text(row.label)
+                .font(.geist(metrics.labelFont, .bold, relativeTo: .headline))
+                .foregroundStyle(ink.fg(0.75))
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(.horizontal, metrics.rowHPad)
+                .padding(.top, 14)
+                .padding(.bottom, 2)
+        case .prose:
+            // Focus here means "this is the part you are scrolled to", not "press A" — so it is a
+            // quiet wash rather than the control rows' full glass.
+            VStack(alignment: .leading, spacing: 4) {
+                Text(row.label)
+                    .font(.geistFixed(metrics.valueFont, .medium))
+                    .foregroundStyle(ink.fg(0.95))
+                    .fixedSize(horizontal: false, vertical: true)
+                if !row.value.isEmpty {
+                    Text(row.value)
+                        .font(.geist(metrics.detailFont, relativeTo: .caption))
+                        .foregroundStyle(ink.fg(0.6))
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(.horizontal, metrics.rowHPad)
+            .padding(.vertical, metrics.rowVPad * 0.7)
+            .background {
+                RoundedRectangle(cornerRadius: metrics.rowCorner, style: .continuous)
+                    .fill(ink.fg(focused ? 0.08 : 0))
+            }
+            .animation(.smooth(duration: 0.18), value: focused)
+        }
+    }
+
+    private func controlRow(_ row: Row, focused: Bool) -> some View {
         let m = metrics
         // No section header: the tab strip names the section now, and repeating it above the
         // first row of every tab was just a second label saying the same word.
@@ -502,10 +616,23 @@ struct GamepadSettingsView: View {
         /// `activate(id:)`, not per closure, so no row builder can forget it.
         /// (Android's `GpRow.enabled` and `pf-console-ui`'s `RowSpec.enabled` are the twins.)
         var enabled = true
+        /// How this row DRAWS. Every tab but About is `.control` — the glass row with a label and
+        /// a value. About is a reading surface as much as a menu, so it also has a heading and a
+        /// block of prose, which are rows only so the focus list can scroll them (the same trick
+        /// `Licenses.chunked` plays for tvOS focus).
+        var kind: Kind = .control
         /// Left/right step; returns whether the value actually changed (false ⇒ boundary thud).
         let adjust: (Int) -> Bool
         /// A — cycle forward (wrapping) / flip.
         let activate: () -> Void
+
+        enum Kind {
+            case control
+            case heading
+            case prose
+            /// Quiet, centred trailing text — the About tab's version line.
+            case footer
+        }
     }
 
     /// Dispatch by id so the focus list's stored input callbacks always act on freshly built rows
@@ -527,9 +654,133 @@ struct GamepadSettingsView: View {
     /// controller wiring and the tvOS focus engine carry over as is).
     private var rows: [Row] {
         if let profile = pinTarget { return pinRows(for: profile) }
+        if let page = aboutPage {
+            switch page {
+            case .shortcuts: return shortcutRows
+            case .licenses: return licenseRows
+            }
+        }
+        if tab == .about { return aboutRows }
         return allRows.filter { $0.tab == tab }
     }
 
+    // MARK: - About
+
+    /// The About section: the ways out, plus the two reading surfaces. The identity itself (icon,
+    /// name, version, tagline) is the HEADER while this tab is up — see `aboutIdentity` — not a
+    /// row, so the list holds no focus stop that does nothing when pressed.
+    private var aboutRows: [Row] {
+        var list: [Row] = [
+            aboutAction(
+                id: "shortcuts", icon: "command", label: "Shortcuts", value: "While streaming",
+                detail: "What to press during a session on this device — and on a controller.",
+                open: .shortcuts),
+            aboutAction(
+                id: "licenses", icon: "text.document", label: "Acknowledgements",
+                value: "MIT or Apache-2.0",
+                detail: "Punktfunk's own licence and the third-party components it uses.",
+                open: .licenses),
+        ]
+        list.append(contentsOf: [
+            aboutLink(id: "docs", icon: "book", label: "Documentation", url: Destination.docs),
+            aboutLink(
+                id: "community", icon: "bubble.left.and.bubble.right", label: "Community",
+                url: Destination.community),
+            aboutLink(
+                id: "source", icon: "chevron.left.forwardslash.chevron.right",
+                label: "Source code", url: Destination.source),
+        ])
+        // The version sits UNDER the rows rather than in a header card above them. The card that
+        // used to head this tab carried the app icon, and on tvOS that icon is a 400x240
+        // rectangle that would not survive contact with a layout built for square art — three
+        // attempts at framing it were still cropping it on the real TV. A version string answers
+        // the only question anyone actually opens About to ask, and has no aspect ratio to get
+        // wrong. `.footer` draws it quiet and centred, so it reads as a footer and not a row you
+        // failed to press.
+        list.append(Row(
+            id: "version", tab: .about, icon: "", label: Self.versionLine, value: "",
+            detail: "", adjustable: false, enabled: true, kind: .footer,
+            adjust: { _ in false }, activate: {}))
+        return list
+    }
+
+    private func aboutAction(
+        id: String, icon: String, label: String, value: String, detail: String, open: AboutPage
+    ) -> Row {
+        Row(
+            id: id, tab: .about, icon: icon, label: label, value: value, detail: detail,
+            adjustable: false,
+            adjust: { _ in false },
+            activate: {
+                // Focus lands on the page's first row — the focus list's reconcile follows this
+                // id when the row set swaps underneath it (the pin picker's pattern).
+                focusID = open == .shortcuts ? shortcutRows.first?.id : licenseRows.first?.id
+                aboutPage = open
+            })
+    }
+
+    /// tvOS has no browser and no `openURL`, so an address there is text to read off the screen
+    /// rather than a link to nowhere — the same call the touch About page makes.
+    private func aboutLink(id: String, icon: String, label: String, url: URL) -> Row {
+        let shown = url.absoluteString.replacingOccurrences(of: "https://", with: "")
+        #if os(tvOS)
+        return Row(
+            id: id, tab: .about, icon: icon, label: label, value: shown,
+            detail: "Open this address on a phone or computer.",
+            adjustable: false, adjust: { _ in false }, activate: {})
+        #else
+        return Row(
+            id: id, tab: .about, icon: icon, label: label, value: shown,
+            detail: "Opens in your browser.",
+            adjustable: false, adjust: { _ in false }, activate: { openURL(url) })
+        #endif
+    }
+
+    /// The shortcuts reference — the same `ShortcutsCatalog` the touch About page renders, so the
+    /// two can never drift.
+    private var shortcutRows: [Row] {
+        ShortcutsCatalog.groups(micAvailable: micAvailable).flatMap { group -> [Row] in
+            [aboutText(id: "group-\(group.title)", label: group.title, kind: .heading)]
+                + group.items.map { item in
+                    aboutText(
+                        id: "sc-\(group.title)-\(item.keys)", label: item.keys, value: item.text,
+                        kind: .prose)
+                }
+        }
+    }
+
+    /// The licence wall, one row per pre-chunked page (`Licenses.chunked`, which exists so tvOS
+    /// can page it by focus steps) — so it scrolls with the stick and needs no machinery here.
+    private var licenseRows: [Row] {
+        var list: [Row] = [
+            aboutText(id: "lic-heading", label: "Punktfunk", kind: .heading),
+            aboutText(
+                id: "lic-summary",
+                label: "Punktfunk's source is open under MIT or Apache-2.0. It ships the Geist "
+                    + "typeface under the SIL Open Font License 1.1, and uses the third-party "
+                    + "components below, each under its own license.",
+                kind: .prose),
+        ]
+        for (i, chunk) in Licenses.chunked(Licenses.appLicense).enumerated() {
+            list.append(aboutText(id: "lic-app-\(i)", label: chunk, kind: .prose))
+        }
+        list.append(aboutText(
+            id: "lic-third-heading", label: "Third-party software", kind: .heading))
+        for (i, chunk) in Licenses.thirdPartyNoticesChunks.enumerated() {
+            list.append(aboutText(id: "lic-third-\(i)", label: chunk, kind: .prose))
+        }
+        return list
+    }
+
+    private func aboutText(
+        id: String, label: String, value: String = "", kind: Row.Kind
+    ) -> Row {
+        Row(
+            id: id, tab: .about, icon: "", label: label, value: value, detail: "",
+            adjustable: false, enabled: true, kind: kind,
+            adjust: { _ in false }, activate: {})
+    }
+
     /// Every row on the screen, tagged with its section. Built as one list (not per tab) so the
     /// platform-conditional insertions below can still place a row RELATIVE to another by id.
     private var allRows: [Row] {

clients/apple/Sources/PunktfunkClient/Settings/ShortcutsReference.swift

@@ -0,0 +1,181 @@
+// The in-session controls, written down once and read by every surface that shows them.
+//
+// This replaced the start-of-stream banner (ContentView's `showShortcutHint`): a 6-second pill
+// that told you the controls exactly once, while you were busy looking at the thing you had just
+// connected to, and then never again. A reference you can OPEN answers the question at the moment
+// it is actually asked — which is the second session, not the first.
+//
+// The catalog is data rather than a view so both About pages render the same words: the touch
+// `AboutView` (a Form) and the controller-first `GamepadAboutView` (a console list). The banner
+// was macOS/tvOS-only, so deleting it would have cost Mac TOUCH users the one place those keys
+// were written down — hence the touch surface gets this too, not just the gamepad UI.
+//
+// Per-platform by `#if`, because the honest answer really is different: tvOS has no keyboard and
+// no menu bar, iOS has a touch gesture nothing else has, and macOS is the only one that has to
+// explain mouse capture. A controller's chords are the one section common to all three — they are
+// the same buttons on every client (`GamepadCapture.escapeChord` / `.statsChord`), which is the
+// whole point of a cross-client chord.
+
+import AVFoundation
+import PunktfunkKit
+import SwiftUI
+
+/// One line of the reference: what you press, and what it does.
+struct ShortcutItem: Identifiable {
+    /// Stable within its group — the keys are unique per group by construction.
+    var id: String { keys }
+    /// The chord itself, rendered monospaced so ⌃⌥⇧-style runs stay legible.
+    let keys: String
+    let text: String
+}
+
+struct ShortcutGroup: Identifiable {
+    var id: String { title }
+    let title: String
+    let items: [ShortcutItem]
+}
+
+enum ShortcutsCatalog {
+    /// Whether a mute key is worth listing when no session is running, for the About page reached
+    /// from settings. `SessionModel.micAvailable` is the authority DURING a session — it also
+    /// consults the profile the session actually resolved — but a reference page opened between
+    /// sessions has no session to ask, so it answers the device-level half of the same question:
+    /// a platform with an app-accessible input, the mic setting on, and the OS not refusing.
+    /// `.notDetermined` counts, exactly as it does there: the prompt is simply still pending.
+    static var micPlausible: Bool {
+        #if os(tvOS)
+        return false // no app-accessible microphone
+        #else
+        guard UserDefaults.standard.object(forKey: DefaultsKey.micEnabled) as? Bool ?? true
+        else { return false }
+        switch AVCaptureDevice.authorizationStatus(for: .audio) {
+        case .authorized, .notDetermined: return true
+        default: return false
+        }
+        #endif
+    }
+
+    /// `micAvailable` gates the mute row — a device with no microphone would otherwise be told
+    /// about a key that does nothing, which is the failure the old banner already avoided.
+    static func groups(micAvailable: Bool) -> [ShortcutGroup] {
+        var groups: [ShortcutGroup] = []
+        #if os(macOS)
+        var keyboard: [ShortcutItem] = [
+            .init(keys: "Click", text: "Capture the mouse and keyboard for the stream"),
+            .init(keys: "⌃⌥⇧Q", text: "Release the mouse and keyboard back to this Mac"),
+            .init(keys: "⌃⌥⇧D", text: "Disconnect"),
+            .init(keys: "⌃⌥⇧S", text: "Cycle the statistics overlay"),
+        ]
+        if micAvailable {
+            keyboard.append(.init(keys: "⌃⌥⇧A", text: "Mute or unmute the microphone"))
+        }
+        groups.append(.init(title: "Keyboard", items: keyboard))
+        #elseif os(iOS)
+        // iPad with a hardware keyboard gets the same cross-client set as the Mac (StreamCommands
+        // publishes it either way); a phone simply never sees a keyboard to press it on.
+        var keyboard: [ShortcutItem] = [
+            .init(keys: "⌃⌥⇧Q", text: "Release the pointer back to this device"),
+            .init(keys: "⌃⌥⇧D", text: "Disconnect"),
+            .init(keys: "⌃⌥⇧S", text: "Cycle the statistics overlay"),
+        ]
+        if micAvailable {
+            keyboard.append(.init(keys: "⌃⌥⇧A", text: "Mute or unmute the microphone"))
+        }
+        groups.append(.init(title: "Hardware keyboard", items: keyboard))
+        groups.append(.init(title: "Touch", items: [
+            .init(keys: "Three-finger tap", text: "Cycle the statistics overlay"),
+        ]))
+        #elseif os(tvOS)
+        // The remote section leads on tvOS: it carries the ONLY exits. Menu/B is swallowed during
+        // a session (ContentView's `.onExitCommand {}`), so a user who does not know the hold
+        // gesture is genuinely stuck — which is why this was the one banner that could not simply
+        // be deleted without putting the words somewhere findable first.
+        groups.append(.init(title: "Siri Remote", items: [
+            .init(keys: "Hold Back", text: "Disconnect"),
+            .init(keys: "Touch surface", text: "Move the pointer"),
+            .init(keys: "Press", text: "Click"),
+            .init(keys: "Play/Pause", text: "Right-click"),
+            .init(keys: "Hold Play/Pause", text: "Cycle the statistics overlay"),
+        ]))
+        #endif
+        // Every client's controller speaks these two chords — see GamepadCapture.escapeChord and
+        // .statsChord, which a test pins against their GameController element lists.
+        groups.append(.init(title: "Controller", items: [
+            .init(keys: "L1 + R1 + Start + Select", text: "Hold to disconnect"),
+            .init(keys: "Select + X", text: "Cycle the statistics overlay"),
+            .init(keys: "Hold Select", text: "Press the host's guide button"),
+        ]))
+        return groups
+    }
+}
+
+/// The standard-interface reference — a sheet from `AboutView` on iOS/macOS, a pushed page on
+/// tvOS — so the keys the start-of-stream banner used to carry are still one press away.
+/// (The controller-first surface renders the same catalog itself; see `GamepadAboutView`.)
+struct ShortcutsView: View {
+    let micAvailable: Bool
+
+    var body: some View {
+        #if os(tvOS)
+        // No `Form`/`.formStyle(.grouped)` worth using at 10 feet, and the rows are read, not
+        // operated — a plain scrolling column at TV sizes says the same thing with less chrome.
+        ScrollView {
+            VStack(alignment: .leading, spacing: 30) {
+                ForEach(ShortcutsCatalog.groups(micAvailable: micAvailable)) { group in
+                    VStack(alignment: .leading, spacing: 12) {
+                        Text(group.title)
+                            .font(.geist(28, .semibold, relativeTo: .headline))
+                        ForEach(group.items) { item in
+                            HStack(alignment: .firstTextBaseline, spacing: 20) {
+                                Text(item.keys)
+                                    .font(.geistFixed(22, .medium))
+                                    .frame(minWidth: 300, alignment: .leading)
+                                    .fixedSize(horizontal: false, vertical: true)
+                                Text(item.text)
+                                    .font(.geist(22, relativeTo: .caption))
+                                    .foregroundStyle(.secondary)
+                                    .fixedSize(horizontal: false, vertical: true)
+                            }
+                        }
+                    }
+                }
+            }
+            .frame(maxWidth: 1000, alignment: .leading)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(60)
+        }
+        .navigationTitle("Shortcuts")
+        #else
+        form
+        #endif
+    }
+
+    #if !os(tvOS)
+    private var form: some View {
+        Form {
+            ForEach(ShortcutsCatalog.groups(micAvailable: micAvailable)) { group in
+                Section(group.title) {
+                    ForEach(group.items) { item in
+                        HStack(alignment: .firstTextBaseline, spacing: 12) {
+                            Text(item.keys)
+                                .font(.geistFixed(13, .medium))
+                                .foregroundStyle(.primary)
+                                // A fixed column keeps the descriptions aligned; the chords vary
+                                // from "Click" to "L1 + R1 + Start + Select".
+                                .frame(minWidth: 132, alignment: .leading)
+                                .fixedSize(horizontal: false, vertical: true)
+                            Text(item.text)
+                                .font(.geist(13, relativeTo: .footnote))
+                                .foregroundStyle(.secondary)
+                                .fixedSize(horizontal: false, vertical: true)
+                        }
+                        .padding(.vertical, 2)
+                    }
+                }
+            }
+        }
+        .formStyle(.grouped)
+        .navigationTitle("Shortcuts")
+    }
+    #endif
+}

clients/apple/Sources/PunktfunkClient/Trust/GamepadPairView.swift

@@ -18,7 +18,10 @@ import SwiftUI
 #if os(iOS) || os(macOS)
 
 struct GamepadPairView: View {
-    @Environment(\.gamepadInk) private var ink
+    /// Resolved from the stored palette, NOT from `\.gamepadInk` — this screen publishes that
+    /// value itself and so sits above its own copy (see `GamepadInk.stored`).
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+    private var ink: GamepadInk { .stored(paletteID) }
     @Environment(\.gamepadMetrics) private var metrics
     @Environment(\.displayBottomInset) private var displayBottomInset
     @Environment(\.dismiss) private var dismiss

clients/apple/Sources/PunktfunkKit/Audio/AudioDeviceWatcher.swift

@@ -32,8 +32,11 @@ final class AudioDeviceWatcher {
     /// posts one last change as it is torn down, and other AVAudioEngines in the process are not
     /// ours to restart.
     private let isOurs: (AnyObject?) -> Bool
-    /// Delivered on the main queue.
-    private let onChange: (Reason) -> Void
+    /// Delivered on the main queue. The second argument is the engine that posted the change
+    /// (`.engineConfiguration` only; nil for the HAL listener) — the owner needs the OBJECT, not
+    /// just the reason, because an engine that is RUNNING when the notification lands is one the
+    /// owner already restarted: acting on that echo is how a rebuild loop starts.
+    private let onChange: (Reason, AnyObject?) -> Void
 
     private let lock = NSLock()
     private var configObserver: NSObjectProtocol?
@@ -41,7 +44,7 @@ final class AudioDeviceWatcher {
     private var defaultOutputListener: AudioObjectPropertyListenerBlock?
     #endif
 
-    init(isOurs: @escaping (AnyObject?) -> Bool, onChange: @escaping (Reason) -> Void) {
+    init(isOurs: @escaping (AnyObject?) -> Bool, onChange: @escaping (Reason, AnyObject?) -> Void) {
         self.isOurs = isOurs
         self.onChange = onChange
     }
@@ -63,7 +66,7 @@ final class AudioDeviceWatcher {
             let posted = note.object as AnyObject?
             DispatchQueue.main.async {
                 guard let self, self.isOurs(posted) else { return }
-                self.onChange(.engineConfiguration)
+                self.onChange(.engineConfiguration, posted)
             }
         }
         lock.lock()
@@ -77,7 +80,8 @@ final class AudioDeviceWatcher {
         // (the voice-processing engine, which is the DEFAULT macOS configuration and which no Mac
         // here can even initialize). The HAL is told either way.
         let block: AudioObjectPropertyListenerBlock = { [weak self] _, _ in
-            self?.onChange(.defaultOutputDevice) // on the main queue — registered against it below
+            // On the main queue — registered against it below. No engine posted this, so nil.
+            self?.onChange(.defaultOutputDevice, nil)
         }
         var address = Self.defaultOutputAddress()
         let status = AudioObjectAddPropertyListenerBlock(

clients/apple/Sources/PunktfunkKit/Audio/AudioDevices.swift

@@ -42,7 +42,10 @@ public enum AudioDevices {
         return channelCount(id, scope: kAudioObjectPropertyScopeInput)
     }
 
-    private static func defaultInputDevice() -> AudioDeviceID? {
+    /// The device the system is currently capturing from — the key `SessionAudio`'s
+    /// voice-processing gate latches a start failure against (the failure is a property of the
+    /// input device, so a new device earns a fresh attempt).
+    static func defaultInputDevice() -> AudioDeviceID? {
         systemDevice(kAudioHardwarePropertyDefaultInputDevice)
     }
 

clients/apple/Sources/PunktfunkKit/Audio/AudioRebuildPolicy.swift

@@ -0,0 +1,89 @@
+// The two policy decisions of the device-change recovery, extracted where a unit test can reach
+// them. Both exist because of one field incident (2026-08-14, Mac Studio): the voice-processing
+// engine could not start on a 6-channel input device, every rebuild re-tried it, and the failed
+// attempt's HAL churn (VPIO builds and tears down an aggregate device) re-stopped the fallback
+// engines — which posted the configuration change that scheduled the next rebuild. A ~2.5 s
+// metronome of audio gaps, forever, with each rebuild also stalling the main thread (where macOS
+// input capture lives), so the stream's INPUT cut out on the same beat. The session-side wiring
+// lives in `SessionAudio`; the decisions live here because the loop shipped precisely because
+// they could not be tested without a mic and a session.
+
+#if os(macOS)
+import CoreAudio
+#endif
+import Foundation
+
+#if os(macOS)
+/// Should a rebuild try the combined (voice-processing) topology again?
+///
+/// A VPIO start failure is a property of the INPUT DEVICE (its channel count and format), not of
+/// the moment: retrying it on the same device fails the same way, and the attempt is not free —
+/// engaging and abandoning the voice processor churns the HAL hard enough to stop the healthy
+/// fallback engines. So a failure latches until the default input actually changes; a new device
+/// earns exactly one fresh attempt (it may well support VPIO), and its own failure latches again.
+struct CombinedTopologyGate {
+    private var failed = false
+    /// The default input device the failure was observed on — nil is a real value here ("failed
+    /// with no resolvable input device"), which is why `failed` is tracked separately.
+    private var failedInput: AudioDeviceID?
+
+    /// The combined topology failed with `input` as the default input device.
+    mutating func noteFailure(input: AudioDeviceID?) {
+        failed = true
+        failedInput = input
+    }
+
+    /// True when the combined topology is worth attempting with `input` as the default input
+    /// device. A device change clears the latch — the answer is about the CURRENT hardware, and
+    /// coming back to a device that failed before earns a fresh attempt too (the failure may have
+    /// been the mid-transition kind, and one attempt per device change cannot loop).
+    mutating func shouldTry(input: AudioDeviceID?) -> Bool {
+        guard failed else { return true }
+        guard input == failedInput else {
+            failed = false
+            failedInput = nil
+            return true
+        }
+        return false
+    }
+}
+#endif
+
+/// The delay before the next engine rebuild — the base debounce/floor behaviour, plus an
+/// escalating floor when rebuilds CHAIN (each one retriggered by its predecessor's own fallout).
+///
+/// One device switch produces one rebuild: its trigger burst is coalesced upstream, so the next
+/// trigger normally arrives minutes later and gets the base floor. A trigger that arrives hard on
+/// the heels of the last rebuild, again and again, is a rebuild answering itself — and since the
+/// recovery cannot always identify its own echo, the backstop is to keep answering but at a
+/// doubling floor, so an unforeseen feedback shape costs one audio blip per half-minute instead
+/// of a metronome. A quiet stretch resets the ladder to full responsiveness.
+struct RebuildBackoff {
+    /// Let the burst of triggers from one switch land before rebuilding.
+    static let debounce: TimeInterval = 0.15
+    /// Floor between two rebuilds.
+    static let floor: TimeInterval = 0.5
+    /// The escalated floor's cap: looping recoveries settle at one attempt per this interval.
+    static let floorCap: TimeInterval = 30
+    /// A trigger this long after the last rebuild is unrelated to it — the chain resets.
+    static let chainWindow: TimeInterval = 10
+
+    /// Consecutive rebuilds whose trigger arrived within `chainWindow` of the previous rebuild.
+    private(set) var chain = 0
+    private var lastRebuildAt: TimeInterval = -.infinity
+
+    /// The delay to schedule the next rebuild with, for a trigger arriving at `now`
+    /// (`systemUptime`). Mutates the chain accounting: call once per SCHEDULED rebuild, not per
+    /// coalesced trigger.
+    mutating func delay(now: TimeInterval) -> TimeInterval {
+        let since = now - lastRebuildAt
+        chain = since < Self.chainWindow ? chain + 1 : 0
+        let floor = min(Self.floor * pow(2, Double(min(chain, 6))), Self.floorCap)
+        return max(Self.debounce, floor - since)
+    }
+
+    /// The rebuild actually ran at `now` — the reference the next trigger's `delay` measures from.
+    mutating func noteRebuild(at now: TimeInterval) {
+        lastRebuildAt = now
+    }
+}

clients/apple/Sources/PunktfunkKit/Audio/AudioRing.swift

@@ -39,7 +39,18 @@ final class AudioRing: @unchecked Sendable {
     private static let maxTargetMS = 70
     private static let headroomMS = 30
     private static let hardCapMS = 90
-    private static let deprimeAfter = 4
+    /// How long the ring may run short before it goes back to priming, in MILLISECONDS of
+    /// starvation — not a count of callbacks. As a count (it was 4) the hysteresis meant a
+    /// different span of time on every device, because a callback is not a unit of time: 4 of them
+    /// is ~44 ms on a Mac's ~11 ms quantum and **20 ms on iOS**, whose session asks for a short IO
+    /// buffer. A Wi-Fi delivery stall therefore de-primed this ring on every bunching cycle where
+    /// the same policy rode it out elsewhere — measured on the shared Rust policy at 120 audible
+    /// gaps per 10 minutes at a 5 ms quantum, against 3 at 8 ms and 1 at 16 ms on an identical
+    /// link. Mirrors `JitterTuning::COREAUDIO.deprime_ms`.
+    private static let deprimeMS = 60
+    /// Floor in callbacks under `deprimeMS`, so a large-quantum device keeps real hysteresis
+    /// instead of de-priming on the first short read. Mirrors `MIN_DEPRIME_CALLBACKS`.
+    private static let minDeprimeCallbacks = 2
     /// The protocol's frame: the shed unit, and the slack added over a large device quantum.
     private static let frameMS = 5
     /// Depth average must exceed target by this before drift correction fires — the middle of the
@@ -93,7 +104,12 @@ final class AudioRing: @unchecked Sendable {
     private var writeIdx = 0
     private var primed = false
     private var renderQuantum = 0
+    /// Consecutive short reads, and the audio they starved for in interleaved samples. BOTH gate
+    /// the de-prime (see `deprimeMS`): the run must be at least that long AND at least
+    /// `minDeprimeCallbacks` callbacks, so the fuse is the same span of time whatever the device's
+    /// quantum without collapsing to a hair trigger on a large-quantum device.
     private var emptyReads = 0
+    private var emptyRun = 0
     private var depthAvg: Double = 0
     private var overRun = 0
     /// The live target in interleaved samples — `targetMS` grown by underrun pressure
@@ -240,8 +256,10 @@ final class AudioRing: @unchecked Sendable {
             min(target + Self.headroomMS * perMS, Self.hardCapMS * perMS),
             target + renderQuantum)
         if writeIdx - readIdx > cap {
-            readIdx = writeIdx - cap
-            depthAvg = Double(cap)
+            // Crossfaded, like the smooth shed — see `dropFront`. This is the correction a
+            // bunching link actually pays, so it is the one that most needs not to click.
+            dropFront(writeIdx - readIdx - cap)
+            depthAvg = Double(writeIdx - readIdx)
             overRun = 0
         }
     }
@@ -262,6 +280,7 @@ final class AudioRing: @unchecked Sendable {
             if available >= target {
                 primed = true
                 emptyReads = 0
+                emptyRun = 0
                 // The refill just banked this much: seed the average with it rather than letting
                 // it climb from wherever the drought left it — a freshly-primed ring would
                 // otherwise read as hollow for the EWMA's whole settling time, and the FIRST
@@ -348,15 +367,23 @@ final class AudioRing: @unchecked Sendable {
         if ranShort {
             quietRun = 0
             emptyReads += 1
+            emptyRun += count
             underrunCount += 1
-            if emptyReads >= Self.deprimeAfter || hollow {
-                // The consecutive-empties hysteresis protects a FULL ring from one late packet.
+            // Starved for `deprimeMS` of audio, over at least `minDeprimeCallbacks` callbacks.
+            // Both, because either alone is wrong at one end of the quantum range: time alone is a
+            // hair trigger on a device whose single quantum already exceeds the window, and a
+            // callback count alone is the device-dependent fuse this replaced.
+            let starved = emptyRun >= Self.deprimeMS * perMS
+                && emptyReads >= Self.minDeprimeCallbacks
+            if starved || hollow {
+                // The starvation hysteresis protects a FULL ring from one late packet.
                 // A hollow ring is the opposite case: the target has been raised but the depth
                 // never re-banked (growth is a promise; only a re-prime cashes it), and riding
                 // that out is a click per bunching period, forever. The click just heard has
                 // already paid for the refill — take it now.
                 primed = false
                 emptyReads = 0
+                emptyRun = 0
             }
             if !restored {
                 underrunsInWindow += 1
@@ -375,12 +402,14 @@ final class AudioRing: @unchecked Sendable {
             // the path above takes over. A near-miss is pressure, not quiet.
             quietRun = 0
             emptyReads = 0
+            emptyRun = 0
             if !nearMissGrown, !restored {
                 nearMissGrown = true
                 targetLive = min(targetLive + Self.growStepMS * perMS, Self.maxTargetMS * perMS)
             }
         } else {
             emptyReads = 0
+            emptyRun = 0
             quietRun += count
             // Without a sync request, time is the only evidence that hard-won slack is no longer
             // needed, so a grown target waits out the long window. A request for less IS evidence,
@@ -402,13 +431,21 @@ final class AudioRing: @unchecked Sendable {
         }
     }
 
-    /// Drop one protocol frame from the front, linearly crossfading the seam so the correction is
-    /// inaudible rather than a click. Mirrors `punktfunk_core::audio::crossfade_drop`; caller holds
-    /// the lock.
-    private func shedOneFrame() {
-        let drop = Self.frameMS * perMS
+    /// Drop one protocol frame from the front — the smooth drift correction.
+    private func shedOneFrame() { dropFront(Self.frameMS * perMS) }
+
+    /// Drop `drop` interleaved samples from the front, linearly crossfading the seam so the
+    /// correction is inaudible rather than a click. Mirrors `punktfunk_core::audio::crossfade_drop`;
+    /// caller holds the lock.
+    ///
+    /// Used by BOTH corrections. The hard-cap trim in `write` used to splice raw, on the reasoning
+    /// that a ring which blew its ceiling is already a discontinuity — but that describes the
+    /// ARRIVALS, not the samples either side of the seam, which are ordinary continuous audio. It
+    /// is also the drop that actually fires here: a bunching Wi-Fi link trims far more often than
+    /// drift sheds, so the one path left unfaded was the audible one.
+    private func dropFront(_ drop: Int) {
         let available = writeIdx - readIdx
-        guard available > drop else { return }
+        guard drop > 0, available > drop else { return }
         let fade = min(Self.crossfadeMS * perMS, min(drop, available - drop))
         let capacity = buf.count
         if fade > 0 {

clients/apple/Sources/PunktfunkKit/Audio/SessionAudio.swift

@@ -63,15 +63,24 @@ public final class SessionAudio {
     private var micMuted = false
     /// The playback jitter ring — created by whichever engine starts playback first and KEPT
     /// across an engine rebuild (the permission-grant upgrade in `startEngines` swaps engines,
-    /// not the ring, so the drain thread never has to be re-pointed). Main-thread confined,
-    /// like every start path.
+    /// not the ring, so the drain thread never has to be re-pointed). Guarded by `stateLock`:
+    /// the start paths run on `engineQueue`, while `stats` reads from the main thread.
     private var ring: AudioRing?
+    /// Every engine build, start, stop and rebuild runs here, serially — and NOT on the main
+    /// thread. macOS captures and sends input from the main thread, so the seconds a
+    /// voice-processing start can take (~1.9 s measured in the 2026-08-14 field loop) would
+    /// freeze the stream's input for exactly that long — the recovery must never make the main
+    /// thread wait on the audio server. The main queue keeps only the trigger bookkeeping
+    /// (debounce, backoff, retry ladder), which is cheap by construction.
+    private let engineQueue = DispatchQueue(
+        label: "io.unom.punktfunk.audio.engines", qos: .userInitiated)
     /// The video plane's end-to-end meter (capture→on-glass), if the owner wired one — the
     /// reference the A/V sync loop steers the ring against. `nil` leaves the loop inert and the
     /// ring exactly as it was before sync existed, which is also what the stage-1 fallback
     /// presenter gets: it decodes and presents inside the layer with no per-frame stamp, so it can
-    /// offer no reference, and a loop with no reference must not invent one. Main-thread confined,
-    /// like `ring`; the meter itself is internally locked and read from the drain thread.
+    /// offer no reference, and a loop with no reference must not invent one. Written ONCE in
+    /// `start()` before anything is dispatched (the queue hop orders it for `startDrain`); the
+    /// meter itself is internally locked and read from the drain thread.
     private var videoLatency: LatencyMeter?
     #if !os(macOS)
     /// AVAudioSession `setCategory`/`setActive` are synchronous and block on the audio server, so
@@ -99,7 +108,8 @@ public final class SessionAudio {
     // MARK: - Device changes (see `installDeviceChangeRecovery`)
 
     /// What `start()` was asked for, so a rebuild can put back the SAME topology the session was
-    /// started with. Main-thread confined, like the start paths that read it.
+    /// started with. Guarded by `stateLock` (written on the caller's thread, read when a rebuild
+    /// fires on the main queue).
     private var startConfig: StartConfig?
     private struct StartConfig {
         let speakerUID: String
@@ -110,20 +120,23 @@ public final class SessionAudio {
     }
     /// Watches the hardware for us (see `AudioDeviceWatcher`). Guarded by `stateLock`.
     private var deviceWatcher: AudioDeviceWatcher?
-    /// Whether the engines have been built at least once. Distinguishes "not started yet" (iOS
-    /// starts asynchronously) from "started and dead", which is what the recovery may act on.
-    /// Main-thread confined.
+    /// Whether the engines have been built at least once. Distinguishes "not started yet" (every
+    /// platform starts asynchronously now) from "started and dead", which is what the recovery
+    /// may act on. Guarded by `stateLock` (set on `engineQueue`, read on the main queue).
     private var enginesAttempted = false
     /// A rebuild is already on the main queue — one device switch produces a burst of triggers
     /// and they must collapse into one restart. Main-thread confined.
     private var rebuildQueued = false
-    /// `systemUptime` of the last rebuild, so a device that renegotiates in a loop cannot spin
-    /// the session. Main-thread confined.
-    private var lastRebuildAt: TimeInterval = 0
-    /// Let the burst of triggers from one switch land before rebuilding.
-    private static let rebuildDebounce: TimeInterval = 0.15
-    /// Floor between two rebuilds.
-    private static let rebuildFloor: TimeInterval = 0.5
+    /// Debounce/floor for the next rebuild, with an escalating floor when rebuilds chain (each
+    /// retriggered by its predecessor — see `RebuildBackoff`). Main-thread confined.
+    private var rebuildBackoff = RebuildBackoff()
+    #if os(macOS)
+    /// Latches a voice-processing start failure per input device, so a rebuild never re-attempts
+    /// a topology that deterministically fails — the retry is what turned one failure into a
+    /// rebuild loop (see `CombinedTopologyGate` and the note on `installDeviceChangeRecovery`).
+    /// `engineQueue`-confined, like the start paths that consult and feed it.
+    private var combinedGate = CombinedTopologyGate()
+    #endif
     /// Retries when a rebuild's `start()` loses the race with a device that is still going away
     /// (0.3 s, 0.6 s, 1.2 s). A failed rebuild leaves no engine to post the next notification,
     /// so this ladder — and, on macOS, the HAL listener — is all that stands between a mistimed
@@ -151,11 +164,12 @@ public final class SessionAudio {
     }
 
     /// Start playback (and, if enabled+authorized, the mic uplink). Empty UIDs = system default
-    /// device; on iOS the UIDs are ignored entirely (routes are AVAudioSession-managed). On macOS
-    /// the engines start synchronously on the caller's (main) thread. On iOS/tvOS start() is
-    /// ASYNCHRONOUS: it activates the AVAudioSession off the main thread, then starts the engines on
-    /// a later main-queue hop (gated by `!flag.isStopped`) — so playback is live shortly after, not
-    /// on return. The mic may start later still if the permission prompt is pending.
+    /// device; on iOS the UIDs are ignored entirely (routes are AVAudioSession-managed).
+    /// ASYNCHRONOUS on every platform: the engines start on `engineQueue` (iOS/tvOS activate the
+    /// AVAudioSession off the main thread first), gated by `!flag.isStopped` — so playback is
+    /// live shortly after, not on return. An engine start can block on the audio server for
+    /// seconds, and the caller's (main) thread is where macOS input capture lives — it must
+    /// never wait. The mic may start later still if the permission prompt is pending.
     /// `echoCancel` picks the engine topology — see the header note and `wantsCombined`.
     ///
     /// `videoLatency` is the session's END-TO-END latency meter (capture→on-glass). Pass it to arm
@@ -166,26 +180,33 @@ public final class SessionAudio {
         speakerUID: String, micUID: String, micChannel: Int, micEnabled: Bool, echoCancel: Bool,
         videoLatency: LatencyMeter? = nil
     ) {
-        self.videoLatency = videoLatency
+        self.videoLatency = videoLatency // before any dispatch below — startDrain reads it
         // Before any engine exists: the recovery watches the hardware, not the engines, and the
         // config it rebuilds from has to be recorded whether or not this start succeeds.
+        stateLock.lock()
         startConfig = StartConfig(
             speakerUID: speakerUID, micUID: micUID, micChannel: micChannel,
             micEnabled: micEnabled, echoCancel: echoCancel)
+        stateLock.unlock()
         installDeviceChangeRecovery(micEnabled: micEnabled)
         #if os(macOS)
-        // No AVAudioSession on macOS — start the engines directly (caller's thread, as before).
-        startEngines(
-            speakerUID: speakerUID, micUID: micUID, micChannel: micChannel,
-            micEnabled: micEnabled, echoCancel: echoCancel)
+        // No AVAudioSession on macOS — but the engines start on `engineQueue`, never the
+        // caller's (main) thread: a voice-processing start can block on the audio server for
+        // seconds, and the main thread is where input capture lives.
+        engineQueue.async { [weak self] in
+            guard let self, !self.flag.isStopped else { return }
+            self.startEngines(
+                speakerUID: speakerUID, micUID: micUID, micChannel: micChannel,
+                micEnabled: micEnabled, echoCancel: echoCancel)
+        }
         #else
         // Configure + activate the session OFF the main thread (it blocks on the audio server),
-        // then start the engines back on the main thread once it's active — engine routing/format
+        // then start the engines on `engineQueue` once it's active — engine routing/format
         // depend on the active session. A stop() racing in between is caught by the flag guard.
         Self.sessionQueue.async { [weak self] in
             guard let self else { return }
             self.activateAudioSession(micEnabled: micEnabled)
-            DispatchQueue.main.async { [weak self] in
+            self.engineQueue.async { [weak self] in
                 guard let self, !self.flag.isStopped else { return }
                 self.startEngines(
                     speakerUID: speakerUID, micUID: micUID, micChannel: micChannel,
@@ -234,11 +255,23 @@ public final class SessionAudio {
                 try session.setCategory(
                     .playAndRecord, mode: .default,
                     options: [.allowBluetoothA2DP, .mixWithOthers])
-                // Uplink latency: ask for 5 ms IO quanta at the wire rate (the default ~10-23 ms
+                // Uplink latency: ask for 10 ms IO quanta at the wire rate (the default ~23 ms
                 // quantum is most of the mic path's burst latency). Best-effort — the hardware
                 // has the final word (a Bluetooth route will ignore both), and whatever quantum
                 // is actually granted, the capture tap handles the buffers it gets.
-                try? session.setPreferredIOBufferDuration(0.005)
+                //
+                // 10 ms, NOT the 5 ms this used to ask for. The IO buffer duration is a property
+                // of the whole IO unit, so a shorter quantum is not free to the PLAYBACK side —
+                // and it bought the uplink nothing, because the encoder frames at 10 ms
+                // (`installMicTap` installs with `bufferSize: 480` and `OpusEncoder` consumes
+                // whole `framesPerPacket` chunks): at a 5 ms quantum the tap simply fired twice
+                // per packet, for the same packet latency. What it did buy was a halved deadline
+                // for the render callback and — because the de-prime fuse used to be a callback
+                // COUNT — half the starvation hysteresis in the jitter ring, on the one platform
+                // whose transport bunches hardest. Both ends of that are fixed now (`AudioRing`
+                // measures the fuse in ms), but there is still no reason to ask for a quantum
+                // finer than the packets we send.
+                try? session.setPreferredIOBufferDuration(0.010)
                 try? session.setPreferredSampleRate(48_000)
             } else {
                 try session.setCategory(.playback, mode: .default, options: [.mixWithOthers])
@@ -247,6 +280,16 @@ public final class SessionAudio {
             try session.setCategory(.playback, mode: .default, options: [.mixWithOthers])
             #endif
             try session.setActive(true)
+            // What we were actually GRANTED, not what we asked for. Both are best-effort, and the
+            // ring's behaviour depends on the quantum it really gets — without this, a report of
+            // audio jitter arrives with no way to tell a 10 ms session from a 5 ms or a 23 ms one,
+            // which is exactly the gap that made the last round of this take a simulation to close.
+            log.info("""
+                AVAudioSession active: io_buffer_ms=\
+                \(session.ioBufferDuration * 1000, format: .fixed(precision: 2)) \
+                sample_rate=\(Int(session.sampleRate)) \
+                route=\(session.currentRoute.outputs.first?.portType.rawValue ?? "none")
+                """)
             #if os(iOS)
             // Only the `.playAndRecord` session can land on the earpiece, and only it accepts an
             // output override — so the mic-off (`.playback`) path deliberately does neither.
@@ -320,12 +363,15 @@ public final class SessionAudio {
     #endif
 
     /// Build + start the engines — combined (voice-processed) or split, per `wantsCombined` —
-    /// with the mic uplink only when enabled + authorized. Main thread (engine setup); on
-    /// iOS/tvOS the session is already active by the time this runs.
+    /// with the mic uplink only when enabled + authorized. Runs on `engineQueue` (a start can
+    /// block on the audio server for seconds — never the main thread); on iOS/tvOS the session
+    /// is already active by the time this runs.
     private func startEngines(
         speakerUID: String, micUID: String, micChannel: Int, micEnabled: Bool, echoCancel: Bool
     ) {
+        stateLock.lock()
         enginesAttempted = true // even if every path below fails — see `reviveStoppedEngines`
+        stateLock.unlock()
         #if os(tvOS)
         // No app-accessible microphone input on tvOS — playback only.
         startPlayback(speakerUID: speakerUID)
@@ -334,9 +380,25 @@ public final class SessionAudio {
             startPlayback(speakerUID: speakerUID)
             return
         }
+        #if os(macOS)
+        // A rebuild must not re-attempt a voice-processing start that already failed on this
+        // input device: the failure repeats, and the failed attempt's HAL churn stops the healthy
+        // fallback engines — the 2026-08-14 rebuild loop (see `CombinedTopologyGate`).
+        var combined = wantsCombined(
+            speakerUID: speakerUID, micUID: micUID, micChannel: micChannel,
+            echoCancel: echoCancel)
+        if combined, !combinedGate.shouldTry(input: AudioDevices.defaultInputDevice()) {
+            log.info("""
+                voice processing already failed on this input device — split engines, no echo \
+                cancellation
+                """)
+            combined = false
+        }
+        #else
         let combined = wantsCombined(
             speakerUID: speakerUID, micUID: micUID, micChannel: micChannel,
             echoCancel: echoCancel)
+        #endif
         switch AVCaptureDevice.authorizationStatus(for: .audio) {
         case .authorized:
             if combined {
@@ -352,7 +414,8 @@ public final class SessionAudio {
             // drain thread carry over — see `makePlaybackChain`).
             startPlayback(speakerUID: speakerUID)
             AVCaptureDevice.requestAccess(for: .audio) { [weak self] granted in
-                DispatchQueue.main.async {
+                guard let self else { return }
+                self.engineQueue.async { [weak self] in
                     guard let self, granted, !self.flag.isStopped else { return }
                     if combined {
                         self.stateLock.lock()
@@ -491,6 +554,17 @@ public final class SessionAudio {
     ///  - the route-change and media-services-reset notifications, iOS/tvOS, where the session and
     ///    not the device is what moves.
     ///
+    /// And three defenses keep the recovery from ANSWERING ITSELF — a rebuild is not a silent
+    /// act (a voice-processing start builds and tears down HAL aggregates, and every fresh engine
+    /// renegotiates its IO), so its own fallout can retrigger it. The 2026-08-14 field loop was
+    /// exactly that: VPIO failed on a 6-channel mic, every rebuild re-tried it, and the failure's
+    /// churn stopped the fallback engines — audio and (via the main thread) INPUT cutting out
+    /// every ~2.5 s for the whole session. The defenses: a configuration change from an engine
+    /// that is RUNNING is a rebuild's echo and is ignored (`hardwareMoved`); a VPIO failure is
+    /// latched per input device and never re-attempted on it (`CombinedTopologyGate`); and
+    /// rebuilds that chain anyway back off exponentially instead of metronoming
+    /// (`RebuildBackoff`).
+    ///
     /// `micEnabled` only decides whether the mic-bearing session observers are worth installing.
     /// Main thread.
     private func installDeviceChangeRecovery(micEnabled: Bool) {
@@ -501,7 +575,7 @@ public final class SessionAudio {
 
         let watcher = AudioDeviceWatcher(
             isOurs: { [weak self] posted in self?.ownsEngine(posted) ?? false },
-            onChange: { [weak self] reason in self?.hardwareMoved(reason) })
+            onChange: { [weak self] reason, posted in self?.hardwareMoved(reason, posted: posted) })
         stateLock.lock()
         deviceWatcher = watcher
         stateLock.unlock()
@@ -527,10 +601,17 @@ public final class SessionAudio {
     /// question — is playback still where it should be — but they answer it differently: an engine
     /// that told us it stopped is definitive, while the default device moving might not concern us
     /// at all.
-    private func hardwareMoved(_ reason: AudioDeviceWatcher.Reason) {
+    private func hardwareMoved(_ reason: AudioDeviceWatcher.Reason, posted: AnyObject?) {
         guard !flag.isStopped else { return }
         switch reason {
         case .engineConfiguration:
+            // The engine stops itself BEFORE posting this — so an engine that is RUNNING when the
+            // notification lands on the main queue is one a rebuild already replaced or restarted:
+            // the notification is the rebuild's own echo, and answering it is how the recovery
+            // loops. A change that stops the engine again after this posts again, and the HAL
+            // backstop checks placement independently, so ignoring a live engine's echo can never
+            // strand a stopped one.
+            if let engine = posted as? AVAudioEngine, engine.isRunning { return }
             scheduleEngineRebuild(reason: reason.rawValue)
         case .defaultOutputDevice:
             #if os(macOS)
@@ -550,7 +631,10 @@ public final class SessionAudio {
     /// output device at the moment it connected — and leaving it silent for good. On iOS the same
     /// flag keeps this from racing the asynchronous start, where no engine yet is normal.
     private func reviveStoppedEngines(_ reason: String) {
-        guard !flag.isStopped, enginesAttempted, !playbackIsLive else { return }
+        stateLock.lock()
+        let attempted = enginesAttempted
+        stateLock.unlock()
+        guard !flag.isStopped, attempted, !playbackIsLive else { return }
         scheduleEngineRebuild(reason: "playback is stopped and \(reason)")
     }
 
@@ -572,15 +656,43 @@ public final class SessionAudio {
     private func scheduleEngineRebuild(reason: String) {
         guard !rebuildQueued else { return }
         rebuildQueued = true
-        let since = ProcessInfo.processInfo.systemUptime - lastRebuildAt
-        let delay = max(Self.rebuildDebounce, Self.rebuildFloor - since)
-        log.info("\(reason) — restarting the audio engines in \(Int(delay * 1000)) ms")
+        let delay = rebuildBackoff.delay(now: ProcessInfo.processInfo.systemUptime)
+        if rebuildBackoff.chain >= 2 {
+            // Each rebuild is retriggering the next — a feedback shape the echo guard and the
+            // topology gate did not identify. Keep answering (a real recovery must not be
+            // abandoned), but say what is happening: this line repeating IS the diagnosis.
+            log.warning("""
+                audio engine rebuilds are chaining (\(self.rebuildBackoff.chain) in a row — \
+                \(reason)); backing off \(Int(delay * 1000)) ms
+                """)
+        } else {
+            log.info("\(reason) — restarting the audio engines in \(Int(delay * 1000)) ms")
+        }
         DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
-            self?.rebuildEngines(attempt: 0)
+            self?.rebuildFire(attempt: 0)
+        }
+    }
+
+    /// The scheduled rebuild came due (main queue): close out the bookkeeping and hand the
+    /// actual engine work to `engineQueue` — the teardown + start can block on the audio server
+    /// for seconds, and the main thread is where macOS captures and sends the stream's input.
+    /// A trigger arriving while the work is in flight schedules a fresh rebuild rather than
+    /// being swallowed; `engineQueue` is serial, so the two never interleave.
+    private func rebuildFire(attempt: Int) {
+        rebuildQueued = false
+        guard !flag.isStopped else { return }
+        stateLock.lock()
+        let config = startConfig
+        stateLock.unlock()
+        guard let config else { return }
+        rebuildBackoff.noteRebuild(at: ProcessInfo.processInfo.systemUptime)
+        engineQueue.async { [weak self] in
+            self?.performRebuild(config: config, attempt: attempt)
         }
     }
 
     /// Put back the topology this session was started with, on whatever hardware is there now.
+    /// Runs on `engineQueue`.
     ///
     /// A full rebuild rather than a `start()` on the stopped engine, because the mic side has to
     /// follow too: `installMicTap` reads the input's live format, and the voice processor
@@ -588,10 +700,8 @@ public final class SessionAudio {
     /// across (`makePlaybackChain` reuses it, `startDrain` is idempotent), so the drain thread
     /// keeps decoding right through the switch and its overflow policy has already dropped
     /// everything that went stale while the engine was down.
-    private func rebuildEngines(attempt: Int) {
-        rebuildQueued = false
-        guard !flag.isStopped, let config = startConfig else { return }
-        lastRebuildAt = ProcessInfo.processInfo.systemUptime
+    private func performRebuild(config: StartConfig, attempt: Int) {
+        guard !flag.isStopped else { return }
         tearDownEngines()
         startEngines(
             speakerUID: config.speakerUID, micUID: config.micUID, micChannel: config.micChannel,
@@ -604,6 +714,18 @@ public final class SessionAudio {
             log.info("audio engines restarted on the current device")
             return
         }
+        DispatchQueue.main.async { [weak self] in
+            self?.rebuildFailed(attempt: attempt)
+        }
+    }
+
+    /// A rebuild's playback did not come back (main queue) — walk the retry ladder. Retries
+    /// when a rebuild's `start()` loses the race with a device that is still going away
+    /// (0.3 s, 0.6 s, 1.2 s): a failed rebuild leaves no engine to post the next notification,
+    /// so this ladder — and, on macOS, the HAL listener — is all that stands between a mistimed
+    /// switch and a silent session.
+    private func rebuildFailed(attempt: Int) {
+        guard !flag.isStopped else { return }
         guard attempt < Self.rebuildAttempts else {
             #if os(macOS)
             log.error("""
@@ -615,10 +737,11 @@ public final class SessionAudio {
             #endif
             return
         }
+        guard !rebuildQueued else { return } // a fresh trigger already queued a full rebuild
         rebuildQueued = true // holds off a trigger that would only race this ladder
-        let delay = Self.rebuildDebounce * Double(1 << (attempt + 1))
+        let delay = RebuildBackoff.debounce * Double(1 << (attempt + 1))
         DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
-            self?.rebuildEngines(attempt: attempt + 1)
+            self?.rebuildFire(attempt: attempt + 1)
         }
     }
 
@@ -764,9 +887,13 @@ public final class SessionAudio {
         public let avOffsetMS: Int
     }
 
-    /// A snapshot of `Stats`, or nil before playback starts. Main thread (`ring` is main-confined;
-    /// the ring's own numbers are taken under its lock, so they describe one instant).
+    /// A snapshot of `Stats`, or nil before playback starts. Safe from any thread (the handle is
+    /// taken under `stateLock`; the ring's own numbers are taken under its lock, so they
+    /// describe one instant).
     public var stats: Stats? {
+        stateLock.lock()
+        let ring = self.ring
+        stateLock.unlock()
         guard let s = ring?.stats else { return nil }
         return Stats(bufferMS: s.bufferedMS, avOffsetMS: s.avOffsetMS)
     }
@@ -791,7 +918,7 @@ public final class SessionAudio {
     /// The playback jitter ring + the source node draining it — shared by the plain playback
     /// engine and the combined voice-processing engine, and REUSED across an engine rebuild
     /// (same session, same ring: the drain thread keeps writing right through the swap). nil
-    /// when the host's channel layout can't be expressed (already logged). Main thread.
+    /// when the host's channel layout can't be expressed (already logged). Runs on `engineQueue`.
     private func makePlaybackChain()
         -> (ring: AudioRing, source: AVAudioSourceNode, format: AVAudioFormat)?
     {
@@ -801,8 +928,10 @@ public final class SessionAudio {
         // 1 s interleaved capacity, scaled by the channel count. The de-jitter depth itself is
         // the ring's own business now (`AudioRing.targetMS`, mirroring `JitterTuning::COREAUDIO`)
         // rather than a prefill passed in here.
+        stateLock.lock()
         let ring = self.ring ?? AudioRing(capacity: 48_000 * channels, channels: channels)
         self.ring = ring
+        stateLock.unlock()
 
         // Engine-native deinterleaved float; the render block deinterleaves from the ring. Surround
         // uses an explicit wire-order channel layout; the mixer downmixes to the output device when
@@ -961,6 +1090,17 @@ public final class SessionAudio {
     // MARK: - Mic (mic → host)
 
     #if !os(tvOS)
+    /// The combined topology failed to come up. On macOS, latch the input device it failed on so
+    /// a rebuild goes straight to the split topology instead of re-running the failure — the
+    /// failed attempt is what churns the HAL and retriggers the recovery (see
+    /// `CombinedTopologyGate`). On iOS routes are session-managed and a VPIO failure is the
+    /// transient route-transition kind, so nothing is latched there.
+    private func noteCombinedFailure() {
+        #if os(macOS)
+        combinedGate.noteFailure(input: AudioDevices.defaultInputDevice())
+        #endif
+    }
+
     /// One engine, both directions: engage the system voice processor on the shared IO unit
     /// (AEC + noise suppression + AGC), hang the playback source off its render side and the
     /// mic tap off its capture side. Every failure falls back to a WORKING configuration —
@@ -979,6 +1119,7 @@ public final class SessionAudio {
                 voice processing unavailable (\(error.localizedDescription)) — separate \
                 engines, no echo cancellation
                 """)
+            noteCombinedFailure()
             startPlayback(speakerUID: speakerUID)
             startCapture(micUID: micUID, micChannel: micChannel)
             return
@@ -1032,6 +1173,7 @@ public final class SessionAudio {
             // processor won't engage at all, already does exactly this; this arm used to give up
             // on the mic instead, which is how a whole session could go silent uplink-only.)
             engine.stop()
+            noteCombinedFailure()
             startPlayback(speakerUID: speakerUID)
             startCapture(micUID: micUID, micChannel: micChannel)
             return
@@ -1042,6 +1184,7 @@ public final class SessionAudio {
             log.error("combined engine failed to start: \(error.localizedDescription)")
             engine.inputNode.removeTap(onBus: 0)
             engine.stop()
+            noteCombinedFailure()
             // Same rule: a working mic without echo cancellation beats no mic at all.
             startPlayback(speakerUID: speakerUID)
             startCapture(micUID: micUID, micChannel: micChannel)

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

@@ -382,12 +382,29 @@ public final class PunktfunkConnection {
     /// the client draws its own (a visible system cursor over the stream).
     public private(set) var resolvedCompositor: Compositor = .auto
 
-    /// Host clock minus client clock (nanoseconds), from the connect-time wall-clock skew handshake
-    /// (`punktfunk_connection_clock_offset_ns`). Add it to a local `CLOCK_REALTIME` instant to
-    /// express that instant in the host's capture clock — the clock each `AccessUnit.ptsNs` is
-    /// stamped in — so a glass-to-glass latency (present/enqueue time minus `ptsNs`) is valid across
-    /// machines. `0` = no correction (an older host that didn't answer, or synchronized clocks).
-    public private(set) var clockOffsetNs: Int64 = 0
+    /// Host clock minus client clock (nanoseconds) — LIVE: the connect-time skew handshake's
+    /// estimate, kept fresh by the core's mid-stream re-syncs (every 60 s plus immediately on a
+    /// suspected wall-clock step; `punktfunk_connection_clock_offset_now_ns`, ABI v10). Add it to
+    /// a local `CLOCK_REALTIME` instant to express that instant in the host's capture clock — the
+    /// clock each `AccessUnit.ptsNs` is stamped in — so a glass-to-glass latency (present/enqueue
+    /// time minus `ptsNs`) is valid across machines. `0` = no correction (an older host that
+    /// didn't answer, synchronized clocks, or a closed connection).
+    ///
+    /// ⚠ LIVE means DO NOT CACHE. Until 2026-08-13 this was a connect-time snapshot, and the
+    /// core's own doc names the failure: "after an NTP step or slow drift the connect-time value
+    /// silently corrupts every capture-clock comparison." The field evidence was stark — two
+    /// sessions minutes apart against the same wired host read hostnet 17–21 ms, then a
+    /// physically impossible 4.4 ms (the host is a VM; VM wall clocks step), and LatencyMeter's
+    /// impossible-sample guard silently trimmed the shifted-negative half, so the HUD showed a
+    /// plausible small number instead of an alarm. Read this property at each use — it is an
+    /// atomic load behind the FFI — and never park it in a `let` or a closure capture list.
+    /// Cross-thread reads follow the `framesDropped()` precedent.
+    public var clockOffsetNs: Int64 {
+        guard let handle else { return 0 }
+        var offset: Int64 = 0
+        _ = punktfunk_connection_clock_offset_now_ns(handle, &offset)
+        return offset
+    }
 
     /// The video encoder bitrate (kbps) the host actually configured — the requested
     /// `bitrateKbps` clamped to the host's range ([500, 2 000 000] kbps), or its default
@@ -635,9 +652,6 @@ public final class PunktfunkConnection {
         var comp: UInt32 = 0
         _ = punktfunk_connection_compositor(handle, &comp)
         resolvedCompositor = Compositor(rawValue: comp) ?? .auto
-        var offset: Int64 = 0
-        _ = punktfunk_connection_clock_offset_ns(handle, &offset)
-        clockOffsetNs = offset
         var br: UInt32 = 0
         _ = punktfunk_connection_bitrate(handle, &br)
         resolvedBitrateKbps = br

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

@@ -15,8 +15,9 @@ import Foundation
 ///   `record(ptsNs:atNs:offsetNs:)` at present.
 ///
 /// For the host-anchored intervals (capture→…) the sample is `end + offset - pts_ns`, where
-/// `pts_ns` is the host's capture wall clock (the AU's pts) and the connect-time **clock-skew
-/// offset** (`PunktfunkConnection.clockOffsetNs`, host minus client) makes the difference valid
+/// `pts_ns` is the host's capture wall clock (the AU's pts) and the LIVE **clock-skew
+/// offset** (`PunktfunkConnection.clockOffsetNs`, host minus client, mid-stream re-synced —
+/// read it per record, never cached) makes the difference valid
 /// across machines. `offsetNs == 0` means an old host that didn't answer the skew handshake (or
 /// genuinely synced clocks) — the number is then only meaningful same-host, and the HUD tags the
 /// end-to-end line `(same-host clock)`.
@@ -24,6 +25,8 @@ public final class LatencyMeter: @unchecked Sendable {
     private let lock = NSLock()
     private var samplesUs: [Int64] = []
     private var skewCorrected = false
+    /// Samples `record` refused as impossible since the last `drainTrimmed` (see the guard).
+    private var trimmed = 0
     /// The most recent sample and the instant it ended, for `latestSample(asOfNs:maxAgeMs:)` —
     /// a LEVEL, not a window, so `drain` deliberately leaves both alone.
     private var latestNs: Int64 = 0
@@ -49,8 +52,19 @@ public final class LatencyMeter: @unchecked Sendable {
     public func record(ptsNs: UInt64, atNs: Int64, offsetNs: Int64) {
         let latNs = atNs &+ offsetNs &- Int64(bitPattern: ptsNs)
         // Drop absurd values (a clock step, a wildly wrong offset, garbage pts, or a stage whose
-        // start stamp is missing/after its end) — samples are clamped to (0, 10 s).
-        guard latNs > 0, latNs < 10_000_000_000 else { return }
+        // start stamp is missing/after its end) — samples are clamped to (0, 10 s). COUNTED, not
+        // silent: a cluster of non-positive samples is the signature of a wrong clock offset
+        // (client-local stages can't go negative), and a meter that quietly trims the impossible
+        // half of a shifted distribution presents the surviving tail as a plausible small number
+        // — field 2026-08-13: "e2e 0–3 ms p50 / 23 ms p95" on a session whose true hostnet was
+        // ~18 ms. `drainTrimmed` surfaces the count so the window can be MARKED suspect instead
+        // of looking healthy.
+        guard latNs > 0, latNs < 10_000_000_000 else {
+            lock.lock()
+            trimmed += 1
+            lock.unlock()
+            return
+        }
         lock.lock()
         samplesUs.append(latNs / 1000)
         latestNs = latNs
@@ -99,6 +113,18 @@ public final class LatencyMeter: @unchecked Sendable {
         public let skewCorrected: Bool
     }
 
+    /// Take-and-reset the count of impossible samples `record` refused (see its guard). Drained
+    /// SEPARATELY from `drain()` on purpose: with a badly wrong offset EVERY sample of a window
+    /// can be non-positive, `drain()` then returns `nil` — and a count folded into `Stats` would
+    /// vanish with it, hiding the very windows that scream loudest. This survives an empty window.
+    public func drainTrimmed() -> Int {
+        lock.lock()
+        defer { lock.unlock() }
+        let n = trimmed
+        trimmed = 0
+        return n
+    }
+
     /// Percentiles over the samples accumulated since the last drain, then reset the window. `nil`
     /// when no samples arrived in the interval.
     public func drain() -> Stats? {

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

@@ -56,17 +56,27 @@ enum WindowedPresentMode: String, Sendable {
 /// 203-nit diffuse white at EDR 1.0 (the display's SDR-white level) and lets the system tone-map the
 /// brighter highlights into the panel's headroom. This is the missing anchor that made the old HDR path
 /// render "way too bright" (no `edrMetadata` → no reference-white anchoring); a LARGER value renders
-/// dimmer. Matches the host's standard PQ reference white.
+/// dimmer.
+///
+/// ⚠️ This is one half of a pair: the host has to map SDR content into the PQ container at the SAME
+/// luminance, and pins it to 203 in `pf-vdisplay`'s `SDR_REFERENCE_WHITE_NITS`. When they disagree
+/// every pixel is off by the ratio — a gamescope host left on gamescope's own 400-nit default put
+/// the stream nearly a stop bright, which read as a glaring, over-saturated Steam UI and washed-out
+/// HDR game content at the same time. Change one end without the other and that gap re-opens.
 private let hdrReferenceWhiteNits: Float = 203.0
 
-/// PUNKTFUNK_SDR_COLORSPACE=srgb — A/B hatch for the SDR layer's colour tag. Today the SDR layer
-/// ships with `colorspace = nil`, which on macOS means NO colour matching: the BT.709/sRGB-encoded
-/// stream is displayed with the panel's native primaries — mild oversaturation on every P3 Mac.
-/// `srgb` tags the layer so CoreAnimation colour-matches it into the panel's gamut (the strictly
-/// correct rendering). Kept OFF by default until the on-glass A/B confirms it (the nil path is the
-/// long-proven look, and some users may prefer the vivid rendition); flip the default once verified.
-private let sdrColorspaceOverride: CGColorSpace? = {
-    guard ProcessInfo.processInfo.environment["PUNKTFUNK_SDR_COLORSPACE"] == "srgb" else {
+/// The SDR layer's colour tag. `colorspace = nil` means NO colour matching: the BT.709-encoded
+/// stream is handed to the compositor untagged and drawn in the display's native space. That is
+/// mild oversaturation on a P3 Mac or iPad, and on a tvOS display composited for HDR it also lifts
+/// the black floor — the 2026-08-13 field report of greys where blacks should be, which arrived
+/// with the client's own HDR switch already OFF, so no other stage had tagged those pixels either.
+/// Tagging lets CoreAnimation colour-match into whatever the output actually is, which is the
+/// strictly correct rendering, so it is now the default.
+///
+/// `PUNKTFUNK_SDR_COLORSPACE=none` restores the old untagged look — the A/B lever if a panel
+/// regresses, or for anyone who preferred the more vivid rendition.
+private let sdrColorspace: CGColorSpace? = {
+    guard ProcessInfo.processInfo.environment["PUNKTFUNK_SDR_COLORSPACE"] != "none" else {
         return nil
     }
     return CGColorSpace(name: CGColorSpace.sRGB)
@@ -425,6 +435,14 @@ public final class MetalVideoPresenter {
     /// Render-thread confined once the pipeline runs (Stage2Pipeline.start's one pre-thread
     /// `configure` call is ordered before the thread starts, so it doesn't race).
     private var hdrActive = false
+    /// Has `configureColor` run even once? `hdrActive` starts `false`, so a session that is SDR from
+    /// the first frame matches the initial state and used to fall straight through `configure`'s
+    /// guard — the layer then kept `make()`'s bare config, which never assigns a colour space, and
+    /// the SDR stream presented untagged for the whole session. That also made
+    /// `PUNKTFUNK_SDR_COLORSPACE` dead code on exactly the sessions it was meant to fix, so an
+    /// operator A/B-ing it in the field saw nothing change. Same-state calls after the first are
+    /// still no-ops, which is what the guard is for.
+    private var didConfigureColor = false
     /// tvOS only: whether HDR frames currently present as PQ PASSTHROUGH (display has HDR headroom
     /// — its own tone-map applies) vs the in-shader tone-map fallback. Render-thread confined;
     /// derived from the staged display headroom at the top of every `render`.
@@ -549,6 +567,11 @@ public final class MetalVideoPresenter {
         layer.contentsGravity = .resizeAspect
         // Triple-buffer: more in-flight drawables before `nextDrawable()` (called on the display-link /
         // MAIN thread) has to block waiting for one to free.
+        // ⚠ This is the STAGE-2/3 depth. Stage-4 (deadline pacing, the iOS/tvOS default) never
+        // calls `nextDrawable()` — the link vends every drawable — so the third slot only gives
+        // the compositor room to queue a second present ahead of scanout, i.e. the two-refresh
+        // present floor. `Stage2Pipeline.startDeadlinePresenter` clamps it to 2 for that pacing;
+        // keep the two in step if this number ever changes.
         layer.maximumDrawableCount = 3
 
         return MetalVideoPresenter(
@@ -592,13 +615,16 @@ public final class MetalVideoPresenter {
         stagingLock.lock()
         let passthrough = stagedDisplayHeadroom > 1.0
         stagingLock.unlock()
-        guard hdr != hdrActive || (hdr && passthrough != hdrPassthroughActive) else { return }
+        guard !didConfigureColor || hdr != hdrActive
+            || (hdr && passthrough != hdrPassthroughActive)
+        else { return }
         hdrActive = hdr
         hdrPassthroughActive = passthrough
         #else
-        guard hdr != hdrActive else { return }
+        guard !didConfigureColor || hdr != hdrActive else { return }
         hdrActive = hdr
         #endif
+        didConfigureColor = true
         configureColor(hdr: hdr)
     }
 
@@ -628,9 +654,10 @@ public final class MetalVideoPresenter {
                 layer.colorspace = CGColorSpace(name: CGColorSpace.itur_2100_PQ)
             } else {
                 // SDR-composited display: PQ would render untone-mapped (blown out) — the
-                // pf_frag_hdr_tv shader tone-maps to SDR instead.
+                // pf_frag_hdr_tv shader tone-maps to SDR instead. Its output is BT.709, so it
+                // carries the same SDR tag as a genuinely SDR session.
                 layer.pixelFormat = .bgra8Unorm
-                layer.colorspace = nil
+                layer.colorspace = sdrColorspace
             }
             #else
             layer.pixelFormat = .rgba16Float
@@ -641,12 +668,11 @@ public final class MetalVideoPresenter {
             layer.edrMetadata = makeEDR(lastHdrMeta)
             #endif
         } else {
-            // SDR: gamma-encoded BT.709 [0,1] in an 8-bit drawable. Default: nil colorspace = NO
-            // colour matching on macOS (the panel's native primaries — the long-proven look,
-            // slightly oversaturated on P3 panels); PUNKTFUNK_SDR_COLORSPACE=srgb tags the layer
-            // for correct colour matching instead (A/B pending — see sdrColorspaceOverride).
+            // SDR: gamma-encoded BT.709 [0,1] in an 8-bit drawable, tagged so CoreAnimation
+            // colour-matches it into the output rather than drawing it in the panel's native
+            // space (see sdrColorspace; PUNKTFUNK_SDR_COLORSPACE=none restores untagged).
             layer.pixelFormat = .bgra8Unorm
-            layer.colorspace = sdrColorspaceOverride
+            layer.colorspace = sdrColorspace
             #if !os(tvOS)
             layer.wantsExtendedDynamicRangeContent = false
             layer.edrMetadata = nil

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

@@ -260,13 +260,22 @@ final class SessionPresenter {
         // value is deliberately ignored). The user-facing choice is the INTENT
         // (PresentPriority): latency (newest-wins zero-queue store) vs smoothness (a FIFO jitter
         // buffer; on macOS it additionally paces presents onto the vsync grid so the buffer
-        // drains on display cadence). Stage-1 is reachable only via env in DEBUG; release maps
-        // it back to the default (the stage-1 pump below stays the automatic Metal-missing
-        // fallback).
+        // drains on display cadence). Stage-1 resolves from the persisted picker only in DEBUG;
+        // in release the ENV alone reaches it (the stage-1 pump below stays the automatic
+        // Metal-missing fallback either way).
         #if DEBUG
         let allowStage1 = true
         #else
-        let allowStage1 = false
+        // The gate exists so a LEFTOVER value can't revive the freeze-prone fallback — but the
+        // persisted picker is no longer read at all (setting: nil below), so the only channel
+        // left is the env, and an env var is never leftover: it takes a devicectl/Xcode launch
+        // to exist. It must stay openable on Release because Release is the only build that
+        // measures presentation honestly, and stage-1 is the one rung that presents on the
+        // hardware video plane instead of through the GPU compositor — the A/B for the tvOS
+        // two-refresh present floor (field 2026-08-13: PUNKTFUNK_PRESENTER=stage1 on a Release
+        // build silently ran stage-4, which would have false-negatived that A/B).
+        let allowStage1 =
+            ProcessInfo.processInfo.environment["PUNKTFUNK_PRESENTER"] == "stage1"
         #endif
         let explicit = PresenterChoice.explicit(
             setting: nil, // the legacy DefaultsKey.presenter picker value is no longer read
@@ -336,7 +345,7 @@ final class SessionPresenter {
         } else {
             let pump = StreamPump()
             pump.start(
-                connection: connection, layer: baseLayer,
+                connection: connection, layer: baseLayer, endToEndMeter: endToEndMeter,
                 onFrame: onFrame, onSessionEnd: onSessionEnd, onDecodedSize: onDecodedSize)
             self.pump = pump
         }

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

@@ -271,6 +271,64 @@ final class LatestBox<T>: @unchecked Sendable {
     }
 }
 
+/// The deadline link's frame-latency ASK and property READBACK, published for the HUD to render.
+///
+/// ⚠ A readback is NOT a grant. `preferredFrameLatency` is a plain read-write float
+/// (CAMetalDisplayLink.h carries no doc contract), so reading it returns whatever we last
+/// stored unless the system actively clamps the setter — and the 2026-08-13 field run proved
+/// how misleading that is: it read 1.00 while the measured vend lead sat at 1.95 refresh
+/// periods. The number that tells the truth about scheduling is the vend lead (the HUD's
+/// `os present` floor), never this property. The line still earns its place twice over: a
+/// readback that DIFFERS from the ask is the one clamp signal the API can give, and the ask
+/// must be visible on screen because **on tvOS no log is reachable** — `log stream --device`
+/// is gone from modern macOS, `log collect --device-name` needs root and then fails "Device
+/// not configured" because an Apple TV has no USB to fall back to, and the libimobiledevice
+/// pairing is a different database from Xcode's. Console.app is a GUI.
+///
+/// A process-global rather than a sixth parameter threaded through SessionModel → StreamView →
+/// controller → SessionPresenter → Stage2Pipeline → delegate: it is write-once-per-session
+/// diagnostics, and this file already keeps `presentDebug`/`presentLog` at file scope. Reset by
+/// `clear()` at session start so a stale session's answer can never be read as this one's.
+public final class PresentLinkInfo: @unchecked Sendable {
+    public static let shared = PresentLinkInfo()
+    private let lock = NSLock()
+    private var ask: Float = 0
+    private var latency: Float = 0
+    private var rangeMin: Float = 0
+    private var rangeMax: Float = 0
+    private var drawables: Int = 0
+    private var present = false
+
+    private init() {}
+
+    func publish(ask: Float, latency: Float, rangeMin: Float, rangeMax: Float, drawables: Int) {
+        lock.lock()
+        self.ask = ask
+        self.latency = latency
+        self.rangeMin = rangeMin
+        self.rangeMax = rangeMax
+        self.drawables = drawables
+        present = true
+        lock.unlock()
+    }
+
+    /// Session start — a link that never comes up must not leave the previous one's answer up.
+    public func clear() {
+        lock.lock()
+        present = false
+        lock.unlock()
+    }
+
+    /// `nil` until the link's first update (or on a non-deadline rung, which has no link).
+    public func snapshot()
+        -> (ask: Float, latency: Float, rangeMin: Float, rangeMax: Float, drawables: Int)?
+    {
+        lock.lock()
+        defer { lock.unlock() }
+        return present ? (ask, latency, rangeMin, rangeMax, drawables) : nil
+    }
+}
+
 /// Deadline pacing's staged frame-rate hint. SessionPresenter pushes the stream rate from the
 /// MAIN thread (session start + every layout/Reconfigure); the link's own thread drains and
 /// applies it, so the CAMetalDisplayLink is only ever touched from the thread that runs it. The
@@ -312,9 +370,24 @@ private final class FrameRateHint: @unchecked Sendable {
         return p
     }
     private static func range(hz: Float, boosted: Bool) -> CAFrameRateRange {
+        #if os(tvOS)
+        // A TV is a FIXED-rate display: there is no ProMotion panel to lift and no Pencil to
+        // sample for, so the `max(hz, 120)` ceiling below asks a 60 Hz Apple TV to accept
+        // anything up to 120. A range is a promise about how variable our cadence may be, and a
+        // scheduler handed 60…120 on a fixed 60 Hz display has every reason to keep a frame of
+        // slack in hand — which is what a two-refresh `targetPresentationTimestamp` IS. Pin all
+        // three bounds to the stream rate so the deadline has nothing to hedge against.
+        // (Field 2026-08-13, Apple TV 4K / tvOS 27: `os present` stuck at ~2 × 16.67 with
+        // `preferredFrameLatency = 1` asked for and re-asserted every update; shrinking the
+        // drawable pool to 2 moved it not at all.) `boosted` is deliberately ignored — it exists
+        // for pen proximity, which tvOS does not have.
+        _ = boosted
+        return CAFrameRateRange(minimum: hz, maximum: hz, preferred: hz)
+        #else
         let cap = max(hz, 120)
         let preferred = boosted ? cap : hz
         return CAFrameRateRange(minimum: preferred, maximum: cap, preferred: preferred)
+        #endif
     }
 }
 
@@ -435,18 +508,28 @@ private final class DeadlineLinkDelegate: NSObject, CAMetalDisplayLinkDelegate {
     private let phase: PhaseReporter?
     /// The OS-floor sampler (design/apple-presentation-rebuild.md): every update's vend→glass
     /// lead is recorded so its p50 becomes the "OS present floor" the HUD subtracts from the
-    /// shown display/e2e numbers. Self-adapting — reads ~2 refresh periods composited today,
-    /// would read ~1 under direct-to-display, tracks VRR rate changes.
+    /// shown display/e2e numbers. Self-adapting: ~1 refresh period is the goal, ~2 means the
+    /// compositor is running a frame ahead of us (what a 3-slot drawable pool bought it before
+    /// `startDeadlinePresenter` clamped stage-4 to 2). Tracks VRR rate changes.
     private let floorMeter: LatencyMeter?
-    /// One-shot: log the link's EFFECTIVE preferredFrameLatency after the first re-assert —
-    /// reads 1 while vendLeadMs sits at ~2 periods ⇒ the scheduler ignores the request while
-    /// the layer is composited (the promotion hunt); reads 2 ⇒ the system clamped it outright.
+    /// The pool depth this session vends from (`startDeadlinePresenter` sets it on the layer).
+    /// Carried only so the one-shot line below reports the two halves of the depth question
+    /// together — a `preferredFrameLatency` of 1 against a 3-slot pool is the configuration that
+    /// measured a two-refresh floor in the field, and reading either number alone hides that.
+    private let drawableCount: Int
+    /// The `preferredFrameLatency` this session asks for — 1 by default, PUNKTFUNK_FRAME_LATENCY
+    /// for the on-device ladder (see `startDeadlinePresenter` for the ladder's design).
+    private let latencyAsk: Float
+    /// One-shot: log the link's preferredFrameLatency READBACK after the first re-assert. A
+    /// readback differing from the ask ⇒ the system clamps the property (the one clamp signal
+    /// it can give); a readback EQUAL to the ask proves nothing — only vendLeadMs does (see
+    /// PresentLinkInfo's doc for the field lesson).
     private var loggedEffective = false
 
     init(
         stash: LatestBox<CAMetalDrawable>, renderSignal: DispatchSemaphore,
         hint: FrameRateHint, stats: PresentDebugStats?, floorMeter: LatencyMeter?,
-        phase: PhaseReporter?
+        phase: PhaseReporter?, drawableCount: Int, latencyAsk: Float
     ) {
         self.stash = stash
         self.renderSignal = renderSignal
@@ -454,23 +537,34 @@ private final class DeadlineLinkDelegate: NSObject, CAMetalDisplayLinkDelegate {
         self.stats = stats
         self.floorMeter = floorMeter
         self.phase = phase
+        self.drawableCount = drawableCount
+        self.latencyAsk = latencyAsk
     }
 
     func metalDisplayLink(_ link: CAMetalDisplayLink, needsUpdate update: CAMetalDisplayLink.Update) {
         if let range = hint.drain(), link.preferredFrameRateRange != range {
             link.preferredFrameRateRange = range
         }
-        // Re-assert the minimum-latency request every update (cheap compare): it was set once
-        // before add(to:), and whether a pre-add set survives scheduling is exactly the kind of
+        // Re-assert the latency ask every update (cheap compare): it was set once before
+        // add(to:), and whether a pre-add set survives scheduling is exactly the kind of
         // thing the vendLeadMs stat exists to catch — belt and braces.
-        if link.preferredFrameLatency != 1 { link.preferredFrameLatency = 1 }
+        if link.preferredFrameLatency != latencyAsk { link.preferredFrameLatency = latencyAsk }
+        // Publish every update, not just the first: the range is re-applied from the staged hint
+        // above (mode switch / rate change), and `preferredFrameLatency` is re-asserted right
+        // here — so the readback can change mid-session, and a write-once snapshot would keep
+        // showing the answer to a question we have since asked again. Cheap: five stores under
+        // an uncontended lock, once per refresh.
+        let range = link.preferredFrameRateRange
+        PresentLinkInfo.shared.publish(
+            ask: latencyAsk, latency: link.preferredFrameLatency, rangeMin: range.minimum,
+            rangeMax: range.maximum, drawables: drawableCount)
         if !loggedEffective {
             loggedEffective = true
-            let range = link.preferredFrameRateRange
             let msg = String(
-                format: "deadline link up: effective preferredFrameLatency=%.2f "
-                    + "range=%.0f-%.0f preferred=%.0f",
-                link.preferredFrameLatency, range.minimum, range.maximum, range.preferred ?? 0)
+                format: "deadline link up: preferredFrameLatency ask=%.2f readback=%.2f "
+                    + "maxDrawables=%d range=%.0f-%.0f preferred=%.0f",
+                latencyAsk, link.preferredFrameLatency, drawableCount,
+                range.minimum, range.maximum, range.preferred ?? 0)
             presentLog.info("\(msg, privacy: .public)")
         }
         // The link's own pipeline depth, measured: how far ahead of glass this vend runs.
@@ -729,7 +823,13 @@ public final class Stage2Pipeline {
     /// (which withhold concealed frames) and driven by the pump (arm on a gap, poll per iteration).
     private let gate = ReanchorGate(framesDropped: 0)
     private var token = StopFlag()
-    private var offsetNs: Int64 = 0
+    /// LIVE host↔client clock offset, read AT EACH RECORD — never cached per session. Until
+    /// 2026-08-13 this was a `let` snapshot of the connect-time handshake, and on a host whose
+    /// wall clock steps (a VM under NTP) the frozen value silently shifted every host-anchored
+    /// stat — field evidence: hostnet 17–21 ms one session, a physically impossible 4.4 ms the
+    /// next, same wired host. The core re-syncs the estimate mid-stream (60 s + step detection);
+    /// each call is an atomic load behind the FFI.
+    private var clockOffset: () -> Int64 = { 0 }
     /// Signalled when the pump thread exits, so `stop()` can join it (bounded) before `decoder.reset()`
     /// — otherwise a pump iteration already past its `token.isStopped` check can rebuild a decode session
     /// right after the reset (a brief orphan session). `pumpJoinable` is armed by `start`, consumed by
@@ -831,7 +931,7 @@ public final class Stage2Pipeline {
         onSessionEnd: (@Sendable () -> Void)?,
         onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil
     ) {
-        offsetNs = connection.clockOffsetNs
+        clockOffset = { connection.clockOffsetNs } // live (re-synced) — see the field doc
         recovery.bind(connection) // arm host-keyframe recovery for this session
         decodeReport.bind(connection) // arm the Automatic-bitrate decode signal for this session
         phaseReporter.bind(connection) // arm phase reports (flushed only by the deadline link)
@@ -1001,7 +1101,7 @@ public final class Stage2Pipeline {
         let ring = ring
         let endToEndMeter = endToEndMeter
         let displayMeter = displayMeter
-        let offsetNs = offsetNs
+        let clockOffset = clockOffset
         let renderSignal = renderSignal
         let renderStopped = renderStopped
         // Present policy — the user's V-Sync setting (default OFF = immediate, the long-proven
@@ -1075,7 +1175,7 @@ public final class Stage2Pipeline {
                         ?? Stage2Pipeline.realtimeNs(forDisplayLinkTimestamp: CACurrentMediaTime())
                     // End-to-end = capture→on-glass, measured directly (skew-corrected via the
                     // connect-time clock offset) — the HUD headline.
-                    endToEndMeter?.record(ptsNs: frame.ptsNs, atNs: atNs, offsetNs: offsetNs)
+                    endToEndMeter?.record(ptsNs: frame.ptsNs, atNs: atNs, offsetNs: clockOffset())
                     // Display stage = decoded → on-glass. Both instants are client CLOCK_REALTIME,
                     // so no skew offset applies.
                     displayMeter?.record(ptsNs: UInt64(frame.decodedNs), atNs: atNs, offsetNs: 0)
@@ -1134,11 +1234,52 @@ public final class Stage2Pipeline {
         let presenter = presenter
         let endToEndMeter = endToEndMeter
         let displayMeter = displayMeter
-        let offsetNs = offsetNs
+        let clockOffset = clockOffset
         let hint = frameRateHint
         let layer = presenter.layer
         let stash = LatestBox<CAMetalDrawable>()
 
+        // ⭐ Shrink the drawable pool to 2 for THIS pacing — the measured fix for a present floor
+        // stuck at two refreshes (field 2026-08-13, Apple TV 4K / tvOS 27: `os present +32.5` at
+        // 60 Hz = 1.95 × 16.67, i.e. the system running a whole frame ahead of us).
+        //
+        // `maximumDrawableCount` is 3 from MetalVideoPresenter.make(), and its rationale there —
+        // "more in-flight drawables before nextDrawable() has to block" — is a STAGE-2 concern.
+        // Stage-4 never calls nextDrawable(): every drawable is vended by the link
+        // (`update.drawable` → stash → `render(into:)`), so the third slot buys this path nothing
+        // and costs it a refresh — a pool of 3 is exactly the room the compositor needs to keep
+        // two presents queued ahead of scanout, which is what `preferredFrameLatency = 1` is
+        // asking it not to do. Two slots is the shallowest pool that still double-buffers: one
+        // vended (stashed or being rendered), one being scanned out.
+        //
+        // Set HERE, not on the link thread: this runs before either the render thread or the link
+        // thread exists, so the layer still has a single writer (the render thread owns
+        // drawableSize/format afterwards — see MetalVideoPresenter's threading notes).
+        // PUNKTFUNK_DRAWABLE_COUNT=3 restores the old depth for an on-glass A/B without a
+        // rebuild; values outside 2...3 are ignored (CAMetalLayer's own accepted range).
+        let drawableCount =
+            ProcessInfo.processInfo.environment["PUNKTFUNK_DRAWABLE_COUNT"]
+                .flatMap(Int.init)
+                .flatMap { (2...3).contains($0) ? $0 : nil } ?? 2
+        layer.maximumDrawableCount = drawableCount
+
+        // The frame-latency ASK (default 1 — wake as late as fits: latch the NEXT refresh).
+        // PUNKTFUNK_FRAME_LATENCY overrides it for the on-device ladder. The property is a
+        // FLOAT, so sub-frame asks (0.5) are expressible; whether the scheduler honours them —
+        // or reacts to the property at all — is exactly what the ladder measures. Field
+        // 2026-08-13 (Apple TV 4K, tvOS 27): ask 1 → vend lead 1.95 refresh periods, and the
+        // readback echoed the ask throughout (it is a plain property — see PresentLinkInfo).
+        // The discriminating runs, watching `os present` (the vend lead), are:
+        //   ask=2   → lead grows to ~3 ⇒ the property WORKS and the tvOS floor is ~ask+1;
+        //             lead stays ~2 ⇒ the property is INERT here — stop pulling this lever.
+        //   ask=0.5 → any lead below ~1.9 ⇒ a real in-regime win to then tune.
+        // Clamped to 0...4: negatives/NaN are meaningless, and beyond 4 asked-for frames of
+        // latency nothing is being measured.
+        let latencyAsk =
+            ProcessInfo.processInfo.environment["PUNKTFUNK_FRAME_LATENCY"]
+                .flatMap(Float.init)
+                .flatMap { $0.isFinite ? min(max($0, 0), 4) : nil } ?? 1
+
         let floorMeter = presentFloorMeter
         let phaseReporter = phaseReporter
         // The link starts LAZILY — the render thread triggers this after the FIRST decoded
@@ -1151,9 +1292,10 @@ public final class Stage2Pipeline {
             let linkThread = Thread {
                 let delegate = DeadlineLinkDelegate(
                     stash: stash, renderSignal: renderSignal, hint: hint, stats: debugStats,
-                    floorMeter: floorMeter, phase: phaseReporter)
+                    floorMeter: floorMeter, phase: phaseReporter,
+                    drawableCount: drawableCount, latencyAsk: latencyAsk)
                 let link = CAMetalDisplayLink(metalLayer: layer)
-                link.preferredFrameLatency = 1 // wake as late as fits: latch the NEXT refresh
+                link.preferredFrameLatency = latencyAsk // see the ladder note above
                 if let range = hint.drain() { link.preferredFrameRateRange = range }
                 link.delegate = delegate // weak — this closure is the strong ref
                 link.add(to: RunLoop.current, forMode: .default)
@@ -1223,7 +1365,7 @@ public final class Stage2Pipeline {
                 let onGlass: (Int64?) -> Void = { presentedNs in
                     let atNs = presentedNs
                         ?? Stage2Pipeline.realtimeNs(forDisplayLinkTimestamp: CACurrentMediaTime())
-                    endToEndMeter?.record(ptsNs: frame.ptsNs, atNs: atNs, offsetNs: offsetNs)
+                    endToEndMeter?.record(ptsNs: frame.ptsNs, atNs: atNs, offsetNs: clockOffset())
                     displayMeter?.record(ptsNs: UInt64(frame.decodedNs), atNs: atNs, offsetNs: 0)
                     debugStats?.presented(atNs: presentedNs, issuedNs: issuedNs)
                 }

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

@@ -17,9 +17,18 @@ final class StreamPump {
 
     /// Pump thread: pull AUs, wrap, enqueue. Non-IDR AUs before the first format
     /// description are dropped. `onFrame`/`onSessionEnd` fire on the pump thread.
+    ///
+    /// `endToEndMeter` is stage-1's ONLY latency instrument, and it measures capture→ENQUEUE —
+    /// not capture→glass like the Metal rungs: the layer decodes AND presents after our hand-off,
+    /// and AVSampleBufferDisplayLayer has no presented callback, so the tail past enqueue (its
+    /// internal decode + the video-plane flip) is unmeasurable from the app. Cross-rung
+    /// comparisons must read this as e2e MINUS decode+display and settle the remainder on
+    /// camera. It is still worth wiring: matching pre-tail halves between rungs pins any felt
+    /// difference on the present tail — the video-plane-vs-compositor question itself.
     func start(
         connection: PunktfunkConnection,
         layer: AVSampleBufferDisplayLayer,
+        endToEndMeter: LatencyMeter? = nil,
         onFrame: (@Sendable (AccessUnit) -> Void)?,
         onSessionEnd: (@Sendable () -> Void)?,
         onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil
@@ -158,7 +167,14 @@ final class StreamPump {
                     // flagging it DoNotDisplay — the layer still decodes it (keeping the reference
                     // chain fed) but shows the last GOOD picture until a clean re-anchor lifts the
                     // gate. Folded from the AU's wire flags (stage-1 has no decode callback).
-                    if !gate.onDecoded(flags: au.flags) {
+                    if gate.onDecoded(flags: au.flags) {
+                        // Capture→enqueue (see start's doc). Only frames that will DISPLAY:
+                        // a withheld frame never reaches glass, so its enqueue instant would
+                        // dilute the population the Metal rungs are compared against. The
+                        // offset is read PER ENQUEUE — it is live (mid-stream re-synced) and
+                        // caching it rebuilds the stale-offset corruption (see clockOffsetNs).
+                        endToEndMeter?.record(ptsNs: au.ptsNs, offsetNs: connection.clockOffsetNs)
+                    } else {
                         StreamPump.setDoNotDisplay(sample)
                     }
                     layer.enqueue(sample)

clients/apple/Sources/PunktfunkKit/Views/StreamViewIOS.swift

@@ -758,10 +758,18 @@ public final class StreamViewController: StreamViewControllerBase {
     /// the switch never lands, so an SDR-composited display can't show blown-out PQ either way.
     /// Applied once per session, as soon as the window and the negotiated mode both exist; the
     /// stop() teardown clears it.
+    ///
+    /// ⚠️ Gated on the STREAM being HDR (`connection.isHDR`), not just on the user's HDR setting.
+    /// The criteria below hardcode BT.2020 + ST.2084 PQ, so without that check an ordinary SDR
+    /// session drove an HDR-capable TV into PQ output — which is a standard way to raise the black
+    /// floor, since the Apple TV switches HDMI to limited-range levels in its HDR modes and a set
+    /// configured for full-range then renders code 16 as grey. Layout re-runs this, so a session
+    /// that flips to HDR mid-stream still picks the mode up on the next pass.
     private func applyDisplayCriteriaIfNeeded() {
         guard let manager = view.window?.avDisplayManager, let connection,
               manager.preferredDisplayCriteria == nil,
-              SessionSettings.current.hdrEnabled
+              SessionSettings.current.hdrEnabled,
+              connection.isHDR
         else { return }
         let mode = connection.currentMode()
         guard mode.width > 0, mode.height > 0, mode.refreshHz > 0 else { return }

clients/apple/Tests/PunktfunkKitTests/AudioDeviceWatcherTests.swift

@@ -32,7 +32,7 @@ final class AudioDeviceWatcherTests: XCTestCase {
         let engine = AVAudioEngine()
         var reasons: [AudioDeviceWatcher.Reason] = []
         let watcher = AudioDeviceWatcher(
-            isOurs: { $0 === engine }, onChange: { reasons.append($0) })
+            isOurs: { $0 === engine }, onChange: { reason, _ in reasons.append(reason) })
         watcher.start()
         defer { watcher.stop() }
 
@@ -51,7 +51,7 @@ final class AudioDeviceWatcherTests: XCTestCase {
         let stranger = AVAudioEngine()
         var reasons: [AudioDeviceWatcher.Reason] = []
         let watcher = AudioDeviceWatcher(
-            isOurs: { $0 === ours }, onChange: { reasons.append($0) })
+            isOurs: { $0 === ours }, onChange: { reason, _ in reasons.append(reason) })
         watcher.start()
         defer { watcher.stop() }
 
@@ -66,7 +66,7 @@ final class AudioDeviceWatcherTests: XCTestCase {
         let engine = AVAudioEngine()
         var reasons: [AudioDeviceWatcher.Reason] = []
         let watcher = AudioDeviceWatcher(
-            isOurs: { $0 === engine }, onChange: { reasons.append($0) })
+            isOurs: { $0 === engine }, onChange: { reason, _ in reasons.append(reason) })
         watcher.start()
         watcher.stop()
 
@@ -93,7 +93,7 @@ final class AudioDeviceWatcherTests: XCTestCase {
         }
 
         var reasons: [AudioDeviceWatcher.Reason] = []
-        let watcher = AudioDeviceWatcher(isOurs: { _ in false }, onChange: { reasons.append($0) })
+        let watcher = AudioDeviceWatcher(isOurs: { _ in false }, onChange: { reason, _ in reasons.append(reason) })
         watcher.start()
         defer {
             _ = Self.setDefaultOutput(original)

clients/apple/Tests/PunktfunkKitTests/AudioRebuildPolicyTests.swift

@@ -0,0 +1,110 @@
+// The two decisions that ended the 2026-08-14 rebuild loop, driven with a synthetic clock.
+//
+// The loop's shape, for the plant-the-defect cases below: the voice-processing engine fails to
+// start (~1.9 s spent trying), the fallback comes up, and its own HAL fallout retriggers the
+// recovery ~0.6 s later — forever. Restore either defect (retry the failed topology, or keep the
+// flat 0.5 s floor) and the session pays an audio gap every ~2.5 s for as long as it lives.
+
+import XCTest
+
+@testable import PunktfunkKit
+
+final class AudioRebuildPolicyTests: XCTestCase {
+    // MARK: - RebuildBackoff
+
+    /// The first trigger of a session keeps the old behaviour: the burst-coalescing debounce.
+    func testFirstTriggerWaitsOnlyTheDebounce() {
+        var backoff = RebuildBackoff()
+        XCTAssertEqual(backoff.delay(now: 1000), RebuildBackoff.debounce)
+    }
+
+    /// One rebuild, then quiet: the next real device switch minutes later is answered at full
+    /// responsiveness — the ladder must never make a HEALTHY recovery sluggish.
+    func testAnIsolatedSwitchLongAfterTheLastRebuildResetsTheChain() {
+        var backoff = RebuildBackoff()
+        _ = backoff.delay(now: 1000)
+        backoff.noteRebuild(at: 1000.2)
+        // Chained once (a second switch soon after — legitimate, e.g. AirPods out then back in).
+        _ = backoff.delay(now: 1001)
+        backoff.noteRebuild(at: 1002)
+        // Minutes of quiet, then a fresh switch: base debounce again, chain forgotten.
+        XCTAssertEqual(backoff.delay(now: 1300), RebuildBackoff.debounce)
+        XCTAssertEqual(backoff.chain, 0)
+    }
+
+    /// THE FIELD LOOP, against the real constants: a trigger 0.6 s after every rebuild, ten
+    /// minutes long. The flat 0.5 s floor produced a rebuild every ~2.5 s — ~240 audio gaps.
+    /// The ladder must cut that by an order of magnitude and settle at the floor cap.
+    func testAChainedLoopBacksOffToTheFloorCap() {
+        var backoff = RebuildBackoff()
+        var now: TimeInterval = 0
+        var rebuilds = 0
+        var lastDelay: TimeInterval = 0
+        let end: TimeInterval = 600
+        while now < end {
+            lastDelay = backoff.delay(now: now)
+            now += lastDelay // the scheduled rebuild fires...
+            backoff.noteRebuild(at: now)
+            rebuilds += 1
+            now += 0.6 // ...and its fallout retriggers the recovery 0.6 s later.
+        }
+        XCTAssertEqual(
+            lastDelay, RebuildBackoff.floorCap - 0.6, accuracy: 0.01,
+            "a persistent loop should settle at one rebuild per floorCap")
+        XCTAssertLessThanOrEqual(
+            rebuilds, 30,
+            "\(rebuilds) rebuilds in 10 min — the ladder is not escalating (the shipped flat "
+                + "floor produced ~240)")
+        // And the loop's END must restore responsiveness: quiet, then a real switch.
+        XCTAssertEqual(backoff.delay(now: now + 120), RebuildBackoff.debounce)
+    }
+
+    /// The ladder's exponent is clamped — a loop that runs for hours must neither overflow nor
+    /// push the interval past the cap.
+    func testTheFloorNeverExceedsTheCap() {
+        var backoff = RebuildBackoff()
+        var now: TimeInterval = 0
+        for _ in 0..<1000 {
+            let delay = backoff.delay(now: now)
+            XCTAssertLessThanOrEqual(delay, RebuildBackoff.floorCap)
+            now += delay
+            backoff.noteRebuild(at: now)
+            now += 0.1
+        }
+    }
+
+    #if os(macOS)
+    // MARK: - CombinedTopologyGate
+
+    /// The loop's fuel: re-attempting the voice-processing start that just failed. Same input
+    /// device ⇒ never again.
+    func testAFailureLatchesForTheDeviceItFailedOn() {
+        var gate = CombinedTopologyGate()
+        XCTAssertTrue(gate.shouldTry(input: 42), "an unfailed gate must allow the attempt")
+        gate.noteFailure(input: 42)
+        XCTAssertFalse(gate.shouldTry(input: 42))
+        XCTAssertFalse(gate.shouldTry(input: 42), "the latch must hold across rebuilds")
+    }
+
+    /// The failure is a property of the DEVICE: a different default input earns a fresh attempt,
+    /// and its own failure latches again — one attempt per device change can never loop.
+    func testADifferentInputDeviceEarnsOneFreshAttempt() {
+        var gate = CombinedTopologyGate()
+        gate.noteFailure(input: 42)
+        XCTAssertTrue(gate.shouldTry(input: 7))
+        gate.noteFailure(input: 7)
+        XCTAssertFalse(gate.shouldTry(input: 7))
+        // Back to the first device: the earlier failure may have been mid-transition — one fresh
+        // attempt again, not a permanent ban.
+        XCTAssertTrue(gate.shouldTry(input: 42))
+    }
+
+    /// "No resolvable input device" is a real failure key too, distinct from "never failed".
+    func testFailingWithNoInputDeviceLatchesForNoInputDevice() {
+        var gate = CombinedTopologyGate()
+        gate.noteFailure(input: nil)
+        XCTAssertFalse(gate.shouldTry(input: nil))
+        XCTAssertTrue(gate.shouldTry(input: 42), "a device appearing is a device change")
+    }
+    #endif
+}

clients/apple/Tests/PunktfunkKitTests/AudioRingDriftTests.swift

@@ -106,6 +106,77 @@ final class AudioRingDriftTests: XCTestCase {
             "a single short read must not force a full re-prime")
     }
 
+    /// THE regression that made an iPad crackle where a Mac did not: the de-prime fuse must be the
+    /// same SPAN OF TIME whatever the device's IO quantum. It used to be a callback COUNT (4), and
+    /// a callback is not a unit of time — the same 4 was ~44 ms on a Mac's ~11 ms quantum and 20 ms
+    /// on iOS, whose session asked for a 5 ms IO buffer. A Wi-Fi delivery stall therefore de-primed
+    /// this ring on every bunching cycle where the identical policy rode it out elsewhere (measured
+    /// on the shared Rust policy: 120 audible gaps per 10 min at a 5 ms quantum against 3 at 8 ms).
+    /// Plant the defect by restoring a fixed count and the quanta below stop agreeing.
+    ///
+    /// Mirrors `deprime_fuse_is_a_duration_not_a_callback_count` in `punktfunk_core::audio`.
+    func testDeprimeFuseIsADurationNotACallbackCount() {
+        let deprimeMS = 60 // AudioRing.deprimeMS / JitterTuning::COREAUDIO.deprime_ms
+        let quanta = [5, 8, 10, 16, 21]
+        var deprimedAt: [Int: Int] = [:]
+        for quantumMS in quanta {
+            let ring = AudioRing(capacity: 48_000 * channels, channels: channels)
+            let want = quantumMS * perMS
+            var scratch = [Float](repeating: 0, count: want)
+            // Prime DEEP: the depth average is seeded with the refill, so `hollow` stays false for
+            // the EWMA's whole settling second and the starvation fuse — not the hollow shortcut —
+            // is what this measures.
+            let big = [Float](repeating: 0.5, count: 80 * perMS)
+            big.withUnsafeBufferPointer { ring.write($0.baseAddress!, count: big.count) }
+            scratch.withUnsafeMutableBufferPointer { ring.read(into: $0.baseAddress!, count: want) }
+            XCTAssertTrue(
+                scratch.contains { $0 != 0 }, "q=\(quantumMS)ms: must play after priming")
+
+            // Starve on a trickle far under what the device takes: every read runs short but still
+            // carries audio, so an all-zero read can only mean the ring gave up and re-primed.
+            let trickle = [Float](repeating: 0.5, count: max(perMS, want / 4))
+            var starvedMS = 0
+            var deprimedAfterMS: Int?
+            for _ in 0..<2_000 {
+                trickle.withUnsafeBufferPointer {
+                    ring.write($0.baseAddress!, count: trickle.count)
+                }
+                let short = ring.bufferedSamples < want
+                scratch.withUnsafeMutableBufferPointer {
+                    ring.read(into: $0.baseAddress!, count: want)
+                }
+                if scratch.allSatisfy({ $0 == 0 }) {
+                    deprimedAfterMS = starvedMS
+                    break
+                }
+                if short { starvedMS += quantumMS }
+            }
+            guard let deprimedAfterMS else {
+                return XCTFail("q=\(quantumMS)ms: never de-primed at all")
+            }
+            deprimedAt[quantumMS] = deprimedAfterMS
+        }
+
+        // Each quantum must give up somewhere around the fuse. The band is wide on purpose: at a
+        // short quantum the HOLLOW shortcut legitimately fires a little before the fuse does (the
+        // target has grown, the depth was never re-banked, so the click is taken early and spent
+        // on a full refill — see `deprimeDebtMS`), and that is the policy working, not drift.
+        for (q, ms) in deprimedAt.sorted(by: { $0.key < $1.key }) {
+            XCTAssertTrue(
+                (deprimeMS - 20...deprimeMS + 25).contains(ms),
+                "q=\(q)ms de-primed after \(ms) ms, nowhere near the \(deprimeMS) ms fuse — "
+                    + "\(deprimedAt.sorted { $0.key < $1.key })")
+        }
+        // ...and THE property: the fuse must not SCALE with the quantum. As a callback count these
+        // same devices de-primed after 20/32/40/64/84 ms — a 4.2x spread, which is exactly why an
+        // iPad crackled where a Mac did not. Measured in time the spread collapses to ~1.3x.
+        let spread = Double(deprimedAt.values.max()!) / Double(deprimedAt.values.min()!)
+        XCTAssertLessThan(
+            spread, 1.6,
+            "de-prime time still scales with the IO quantum (\(String(format: "%.2f", spread))x "
+                + "across \(deprimedAt.sorted { $0.key < $1.key })) — the fuse is a count again")
+    }
+
     /// Mirror of the Rust `target_grows_on_underruns_and_relaxes_when_quiet`, updated for
     /// near-miss growth: the drain's LAST full read (less than a frame left over) already grows
     /// the floor before anything was audible, clustered genuine underruns raise it further, and

clients/cli/Cargo.toml

@@ -21,7 +21,6 @@ path = "src/main.rs"
 pf-client-core = { path = "../../crates/pf-client-core", default-features = false }
 punktfunk-core = { path = "../../crates/punktfunk-core", features = ["quic"] }
 serde_json = "1"
-tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 
 [lints]

clients/cli/src/main.rs

@@ -1389,6 +1389,7 @@ from the config directory for a true factory reset."
 
 #[cfg(any(target_os = "linux", windows))]
 fn main() -> std::process::ExitCode {
+    punktfunk_core::tls::install_default_provider();
     // Logs to stderr; stdout is the machine interface (TSV/JSON), exactly like the session
     // binary's contract.
     tracing_subscriber::fmt()

clients/decky/src/hooks.ts

@@ -215,9 +215,10 @@ export function useHosts() {
   const [views, setViews] = useState<HostView[]>([]);
   const [scanning, setScanning] = useState(false);
   // Why the list is empty, when it is empty for a reason other than an empty LAN. Rendering
-  // either of these as "No hosts yet" would blame the user's network for the plugin's problem:
+  // any of these as "No hosts yet" would blame the user's network for the plugin's problem:
   //   "client-outdated"    — the installed client predates `punktfunk discover`
   //   "client-unavailable" — there is no client installed at all
+  //   "list-failed"        — the refresh itself blew up (backend down, call threw)
   const [problem, setProblem] = useState<string | null>(null);
 
   const refresh = useCallback(async () => {
@@ -236,7 +237,11 @@ export function useHosts() {
       );
       setViews(mergeHosts(s.hosts ?? [], d.hosts ?? []));
     } catch (e) {
-      toaster.toast({ title: "Punktfunk", body: `Couldn't list hosts: ${e}` });
+      // Inline, not a toast: the panel remounts (and refreshes) on every QAM open, so while
+      // the backend is unhappy a toast here nagged on each open. The panel row also sits next
+      // to the Refresh button that retries it, which is where the eyes already are.
+      console.warn("punktfunk: host list refresh failed", e);
+      setProblem("list-failed");
     } finally {
       setScanning(false);
     }
@@ -454,9 +459,12 @@ export async function startStream(
 ): Promise<void> {
   try {
     await launchStream(v.ref, opts);
+    // No success toast: the user just pressed the button that names this host/card, the QAM
+    // closes, and Steam's own launch UI takes over — a toast here fired on EVERY launch and
+    // then sat on top of the starting stream. Failure still toasts (the QAM may already be
+    // closed, so inline error state would go unseen).
     Navigation.CloseSideMenus();
-    toaster.toast({ title: "Punktfunk", body: `Starting ${label ?? "stream"} — ${v.name}` });
   } catch (e) {
-    toaster.toast({ title: "Punktfunk", body: `Launch failed: ${e}` });
+    toaster.toast({ title: "Punktfunk", body: `Launch failed${label ? ` (${label})` : ""}: ${e}` });
   }
 }

clients/decky/src/index.tsx

@@ -46,15 +46,23 @@ import { OsMark } from "./os-icon";
 import { ensureGamepadUiShortcut, launchGamepadUi, recreateShortcuts, stopStream } from "./steam";
 import { TrustSheet } from "./trust";
 
-// Recovery action for "the Punktfunk library entry vanished" — recreates the visible shortcut.
+// Recovery action for "the Punktfunk library entry vanished" — recreates the visible shortcut
+// and sweeps duplicate entries (the piles a boot race used to mint, one per Steam start).
 // Deleting the shortcut (optionally + reinstalling the plugin) leaves a stale appId in Steam's
 // CEF localStorage that self-heal fixes on the next mount, but this gives an in-session button
 // that works even without a reload. Always ends in a toast so the tap has feedback.
 async function recreatePunktfunkShortcut(): Promise<void> {
-  const appId = await recreateShortcuts();
+  const { appId, removedDuplicates } = await recreateShortcuts();
   toaster.toast({
     title: "Punktfunk",
-    body: appId != null ? "Shortcut restored to your library" : "Couldn't create the shortcut",
+    body:
+      appId == null
+        ? "Couldn't create the shortcut"
+        : removedDuplicates > 0
+          ? `Shortcut restored — removed ${removedDuplicates} duplicate ${
+              removedDuplicates === 1 ? "entry" : "entries"
+            }`
+          : "Shortcut restored to your library",
   });
 }
 
@@ -222,12 +230,16 @@ const QamPanel: FC = () => {
               label={
                 problem === "client-unavailable"
                   ? "Punktfunk isn’t installed"
-                  : "Update the Punktfunk client"
+                  : problem === "list-failed"
+                    ? "Couldn’t scan for hosts"
+                    : "Update the Punktfunk client"
               }
               description={
                 problem === "client-unavailable"
                   ? "This panel launches the Punktfunk app, which isn’t on this Deck yet. Install it in Desktop Mode."
-                  : "This client is too old to find hosts on your network. Saved hosts still work."
+                  : problem === "list-failed"
+                    ? "Something went wrong while scanning — Refresh tries again."
+                    : "This client is too old to find hosts on your network. Saved hosts still work."
               }
             />
           </PanelSectionRow>
@@ -313,7 +325,7 @@ const QamPanel: FC = () => {
         <PanelSectionRow>
           <ButtonItem
             layout="below"
-            description="Missing the Punktfunk entry in your library? This puts it back."
+            description="Missing the Punktfunk entry in your library, or seeing several? This puts one back and removes the rest."
             onClick={() => void recreatePunktfunkShortcut()}
           >
             <FaPlus style={{ marginRight: "0.5em" }} />

clients/decky/src/steam.ts

@@ -44,6 +44,7 @@ declare const SteamClient: {
     ): Promise<unknown>;
     RunGame(gameId: string, _unused: string, _i: number, _j: number): void;
     TerminateApp(gameId: string, _b: boolean): void;
+    RemoveShortcut(appId: number): void;
   };
 };
 
@@ -62,29 +63,114 @@ declare const collectionStore:
 // that the reuse path below silently repoints (SetShortcut* on a dead id is a no-op), and the
 // entry never comes back.
 declare const appStore:
-  | { GetAppOverviewByAppID?: (appId: number) => unknown | null }
+  | {
+      GetAppOverviewByAppID?: (appId: number) => unknown | null;
+      allApps?: SteamAppOverviewLike[];
+    }
   | undefined;
 
-/** True if a remembered appId still maps to a live Steam shortcut. When appStore is unavailable
- *  we can't tell, so assume it exists — better to keep reusing than risk a duplicate library
- *  entry from a false "missing". A confident null means the shortcut was deleted → recreate. */
-function shortcutStillExists(appId: number): boolean {
+// The overview surface we read when scanning the library — Steam internals, so everything is
+// optional and accessed defensively.
+interface SteamAppOverviewLike {
+  appid?: number;
+  display_name?: string;
+  BIsShortcut?: () => boolean;
+}
+
+// Steam-injected global whose WaitForServicesInitialized resolves once the client's app
+// services are up (the MoonDeck-verified readiness signal). Services-init alone doesn't
+// guarantee the overview map is populated, so it's paired with the hydration witness below.
+declare const App:
+  | { WaitForServicesInitialized?: () => Promise<boolean> }
+  | undefined;
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+let servicesInitialized: Promise<void> | undefined;
+function waitForServicesInitialized(): Promise<void> {
+  servicesInitialized ??= (async () => {
+    try {
+      if (typeof App !== "undefined" && App?.WaitForServicesInitialized) {
+        await App.WaitForServicesInitialized();
+      }
+    } catch {
+      /* no signal — the hydration witness still gates the verdict */
+    }
+  })();
+  return servicesInitialized;
+}
+
+/** Has appStore demonstrably finished its initial load? An empty `allApps` means "not yet":
+ *  any account that ever had our shortcut has at least one app, so a populated map is the
+ *  witness that a null overview lookup is an ANSWER rather than a not-loaded-yet. null =
+ *  can't tell (missing global, API drift). */
+function appStoreHydrated(): boolean | null {
+  try {
+    if (typeof appStore === "undefined" || !appStore) {
+      return null;
+    }
+    const apps = appStore.allApps;
+    return Array.isArray(apps) ? apps.length > 0 : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One overview lookup: true = live, false = absent, null = can't tell. */
+function queryShortcutAlive(appId: number): boolean | null {
   try {
     // Call it as a METHOD on appStore — NEVER as an extracted function. Its implementation
     // reads the store's own state (`this.m_mapApps`), so `const get = appStore.GetAppOverview…;
     // get(id)` throws on the lost `this`, and the catch below turns that into a permanent
-    // "true". That is not a stale-data bug but a total one: the guard then answers "still
-    // exists" for EVERY appId, so a dangling id is never dropped, the reuse path repoints a
-    // dead shortcut (silent no-ops), and "recreate" reports success having done nothing.
-    // `typeof` first: `appStore` is a Steam-injected global, and a bare reference to a missing
-    // one is a ReferenceError that optional chaining does NOT prevent.
+    // "can't tell". `typeof` first: `appStore` is a Steam-injected global, and a bare
+    // reference to a missing one is a ReferenceError that optional chaining does NOT prevent.
     if (typeof appStore === "undefined" || !appStore?.GetAppOverviewByAppID) {
-      return true; // no way to verify — preserve the reuse path
+      return null;
     }
     return appStore.GetAppOverviewByAppID(appId) != null;
   } catch {
+    return null;
+  }
+}
+
+// How long to wait for the app store before conceding liveness can't be verified. A Deck boot
+// hydrates the store within a few seconds of plugin mount; 30 s is comfortably past any real
+// boot, and the wait only burns on the absent/unverifiable paths — a live overview answers on
+// the first query. Overview registration can trail the bulk hydration by a beat, so a
+// "hydrated but absent" verdict gets one grace recheck before it counts as deleted.
+const STORE_WAIT_MS = 30_000;
+const STORE_POLL_MS = 1_000;
+const STORE_GRACE_MS = 2_000;
+
+/** True if a remembered appId still maps to a live Steam shortcut.
+ *
+ *  The dangerous verdict is FALSE — it sends the caller to AddShortcut, so a wrong "deleted"
+ *  mints a duplicate library entry. And a bare null-overview check gets it wrong on EVERY
+ *  boot: the plugin mounts while Steam is still starting up, before appStore has registered
+ *  its overviews, so the remembered (perfectly live) appId looks up as null and each boot
+ *  added another visible "Punktfunk" — the field-reported duplicate pile. Absent is therefore
+ *  only believed once the store is demonstrably hydrated; if that can't be established within
+ *  budget the answer is true, because a false "alive" merely no-ops Set-calls until the next
+ *  ask (and the recreate button re-asks when the store IS ready) while a false "dead"
+ *  duplicates forever. */
+async function shortcutStillExists(appId: number): Promise<boolean> {
+  if (queryShortcutAlive(appId) === true) {
     return true;
   }
+  // Race the init signal against the same budget the poll loop gets: a signal that never
+  // resolves must not wedge the guard (the single-flight ensure would stay occupied forever).
+  await Promise.race([waitForServicesInitialized(), sleep(STORE_WAIT_MS)]);
+  for (let waited = 0; waited < STORE_WAIT_MS; waited += STORE_POLL_MS) {
+    if (queryShortcutAlive(appId) === true) {
+      return true;
+    }
+    if (appStoreHydrated() === true) {
+      await sleep(STORE_GRACE_MS);
+      return queryShortcutAlive(appId) !== false; // null = unverifiable → reuse
+    }
+    await sleep(STORE_POLL_MS);
+  }
+  return true; // store never became inspectable — reusing beats duplicating
 }
 
 /** Set a shortcut's library visibility (best-effort, deferred — the overview registers a moment
@@ -156,6 +242,67 @@ async function applyArtwork(appId: number, isRetry = false): Promise<void> {
 // share it so Steam keys them to the SAME controller config (configset key = lowercase name).
 const SHORTCUT_NAME = "Punktfunk";
 
+/** Find an existing "Punktfunk" shortcut to ADOPT instead of minting a new library entry — the
+ *  healing path for a lost/wiped appId, and for the duplicate piles the boot race left behind
+ *  in the field: rebind one of the existing entries to the role rather than adding an N+1th.
+ *  (The caller rewrites exe/dir/opts/visibility anyway, so any of them serves.) Only overviews
+ *  Steam itself says are shortcuts qualify, and the other role's remembered id is excluded so
+ *  the two roles never collapse onto one shortcut. */
+function findAdoptableShortcut(excludeAppId: number | null): number | null {
+  try {
+    if (typeof appStore === "undefined" || !Array.isArray(appStore?.allApps)) {
+      return null;
+    }
+    for (const app of appStore.allApps) {
+      if (
+        app?.display_name === SHORTCUT_NAME &&
+        typeof app.appid === "number" &&
+        app.appid !== excludeAppId &&
+        app.BIsShortcut?.() === true
+      ) {
+        return app.appid;
+      }
+    }
+  } catch {
+    /* Steam internals drifted — AddShortcut is the fallback */
+  }
+  return null;
+}
+
+/** Remove every "Punktfunk" shortcut beyond the two remembered role ids — the cleanup for
+ *  piles already minted by the boot race. Deliberately reachable ONLY from the user-pressed
+ *  recreate button, never from mount: automatic library deletion at boot is a bigger hazard
+ *  than the mess it would tidy. Returns how many entries were removed. */
+function removeDuplicateShortcuts(): number {
+  let removed = 0;
+  try {
+    if (typeof appStore === "undefined" || !Array.isArray(appStore?.allApps)) {
+      return 0;
+    }
+    const keep = [recall(STORAGE_KEY_STREAM), recall(STORAGE_KEY_UI)];
+    // Snapshot before removing — RemoveShortcut mutates the store's list under the iteration.
+    const surplus = appStore.allApps.filter(
+      (app) =>
+        app?.display_name === SHORTCUT_NAME &&
+        typeof app.appid === "number" &&
+        !keep.includes(app.appid) &&
+        app.BIsShortcut?.() === true,
+    );
+    for (const app of surplus) {
+      SteamClient.Apps.RemoveShortcut(app.appid as number);
+      try {
+        localStorage.removeItem(artKey(app.appid as number));
+      } catch {
+        /* ignore */
+      }
+      removed++;
+    }
+  } catch (e) {
+    console.warn("punktfunk: duplicate-shortcut sweep incomplete", e);
+  }
+  return removed;
+}
+
 // The shortcut's exe is /bin/sh, NOT the script itself: Decky extracts plugin zips without
 // preserving the exec bit, and ~/homebrew/plugins is root-owned so the unprivileged plugin
 // backend can't chmod it back on. Passing the script as an argument to the always-executable
@@ -223,7 +370,7 @@ async function ensureControllerConfig(): Promise<void> {
  * the current runner path. Reuses/repoints the remembered shortcut (the plugin dir can change
  * across reinstalls, and pre-two-shortcut installs had this one visible).
  */
-async function ensureStreamShortcut(): Promise<{ appId: number; runner: string; clientBin: string }> {
+async function doEnsureStreamShortcut(): Promise<{ appId: number; runner: string; clientBin: string }> {
   const info = await runnerInfo();
   if (!info.exists) {
     throw new Error(`launch wrapper missing at ${info.runner}`);
@@ -232,25 +379,38 @@ async function ensureStreamShortcut(): Promise<{ appId: number; runner: string;
   void ensureControllerConfig(); // fire-and-forget — never blocks the launch
 
   // Reuse the remembered shortcut only if it still exists — a stale appId (shortcut deleted, key
-  // outlived it across a reinstall) must fall through to AddShortcut, not be silently repointed.
+  // outlived it across a reinstall) must fall through, not be silently repointed. On a lost id,
+  // ADOPT an existing same-named shortcut before AddShortcut so a wiped key never duplicates.
   const remembered = recall(STORAGE_KEY_STREAM);
-  if (remembered != null && shortcutStillExists(remembered)) {
-    SteamClient.Apps.SetShortcutExe(remembered, SHELL);
-    SteamClient.Apps.SetShortcutStartDir(remembered, startDir);
-    SteamClient.Apps.SetShortcutName(remembered, SHORTCUT_NAME);
-    setShortcutHidden(remembered, true); // migrate pre-two-shortcut installs (were visible)
-    void applyArtwork(remembered);
-    return { appId: remembered, runner: info.runner, clientBin: info.client_bin ?? "" };
+  let appId =
+    remembered != null && (await shortcutStillExists(remembered)) ? remembered : null;
+  if (appId == null) {
+    appId =
+      findAdoptableShortcut(recall(STORAGE_KEY_UI)) ??
+      (await SteamClient.Apps.AddShortcut(SHORTCUT_NAME, SHELL, startDir, ""));
+    remember(STORAGE_KEY_STREAM, appId);
   }
-
-  const appId = await SteamClient.Apps.AddShortcut(SHORTCUT_NAME, SHELL, startDir, "");
+  SteamClient.Apps.SetShortcutExe(appId, SHELL);
+  SteamClient.Apps.SetShortcutStartDir(appId, startDir);
   SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
-  setShortcutHidden(appId, true);
+  setShortcutHidden(appId, true); // also migrates pre-two-shortcut installs (were visible)
   void applyArtwork(appId);
-  remember(STORAGE_KEY_STREAM, appId);
   return { appId, runner: info.runner, clientBin: info.client_bin ?? "" };
 }
 
+// Concurrent ensure calls share one run per role — two ensures racing past the liveness check
+// would each AddShortcut, which is exactly the duplicate class this file exists to prevent (and
+// the store-readiness wait makes the window real: mount's fire-and-forget ensure can be mid-wait
+// when a QAM press arrives). Sequential calls still re-run, so per-launch repointing is kept.
+let streamEnsureInFlight: Promise<{ appId: number; runner: string; clientBin: string }> | null =
+  null;
+function ensureStreamShortcut(): Promise<{ appId: number; runner: string; clientBin: string }> {
+  streamEnsureInFlight ??= doEnsureStreamShortcut().finally(() => {
+    streamEnsureInFlight = null;
+  });
+  return streamEnsureInFlight;
+}
+
 /**
  * Ensure the GAMEPAD-UI shortcut (visible, stateless) — the library-facing "Punktfunk" entry
  * that opens the client's console home (bare `--browse`: host picker + pairing + settings).
@@ -258,7 +418,7 @@ async function ensureStreamShortcut(): Promise<{ appId: number; runner: string;
  * kept VISIBLE. Idempotent — call on plugin mount so the library entry always exists and stays
  * repointed to the current plugin dir. Best-effort: returns null on any failure.
  */
-export async function ensureGamepadUiShortcut(): Promise<number | null> {
+async function doEnsureGamepadUiShortcut(): Promise<number | null> {
   try {
     const info = await runnerInfo();
     if (!info.exists) {
@@ -275,18 +435,20 @@ export async function ensureGamepadUiShortcut(): Promise<number | null> {
     const launchOpts = `${clientBin}PF_BROWSE=1 %command% "${info.runner}"`;
 
     // Reuse the remembered entry only if it still exists; a stale appId (deleted shortcut whose
-    // localStorage key survived a plugin reinstall) falls through to AddShortcut so the visible
-    // library entry actually comes back instead of repointing a dead id.
+    // localStorage key survived a plugin reinstall) falls through so the visible library entry
+    // actually comes back instead of repointing a dead id. On a lost id, ADOPT an existing
+    // same-named shortcut (a boot-race duplicate, or the entry whose key was wiped) before
+    // AddShortcut — creation is the last resort, never the response to a mere lookup miss.
     let appId = recall(STORAGE_KEY_UI);
-    if (appId != null && shortcutStillExists(appId)) {
-      SteamClient.Apps.SetShortcutExe(appId, SHELL);
-      SteamClient.Apps.SetShortcutStartDir(appId, startDir);
-      SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
-    } else {
-      appId = await SteamClient.Apps.AddShortcut(SHORTCUT_NAME, SHELL, startDir, "");
-      SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
+    if (appId == null || !(await shortcutStillExists(appId))) {
+      appId =
+        findAdoptableShortcut(recall(STORAGE_KEY_STREAM)) ??
+        (await SteamClient.Apps.AddShortcut(SHORTCUT_NAME, SHELL, startDir, ""));
       remember(STORAGE_KEY_UI, appId);
     }
+    SteamClient.Apps.SetShortcutExe(appId, SHELL);
+    SteamClient.Apps.SetShortcutStartDir(appId, startDir);
+    SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
     SteamClient.Apps.SetAppLaunchOptions(appId, launchOpts);
     setShortcutHidden(appId, false); // the visible library entry
     void applyArtwork(appId);
@@ -297,18 +459,32 @@ export async function ensureGamepadUiShortcut(): Promise<number | null> {
   }
 }
 
+// Same single-flight rule as the stream role (see ensureStreamShortcut).
+let uiEnsureInFlight: Promise<number | null> | null = null;
+export function ensureGamepadUiShortcut(): Promise<number | null> {
+  uiEnsureInFlight ??= doEnsureGamepadUiShortcut().finally(() => {
+    uiEnsureInFlight = null;
+  });
+  return uiEnsureInFlight;
+}
+
 /**
  * Force the visible "Punktfunk" library entry back into existence — the recovery button for
  * "my shortcut disappeared". Drops any remembered appId that no longer maps to a live shortcut
  * (so it can't shadow a fresh AddShortcut), then re-ensures. Safe to press anytime: a shortcut
  * that still exists is left in place (no duplicate); a missing one is recreated. Covers the case
  * self-heal-on-mount can't — deleting the shortcut WITHOUT reinstalling (no mount → no ensure).
- * Returns the (new or existing) visible appId, or null on failure.
+ * Also sweeps surplus "Punktfunk" entries (the piles the boot race minted before the store-
+ * readiness gate existed) — the button is where that cleanup lives, never mount. Returns the
+ * (new or existing) visible appId (null on failure) plus how many duplicates were removed.
  */
-export async function recreateShortcuts(): Promise<number | null> {
+export async function recreateShortcuts(): Promise<{
+  appId: number | null;
+  removedDuplicates: number;
+}> {
   for (const key of [STORAGE_KEY_STREAM, STORAGE_KEY_UI]) {
     const id = recall(key);
-    if (id != null && !shortcutStillExists(id)) {
+    if (id != null && !(await shortcutStillExists(id))) {
       try {
         localStorage.removeItem(artKey(id)); // stale art marker for the dead appId
         localStorage.removeItem(key);
@@ -317,8 +493,13 @@ export async function recreateShortcuts(): Promise<number | null> {
       }
     }
   }
-  // Recreate the visible entry now; the hidden stream shortcut re-registers lazily on next launch.
-  return ensureGamepadUiShortcut();
+  // Recreate the visible entry now; the hidden stream shortcut re-registers lazily on next
+  // launch. Sweep AFTER the ensure so the remembered ids are fresh — and only when the ensure
+  // succeeded: on a failed ensure the "keep" list can't be trusted, and deleting candidates a
+  // later ensure would adopt could leave the library with no entry at all.
+  const appId = await ensureGamepadUiShortcut();
+  const removedDuplicates = appId != null ? removeDuplicateShortcuts() : 0;
+  return { appId, removedDuplicates };
 }
 
 /** Launch the stateless gamepad-UI shortcut (console home) from the plugin, e.g. a QAM button. */

clients/linux/src/app.rs

@@ -870,6 +870,23 @@ fn deliver_deep_link(url: String) {
     }
 }
 
+/// The crate's one runtime env mutation, isolated so `main.rs`'s `deny(unsafe_code)` covers
+/// everything else and the exemption is a named function rather than a whole call site.
+#[allow(unsafe_code)]
+fn clear_steam_sdl_device_filter() {
+    for var in [
+        "SDL_GAMECONTROLLER_IGNORE_DEVICES",
+        "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT",
+    ] {
+        if let Ok(v) = std::env::var(var) {
+            tracing::info!(var, value = %v, "clearing Steam's SDL device filter");
+            // SAFETY: called at the top of `run()`, before GTK init or any other thread
+            // exists in this process — nothing reads the environment concurrently.
+            unsafe { std::env::remove_var(var) };
+        }
+    }
+}
+
 pub fn run() -> glib::ExitCode {
     tracing_subscriber::fmt()
         .with_env_filter(
@@ -879,15 +896,7 @@ pub fn run() -> glib::ExitCode {
     // Steam launches its shortcuts with SDL_GAMECONTROLLER_IGNORE_DEVICES naming every
     // physical pad Steam Input has virtualized; the Settings controller list needs the
     // real devices (same rationale as the session binary).
-    for var in [
-        "SDL_GAMECONTROLLER_IGNORE_DEVICES",
-        "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT",
-    ] {
-        if let Ok(v) = std::env::var(var) {
-            tracing::info!(var, value = %v, "clearing Steam's SDL device filter");
-            std::env::remove_var(var);
-        }
-    }
+    clear_steam_sdl_device_filter();
     // Headless paths (no GTK window).
     if let Some(pin) = crate::cli::arg_value("--pair") {
         return crate::cli::headless_pair(&pin);

clients/linux/src/main.rs

@@ -3,7 +3,10 @@
 //! Hosts, pairing/trust, settings, and the desktop library page; every stream (and the
 //! console game library) runs in the spawned `punktfunk-session` Vulkan binary — the
 //! shell never touches video (punktfunk-planning `linux-client-rearchitecture.md`).
-#![forbid(unsafe_code)]
+// `deny`, not `forbid`, since edition 2024: clearing Steam's SDL device filter and the spawn
+// test's `HOME` scoping mutate the process env, which is now an unsafe call. Both carry a named
+// `#[allow(unsafe_code)]` with the proof at the site; everything else stays compiler-refused.
+#![deny(unsafe_code)]
 
 // The UI-agnostic plumbing lives in `pf-client-core`, shared with the session binary.
 // Root re-exports keep every `crate::trust`-style path resolving unchanged.
@@ -30,6 +33,7 @@ mod ui_trust;
 
 #[cfg(target_os = "linux")]
 fn main() -> gtk::glib::ExitCode {
+    punktfunk_core::tls::install_default_provider();
     app::run()
 }
 

clients/linux/src/spawn.rs

@@ -128,6 +128,8 @@ mod tests {
     /// that is merely capped. One test, one `HOME` — the stores are read from it, so this
     /// deliberately does not split into several that would race over the same env var.
     #[test]
+    // The crate's one test env mutation (the `HOME` scoping below) — see main.rs's deny note.
+    #[allow(unsafe_code)]
     fn the_plan_carries_resolved_settings_not_defaults() {
         use pf_client_core::profiles::{ProfilesFile, SettingsOverlay, StreamProfile};
         use pf_client_core::trust::{KnownHost, KnownHosts, Settings};
@@ -135,7 +137,10 @@ mod tests {
         let home = std::env::temp_dir().join(format!("pf-spawn-test-{}", std::process::id()));
         let cfg = home.join(".config/punktfunk");
         std::fs::create_dir_all(&cfg).unwrap();
-        std::env::set_var("HOME", &home);
+        // SAFETY: the only env-mutating test in this binary (see the doc above — one test, one
+        // `HOME`, deliberately not split). Parallel tests may `getenv` concurrently; glibc keeps
+        // replaced environ storage alive, and every reader tolerates either value.
+        unsafe { std::env::set_var("HOME", &home) };
 
         // A device whose owner has set a bitrate, and a host bound to a profile that raises it
         // further — the two layers the spec has to carry.

clients/probe/Cargo.toml

@@ -10,14 +10,21 @@ repository.workspace = true
 
 [dependencies]
 punktfunk-core = { path = "../../crates/punktfunk-core", features = ["quic"] }
-quinn = "0.11"
+# Backend features mirror punktfunk-core's quinn exactly (see its Cargo.toml).
+quinn = { version = "0.11", default-features = false, features = [
+    "log",
+    "platform-verifier",
+    "runtime-tokio",
+    "rustls-aws-lc-rs",
+    "bloom",
+] }
 tokio = { version = "1", features = ["rt-multi-thread", "net", "time", "macros"] }
 anyhow = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 # LAN host discovery (`--discover`): browse the native `_punktfunk._udp` mDNS service the host
 # advertises (same crate/version the host advertises with).
-mdns-sd = "0.20"
+mdns-sd = "0.21"
 # Opus: multistream DECODE of the host's audio plane (the surround validator) + `--mic-test`'s
 # encoder. libopus is already in the graph via `punktfunk-core`'s quic feature; this exposes the
 # name directly. Cross-platform (cmake-vendored), so the probe builds + validates everywhere.

clients/session/Cargo.toml

@@ -37,7 +37,6 @@ pf-client-core = { path = "../../crates/pf-client-core", default-features = fals
 punktfunk-core = { path = "../../crates/punktfunk-core", features = ["quic"] }
 # The fake-library dev hook (`PUNKTFUNK_FAKE_LIBRARY`, browse mode) parses GameEntry JSON.
 serde_json = { version = "1", optional = true }
-anyhow = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 

clients/session/src/console.rs

@@ -13,7 +13,7 @@
 //! (portrait paths starting with `/` load from disk), the GPU-only dev path.
 
 use crate::session_main::{
-    arg_flag, arg_value, fullscreen_mode, parse_host_port, session_params, window_pos,
+    arg_flag, arg_value, fullscreen_mode, parse_host_port, session_params, stats_tier, window_pos,
 };
 use pf_client_core::gamepad::is_steam_deck;
 use pf_client_core::{discovery, library, trust, wol};
@@ -141,11 +141,18 @@ pub fn run(target: Option<&str>) -> u8 {
     let json_status = arg_flag("--json-status");
     let settings_at_start = trust::Settings::load();
     // The console's window and its input models are built ONCE, from the global defaults, and
-    // live across every launch — so the presentation-tier fields below (stats tier, touch and
-    // mouse model, shortcut inhibit, match-window, render scale) are latched here and a per-host
-    // profile cannot move them in this mode. Everything the HOST is told (mode, bitrate, codec,
-    // audio, pad) is re-resolved per launch and does honor the binding. Closing that gap means
-    // rebuilding the presenter's models per launch — profiles P4 territory, not P0.
+    // live across every launch — so the presentation-tier fields below (touch and mouse model,
+    // shortcut inhibit, match-window, render scale) are latched here and a per-host profile
+    // cannot move them in this mode. Everything the HOST is told (mode, bitrate, codec, audio,
+    // pad) is re-resolved per launch and does honor the binding. Closing the rest of that gap
+    // means rebuilding the presenter's models per launch — profiles P4 territory, not P0.
+    //
+    // ⚠ The STATS TIER used to be latched here too, and that was a bug people hit: the console's
+    // own settings screen writes the tier to the file and redraws its row, so the choice looked
+    // taken while every stream kept the tier the process started on — "no matter what I select
+    // the overlay is stuck on Detailed", cured only by restarting the app. It now rides
+    // `SessionParams` per launch (`stats_verbosity`), so the value below only seeds the loop
+    // until the first stream. Anything else moved off this snapshot has to travel the same way.
     let latched_mouse = settings_at_start.mouse_mode();
 
     // Request-access hand-off: the launch handler stamps this when it starts a delegated-approval
@@ -162,11 +169,8 @@ pub fn run(target: Option<&str>) -> u8 {
         ),
         fullscreen: fullscreen_mode(),
         window_pos: window_pos(),
-        // `--stats` forces the overlay visible without demoting a richer chosen tier.
-        stats_verbosity: match settings_at_start.stats_verbosity() {
-            trust::StatsVerbosity::Off if arg_flag("--stats") => trust::StatsVerbosity::Normal,
-            v => v,
-        },
+        // Seeds the loop only — every launch carries its own freshly resolved tier.
+        stats_verbosity: stats_tier(&settings_at_start),
         touch_mode: settings_at_start.touch_mode(),
         mouse_mode: settings_at_start.mouse_mode(),
         invert_scroll: settings_at_start.invert_scroll,

clients/session/src/main.rs

@@ -13,7 +13,13 @@
 //! the first presented frame, `stats:` lines per 1 s window, one `{"error": …}` /
 //! `{"ended": …}` JSON line on the way out. Logs go to stderr. Exit codes: 0 clean end,
 //! 2 connect failed, 3 trust rejected / pairing required, 4 presenter init failed.
-#![forbid(unsafe_code)]
+// `deny`, not `forbid`: edition 2024 makes the std process-environment mutators unsafe
+// (WP20 — the env-mutation class made visible; named-API mentions here would count against
+// the unsafe-hygiene gate C baseline, which tracks this file's real call sites), and this
+// bin's three single-threaded-startup env writes carry documented SAFETY comments under
+// localized `#[allow(unsafe_code)]` (the pf-update idiom). A `forbid` cannot be overridden
+// at those sites and refuses the file.
+#![deny(unsafe_code)]
 
 #[cfg(all(any(target_os = "linux", windows), feature = "ui"))]
 mod console;
@@ -116,6 +122,28 @@ mod session_main {
         std::env::args().any(|a| a == flag)
     }
 
+    /// The stats-overlay tier a session starts on: the resolved setting, except that
+    /// `--stats` (tooling/debug runs) forces the overlay VISIBLE without demoting an
+    /// explicitly chosen richer tier.
+    ///
+    /// One helper because three callers need the identical rule — both run modes' presenter
+    /// options and the per-launch [`session_params`] — and a fourth reading of it would be
+    /// the bug this is here to prevent.
+    pub(crate) fn stats_tier(settings: &trust::Settings) -> trust::StatsVerbosity {
+        stats_tier_with(settings.stats_verbosity(), arg_flag("--stats"))
+    }
+
+    /// [`stats_tier`]'s rule, with argv lifted out so it is testable.
+    pub(crate) fn stats_tier_with(
+        chosen: trust::StatsVerbosity,
+        stats_flag: bool,
+    ) -> trust::StatsVerbosity {
+        match chosen {
+            trust::StatsVerbosity::Off if stats_flag => trust::StatsVerbosity::Normal,
+            v => v,
+        }
+    }
+
     /// Running under Gaming Mode (a Deck, or any gamescope session): the environment
     /// where the local Steam UI owns the physical Steam/QAM buttons — the system-button
     /// "auto" policy keys off this.
@@ -420,6 +448,12 @@ mod session_main {
             connect_timeout: connect_timeout(),
             force_software,
             profile,
+            // Presentation-tier, carried per launch rather than read once by the run loop:
+            // the console streams many sessions through ONE loop, so this is the only way a
+            // tier the user picked between streams (or one a host's profile carries) reaches
+            // the overlay before the app is restarted. Single mode passes the same value its
+            // presenter options already hold, so it changes nothing there.
+            stats_verbosity: stats_tier(settings),
             // Phase-locked capture (design/phase-locked-capture.md, Apple/Android parity):
             // advertised only when the presenter has real on-glass latch stamps
             // (VK_KHR_present_wait) — without them there is no latch grid to report. The
@@ -505,12 +539,18 @@ mod session_main {
     /// initialises, so a call placed after them leaves the triage tool describing a device
     /// that cannot decode while the streaming path decodes on it.
     #[cfg(target_os = "linux")]
+    #[allow(unsafe_code)] // the two SAFETY-commented single-threaded-startup env writes below
     fn enable_radv_video_decode() {
         const TOKEN: &str = "video_decode";
         match std::env::var("RADV_PERFTEST") {
             Ok(v) if v.split(',').any(|t| t == TOKEN) => return,
-            Ok(v) if !v.is_empty() => std::env::set_var("RADV_PERFTEST", format!("{v},{TOKEN}")),
-            _ => std::env::set_var("RADV_PERFTEST", TOKEN),
+            // SAFETY: called at the very top of `run()`, before this process creates any
+            // thread — the Vulkan loader, SDL, and the session runtime all start later.
+            Ok(v) if !v.is_empty() => unsafe {
+                std::env::set_var("RADV_PERFTEST", format!("{v},{TOKEN}"))
+            },
+            // SAFETY: as above — single-threaded startup.
+            _ => unsafe { std::env::set_var("RADV_PERFTEST", TOKEN) },
         }
         tracing::info!(
             radv_perftest = %std::env::var("RADV_PERFTEST").unwrap_or_default(),
@@ -804,7 +844,13 @@ mod session_main {
                 ("PUNKTFUNK_AUDIO_SOURCE", &s.mic_device),
             ] {
                 if std::env::var_os(var).is_none() && !value.is_empty() {
-                    std::env::set_var(var, value);
+                    // SAFETY: still the single-threaded startup stretch of `run()` — the
+                    // early-exit probes above return out of the process, and everything that
+                    // spawns threads (the session, the console, SDL) only starts below.
+                    #[allow(unsafe_code)]
+                    unsafe {
+                        std::env::set_var(var, value)
+                    };
                 }
             }
         }
@@ -818,7 +864,12 @@ mod session_main {
         ] {
             if let Ok(v) = std::env::var(var) {
                 tracing::info!(var, value = %v, "clearing Steam's SDL device filter");
-                std::env::remove_var(var);
+                // SAFETY: as the settings block above — single-threaded startup, before SDL
+                // (the reader of these variables) or any other thread exists.
+                #[allow(unsafe_code)]
+                unsafe {
+                    std::env::remove_var(var)
+                };
             }
         }
 
@@ -926,12 +977,7 @@ mod session_main {
             window_title: format!("Punktfunk · {title}"),
             fullscreen,
             window_pos: window_pos(),
-            // `--stats` forces the overlay visible (tooling/debug runs) without
-            // demoting an explicitly chosen richer tier.
-            stats_verbosity: match settings.stats_verbosity() {
-                trust::StatsVerbosity::Off if arg_flag("--stats") => trust::StatsVerbosity::Normal,
-                v => v,
-            },
+            stats_verbosity: stats_tier(&settings),
             touch_mode: settings.touch_mode(),
             mouse_mode: settings.mouse_mode(),
             invert_scroll: settings.invert_scroll,
@@ -1000,6 +1046,37 @@ mod session_main {
             }
         }
     }
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+        use trust::StatsVerbosity as V;
+
+        /// `--stats` is a floor, never a ceiling: it lifts Off to Normal and leaves every
+        /// richer chosen tier alone. Both run modes' presenter options AND the per-launch
+        /// params read this one rule, which is the point of having it.
+        #[test]
+        fn the_stats_flag_lifts_off_and_demotes_nothing() {
+            assert_eq!(stats_tier_with(V::Off, true), V::Normal);
+            assert_eq!(stats_tier_with(V::Off, false), V::Off);
+            for chosen in [V::Compact, V::Normal, V::Detailed] {
+                assert_eq!(stats_tier_with(chosen, true), chosen);
+                assert_eq!(stats_tier_with(chosen, false), chosen);
+            }
+        }
+
+        /// The console reads the file ONCE for its window, so a tier changed between streams
+        /// can only reach the overlay by riding the launch. Guards the wiring the field exists
+        /// for: whatever settings a launch resolved is what the params carry.
+        #[test]
+        fn a_launch_carries_the_tier_its_settings_resolved() {
+            let mut s = trust::Settings::default();
+            for chosen in [V::Off, V::Compact, V::Normal, V::Detailed] {
+                s.set_stats_verbosity(chosen);
+                assert_eq!(stats_tier_with(s.stats_verbosity(), false), chosen);
+            }
+        }
+    }
 }
 
 #[cfg(any(target_os = "linux", windows))]