feat(host,console): the host knew about every one of these faults and had no way to say so

Implements design/web-console-diagnostics.md, WP1-WP3 (the v1). WP4 (live checks + SSE)
and WP5 (instant helpers) stay deferred, as that plan sequences them.

The `.181` incident is the type specimen. `preflight_takeover_privilege()` is the most
careful probe in the repo — four applicability gates, and it even separates user-database
membership from the running process's supplementary groups — and it spends all of that
care on ONE WARN log line. A console-driven update never shows scriptlet stderr, so the
operator's only symptom was a black screen on every connect. The class of bug is "the host
knows, and the person operating it has no way to find out".

Host
----
`diagnostics.rs` holds the `HostCheck` model and a process-global registry (probes in,
cached verdicts out; `POST /refresh` re-runs them). `inapplicable` is a first-class status
rather than an absent row, so the page can answer "why isn't this check relevant here?"
instead of silently hiding it. `diagnostics/catalog.rs` maps verdicts to wire checks and
owns every user-visible string.

`GET /api/v1/diagnostics` + `POST /api/v1/diagnostics/refresh` are **admin lane only**.
Neither allowlist in `auth.rs` is touched: both are opt-in, and these verdicts carry the
host user's name, its group layout and device-node state. The route-classification test
gets both rows so that stays a reviewed decision rather than a default.

Probes stay in their owning crates and export plain verdict enums; the host does the
mapping. No reverse dependency — `pf-inject`/`pf-vdisplay` never learn about host types.

* `pf-vdisplay`: `preflight_takeover_privilege()` now logs FROM
  `takeover_privilege_verdict()`. The WARN line is unchanged, deliberately: headless
  operators read logs, not consoles, and this moves where the verdict GOES, not what it
  says.
* `pf-inject`: `uinput_probe()` keeps the errno that `pen_supported()` throws away, so
  "you are not in the input group" (EACCES) and "the module was never installed" (ENOENT)
  stop looking identical — they need opposite remedies. `vhci_probe()` reports device
  facts only (module present, node writable by this process); who to blame is the host's
  question, because only the user database can answer it.

Two distinctions the catalog refuses to collapse:

1. **User-database membership vs this process's groups.** `usermod -aG` satisfies the
   first immediately and the second not until the next login. Collapsing them produces
   the single most maddening support state there is — "I already added myself!" — which
   nothing in the logs distinguishes today. It now gets its own remedy: log out, no
   command to run.
2. **`usermod` does not stick on an atomic OS.** On the Universal Blue images the remedy
   is `ujust add-user-to-input-group`. Matched on the OS chain's LEAF, never on the
   `fedora` family token: plain Fedora Workstation is mutable and does want `usermod`.

Console
-------
The dashboard gets an `AttentionCard` that renders nothing at all on a healthy host
(`ConflictsCard`'s rule), shows at most the 3 worst checks, and links onward rather than
explaining — a dashboard that starts teaching remedies stops being a dashboard.

Its badge says the **severity**, not the status. The badge's colour already encodes
severity, so a badge reading "Failing" on both a red and an amber row leaves the
difference between them carried by colour alone — which is the thing the `pin_pending`
precedent exists to prevent. Caught on glass, not in the diff.

The Logs page becomes Troubleshooting: checks above the log stream, because when the
checks are green and something is still broken the log is the natural next step. The
ROUTE stays `/logs` — bookmarks and deep links outlive a label. `LogsCard` grows a
heading, since the page title no longer names it.

A check id this console has never heard of still renders, from the host's English
`summary`/`impact`/`remedy.text`. That is what makes console N paired with host N+1
survivable, and it is enforced as a test rather than left as a convention. The situational
prose is deliberately NOT duplicated into the message catalogues: one check has many
shapes (the vhci one alone has four distinct causes), and copying ~20 sentences into a
package that versions independently of the one that generates them is the very drift this
design set out to avoid. The console localizes the check NAMES and all chrome; when the
host sends a shape discriminator alongside `id`, localized prose can key off it.

Verification
------------
`cargo clippy -D warnings` and `cargo fmt --all --check` clean on Linux; 12 diagnostics
unit tests and 48 mgmt handler tests green, including the openapi drift test —
`api/openapi.json` and the ungated `docs-site/public/openapi.json` copy are both
regenerated. Web: build, lint, `bun test server/`, storybook, and the new stories shot in
both themes with the theme flip verified rather than assumed.

Not yet on glass: the real `.181` box (all three vhci states), `.138` for the
unpackaged-helper path, and the old-console/new-host pairing legs.

.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-promote.yml

@@ -6,7 +6,7 @@
 # android.yml would mean an `if:` on all ten of its build steps.
 #
 # What it is for:
-#   * promote a tested build up a track (alpha -> production)
+#   * promote a tested build up a track (beta -> production)
 #   * roll production back by re-pointing it at an older versionCode (to_track=production,
 #     version_code=<the good one>, from_track blank)
 #   * halt a rollout (status=halted)
@@ -36,7 +36,7 @@ on:
       from_track:
         description: 'track to verify it is on, then clear (blank = touch nothing else)'
         required: false
-        default: 'alpha'
+        default: 'beta'
       notes_tag:
         description: "tag whose docs/releases/whatsnew/<tag>.txt to attach, e.g. v0.23.0 (blank = none)"
         required: false

.gitea/workflows/android.yml

@@ -36,8 +36,13 @@ on:
       - '.gitea/workflows/android.yml'
     # Single project version: a `vX.Y.Z` tag is THE release (publishes to Play `production` at
     # 100% + attaches the .aab/.apk to the unified Gitea Release). A main push is canary
-    # (Play `internal`). Production access was granted 2026-08-01; before that a tag could only
-    # reach `alpha` and someone had to promote it by hand in the Console.
+    # (Play `beta` = open testing: public opt-in, no tester list — but unlike the previous
+    # `internal` target, every canary now passes Google review before testers see it, so a
+    # canary lands in hours/days, not minutes). The same canary versionCode is also assigned
+    # to `alpha` (closed testing) in the same Play edit, so the pre-production-access closed
+    # testers keep receiving builds without re-opting-in. Production access was granted
+    # 2026-08-01; before that a tag could only reach `alpha` and someone had to promote it
+    # by hand in the Console.
     tags: ['v*']
   pull_request:
     paths:
@@ -51,7 +56,21 @@ on:
       - 'rust-toolchain.toml'
       - 'scripts/ci/**'
       - '.gitea/workflows/android.yml'
+  # Manual runs are BUILD-ONLY by default. The escape hatch below exists because a push run can
+  # go missing entirely: merge two PRs seconds apart and Gitea attributes the window's runs to the
+  # newer head, so the older merge sha gets no run at all — its android change then sits on main
+  # having never been built, let alone published (2026-08-14: `1e5dca4c`, PR #235, lost its run to
+  # `b5cace3a` 12 s later). Re-running the PR run does NOT recover it: a re-run replays the original
+  # `pull_request` event, so every gate below stays false. Only a dispatch with publish=true can
+  # ship that commit without inventing a filler push.
   workflow_dispatch:
+    inputs:
+      publish:
+        # String, not a boolean: matches apple.yml's `testflight` input, which is the form proven
+        # to evaluate correctly on this Gitea. Compared as `inputs.publish == 'true'` below.
+        description: "Also publish this build (registry + Google Play). main -> beta+alpha, vX.Y.Z tag -> production at 100%. Default false: a stray click must not reach testers."
+        required: false
+        default: "false"
 
 # Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
 # unbound). The NDK clang targets get their own key universes automatically (keys embed
@@ -63,6 +82,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"
@@ -85,8 +113,9 @@ jobs:
       # store listing. Failing here also means a missing file cannot leave a half-published
       # release: nothing is built, nothing is attached to the Gitea release, nothing reaches Play.
       #
-      # Canary is exempt on purpose: it has no curated notes, and Play reusing text for internal
-      # testers costs nothing.
+      # Canary is exempt on purpose: it has no curated notes. Open-testing users therefore see
+      # the previous release's text on a canary — cosmetic, and cheaper than gating every main
+      # push on a notes file.
       - name: Play release notes gate (tags only)
         if: startsWith(github.ref, 'refs/tags/v')
         run: |
@@ -213,15 +242,18 @@ jobs:
       # Single source of the version name + the Play track for the release steps below. versionCode
       # stays github.run_number (monotonic across both tracks; Play rejects a regressed code).
       - name: Version + channel
-        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        if: >-
+          (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish == 'true'))
+          && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
         run: |
           eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE (one minor ahead of the latest stable tag)
           case "$GITHUB_REF" in
-            refs/tags/v*) VN="${GITHUB_REF_NAME#v}"; TRACK="production" ;;
-            *)            VN="${PF_BASE}-ci${GITHUB_RUN_NUMBER}"; TRACK="internal" ;;
+            refs/tags/v*) VN="${GITHUB_REF_NAME#v}"; TRACK="production"; ALSO="" ;;
+            *)            VN="${PF_BASE}-ci${GITHUB_RUN_NUMBER}"; TRACK="beta"; ALSO="alpha" ;;
           esac
           echo "VERSION_NAME=$VN" >> "$GITHUB_ENV"
           echo "PLAY_TRACK=$TRACK" >> "$GITHUB_ENV"
+          echo "PLAY_ALSO_TRACK=$ALSO" >> "$GITHUB_ENV"
           # Play's own "What's new" (500-char cap, its own file — the vX.Y.Z.md body is ~34 KB).
           # On a tag the gate step above already proved this exists, so the else branch is only
           # ever the canary path. See docs/releases/README.md.
@@ -231,10 +263,12 @@ jobs:
           else
             echo "no Play release notes at $NOTES (canary — Play keeps the previous text)"
           fi
-          echo "android version $VN -> Play track '$TRACK'"
+          echo "android version $VN -> Play track '$TRACK'${ALSO:+ (+ '$ALSO')}"
 
       - name: Build Release (signed AAB + universal APK)
-        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        if: >-
+          (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish == 'true'))
+          && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
         working-directory: clients/android
         env:
           VERSION_CODE: ${{ github.run_number }}   # VERSION_NAME comes from the Version+channel step (GITHUB_ENV)
@@ -265,11 +299,13 @@ 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
-        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        if: >-
+          (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish == 'true'))
+          && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
         env:
           REGISTRY: git.unom.io
           OWNER: unom
@@ -303,7 +339,8 @@ jobs:
       # Direct Publishing-API upload instead of r0adkll/upload-google-play — that action hides the
       # real API error behind "Unknown error occurred."; this prints it. stdlib + openssl only (no
       # pip), reuses SERVICE_ACCOUNT_JSON (raw JSON or base64), auto-handles changesNotSentForReview.
-      # Track: canary main -> `internal`; a vX.Y.Z release -> `production` at 100% (`completed`).
+      # Track: canary main -> `beta` (open testing) + the same versionCode on `alpha` (closed
+      # testing) in the same Play edit; a vX.Y.Z release -> `production` at 100% (`completed`).
       #
       # A tag therefore ships to real users with no further click. Two things keep that honest:
       # the tag is only pushed once every platform is green, and Play reviews each production
@@ -311,13 +348,16 @@ jobs:
       # `--status inProgress --user-fraction 0.2`; to undo a bad one, halt or roll back from the
       # Console (or `android-promote.yml`, which can re-point production at an older versionCode).
       - name: Upload to Google Play
-        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        if: >-
+          (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish == 'true'))
+          && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
         env:
           SERVICE_ACCOUNT_JSON: ${{ secrets.SERVICE_ACCOUNT_JSON }}
         run: |
-          echo "uploading to Play track '$PLAY_TRACK'"
+          echo "uploading to Play track '$PLAY_TRACK'${PLAY_ALSO_TRACK:+ (+ '$PLAY_ALSO_TRACK')}"
           set -- --package io.unom.punktfunk \
                  --aab clients/android/app/build/outputs/bundle/release/app-release.aab \
                  --track "$PLAY_TRACK" --status completed
+          if [ -n "${PLAY_ALSO_TRACK:-}" ]; then set -- "$@" --also-track "$PLAY_ALSO_TRACK"; fi
           if [ -n "${PLAY_NOTES:-}" ]; then set -- "$@" --release-notes-file "$PLAY_NOTES"; fi
           python3 clients/android/ci/play-upload.py "$@"

.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 11-library 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
@@ -96,8 +114,14 @@ jobs:
           path: |
             /usr/local/cargo/registry
             /usr/local/cargo/git
-          key: cargo-home-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-home-
+          # Namespaced `-ci-` so a fork PR's cargo-home cache can never land in the `cargo-home-`
+          # pool the SIGNED release builds (deb.yml / android.yml) restore: registry/src holds
+          # already-extracted crate sources that cargo compiles WITHOUT re-checksumming past
+          # `.cargo-ok`, so a poisoned entry would be arbitrary Rust source compiled into a release
+          # artifact with no Cargo.lock diff. security-review 2026-08-15 finding 5. (The definitive
+          # control is operator-side: Gitea's "require approval for fork PRs".)
+          key: cargo-home-ci-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-ci-
       - uses: actions/cache@v4
         with:
           path: target
@@ -105,8 +129,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
@@ -220,14 +253,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"
@@ -236,14 +264,28 @@ jobs:
           path: |
             /usr/local/cargo/registry
             /usr/local/cargo/git
-          key: cargo-home-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-home-
+          # Namespaced `-ci-` so a fork PR's cargo-home cache can never land in the `cargo-home-`
+          # pool the SIGNED release builds (deb.yml / android.yml) restore: registry/src holds
+          # already-extracted crate sources that cargo compiles WITHOUT re-checksumming past
+          # `.cargo-ok`, so a poisoned entry would be arbitrary Rust source compiled into a release
+          # artifact with no Cargo.lock diff. security-review 2026-08-15 finding 5. (The definitive
+          # control is operator-side: Gitea's "require approval for fork PRs".)
+          key: cargo-home-ci-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-ci-
       - uses: actions/cache@v4
         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: |
@@ -259,6 +301,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.
@@ -357,6 +363,12 @@ jobs:
           envs: REGISTRY_TOKEN
           script: |
             set -euo pipefail
+            # Log out on EVERY exit path: unlike the ephemeral LAN-registry runners, this is a
+            # long-lived internet-facing VM, so a `write:package` PAT left base64-encoded in
+            # ~/.docker/config.json is credential-at-rest on the most exposed host in the estate.
+            # The LAN jobs above already `docker logout`; this one omitted it. security-review
+            # 2026-08-15 finding 14.
+            trap 'docker logout git.unom.io || true' EXIT
             printf '%s' "$REGISTRY_TOKEN" | docker login git.unom.io -u enricobuehler --password-stdin
             cd ~/punktfunk-docs
             docker compose -f compose.production.yml pull docs

.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,340 @@
+# 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), first match wins:
+#   1. Azure Artifact Signing — what this workflow always takes, since the AZURE_CODESIGNING_*
+#      endpoint/account/profile are literals below and only the AZURE_TENANT_ID / AZURE_CLIENT_ID /
+#      AZURE_CLIENT_SECRET secrets are needed. Publicly trusted, so NO .cer is emitted or published
+#      and users import nothing. NOTE the Publisher DN is the Azure profile's verified subject, and
+#      MSIX identity is name + publisher: moving to it changed the package identity, so installs
+#      predating it need an uninstall, not an upgrade.
+#   2. MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD — the older self-signed .pfx, kept as a fallback.
+#   3. an ephemeral self-signed cert. Modes 2 and 3 DO emit a .cer next to the .msix, which users
+#      would have to import into Trusted People before Windows will install the package.
+#
+# Modes 2 and 3 are 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.
@@ -291,9 +297,17 @@ jobs:
           # so the installer ships just bun + a ~75-file .output instead of node + a node_modules forest.
           $ver = 'bun-v1.3.14'
           $url = "https://github.com/oven-sh/bun/releases/download/$ver/bun-windows-x64.zip"
+          # SHA-256 of this exact asset, pinned. GitHub release assets are MUTABLE at a fixed URL, so
+          # the tag alone vouches for nothing — this binary is Authenticode-signed into our installer
+          # and its hash published in the Ed25519 update manifest, i.e. our signature vouches for bytes
+          # we downloaded. Verify them. On a bun bump, update BOTH $ver and $sha (compute:
+          # `shasum -a 256 bun-windows-x64.zip`). security-review 2026-08-15 finding 12.
+          $sha = '0a0620930b6675d7ba440e81f4e0e00d3cfbe096c4b140d3fff02205e9e18922'
           New-Item -ItemType Directory -Force -Path C:\t | Out-Null
           $zip = 'C:\t\bun.zip'; $dst = 'C:\t\bundist'
           Invoke-WebRequest -Uri $url -OutFile $zip
+          $got = (Get-FileHash -Algorithm SHA256 $zip).Hash.ToLower()
+          if ($got -ne $sha) { throw "bun zip sha256 mismatch for ${ver}: got $got, pinned $sha" }
           if (Test-Path $dst) { Remove-Item $dst -Recurse -Force }
           Expand-Archive -Path $zip -DestinationPath $dst -Force
           $bun = (Get-ChildItem -Path $dst -Recurse -Filter bun.exe | Select-Object -First 1).FullName
@@ -415,12 +429,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 +480,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,7 +65,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.27.0"
+version = "0.29.0"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT OR Apache-2.0"

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.

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/README.md

@@ -22,7 +22,8 @@ Google TV, budget Amlogic boxes) that otherwise reject a 64-bit-only build as "n
 
 ## Get it
 
-Published to **Google Play (Internal Testing)** — join the beta via the
+Published to **Google Play (Open Testing)** — join via the
+[public opt-in link](https://play.google.com/apps/testing/io.unom.punktfunk) or the
 [Discord](https://discord.gg/kaPNvzMuGU). Per-device setup and pairing:
 **[docs.punktfunk.unom.io/docs/install-client](https://docs.punktfunk.unom.io/docs/install-client)**.
 

clients/android/app/build.gradle.kts

@@ -142,6 +142,10 @@ dependencies {
     // job runs `:app:testDebugUnitTest -PskipRustBuild` (see kit/build.gradle.kts). ---
     testImplementation(composeBom)
     testImplementation("androidx.compose.ui:ui-test-junit4")
+    // Deterministic cover art for the library scene: FakeImageLoaderEngine answers the coverflow's
+    // AsyncImage synchronously with generated posters — no network, no async race under the frozen
+    // animation clock.
+    testImplementation("io.coil-kt:coil-test:2.7.0")
     debugImplementation("androidx.compose.ui:ui-test-manifest") // the ComponentActivity test host
     testImplementation("junit:junit:4.13.2")
     // Real `org.json` for the shared-vectors test: the `org.json` inside `android.jar` is a stub

clients/android/app/src/main/AndroidManifest.xml

@@ -28,9 +28,14 @@
     <!-- Gamepad rumble feedback. -->
     <uses-permission android:name="android.permission.VIBRATE" />
     <!-- Steam Controller 2 over direct BLE (Sc2BleLink talks Valve's vendor GATT service to the
-         bonded pad). A RUNTIME permission (NEARBY_DEVICES group); the capture engages only when
-         already granted — USB capture (wired / Puck dongle) needs no Bluetooth at all. -->
+         bonded pad). A RUNTIME permission (NEARBY_DEVICES group) from API 31 — MainActivity asks
+         for it when a BLE-paired SC2 is actually around, and the Controllers screen offers the
+         grant outright. USB capture (wired / Puck dongle) needs no Bluetooth at all.
+         Below API 31 the same two operations (the bonded list + connectGatt) are covered by the
+         install-time legacy permission instead, which BLUETOOTH_CONNECT does NOT imply — without
+         it every BLE capture on Android 11 and older throws SecurityException. -->
     <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
 
     <!-- We target phone + TV from day one: keep the app installable on TV (no touchscreen) and on
          devices without a gamepad. -->

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

@@ -1,6 +1,5 @@
 package io.unom.punktfunk
 
-import android.os.Build
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.ColumnScope
@@ -14,6 +13,7 @@ import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.window.DialogProperties
@@ -206,7 +206,9 @@ fun AwaitingApprovalPrompt(gamepadUi: Boolean, hostLabel: String, onCancel: () -
         actions = listOf(DialogAction("Cancel", primary = true, onClick = onCancel)),
         dismissOnOutsideTap = false,
     ) {
-        val deviceName = Build.MODEL ?: "this device"
+        // MUST be the name the connect actually knocked with (`HostConnect`), or this sends the
+        // user looking for a row the console does not show.
+        val label = deviceName(LocalContext.current)
         Row(
             verticalAlignment = Alignment.CenterVertically,
             horizontalArrangement = Arrangement.spacedBy(12.dp),
@@ -222,7 +224,7 @@ fun AwaitingApprovalPrompt(gamepadUi: Boolean, hostLabel: String, onCancel: () -
             )
         }
         PromptText(
-            "Open the host's console (or web UI) and approve “$deviceName”. It connects " +
+            "Open the host's console (or web UI) and approve “$label”. It connects " +
                 "automatically once you approve — no PIN needed.",
             gamepadUi,
         )

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

@@ -1,6 +1,5 @@
 package io.unom.punktfunk
 
-import android.os.Build
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
@@ -31,6 +30,7 @@ import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.input.KeyboardType
 import androidx.compose.ui.unit.dp
 import io.unom.punktfunk.kit.NativeBridge
@@ -137,7 +137,8 @@ internal fun PairPinDialog(
 ) {
     val scope = rememberCoroutineScope()
     var pin by remember(pt) { mutableStateOf("") }
-    var name by remember(pt) { mutableStateOf(Build.MODEL ?: "Android") }
+    val context = LocalContext.current
+    var name by remember(pt) { mutableStateOf(deviceName(context)) }
     var pairing by remember(pt) { mutableStateOf(false) }
     var err by remember(pt) { mutableStateOf<String?>(null) }
     AlertDialog(

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

@@ -53,6 +53,11 @@ object ConnectErrors {
                 "on the host."
         "wire-version" -> "Client and host versions don't match — update both to the same release."
         "busy" -> "The host is busy with another session."
+        "access-expired" ->
+            "Your access to this host has expired — ask the host's owner to grant it again."
+        "launch-not-permitted" ->
+            "This device's access doesn't include launching games — connect to the desktop, " +
+                "or ask the host's owner."
         else -> null
     }
 

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

@@ -243,6 +243,15 @@ fun ConnectScreen(
                     knownHostStore.learnOs(dh.host, dh.port, dh.os)
                     any = true
                 }
+                // And the mgmt port, so a host that moved off 47990 keeps its library once this
+                // device can no longer see the advert (VPN, routed subnet, multicast-dead Wi-Fi).
+                val mgmt = dh.mgmtPort
+                if (mgmt != null &&
+                    knownHostStore.get(dh.host, dh.port)?.let { it.mgmtPort != mgmt } == true
+                ) {
+                    knownHostStore.learnMgmtPort(dh.host, dh.port, mgmt)
+                    any = true
+                }
             }
             any
         }
@@ -313,13 +322,24 @@ fun ConnectScreen(
     // What the stream screen is handed: the settings this connect actually used, plus the HOST's
     // clipboard decision (a property of the record, not a global). A host we never saved — a
     // connect that failed to pin — falls back to the on default the setting always had.
-    fun session(handle: Long, record: KnownHost?, profile: StreamProfile?) = ActiveSession(
-        handle,
-        settings.effectiveFor(profile),
-        clipboardSync = record?.clipboardSync ?: true,
-        profileName = profile?.name,
-        hostId = record?.id,
-    )
+    fun session(handle: Long, record: KnownHost?, profile: StreamProfile?): ActiveSession {
+        // The session's own Welcome carries where this host serves its library. Save it now: this
+        // is the only source that does not need an mDNS advert, so it is what makes a host that
+        // moved off 47990 browsable over a VPN or when it was added by address. 0 = not
+        // advertised, and learnMgmtPort ignores it.
+        if (record != null) {
+            NativeBridge.nativeHostMgmtPort(handle).takeIf { it > 0 }?.let {
+                knownHostStore.learnMgmtPort(record.address, record.port, it)
+            }
+        }
+        return ActiveSession(
+            handle,
+            settings.effectiveFor(profile),
+            clipboardSync = record?.clipboardSync ?: true,
+            profileName = profile?.name,
+            hostId = record?.id,
+        )
+    }
 
     // The actual dial (identity already ready). On a TOFU connect (pinHex null), pin the fingerprint
     // the host presented (as an unpaired known host) so the next connect goes straight through and it

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

@@ -12,6 +12,8 @@ import android.view.InputDevice
 import android.view.KeyEvent
 import android.view.MotionEvent
 import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.foundation.ScrollState
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Arrangement
@@ -54,6 +56,7 @@ import dev.chrisbanes.haze.HazeState
 import dev.chrisbanes.haze.hazeSource
 import io.unom.punktfunk.kit.DsDevice
 import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.Sc2BleLink
 import io.unom.punktfunk.kit.Sc2Capture
 import kotlinx.coroutines.delay
 
@@ -69,7 +72,7 @@ import kotlinx.coroutines.delay
  * to be the same one whichever interface asked.
  */
 @Composable
-fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
+internal fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit, padsOverride: List<PadInfo>? = null) {
     BackHandler(onBack = onBack)
     var testing by remember { mutableStateOf(false) }
     ControllersBody(
@@ -77,6 +80,7 @@ fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
         scroll = rememberScrollState(),
         testing = testing,
         onTestingChange = { testing = it },
+        padsOverride = padsOverride,
         // The touch screen holds the probes for its whole life: events are OBSERVED (not consumed)
         // while the test is off, which is what keeps the "Last input" line live while browsing.
         // Nothing else here wants the pad, so there is no one to hand them to.
@@ -99,7 +103,12 @@ fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
  *    drops out of the probe slots and B is a HOLD (below). Everything reverts the moment it ends.
  */
 @Composable
-fun ConsoleControllersScreen(gamepadSetting: Int, onBack: () -> Unit, navActive: Boolean = true) {
+internal fun ConsoleControllersScreen(
+    gamepadSetting: Int,
+    onBack: () -> Unit,
+    navActive: Boolean = true,
+    padsOverride: List<PadInfo>? = null,
+) {
     BackHandler(onBack = onBack)
     val landscape = LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
     val hazeState = remember { HazeState() }
@@ -139,6 +148,7 @@ fun ConsoleControllersScreen(gamepadSetting: Int, onBack: () -> Unit, navActive:
                         scroll = scroll,
                         testing = testing,
                         onTestingChange = { testing = it },
+                        padsOverride = padsOverride,
                         // Only while testing: the rest of the time the screen's own nav holds the
                         // probes, so the "Last input" line is a test-time readout here rather than
                         // an always-on one. A pad that reaches this screen at all has already
@@ -200,14 +210,17 @@ private fun ControllersBody(
     onTestingChange: (Boolean) -> Unit,
     observeInput: Boolean,
     contentPadding: PaddingValues,
+    padsOverride: List<PadInfo>? = null,
     heading: @Composable () -> Unit,
 ) {
     val context = LocalContext.current
     val activity = context as? MainActivity
 
-    // Device list, re-read on every hot-plug event.
+    // Device list, re-read on every hot-plug event. [padsOverride] replaces it wholesale: the
+    // screenshot harness runs where no InputDevice can exist, and the connected-pad card is the
+    // point of that shot.
     var generation by remember { mutableIntStateOf(0) }
-    val pads = remember(generation) { Gamepad.pads() }
+    val pads = padsOverride ?: remember(generation) { Gamepad.pads() }.map(::padInfoOf)
     val others = remember(generation) {
         InputDevice.getDeviceIds()
             .toList()
@@ -363,12 +376,16 @@ private fun ControllersBody(
         }
         val sc2Probe = remember { Sc2Capture(context) }
         val sc2Usb = remember(usbGeneration) { sc2Probe.findUsbDevice() }
-        val sc2Ble = remember(usbGeneration) {
-            if (context.checkSelfPermission(android.Manifest.permission.BLUETOOTH_CONNECT) ==
-                android.content.pm.PackageManager.PERMISSION_GRANTED
-            ) sc2Probe.pairedBleAddress() else null
-        }
+        // Answers null without the Bluetooth grant (and logs why) — see Sc2BleLink.
+        val sc2Ble = remember(usbGeneration) { sc2Probe.pairedBleAddress() }
         val sc2Present = sc2Usb != null || sc2Ble != null
+        // A BLE-paired SC2 cannot be seen at all until Bluetooth is granted, so "no controller
+        // detected" would be the wrong thing to print at someone who has one paired. This is the
+        // screen a user opens when a pad is missing, so the grant belongs here — see
+        // [sc2BluetoothGrantOffered] for when it is worth offering, and the lizard-mode
+        // InputDevice probe (no permission of its own) for how we word it.
+        val btPermitted = remember(usbGeneration) { Sc2BleLink.permissionGranted(context) }
+        val sc2OnBluetooth = remember(usbGeneration) { Gamepad.sc2InputDevicePresent() }
         val dsUsb = remember(usbGeneration) {
             (context.getSystemService(Context.USB_SERVICE) as android.hardware.usb.UsbManager)
                 .deviceList.values.firstOrNull {
@@ -389,11 +406,24 @@ private fun ControllersBody(
                     color = MaterialTheme.colorScheme.onSurfaceVariant,
                 )
             }
+            // After that paragraph on purpose: when nothing was detected, this is the actionable
+            // half of the same answer — the one pad we are blind to rather than one Android has
+            // simply classified oddly.
+            if (
+                sc2BluetoothGrantOffered(
+                    permissionGranted = btPermitted,
+                    usbSc2 = sc2Usb != null,
+                    sc2Attached = sc2OnBluetooth,
+                    anyPadDetected = pads.isNotEmpty(),
+                )
+            ) {
+                Sc2BluetoothRow(attached = sc2OnBluetooth, activity = activity) { usbGeneration++ }
+            }
             // Every real controller is forwarded now (Automatic forwards them all, each on its own
             // wire pad index) — not just the first. A joystick-only device Android doesn't classify as
             // a gamepad still can't be forwarded (the host wants a gamepad), so gate the badge on it.
-            pads.forEach { dev ->
-                PadRow(dev, forwarded = isForwarded(dev), gamepadSetting = gamepadSetting)
+            pads.forEach { info ->
+                PadRow(info, gamepadSetting = gamepadSetting)
             }
         }
 
@@ -451,6 +481,90 @@ private fun ControllersBody(
     }
 }
 
+/**
+ * Whether to offer the Bluetooth grant for a directly-paired Steam Controller 2.
+ *
+ * Only when it could change the answer ([permissionGranted] false), and only when there is reason
+ * to think it would: an SC2 is visibly attached in lizard mode ([sc2Attached] — the permission-free
+ * probe), or nothing was detected at all ([anyPadDetected] false) and a Bluetooth SC2 is precisely
+ * the pad this client cannot see without the grant. A [usbSc2] is already captured over USB and
+ * needs no Bluetooth, and someone with working controllers and no sign of an SC2 is shown nothing.
+ */
+fun sc2BluetoothGrantOffered(
+    permissionGranted: Boolean,
+    usbSc2: Boolean,
+    sc2Attached: Boolean,
+    anyPadDetected: Boolean,
+): Boolean = !permissionGranted && !usbSc2 && (sc2Attached || !anyPadDetected)
+
+/**
+ * The Bluetooth grant for a directly-paired Steam Controller 2 — the card that exists because a
+ * BLE SC2 is invisible without it.
+ *
+ * A wired or Puck SC2 is enumerated over USB with no permission at all, so it shows up in this
+ * screen either way; the bonded list a BLE one lives in is behind `BLUETOOTH_CONNECT` from API 31
+ * and answers "nothing is paired" rather than "ask me first" when the permission is missing. Until
+ * this existed, nothing in the client ever requested it, so a Bluetooth SC2 was silently absent
+ * everywhere — no capture, no controller layout, no forwarding — while the same pad over USB
+ * worked (field report, 2026-08-15).
+ *
+ * [attached] distinguishes "we can see one sitting in lizard mode" from "you may have one paired",
+ * which is the difference between a statement and a guess. [onGranted] re-probes the caller's
+ * device state; the menu capture is engaged from here too, so the pad starts driving the UI on the
+ * grant rather than at the next resume.
+ */
+@Composable
+private fun Sc2BluetoothRow(
+    attached: Boolean,
+    activity: MainActivity?,
+    onGranted: () -> Unit,
+) {
+    val context = LocalContext.current
+    val settingOn = remember { SettingsStore(context).load().sc2Capture }
+    val launcher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted ->
+        if (granted) {
+            activity?.startSc2MenuNav()
+            onGranted()
+        }
+    }
+    val permission = Sc2BleLink.CONNECT_PERMISSION ?: return
+    OutlinedCard(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Text(
+                if (attached) "Steam Controller 2" else "Steam Controller 2 over Bluetooth",
+                style = MaterialTheme.typography.bodyLarge,
+            )
+            Text(
+                when {
+                    !settingOn ->
+                        "Passthrough is disabled in Settings — enable \"Steam Controller 2 " +
+                            "passthrough\" to capture it."
+                    attached ->
+                        "Paired over Bluetooth. Punktfunk needs Bluetooth access to capture it — " +
+                            "until then it stays in its built-in keyboard/mouse mode and no game " +
+                            "sees a controller."
+                    else ->
+                        "A Steam Controller 2 paired over Bluetooth can't be detected without " +
+                            "Bluetooth access. Wired and Puck-dongle controllers need no " +
+                            "permission and are already listed above."
+                },
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            if (settingOn) {
+                OutlinedButton(onClick = { launcher.launch(permission) }) {
+                    Text("Grant Bluetooth access")
+                }
+            }
+        }
+    }
+}
+
 /**
  * The Steam Controller 2 card — capture-side state, since a (claimed or lizard-mode) SC2 never
  * appears as a gamepad InputDevice. Shows the transport, whether the capture is live (driving
@@ -675,19 +789,19 @@ private fun DsRow(usbDev: android.hardware.usb.UsbDevice) {
 
 /** One detected gamepad: identity, what it streams as, and a rumble test. */
 @Composable
-private fun PadRow(dev: InputDevice, forwarded: Boolean, gamepadSetting: Int) {
+private fun PadRow(info: PadInfo, gamepadSetting: Int) {
     OutlinedCard(modifier = Modifier.fillMaxWidth()) {
         Column(
             modifier = Modifier.padding(16.dp),
             verticalArrangement = Arrangement.spacedBy(6.dp),
         ) {
             Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
-                Text(dev.name, style = MaterialTheme.typography.bodyLarge, modifier = Modifier.weight(1f))
-                if (forwarded) {
+                Text(info.name, style = MaterialTheme.typography.bodyLarge, modifier = Modifier.weight(1f))
+                if (info.forwarded) {
                     // Android's own controller number (1-based; 0 = unassigned), shown so a multi-pad
                     // user can tell which physical pad is which. The stream's wire pad index is
                     // assigned separately (lowest-free per device) once streaming starts.
-                    val number = dev.controllerNumber
+                    val number = info.controllerNumber
                     Text(
                         if (number > 0) "forwarded · player $number" else "forwarded to host",
                         style = MaterialTheme.typography.labelSmall,
@@ -696,11 +810,11 @@ private fun PadRow(dev: InputDevice, forwarded: Boolean, gamepadSetting: Int) {
                 }
             }
             Text(
-                deviceDetail(dev),
+                info.detail,
                 style = MaterialTheme.typography.bodySmall,
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )
-            val resolved = Gamepad.prefFor(dev)
+            val resolved = info.resolvedPref
             Text(
                 if (gamepadSetting == Gamepad.PREF_AUTO) {
                     "Streams as: ${prefLabel(resolved)} (automatic)"
@@ -711,9 +825,8 @@ private fun PadRow(dev: InputDevice, forwarded: Boolean, gamepadSetting: Int) {
                 style = MaterialTheme.typography.bodySmall,
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )
-            val canRumble = deviceHasVibrator(dev)
-            if (canRumble) {
-                OutlinedButton(onClick = { testRumble(dev) }) { Text("Test rumble") }
+            if (info.canRumble) {
+                OutlinedButton(onClick = { info.dev?.let(::testRumble) }) { Text("Test rumble") }
             } else {
                 Text(
                     "No rumble motors reported — host rumble will be silent",
@@ -794,6 +907,32 @@ private fun Group(title: String, content: @Composable ColumnScope.() -> Unit) {
 private fun isForwarded(dev: InputDevice): Boolean =
     !dev.isVirtual && dev.sources and InputDevice.SOURCE_GAMEPAD == InputDevice.SOURCE_GAMEPAD
 
+/**
+ * Everything [PadRow] renders, decoupled from [InputDevice] so the screenshot harness can compose
+ * the connected-pad card at all — Robolectric enumerates no input devices, and a marketing shot of
+ * "no controller detected" sells nothing. Production always maps a real device via [padInfoOf];
+ * [dev] powers the rumble test and is absent only in the harness (the button then no-ops).
+ */
+internal data class PadInfo(
+    val name: String,
+    val detail: String,
+    val forwarded: Boolean,
+    val controllerNumber: Int,
+    val resolvedPref: Int,
+    val canRumble: Boolean,
+    val dev: InputDevice? = null,
+)
+
+internal fun padInfoOf(dev: InputDevice): PadInfo = PadInfo(
+    name = dev.name,
+    detail = deviceDetail(dev),
+    forwarded = isForwarded(dev),
+    controllerNumber = dev.controllerNumber,
+    resolvedPref = Gamepad.prefFor(dev),
+    canRumble = deviceHasVibrator(dev),
+    dev = dev,
+)
+
 /** Whether the controller reports a rumble motor — via VibratorManager (API 31+) or the legacy Vibrator. */
 private fun deviceHasVibrator(dev: InputDevice): Boolean =
     if (Build.VERSION.SDK_INT >= 31) {

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

@@ -0,0 +1,25 @@
+package io.unom.punktfunk
+
+import android.content.Context
+import android.os.Build
+import android.provider.Settings
+
+/**
+ * The name the user knows this device by — what a host shows in its pending-approval list (the web
+ * console's outstanding-pairings view and the dialog that approves a knock) and files the device
+ * under once approved.
+ *
+ * `Settings.Global.DEVICE_NAME` is the name the user typed in Settings ("Enrico's Pixel", "TV im
+ * Wohnzimmer"); it is what every other protocol on the network already calls this device. Only when
+ * it is unset does this fall back to [Build.MODEL], which names the *product* and so reads
+ * identically on every unit of it — two of the same tablet pending approval are indistinguishable.
+ * Available unconditionally here: `DEVICE_NAME` landed in API 25 and this app's floor is 28.
+ */
+internal fun deviceName(context: Context): String {
+    val userNamed = runCatching {
+        Settings.Global.getString(context.contentResolver, Settings.Global.DEVICE_NAME)
+    }.getOrNull()
+    return userNamed?.trim()?.takeIf { it.isNotEmpty() }
+        ?: Build.MODEL?.trim()?.takeIf { it.isNotEmpty() }
+        ?: "Android"
+}

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

@@ -1,6 +1,5 @@
 package io.unom.punktfunk
 
-import android.os.Build
 import androidx.activity.compose.BackHandler
 import androidx.compose.animation.animateColorAsState
 import androidx.compose.animation.core.Spring
@@ -44,6 +43,7 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.style.TextAlign
@@ -396,7 +396,8 @@ fun GamepadPairPinDialog(pt: PendingTrust, identity: ClientIdentity?, onPaired:
     var slot by remember(pt) { mutableIntStateOf(0) } // 0..3 = digit slots, 4 = Pair button
     var pairing by remember(pt) { mutableStateOf(false) }
     var err by remember(pt) { mutableStateOf<String?>(null) }
-    val name = remember { Build.MODEL ?: "Android" }
+    val context = LocalContext.current
+    val name = remember(context) { deviceName(context) }
 
     fun pair() {
         val id = identity ?: return

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

@@ -1,7 +1,6 @@
 package io.unom.punktfunk
 
 import android.content.Context
-import android.os.Build
 import android.util.Log
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.NativeBridge
@@ -82,8 +81,8 @@ suspend fun connectToHost(
             codecBits, preferredCodec, timeoutMs,
             launch,
             // The host's approval-list / trust-store label for this device — the same
-            // Build.MODEL convention the pairing dialogs use for nativePair.
-            Build.MODEL ?: "Android",
+            // user-set device name the pairing dialogs offer for nativePair.
+            deviceName(context),
             // Tier-A pad audio: ask for the 0xD1 plane only when a setting would render it, so a
             // user with it off does not make the host provision endpoints it will never feed.
             settings.padHaptics || settings.padSpeaker,

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

@@ -59,7 +59,6 @@ import coil.ImageLoader
 import coil.compose.AsyncImage
 import coil.request.ImageRequest
 import io.unom.punktfunk.components.launcherIcon
-import io.unom.punktfunk.kit.library.DEFAULT_MGMT_PORT
 import io.unom.punktfunk.kit.library.GameEntry
 import io.unom.punktfunk.kit.library.LibraryClient
 import io.unom.punktfunk.kit.library.LibraryResult
@@ -120,14 +119,16 @@ fun LibraryScreen(
     }
     val streamSettings = remember(settings, profile) { settings.effectiveFor(profile) }
 
-    LaunchedEffect(host.address, host.port, host.fpHex) {
+    // Keyed on the mgmt port too: a discovery tick can learn it after this screen is composed, and
+    // the fetch must redo itself against the real port rather than stay on a stale 47990 failure.
+    LaunchedEffect(host.address, host.port, host.fpHex, host.effectiveMgmtPort) {
         state = LibState.Loading
         state = withContext(Dispatchers.IO) {
             val id = runCatching { obtainIdentity(IdentityStore(context)) }.getOrNull()
                 ?: return@withContext LibState.Message("Identity unavailable — re-pair may be required.")
             when (val res = LibraryClient.fetch(
                 address = host.address,
-                mgmtPort = DEFAULT_MGMT_PORT,
+                mgmtPort = host.effectiveMgmtPort,
                 certPem = id.certPem,
                 keyPem = id.privateKeyPem,
                 fpHex = host.fpHex,
@@ -254,8 +255,10 @@ private fun MessageState(text: String) {
     )
 }
 
+// Internal (not private): the screenshot harness composes the real coverflow with mock games —
+// the library screen itself can't be shot, its state comes off the network.
 @Composable
-private fun Coverflow(
+internal fun Coverflow(
     games: List<GameEntry>,
     loader: ImageLoader,
     navActive: Boolean,

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

@@ -34,6 +34,8 @@ import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.GamepadRouter
 import io.unom.punktfunk.kit.Keymap
 import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.Sc2BleLink
+import io.unom.punktfunk.kit.SessionAccess
 import io.unom.punktfunk.kit.link.DeepLinkResult
 import io.unom.punktfunk.kit.link.DeepLinks
 import io.unom.punktfunk.kit.link.HostResolution
@@ -42,6 +44,9 @@ import io.unom.punktfunk.kit.security.KnownHostStore
 /** Broadcast action for the menu-time SC2 USB-permission grant (see [MainActivity.startSc2MenuNav]). */
 private const val SC2_MENU_PERMISSION = "io.unom.punktfunk.SC2_MENU_USB_PERMISSION"
 
+/** Request code for the SC2's Bluetooth grant (see [MainActivity.maybeAskSc2BtPermission]). */
+private const val REQ_SC2_BLUETOOTH = 0x5C2B
+
 /**
  * Keeps ONE window-insets reader alive for as long as the app's UI exists — the fix for the menus
  * coming back from a stream laid out against the WRONG safe area.
@@ -86,6 +91,16 @@ class MainActivity : ComponentActivity() {
      */
     var streamHandle: Long = 0L
 
+    /**
+     * The active session's access-grant mask ([SessionAccess] bits) — set with [streamHandle] by
+     * StreamScreen and kept live by its access poll; back to [SessionAccess.ALL] when the stream
+     * leaves. Consulted only while streaming: the VK keyboard path below goes inert without
+     * [SessionAccess.KEYBOARD] (the keys are consumed, not sent — the host would drop them, and
+     * letting them fall through would drive Android navigation under a live stream). Courtesy
+     * gating; the host enforces regardless.
+     */
+    var streamAccess: Int = SessionAccess.ALL
+
     /**
      * Multi-controller router for the active session (built/released by StreamScreen): assigns each
      * connected pad a stable wire index, threads it onto every event, declares/removes pads on
@@ -181,6 +196,9 @@ class MainActivity : ComponentActivity() {
     private var sc2Receiver: BroadcastReceiver? = null
     private var sc2PermissionAsked = false
 
+    /** Bluetooth asked once this process — a denial must not re-prompt on every resume. */
+    private var sc2BtPermissionAsked = false
+
     /** Sony-pad USB grant asked this attach — a deny doesn't re-nag until a fresh attach (or the
      *  Controllers screen's explicit button). */
     private var dsPermissionAsked = false
@@ -319,7 +337,8 @@ class MainActivity : ComponentActivity() {
      * Engage the menu-time SC2 capture if possible: setting on, not streaming, and a wired/Puck
      * pad attached (asking for USB permission at most once per attach — [forceAsk] re-arms the
      * dialog, for the Controllers screen's explicit grant button) — else an already-paired BLE
-     * controller when BLUETOOTH_CONNECT is granted. Safe to call repeatedly.
+     * controller, asking for Bluetooth access once if one appears to be attached
+     * ([maybeAskSc2BtPermission]). Safe to call repeatedly.
      */
     fun startSc2MenuNav(forceAsk: Boolean = false) {
         if (forceAsk) sc2PermissionAsked = false
@@ -347,10 +366,46 @@ class MainActivity : ComponentActivity() {
                     ),
                 )
             }
-            dev == null && checkSelfPermission(android.Manifest.permission.BLUETOOTH_CONNECT) ==
-                PackageManager.PERMISSION_GRANTED -> {
+            dev == null && Sc2BleLink.permissionGranted(this) -> {
                 cap.pairedBleAddress()?.let { cap.startBle(it) }
             }
+            dev == null -> maybeAskSc2BtPermission()
+        }
+    }
+
+    /**
+     * Ask for Bluetooth access when a BLE-paired SC2 looks like it is attached and we cannot see
+     * it — once per process, and never on a device that shows no sign of owning one.
+     *
+     * The permission is the whole reason a Bluetooth SC2 used to go unnoticed: the bonded list and
+     * `connectGatt` both need it from API 31, nothing in the client had ever requested it, and the
+     * bonded-list call answers an empty list rather than an error when it is missing — so the
+     * capture stood down silently and the console UI never flipped to its controller layout, while
+     * the same pad over USB worked (field report, 2026-08-15). Asking is gated on
+     * [Gamepad.sc2InputDevicePresent] because an uncaptured SC2 sits in lizard mode as a
+     * keyboard/mouse [android.view.InputDevice] — visible without any permission at all — so the
+     * prompt reaches the people who have the hardware and nobody else.
+     */
+    private fun maybeAskSc2BtPermission() {
+        val permission = Sc2BleLink.CONNECT_PERMISSION ?: return // granted at install time here
+        if (sc2BtPermissionAsked) return
+        if (!Gamepad.sc2InputDevicePresent()) return
+        sc2BtPermissionAsked = true
+        requestPermissions(arrayOf(permission), REQ_SC2_BLUETOOTH)
+    }
+
+    override fun onRequestPermissionsResult(
+        requestCode: Int,
+        permissions: Array<String>,
+        grantResults: IntArray,
+    ) {
+        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
+        // Engage immediately on the grant — the pad is already paired, so there is nothing else to
+        // wait for and the user just told us what they want it for.
+        if (requestCode == REQ_SC2_BLUETOOTH &&
+            grantResults.firstOrNull() == PackageManager.PERMISSION_GRANTED
+        ) {
+            startSc2MenuNav()
         }
     }
 
@@ -526,10 +581,25 @@ class MainActivity : ComponentActivity() {
     override fun dispatchKeyEvent(event: KeyEvent): Boolean {
         val handle = streamHandle
         if (handle != 0L) {
+            // A mouse's side buttons, when they arrive key-shaped, are X1/X2 — not navigation.
+            // Resolved before the gamepad and remote-pointer hooks so neither can claim them as
+            // its own BACK. See [mouseSideButton] for how a mouse's BACK is told from a pad's or
+            // a remote's; it answers null for every device that cannot be a mouse, so asking it
+            // first re-routes nothing else.
+            mouseSideButton(event)?.let { back ->
+                when (event.action) {
+                    KeyEvent.ACTION_DOWN ->
+                        if (event.repeatCount == 0) mouseForwarder?.sideButtonKey(back, true)
+                    KeyEvent.ACTION_UP -> mouseForwarder?.sideButtonKey(back, false)
+                }
+                return true
+            }
             // Gamepad buttons (incl. DPAD only when truly from a gamepad — else KEYCODE_DPAD_* are
-            // keyboard arrows and belong to the VK path below).
+            // keyboard arrows and belong to the VK path below — and BACK, which is how a pad with
+            // no BUTTON_SELECT scancode delivers its Select: see [Gamepad.padButtonBit], which is
+            // why this asks it rather than `buttonBit`).
             if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
-                val bit = Gamepad.buttonBit(event.keyCode)
+                val bit = Gamepad.padButtonBit(event.keyCode, event.flags)
                 if (bit != 0) {
                     // The router forwards the bit on this device's own wire pad index and tracks held
                     // state per pad. The emergency-exit chord (Select + Start + L1 + R1) is handled
@@ -540,17 +610,6 @@ class MainActivity : ComponentActivity() {
                     return true // consumed
                 }
             }
-            // A mouse's side buttons, when they arrive key-shaped, are X1/X2 — not navigation.
-            // Resolved before the remote-pointer hook so pointer mode can't eat them as its own
-            // BACK. See [mouseSideButton] for how a mouse's BACK is told from a remote's.
-            mouseSideButton(event)?.let { back ->
-                when (event.action) {
-                    KeyEvent.ACTION_DOWN ->
-                        if (event.repeatCount == 0) mouseForwarder?.sideButtonKey(back, true)
-                    KeyEvent.ACTION_UP -> mouseForwarder?.sideButtonKey(back, false)
-                }
-                return true
-            }
             // TV remote-as-pointer sees non-gamepad keys first (SELECT long-press toggles it;
             // while active it owns the D-pad/SELECT/PLAY-PAUSE/BACK).
             if (!event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
@@ -567,12 +626,13 @@ class MainActivity : ComponentActivity() {
                 return true
             }
             when (event.keyCode) {
-                // Whatever [mouseSideButton] didn't claim. A view-level FALLBACK BACK appears when
-                // a BUTTON_* press goes unconsumed, and an air-mouse remote stamps its own BACK
-                // SOURCE_MOUSE; both are duplicates of something already handled, and letting
-                // either through doubles as Android navigation and yanks the user out of the
-                // stream. A remote/keyboard BACK is never mouse-sourced, so it still falls through
-                // to the BackHandler and exits.
+                // Whatever [mouseSideButton] and the pad branch didn't claim. A view-level FALLBACK
+                // BACK appears when a BUTTON_* press goes unconsumed, and an air-mouse remote stamps
+                // its own BACK SOURCE_MOUSE; both are duplicates of something already handled, and
+                // letting either through doubles as Android navigation and yanks the user out of the
+                // stream. A remote/keyboard BACK is never mouse-sourced and never gamepad-sourced,
+                // so it still falls through to the BackHandler and exits — which for a device with
+                // no pad on it is the documented way out.
                 KeyEvent.KEYCODE_BACK, KeyEvent.KEYCODE_FORWARD ->
                     if (event.isFromSource(InputDevice.SOURCE_MOUSE) ||
                         event.flags and KeyEvent.FLAG_FALLBACK != 0
@@ -591,6 +651,10 @@ class MainActivity : ComponentActivity() {
                         KeyEvent.ACTION_UP -> false
                         else -> return super.dispatchKeyEvent(event)
                     }
+                    // Without the KEYBOARD grant the key path is inert: consumed (so nothing
+                    // drives Android navigation under the stream) but never sent — the host
+                    // would drop it, and the Access chip is what says why. Courtesy gating.
+                    if (streamAccess and SessionAccess.KEYBOARD == 0) return true
                     // Full-event overload: evdev scancode first (positional under ANY selected
                     // physical-keyboard layout), keycode fallback — see Keymap docs.
                     val vk = Keymap.toVk(event)

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

@@ -44,6 +44,18 @@ class MouseForwarder(
     var onRequestCapture: (() -> Unit)? = null
     var onReleaseCapture: (() -> Unit)? = null
 
+    /**
+     * Whether this session's access includes the POINTER grant ([io.unom.punktfunk.kit.SessionAccess.POINTER])
+     * — seeded from the Welcome, kept live by StreamScreen's access poll. Without it the mouse
+     * path goes inert: nothing forwards, and — the part that matters — the pointer is never
+     * GRABBED, because a captured mouse that moves nothing is the "my mouse does nothing and
+     * nobody says why" failure the grants UX exists to prevent (the Access chip says why
+     * instead). Revocation mid-session releases an existing grab (StreamScreen calls [release]).
+     * Volatile: set on the main thread, read wherever the dispatch path runs.
+     */
+    @Volatile
+    var pointerGranted: Boolean = true
+
     /** Live capture state, updated from [android.app.Activity.onPointerCaptureChanged]. */
     var captured = false
         private set
@@ -59,6 +71,7 @@ class MouseForwarder(
 
     /** Uncaptured mouse events on the TOUCH stream (position while a button is down). */
     fun onTouchEvent(ev: MotionEvent): Boolean {
+        if (!pointerGranted) return true // inert: consumed over the stream, nothing forwards
         when (ev.actionMasked) {
             MotionEvent.ACTION_DOWN -> {
                 if (captureWanted && !captured && !userReleased) {
@@ -80,6 +93,7 @@ class MouseForwarder(
 
     /** Uncaptured mouse events on the GENERIC stream (hover motion, wheel, button edges). */
     fun onGenericMotion(ev: MotionEvent): Boolean {
+        if (!pointerGranted) return true // inert: consumed over the stream, nothing forwards
         when (ev.actionMasked) {
             MotionEvent.ACTION_HOVER_MOVE -> sendAbs(ev)
             MotionEvent.ACTION_SCROLL -> wheel(ev)
@@ -98,6 +112,7 @@ class MouseForwarder(
      * gesture layer is the touchpad story); returning false leaves those to the framework.
      */
     fun onCapturedPointer(ev: MotionEvent): Boolean {
+        if (!pointerGranted) return true // a revocation is racing the release of the grab
         if (!ev.isFromSource(InputDevice.SOURCE_MOUSE_RELATIVE)) return false
         when (ev.actionMasked) {
             MotionEvent.ACTION_MOVE -> {
@@ -131,7 +146,7 @@ class MouseForwarder(
         if (captured) {
             userReleased = true
             onReleaseCapture?.invoke()
-        } else {
+        } else if (pointerGranted) { // never grab a pointer whose input can't land
             userReleased = false
             onRequestCapture?.invoke()
         }
@@ -139,7 +154,7 @@ class MouseForwarder(
 
     /** Auto-engage at stream start (setting on + a mouse actually present). */
     fun engageFromStart() {
-        if (captureWanted && !captured && !userReleased && hasPhysicalMouse()) {
+        if (pointerGranted && captureWanted && !captured && !userReleased && hasPhysicalMouse()) {
             onRequestCapture?.invoke()
         }
     }
@@ -204,7 +219,9 @@ class MouseForwarder(
      * input reader synthesizes them in), so both paths funnel into the same held-set and the
      * add/remove guard collapses the pair into a single wire press.
      */
-    fun sideButtonKey(back: Boolean, down: Boolean) = press(if (back) 4 else 5, down)
+    fun sideButtonKey(back: Boolean, down: Boolean) {
+        if (pointerGranted) press(if (back) 4 else 5, down)
+    }
 
     private fun button(actionButton: Int, down: Boolean) {
         val b = when (actionButton) {

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

@@ -44,6 +44,21 @@ class RemotePointer(
     var active = false
         private set
 
+    /**
+     * Whether this session's access includes the POINTER grant — StreamScreen keeps it live from
+     * the access poll. Ungranted, the SELECT long-press stops entering pointer mode (a mode whose
+     * every action the host would drop; the Access chip says why), and a revocation while the
+     * mode is on leaves it cleanly ([setGranted]). Everything else passes through untouched,
+     * exactly as when the mode is off — the remote stays a remote.
+     */
+    private var granted = true
+
+    /** Update the POINTER grant; revoking while pointer mode is on leaves the mode. Main thread. */
+    fun setGranted(ok: Boolean) {
+        granted = ok
+        if (!ok && active) toggle()
+    }
+
     private val handler = Handler(Looper.getMainLooper())
     private val held = mutableSetOf<Int>() // D-pad keycodes currently down
     private var moveAccX = 0f
@@ -169,6 +184,7 @@ class RemotePointer(
     }
 
     private fun toggle() {
+        if (!active && !granted) return // never enter a mode whose input can't land
         active = !active
         if (!active) {
             held.clear()

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
@@ -79,6 +70,7 @@ import io.unom.punktfunk.kit.deviceBodyVibrator
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.PadSensors
 import io.unom.punktfunk.kit.Sc2Capture
+import io.unom.punktfunk.kit.SessionAccess
 import io.unom.punktfunk.kit.SessionEndReason
 import io.unom.punktfunk.kit.VideoDecoders
 import io.unom.punktfunk.models.ActiveSession
@@ -111,6 +103,20 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
         window?.let { WindowCompat.getInsetsController(it, it.decorView) }
     }
 
+    // The session's access level (the per-client grants of design/per-client-access.md), the
+    // courtesy mirror of what the host enforces: seeded from the Welcome's advert here, kept live
+    // by the 1 Hz poll below (the host's AccessUpdate messages fold latest-wins into the native
+    // state). Full control + permanent — the only state an old host or an old native lib ever
+    // reports — gates nothing and draws nothing: today's look, unchanged.
+    val initialAccess = remember(handle) { NativeBridge.nativeAccessState(handle) }
+    var accessGrants by remember(handle) {
+        mutableStateOf(initialAccess?.getOrNull(0) ?: SessionAccess.ALL)
+    }
+    // Seconds until this session's access expires (0 = permanent), as last reported natively.
+    var accessRemaining by remember(handle) {
+        mutableStateOf(initialAccess?.getOrNull(1) ?: 0)
+    }
+
     // Start mic only if the user enabled it AND granted RECORD_AUDIO (else the AAudio input fails).
     val micWanted = micEnabled && ContextCompat.checkSelfPermission(
         context,
@@ -130,12 +136,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) {
@@ -191,6 +197,34 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
         NativeBridge.nativeSetMicMuted(handle, muted)
     }
 
+    // Push a grant mask into every gate that consults one — called at session start (once the
+    // router/forwarders exist) and again whenever the poll sees the mask change (an AccessUpdate
+    // revoked or restored something mid-session). A lambda, deliberately not a local fun — this
+    // codebase has been burned by `::localFun` references in composable scopes. The gates it does
+    // NOT reach (the Compose-side ones — the touch layer, the IME summon, the banner line, the
+    // chip) key on `accessGrants` directly and re-run on the state write.
+    val applyAccess: (Int) -> Unit = { grants ->
+        activity?.streamAccess = grants
+        activity?.gamepadRouter?.gamepadGranted = grants and SessionAccess.GAMEPAD != 0
+        val pointerOk = grants and SessionAccess.POINTER != 0
+        activity?.mouseForwarder?.let { m ->
+            m.pointerGranted = pointerOk
+            // A revocation must also let an existing grab go (and lift held buttons): a captured
+            // mouse that moves nothing reads as a broken mouse, not a spectator session.
+            if (!pointerOk) m.release()
+        }
+        activity?.remotePointer?.setGranted(pointerOk)
+        // Mic revoked mid-session: stop the capture — the host detaches its end regardless, and
+        // an open mic (with the platform's recording indicator lit) feeding a plane the host
+        // drops would be the worst kind of lie. Not restarted on a re-grant: the host attaches
+        // the mic service at session setup only, so a fresh session is the honest offer.
+        if (grants and SessionAccess.MIC == 0 && micRunning) {
+            releaseMicEffects(micEffects)
+            NativeBridge.nativeStopMic(handle)
+            micRunning = false
+        }
+    }
+
     // Live decode stats for the HUD. `statsOn` (verbosity != OFF) gates the whole native pipeline:
     // the per-frame sampling (nativeSetVideoStatsEnabled — a hidden HUD costs one atomic load per
     // frame) AND the 1 s poll loop, which only runs while the overlay is visible. Enabling resets
@@ -252,22 +286,62 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
     // open, so this fires only on a genuinely dead peer, never a false positive. Keyed on `handle`, so
     // it stops the moment we navigate away (the handle is only freed later, in onDispose).
     LaunchedEffect(handle) {
+        var lastAccessSeq = initialAccess?.getOrNull(2) ?: 0
         while (true) {
             delay(1000)
+            // Access first, ended second: a session about to close on its expiry gets its final
+            // countdown read, which is what lets the ended branch word that close honestly.
+            NativeBridge.nativeAccessState(handle)?.let { st ->
+                val grants = st.getOrNull(0) ?: SessionAccess.ALL
+                val seq = st.getOrNull(2) ?: 0
+                if (grants != accessGrants) {
+                    accessGrants = grants
+                    applyAccess(grants)
+                }
+                accessRemaining = st.getOrNull(1) ?: 0
+                if (seq != lastAccessSeq) {
+                    lastAccessSeq = seq
+                    // A fresh AccessUpdate close to the deadline is the host's T−5 m / T−1 m
+                    // courtesy warning — surface it. Grant edits (and a warning's grant echo)
+                    // otherwise just move the chip; a toast per edit would be noise.
+                    if (accessRemaining in 1..330) {
+                        val mins = (accessRemaining + 30) / 60
+                        Toast.makeText(
+                            context,
+                            if (mins <= 1) {
+                                "Access expires in about a minute."
+                            } else {
+                                "Access expires in about $mins minutes."
+                            },
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    }
+                }
+            }
             if (NativeBridge.nativeSessionEnded(handle)) {
                 // WHY it ended decides what the user is told. This used to show the "host may be
                 // asleep" line for EVERY ending — including a game the player had just quit and a
                 // session the host ended on purpose — which reads as a failure report for
                 // something nobody did wrong. Only a connection that actually died says that now.
                 val reason = SessionEndReason.fromNative(NativeBridge.nativeEndReason(handle))
-                when (reason) {
-                    SessionEndReason.LOST ->
+                when {
+                    // The session died inside the access countdown's final stretch: that IS the
+                    // typed expiry close (ACCESS_EXPIRED), worded with the shared rejection
+                    // sentence rather than the generic host-ended silence. Recognized off the
+                    // countdown because the generic end-reason byte predates the expiry code.
+                    accessRemaining in 1..75 ->
+                        Toast.makeText(
+                            context,
+                            "Your access to this host has expired.",
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    reason == SessionEndReason.LOST ->
                         Toast.makeText(
                             context,
                             "Connection lost — the host may be asleep. Wake it to reconnect.",
                             Toast.LENGTH_LONG,
                         ).show()
-                    SessionEndReason.HOST_ERROR ->
+                    reason == SessionEndReason.HOST_ERROR ->
                         Toast.makeText(
                             context,
                             "The host ended the session with an error.",
@@ -275,10 +349,7 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                         ).show()
                     // Deliberate endings — the player quit the game, the host was stopped, or we
                     // closed it. Leaving the stream IS the feedback; a toast would only add noise.
-                    SessionEndReason.GAME_EXITED,
-                    SessionEndReason.HOST_ENDED,
-                    SessionEndReason.LOCAL,
-                    SessionEndReason.NONE -> {}
+                    else -> {}
                 }
                 onSessionEnded(reason)
                 return@LaunchedEffect
@@ -413,9 +484,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 }
@@ -474,15 +545,32 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                 handle,
                 surfaceWidth = { videoView?.width?.takeIf { it > 0 } ?: decor?.width ?: 1920 },
                 onActiveChanged = { on -> remotePointerOn = on },
-                onKeyboardToggle = { keyCapture?.let { it.setImeVisible(!it.imeShown) } },
+                // The toggle TYPES — summoning also needs the KEYBOARD grant (hiding is free).
+                onKeyboardToggle = {
+                    keyCapture?.let { v ->
+                        if (v.imeShown || accessGrants and SessionAccess.KEYBOARD != 0) {
+                            v.setImeVisible(!v.imeShown)
+                        }
+                    }
+                },
             )
         } else {
             null
         }
         activity?.remotePointer = remote
-        // Shared clipboard (text v1): only when the user setting is on AND the host has a
-        // working clipboard service. Protocol-level opt-in + the poll thread live in the sync.
-        val clip = if (session.clipboardSync && NativeBridge.nativeClipSupported(handle)) {
+        // Everything the grant gates hang off now exists — apply the session's access level once
+        // up front (the poll only re-applies on change, and a restricted session is restricted
+        // from its first event, not from its first poll).
+        applyAccess(accessGrants)
+        // Shared clipboard (text v1): only when the user setting is on AND the session's access
+        // includes the clipboard AND the host has a working clipboard service. Ungranted, the
+        // host's policy resolution declines everything anyway (grants AND into it); not starting
+        // the sync is the client-side mirror — no offers announced, no poll thread for a plane
+        // that cannot move. Applied at session start only, like the host's own coordinator gate.
+        val clip = if (session.clipboardSync &&
+            accessGrants and SessionAccess.CLIPBOARD != 0 &&
+            NativeBridge.nativeClipSupported(handle)
+        ) {
             ClipboardSync(context, handle).also { it.start() }
         } else {
             null
@@ -603,8 +691,11 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                         ),
                     )
                 }
-                ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_CONNECT) ==
-                    PackageManager.PERMISSION_GRANTED -> {
+                // No USB pad: fall back to a bonded BLE one. The Bluetooth-permission gate lives
+                // inside pairedBleAddress() (it answers null, and says why, when the grant is
+                // missing) rather than being restated here — the grant itself is asked for where
+                // a user can act on it, in the console UI and the Controllers screen.
+                else -> {
                     sc2.pairedBleAddress()?.let { addr ->
                         Log.i("punktfunk", "SC2: no USB pad — using the paired BLE controller $addr")
                         sc2.startBle(addr)
@@ -708,6 +799,7 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
             activity?.remotePointer = null
             decor?.pointerIcon = priorPointerIcon
             activity?.streamHandle = 0L
+            activity?.streamAccess = SessionAccess.ALL // grants are per session, like the handle
             activity?.requestStreamExit = null
             // Back in the menus: the SC2 (if present) resumes driving the console UI.
             activity?.startSc2MenuNav()
@@ -825,8 +917,13 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                                     ?: (runCatching { context.display }.getOrNull()?.refreshRate ?: 0f)
                                         .roundToInt(),
                             )
-                            NativeBridge.nativeStartAudio(handle, lowLatencyMode)
-                            if (micWanted) {
+                            NativeBridge.nativeStartAudio(handle, lowLatencyMode, isTv)
+                            // The MIC grant is read live (a surface recreate re-runs this, and
+                            // the mask may have changed since the last one): without it no
+                            // capture opens — the host never attached this session to its mic
+                            // service, so the platform's recording indicator would announce a
+                            // mic nobody can hear.
+                            if (micWanted && accessGrants and SessionAccess.MIC != 0) {
                                 val sessionId =
                                     NativeBridge.nativeStartMic(handle, initialSettings.echoCancel)
                                 if (initialSettings.echoCancel) {
@@ -890,6 +987,22 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                 )
             }
         }
+        // The Access chip — what this session is allowed to do, said in the preset vocabulary
+        // ("Controller only · 1 h 58 m left"), standing for the whole stream. Full control with
+        // no expiry — every session against an old host, and most against a new one — shows
+        // NOTHING: the chip exists for the sessions where input silently not landing needs an
+        // explanation, not as new chrome on everyone's stream. TopEnd, in the shared pill family
+        // (TopStart is the HUD's, TopCentre the transient cues', BottomCentre the banner's).
+        val accessChip = when {
+            accessGrants and SessionAccess.ALL == SessionAccess.ALL && accessRemaining == 0 -> null
+            accessRemaining > 0 ->
+                "${SessionAccess.label(accessGrants)} · " +
+                    "${SessionAccess.remainingLabel(accessRemaining)} left"
+            else -> SessionAccess.label(accessGrants)
+        }
+        if (accessChip != null) {
+            AccessChip(accessChip, Modifier.align(Alignment.TopEnd).padding(12.dp))
+        }
         // "Hold to quit" hint while the gamepad exit chord is armed — the exit debounces on a ~1 s
         // hold, so without this cue a couch user reads the (deliberately no-longer-instant) chord as
         // broken. Purely visual; it sits above the video and below the gesture layer.
@@ -907,7 +1020,7 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
         // Above the video and below the gesture layer: it teaches touches, it must never eat one.
         //
         // Bottom-centre is the desktop's placement and the only edge left — TopStart is the HUD,
-        // TopEnd the mic badge, TopCentre the three transient cues — but MotionUnreachableHint
+        // TopEnd the Access chip, TopCentre the three transient cues — but MotionUnreachableHint
         // already owns it, and both of these can be up at t≈0. The banner YIELDS rather than
         // stacking or sliding off-centre: the notice reports something broken about THIS session
         // and names the setting that fixes it, while the banner repeats shortcuts that will be
@@ -928,8 +1041,13 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                         // button — all land on the same BackHandler).
                         add("Back leaves the stream")
                         // The tap lives in the pointer touch models only — passthrough gives every
-                        // finger to the host verbatim — and needs a screen to put three fingers on.
-                        if (hasTouch && touchMode != TouchMode.TOUCH) add("three-finger tap for stats")
+                        // finger to the host verbatim — and needs a screen to put three fingers on,
+                        // plus the POINTER grant (without it the gesture layer is not installed).
+                        if (hasTouch && touchMode != TouchMode.TOUCH &&
+                            accessGrants and SessionAccess.POINTER != 0
+                        ) {
+                            add("three-finger tap for stats")
+                        }
                     }
                 }.joinToString(" · "),
                 alpha = bannerAlpha,
@@ -960,40 +1078,45 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
         // Stylus lane (design/pen-tablet-input.md §7): against a HOST_CAP_PEN host a stylus
         // splits out of BOTH touch models onto the pen plane; its heartbeat coroutine keeps a
         // stationary held stroke alive (and its cancellation lifts everything on teardown).
-        val stylus = remember(handle) {
-            if (NativeBridge.nativeHostSupportsPen(handle)) StylusStream(handle) else null
+        // The POINTER grant gates the whole touch/stylus capture layer — "don't capture what
+        // can't land": ungranted, no gesture handler is installed at all (and no pen lane opens),
+        // rather than fingers being read into events the host will drop. Keyed on the grant so an
+        // AccessUpdate flipping it mid-session swaps the layer live.
+        val pointerOk = accessGrants and SessionAccess.POINTER != 0
+        val stylus = remember(handle, pointerOk) {
+            if (pointerOk && NativeBridge.nativeHostSupportsPen(handle)) StylusStream(handle) else null
         }
         if (stylus != null) {
             LaunchedEffect(stylus) { stylus.heartbeatLoop() }
         }
         Box(
-            videoFit.pointerInput(handle, touchMode) {
-                when (touchMode) {
-                    TouchMode.TOUCH -> streamTouchPassthrough(handle, stylus)
+            videoFit.pointerInput(handle, touchMode, pointerOk) {
+                when {
+                    !pointerOk -> {} // no capture — the Access chip is what says why
+                    touchMode == TouchMode.TOUCH -> streamTouchPassthrough(handle, stylus)
                     else -> streamTouchInput(
                         handle,
                         stylus,
                         trackpad = touchMode == TouchMode.TRACKPAD,
                         invertScroll = initialSettings.invertScroll,
                         onCycleStats = { statsVerbosity = statsVerbosity.next() },
-                        onKeyboard = { show -> keyCapture?.setImeVisible(show) },
+                        // The summon rides the pointer gesture but TYPES — so it also needs the
+                        // KEYBOARD grant (dismissing is always allowed).
+                        onKeyboard = { show ->
+                            if (!show || accessGrants and SessionAccess.KEYBOARD != 0) {
+                                keyCapture?.setImeVisible(show)
+                            }
+                        },
                     )
                 }
             },
         )
-        // 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 +1153,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.
  */
@@ -1086,6 +1170,25 @@ private fun MicChordHint(text: String, modifier: Modifier = Modifier) {
     )
 }
 
+/**
+ * The standing Access chip — the session's access level in the preset vocabulary, with the live
+ * countdown when the grant expires ("Controller only · 1 h 58 m left"). Same pill family as the
+ * other in-stream overlays, sized down a step because it stands for the whole session rather than
+ * flashing a moment's confirmation. Only composed when there is something to say: a full-control
+ * permanent session — today's normal — shows nothing at all.
+ */
+@Composable
+private fun AccessChip(text: String, modifier: Modifier = Modifier) {
+    Text(
+        text,
+        modifier = modifier
+            .background(Color.Black.copy(alpha = 0.55f), RoundedCornerShape(8.dp))
+            .padding(horizontal = 10.dp, vertical = 5.dp),
+        color = Color.White,
+        fontSize = 12.sp,
+    )
+}
+
 /**
  * "This pad's gyro can't reach the game" — shown briefly when a captured controller with motion
  * meets a session whose virtual pad has no motion plane (the X-Box classes have no gyro in their

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

@@ -0,0 +1,98 @@
+package io.unom.punktfunk
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * [sc2BluetoothGrantOffered] is pure — table-tested over its inputs.
+ *
+ * The rule exists because a Steam Controller 2 paired over Bluetooth is invisible to this client
+ * until `BLUETOOTH_CONNECT` is granted (the bonded list answers "nothing is paired" rather than
+ * refusing), and nothing ever asked for it — so the pad silently never engaged while the same
+ * controller over USB worked. The offer has to reach those users without becoming a Bluetooth
+ * prompt for everyone else, which is the whole content of these assertions.
+ */
+class Sc2BluetoothGrantTest {
+
+    /** The reported case: an SC2 sitting in lizard mode that we cannot capture. */
+    @Test
+    fun offeredWhenAnSc2IsAttachedButBluetoothIsNot() {
+        assertTrue(
+            sc2BluetoothGrantOffered(
+                permissionGranted = false,
+                usbSc2 = false,
+                sc2Attached = true,
+                anyPadDetected = false,
+            ),
+        )
+        // Still offered next to other working pads — the SC2 is the one we can't reach.
+        assertTrue(
+            sc2BluetoothGrantOffered(
+                permissionGranted = false,
+                usbSc2 = false,
+                sc2Attached = true,
+                anyPadDetected = true,
+            ),
+        )
+    }
+
+    /**
+     * The probe reads an SC2's USB identity, which we cannot assume a BLE stack reports. When it
+     * misses, "no controller detected" is exactly when a blind spot is worth naming.
+     */
+    @Test
+    fun offeredWhenNothingWasDetectedAtAll() {
+        assertTrue(
+            sc2BluetoothGrantOffered(
+                permissionGranted = false,
+                usbSc2 = false,
+                sc2Attached = false,
+                anyPadDetected = false,
+            ),
+        )
+    }
+
+    /** Never a prompt for someone with working controllers and no sign of an SC2. */
+    @Test
+    fun notOfferedToUsersWithNoSignOfAnSc2() {
+        assertFalse(
+            sc2BluetoothGrantOffered(
+                permissionGranted = false,
+                usbSc2 = false,
+                sc2Attached = false,
+                anyPadDetected = true,
+            ),
+        )
+    }
+
+    /** Granting it changes nothing that is already captured over USB — wired and Puck alike. */
+    @Test
+    fun notOfferedWhenTheSc2IsOnUsb() {
+        assertFalse(
+            sc2BluetoothGrantOffered(
+                permissionGranted = false,
+                usbSc2 = true,
+                sc2Attached = true,
+                anyPadDetected = false,
+            ),
+        )
+    }
+
+    /** Nothing to ask for once it is held — including on releases that grant it at install time. */
+    @Test
+    fun notOfferedOncePermitted() {
+        for (attached in listOf(true, false)) {
+            for (pads in listOf(true, false)) {
+                assertFalse(
+                    sc2BluetoothGrantOffered(
+                        permissionGranted = true,
+                        usbSc2 = false,
+                        sc2Attached = attached,
+                        anyPadDetected = pads,
+                    ),
+                )
+            }
+        }
+    }
+}

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

@@ -34,19 +34,34 @@ class ScreenshotTest {
     // cursor via an infinite animation that otherwise keeps Compose perpetually "busy", so
     // setContent's wait-for-idle never returns. Frozen, the capture is also deterministic.
 
-    /** Full-screen content scenes: the compose root fills the device, so a root capture is the shot. */
-    private fun shootRoot(name: String, content: @androidx.compose.runtime.Composable () -> Unit) {
+    /**
+     * Full-screen content scenes: the compose root fills the device, so a root capture is the
+     * shot. [statusBar] draws the fake system bar and pushes content below it (see
+     * [ShotStatusFrame]) — off for the immersive surfaces (stream, console shell), which hide
+     * the real bar too.
+     */
+    private fun shootRoot(
+        name: String,
+        statusBar: Boolean = true,
+        content: @androidx.compose.runtime.Composable () -> Unit,
+    ) {
         compose.mainClock.autoAdvance = false
-        compose.setContent { ShotTheme(content) }
+        compose.setContent { ShotTheme { if (statusBar) ShotStatusFrame(content) else content() } }
         compose.mainClock.advanceTimeBy(800)
         compose.onRoot().captureRoboImage("$out/phone-$name.png")
     }
 
     /** Dialog scenes: the AlertDialog is a separate window, so capture the whole screen (all windows). */
-    private fun shootScreen(name: String, content: @androidx.compose.runtime.Composable () -> Unit) {
+    private fun shootScreen(
+        name: String,
+        statusBar: Boolean = true,
+        content: @androidx.compose.runtime.Composable () -> Unit,
+    ) {
         compose.mainClock.autoAdvance = false
-        compose.setContent { ShotTheme(content) }
-        compose.mainClock.advanceTimeBy(800)
+        compose.setContent { ShotTheme { if (statusBar) ShotStatusFrame(content) else content() } }
+        // 1.6 s, not 0.8: a ModalBottomSheet's entrance spring is still mid-rise at 0.8 s and the
+        // add-host sheet's Connect button was captured half below the frame.
+        compose.mainClock.advanceTimeBy(1600)
         captureScreenRoboImage("$out/phone-$name.png")
     }
 
@@ -73,25 +88,25 @@ class ScreenshotTest {
 
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi") // landscape — the stream is immersive
-    fun stream() = shootRoot("stream") { StreamScene(io.unom.punktfunk.StatsVerbosity.DETAILED) }
+    fun stream() = shootRoot("stream", statusBar = false) { StreamScene(io.unom.punktfunk.StatsVerbosity.DETAILED) }
 
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
-    fun streamCompact() = shootRoot("stream-compact") { StreamScene(io.unom.punktfunk.StatsVerbosity.COMPACT) }
+    fun streamCompact() = shootRoot("stream-compact", statusBar = false) { StreamScene(io.unom.punktfunk.StatsVerbosity.COMPACT) }
 
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
-    fun streamNormal() = shootRoot("stream-normal") { StreamScene(io.unom.punktfunk.StatsVerbosity.NORMAL) }
+    fun streamNormal() = shootRoot("stream-normal", statusBar = false) { StreamScene(io.unom.punktfunk.StatsVerbosity.NORMAL) }
 
     // Both banner texts, in the stream's own landscape geometry — it is bottom-centre, so the
     // aspect is load-bearing.
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
-    fun streamBannerPad() = shootRoot("stream-banner-pad") { StreamBannerScene(pad = true) }
+    fun streamBannerPad() = shootRoot("stream-banner-pad", statusBar = false) { StreamBannerScene(pad = true) }
 
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
-    fun streamBannerTouch() = shootRoot("stream-banner-touch") { StreamBannerScene(pad = false) }
+    fun streamBannerTouch() = shootRoot("stream-banner-touch", statusBar = false) { StreamBannerScene(pad = false) }
 
     // The touch flow is a Material dialog over the host grid (a separate window → shootScreen).
     @Test
@@ -114,15 +129,15 @@ class ScreenshotTest {
 
     // The console flow is the full-screen aurora takeover (a root capture).
     @Test
-    fun connectingConsole() = shootRoot("connecting-console") { ConnectConsoleScene() }
+    fun connectingConsole() = shootRoot("connecting-console", statusBar = false) { ConnectConsoleScene() }
 
     @Test
-    fun consoleSettings() = shootRoot("console-settings") { ConsoleSettingsScene() }
+    fun consoleSettings() = shootRoot("console-settings", statusBar = false) { ConsoleSettingsScene() }
 
     /** A PALE palette: the whole UI flips to dark ink on white frost, which only a shot proves. */
     @Test
     fun consoleSettingsLight() =
-        shootRoot("console-settings-light") { ConsoleSettingsScene(paletteId = "holo") }
+        shootRoot("console-settings-light", statusBar = false) { ConsoleSettingsScene(paletteId = "holo") }
 
     /**
      * Landscape — the orientation the console actually runs in, and a DIFFERENT layout since the
@@ -132,16 +147,16 @@ class ScreenshotTest {
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
     fun consoleSettingsLandscape() =
-        shootRoot("console-settings-landscape") { ConsoleSettingsScene() }
+        shootRoot("console-settings-landscape", statusBar = false) { ConsoleSettingsScene() }
 
     // The console home, the screen the living backdrop is most of. The default sdk (36) draws the
     // real AGSL MESH field; the paired API-31 shot below draws the blob fallback, so the two
     // renderings of the same palette can be compared rather than assumed equivalent.
     @Test
-    fun consoleHome() = shootRoot("console-home") { ConsoleHomeScene() }
+    fun consoleHome() = shootRoot("console-home", statusBar = false) { ConsoleHomeScene() }
 
     @Test
-    fun consoleHomeLight() = shootRoot("console-home-light") { ConsoleHomeScene(paletteId = "holo") }
+    fun consoleHomeLight() = shootRoot("console-home-light", statusBar = false) { ConsoleHomeScene(paletteId = "holo") }
 
     /**
      * Landscape — the orientation the console UI actually runs in, and the only one wide enough to
@@ -149,7 +164,7 @@ class ScreenshotTest {
      */
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
-    fun consoleHomeLandscape() = shootRoot("console-home-landscape") { ConsoleHomeScene() }
+    fun consoleHomeLandscape() = shootRoot("console-home-landscape", statusBar = false) { ConsoleHomeScene() }
 
     /**
      * The API 31/32 field. `RuntimeShader` is API 33+, so everything below it keeps the four
@@ -158,24 +173,46 @@ class ScreenshotTest {
      */
     @Test
     @Config(sdk = [31], qualifiers = "w360dp-h800dp-xxhdpi")
-    fun consoleHomeBlobFallback() = shootRoot("console-home-blobs") { ConsoleHomeScene() }
+    fun consoleHomeBlobFallback() = shootRoot("console-home-blobs", statusBar = false) { ConsoleHomeScene() }
 
     // The two screens the console reached for the first time in WP8.3. Each is shot on a dark AND a
     // pale palette, because the console draws them through a ColorScheme derived from the palette's
     // ink — and the pale one is the only place a grey-on-pastel slip can show up.
     @Test
-    fun consoleLicenses() = shootRoot("console-licenses") { ConsoleLicensesScene() }
+    fun consoleLicenses() = shootRoot("console-licenses", statusBar = false) { ConsoleLicensesScene() }
 
     @Test
     fun consoleLicensesLight() =
-        shootRoot("console-licenses-light") { ConsoleLicensesScene(paletteId = "holo") }
+        shootRoot("console-licenses-light", statusBar = false) { ConsoleLicensesScene(paletteId = "holo") }
 
     @Test
-    fun consoleControllers() = shootRoot("console-controllers") { ConsoleControllersScene() }
+    fun consoleControllers() = shootRoot("console-controllers", statusBar = false) { ConsoleControllersScene() }
+
+    /**
+     * The touch presentation, pads connected — landscape, like every store frame: the app is
+     * built for horizontal use, and a portrait capture shows a layout nobody streams in.
+     */
+    @Test
+    @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
+    fun controllers() = shootRoot("controllers") { ControllersScene() }
+
+    /** The console presentation at the same landscape geometry — the store's FEEL THE GAME frame. */
+    @Test
+    @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
+    fun consoleControllersLandscape() =
+        shootRoot("console-controllers-landscape", statusBar = false) { ConsoleControllersScene() }
+
+    /**
+     * The library coverflow with a mock shelf — the store's PICK & PLAY frame. Landscape: the
+     * orientation the coverflow actually runs in, and the only one wide enough for neighbours.
+     */
+    @Test
+    @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
+    fun library() = shootRoot("library", statusBar = false) { LibraryScene() }
 
     @Test
     fun consoleControllersLight() =
-        shootRoot("console-controllers-light") { ConsoleControllersScene(paletteId = "holo") }
+        shootRoot("console-controllers-light", statusBar = false) { ConsoleControllersScene(paletteId = "holo") }
 
     @Test
     fun trust() = shootScreen("trust") {
@@ -197,4 +234,13 @@ class ScreenshotTest {
         HostsScene()
         PairDialog()
     }
+
+    /**
+     * The add-host sheet (separate window → whole-screen capture). Pixel-like geometry, not the
+     * default 360×800dp: same 1080×2400 px, but at 420 dpi the extra dp headroom is what lets the
+     * sheet's Connect button — the row that carries the resolution promise — fit in frame.
+     */
+    @Test
+    @Config(sdk = [36], qualifiers = "w411dp-h915dp-420dpi")
+    fun addHost() = shootScreen("add-host") { AddHostScene() }
 }

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

@@ -1,14 +1,35 @@
 package io.unom.punktfunk.screenshots
 
+import android.content.Context
+import android.content.res.Configuration
+import android.graphics.Bitmap
+import android.graphics.BlendMode
+import android.graphics.Canvas
+import android.graphics.LinearGradient
+import android.graphics.Paint
+import android.graphics.Path
+import android.graphics.RadialGradient
+import android.graphics.Shader
+import android.graphics.Typeface
+import android.graphics.drawable.BitmapDrawable
+import android.graphics.drawable.ColorDrawable
+import android.graphics.drawable.Drawable
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.BatteryFull
+import androidx.compose.material.icons.filled.SignalCellular4Bar
+import androidx.compose.material.icons.filled.Wifi
+import androidx.compose.material3.Icon
 import androidx.compose.foundation.lazy.grid.GridCells
 import androidx.compose.foundation.lazy.grid.GridItemSpan
 import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
@@ -35,8 +56,27 @@ import androidx.compose.runtime.CompositionLocalProvider
 import io.unom.punktfunk.GamepadHome
 import io.unom.punktfunk.GamepadInk
 import io.unom.punktfunk.GamepadPalette
+import coil.ImageLoader
+import coil.test.FakeImageLoaderEngine
+import dev.chrisbanes.haze.HazeState
+import dev.chrisbanes.haze.hazeSource
+import io.unom.punktfunk.AddHostSheet
 import io.unom.punktfunk.ConsoleControllersScreen
+import io.unom.punktfunk.ConsoleHeader
+import io.unom.punktfunk.ConsoleLegendInset
 import io.unom.punktfunk.ConsoleLicensesScreen
+import io.unom.punktfunk.ControllersScreen
+import io.unom.punktfunk.Coverflow
+import io.unom.punktfunk.GamepadAuroraBackground
+import io.unom.punktfunk.GamepadHintBar
+import io.unom.punktfunk.PadGlyph
+import io.unom.punktfunk.PadInfo
+import io.unom.punktfunk.consoleLegendInsets
+import io.unom.punktfunk.consoleSafeArea
+import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.library.Artwork
+import io.unom.punktfunk.kit.library.GameEntry
+import androidx.compose.ui.platform.LocalConfiguration
 import io.unom.punktfunk.GamepadSettingsScreen
 import io.unom.punktfunk.HomeTile
 import io.unom.punktfunk.LocalGamepadInk
@@ -70,6 +110,51 @@ internal fun ShotTheme(content: @Composable () -> Unit) {
     MaterialTheme(colorScheme = BrandDark, content = content)
 }
 
+/**
+ * Robolectric has no system UI, so every capture was missing the status bar and the content sat
+ * where the bar belongs — on the Pixel render the app title collided with the camera punch-hole.
+ * This frame draws a plausible bar (time left, radios right, the CENTRE left empty for the hole)
+ * and pushes the scene below it, the same geometry real insets produce. The height mirrors a
+ * Pixel's tall bar as measured off a real 1344×2992 capture (~145 px ≈ 40 dp).
+ */
+@Composable
+internal fun ShotStatusFrame(content: @Composable () -> Unit) {
+    Column(Modifier.fillMaxSize().background(MaterialTheme.colorScheme.background)) {
+        Row(
+            Modifier.fillMaxWidth().height(40.dp).padding(horizontal = 28.dp),
+            horizontalArrangement = Arrangement.SpaceBetween,
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Text(
+                "21:47",
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onBackground.copy(alpha = 0.9f),
+            )
+            Row(
+                horizontalArrangement = Arrangement.spacedBy(5.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                Icon(
+                    Icons.Filled.Wifi, contentDescription = null,
+                    tint = MaterialTheme.colorScheme.onBackground.copy(alpha = 0.9f),
+                    modifier = Modifier.size(15.dp),
+                )
+                Icon(
+                    Icons.Filled.SignalCellular4Bar, contentDescription = null,
+                    tint = MaterialTheme.colorScheme.onBackground.copy(alpha = 0.9f),
+                    modifier = Modifier.size(14.dp),
+                )
+                Icon(
+                    Icons.Filled.BatteryFull, contentDescription = null,
+                    tint = MaterialTheme.colorScheme.onBackground.copy(alpha = 0.9f),
+                    modifier = Modifier.size(16.dp),
+                )
+            }
+        }
+        Box(Modifier.weight(1f).fillMaxWidth()) { content() }
+    }
+}
+
 private data class MockHost(
     val name: String,
     val address: String,
@@ -510,8 +595,8 @@ internal fun ConsoleHomeScene(paletteId: String = "violet") {
  * whole risk. Their touch presentation is inked by the app theme, which is always dark, so nothing
  * before this could catch light-grey body text stranded on a pastel field.
  *
- * Robolectric enumerates no input devices, so the controllers scene renders its deterministic
- * "nothing connected" state.
+ * Robolectric enumerates no input devices, so the controllers scenes inject [shotPads] — the
+ * deterministic connected-pads state the store listing needs.
  */
 @Composable
 internal fun ConsoleLicensesScene(paletteId: String = "violet") =
@@ -520,14 +605,358 @@ internal fun ConsoleLicensesScene(paletteId: String = "violet") =
 @Composable
 internal fun ConsoleControllersScene(paletteId: String = "violet") =
     ConsolePalette(paletteId) {
-        ConsoleControllersScreen(gamepadSetting = 0, onBack = {}, navActive = false)
+        // Robolectric enumerates no input devices, so the shot injects the two pads the store
+        // listing talks about — the empty "no controller detected" state proves the palette but
+        // sells nothing.
+        ConsoleControllersScreen(
+            gamepadSetting = 0, onBack = {}, navActive = false, padsOverride = shotPads(),
+        )
     }
 
+/**
+ * The touch presentation of the same screen, with the same injected pads. Wrapped in a background
+ * [Surface]: the activity provides the dark ground in the app, and without one here the content
+ * color falls back to black-on-white while the cards stay dark.
+ */
+@Composable
+internal fun ControllersScene() =
+    Surface(color = MaterialTheme.colorScheme.background) {
+        ControllersScreen(gamepadSetting = 0, onBack = {}, padsOverride = shotPads())
+    }
+
+/**
+ * The "Add a host" bottom sheet over the host grid — the store's onboarding frame. State is
+ * hoisted in production (ConnectScreen), so the scene passes a filled-in form directly; the
+ * mode label mirrors what a paired 120 Hz phone shows on the connect button.
+ */
+@Composable
+internal fun AddHostScene() {
+    HostsScene()
+    AddHostSheet(
+        hostName = "Living Room PC", onHostNameChange = {},
+        host = "192.168.1.42", onHostChange = {},
+        port = "9777", onPortChange = {},
+        connecting = false, modeLabel = "2992×1344@120",
+        onDismiss = {}, onConnect = { _, _, _ -> },
+    )
+}
+
+/** The two pads the store listing names: DualSense (adaptive triggers, LEDs, rumble) and Xbox. */
+internal fun shotPads() = listOf(
+    PadInfo(
+        name = "DualSense Wireless Controller",
+        detail = "054C:0CE6 · gamepad · joystick",
+        forwarded = true, controllerNumber = 1,
+        resolvedPref = Gamepad.PREF_DUALSENSE, canRumble = true,
+    ),
+    PadInfo(
+        name = "Xbox Wireless Controller",
+        detail = "045E:0B13 · gamepad · joystick",
+        forwarded = true, controllerNumber = 2,
+        resolvedPref = Gamepad.PREF_XBOXONE, canRumble = true,
+    ),
+)
+
 /**
  * Publish the palette locals `App` would normally provide. A scene that calls a console screen
  * directly gets the DEFAULT dark ink without this, and a pale-palette shot would then silently
  * prove nothing at all.
  */
+/**
+ * The game-library coverflow (the real [Coverflow] over the real console chrome) with a mock shelf.
+ * The library screen itself can't be shot — its state comes off the network — so the scene rebuilds
+ * the same shell [io.unom.punktfunk.LibraryScreen] draws around it: aurora, header, floating hint
+ * bar. Cover art is answered synchronously by coil-test's [FakeImageLoaderEngine] with generated
+ * posters, so the frozen animation clock never races an async load.
+ */
+@Composable
+internal fun LibraryScene(paletteId: String = "violet") = ConsolePalette(paletteId) {
+    val context = LocalContext.current
+    val loader = remember { shotLibraryLoader(context) }
+    val games = remember { shotGames() }
+    val hazeState = remember { HazeState() }
+    val landscape =
+        LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
+    Box(Modifier.fillMaxSize()) {
+        Box(Modifier.fillMaxSize().hazeSource(hazeState)) {
+            GamepadAuroraBackground(Modifier.fillMaxSize())
+            Column(Modifier.fillMaxSize().consoleSafeArea()) {
+                ConsoleHeader("Living Room PC — Library")
+                Box(Modifier.weight(1f).fillMaxWidth(), contentAlignment = Alignment.Center) {
+                    Coverflow(games, loader, navActive = false, onLaunch = {})
+                }
+            }
+        }
+        Box(
+            Modifier.align(Alignment.BottomStart)
+                .consoleLegendInsets(landscape)
+                .padding(ConsoleLegendInset),
+        ) {
+            GamepadHintBar(
+                listOf(PadGlyph.hint('A', "Launch"), PadGlyph.hint('B', "Close")),
+                hazeState = hazeState,
+            )
+        }
+    }
+}
+
+/** A believable shelf: four titles with art plus the Steam launcher entry (brand-mark tile). */
+private fun shotGames() = listOf(
+    GameEntry("custom:aurora", "custom", "Aurora Drift", Artwork("shot://art/aurora", null, null)),
+    GameEntry("steam:starfall", "steam", "Starfall Vale", Artwork("shot://art/starfall", null, null)),
+    GameEntry("heroic:neon", "heroic", "Neon Circuit", Artwork("shot://art/neon", null, null)),
+    GameEntry("gog:ember", "gog", "Ember Peaks", Artwork("shot://art/ember", null, null)),
+    GameEntry("steam:launcher", "steam", "Steam", Artwork(null, null, null), role = "launcher", icon = "steam"),
+)
+
+private fun shotLibraryLoader(context: Context): ImageLoader {
+    val engine = FakeImageLoaderEngine.Builder()
+        .intercept("shot://art/aurora", poster(context, "AURORA DRIFT", ::drawAurora))
+        .intercept("shot://art/starfall", poster(context, "STARFALL VALE", ::drawStarfall))
+        .intercept("shot://art/neon", poster(context, "NEON CIRCUIT", ::drawNeon))
+        .intercept("shot://art/ember", poster(context, "EMBER PEAKS", ::drawEmber))
+        .default(ColorDrawable(0xFF221E44.toInt()))
+        .build()
+    return ImageLoader.Builder(context).components { add(engine) }.build()
+}
+
+// The four shelf posters, drawn procedurally at capture time — the same designs the Apple
+// harness draws with CoreGraphics (`ShotPosterArt.swift`), so both listings show the same shelf.
+// All geometry below is in a 600×900, y-UP space (matching the CG source); `posterY()` flips it.
+
+private const val POSTER_W = 600
+private const val POSTER_H = 900
+
+private fun posterY(v: Float) = POSTER_H - v
+
+/** Deterministic LCG (same constants and seeds as the Swift twin) so every capture is identical. */
+private class ShotRand(var state: ULong) {
+    fun next(): Float {
+        state = state * 6364136223846793005UL + 1442695040888963407UL
+        return (state shr 33).toFloat() / (1L shl 31).toFloat()
+    }
+    fun range(lo: Float, hi: Float) = lo + next() * (hi - lo)
+}
+
+private fun poster(context: Context, title: String, draw: (Canvas) -> Unit): Drawable {
+    val bmp = Bitmap.createBitmap(POSTER_W, POSTER_H, Bitmap.Config.ARGB_8888)
+    val canvas = Canvas(bmp)
+    draw(canvas)
+    posterTitle(canvas, title)
+    return BitmapDrawable(context.resources, bmp)
+}
+
+/** Vertical gradient over the full canvas; stops bottom-to-top as (location, color). */
+private fun sky(canvas: Canvas, stops: List<Pair<Float, Int>>) {
+    canvas.drawRect(
+        0f, 0f, POSTER_W.toFloat(), POSTER_H.toFloat(),
+        Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            shader = LinearGradient(
+                0f, POSTER_H.toFloat(), 0f, 0f,
+                stops.map { it.second }.toIntArray(),
+                stops.map { it.first }.toFloatArray(),
+                Shader.TileMode.CLAMP,
+            )
+        },
+    )
+}
+
+private fun glowDot(canvas: Canvas, x: Float, y: Float, radius: Float, color: Int) {
+    canvas.drawCircle(
+        x, posterY(y), radius,
+        Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            shader = RadialGradient(
+                x, posterY(y), radius, color, color and 0x00FFFFFF, Shader.TileMode.CLAMP,
+            )
+        },
+    )
+}
+
+private fun shotAlpha(color: Int, a: Float) = (color and 0x00FFFFFF) or ((a * 255).toInt() shl 24)
+
+/** Three strokes, wide-and-faint to thin-and-bright, in screen blend — the cheap neon glow. */
+private fun glowStroke(canvas: Canvas, path: Path, width: Float, color: Int) {
+    for ((mult, a) in listOf(2.6f to 0.12f, 1.3f to 0.28f, 0.55f to 0.85f)) {
+        canvas.drawPath(
+            path,
+            Paint(Paint.ANTI_ALIAS_FLAG).apply {
+                style = Paint.Style.STROKE
+                strokeCap = Paint.Cap.ROUND
+                strokeJoin = Paint.Join.ROUND
+                strokeWidth = width * mult
+                this.color = shotAlpha(color, a)
+                blendMode = BlendMode.SCREEN
+            },
+        )
+    }
+}
+
+private fun posterTitle(canvas: Canvas, title: String) {
+    sky(canvas, listOf(0f to shotAlpha(0x000000, 0.55f), 0.22f to shotAlpha(0x000000, 0f)))
+    canvas.drawText(
+        title, POSTER_W / 2f, posterY(72f),
+        Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = shotAlpha(0xFFFFFF, 0.94f)
+            textSize = 46f
+            letterSpacing = 5f / 46f
+            typeface = Typeface.create("sans-serif-condensed", Typeface.BOLD)
+            textAlign = Paint.Align.CENTER
+            setShadowLayer(8f, 0f, 2f, shotAlpha(0x000000, 0.6f))
+        },
+    )
+}
+
+private fun drawAurora(canvas: Canvas) {
+    sky(canvas, listOf(0f to 0xFF221E5C.toInt(), 0.45f to 0xFF141040.toInt(), 1f to 0xFF0B0830.toInt()))
+    val rng = ShotRand(11UL)
+    repeat(48) {
+        val x = rng.range(0f, 600f)
+        val y = rng.range(300f, 890f)
+        val r = rng.range(1.4f, 3.2f)
+        glowDot(canvas, x, y, r, shotAlpha(0xFFFFFF, rng.range(0.25f, 0.8f)))
+    }
+    data class Ribbon(
+        val base: Float, val amp: Float, val freq: Float,
+        val phase: Float, val w: Float, val c: Int,
+    )
+    for (r in listOf(
+        Ribbon(700f, 55f, 1.15f, 0.4f, 30f, 0xFF6656F2.toInt()),
+        Ribbon(615f, 70f, 1.4f, 2.2f, 24f, 0xFF8F7BFF.toInt()),
+        Ribbon(530f, 45f, 0.95f, 4.1f, 18f, 0xFF35D0C5.toInt()),
+    )) {
+        val path = Path()
+        for (i in 0..60) {
+            val t = i / 60f
+            val x = t * 600f
+            val y = r.base + r.amp * kotlin.math.sin(t * Math.PI.toFloat() * r.freq + r.phase) + 40f * t
+            if (i == 0) path.moveTo(x, posterY(y)) else path.lineTo(x, posterY(y))
+        }
+        glowStroke(canvas, path, r.w, r.c)
+    }
+    // A low ridge grounds the scene — without it the poster's bottom half is bare sky.
+    for ((fill, baseline, rough) in listOf(
+        Triple(0xFF191345.toInt(), 212f, 30f),
+        Triple(0xFF0E0A2E.toInt(), 148f, 38f),
+    )) {
+        val path = Path()
+        path.moveTo(0f, posterY(0f))
+        path.lineTo(0f, posterY(baseline + rng.range(-rough, rough)))
+        for (i in 1..9) {
+            val x = i / 9f * 600f
+            path.lineTo(x, posterY(baseline + rng.range(-rough, rough)))
+        }
+        path.lineTo(600f, posterY(0f))
+        path.close()
+        canvas.drawPath(path, Paint(Paint.ANTI_ALIAS_FLAG).apply { color = fill })
+    }
+}
+
+private fun drawStarfall(canvas: Canvas) {
+    sky(
+        canvas,
+        listOf(
+            0f to 0xFF2A0C24.toInt(), 0.35f to 0xFF7A2B58.toInt(),
+            0.8f to 0xFFE86FA8.toInt(), 1f to 0xFFF7A8C8.toInt(),
+        ),
+    )
+    val rng = ShotRand(23UL)
+    repeat(6) {
+        val hx = rng.range(60f, 560f)
+        val hy = rng.range(420f, 840f)
+        val len = rng.range(90f, 170f)
+        val dx = kotlin.math.cos(2.15f)
+        val dy = kotlin.math.sin(2.15f)
+        val path = Path()
+        path.moveTo(hx, posterY(hy))
+        path.lineTo(hx + dx * len, posterY(hy + dy * len))
+        glowStroke(canvas, path, 4f, 0xFFFFE3EF.toInt())
+        glowDot(canvas, hx, hy, 11f, shotAlpha(0xFFFFFF, 0.9f))
+    }
+    for ((fill, baseline, rough) in listOf(
+        Triple(0xFF3A1430.toInt(), 300f, 26f),
+        Triple(0xFF1D0818.toInt(), 216f, 34f),
+    )) {
+        val path = Path()
+        path.moveTo(0f, posterY(0f))
+        path.lineTo(0f, posterY(baseline))
+        for (i in 1..8) {
+            val x = i / 8f * 600f
+            path.lineTo(x, posterY(baseline + rng.range(-rough, rough)))
+        }
+        path.lineTo(600f, posterY(0f))
+        path.close()
+        canvas.drawPath(path, Paint(Paint.ANTI_ALIAS_FLAG).apply { color = fill })
+    }
+}
+
+private fun drawNeon(canvas: Canvas) {
+    sky(canvas, listOf(0f to 0xFF0A2A33.toInt(), 1f to 0xFF04161C.toInt()))
+    val rng = ShotRand(7UL)
+    val ring = Path().apply {
+        addOval(300f - 105f, posterY(560f) - 105f, 300f + 105f, posterY(560f) + 105f, Path.Direction.CW)
+    }
+    glowStroke(canvas, ring, 10f, 0xFF35D0C5.toInt())
+    val gateX = listOf(-105f, 105f, 0f, 0f)
+    val gateY = listOf(0f, 0f, -105f, 105f)
+    for (i in 0 until 9) {
+        var px: Float
+        var py: Float
+        if (i < 4) {
+            px = 300f + gateX[i]
+            py = 560f + gateY[i]
+        } else {
+            px = 40f * kotlin.math.round(rng.range(1f, 14f))
+            py = 40f * kotlin.math.round(rng.range(1f, 21f))
+        }
+        val path = Path()
+        path.moveTo(px, posterY(py))
+        var horizontal = rng.next() > 0.5f
+        repeat(rng.range(3f, 6f).toInt()) {
+            val step = 40f * kotlin.math.round(rng.range(1f, 4f)) * (if (rng.next() > 0.5f) 1f else -1f)
+            if (horizontal) px = (px + step).coerceIn(20f, 580f) else py = (py + step).coerceIn(20f, 880f)
+            path.lineTo(px, posterY(py))
+            horizontal = !horizontal
+        }
+        val color = if (rng.next() > 0.6f) 0xFF7FE8DE.toInt() else 0xFF35D0C5.toInt()
+        glowStroke(canvas, path, 5f, color)
+        glowDot(canvas, px, py, 12f, shotAlpha(color, 0.9f))
+    }
+}
+
+private fun drawEmber(canvas: Canvas) {
+    sky(
+        canvas,
+        listOf(
+            0f to 0xFF200A04.toInt(), 0.3f to 0xFF7A2E12.toInt(),
+            0.42f to 0xFFEF8F4B.toInt(), 1f to 0xFF2A0E06.toInt(),
+        ),
+    )
+    glowDot(canvas, 300f, 385f, 160f, shotAlpha(0xFFC37A, 0.85f))
+    val rng = ShotRand(41UL)
+    for ((fill, baseline, rough) in listOf(
+        Triple(0xFF5A2410.toInt(), 340f, 42f),
+        Triple(0xFF401708.toInt(), 255f, 56f),
+        Triple(0xFF200A04.toInt(), 165f, 48f),
+    )) {
+        val path = Path()
+        path.moveTo(0f, posterY(0f))
+        path.lineTo(0f, posterY(baseline + rng.range(-rough, rough)))
+        for (i in 1..10) {
+            val x = i / 10f * 600f
+            path.lineTo(x, posterY(baseline + rng.range(-rough, rough)))
+        }
+        path.lineTo(600f, posterY(0f))
+        path.close()
+        canvas.drawPath(path, Paint(Paint.ANTI_ALIAS_FLAG).apply { color = fill })
+    }
+    repeat(20) {
+        val x = rng.range(30f, 570f)
+        val y = rng.range(180f, 620f)
+        val r = rng.range(2.5f, 6f)
+        glowDot(canvas, x, y, r, shotAlpha(0xFFB067, rng.range(0.35f, 0.9f)))
+    }
+}
+
 @Composable
 private fun ConsolePalette(paletteId: String, content: @Composable () -> Unit) {
     val palette = GamepadPalette.named(paletteId)

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

@@ -0,0 +1,59 @@
+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() }
+
+    /** The library coverflow at TV geometry — the store's PICK & PLAY frame for the TV listing. */
+    @Test
+    fun library() = shootRoot("library") { LibraryScene() }
+
+    @Test
+    fun connectingConsole() = shootRoot("connecting-console") { ConnectConsoleScene() }
+}

clients/android/ci/play-upload.py

@@ -9,7 +9,8 @@ tolerates it being raw JSON *or* base64-encoded JSON.
 Usage (upload a new build):
   SERVICE_ACCOUNT_JSON='<raw-or-base64 SA key>' \
     python3 play-upload.py --package io.unom.punktfunk \
-      --aab path/to/app-release.aab --track internal --status completed [--no-commit]
+      --aab path/to/app-release.aab --track beta --also-track alpha \
+      --status completed [--no-commit]
 
 Usage (promote a build that is already on Play, no rebuild):
   python3 play-upload.py --package io.unom.punktfunk \
@@ -164,6 +165,9 @@ def main():
     ap.add_argument("--promote-from", metavar="TRACK",
                     help="with --promote: assert the code is on TRACK, then clear TRACK")
     ap.add_argument("--track", default="internal")
+    ap.add_argument("--also-track", action="append", default=[], metavar="TRACK",
+                    help="assign the same versionCode to this track too, in the same edit "
+                         "(repeatable). Canary uses it to feed open + closed testing at once.")
     ap.add_argument("--status", default="completed")
     ap.add_argument("--user-fraction", type=float,
                     help="staged rollout fraction, 0<f<1; required by --status inProgress")
@@ -183,6 +187,11 @@ def main():
         sys.exit(f"ERROR: --user-fraction must be strictly between 0 and 1 (got {a.user_fraction})")
     if a.aab and not os.path.isfile(a.aab):
         sys.exit(f"ERROR: AAB not found: {a.aab}")
+    for t in a.also_track:
+        # `--also-track <promote-from>` would assign and clear the same track in one edit;
+        # whichever PUT lands second silently wins. Refuse the ambiguity instead.
+        if t in (a.track, a.promote_from):
+            sys.exit(f"ERROR: --also-track {t} duplicates --track/--promote-from")
 
     notes = load_release_notes(a.release_notes_file, a.release_notes_language) \
         if a.release_notes_file else None
@@ -209,6 +218,11 @@ def main():
         put_track(app, edit, tok, a.track, [vc], a.status, a.user_fraction, notes)
         print(f"assigned versionCode={vc} -> track={a.track} status={a.status}"
               + (f" userFraction={a.user_fraction}" if a.user_fraction is not None else ""))
+        # Same edit, so one commit (and one Play review) covers every track the code lands on —
+        # the tracks can never disagree about which canary is current.
+        for t in a.also_track:
+            put_track(app, edit, tok, t, [vc], a.status, a.user_fraction, notes)
+            print(f"assigned versionCode={vc} -> track={t} status={a.status}")
         # Same edit as the assignment above, so the code is never active on both tracks at once.
         if a.promote_from:
             put_track(app, edit, tok, a.promote_from, [], a.status)

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

@@ -105,9 +105,12 @@ class DeviceGyro(
                 for (i in 0..2) lastAccel[i] = Gamepad.motionAccelWire(v[i])
             }
             Sensor.TYPE_GYROSCOPE -> {
-                // The write gate, per sample: pad 0 must exist (motion never creates a pad)
-                // and must not be a capture link's (its own IMU is streaming).
-                val write = router.padPresent(0) && !router.padHasOwnMotion(0)
+                // The write gate, per sample: sends must be on at all (the forwarding
+                // preference AND the session's GAMEPAD grant — an AccessUpdate can revoke it
+                // mid-session), pad 0 must exist (motion never creates a pad) and must not be
+                // a capture link's (its own IMU is streaming).
+                val write = router.sendsEnabled() && router.padPresent(0) &&
+                    !router.padHasOwnMotion(0)
                 if (!write) {
                     // Stand-down edge: never leave the last angular velocity latched host-side.
                     if (wasWriting) {

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

@@ -195,6 +195,29 @@ object Gamepad {
     /** First connected gamepad/joystick [InputDevice], or null when none is attached. */
     fun firstPad(): InputDevice? = pads().firstOrNull()
 
+    /**
+     * True when a Steam Controller 2 is attached as an ORDINARY [InputDevice] — which, for a pad
+     * this client wants to capture, means an uncaptured one still in lizard mode.
+     *
+     * Deliberately not filtered by [isPad]: lizard mode emulates a keyboard and mouse, so an SC2
+     * is never a gamepad source and every other pad-shaped query in the client steps right past
+     * it. That is also why this is worth having — a wired or Puck SC2 is found by enumerating USB
+     * (no permission needed), but a BLE-paired one is invisible until `BLUETOOTH_CONNECT` is
+     * granted, and asking for Bluetooth on the chance that someone might own one is not something
+     * to put in front of every user. This is the permission-free signal that the pad is genuinely
+     * there, so the request can be made to the people it helps and to nobody else.
+     *
+     * A false negative is survivable by design (the Controllers screen offers the grant outright),
+     * so this matches only the identities we know rather than reaching for every Valve device — a
+     * Steam Deck's own controller and a classic Steam Controller are not SC2s and must not
+     * conjure a Bluetooth prompt.
+     */
+    fun sc2InputDevicePresent(): Boolean =
+        InputDevice.getDeviceIds().asSequence().mapNotNull { InputDevice.getDevice(it) }.any {
+            it.vendorId == VID_VALVE &&
+                (it.productId in PID_STEAMCONTROLLER2 || it.productId in PID_STEAMCONTROLLER2_PUCK)
+        }
+
     /**
      * The [GamepadPref] wire byte to send for the user's [setting] (the persisted gamepad index). A
      * non-Auto setting is passed through unchanged; "Automatic" ([PREF_AUTO]) resolves to a concrete
@@ -230,6 +253,46 @@ object Gamepad {
         else -> 0
     }
 
+    /**
+     * The BTN_* bit for one key event from a SOURCE_GAMEPAD device — [buttonBit] plus the
+     * Select-family button of every pad that carries no `BUTTON_SELECT` scancode at all.
+     *
+     * Plenty of controllers deliver that button as the plain `KEYCODE_BACK` a remote's Back uses,
+     * with no `BUTTON_SELECT` behind it: it is the Android-TV shape, where every input device is
+     * expected to offer Back, and a pad reaches it whether the vendor prints "Back" on the button
+     * (NVIDIA's SHIELD controller) or "Select"/"View" (most pads in an Android mode). Which one is
+     * on the couch cannot be told from here, and does not need to be — the keycode is what routes.
+     *
+     * Read through [buttonBit] alone that button mapped to nothing, so it fell out of the
+     * streaming branch unconsumed and reached the activity's back stack, which is the
+     * deliberate-quit exit: ONE press of Select dropped the session and the host logged a client
+     * quit. `KEYCODE_BACK` is in fact the ONLY keycode that can get there from a pad — a mapped
+     * button is consumed here, anything with a VK is consumed on the keycode path, volume/power go
+     * to the system, and a FLAG_FALLBACK BACK is swallowed — which is what identifies this as the
+     * cause of such a report without knowing the hardware.
+     *
+     * It also meant such a pad could not produce [BTN_BACK] at all, so every shortcut built on
+     * Select — the emergency exit chord this client's own start banner advertises, the mic mute,
+     * the stats tier — was unreachable on exactly the devices whose users have no keyboard.
+     *
+     * A pad that DOES carry `BUTTON_SELECT` is unaffected in both directions: it never had the
+     * bug, and this changes nothing for it.
+     *
+     * FLAG_FALLBACK events are excluded: those are the synthetic BACK the framework raises after
+     * an unconsumed `BUTTON_*` press (a pad reporting L2/R2 as keys, say), not a button anyone
+     * touched, and forwarding one would put a phantom Select on the wire. `MainActivity` drops
+     * them on the keycode path for the same reason.
+     *
+     * Callers must gate on `SOURCE_GAMEPAD` before asking, exactly as [buttonBit]'s `KEYCODE_DPAD_*`
+     * rows require: a remote's or keyboard's BACK shares this keycode and has to keep leaving the
+     * stream — for a device with no pad on it, Back IS the documented way out.
+     */
+    fun padButtonBit(keyCode: Int, flags: Int): Int = when {
+        keyCode != KeyEvent.KEYCODE_BACK -> buttonBit(keyCode)
+        flags and KeyEvent.FLAG_FALLBACK != 0 -> 0
+        else -> BTN_BACK
+    }
+
     /**
      * Maps one controller's joystick MotionEvents to axis (+ HAT→dpad) sends on wire pad index [pad],
      * **on change only**. Holds the previous axis/hat state so an unchanged frame emits nothing. One

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

@@ -51,7 +51,7 @@ class GamepadRouter(
      * claimed by keeping a slot — the Android input stack shares controllers — unlike the USB
      * capture links, which `StreamScreen` does not start at all while this is off.
      */
-    private val forwarding: Boolean = true,
+    forwarding: Boolean = true,
     /**
      * Forward raw guide/QAM presses (`Settings.systemButtons` resolved — auto = forward on
      * Android, where the press reaches the app on most devices; `local` exists for
@@ -70,6 +70,25 @@ class GamepadRouter(
     private val guideGesture: Boolean = false,
 ) {
 
+    /** The ctor's forwarding preference, fixed for the session — one term of [forwarding]. */
+    private val forwardingSetting = forwarding
+
+    /**
+     * Whether this session's access includes the GAMEPAD grant ([SessionAccess.GAMEPAD]) —
+     * seeded from the Welcome and kept live by `StreamScreen`'s access poll (an `AccessUpdate`
+     * can revoke or restore it mid-session, latest-wins). Gates exactly what the forwarding
+     * preference gates: the wire sends, never the slots — the exit/mic/stats chords must keep
+     * working on a Controller-less access level too (they are local controls that happen to be
+     * read off pad buttons). The host enforces regardless; this stops the client paying to send
+     * events that will be dropped. Volatile: the sensor and USB-capture threads read it per
+     * sample through [forwarding].
+     */
+    @Volatile
+    var gamepadGranted: Boolean = true
+
+    /** Send on the wire at all — the forwarding preference AND the session's GAMEPAD grant. */
+    private val forwarding: Boolean get() = forwardingSetting && gamepadGranted
+
     /** One forwarded controller: its stable wire pad index, per-device axis state, and held buttons. */
     private class Slot(
         val index: Int,
@@ -380,6 +399,13 @@ class GamepadRouter(
     /** Whether ANY live slot currently holds wire pad [pad]. Read from the phone-gyro thread. */
     fun padPresent(pad: Int): Boolean = slots.values.any { it.index == pad }
 
+    /**
+     * Whether wire sends are on at all — the forwarding preference AND the session's GAMEPAD
+     * grant. For the writers that ride the pad planes from OUTSIDE this router (the phone-gyro
+     * mirror), which must stand down with it. Read from the sensor thread.
+     */
+    fun sendsEnabled(): Boolean = forwarding
+
     /**
      * Whether wire pad [pad]'s motion already comes from the controller's OWN IMU — either a
      * capture-link slot ([ExternalPad] — USB DualSense / SC2; synthetic ids are negative

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

@@ -99,6 +99,17 @@ object NativeBridge {
      */
     external fun nativeEndReason(handle: Long): Int
 
+    /**
+     * The session's live access state as `[grants, remainingSecs, updateSeq]`, or `null` on a `0`
+     * handle. `grants` is a [SessionAccess] bitmask; `remainingSecs` counts down to the access
+     * expiry (`0` = permanent); `updateSeq` increments once per `AccessUpdate` the host sent
+     * (latest-wins — the state IS the fold, this counter is how a poller tells a fresh T−5 m /
+     * T−1 m warning arrived and owes a toast). Seeded from the Welcome's access advert; an old
+     * host — or an old native lib — reads as full control, permanent, exactly what such a host
+     * enforces. Poll ~1 Hz alongside [nativeSessionEnded]. Cheap; safe on the UI thread.
+     */
+    external fun nativeAccessState(handle: Long): IntArray?
+
     /**
      * Run the SPAKE2 PIN ceremony, presenting [certPem]/[keyPem]. Returns the host's verified
      * fingerprint (64-hex) to persist + pin, or `""` on failure (wrong PIN / MITM / unreachable).
@@ -302,12 +313,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)
@@ -472,6 +488,16 @@ object NativeBridge {
     // cross only when the host pastes (a "fetch:" event answered by nativeClipServeText). Host
     // copies arrive as "offer:" events, fetched eagerly into the system clipboard.
 
+    /**
+     * The management-API port the host reported in this session's `Welcome` — where its game
+     * library is served — or 0 if it advertised none (older host, or no management API).
+     *
+     * Persist it on the host record: unlike the mDNS `mgmt` TXT, this arrives over the connection
+     * we have already authenticated, so it is what makes a host that moved off 47990 browsable
+     * over a VPN, a routed subnet, or when it was added by address.
+     */
+    external fun nativeHostMgmtPort(handle: Long): Int
+
     /** Whether the host advertised a working shared-clipboard service (HOST_CAP_CLIPBOARD). */
     external fun nativeClipSupported(handle: Long): Boolean
 

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

@@ -1,5 +1,6 @@
 package io.unom.punktfunk.kit
 
+import android.Manifest
 import android.annotation.SuppressLint
 import android.bluetooth.BluetoothDevice
 import android.bluetooth.BluetoothGatt
@@ -9,6 +10,8 @@ import android.bluetooth.BluetoothGattDescriptor
 import android.bluetooth.BluetoothManager
 import android.bluetooth.BluetoothProfile
 import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
 import android.util.Log
 import java.util.UUID
 import java.util.concurrent.atomic.AtomicBoolean
@@ -47,16 +50,33 @@ class Sc2BleLink(
 
     @Volatile private var state = State.IDLE
 
-    /** Bonded devices that look like a Steam Controller (name heuristic — BLE exposes no PID here). */
-    fun pairedControllers(): List<BluetoothDevice> = runCatching {
-        manager.adapter?.bondedDevices.orEmpty().filter { dev ->
-            val n = runCatching { dev.name }.getOrNull() ?: return@filter false
-            NAME_HINTS.any { n.contains(it, ignoreCase = true) }
+    /**
+     * Bonded devices that look like a Steam Controller (name heuristic — BLE exposes no PID here).
+     *
+     * Gates on [permissionGranted] itself rather than trusting callers to: without the permission
+     * `bondedDevices` throws, and the `runCatching` below turns that into an empty list —
+     * indistinguishable from "no controller is paired". A capture that never engaged for want of a
+     * permission nobody had asked for is exactly the silence this logs its way out of.
+     */
+    fun pairedControllers(): List<BluetoothDevice> {
+        if (!permissionGranted(context)) {
+            Log.i(TAG, "BLE controllers not enumerated: $CONNECT_PERMISSION not granted")
+            return emptyList()
         }
-    }.getOrDefault(emptyList())
+        return runCatching {
+            manager.adapter?.bondedDevices.orEmpty().filter { dev ->
+                val n = runCatching { dev.name }.getOrNull() ?: return@filter false
+                NAME_HINTS.any { n.contains(it, ignoreCase = true) }
+            }
+        }.getOrDefault(emptyList())
+    }
 
     /** Connect to the bonded controller at [address]. Reports start flowing once READY. */
     fun start(address: String): Boolean {
+        if (!permissionGranted(context)) {
+            Log.i(TAG, "BLE capture not started: $CONNECT_PERMISSION not granted")
+            return false
+        }
         val adapter = manager.adapter ?: return false
         if (!adapter.isEnabled) return false
         val device = runCatching { adapter.getRemoteDevice(address) }.getOrNull() ?: return false
@@ -222,20 +242,50 @@ class Sc2BleLink(
         return s.substring(0, 8).toLongOrNull(16)
     }
 
-    private companion object {
-        const val TAG = "Sc2BleLink"
+    companion object {
+        private const val TAG = "Sc2BleLink"
 
-        val VALVE_SERVICE: UUID = UUID.fromString("100f6c32-1735-4313-b402-38567131e5f3")
-        const val VALVE_UUID_TAIL = "-1735-4313-b402-38567131e5f3"
-        const val NOTIFY_LOW = 0x100f6c75L
-        const val NOTIFY_HIGH = 0x100f6c7aL
-        const val WRITE_LOW = 0x100f6cb5L
-        const val WRITE_HIGH = 0x100f6cbeL
-        val CCCD: UUID = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")
+        private val VALVE_SERVICE: UUID = UUID.fromString("100f6c32-1735-4313-b402-38567131e5f3")
+        private const val VALVE_UUID_TAIL = "-1735-4313-b402-38567131e5f3"
+        private const val NOTIFY_LOW = 0x100f6c75L
+        private const val NOTIFY_HIGH = 0x100f6c7aL
+        private const val WRITE_LOW = 0x100f6cb5L
+        private const val WRITE_HIGH = 0x100f6cbeL
+        private val CCCD: UUID = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")
 
-        val NAME_HINTS = listOf("Steam Ctrl", "Steam Controller", "SteamController", "Valve")
+        private val NAME_HINTS =
+            listOf("Steam Ctrl", "Steam Controller", "SteamController", "Valve")
 
         /** Enough for a state payload (45 B) + ATT header with margin. */
-        const val DESIRED_MTU = 100
+        private const val DESIRED_MTU = 100
+
+        /**
+         * The runtime permission this transport needs, or null where the platform grants Bluetooth
+         * at install time.
+         *
+         * From API 31 both operations a capture makes — reading the bonded list and `connectGatt`
+         * — sit behind the runtime `BLUETOOTH_CONNECT`. Below it the manifest's legacy `BLUETOOTH`
+         * (normal-level, granted on install) covers exactly those two, and `BLUETOOTH_CONNECT` is
+         * not a permission that platform version knows: `checkSelfPermission` answers DENIED for
+         * it and a request is refused without a dialog. Gating on it unconditionally is therefore
+         * not merely redundant on old releases — it is a permanent refusal, which is what this
+         * null arm exists to avoid.
+         */
+        val CONNECT_PERMISSION: String? =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                Manifest.permission.BLUETOOTH_CONNECT
+            } else {
+                null
+            }
+
+        /**
+         * Whether a BLE capture may run: [CONNECT_PERMISSION] held, or not required on this
+         * release. Callers that can offer the user a grant ask this first, so the offer appears
+         * only when it would change something.
+         */
+        fun permissionGranted(context: Context): Boolean {
+            val permission = CONNECT_PERMISSION ?: return true
+            return context.checkSelfPermission(permission) == PackageManager.PERMISSION_GRANTED
+        }
     }
 }

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

@@ -0,0 +1,60 @@
+package io.unom.punktfunk.kit
+
+/**
+ * Per-client access grants — the Kotlin mirror of `punktfunk_core::quic::access` (bit-for-bit;
+ * `design/per-client-access.md` §3), read per session via [NativeBridge.nativeAccessState].
+ *
+ * The host is the only enforcer: everything gated on these bits client-side is courtesy UX over
+ * the same vocabulary — don't capture what can't land (a keyboard that silently does nothing is
+ * the failure mode this exists to prevent), and say what this session is (the stream's Access
+ * chip). The user-facing word is **"Access"**; the preset labels are *derived* from the mask,
+ * never stored, so they can't drift from what the host actually granted.
+ */
+object SessionAccess {
+    /** Controller input — gamepad events, rich pad input, pad audio, rumble return. */
+    const val GAMEPAD = 1 shl 0
+
+    /** Pointing input — mouse rel/abs + buttons, scroll, touch, and the pen plane. */
+    const val POINTER = 1 shl 1
+
+    /** Key input — key down/up and IME-committed text. */
+    const val KEYBOARD = 1 shl 2
+
+    /** Shared clipboard (ANDed into the host's clipboard policy). */
+    const val CLIPBOARD = 1 shl 3
+
+    /** Mic injection — the uplink plane + the per-session mic attach. */
+    const val MIC = 1 shl 4
+
+    /** Library launch (`Hello.launch`). */
+    const val LAUNCH = 1 shl 5
+
+    /** Every defined grant — full control, and what an old host's Welcome decodes to. */
+    const val ALL = GAMEPAD or POINTER or KEYBOARD or CLIPBOARD or MIC or LAUNCH
+
+    /**
+     * The preset name a mask displays as — §3.2's rule: three levels people actually reason
+     * about, "Custom" for any other combination, never a raw bit list.
+     */
+    fun label(grants: Int): String = when (grants and ALL) {
+        ALL -> "Full control"
+        GAMEPAD -> "Controller only"
+        0 -> "View only"
+        else -> "Custom"
+    }
+
+    /**
+     * Compact time-left wording for the Access chip ("1 h 58 m", "12 m", "45 s") — hours and
+     * minutes once the span has them, bare seconds only under a minute (the final countdown).
+     */
+    fun remainingLabel(secs: Int): String {
+        val h = secs / 3600
+        val m = (secs % 3600) / 60
+        return when {
+            h > 0 && m > 0 -> "$h h $m m"
+            h > 0 -> "$h h"
+            m > 0 -> "$m m"
+            else -> "${secs.coerceAtLeast(0)} s"
+        }
+    }
+}

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

@@ -19,13 +19,16 @@ data class DiscoveredHost(
     val pairingRequired: Boolean = false,
     val mac: List<String> = emptyList(), // TXT "mac" (wake-capable NIC MAC(s), for Wake-on-LAN)
     val os: String = "", // TXT "os" (OS-identity chain, e.g. "linux/fedora/bazzite"); "" on older hosts
+    // TXT "mgmt" — the management-API port the library is served on, distinct from `port` (the
+    // native QUIC plane). null on an older host / older native lib, meaning "assume 47990".
+    val mgmtPort: Int? = null,
 )
 
 /** Field separator the native browse uses inside one record (ASCII Unit Separator). */
 private const val FIELD_SEP = '\u001F'
 
 /**
- * Parse one record from [NativeBridge.nativeDiscoveryPoll] (`key␟name␟addr␟port␟fp␟pair␟mac␟os`),
+ * Parse one record from [NativeBridge.nativeDiscoveryPoll] (`key␟name␟addr␟port␟fp␟pair␟mac␟os␟mgmt`),
  * or null if it's malformed. Fields past the 6th are optional — an older native lib omits them
  * (`mac` 7th, `os` 8th). Pure — unit-tested without Android (see ParseRecordTest). The native side
  * already applied the protocol gate and address selection, so this is just field marshaling.
@@ -46,6 +49,9 @@ fun parseHostRecord(record: String): DiscoveredHost? {
         mac = if (f.size > 6) f[6].split(",").map { it.trim() }.filter { it.isNotEmpty() }
         else emptyList(),
         os = if (f.size > 7) sanitizeOsChain(f[7]) else "",
+        // 9th field, absent on an older native lib. `0` (and anything out of range) means "not
+        // advertised" → null, and the caller falls back to 47990.
+        mgmtPort = if (f.size > 8) f[8].toIntOrNull()?.takeIf { it in 1..65535 } else null,
     )
 }
 

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

@@ -32,6 +32,16 @@ data class KnownHost(
      * first learned (or forever, against an older host).
      */
     val os: String = "",
+    /**
+     * The host's management-API port (mDNS `mgmt` TXT), where the game library is served — NOT
+     * [port], which is the native QUIC plane. Learned while online and kept for the same reason as
+     * [mac] and [os], except this one is load-bearing: a host that moved its mgmt port off 47990
+     * (the supported way to share a machine with a Sunshine fork, whose web UI owns that port)
+     * served its library only while mDNS was reachable, because the advert was the sole place the
+     * real port ever existed. `null` until learned — resolve with [effectiveMgmtPort].
+     * Mirrors the Apple client's `StoredHost.mgmtPort` and the Rust `KnownHost.mgmt_port`.
+     */
+    val mgmtPort: Int? = null,
     /** Stable record identity — see the class doc. Minted here for a genuinely new record. */
     val id: String = newRecordId(),
     /**
@@ -54,7 +64,16 @@ data class KnownHost(
      * that no longer exist are dropped when the cards are rendered.
      */
     val pinnedProfileIds: List<String> = emptyList(),
-)
+) {
+    /**
+     * Where this host's management API actually is: the port learned from its advert, else 47990.
+     * The twin of the Apple client's `StoredHost.effectiveMgmtPort` and the Rust
+     * `KnownHost::effective_mgmt_port`. Resolve through this — the constant is the FALLBACK, not
+     * the answer.
+     */
+    val effectiveMgmtPort: Int
+        get() = mgmtPort ?: io.unom.punktfunk.kit.library.DEFAULT_MGMT_PORT
+}
 
 /**
  * Persists trusted hosts — the pinned-fingerprint store *and* the saved-hosts list — keyed by
@@ -130,6 +149,17 @@ class KnownHostStore(context: Context) {
         save(h.copy(os = os))
     }
 
+    /**
+     * Learn/refresh a saved host's management-API port from its live advert — same contract as
+     * [learnMac]. This is the one that keeps a moved mgmt port working once mDNS isn't reachable.
+     */
+    fun learnMgmtPort(address: String, port: Int, mgmtPort: Int) {
+        if (mgmtPort <= 0) return
+        val h = get(address, port) ?: return
+        if (h.mgmtPort == mgmtPort) return
+        save(h.copy(mgmtPort = mgmtPort))
+    }
+
     /** Forget [host] (the next connect re-pairs / re-TOFUs). */
     fun remove(host: KnownHost) {
         prefs.edit().remove(host.id).apply()
@@ -180,6 +210,10 @@ class KnownHostStore(context: Context) {
             paired = j.optBoolean("paired", false),
             mac = j.optString("mac", "").split(",").map { it.trim() }.filter { it.isNotEmpty() },
             os = j.optString("os", ""),
+            // 0 (or absent) = never learned. `optInt` cannot express "missing", hence the sentinel
+            // rather than a bare default — a record written before this field existed must decode
+            // to null and fall back to 47990, not to port 0.
+            mgmtPort = j.optInt("mgmt", 0).takeIf { it > 0 },
             // A record without an id can only be one this build wrote before the migration ran, or
             // a hand-edited file; minting here keeps the parse total rather than dropping a host.
             id = j.optString("id", "").ifEmpty { newRecordId() },
@@ -266,6 +300,7 @@ class KnownHostStore(context: Context) {
             .put("paired", host.paired)
             .put("mac", host.mac.joinToString(","))
             .put("os", host.os)
+            .put("mgmt", host.mgmtPort ?: 0)
             .put("clip", host.clipboardSync)
             .put("profile", host.profileId ?: "")
             .put("pins", JSONArray(host.pinnedProfileIds))

clients/android/kit/src/test/kotlin/io/unom/punktfunk/kit/PadButtonBitTest.kt

@@ -0,0 +1,80 @@
+package io.unom.punktfunk.kit
+
+import android.view.KeyEvent
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Pure JVM test of [Gamepad.padButtonBit] — the streaming branch's gamepad keycode resolution
+ * (`KeyEvent`'s keycode/flag constants are compile-time-inlined ints, so no Android runtime is
+ * involved). Run: `./gradlew :kit:testDebugUnitTest`.
+ *
+ * The regression it pins is a field report: one press of Select disconnected the session. Plenty
+ * of pads deliver that button as the plain `KEYCODE_BACK` a remote uses, with no `BUTTON_SELECT`
+ * scancode behind it — so it mapped to nothing, fell out of the gamepad branch unconsumed, and
+ * reached the activity back stack, which is the deliberate-quit exit. The same gap made
+ * [Gamepad.BTN_BACK] unreachable on those pads, and with it every shortcut built on Select: the
+ * exit chord `StreamScreen`'s own start banner advertises, the mic mute, the stats tier.
+ *
+ * Which controller the report came from is not knowable from the logs and does not matter:
+ * `KEYCODE_BACK` is the only keycode that reaches the back stack from a SOURCE_GAMEPAD device, so
+ * a one-press quit identifies the button's keycode on its own.
+ */
+class PadButtonBitTest {
+
+    /** The report: Select on an Android-TV pad arrives as BACK and must be the Select bit. */
+    @Test
+    fun `a pad's BACK is its Select button`() {
+        assertEquals(Gamepad.BTN_BACK, Gamepad.padButtonBit(KeyEvent.KEYCODE_BACK, 0))
+        // Same bit either spelling reaches us by — a pad that DOES carry BUTTON_SELECT is unchanged.
+        assertEquals(
+            Gamepad.padButtonBit(KeyEvent.KEYCODE_BUTTON_SELECT, 0),
+            Gamepad.padButtonBit(KeyEvent.KEYCODE_BACK, 0),
+        )
+    }
+
+    /**
+     * With Select mapped, the three Select chords are reachable on a pad that has only a BACK
+     * keycode — which is the whole point of the mapping, not a side effect of it. Held-state
+     * assembly is [GamepadRouter]'s (see `GamepadChordTest`); what is pinned here is that the
+     * bits a SHIELD can actually produce cover each chord.
+     */
+    @Test
+    fun `the Select chords are reachable from a BACK-only pad`() {
+        val select = Gamepad.padButtonBit(KeyEvent.KEYCODE_BACK, 0)
+        val start = Gamepad.padButtonBit(KeyEvent.KEYCODE_BUTTON_START, 0)
+        val l1 = Gamepad.padButtonBit(KeyEvent.KEYCODE_BUTTON_L1, 0)
+        val r1 = Gamepad.padButtonBit(KeyEvent.KEYCODE_BUTTON_R1, 0)
+        val x = Gamepad.padButtonBit(KeyEvent.KEYCODE_BUTTON_X, 0)
+        val y = Gamepad.padButtonBit(KeyEvent.KEYCODE_BUTTON_Y, 0)
+        assertEquals(GamepadRouter.EXIT_CHORD, select or start or l1 or r1)
+        assertEquals(GamepadRouter.STATS_CHORD, select or x)
+        assertEquals(GamepadRouter.MIC_CHORD, select or y)
+    }
+
+    /**
+     * The synthetic BACK the framework raises after an unconsumed `BUTTON_*` press is not a button
+     * anyone touched — forwarding it would put a phantom Select on the wire, and one of those
+     * landing while Start + L1 + R1 were held would complete the exit chord out of nowhere.
+     */
+    @Test
+    fun `a fallback BACK is not a button press`() {
+        assertEquals(0, Gamepad.padButtonBit(KeyEvent.KEYCODE_BACK, KeyEvent.FLAG_FALLBACK))
+        // Only BACK is filtered on the flag; a real button keeps its bit whatever rides alongside.
+        assertEquals(
+            Gamepad.BTN_A,
+            Gamepad.padButtonBit(KeyEvent.KEYCODE_BUTTON_A, KeyEvent.FLAG_FALLBACK),
+        )
+    }
+
+    /** Everything else is [Gamepad.buttonBit] verbatim — BACK is the only row this adds. */
+    @Test
+    fun `every other keycode is unchanged`() {
+        for (code in 0..0x400) {
+            if (code == KeyEvent.KEYCODE_BACK) continue
+            assertEquals(Gamepad.buttonBit(code), Gamepad.padButtonBit(code, 0))
+        }
+        // And BACK is genuinely a new row, not one buttonBit already had.
+        assertEquals(0, Gamepad.buttonBit(KeyEvent.KEYCODE_BACK))
+    }
+}

clients/android/kit/src/test/kotlin/io/unom/punktfunk/kit/SessionAccessTest.kt

@@ -0,0 +1,48 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Pure JVM test of [SessionAccess] — the bit values are an ABI contract with
+ * `punktfunk_core::quic::access` (wire == store == this mirror), and the preset labels are the
+ * §3.2 naming rule the Access chip renders from: three levels people reason about, "Custom" for
+ * anything else, derived from the mask so they cannot drift. Run: `./gradlew :kit:testDebugUnitTest`.
+ */
+class SessionAccessTest {
+
+    /** Bit-for-bit the core vocabulary — a reorder here would mislabel every session. */
+    @Test
+    fun `bits mirror punktfunk-core`() {
+        assertEquals(1, SessionAccess.GAMEPAD)
+        assertEquals(2, SessionAccess.POINTER)
+        assertEquals(4, SessionAccess.KEYBOARD)
+        assertEquals(8, SessionAccess.CLIPBOARD)
+        assertEquals(16, SessionAccess.MIC)
+        assertEquals(32, SessionAccess.LAUNCH)
+        assertEquals(0x3F, SessionAccess.ALL)
+    }
+
+    @Test
+    fun `preset labels derive from the mask`() {
+        assertEquals("Full control", SessionAccess.label(SessionAccess.ALL))
+        assertEquals("Controller only", SessionAccess.label(SessionAccess.GAMEPAD))
+        assertEquals("View only", SessionAccess.label(0))
+        // Any other combination is Custom — including controller + clipboard, the design's
+        // media-remote example.
+        assertEquals(
+            "Custom",
+            SessionAccess.label(SessionAccess.GAMEPAD or SessionAccess.CLIPBOARD),
+        )
+        assertEquals("Custom", SessionAccess.label(SessionAccess.ALL and SessionAccess.LAUNCH.inv()))
+    }
+
+    @Test
+    fun `remaining label is compact and never empty`() {
+        assertEquals("1 h 58 m", SessionAccess.remainingLabel(7130))
+        assertEquals("2 h", SessionAccess.remainingLabel(7200))
+        assertEquals("12 m", SessionAccess.remainingLabel(725))
+        assertEquals("45 s", SessionAccess.remainingLabel(45))
+        assertEquals("0 s", SessionAccess.remainingLabel(0))
+    }
+}

clients/android/kit/src/test/kotlin/io/unom/punktfunk/kit/discovery/ParseRecordTest.kt

@@ -47,6 +47,31 @@ class ParseRecordTest {
             rec("k", "n", "10.0.0.5", "9777", "", "optional", "", "linux/fedora/bazzite"),
         )!!
         assertEquals("linux/fedora/bazzite", h.os)
+        // A record from a native lib predating the 9th field: no mgmt port, so the caller falls
+        // back to 47990. Absent must read as "unknown", never as port 0.
+        assertNull(h.mgmtPort)
+    }
+
+    @Test
+    fun ninthFieldCarriesTheMgmtPort() {
+        // 47991, not the 47990 default — a host that MOVED its mgmt port is the whole reason this
+        // field is on the wire, and a test pinned to the default would pass against a hardcode.
+        val h = parseHostRecord(
+            rec("k", "n", "10.0.0.5", "9777", "", "optional", "", "linux/arch", "47991"),
+        )!!
+        assertEquals(47991, h.mgmtPort)
+    }
+
+    @Test
+    fun mgmtPortOutOfRangeOrUnparsableReadsAsUnknown() {
+        // Unauthenticated advert data: 0 (the "not advertised" sentinel the Rust side emits),
+        // a non-number, and an out-of-range value must all mean "assume the default" rather than
+        // produce a port the client would then fail to connect to.
+        val base = arrayOf("k", "n", "10.0.0.5", "9777", "", "optional", "", "linux/arch")
+        assertNull(parseHostRecord(rec(*base, "0"))!!.mgmtPort)
+        assertNull(parseHostRecord(rec(*base, "not-a-port"))!!.mgmtPort)
+        assertNull(parseHostRecord(rec(*base, "70000"))!!.mgmtPort)
+        assertNull(parseHostRecord(rec(*base, ""))!!.mgmtPort)
     }
 
     @Test

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/decode/async_loop.rs

@@ -37,6 +37,7 @@ struct OutputReady {
     index: usize,
     pts_us: u64,
     decoded_ns: i128,
+    decoded_mono_ns: i64,
 }
 
 /// Events the async decode loop reacts to. The codec's async-notify callbacks (which run on its
@@ -51,11 +52,12 @@ enum DecodeEvent {
     Au(Frame, u32),
     /// An input buffer slot freed (index) — we can queue an AU into it.
     InputAvailable(usize),
-    /// A decoded frame is ready (buffer index + echoed pts + the callback-time `decoded` stamp).
+    /// A decoded frame is ready (buffer index + echoed pts + the callback-time `decoded` stamps).
     OutputAvailable {
         index: usize,
         pts_us: u64,
         decoded_ns: i128,
+        decoded_mono_ns: i64,
     },
     /// The output format changed — re-check the stream's colour signalling (HDR DataSpace).
     FormatChanged,
@@ -126,6 +128,12 @@ pub(super) fn run_async(
                     // decode stage ends when the frame actually became available — not after the
                     // channel hop + whatever work the loop coalesces in front of presenting it.
                     decoded_ns: now_realtime_ns(),
+                    // Its monotonic twin, from the same instant. The stats are REALTIME (they
+                    // fold the host's clock offset in), while the cadence loop and
+                    // `releaseOutputBufferAtTime` are both CLOCK_MONOTONIC — and the loop is fed
+                    // and read in one domain, never converted (`punktfunk_core::phase`: a
+                    // constant offset between domains is what its offset estimator absorbs).
+                    decoded_mono_ns: now_monotonic_ns(),
                 });
             })),
             on_format_changed: Some(Box::new(move |_fmt| {
@@ -232,7 +240,7 @@ pub(super) fn run_async(
                 PresentPriority::Smooth { buffer } => format!("smoothness, buffer {buffer}"),
             }
         );
-        Some(Presenter::new(priority))
+        Some(Presenter::new(priority, mode.refresh_hz))
     };
     stats.set_presenter_active(presenter.is_some());
     // The vsync clock, started LAZILY on the first decoded frame (see `vsync.rs`); its ticks ride
@@ -299,6 +307,7 @@ pub(super) fn run_async(
     // codec error; `recovery_flags` carries each AU's user_flags from `dispatch_event` (feed) to
     // `present_ready` (present), keyed by the codec-echoed pts.
     let mut gate = ReanchorGate::new(client.frames_dropped());
+    let mut last_arms = gate.arms();
     let mut recovery_flags: VecDeque<(u64, u32)> = VecDeque::new();
     let mut last_kf_req: Option<Instant> = None;
     // Productive (dispatch+feed+present) time between displayed frames; reported to ADPF once one is
@@ -378,6 +387,19 @@ pub(super) fn run_async(
             &mut queued_stamps,
             &mut gate,
         );
+        // The cadence loop's re-anchor seam. A fresh arm means a loss was detected: the gate is
+        // about to freeze on the last good picture and the frames that reach the presenter on the
+        // far side come through a decoder that has just recovered, so the source→presentable delay
+        // the loop had measured is not the one it will see. Watched by ARM COUNT rather than at
+        // each `gate.arm` site because those are spread across the dispatcher, the feeder and this
+        // loop's own backstops, and the count catches every one of them — including the ones
+        // `feed_ready` raises for an abandoned partial AU.
+        if gate.arms() != last_arms {
+            last_arms = gate.arms();
+            if let Some(p) = presenter.as_mut() {
+                p.reset_cadence();
+            }
+        }
         let had_output = !ready.is_empty();
         let rendered_before = rendered;
         present_ready(
@@ -414,7 +436,7 @@ pub(super) fn run_async(
             if let (Some(_), Some(c)) = (p.flush_log(&meter, clock), clock) {
                 let period = c.panel_period_ns().max(c.period_ns());
                 if period > 0 {
-                    if let Some(t) = c.next_target(now_monotonic_ns(), 0) {
+                    if let Some(t) = c.next_target(now_monotonic_ns()) {
                         let mono_now = now_monotonic_ns();
                         let real_now = now_realtime_ns();
                         let leads_us: Vec<u64> = arrival_stamps
@@ -737,10 +759,12 @@ fn dispatch_event(
             index,
             pts_us,
             decoded_ns,
+            decoded_mono_ns,
         } => ready.push(OutputReady {
             index,
             pts_us,
             decoded_ns,
+            decoded_mono_ns,
         }),
         DecodeEvent::FormatChanged => *fmt_dirty = true,
         DecodeEvent::Vsync => *vsync_tick = true,
@@ -998,7 +1022,7 @@ fn present_ready(
         for o in ready.drain(..) {
             let flags = take_flags(recovery_flags, o.pts_us);
             if gate.on_decoded(flags, false, now) == GateVerdict::Present {
-                let dropped = p.submit(codec, o.index, o.pts_us, o.decoded_ns);
+                let dropped = p.submit(codec, o.index, o.pts_us, o.decoded_ns, o.decoded_mono_ns);
                 skipped += dropped;
                 *discarded += dropped;
             } else {

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

@@ -14,6 +14,12 @@
 //!    frame timeline (API 33+, via [`super::vsync`]), so the latch phase is deterministic instead
 //!    of inheriting network + decode jitter. On the 31/32 fallback the release is ASAP —
 //!    identical to the legacy path — and only the budget prediction uses the measured period.
+//!  * under the SMOOTHNESS intent only, a **due time** per frame from
+//!    [`punktfunk_core::phase::CadenceClock`]: the release targets the first timeline at or after
+//!    the instant the SOURCE's own timestamp says the frame is due, rather than the first one
+//!    after it happened to decode, so the host's cadence reaches glass instead of the network's
+//!    (`design/presenter-cadence-rework.md` D1). The latency intent holds no clock at all and
+//!    stays arrival-driven by construction.
 //!
 //! The legacy behaviour (release the newest ready buffer immediately, unbudgeted) remains
 //! selectable at runtime: `adb shell setprop debug.punktfunk.presenter arrival` — the on-device
@@ -21,6 +27,7 @@
 //! (off = the synchronous pre-overhaul loop, no presenter at all).
 
 use ndk::media::media_codec::MediaCodec;
+use punktfunk_core::phase::{CadenceClock, CadenceHealth, CadenceTuning};
 use std::collections::VecDeque;
 use std::sync::atomic::{AtomicBool, AtomicI32, Ordering};
 use std::sync::Mutex;
@@ -103,8 +110,9 @@ const FALLBACK_PERIOD_NS: i64 = 8_333_333;
 pub(crate) enum PresentPriority {
     /// Newest-wins, release the instant the budget opens. The default.
     Latency,
-    /// A small FIFO (1..=3 frames) drained one per vsync: jitter absorbed at one refresh of
-    /// added display latency per slot, which the metrics show rather than hide.
+    /// A small holding store (1..=3 frames) drained on each frame's DUE time from the source's own
+    /// timestamps: transport jitter absorbed in the cushion the cadence loop sizes from its own
+    /// measured residual, at a latency the metrics show rather than hide.
     Smooth { buffer: usize },
 }
 
@@ -129,6 +137,9 @@ struct HeldFrame {
     pts_us: u64,
     /// The output callback's `CLOCK_REALTIME` stamp — the pace metric's start (decoded→release).
     decoded_ns: i128,
+    /// When the source says this frame is due, monotonic — [`CadenceClock::due_ns`] folded at
+    /// submit. `None` under the latency intent, which has no clock.
+    due_ns: Option<i64>,
 }
 
 /// The one-in-flight glass budget.
@@ -287,20 +298,33 @@ fn p50_max_ms(mut v: Vec<u64>) -> (f64, f64) {
 }
 
 pub(super) struct Presenter {
-    /// 0 = newest-wins; 1..=3 = smoothing FIFO capacity.
+    /// 0 = newest-wins; 1..=3 = the holding store's capacity, a bound against a burst rather than
+    /// a pacing depth (design §4.3).
     fifo_capacity: usize,
     frames: VecDeque<HeldFrame>,
-    /// FIFO preroll: `take` withholds until the buffer filled to capacity once, re-armed on a dry
-    /// run — the Apple `FrameStore` semantics (headroom never builds without it).
-    prerolled: bool,
+    /// The source-cadence loop, and the ONLY thing that makes this presenter anything but
+    /// arrival-driven. `None` under the latency intent — not "a clock we choose to ignore" but no
+    /// clock at all, so that path cannot drift into cadence targeting by accident (`design/
+    /// presenter-cadence-rework.md` §5; the test below is what holds it there).
+    cadence: Option<CadenceClock>,
+    /// The source's nominal frame interval — [`CadenceClock`]'s cushion ceiling, which is a design
+    /// invariant rather than a tunable (a cushion past one whole frame buys smoothness the source
+    /// cannot supply). From the negotiated stream rate, which cannot change without tearing this
+    /// loop down.
+    frame_interval_ns: i64,
     inflight: Option<InFlight>,
-    /// A vsync arrived since the last release — the FIFO's one-per-refresh drain pace.
+    /// A vsync arrived since the last release — the retry beat for a parked frame, and what the
+    /// empty-store readout below is counted against.
     vsync_tick: bool,
     // -- 1 Hz pf-present window, always on --
     released: u64,
     paced_drops: u64,
     no_budget: u64,
     forced: u64,
+    /// Vsync ticks that found the store empty. Under cadence targeting an empty store is the
+    /// ordinary state between a frame's decode and its due time, so this reads as supply depth
+    /// rather than as the underflow alarm it was under the retired per-slot drain — the alarm is
+    /// the loop's own late count.
     dry: u64,
     /// Pump passes that held a frame back because too many earlier releases were still
     /// unconfirmed ([`UNDISPLAYED_CAP`]) — reads 0 on a healthy device, and a climbing value is
@@ -321,7 +345,12 @@ pub(super) struct Presenter {
 }
 
 impl Presenter {
-    pub(super) fn new(priority: PresentPriority) -> Presenter {
+    /// `source_hz` is the NEGOTIATED STREAM rate, not the panel's — it sizes the cadence loop's
+    /// cushion ceiling, and the quantity that must not be exceeded is one source frame. 0 (an
+    /// unnegotiated rate) falls back to [`FALLBACK_PERIOD_NS`], the tighter of the two plausible
+    /// answers: a ceiling set too low costs smoothness, one set too high costs latency the user
+    /// never asked for.
+    pub(super) fn new(priority: PresentPriority, source_hz: u32) -> Presenter {
         let pinned = latch_margin_ns();
         let (margin_ns, margin_pinned) = match pinned {
             Some(ns) => (ns, true),
@@ -336,13 +365,27 @@ impl Presenter {
                 " (adaptive — widens on latch misses)"
             }
         );
+        let frame_interval_ns = match source_hz {
+            0 => FALLBACK_PERIOD_NS,
+            hz => 1_000_000_000 / i64::from(hz),
+        };
+        // `snapping()`, because every release here goes through the frame-timeline grid: the
+        // snap-up carries roughly half a refresh of implicit slack, so the cushion is small.
+        let cadence = matches!(priority, PresentPriority::Smooth { .. }).then(|| {
+            log::info!(
+                "presenter: cadence clock on the source's timeline, frame interval {:.2}ms",
+                frame_interval_ns as f64 / 1e6
+            );
+            CadenceClock::new(CadenceTuning::snapping())
+        });
         Presenter {
             fifo_capacity: match priority {
                 PresentPriority::Latency => 0,
                 PresentPriority::Smooth { buffer } => buffer,
             },
             frames: VecDeque::new(),
-            prerolled: false,
+            cadence,
+            frame_interval_ns,
             inflight: None,
             vsync_tick: false,
             released: 0,
@@ -359,8 +402,9 @@ impl Presenter {
         }
     }
 
-    /// A vsync pulse from the clock thread's event — the retry tick for a parked frame and the
-    /// FIFO's drain pace.
+    /// A vsync pulse from the clock thread's event — the retry tick for a frame parked on a closed
+    /// budget, and the beat the empty-store readout is counted against. No longer a drain pace:
+    /// under cadence targeting the due time is what releases a frame.
     pub(super) fn on_vsync(&mut self) {
         self.vsync_tick = true;
     }
@@ -368,13 +412,21 @@ impl Presenter {
     /// Accept one decoded, gate-approved output buffer. Newest-wins evicts everything older
     /// (released unrendered — the explicit, counted drop); the FIFO evicts its oldest past
     /// capacity. Returns how many frames were dropped by the policy (the HUD's `skipped`).
+    ///
+    /// `decoded_mono_ns` is the monotonic twin of `decoded_ns`, stamped at the same instant on the
+    /// codec's callback thread: the cadence loop and `releaseOutputBufferAtTime` both live in
+    /// `CLOCK_MONOTONIC`, while the latency stats live in `CLOCK_REALTIME`, and the loop is fed and
+    /// read in ONE domain (`phase.rs`: a constant offset between domains is absorbed by the offset
+    /// estimator, so no conversion belongs anywhere in this path).
     pub(super) fn submit(
         &mut self,
         codec: &MediaCodec,
         index: usize,
         pts_us: u64,
         decoded_ns: i128,
+        decoded_mono_ns: i64,
     ) -> u64 {
+        let due_ns = self.due_at(pts_us, decoded_mono_ns);
         let mut dropped = 0u64;
         if self.fifo_capacity == 0 {
             while let Some(stale) = self.frames.pop_front() {
@@ -386,6 +438,7 @@ impl Presenter {
             index,
             pts_us,
             decoded_ns,
+            due_ns,
         });
         if self.fifo_capacity > 0 && self.frames.len() > self.fifo_capacity {
             if let Some(stale) = self.frames.pop_front() {
@@ -397,6 +450,61 @@ impl Presenter {
         dropped
     }
 
+    /// When the source says this frame is due, or `None` under the latency intent.
+    ///
+    /// `pts_us` IS the host's own stamp — it round-trips through the codec's presentation time, so
+    /// the source timeline needs no plumbing of its own. The µs the codec API quantises it to
+    /// costs ±0.5 µs of white noise on an 8.3 ms period, and that passes through to the due time
+    /// like any other variation in the source's cadence: the loop smooths the offset, never the
+    /// timestamps.
+    fn due_at(&mut self, pts_us: u64, decoded_mono_ns: i64) -> Option<i64> {
+        let interval_ns = self.frame_interval_ns;
+        self.cadence
+            .as_mut()
+            .map(|c| c.due_ns(pts_us.saturating_mul(1_000), decoded_mono_ns, interval_ns))
+    }
+
+    /// The earliest present a release may target: SurfaceFlinger's latch lead ahead of now, since
+    /// a present it cannot latch in time is not a target, and never before the frame's own due
+    /// time. That second half is the whole of the cadence change — `next_target(max(now, due))`
+    /// where it used to be `next_target(now)` (design §4.2).
+    fn not_before_ns(&self, now_mono_ns: i64, due_ns: Option<i64>) -> i64 {
+        let submit_floor_ns = now_mono_ns + self.margin_ns;
+        due_ns.map_or(submit_floor_ns, |due| due.max(submit_floor_ns))
+    }
+
+    /// Whether the frame at the head of the smoothing store may leave it yet.
+    ///
+    /// The store's job under cadence targeting is to HOLD WHAT IS NOT DUE YET (design §4.3): the
+    /// due time paces, so capacity is a bound against a burst rather than the clock. A frame is
+    /// releasable once the grid point it aims at is the next one this pump could still submit for
+    /// — one `grid_period_ns` of reach past the submit margin. Sooner buys nothing, because the
+    /// release is timed either way and holding keeps the store's own eviction policy live over the
+    /// frame; later risks the loop's 5 ms housekeeping wake landing inside the submit lead, which
+    /// costs the frame a whole refresh.
+    fn head_is_releasable(&self, now_mono_ns: i64, grid_period_ns: i64) -> bool {
+        let reach_ns = now_mono_ns + self.margin_ns + grid_period_ns;
+        self.frames
+            .front()
+            .is_some_and(|f| f.due_ns.is_none_or(|due| due <= reach_ns))
+    }
+
+    /// Force the cadence loop to re-anchor on the next frame — the discontinuity hook the clock
+    /// asks its callers for. The Android seam is the re-anchor gate arming: a loss freezes the
+    /// gate, the decoder recovers behind it, and what reaches this store on the far side comes
+    /// through a pipeline whose delay is no longer the one the loop measured. Source-timestamp
+    /// regressions and half-second gaps the loop catches by itself. No-op under latency.
+    pub(super) fn reset_cadence(&mut self) {
+        if let Some(c) = self.cadence.as_mut() {
+            c.reset();
+        }
+    }
+
+    /// The cadence loop's health for the 1 Hz line, or `None` when there is no loop to read.
+    fn cadence_health(&self) -> Option<CadenceHealth> {
+        self.cadence.as_ref().map(CadenceClock::health)
+    }
+
     /// The present decision point — run on every loop pass (frame arrivals, vsync ticks, and the
     /// 5 ms housekeeping wake all land here). Releases AT MOST one frame (the budget). Returns
     /// `true` when a frame was released to glass this call.
@@ -423,28 +531,28 @@ impl Presenter {
         // pass — frame waiting or not — so its forgiveness timer measures real elapsed time
         // rather than how often a frame happened to be ready.
         let backlogged = self.unconfirmed_backlog(meter, now_mono_ns);
+        // The grid a release snaps to, for the store's due-time reach below: the panel's own
+        // period where it is known — the app's choreographer stream can be down-rated below it
+        // (see `VsyncShared::next_target`) — and the measured callback period otherwise.
+        let grid_period_ns = clock
+            .map(|c| c.panel_period_ns().max(c.period_ns()))
+            .filter(|&p| p > 0)
+            .unwrap_or(FALLBACK_PERIOD_NS);
         // Pick the frame this pump may release.
         let frame = if self.fifo_capacity == 0 {
             self.frames.pop_back() // submit() kept it a single slot; back == the newest
         } else {
-            // FIFO: drain exactly one frame per vsync tick, after preroll; a drain tick that
-            // finds the buffer dry re-arms preroll (the Apple `FrameStore` underflow semantics —
-            // the previous frame persists on glass, a repeat by omission, while headroom
-            // rebuilds). Everything is gated on the tick so an idle stream neither counts
-            // underflows nor churns the preroll flag 200×/s.
-            if !self.vsync_tick {
-                return false;
-            }
-            if !self.prerolled {
-                if self.frames.len() < self.fifo_capacity {
-                    return false;
+            // The smoothing store releases on the DUE time, so there is no drain tick to gate on
+            // and no preroll beneath it. One-frame-per-slot was itself the defect: at 60 fps on a
+            // 120 Hz panel it drains at twice supply, the store empties, preroll re-arms, and the
+            // intervals become 1,3,1,3 where 2,2,2 is the correct answer — the smoothing mode
+            // juddering by construction at exactly the rate mismatch it exists to smooth (design
+            // §4.3, D3). Due times one source period apart snap to every second vblank instead.
+            if !self.head_is_releasable(now_mono_ns, grid_period_ns) {
+                if self.vsync_tick && self.frames.is_empty() {
+                    self.dry += 1;
                 }
-                self.prerolled = true;
-            }
-            if self.frames.is_empty() {
-                self.prerolled = false;
-                self.dry += 1;
-                self.vsync_tick = false; // this tick's drain ran (and found nothing)
+                self.vsync_tick = false; // this tick's evaluation ran (and released nothing)
                 return false;
             }
             self.frames.pop_front()
@@ -463,8 +571,11 @@ impl Presenter {
             }
             return false;
         }
-        // Release: timeline-timed when the clock has one, ASAP otherwise.
-        let target = clock.and_then(|c| c.next_target(now_mono_ns, self.margin_ns));
+        // Release: timeline-timed when the clock has one, ASAP otherwise. Under cadence targeting
+        // the floor is the frame's due time rather than this instant — the source's grid rather
+        // than the network's.
+        let target =
+            clock.and_then(|c| c.next_target(self.not_before_ns(now_mono_ns, frame.due_ns)));
         let released = match target {
             Some(t) => codec
                 .release_output_buffer_at_time_by_index(frame.index, t.expected_present_ns)
@@ -549,6 +660,12 @@ impl Presenter {
     /// codec-pure queued→decoded time) / `e2e` (capture→decoded, skew-corrected — the wireless
     /// A/B headline) / `vsync` (the measured panel period).
     ///
+    /// Under the smoothness intent it carries the cadence loop's health as well — `late‰` of all
+    /// frames folded (a due time already past when the frame became presentable: the direct signal
+    /// the cushion is too small, and WP8's acceptance criterion), `jitter` (the loop residual's
+    /// mean absolute deviation, our first honest per-stream jitter number), `cushion` and
+    /// `reanchors`. Absent under latency, where there is no loop.
+    ///
     /// Returns this window's CIRCULAR latch statistics `(vector-mean latch ns mod panel period,
     /// coherence ‰)` when a window actually flushed — the phase-lock reporter's v2 error signal
     /// (design/phase-locked-capture.md §6; the v1 median was immovable under jitter).
@@ -577,6 +694,21 @@ impl Presenter {
         let period_ms = clock.map(|c| c.period_ns() as f64 / 1e6).unwrap_or(0.0);
         let panel_ns = clock.map(|c| c.panel_period_ns()).unwrap_or(0);
         let (outstanding, _) = meter.outstanding();
+        // Cumulative over the session rather than this window (the loop's counters survive
+        // `reset`): `late` is a RATE question, and one second of it is too few frames to read a
+        // sub-percent criterion off.
+        let cadence = self
+            .cadence_health()
+            .map(|h| {
+                format!(
+                    " late={}‰ jitterMs={:.2} cushionMs={:.2} reanchors={}",
+                    h.late.saturating_mul(1000) / h.frames.max(1),
+                    h.jitter_ns as f64 / 1e6,
+                    h.cushion_ns as f64 / 1e6,
+                    h.reanchors,
+                )
+            })
+            .unwrap_or_default();
         log::info!(
             target: "pf.present",
             "released={} displays={} paced={} noBudget={} forced={} qDry={} \
@@ -584,7 +716,7 @@ impl Presenter {
              paceMs p50={:.2} max={:.2} latchMs p50={:.2} max={:.2} \
              feedMs p50={:.2} max={:.2} codecMs p50={:.2} max={:.2} \
              e2eMs p50={:.2} max={:.2} circ={:.2}ms coh={} \
-             vsyncMs={:.2} panelMs={:.2}",
+             vsyncMs={:.2} panelMs={:.2}{}",
             self.released,
             displays,
             self.paced_drops,
@@ -607,6 +739,7 @@ impl Presenter {
             circ.map(|(_, c)| c).unwrap_or(0),
             period_ms,
             panel_ns as f64 / 1e6,
+            cadence,
         );
         self.released = 0;
         // Margin adaptation, off the MEASURED latch. A release targets the first grid point past
@@ -671,3 +804,108 @@ pub(super) fn presenter_disabled_by_sysprop() -> bool {
     };
     n > 0 && &buf[..n as usize] == b"arrival"
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const SOURCE_HZ: u32 = 120;
+    const P: i64 = 8_333_333; // one 120 Hz source interval, ns
+    /// A host stamping realtime, played out against a monotonic present clock — two different
+    /// eras, which is the whole reason the loop estimates the offset rather than being told it.
+    const PTS0_NS: i64 = 1_786_000_000_000_000_000;
+    const MONO0: i64 = 987_000_000_000;
+    const PTS0_US: u64 = (PTS0_NS / 1000) as u64;
+
+    /// `k`'s pts as the CODEC echoes it — µs, truncated exactly as `feed_ready` queues it — and
+    /// the monotonic instant it became presentable, with `jitter_ns` of transport noise on the
+    /// arrival and none on the source stamp.
+    fn frame(k: i64, jitter_ns: i64) -> (u64, i64) {
+        (((PTS0_NS + k * P) / 1000) as u64, MONO0 + k * P + jitter_ns)
+    }
+
+    #[test]
+    fn the_latency_intent_never_consults_the_cadence_clock() {
+        let mut p = Presenter::new(PresentPriority::Latency, SOURCE_HZ);
+        for k in 0..600 {
+            let (pts_us, ready) = frame(k, (k % 11) * 400_000);
+            assert_eq!(
+                p.due_at(pts_us, ready),
+                None,
+                "latency must produce no due time at all"
+            );
+        }
+        assert!(
+            p.cadence_health().is_none(),
+            "latency holds no loop to have health"
+        );
+        // …so the target floor is exactly what it was before the clock existed: this instant plus
+        // SurfaceFlinger's latch lead, and nothing else.
+        assert_eq!(p.not_before_ns(MONO0, None), MONO0 + p.margin_ns);
+    }
+
+    #[test]
+    fn the_smooth_intent_puts_every_decoded_frame_through_the_loop() {
+        let mut p = Presenter::new(PresentPriority::Smooth { buffer: 2 }, SOURCE_HZ);
+        for k in 0..600 {
+            let (pts_us, ready) = frame(k, (k % 11) * 400_000);
+            assert!(p.due_at(pts_us, ready).is_some());
+        }
+        let h = p.cadence_health().expect("smooth holds a loop");
+        assert_eq!(h.frames, 600);
+        assert_eq!(
+            h.reanchors, 1,
+            "only the cold start anchors on a clean trace"
+        );
+    }
+
+    #[test]
+    fn a_due_time_ahead_of_now_moves_the_target_and_one_behind_it_does_not() {
+        let p = Presenter::new(PresentPriority::Smooth { buffer: 2 }, SOURCE_HZ);
+        let floor = MONO0 + p.margin_ns;
+        // Due ahead: the release aims at the source's grid, which is the entire change.
+        assert_eq!(p.not_before_ns(MONO0, Some(floor + P)), floor + P);
+        // Due already past — a late frame, which the loop deliberately reports unclamped: present
+        // at the next opportunity, never drag the grid back to the frame.
+        assert_eq!(p.not_before_ns(MONO0, Some(floor - 5 * P)), floor);
+    }
+
+    #[test]
+    fn the_store_holds_a_frame_that_is_not_due_yet_and_releases_it_within_reach_of_its_slot() {
+        let mut p = Presenter::new(PresentPriority::Smooth { buffer: 2 }, SOURCE_HZ);
+        let due = MONO0 + 4 * P;
+        p.frames.push_back(HeldFrame {
+            index: 0,
+            pts_us: PTS0_US,
+            decoded_ns: 0,
+            due_ns: Some(due),
+        });
+        assert!(!p.head_is_releasable(MONO0, P), "four refreshes early");
+        assert!(
+            !p.head_is_releasable(due - P - p.margin_ns - 1, P),
+            "one nanosecond outside the submit reach of its own slot"
+        );
+        assert!(
+            p.head_is_releasable(due - P - p.margin_ns, P),
+            "exactly one panel period of reach, the earliest that still buys nothing to wait"
+        );
+        assert!(
+            p.head_is_releasable(due + 10 * P, P),
+            "late frames go at once"
+        );
+    }
+
+    #[test]
+    fn a_frame_carrying_no_due_time_is_always_releasable() {
+        // `HeldFrame` is shared with the latency intent, where the due time is always absent, so
+        // the predicate has to drain on a frame it cannot answer for rather than wedge behind it.
+        let mut p = Presenter::new(PresentPriority::Smooth { buffer: 2 }, SOURCE_HZ);
+        p.frames.push_back(HeldFrame {
+            index: 0,
+            pts_us: PTS0_US,
+            decoded_ns: 0,
+            due_ns: None,
+        });
+        assert!(p.head_is_releasable(MONO0, P));
+    }
+}

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

@@ -93,16 +93,24 @@ impl VsyncShared {
         self.panel_period_ns.load(Ordering::Relaxed)
     }
 
-    /// The release target for a frame submitted at `now`: the earliest stored timeline whose
-    /// EXPECTED PRESENT is still `margin` away, extrapolated forward by whole periods once the
-    /// stored set has aged out (timelines refresh once per vsync callback; a frame can decode
-    /// anywhere inside that window). `None` on the 31/32 fallback — the caller releases ASAP.
+    /// The release target for a frame that must not be presented before `not_before_ns`: the
+    /// earliest stored timeline whose EXPECTED PRESENT is past that instant, extrapolated forward
+    /// by whole periods once the stored set has aged out (timelines refresh once per vsync
+    /// callback; a frame can decode anywhere inside that window). `None` on the 31/32 fallback —
+    /// the caller releases ASAP.
+    ///
+    /// The floor is the CALLER's to compose because two constraints meet in it and only the
+    /// caller knows the second: SurfaceFlinger's latch lead (`now + margin`, always) and, under
+    /// cadence targeting, the frame's own due time on the source's timeline. Adding the submit
+    /// lead here to a due time that is already an absolute present instant would push a frame due
+    /// just under a grid point onto the next one for some phases and not others — judder rather
+    /// than latency, which is the defect the due time exists to remove.
     ///
     /// Gated on `expected_present`, NOT the timeline's `deadline`, on purpose: the deadline
     /// budgets for GPU rendering the app has yet to submit (`presDeadline` — 11.3 ms on the
     /// A024, more than a full 120 Hz period), but a video buffer is already fully rendered —
-    /// the only real constraint is SurfaceFlinger's own latch lead, which is what the caller's
-    /// `margin` represents. Targeting by deadline cost every frame an extra refresh of waiting
+    /// the only real constraint is SurfaceFlinger's own latch lead, which is what the caller
+    /// folds into the floor. Targeting by deadline cost every frame an extra refresh of waiting
     /// (measured: latch p50 ~21 ms vs the ~2-interval floor); a mis-gamble here just means the
     /// frame presents one vsync later — exactly what the conservative gate always paid.
     ///
@@ -110,10 +118,9 @@ impl VsyncShared {
     /// at the app's assigned render rate, but the panel latches at its own — when the app is
     /// down-rated (60 Hz callbacks on a 120 Hz panel) the reported timelines are a whole panel
     /// period apart or more, and pacing to them would cap the video. Pulling the target earlier
-    /// by whole panel periods (while its present still clears the margin) restores the true
-    /// grid; when callbacks run at the panel rate the pull condition is never true and this is
-    /// a no-op.
-    pub(super) fn next_target(&self, now_ns: i64, margin_ns: i64) -> Option<FrameTimeline> {
+    /// by whole panel periods (while its present still clears the floor) restores the true grid;
+    /// when callbacks run at the panel rate the pull condition is never true and this is a no-op.
+    pub(super) fn next_target(&self, not_before_ns: i64) -> Option<FrameTimeline> {
         let mut t = {
             let g = self
                 .timelines
@@ -121,7 +128,7 @@ impl VsyncShared {
                 .unwrap_or_else(std::sync::PoisonError::into_inner);
             let found = g
                 .iter()
-                .find(|t| t.expected_present_ns > now_ns + margin_ns)
+                .find(|t| t.expected_present_ns > not_before_ns)
                 .copied();
             match found {
                 Some(t) => t,
@@ -132,8 +139,8 @@ impl VsyncShared {
                         return None;
                     }
                     // All stored timelines have passed — step the last one forward whole
-                    // periods until its present clears `now + margin` again.
-                    let behind = (now_ns + margin_ns).saturating_sub(last.expected_present_ns);
+                    // periods until its present clears the floor again.
+                    let behind = not_before_ns.saturating_sub(last.expected_present_ns);
                     let k = behind / period + 1;
                     FrameTimeline {
                         expected_present_ns: last.expected_present_ns + k * period,
@@ -144,7 +151,7 @@ impl VsyncShared {
         };
         let panel = self.panel_period_ns.load(Ordering::Relaxed);
         if panel > 0 {
-            while t.expected_present_ns - panel > now_ns + margin_ns {
+            while t.expected_present_ns - panel > not_before_ns {
                 t.deadline_ns -= panel;
                 t.expected_present_ns -= panel;
             }

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};
@@ -31,7 +32,7 @@ const PROTO: &str = "punktfunk/1";
 /// Field separator inside one serialized record (ASCII Unit Separator — never in a field value).
 const FIELD_SEP: char = '\u{1f}';
 
-/// One resolved host, serialized to Kotlin as `key␟name␟addr␟port␟fp␟pair␟mac␟os`
+/// One resolved host, serialized to Kotlin as `key␟name␟addr␟port␟fp␟pair␟mac␟os␟mgmt`
 /// (`␟` = [`FIELD_SEP`]). Records are newline-joined in a poll snapshot; [`Host::encode`] strips
 /// the framing bytes from every field so no value can break it. New fields append (the Kotlin
 /// parser tolerates both arities), never reorder.
@@ -48,6 +49,10 @@ struct Host {
     /// OS-identity chain from the mDNS `os` TXT (`linux/fedora/bazzite`, ...), for the host
     /// card's OS icon. Empty if absent (older host).
     os: String,
+    /// Management-API port from the mDNS `mgmt` TXT — where the game library is served, distinct
+    /// from `port` (the native QUIC plane). `0` if absent. Kotlin persists it on the host record so
+    /// a host that moved off 47990 keeps its library once mDNS is no longer reachable.
+    mgmt: u16,
 }
 
 impl Host {
@@ -60,7 +65,7 @@ impl Host {
             s.replace(['\n', '\r', FIELD_SEP], "")
         }
         format!(
-            "{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}",
+            "{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}",
             clean(&self.key),
             clean(&self.name),
             clean(&self.addr),
@@ -69,6 +74,7 @@ impl Host {
             clean(&self.pair),
             clean(&self.mac),
             clean(&self.os),
+            self.mgmt,
         )
     }
 }
@@ -192,6 +198,8 @@ fn resolve(info: &ResolvedService) -> Option<Host> {
         pair: val("pair"),
         mac: val("mac"),
         os: val("os"),
+        // 0 = the host didn't advertise one (older host); Kotlin then falls back to 47990.
+        mgmt: val("mgmt").parse().unwrap_or(0),
     })
 }
 
@@ -202,7 +210,7 @@ fn resolve(info: &ResolvedService) -> Option<Host> {
 /// [`nativeDiscoveryStop`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop
 #[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() {
@@ -212,15 +220,18 @@ 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 /
+/// newline-joined records of `key␟name␟addr␟port␟fp␟pair␟mac␟os␟mgmt` (`␟` = U+001F). Empty string = no hosts /
 /// `0` handle. Poll ~1 Hz from the UI thread (cheap: a mutex lock + string build).
 #[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 +240,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
@@ -247,7 +256,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPo
 /// [`nativeDiscoveryPoll`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPoll
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -275,10 +284,11 @@ mod tests {
             pair: "required".into(),
             mac: "aa:bb:cc:dd:ee:ff".into(),
             os: "linux/fedora/bazzite".into(),
+            mgmt: 47991,
         };
         let encoded = h.encode();
         let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
-        assert_eq!(fields.len(), 8);
+        assert_eq!(fields.len(), 9);
         assert_eq!(fields[0], "host-123");
         assert_eq!(fields[1], "home-worker-2");
         assert_eq!(fields[2], "192.168.1.70");
@@ -287,6 +297,9 @@ mod tests {
         assert_eq!(fields[5], "required");
         assert_eq!(fields[6], "aa:bb:cc:dd:ee:ff");
         assert_eq!(fields[7], "linux/fedora/bazzite");
+        // A NON-default port on purpose: the whole point of carrying this field is the host that
+        // moved off 47990, so a test pinned to the default would pass against a hardcoded value.
+        assert_eq!(fields[8], "47991");
         assert!(
             !encoded.contains('\n'),
             "a record must never contain the record separator"
@@ -306,13 +319,11 @@ mod tests {
             pair: "required\n".into(),
             mac: "aa:bb\u{1f}cc".into(),
             os: "linux\u{1f}evil/arch".into(),
+            // A numeric field cannot smuggle a separator — it is formatted from a u16, not cleaned.
+            mgmt: 47991,
         };
         let encoded = h.encode();
-        assert_eq!(
-            encoded.matches(FIELD_SEP).count(),
-            7,
-            "exactly eight fields"
-        );
+        assert_eq!(encoded.matches(FIELD_SEP).count(), 8, "exactly nine fields");
         assert!(!encoded.contains('\n') && !encoded.contains('\r'));
         let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
         assert_eq!(fields[0], "kinjected");

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;
 
@@ -62,7 +63,7 @@ const TAG_HID_RAW: u8 = 0x05;
 /// poll thread.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jlong {
@@ -101,94 +102,103 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
 /// Returns the byte count written, or `-1` on timeout / session closed / buffer too small.
 #[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;
@@ -76,7 +77,7 @@ pub extern "system" fn JNI_OnLoad(
 /// linked `punktfunk-core` is the one we expect.
 #[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
@@ -85,11 +86,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_abiVersion(
 /// `NativeBridge.coreVersion(): String` — the crate version, proving JNI string marshaling works.
 #[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,9 +5,10 @@
 //! 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;
 
@@ -16,21 +17,17 @@ use std::time::Duration;
 /// Blocking (builds its own runtime) — Kotlin runs it on `Dispatchers.IO`, never the main thread.
 #[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/access.rs

@@ -0,0 +1,69 @@
+//! The session's access level over JNI — the Android leg of `design/per-client-access.md` §7.
+//!
+//! One poll shim: Kotlin reads `[grants, remainingSecs, updateSeq]` ~1 Hz (alongside its
+//! session-ended watchdog) instead of holding a blocking event thread — access news is a
+//! console edit or an expiry warning, a handful per session, and every gate the mask drives
+//! re-checks within a second anyway. The connector already folds each mid-session
+//! [`punktfunk_core::quic::AccessUpdate`] latest-wins into its live grants/deadline slots;
+//! the seq counter here only exists so the poller can tell a FRESH update arrived (the host's
+//! T−5 m / T−1 m warnings owe a toast) without diffing state that a warning doesn't change.
+
+use jni::errors::LogErrorAndDefault;
+use jni::objects::{JIntArray, JObject};
+use jni::sys::jlong;
+use jni::EnvUnowned;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+
+use super::SessionHandle;
+
+/// `NativeBridge.nativeAccessState(handle): IntArray?` — the live access state as
+/// `[grants, remainingSecs, updateSeq]`; `null` on a `0` handle. `grants` is the
+/// `GRANT_GAMEPAD`-family bitmask, seeded from the Welcome's advert (an old host reads as
+/// `GRANT_ALL` — full control, today's behavior); `remainingSecs` counts down to the access
+/// deadline on the CLIENT's clock (`0` = permanent, clamped to ≥ 1 once a deadline exists so
+/// the sentinel can never be reached by counting); `updateSeq` increments once per
+/// `AccessUpdate` drained from the connector's event plane. Not android-gated — pure `jni` +
+/// connector reads, so it links on the host build too. Cheap; safe on the UI thread.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeAccessState<'local>(
+    mut env: EnvUnowned<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> JIntArray<'local> {
+    env.with_env(|env| -> jni::errors::Result<JIntArray<'local>> {
+        if handle == 0 {
+            return Ok(JIntArray::default());
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        // Drain the event plane into the seq counter. The connector's grants/deadline slots
+        // are already the latest-wins fold when an event lands — the events carry no state
+        // this read doesn't get below, they are purely the "something arrived" cue. Zero
+        // timeout: this is the UI thread's poll, it must never park.
+        while h.client.next_access_update(Duration::ZERO).is_ok() {
+            h.access_seq.fetch_add(1, Ordering::Relaxed);
+        }
+        let remaining: u64 = match h.client.access_deadline_unix() {
+            None => 0, // permanent
+            Some(deadline) => {
+                let now = std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .map_or(0, |d| d.as_secs());
+                // ≥ 1 once a deadline exists: 0 is the "permanent" sentinel, and a deadline
+                // already past with the session still up (the host's typed close is in
+                // flight) must keep reading as "about to end", never flip to "forever".
+                deadline.saturating_sub(now).max(1)
+            }
+        };
+        let buf: [i32; 3] = [
+            h.client.access_grants() as i32,
+            remaining.min(i32::MAX as u64) as i32,
+            h.access_seq.load(Ordering::Relaxed) as i32,
+        ];
+        let arr = env.new_int_array(buf.len())?;
+        arr.set_region(env, 0, &buf)?;
+        Ok(arr)
+    })
+    .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};
@@ -42,26 +43,39 @@ fn client(handle: jlong) -> Option<&'static SessionHandle> {
 /// `NativeBridge.nativeClipSupported(handle)` — the host advertised `HOST_CAP_CLIPBOARD`.
 #[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.nativeHostMgmtPort(handle)` — the management-API port the host reported in this
+/// session's `Welcome`, or `0` if it advertised none (older host / no management API).
+///
+/// Kotlin persists this on the host record, which is what lets the library screen reach a host that
+/// moved its mgmt port off 47990 WITHOUT ever having seen an mDNS advert — the VPN / routed-subnet
+/// / added-by-address cases, where the `mgmt` TXT the discovery path relies on never arrives.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostMgmtPort(
+    _env: EnvUnowned,
+    _this: JObject,
+    handle: jlong,
+) -> jint {
+    client(handle).map_or(0, |h| jint::from(h.client.mgmt_port()))
 }
 
 /// `NativeBridge.nativeClipControl(handle, enabled)` — session-level opt-in/out. Nothing
 /// clipboard-related happens on either side until an `enabled: true` crosses.
 #[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);
     }
 }
 
@@ -70,7 +84,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipControl
 /// counter, newest wins.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipOfferText(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     seq: jint,
@@ -90,7 +104,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipOfferTe
 /// Returns the transfer id echoed on the matching `data:`/`error:` event, or −1.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipFetchText(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     seq: jint,
@@ -108,26 +122,32 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipFetchTe
 /// clipboard's current text (the host is pasting our offer).
 #[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).
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipCancel(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     id: jint,
@@ -145,38 +165,41 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClipCancel(
 /// clipboard task delivers a whole payload in ONE event (`last = true`), so a chunk boundary
 /// can never split a UTF-8 sequence.
 #[unsafe(no_mangle)]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextClip(
-    env: JNIEnv,
-    _this: JObject,
+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};
@@ -38,14 +39,12 @@ fn note_error(e: &punktfunk_core::error::PunktfunkError) {
 /// handle / `""` fingerprint.
 #[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.
@@ -53,9 +52,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeTakeLastErr
 /// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
 #[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
@@ -76,11 +73,11 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIde
 /// toggle rides explicit per-session parameters (`nativeStartVideo` / `nativeStartAudio`).
 #[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
@@ -123,7 +120,7 @@ fn force_parts_sysprop() -> bool {
 #[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
@@ -305,6 +315,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
                 pad_audio: Mutex::new(None),
                 // A fresh session is never muted (mute is per-session UI state, not a setting).
                 mic_muted: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+                access_seq: std::sync::atomic::AtomicU32::new(0),
             };
             Box::into_raw(Box::new(handle)) as jlong
         }
@@ -324,7 +335,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
 /// closed exactly once and not concurrently with other calls on the same handle (Kotlin owns this).
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -346,7 +357,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
 /// not freed / closed concurrently with this call (Kotlin still owns it and closes it via `nativeClose`).
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDisconnectQuit(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -365,10 +376,10 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDisconnectQ
 /// connect. `""` on a `0` handle.
 #[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 +387,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?
@@ -390,17 +399,17 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerp
 /// handle. Cheap (one atomic load); safe on the UI thread.
 #[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()
     })
 }
 
@@ -415,7 +424,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSessionEnde
 /// atomic load); safe on the UI thread.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeEndReason(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) -> jint {
@@ -436,7 +445,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeEndReason(
 #[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 +453,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,
@@ -37,7 +38,7 @@ 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).
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerMove(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     dx: jint,
@@ -53,7 +54,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointer
 /// cursor jumps to the finger — and matches the Apple client's absolute touch forwarding.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerAbs(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     x: jint,
@@ -70,13 +71,13 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointer
 /// `button`: GameStream id (1=left, 2=middle, 3=right, 4=X1, 5=X2). `down`: 1=press, 0=release.
 #[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
@@ -88,7 +89,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointer
 /// 1=horizontal. `delta`: signed, WHEEL_DELTA(120)-scaled, +=up/right.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     axis: jint,
@@ -105,7 +106,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
 /// (libei touchscreen / wlroots / SendInput).
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendTouch(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     id: jint,
@@ -130,7 +131,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendTouch(
 /// bitmask (0 for now — the host folds modifiers from the L/R modifier key events themselves).
 #[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
@@ -153,16 +154,16 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
 /// the real IME `InputConnection` over the TYPE_NULL raw-key fallback. `0` handle → false.
 #[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
@@ -170,16 +171,16 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeTextInputSu
 /// (design/pen-tablet-input.md §7). `0` handle → false.
 #[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.
@@ -199,65 +200,69 @@ const PEN_JNI_MAX_SAMPLES: usize = PEN_BATCH_MAX * 8;
 /// while in range (Kotlin side — see `StylusStream`).
 #[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
@@ -266,20 +271,24 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPen(
 /// [`Java_io_unom_punktfunk_kit_NativeBridge_nativeTextInputSupported`] returned true.
 #[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 ---------------
@@ -298,7 +307,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendText(
 /// 0=release. `pad`: wire pad index 0..15 (rides `flags`).
 #[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,
     );
@@ -320,7 +329,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 /// (−32768..32767, +y=up) or trigger 0..255. `pad`: wire pad index 0..15 (rides `flags`).
 #[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,
@@ -345,7 +354,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 /// the session-default kind from the handshake — the pre-existing single-pad behaviour on pad 0).
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadArrival(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pref: jint,
@@ -375,24 +384,24 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 /// the `Auto` rule inside the predicate itself.
 #[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
@@ -401,7 +410,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePadMotionRe
 /// pad) and arms a re-send burst against datagram loss. An older host ignores the unknown tag.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadRemove(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
     pad: jint,
@@ -417,36 +426,40 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 /// own report rate (~250–500 Hz) — the direct-buffer read avoids a JNI array copy per report.
 #[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
@@ -457,7 +470,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadHidR
 /// the capture diffs, the host holds per-slot state.
 #[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,
     });
@@ -488,7 +501,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadTouc
 #[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/mod.rs

@@ -17,6 +17,7 @@
 //! TODO(M4 Android stage 1): client→host DualSense rich input (`send_rich_input`), mode
 //! renegotiation. Port the remaining orchestration from `clients/linux`.
 
+mod access;
 mod clipboard;
 mod connect;
 mod input;
@@ -25,7 +26,7 @@ mod probe;
 
 use punktfunk_core::client::NativeClient;
 use std::panic::AssertUnwindSafe;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread::JoinHandle;
 
@@ -82,6 +83,10 @@ pub(crate) struct SessionHandle {
     /// fresh capture could send an unmuted frame. Per session and never persisted: a new session
     /// starts unmuted.
     pub mic_muted: Arc<AtomicBool>,
+    /// Count of `AccessUpdate`s drained from the connector's event plane, bumped by the
+    /// `nativeAccessState` poll ([`access`]) — how the Kotlin poller tells a fresh update
+    /// (the host's expiry warnings) arrived without holding a blocking event thread.
+    pub(crate) access_seq: AtomicU32,
 }
 
 struct VideoThread {

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};
 
@@ -21,7 +19,7 @@ use super::{jni_guard, lock_recover, SessionHandle};
 #[cfg(target_os = "android")]
 #[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
@@ -93,21 +96,19 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
 #[cfg(target_os = "android")]
 #[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
@@ -118,21 +119,19 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoMime<'
 #[cfg(target_os = "android")]
 #[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
@@ -142,28 +141,26 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoCodecL
 /// device).
 #[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`.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -211,19 +208,19 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
 /// 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).
 #[unsafe(no_mangle)]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
-    env: JNIEnv,
-    _this: JObject,
+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
@@ -313,14 +306,14 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
 /// 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.
 #[unsafe(no_mangle)]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoSize(
-    env: JNIEnv,
-    _this: JObject,
+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
@@ -348,7 +337,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoSize(
 /// pure `jni` + an atomic store, so it links on the host build too.
 #[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")]
 #[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)"),
     }
@@ -400,7 +390,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
 #[cfg(target_os = "android")]
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -424,7 +414,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
 #[cfg(target_os = "android")]
 #[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);
@@ -459,7 +449,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
 #[cfg(target_os = "android")]
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
-    _env: JNIEnv,
+    _env: EnvUnowned,
     _this: JObject,
     handle: jlong,
 ) {
@@ -487,7 +477,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
 #[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,
         }
     })
 }
@@ -533,7 +523,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartPadAud
 #[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,
@@ -556,7 +546,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePadAudioSel
 #[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,
@@ -596,7 +586,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopPadAudi
 /// no captured audio leaves the process.
 #[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);
         }
     })
 }
@@ -619,16 +609,16 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetMicMuted
 #[cfg(target_os = "android")]
 #[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.
@@ -25,25 +26,25 @@ const PROBE_RESULT_LEN: usize = 6;
 /// Starting a probe resets any prior measurement. `false` on a `0` handle or a closed session.
 #[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
             }
         }
     })
@@ -56,13 +57,15 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSpeedTest(
 /// `[done, throughputKbps, lossPct, hostDropPct, elapsedMs, recvBytes]`.
 #[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,8 +3,9 @@
 //! 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
@@ -12,29 +13,25 @@ use jni::JNIEnv;
 /// Returns true if at least one datagram went out.
 #[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
@@ -365,9 +354,14 @@ struct ContentView: View {
                 // Persist on the next runloop tick: HostStore is an ObservableObject, and mutating
                 // its @Published from inside .onChange (a view-update callback) trips SwiftUI's
                 // "Publishing changes from within view updates". A one-tick delay is imperceptible.
+                // The session's own Welcome told us where this host's library lives — the one
+                // source that does not need an mDNS advert, so it also covers a host reached by
+                // address over a VPN. 0 = not advertised; updateMgmtPort ignores it.
+                let liveMgmtPort = model.connection?.hostMgmtPort
                 let store = store
                 DispatchQueue.main.async {
                     store.markConnected(host.id)
+                    store.updateMgmtPort(host.id, port: liveMgmtPort)
                     if let approvedFingerprint { store.pin(host.id, fingerprint: approvedFingerprint) }
                 }
             case .idle:
@@ -384,7 +378,11 @@ struct ContentView: View {
         #if !os(tvOS)
         .focusedSceneValue(\.sessionFocus, SessionFocus(
             isStreaming: model.connection != nil,
-            clipboardAvailable: model.connection?.hostSupportsClipboard == true,
+            // Host cap AND this device's CLIPBOARD grant (per-client access §7) — an
+            // ungranted session's menu item greys out instead of inviting a refused enable.
+            clipboardAvailable: model.connection.map {
+                $0.hostSupportsClipboard && $0.canUseClipboard
+            } == true,
             clipboardOn: model.clipboardEnabled,
             toggleClipboard: { model.toggleClipboardSync() },
             micAvailable: model.micAvailable,
@@ -453,6 +451,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 +824,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 +844,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 +855,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 +994,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
@@ -1040,7 +1067,25 @@ struct ContentView: View {
                             MotionUnreachableBadge()
                                 .transition(.opacity.combined(with: .scale(scale: 0.9)))
                         }
+                        // The expiry-warning toast (T−5 m / T−1 m, per-client access §7) —
+                        // transient, every platform, every tier: "the pad just died" must
+                        // read as "the evening's access ended" while it can still be fixed.
+                        if captureEnabled, let warning = model.accessWarning {
+                            AccessWarningBadge(text: warning)
+                                .transition(.opacity.combined(with: .scale(scale: 0.9)))
+                        }
                         #if !os(tvOS)
+                        // The access chip — up for the life of a LIMITED session ("Controller
+                        // only · ends in 1 h 58 m"), at every tier and with the overlay off.
+                        // Never mounted for a full-and-permanent session (every old host):
+                        // today's look must not change there. tvOS states it as a line in the
+                        // stats overlay instead (StreamHUDView).
+                        if captureEnabled && model.accessLimited {
+                            AccessChipBadge(
+                                label: model.accessLevel.label,
+                                remainingSecs: model.accessRemainingSecs)
+                                .transition(.opacity.combined(with: .scale(scale: 0.9)))
+                        }
                         // Shown for as long as the mic is muted, at every stats tier and with the
                         // overlay off — see MicMutedBadge. tvOS has no microphone to mute.
                         if captureEnabled && model.micMuted {
@@ -1048,34 +1093,20 @@ 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)
+                    .animation(.easeOut(duration: 0.2), value: model.accessWarning)
+                    .animation(.easeOut(duration: 0.2), value: model.accessLimited)
                 }
                 #if os(iOS)
                 // Touch users have no menu / ⌘D, so when the HUD's Disconnect button isn't on
@@ -1139,23 +1170,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
 
@@ -1273,6 +1291,9 @@ struct ContentView: View {
         if let live = discovery.hosts.first(where: { host.matches($0) }) {
             store.updateMacs(host.id, macs: live.macAddresses) // learn — on every platform
             store.updateOsChain(host.id, chain: live.osChain) // ditto for the card's OS mark
+            // ...and the mgmt port, so the library keeps working against a host that moved it once
+            // this device can no longer see the advert (VPN, routed subnet, multicast-dead Wi-Fi).
+            store.updateMgmtPort(host.id, port: live.mgmtPort)
         } else if autoWakeEnabled, PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty {
             // Auto-wake only: fire the up-front packet so a genuinely-asleep host is booting while the
             // dial times out. With auto-wake off, connects go straight through (no packet).
@@ -1331,6 +1352,7 @@ struct ContentView: View {
         guard !model.isBusy else { return }
         let host = StoredHost(
             name: d.name, address: d.host, port: d.port,
+            mgmtPort: d.mgmtPort,
             macAddresses: d.macAddresses.isEmpty ? nil : d.macAddresses,
             osChain: d.osChain.isEmpty ? nil : d.osChain)
         store.add(host)

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 }))
@@ -503,8 +551,10 @@ struct GamepadHomeView: View {
                     filled: true,
                     // A pinned card reaches the library too, and gets its OWN shelf: browsing is
                     // this card's connect with a title picked first, not a host-level action like
-                    // wake or forget.
-                    hasLibrary: true,
+                    // wake or forget. Gated on a pinned identity: the library plane's MgmtTransport
+                    // accepts any cert for an unpinned host, so an unpaired host must not expose a
+                    // library affordance a LAN MITM could answer. security-review 2026-08-15 #8.
+                    hasLibrary: host.pinnedSHA256 != nil,
                     osChain: host.osChain,
                     canWake: autoWakeEnabled && PunktfunkConnection.wakeOnLANAvailable
                         && !online && !host.wakeMacs.isEmpty,
@@ -543,6 +593,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 +761,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 +774,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 +786,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/HomeView.swift

@@ -268,7 +268,12 @@ struct HomeView: View {
         let selection: ProfileSelection = pinned.map { .profile($0.id) } ?? .inherit
         // …and browsing is that same connect with a title picked first, so a pinned card opens its
         // OWN shelf: every launch off it carries the card's profile rather than the host's binding.
-        let onBrowseLibrary: (() -> Void)? = libraryEnabled
+        // Gated on a pinned identity, not just the feature toggle: the library plane's
+        // MgmtTransport trust-on-first-use accepts ANY cert for a pin-less host (self-signed, no
+        // SAN — system trust is bypassed), so browsing an unpinned host lets a LAN MITM serve a
+        // forged catalog and harvest the device's pairing identity. Pair first, exactly as the
+        // stream path already refuses an unpinned connect. security-review 2026-08-15 finding 8.
+        let onBrowseLibrary: (() -> Void)? = (libraryEnabled && host.pinnedSHA256 != nil)
             ? { libraryTarget = LibraryTarget(host: host, profile: selection) }
             : nil
         return HostCardView(

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

@@ -19,9 +19,12 @@ 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?
+    let artLoader: (any LibraryArtSource)?
     var onLaunch: ((String) -> Void)?
     /// Button B (back) — dismisses the library screen. No touch equivalent needed here (the toolbar
     /// Close button already covers that); this is what makes gamepad-only exit possible.

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

@@ -74,7 +74,7 @@ struct LibraryView: View {
     @State private var errorText: String?
     /// Cover-art loader (the same paired identity + host pinning as the list fetch, reused across
     /// every poster in the grid). Built alongside `games` in `load()`; dropped on disappear.
-    @State private var artLoader: LibraryArtLoader?
+    @State private var artLoader: (any LibraryArtSource)?
     #if os(iOS) || os(macOS)
     /// The plain grid's hardware-keyboard cursor (a game id), and the grid width the column count
     /// is derived from. nil until the first arrow press, so a touch user never sees a selection
@@ -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
@@ -335,6 +357,17 @@ struct LibraryView: View {
             loading = false
             return
         }
+        // Beyond the client identity, require the HOST's pinned fingerprint. MgmtTransport accepts
+        // ANY cert for a pin-less host (self-signed, no SAN → system trust is bypassed), so browsing
+        // one lets a LAN MITM serve a forged catalog and harvest this device's mTLS identity. A host
+        // can hold a client identity yet no host pin (abandoned pairing, or after "Forget
+        // Identity"), so this is a distinct check. security-review 2026-08-15 finding 8.
+        guard current.pinnedSHA256 != nil else {
+            games = []
+            errorText = "Pair with this host before browsing its library."
+            loading = false
+            return
+        }
         do {
             // `launchersFirst` groups launcher entries ahead of titles once, here, so the grid and
             // the gamepad coverflow both inherit the D4 ordering.
@@ -387,7 +420,7 @@ private struct LibraryBackCatcher: View {
 /// (portrait → header → hero) and finally a text placeholder.
 private struct GameCard: View {
     let game: GameEntry
-    let artLoader: LibraryArtLoader?
+    let artLoader: (any LibraryArtSource)?
     /// The hardware-keyboard cursor is on this tile — drawn as an accent ring, since the plain
     /// grid has no other way to say "Return launches THIS one".
     var selected = false