fix(host): video egressed from whichever interface routing picked, not the one the client dialed

`bind_data_socket` bound `0.0.0.0:0`, so the kernel chose the video source
address from the routing table, independently of the address the client's
control connection actually arrived on. The client's data socket is
`connect`ed to the host IP it dialed, so its kernel drops every datagram from
any other source — before userspace, where nothing counts it.

On a host with two live paths to the client (Ethernet and Wi-Fi both up on the
same LAN; a VPN/overlay adapter claiming the route) that is a permanent black
screen with every gauge green: the hole-punch still arrives so the host logs
`punched=true`, `loss_ppm` stays 0 because there are no packets to see gaps
in, and QUIC — which quinn pins to the right local address — carries control,
audio and input perfectly. `from_socket_punch` already documents the mirror of
this assumption for the *client's* source IP; the host side was never checked.

Bind the data socket to `Connection::local_ip()` instead (unmapping an
IPv4-mapped v6 address so the socket can still `connect` to a v4 peer), and
fall back to the wildcard, loudly, when it is unavailable.

Two diagnostics, because this session's log could not answer the question:
- the `data plane bound` line now carries the socket's post-`connect` `local=`
  address — the source the kernel will actually stamp — and WARNs when it
  differs from the address the control plane arrived on.
- the black-screen ERROR no longer asserts "This is a PATH problem, not
  decode" and no longer names `punched=false` as *the* fingerprint. It fired
  with `punched=true` in the field, which contradicts its own advice and sent
  an investigation at the firewall. It now branches on what the bring-up line
  says, and admits its counter is incremented after decrypt and replay checks,
  so a session whose every datagram failed to open reports the same zero.

CHANGELOG.md

@@ -12,6 +12,278 @@ with the version table of the release you are moving to, then read **Breaking ch
 
 ---
 
+## v0.31.1
+
+30 commits since v0.31.0 (19 non-merge), counted at the tip this was cut from.
+
+**No versioned surface moves.** `WIRE_VERSION` stays **2**, the C ABI stays **25**, and so do the
+driver protocol, the gamepad channel, the plugin index schema and the host event schema. No C
+function changed its signature, no `#[repr(C)]` struct grew a field, and `include/punktfunk_core.h`
+gains exactly one line: a `#define` for a new control-message type byte. An embedder rebuilds
+against the new header and is done; a packager has one thing to notice (the Windows firewall rule
+below) and one thing to be glad of (the Arch compositor package finally declares the level it
+builds).
+
+Two surfaces grow, both by pure addition: the **management API** gains
+`PUT /library/provider/{provider}/running` and its three schemas, and **`@punktfunk/plugin-kit`
+goes 0.4.3 → 0.4.4** to export the client call for it. A plugin that adopts neither is unaffected,
+and an older host answers the route with a 404 that means "this host tracks games by scanning".
+
+One control message is **added** to the wire — `DeliveryReport`, type byte **`0x0B`** — which is a
+`#define`, not an ABI step, exactly as `PipelineGap` (`0x0A`) was at v0.30.0. It takes a free byte
+in its block rather than lengthening an existing message, deliberately: see below.
+
+Two behaviour changes are worth reading before you package or embed this release: on Windows,
+`service install` now provisions a **program-scoped inbound UDP rule** for the host executable, and
+the **GameStream plane's default virtual-Xbox backend flips from the XUSB companion to the UMDF HID
+pad**, matching what the native plane has done since 2026-08-09.
+
+### Versions
+
+| | v0.31.0 | v0.31.1 | Notes |
+|---|---|---|---|
+| Wire protocol | 2 | **2** | unchanged. One additive control message, `DeliveryReport` (`0x0B`), which an older peer does not parse and does not need — see **The wire** below |
+| C ABI | 25 | **25** | unchanged. `include/punktfunk_core.h` differs from the v0.31.0 tag by one `#define` (`PUNKTFUNK_MSG_DELIVERY_REPORT = 11`, under `PUNKTFUNK_FEATURE_QUIC`), which is a constant, not a declaration. Rust-only addition in `punktfunk-core`: `client::NO_VIDEO_RETRY` is now public beside `client::FLUSH_COOLDOWN` |
+| Rust edition | 2024 | **2024** | unchanged |
+| MSRV (`rust-version`) | 1.85 | **1.85** | unchanged |
+| Workspace crate dirs | 27 | **27** | unchanged (39 `[workspace] members`, also unchanged) |
+| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3); `pf-driver-proto` shows no diff against the v0.31.0 tag |
+| Windows virtual-gamepad channel | 3 | **3** | unchanged. What changed is which *backend* the GameStream plane picks, not the channel — see **Windows: the GameStream plane builds the pad games can see** |
+| Plugin index schema | 1 | **1** | unchanged |
+| Host event schema | 1 | **1** | unchanged (`punktfunk-host/src/events.rs`) |
+| `api/openapi.json` | 0.31.0 | **0.31.1** | one route **added** — `PUT /library/provider/{provider}/running` plus its three schemas — and the stamp moved with the crate (`info.version` is `CARGO_PKG_VERSION`). Regenerated in #361 and re-stamped here; nothing else in the document differs. `api/` and `docs-site/public/` are byte-identical to each other |
+| gamescope patch level (`+pfhdrN`) | 8 | **8** | unchanged; no new patch files. ⚠ **`packaging/gamescope/PKGBUILD` is fixed here**: it declared `pfhdr7` while patch 0010 stamps `+pfhdr8` into the banner, so pacman saw no upgrade at all — see below |
+| `@punktfunk/host` (SDK) | 0.1.5 | **0.1.5** | unchanged; nothing under `sdk/` moved |
+| `@punktfunk/plugin-kit` | 0.4.3 | **0.4.4** | cut, for `ProviderClient.reportRunning` and its two types: they were reachable only through the deep `./reconcile.js` path, because `index.ts` re-exports an explicit list rather than a star, so no plugin could import them from the package root. Tagged `plugin-kit-v0.4.4` and **published** — the registry's `latest` (0.4.2 is still skipped there, as it has been since v0.30.0). The playnite plugin deliberately does *not* depend on it, calling the route through the untyped host seam so it was never gated on this publish |
+
+### ⚠ Breaking changes
+
+**None.** No wire change, no ABI change, no driver-protocol change, no plugin-contract change. Every
+0.31.0 host, client, driver and plugin keeps interoperating in both directions with no re-pairing.
+
+Two **behaviour** changes that break no build but change what a machine does:
+
+- **Windows `service install` adds a second firewall rule.** `Punktfunk UDP (data plane)` —
+  `dir=in action=allow protocol=UDP program=<host exe>`, on the same profile set the port rules use.
+  `service uninstall` deletes it by name. If you provision firewall rules yourself instead of
+  letting `service install` do it, you need the equivalent, or your hosts keep the black-picture
+  failure below. Program-scoped rather than port-scoped by design: the data plane binds `0.0.0.0:0`,
+  and a pinned port inside 47998-48010 would collide with Sunshine/Apollo.
+- **`PUNKTFUNK_XBOX_BACKEND` now governs both planes on Windows, and the GameStream plane's default
+  moves to the HID pad.** `PUNKTFUNK_XBOX_BACKEND=xusb` reverts both planes together; it previously
+  reverted only the native one, because `windows_xbox_hid` was `pub(super)` and unreachable from
+  `gamestream/control.rs`. It is `pub(crate)` now, with one definition and one name.
+
+### A provider plugin can report which of its titles are running
+
+The host derives liveness by **scanning**, which needs something recognizable on disk. A
+Playnite-launched emulated game, a manually added one, or a library plugin that records no install
+directory has none — and its launch is a `playnite://` hand-off, so the host holds no process
+either. The lease went `Untracked`: the exit was never noticed, `session_on_game_exit` could not
+fire, and `POST /game/end` had nothing to aim at.
+
+**`PUT /library/provider/{provider}/running`** takes a provider's *complete* running set (with the
+pid where it knows one) — declarative and idempotent like the reconcile beside it, so a missed event
+or a plugin restart self-corrects rather than drifting. `crate::runstate` holds it and **expires it
+after 90 s unless restated**, which is what makes it safe for a live provider to hold a session open
+for a game the host cannot see: a plugin that dies stops counting and the host falls back to
+scanning. The route is the plugin lane's, like the reconcile, and carries **no new authority** — the
+host maps `external_id` through the catalog, so a provider can only speak about entries it
+published. An unknown id is *counted, not refused*, because a report legitimately races its own
+reconcile and 400-ing the batch would discard the liveness of every other running title.
+
+**`LeaseKind::Reported`** is the lease that follows. `open` reaches it when the spec is empty and a
+provider speaks for the id, and — load-bearing on Windows, where every launch is a hand-off by
+construction — the three shim reclassification paths now fall back to it where they fell to
+`Untracked`. Phase 1 takes "running" as the game appearing; phase 2 takes "stopped" as the exit.
+Unlike `procscan::running_hint`, which may only ever *delay* an exit (Steam's registry flag survives
+an unclean one), a fresh report is decisive in both directions. A reported pid joins the termination
+ladders on the same terms as a spawned one: re-resolved and start-time-pinned at the moment of use.
+
+Client side, `ProviderClient.reportRunning` is exported from the plugin-kit root in 0.4.4 (see the
+table). A **404 from an older host means "this host tracks games by scanning"** — it is not an error
+a plugin should retry.
+
+### The wire: `DeliveryReport` (`0x0B`)
+
+`LossReport` carries `loss_ppm`, which is a ratio over the packets that **arrived** — so a flawless
+link and a link delivering nothing both report `0`. A host reading total silence as perfection
+decayed adaptive FEC to its floor and logged confident wording about the client's network.
+
+Clients now also send `DeliveryReport`, carrying the session's received-packet count. It is a **new
+type byte, not a field appended to `LossReport`**: that message is length-checked exactly, so
+lengthening it would make every shipped host reject the loss reports its FEC runs on. Send policy is
+deliberately sparse — every window while the count is zero, once when the first packets land, then
+never — because an older host warns per unknown message type and must not be flooded across a good
+session.
+
+`client::NO_VIDEO_RETRY` (the client got nothing) and `client::FLUSH_COOLDOWN` (the client is
+drowning) were both 2000 ms, so the host's cadence classifier could not tell two opposite faults
+apart and named the wrong one out loud. `NO_VIDEO_RETRY` moves into `punktfunk-core` beside
+`FLUSH_COOLDOWN` at **2600 ms**, and both sides now compare against the shared constant rather than
+against a local copy.
+
+### Windows: the data plane was never open, on any host
+
+The firewall rules `service install` writes are `localport=`-scoped (47998-48010, 9777, 5353), and
+the media data plane binds an **ephemeral** port per session. No such rule can cover it, so Windows
+Firewall dropped the client's hole-punch on **every session on every Windows host** — `punched=false`
+on the "data plane bound" line, in all six sessions across two field logs, including sessions that
+appeared to work. Video then fell back to blind-sending at the address the client *reported*; where
+the path needed the flow opened client-first, the control plane stayed healthy and the picture never
+arrived. One field host sent 1,919 frames into a black screen while blaming the client.
+
+Diagnosis changed with it: it now leads with the delivery count (zero is an **error** naming the data
+plane; a confirmed count keeps the old confident wording; a client that cannot answer gets a warning
+that says so), and a punch that never arrives is its own warning rather than a debug field on an info
+line.
+
+### Windows: the GameStream plane builds the pad games can see
+
+There are two virtual Xbox backends on Windows and they are not interchangeable to a game. The XUSB
+companion registers only `GUID_DEVINTERFACE_XUSB` and exposes no HID collection (`pf_xusb.inx`:
+"a non-HID UMDF2 driver", `Class = System`), so Steam's hidapi enumeration, SDL, RawInput,
+DirectInput, `joy.cpl` and WGI/GameInput cannot see it at all — only classic `XInputGetState` can.
+The native plane moved to the real HID pad as its default in `bd5735b8` for exactly that reason.
+
+`gamestream/control.rs` had bound `crate::inject::gamepad` since the first gamepad commit, when that
+name meant uinput and Windows had no second backend; Windows later gave the same name the XUSB
+companion, so this plane inherited it by module-name coincidence rather than by decision. Every
+Moonlight-compatible session since has presented a pad most games cannot enumerate. A `SessionPads`
+enum is now the one place this plane picks a backend, reading the same knob the native plane reads.
+The HID pad's rich-feedback plane is dropped rather than plumbed: an Xbox pad has no lightbar or
+adaptive triggers, and GameStream's rumble message (`0x010B`) carries the two handle motors only.
+
+### Android: buttons resolved from the scancode
+
+Android names a pad's buttons through a **key layout file** matched on VID/PID; a pad with no
+matching file falls back to AOSP's `Generic.kl`, which assigns keycodes by **scancode position**
+(`0x130`→`BUTTON_A`, `0x131`→`BUTTON_B`, …). A HID gamepad with no kernel driver numbers its buttons
+`1..n` in its own report order, so every keycode past the first divergence is somebody else's button.
+AOSP ships no layout for the Elite Series 2 over Bluetooth (`045e:0b05`) on any version, and the
+DualSense's (`054c:0ce6`) postdates Fire OS and requires `CONFIG_HID_PLAYSTATION`, which a Fire TV
+kernel has not.
+
+`Gamepad.padKeyCode(event)` is a drop-in for `event.keyCode` and **every** pad reader now goes
+through it — the streaming branch, the Skia console shell's probe, the older Compose navigation, and
+the Controllers tester. Two guards keep it off pads that already work: the correction applies only
+where the delivered keycode is what `Generic.kl` would have said, and which report order to read is
+decided from what the device *declares* (a pad numbering straight through claims `BUTTON_C` and
+`BUTTON_Z`, keycodes no real controller has a button for) rather than from a model table. Axes get
+the same treatment, with trigger rest position measured from the device's own range instead of
+assumed. The Xbox Bluetooth product ids (One S, Elite Series 2 and its Core) join the identity table.
+
+Also here: `pads()` filters on `looksLikeController` (the source claim **and** hardware behind it)
+rather than on `isPad`, which kept the console UI pinned on for any device merely claiming the
+gamepad source class; and the `ASurfaceControl` layer's destination rect is now read per-present from
+a packed atomic on the session handle (new JNI symbol `nativeVideoSurfaceSize`, fed from every
+`surfaceChanged`) rather than captured once at `surfaceCreated`, which is why the picture sat at the
+origin once the bars and cutout grew the view.
+
+### gamescope and the takeover
+
+- **`packaging/gamescope/PKGBUILD` moves `pfhdr7` → `pfhdr8`.** The banner has said `+pfhdr8` since
+  patch 0010 (the seat's stub keyboard carrying the compiled `XKB_DEFAULT_*` keymap), and the host
+  probes the banner for `>= 8` on the keymap path — but pacman compares `pkgver-pkgrel`, read
+  `3.16.25.pfhdr7-1` on both v0.30.0 and v0.31.0, and **offered no upgrade at all**. deb and rpm
+  derive their version from the binary banner and moved by themselves; Arch is the only channel that
+  hardcodes it. This is the mismatch the v0.31.0 table flagged as pre-existing.
+- **The in-stream session-select gate is armed again.** v0.31.0's takeover stopped stopping the
+  display manager and started idling the autologin session (`c2f5e91b`), which also deleted the two
+  lines the old path carried (`record_session_select_baseline()`, `STOPPED_DM = Some(dm)`);
+  `38a0f54b` then removed every remaining writer, leaving `honor_session_select_switch` unreachable.
+  Bazzite/SteamOS never noticed — their `os-session-select` writes no sentinel and
+  `is_steam_htpc_platform()` defaults the mid-stream watcher on. `ID=nobara` matches no HTPC default
+  and its ChimeraOS-layout `os-session-select` **does** write the sentinel, so on Nobara a mid-stream
+  "Switch to Desktop" went entirely unhandled. `takeover_idled()` now reads `IDLE_DROPIN_ARMED`, the
+  idle drop-in re-baselines the sentinel, and `STOPPED_DM` is documented as adoption-only state for a
+  takeover stranded by a pre-0.31.0 host. Both hand-back paths also restore the box's own Game Mode
+  unit, which neither did — a mid-stream switch is not a disconnect, so the disconnect sweep never
+  reached the `ExecStart=/usr/bin/sleep infinity` drop-in.
+- **Nix shipped a wrapper with no target.** nixpkgs wraps this package: the real ELF is
+  `bin/.gamescope-wrapped` and `bin/gamescope` is a makeWrapper launcher. The prune
+  (`find $out/bin -mindepth 1 ! -name gamescope -delete`) deleted the compositor and kept the
+  launcher — measured at 16 KB. That single line explains the empty `--version` output and the
+  "missing `+pfhdr` marker", both of which had been attributed to the build sandbox and to upstream.
+  The prune keeps the target now and the guard asserts on the **wrapped ELF**. Separately,
+  `packaging/nix/gamescope.nix` now pins `src` to `5fb8dce4` like every other channel — it was the
+  only one patching whatever version nixpkgs happened to carry, which broke `host.gamescopeHdr`
+  (default true) builds outright when nixpkgs shipped 3.16.24.
+
+### Everything else an integrator might notice
+
+- **`pf-console-ui`:** `ConsoleOptions.fallback_ui` (new, threaded to `Ctx` beside `deck`) gates the
+  Android-only "Controller-optimized UI" row, written through `extra` under
+  `android.gamepad_ui_enabled`; it is true only for the Android touch shell. Down on the carousel
+  opens Settings (`▼` is a new hint glyph — the `▲` triangle inverted, not a second draw routine),
+  and the host options menu gains a Library row on the same terms `Y` offers it (saved **and**
+  paired), replacing the menu rather than stacking on it. Both exist because a TV remote emits only
+  Move/Confirm/Back.
+- **`scripts/ci/docs-undocumented-env-baseline.txt`** gains `PUNKTFUNK_MSG_DELIVERY_REPORT`.
+  `check-docs-drift.sh` scans for `PUNKTFUNK_*` identifiers and cannot tell an operator knob from a
+  cbindgen-exported `#define`; every other `PUNKTFUNK_MSG_*` is already baselined beside it.
+- **`clients/probe`** reads the new delivery counter.
+- **`trust::Settings::extra` is `#[serde(flatten)]`**, so `android.*` keys are **top-level** keys of
+  the settings document, beside `width` and `codec`. `ConsoleJson` wrote and read them nested under
+  an `"extra"` object, which serde stored under the literal key `"extra"` — so no console row ever
+  found `android.gamepad_ui_enabled`, every Android-only row (low latency, phone rumble/gyro, SC2 and
+  DualSense capture, the console-UI mode picker) read its own default, and the value the console
+  saved came back to Kotlin unchanged, so `applySettings` raised no callback. Fixed in #362, which is
+  what makes the `feat` above work at all. A store written by the nesting build carries the dead
+  wrapper and drops it on the next write. The new test pins the shape from **both sides**: a
+  round-trip alone could not catch this, because both halves agreed on the same wrong nesting.
+- **`pf-console-ui` focus halo / `panel_highlight` radii.** A rounded rect grown by `d` keeps its
+  corners concentric with the original only if its radius grows by `d` too; both helpers kept the
+  card's own radius, so the halo read as a squared-off outline at the four corners. `drop_shadow`
+  only offsets and was already right; the collections plate uses `RRect::with_outset`, which adjusts
+  radii itself. Every card path goes through the two fixed helpers.
+
+### Verification status
+
+Gates run on the release tree (this MacBook, rustc/rustfmt per `rust-toolchain.toml`):
+`cargo fmt --all --check` clean; `cargo metadata --offline` ok with the `Cargo.lock` diff
+versions-only (36/36 lines); `cargo test -p punktfunk-core --lib` **273 passed**; the C ABI harness
+(`tests/c_abi.rs`) **passed**, reporting `abi_version=25` and four frames round-tripped byte-exact
+through lossy loopback — it did **not** run on the v0.31.0 cut, so this is the first cut since ABI 25
+where a C compiler has actually built the generated header; `scripts/ci/check-docs-drift.sh` clean;
+the android.yml Play notes gate run verbatim — 442/500 characters and not byte-identical to any prior
+release's; both openapi copies `cmp` identical, both stamped 0.31.1; notes voice scan clean.
+
+⚠ **`api/openapi.json` was re-stamped here, not regenerated.** The document itself was regenerated
+in #361 (with the new route and its three schemas) on a runner where
+`openapi_document_is_complete_and_checked_in` actually executes; this commit moves only
+`info.version`, which utoipa fills from `CARGO_PKG_VERSION`. `punktfunk-host` does not build on
+macOS, so that test could not be re-run here — but `0.31.0` appears nowhere else in either copy, so
+regeneration would produce this byte-for-byte. If it ever fails on this commit, regenerate with
+`cargo run -p punktfunk-host -- openapi > api/openapi.json` and `cp` to `docs-site/public/`.
+
+⚠ **Verified by reading only** — compiled nowhere available to the cutting host: everything under
+`crates/punktfunk-host` (Windows and Linux arms alike), `packaging/nix/gamescope.nix`, and the
+Android/Kotlin half. That includes `crate::runstate` and the new route; its own tests turned up a
+collision on their first run in an environment that executes them (all three shared the provider id
+`playnite` and cleared the process-global table between cases, so parallel scheduling flipped their
+answers) — fixed in #361 by giving each test ids only it uses and retiring the blunt `reset()`. The Windows GameStream pad change was checked on `.133` when it landed
+(`cargo check` and `cargo clippy -p punktfunk-host -- -D warnings` clean, both compiling arms), and
+`windows-host.yml` has **no `pull_request` trigger**, so a PR will not re-check that arm.
+
+⚠ **`audit.yml` is red on main and this release does not fix it.** `cargo audit` reports
+**RUSTSEC-2026-0258** (`h2` 0.4.15, "unbounded empty DATA frames", published 2026-08-17, fixed in
+0.4.16); `h2` is transitive through `hyper`. It **predates this cut** — the same job failed on
+`669a1bc0` and on the v0.31.0 tag commit — so it is not a regression here, and it was deliberately
+**not** bundled into the release commit: `cargo update -p h2 --precise 0.4.16` bumps h2 in eleven
+lock lines but also rewrites several `windows-sys` references downward (0.61.2 → 0.59.0/0.52.0) on
+the pinned 1.96.0 toolchain, and re-resolving the graph for the Windows build is not a change to
+make inside a version bump that cannot be compiled for Windows on the cutting host. It wants its own
+commit and its own CI.
+
+⚠ **Not confirmed on glass:** the Android scancode remap (the reporter's Fire TV Stick 4K Max is the
+test that settles it), the Windows data-plane firewall rule in a field session, and the
+Moonlight-compatible HID pad — the log line to look for there is
+`virtual Xbox pad created (Windows UMDF HID)` where it used to say
+`virtual Xbox 360 created (Windows XUSB companion)`.
+
+---
+
 ## v0.31.0
 
 170 commits since v0.30.0 (113 non-merge), counted at the tip this was cut from.
@@ -537,6 +809,55 @@ legs as follow-ups. Both landed here.
   ring layer's line shape; `nativeRenderLogs(header)` hands Kotlin the rendered bundle, and the
   upload rides the client's own mTLS.
 
+### A provider plugin can report which of its titles are **running**
+
+New: `PUT /api/v1/library/provider/{provider}/running`, body
+`{"running":[{"external_id":"…","pid":1234}]}` — the **live** counterpart to the static `detect`
+hints a reconcile carries. `detect` says *how to recognize* a title's process; this says *it is
+running now*, and carries the pid where the provider knows one. Additive: no existing route,
+payload or behaviour changes, and a host with no reporting plugin behaves exactly as before.
+
+It exists because one class of title could never be tracked at all. The host derives liveness by
+scanning (`procscan` + `DetectSpec`), which needs something recognizable on disk — an install
+directory, an executable, a Steam reaper. A Playnite-launched emulated game, a manually added one,
+or a library plugin that records no install directory has none of that, and its launch is a
+`playnite://` hand-off, so the host holds no process either: the lease went `Untracked`, its exit
+was never noticed, `session_on_game_exit` could not fire, and `POST /game/end` had nothing to aim
+at. Playnite knew the whole time — it starts the game, tracks it in the mode the person configured,
+and fires an event on both edges carrying the pid. That was being thrown away.
+
+- **Declarative and idempotent**, like the reconcile beside it: the body is the provider's
+  **complete** running set, so a missed event, a plugin restart or an install mid-game self-correct
+  on the next report instead of drifting. Absent from the set = stopped.
+- **Reports expire** (`crate::runstate::REPORT_TTL`, 90 s; the answer carries `ttl_s`). This is what
+  makes it safe for a live provider to hold a streaming session open for a game the host cannot
+  see: a plugin that dies with a game running stops counting shortly after and the host falls back
+  to scanning. Reporters must restate well inside the window.
+- **New `gamelease::LeaseKind::Reported`** — a lease with no process signal of its own, tracked by
+  what its provider says. `open` reaches it when the spec is empty and a provider speaks for the id;
+  the shim-reclassification paths (every Windows launch is a hand-off by construction) fall back to
+  it too, where they previously fell to `Untracked`. Phase 1 accepts "running" as the game
+  appearing; phase 2 treats "stopped" as the exit, and — unlike `procscan::running_hint`, which may
+  only ever *delay* an exit because Steam's registry flag survives an unclean exit — a fresh
+  provider report is decisive in both directions. A reported pid joins the termination ladders on
+  the same terms as a spawned one (re-resolved and start-time-pinned at the moment of use).
+- **Route authority**: the plugin lane, like the reconcile (`mgmt::auth::plugin_may_access`, and its
+  exhaustive classification table). No new authority — the host maps `external_id` through the
+  catalog, so a provider can only ever speak about entries it published; an unknown id is *counted*,
+  not refused, because a report legitimately races its own reconcile and 400-ing the batch would
+  throw away the liveness of every other running title.
+- **`@punktfunk/plugin-kit`: `ProviderClient.reportRunning(providerId, running)`**, returning
+  `{matched, unknown, ttlS}`; a 404 from an older host means "this host tracks games by scanning".
+  Version bumped to **0.4.4** — **unpublished, `plugin-kit-v0.4.4` owed.**
+
+The Playnite half lives in `punktfunk-plugin-playnite` (**0.4.5**, exporter **0.4.0**): the C#
+exporter hooks Playnite's `OnGameStarted`/`OnGameStopped`/`OnGameStartupCancelled` and writes a
+small `punktfunk-running.json` beside the library export, re-stamped every 30 s and *deleted* when
+Playnite closes; the plugin polls it and restates the set to this route. It calls the route through
+the kit's untyped host seam rather than `reportRunning`, deliberately — depending on the method
+would make that repo unbuildable until the kit publishes, for the same request. Needs a host
+carrying this route; an older one 404s and the plugin carries on without it.
+
 ### Everything else an integrator might notice
 
 - **`mgmt-endpoint` is followed everywhere.** `PUNKTFUNK_MGMT_BIND` moved off 47990 left every plugin,

Cargo.lock

@@ -1090,7 +1090,7 @@ dependencies = [
 
 [[package]]
 name = "cursor-probe"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "pf-capture",
@@ -1222,7 +1222,7 @@ dependencies = [
 
 [[package]]
 name = "display-disturb"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "pf-win-display",
  "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -2343,7 +2343,7 @@ dependencies = [
 
 [[package]]
 name = "latency-probe"
-version = "0.31.0"
+version = "0.31.1"
 
 [[package]]
 name = "lazy_static"
@@ -2446,7 +2446,7 @@ dependencies = [
 
 [[package]]
 name = "libvpl-sys"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "bindgen",
  "cmake",
@@ -2475,7 +2475,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "loss-harness"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "punktfunk-core",
 ]
@@ -2967,7 +2967,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pf-bitstream"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "cros-codecs",
  "tracing",
@@ -2975,7 +2975,7 @@ dependencies = [
 
 [[package]]
 name = "pf-capture"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -2996,7 +2996,7 @@ dependencies = [
 
 [[package]]
 name = "pf-client-core"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ash",
@@ -3032,7 +3032,7 @@ dependencies = [
 
 [[package]]
 name = "pf-clipboard"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3050,7 +3050,7 @@ dependencies = [
 
 [[package]]
 name = "pf-console-ui"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ash",
@@ -3073,7 +3073,7 @@ dependencies = [
 
 [[package]]
 name = "pf-dxvadec"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "cros-codecs",
  "pf-bitstream",
@@ -3083,7 +3083,7 @@ dependencies = [
 
 [[package]]
 name = "pf-encode"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ash",
@@ -3109,7 +3109,7 @@ dependencies = [
 
 [[package]]
 name = "pf-frame"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "libc",
@@ -3122,7 +3122,7 @@ dependencies = [
 
 [[package]]
 name = "pf-gpu"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "pf-host-config",
@@ -3136,11 +3136,11 @@ dependencies = [
 
 [[package]]
 name = "pf-host-config"
-version = "0.31.0"
+version = "0.31.1"
 
 [[package]]
 name = "pf-inject"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3169,14 +3169,14 @@ dependencies = [
 
 [[package]]
 name = "pf-paths"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "tracing",
 ]
 
 [[package]]
 name = "pf-presenter"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ash",
@@ -3191,7 +3191,7 @@ dependencies = [
 
 [[package]]
 name = "pf-update"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "serde",
  "serde_json",
@@ -3199,7 +3199,7 @@ dependencies = [
 
 [[package]]
 name = "pf-update-check"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "aws-lc-rs",
@@ -3211,7 +3211,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vaadec"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "cros-codecs",
  "pf-bitstream",
@@ -3220,7 +3220,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vdisplay"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3253,7 +3253,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vkdecode"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "ash",
  "cros-codecs",
@@ -3264,7 +3264,7 @@ dependencies = [
 
 [[package]]
 name = "pf-win-display"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "pf-paths",
  "punktfunk-core",
@@ -3275,7 +3275,7 @@ dependencies = [
 
 [[package]]
 name = "pf-zerocopy"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ash",
@@ -3487,7 +3487,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-cli"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "pf-client-core",
  "punktfunk-core",
@@ -3497,7 +3497,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-android"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "android_logger",
  "anyhow",
@@ -3521,7 +3521,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -3538,7 +3538,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-session"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "log",
  "pf-client-core",
@@ -3554,7 +3554,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "async-channel",
  "mdns-sd",
@@ -3572,7 +3572,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-core"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "aes-gcm",
  "cbindgen",
@@ -3605,7 +3605,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-encode-worker"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "pf-encode",
  "tracing",
@@ -3614,7 +3614,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-host"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -3684,7 +3684,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-probe"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "mdns-sd",
@@ -3698,7 +3698,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-tray"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "anyhow",
  "ksni",
@@ -3722,7 +3722,7 @@ checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
 
 [[package]]
 name = "pyrowave-sys"
-version = "0.31.0"
+version = "0.31.1"
 dependencies = [
  "bindgen",
  "cmake",

Cargo.toml

@@ -65,7 +65,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.31.0"
+version = "0.31.1"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT OR Apache-2.0"

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.31.0"
+    "version": "0.31.1"
   },
   "paths": {
     "/api/v1/client-logs": {
@@ -1860,6 +1860,69 @@
         }
       }
     },
+    "/api/v1/library/provider/{provider}/running": {
+      "put": {
+        "tags": [
+          "library"
+        ],
+        "summary": "Report which of a provider's titles are running",
+        "description": "The **live** counterpart to the `detect` hints in a reconcile payload: that one says *how to\nrecognize* a title's process, this one says *it is running now* (design §9,\n[`crate::runstate`]). For a provider that starts games itself and knows when they stop —\nPlaynite tracks every launch and fires an event on both edges — this is a fact the host would\notherwise have to re-derive by scanning, and for a title with nothing to scan for (an emulated\ngame, a manually added one) could not derive at all.\n\nDeclarative and idempotent, like the reconcile: the body is the provider's **complete** running\nset, so a missed event, a plugin restart or an install mid-game all self-correct on the next\nreport rather than drifting.\n\nThe report **expires** after `ttl_s` (90s) unless restated, which is what makes it safe for a\nlive provider to keep a streaming session open for a game the host cannot see: a plugin that\ndies with a game running stops counting shortly after, and the host falls back to process\nscanning exactly as it does without one. Re-report on every change **and** on a timer well\ninside the window.\n\nTitles the provider does not currently publish are ignored (counted in `unknown`), not an error:\na report may legitimately race its own reconcile.",
+        "operationId": "reportProviderRunning",
+        "parameters": [
+          {
+            "name": "provider",
+            "in": "path",
+            "description": "The provider id ([a-z0-9._-], `manual` reserved)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProviderRunningInput"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "The report was accepted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProviderRunningAccepted"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid provider id or payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/library/scanners": {
       "get": {
         "tags": [
@@ -7792,6 +7855,46 @@
           }
         }
       },
+      "ProviderRunningAccepted": {
+        "type": "object",
+        "description": "The result of a liveness report.",
+        "required": [
+          "matched",
+          "unknown",
+          "ttl_s"
+        ],
+        "properties": {
+          "matched": {
+            "type": "integer",
+            "description": "How many reported titles matched an entry this provider currently publishes.",
+            "minimum": 0
+          },
+          "ttl_s": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Seconds this report stays authoritative without being restated — re-report inside it while\nanything is running.",
+            "minimum": 0
+          },
+          "unknown": {
+            "type": "integer",
+            "description": "How many were ignored because no such entry exists (a report that raced a reconcile).",
+            "minimum": 0
+          }
+        }
+      },
+      "ProviderRunningInput": {
+        "type": "object",
+        "description": "Request body for `reportProviderRunning`.",
+        "properties": {
+          "running": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunningTitle"
+            },
+            "description": "Every title of this provider's that is running **right now**. The full set, not a delta:\nanything absent from it is reported as stopped."
+          }
+        }
+      },
       "ReleaseDisplayRequest": {
         "type": "object",
         "description": "Request body for `releaseDisplay`.",
@@ -7846,6 +7949,28 @@
           }
         }
       },
+      "RunningTitle": {
+        "type": "object",
+        "description": "One running title in a provider's liveness report.",
+        "required": [
+          "external_id"
+        ],
+        "properties": {
+          "external_id": {
+            "type": "string",
+            "description": "The provider's own stable id for the title — the same key its reconcile payload uses."
+          },
+          "pid": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int32",
+            "description": "The process id the provider started for it, when it knows one. Optional, and never trusted\nas a bare number: the host re-resolves it and pins it to its start time before it is ever\nsignalled, so a stale or recycled pid simply contributes nothing.",
+            "minimum": 0
+          }
+        }
+      },
       "RuntimeRequest": {
         "type": "object",
         "required": [

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

@@ -96,7 +96,11 @@ internal fun ControllersScreen(
         InputDevice.getDeviceIds()
             .toList()
             .mapNotNull { InputDevice.getDevice(it) }
-            .filter { !it.isVirtual && !Gamepad.isPad(it) }
+            // Everything real that is NOT counted as a controller — including a device that claims
+            // a pad source with no pad hardware behind it, which the Gamepads list above now
+            // rejects. One list or the other, never neither: this screen is where someone looks
+            // when the client's idea of "a pad is attached" disagrees with the room.
+            .filter { !it.isVirtual && !Gamepad.looksLikeController(it) }
     }
     DisposableEffect(Unit) {
         val im = context.getSystemService(InputManager::class.java)
@@ -136,14 +140,19 @@ internal fun ControllersScreen(
             // Read ONCE, up front: the test can end inside this very event, and the release that
             // ended it still has to be swallowed here — see the B branch below.
             val consume = consuming
+            // The CORRECTED keycode, so this screen shows the button the stream will send and not
+            // the one Android guessed for a pad it has no key layout for — the two differ on every
+            // controller [Gamepad.padKeyCode] exists for, and a tester that disagrees with the
+            // stream is worse than no tester. The raw pair is still reported in "Last input".
+            val code = Gamepad.padKeyCode(event)
             when (event.action) {
                 KeyEvent.ACTION_DOWN -> {
-                    held[event.keyCode] = true
-                    if (event.keyCode == KeyEvent.KEYCODE_BUTTON_B) bHeld = true
+                    held[code] = true
+                    if (code == KeyEvent.KEYCODE_BUTTON_B) bHeld = true
                 }
                 KeyEvent.ACTION_UP -> {
-                    held[event.keyCode] = false
-                    if (event.keyCode == KeyEvent.KEYCODE_BUTTON_B) {
+                    held[code] = false
+                    if (code == KeyEvent.KEYCODE_BUTTON_B) {
                         bHeld = false
                         if (consume) {
                             if (event.eventTime - event.downTime >= HOLD_TO_FINISH_MS) {
@@ -167,23 +176,43 @@ internal fun ControllersScreen(
                     }
                 }
             }
-            lastInput = "${event.device?.name}: ${KeyEvent.keyCodeToString(event.keyCode)}"
+            // Raw scancode AND keycode, plus the correction when one fired: this line is what a
+            // field report needs to pin an unmapped pad's report order without the device in hand.
+            val raw = KeyEvent.keyCodeToString(event.keyCode).removePrefix("KEYCODE_")
+            val fixed = KeyEvent.keyCodeToString(code).removePrefix("KEYCODE_")
+            lastInput = "${event.device?.name}: scan 0x%X · %s%s".format(
+                event.scanCode,
+                raw,
+                if (code != event.keyCode) " → $fixed" else "",
+            )
             consume
         }
         val motionProbe: (MotionEvent) -> Boolean = probe@{ event ->
             if (!Gamepad.isPad(event.device)) return@probe false
+            // Through the device's resolved map, exactly as `Gamepad.AxisMapper` reads it while
+            // streaming — on a pad Android has no key layout for, the right stick and the triggers
+            // are not on the axes their names suggest.
+            val map = Gamepad.padMap(event.device)
             axes["LX"] = event.getAxisValue(MotionEvent.AXIS_X)
             axes["LY"] = event.getAxisValue(MotionEvent.AXIS_Y)
-            axes["RX"] = event.getAxisValue(MotionEvent.AXIS_Z)
-            axes["RY"] = event.getAxisValue(MotionEvent.AXIS_RZ)
-            axes["LT"] = maxOf(
-                event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
-                event.getAxisValue(MotionEvent.AXIS_BRAKE),
-            )
-            axes["RT"] = maxOf(
-                event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
-                event.getAxisValue(MotionEvent.AXIS_GAS),
-            )
+            axes["RX"] = event.getAxisValue(map.rightStickX)
+            axes["RY"] = event.getAxisValue(map.rightStickY)
+            axes["LT"] = if (map.leftTrigger == Gamepad.AXIS_NONE) {
+                maxOf(
+                    event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
+                    event.getAxisValue(MotionEvent.AXIS_BRAKE),
+                )
+            } else {
+                map.level(event.getAxisValue(map.leftTrigger))
+            }
+            axes["RT"] = if (map.rightTrigger == Gamepad.AXIS_NONE) {
+                maxOf(
+                    event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
+                    event.getAxisValue(MotionEvent.AXIS_GAS),
+                )
+            } else {
+                map.level(event.getAxisValue(map.rightTrigger))
+            }
             axes["HX"] = event.getAxisValue(MotionEvent.AXIS_HAT_X)
             axes["HY"] = event.getAxisValue(MotionEvent.AXIS_HAT_Y)
             consuming
@@ -689,6 +718,16 @@ private fun PadRow(info: PadInfo, gamepadSetting: Int) {
                 style = MaterialTheme.typography.bodySmall,
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )
+            // Only when a correction is actually in force: on a pad Android has a key layout for
+            // there is nothing to say, and a line that says "normal" on every device teaches
+            // nobody anything. Named rather than merely flagged, so a field report can quote it.
+            padButtonsNote(info.buttons)?.let {
+                Text(
+                    it,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
             if (info.canRumble) {
                 OutlinedButton(onClick = { info.dev?.let(::testRumble) }) { Text("Test rumble") }
             } else {
@@ -784,6 +823,12 @@ internal data class PadInfo(
     val controllerNumber: Int,
     val resolvedPref: Int,
     val canRumble: Boolean,
+    /**
+     * The report order this pad's buttons were resolved to ([Gamepad.padButtons]). Defaults to
+     * the pad Android already knows, which is what a screenshot scene wants and what the note
+     * under the card stays silent about.
+     */
+    val buttons: Gamepad.PadButtons = Gamepad.PadButtons.NATIVE,
     val dev: InputDevice? = null,
 )
 
@@ -793,6 +838,7 @@ internal fun padInfoOf(dev: InputDevice): PadInfo = PadInfo(
     forwarded = isForwarded(dev),
     controllerNumber = dev.controllerNumber,
     resolvedPref = Gamepad.prefFor(dev),
+    buttons = Gamepad.padMap(dev).buttons, // via padMap so the list refresh reuses the cache
     canRumble = deviceHasVibrator(dev),
     dev = dev,
 )
@@ -823,6 +869,20 @@ internal fun testRumble(dev: InputDevice) {
 }
 
 /** Identity line: VID:PID + the source classes Android assigned. */
+/**
+ * What to say about a pad whose buttons had to be resolved from their scancodes because Android
+ * has no key layout for it — null for a pad it does know, which needs no explanation.
+ */
+private fun padButtonsNote(buttons: Gamepad.PadButtons): String? = when (buttons) {
+    Gamepad.PadButtons.NATIVE -> null
+    Gamepad.PadButtons.GENERIC_SONY ->
+        "Android has no button layout for this controller — read as a PlayStation pad"
+    Gamepad.PadButtons.GENERIC_XBOX ->
+        "Android has no button layout for this controller — read as an Xbox pad"
+    Gamepad.PadButtons.SONY_MODERN ->
+        "Android has no button layout for this controller — face buttons corrected"
+}
+
 private fun deviceDetail(dev: InputDevice): String =
     "%04X:%04X · %s".format(dev.vendorId, dev.productId, sourcesLabel(dev.sources))
 

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

@@ -11,6 +11,7 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberUpdatedState
 import androidx.compose.ui.platform.LocalContext
+import io.unom.punktfunk.kit.Gamepad
 import kotlin.math.abs
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.isActive
@@ -96,7 +97,7 @@ fun GamepadNavEffect(
         val keyProbe: (KeyEvent) -> Boolean = probe@{ ev ->
             val down = ev.action == KeyEvent.ACTION_DOWN
             val edge = down && ev.repeatCount == 0
-            when (ev.keyCode) {
+            when (Gamepad.padKeyCode(ev)) {
                 KeyEvent.KEYCODE_DPAD_LEFT -> { state.dpadX = if (down) -1 else 0; true }
                 KeyEvent.KEYCODE_DPAD_RIGHT -> { state.dpadX = if (down) 1 else 0; true }
                 // TV remote (no face buttons): Up → Settings, Down → a saved host's Options.
@@ -202,7 +203,7 @@ fun GamepadNavEffect2D(
         val keyProbe: (KeyEvent) -> Boolean = probe@{ ev ->
             val down = ev.action == KeyEvent.ACTION_DOWN
             val edge = down && ev.repeatCount == 0
-            when (ev.keyCode) {
+            when (Gamepad.padKeyCode(ev)) {
                 KeyEvent.KEYCODE_DPAD_LEFT -> { state.dpadX = if (down) -1 else 0; true }
                 KeyEvent.KEYCODE_DPAD_RIGHT -> { state.dpadX = if (down) 1 else 0; true }
                 KeyEvent.KEYCODE_DPAD_UP -> { state.dpadY = if (down) -1 else 0; true }

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

@@ -616,7 +616,7 @@ class MainActivity : ComponentActivity() {
             // 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.padButtonBit(event.keyCode, event.flags)
+                val bit = Gamepad.padButtonBit(Gamepad.padKeyCode(event), 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
@@ -708,8 +708,10 @@ class MainActivity : ComponentActivity() {
             if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
                 // Not streaming: a game controller drives the Compose UI (TV + phone). Map the face
                 // buttons to the navigation the focus system / back stack understand; D-pad *keys*
-                // already move focus on their own, so they fall through to super untouched.
-                when (event.keyCode) {
+                // already move focus on their own, so they fall through to super untouched. Read
+                // through [Gamepad.padKeyCode] so a pad Android has no key layout for reaches the
+                // menus on the right buttons too, not only the stream.
+                when (Gamepad.padKeyCode(event)) {
                     // B → back. Drive the OnBackPressedDispatcher directly rather than synthesising a
                     // BACK KeyEvent: a synthetic event isn't "tracking", so the framework's default
                     // onKeyUp(BACK) never calls onBackPressed() and Compose BackHandlers wouldn't fire.

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

@@ -940,6 +940,17 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                         }
 
                         override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) {
+                            // The view's CURRENT pixel size, for the ASurfaceControl layer's
+                            // destination rect. It is reported here and not only at
+                            // surfaceCreated because the view grows a frame or two after the
+                            // stream screen appears — hiding the system bars and switching on
+                            // cutout drawing both resize it, and neither recreates the surface.
+                            // A layer left on the start-up rect paints the picture small, in the
+                            // top-left corner. The view's own size, not the buffer geometry in
+                            // `width`/`height`: the layer composites in the view's space.
+                            NativeBridge.nativeVideoSurfaceSize(
+                                handle, this@apply.width, this@apply.height,
+                            )
                             // Re-assert the frame-rate vote: a buffer-geometry change can reset
                             // the surface's frame-rate setting on some OEM builds, silently
                             // dropping the 120 Hz pin mid-stream. Mirrors the native hint's

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

@@ -317,15 +317,20 @@ internal object ConsoleJson {
         j.put("invert_scroll", s.invertScroll)
         j.put("pad_haptics", s.padHaptics)
         j.put("pad_speaker", if (s.padSpeaker) "pad" else "off")
-        // Android-only rows ride `extra` (WP5 gives them RowIds); nothing on the desktop reads them.
-        val extra = j.optJSONObject("extra") ?: JSONObject()
-        extra.put("android.low_latency", s.lowLatencyMode)
-        extra.put("android.rumble_on_phone", s.rumbleOnPhone)
-        extra.put("android.gyro_on_phone", s.gyroOnPhone)
-        extra.put("android.sc2_capture", s.sc2Capture)
-        extra.put("android.ds_capture", s.dsCapture)
-        extra.put("android.gamepad_ui_mode", s.gamepadUiMode)
-        j.put("extra", extra)
+        // Android-only rows ride `Settings::extra`, which is `#[serde(flatten)]` — so they are
+        // TOP-LEVEL keys of this document, not a nested `extra` object. Nesting them put the
+        // whole object into the map under the literal key "extra", where no console row could
+        // read it and every value the console wrote came straight back as the one we had sent.
+        j.put("android.low_latency", s.lowLatencyMode)
+        j.put("android.rumble_on_phone", s.rumbleOnPhone)
+        j.put("android.gyro_on_phone", s.gyroOnPhone)
+        j.put("android.sc2_capture", s.sc2Capture)
+        j.put("android.ds_capture", s.dsCapture)
+        j.put("android.gamepad_ui_mode", s.gamepadUiMode)
+        j.put("android.gamepad_ui_enabled", s.gamepadUiEnabled)
+        // A store written by the nesting build carries the stale wrapper; drop it rather than
+        // round-trip a copy of these keys that nothing reads for the life of the install.
+        j.remove("extra")
         return j
     }
 
@@ -335,7 +340,8 @@ internal object ConsoleJson {
      */
     fun applySettings(s: Settings, j: JSONObject): Settings {
         fun str(k: String, cur: String) = j.optString(k, cur).ifEmpty { cur }
-        val extra = j.optJSONObject("extra") ?: JSONObject()
+        // The `android.*` keys are TOP-LEVEL here, not nested: `Settings::extra` is
+        // `#[serde(flatten)]`, so the console writes them beside `width` and `codec`.
         return s.copy(
             width = j.optInt("width", s.width),
             height = j.optInt("height", s.height),
@@ -372,13 +378,14 @@ internal object ConsoleJson {
                 "off" -> false
                 else -> s.padSpeaker
             },
-            lowLatencyMode = extra.optBoolean("android.low_latency", s.lowLatencyMode),
-            rumbleOnPhone = extra.optBoolean("android.rumble_on_phone", s.rumbleOnPhone),
-            gyroOnPhone = extra.optBoolean("android.gyro_on_phone", s.gyroOnPhone),
-            sc2Capture = extra.optBoolean("android.sc2_capture", s.sc2Capture),
-            dsCapture = extra.optBoolean("android.ds_capture", s.dsCapture),
-            gamepadUiMode = extra.optString("android.gamepad_ui_mode", s.gamepadUiMode)
+            lowLatencyMode = j.optBoolean("android.low_latency", s.lowLatencyMode),
+            rumbleOnPhone = j.optBoolean("android.rumble_on_phone", s.rumbleOnPhone),
+            gyroOnPhone = j.optBoolean("android.gyro_on_phone", s.gyroOnPhone),
+            sc2Capture = j.optBoolean("android.sc2_capture", s.sc2Capture),
+            dsCapture = j.optBoolean("android.ds_capture", s.dsCapture),
+            gamepadUiMode = j.optString("android.gamepad_ui_mode", s.gamepadUiMode)
                 .ifEmpty { s.gamepadUiMode },
+            gamepadUiEnabled = j.optBoolean("android.gamepad_ui_enabled", s.gamepadUiEnabled),
         )
     }
 }

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

@@ -159,6 +159,9 @@ object SkiaConsole {
         val opts = JSONObject()
             .put("device_name", deviceName(app))
             .put("gpu_cache_bytes", gpuCacheBytes(app))
+            // The touch shell exists as a fallback on phones/tablets but not on a TV —
+            // gates the console's own "Controller-optimized UI" off switch.
+            .put("fallback_ui", !io.unom.punktfunk.isTvDevice(app))
             .put("settings", ConsoleJson.settings(initial, base))
             .put("profiles", JSONArray(ConsoleJson.profiles(profiles)))
             .put("known_hosts", JSONObject(ConsoleJson.knownHosts(knownHostStore.all())))

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

@@ -159,7 +159,12 @@ fun SkiaConsoleShell(
             if (ev.action != KeyEvent.ACTION_DOWN && ev.action != KeyEvent.ACTION_UP) return@probe false
             val fromPad = ev.isFromSource(InputDevice.SOURCE_GAMEPAD)
             if (fromPad) {
-                val bit = when (ev.keyCode) {
+                // The CORRECTED keycode: a pad Android has no key layout for delivers its buttons
+                // under other buttons' names, so read raw this console answered ✕ with whatever
+                // sat in BUTTON_A's scancode slot. Same resolution the stream uses — the console
+                // and the game must not disagree about which button a user pressed.
+                val code = Gamepad.padKeyCode(ev)
+                val bit = when (code) {
                     KeyEvent.KEYCODE_BUTTON_A -> 0
                     KeyEvent.KEYCODE_BUTTON_B -> 1
                     KeyEvent.KEYCODE_BUTTON_X -> 2
@@ -179,7 +184,7 @@ fun SkiaConsoleShell(
                     }
                     return@probe true
                 }
-                val dbit = when (ev.keyCode) {
+                val dbit = when (code) {
                     KeyEvent.KEYCODE_DPAD_UP -> 0
                     KeyEvent.KEYCODE_DPAD_DOWN -> 1
                     KeyEvent.KEYCODE_DPAD_LEFT -> 2
@@ -191,7 +196,7 @@ fun SkiaConsoleShell(
                     padState.push(handle)
                     return@probe true
                 }
-                if (ev.keyCode == KeyEvent.KEYCODE_BUTTON_SELECT && down && ev.repeatCount == 0) {
+                if (code == KeyEvent.KEYCODE_BUTTON_SELECT && down && ev.repeatCount == 0) {
                     NativeBridge.nativeConsoleMenu(handle, 0) // ▲ opens the tile's options on Home
                     return@probe true
                 }

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

@@ -0,0 +1,73 @@
+package io.unom.punktfunk
+
+import io.unom.punktfunk.console.ConsoleJson
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The Android-only console settings ride `trust::Settings::extra`, which is `#[serde(flatten)]`:
+ * they are TOP-LEVEL keys of the settings document, beside `width` and `codec`.
+ *
+ * They were written and read nested under an `"extra"` object instead. Serde put that whole
+ * object into the map under the literal key `"extra"`, so no console row ever found
+ * `android.gamepad_ui_enabled` — and the value the console saved came back to Kotlin as the one
+ * Kotlin had just sent. On glass that was a "Controller-optimized UI" switch you could turn off
+ * with nothing happening: the console stayed up, because the setting never moved.
+ */
+class ConsoleSettingsExtraTest {
+    @Test
+    fun androidKeysAreWrittenFlat() {
+        val j = ConsoleJson.settings(Settings(gamepadUiEnabled = false, lowLatencyMode = false), null)
+        assertTrue("the console reads this key at the top level", j.has("android.gamepad_ui_enabled"))
+        assertFalse(j.getBoolean("android.gamepad_ui_enabled"))
+        assertFalse(j.getBoolean("android.low_latency"))
+        assertFalse("a nested wrapper is what serde swallows whole", j.has("extra"))
+    }
+
+    /** A store written by the nesting build must not keep echoing its dead wrapper. */
+    @Test
+    fun aStaleNestedWrapperIsDropped() {
+        val base = JSONObject().put(
+            "extra",
+            JSONObject().put("android.gamepad_ui_enabled", true),
+        )
+        assertFalse(ConsoleJson.settings(Settings(gamepadUiEnabled = false), base).has("extra"))
+    }
+
+    @Test
+    fun theConsolesOwnSaveIsReadBack() {
+        val saved = JSONObject()
+            .put("android.gamepad_ui_enabled", false)
+            .put("android.gamepad_ui_mode", GAMEPAD_UI_ALWAYS)
+            .put("android.ds_capture", false)
+        val next = ConsoleJson.applySettings(Settings(), saved)
+        assertFalse("turning the console off must reach the store", next.gamepadUiEnabled)
+        assertEquals(GAMEPAD_UI_ALWAYS, next.gamepadUiMode)
+        assertFalse(next.dsCapture)
+    }
+
+    /** Both halves against each other — the shape only holds if they agree. */
+    @Test
+    fun theRoundTripKeepsEveryAndroidRow() {
+        val want = Settings(
+            gamepadUiEnabled = false,
+            gamepadUiMode = GAMEPAD_UI_ALWAYS,
+            lowLatencyMode = false,
+            rumbleOnPhone = true,
+            gyroOnPhone = true,
+            sc2Capture = false,
+            dsCapture = false,
+        )
+        val got = ConsoleJson.applySettings(Settings(), ConsoleJson.settings(want, null))
+        assertEquals(want.gamepadUiEnabled, got.gamepadUiEnabled)
+        assertEquals(want.gamepadUiMode, got.gamepadUiMode)
+        assertEquals(want.lowLatencyMode, got.lowLatencyMode)
+        assertEquals(want.rumbleOnPhone, got.rumbleOnPhone)
+        assertEquals(want.gyroOnPhone, got.gyroOnPhone)
+        assertEquals(want.sc2Capture, got.sc2Capture)
+        assertEquals(want.dsCapture, got.dsCapture)
+    }
+}

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

@@ -3,6 +3,7 @@ package io.unom.punktfunk.kit
 import android.view.InputDevice
 import android.view.KeyEvent
 import android.view.MotionEvent
+import java.util.concurrent.ConcurrentHashMap
 import kotlin.math.roundToInt
 
 /**
@@ -127,8 +128,12 @@ object Gamepad {
 
     // Microsoft Xbox One / Series product ids (wired + the common Bluetooth/dongle revisions). All
     // behave like Xbox 360 on the host minus the glyph identity, so they share one pref byte.
+    // The Bluetooth revisions (0x02E0/0x02FD Xbox One S, 0x0B05/0x0B22 Elite Series 2 and its
+    // Core) are here for the same reason as the wired ones: they are the pads a couch actually
+    // pairs to a TV box, and without them an Elite streams under the Xbox 360 identity.
     private val PID_XBOXONE = setOf(
-        0x02D1, 0x02DD, 0x02E3, 0x02EA, 0x0B00, 0x0B12, 0x0B13, 0x0B20,
+        0x02D1, 0x02DD, 0x02E0, 0x02E3, 0x02EA, 0x02FD,
+        0x0B00, 0x0B05, 0x0B12, 0x0B13, 0x0B20, 0x0B22,
     )
 
     /**
@@ -188,9 +193,53 @@ object Gamepad {
             s and InputDevice.SOURCE_JOYSTICK == InputDevice.SOURCE_JOYSTICK
     }
 
-    /** All connected gamepad/joystick [InputDevice]s, in system enumeration order. */
-    fun pads(): List<InputDevice> =
-        InputDevice.getDeviceIds().toList().mapNotNull { InputDevice.getDevice(it) }.filter { isPad(it) }
+    /**
+     * True when [dev] is a controller someone can actually hold: a pad source ([isPad]) that is a
+     * REAL device carrying real pad hardware — a stick, a HAT, or the A/B face buttons.
+     *
+     * [isPad] alone answers "did this event come from a pad source", which is the right question
+     * for ROUTING an event and the wrong one for "is a controller attached". Devices publish
+     * inputs that claim `SOURCE_GAMEPAD`/`SOURCE_JOYSTICK` while being no such thing — OEM
+     * game-mode overlays and the gaming-phone shoulder triggers among them — and one of those is
+     * enough to pin the console UI on forever: a pad that was never there cannot disconnect, so
+     * "With a controller" has no way back to the touch UI.
+     *
+     * The capability probe is what separates them: a source class is a claim, a stick or a face
+     * button is hardware. It is not a complete defence — an OEM device that declares `BTN_GAMEPAD`
+     * and a pair of axes is indistinguishable from a pad at this layer — so the master switch stays
+     * the guaranteed way out. `isVirtual` only means "device id < 0" (the platform's own synthetic
+     * device), which is worth excluding but catches none of the above.
+     */
+    fun looksLikeController(dev: InputDevice?): Boolean {
+        val d = dev ?: return false
+        return looksLikeController(
+            padSource = isPad(d),
+            virtual = d.isVirtual,
+            hasStick = d.getMotionRange(MotionEvent.AXIS_X, InputDevice.SOURCE_JOYSTICK) != null ||
+                d.getMotionRange(MotionEvent.AXIS_HAT_X, InputDevice.SOURCE_JOYSTICK) != null,
+            // `hasKeys` answers for the DEVICE, so a pad with no sticks at all (an arcade stick,
+            // a d-pad-only pad) still counts.
+            hasFaceButtons = d.hasKeys(KeyEvent.KEYCODE_BUTTON_A, KeyEvent.KEYCODE_BUTTON_B)
+                .any { it },
+        )
+    }
+
+    /** [looksLikeController]'s decision, over plain facts — the seam its truth table is tested at
+     * (an [InputDevice] cannot be built off a device). */
+    fun looksLikeController(
+        padSource: Boolean,
+        virtual: Boolean,
+        hasStick: Boolean,
+        hasFaceButtons: Boolean,
+    ): Boolean = padSource && !virtual && (hasStick || hasFaceButtons)
+
+    /**
+     * All connected controllers, in system enumeration order — the devices that answer "is a pad
+     * attached", so the filter is [looksLikeController] rather than the looser [isPad].
+     */
+    fun pads(): List<InputDevice> = InputDevice.getDeviceIds().toList()
+        .mapNotNull { InputDevice.getDevice(it) }
+        .filter { looksLikeController(it) }
 
     /** First connected gamepad/joystick [InputDevice], or null when none is attached. */
     fun firstPad(): InputDevice? = pads().firstOrNull()
@@ -293,6 +342,334 @@ object Gamepad {
         else -> BTN_BACK
     }
 
+    // ---------------------------------------------------------------------------------------
+    // Controllers Android has no key layout for
+    //
+    // Android turns a pad's raw evdev scancode into a `KeyEvent.keyCode` through a KEY LAYOUT
+    // file matched on USB VID/PID (`Vendor_054c_Product_0ce6.kl` & co.). A pad with no matching
+    // file falls back to AOSP's `Generic.kl`, which assigns keycodes by SCANCODE POSITION —
+    // `0x130`→BUTTON_A, `0x131`→BUTTON_B, `0x132`→BUTTON_C, and so on up. That is only right if
+    // the pad's buttons happen to sit at the positions the file assumes, and a HID gamepad with
+    // no kernel driver behind it numbers its buttons 1..n straight through IN ITS OWN REPORT
+    // ORDER — so every keycode after the first divergence is somebody else's button.
+    //
+    // Reported from a Fire TV Stick 4K Max (2026-08-20): a DualSense and an Xbox Elite Series 2,
+    // both over Bluetooth, both identified correctly but with buttons landing on the wrong
+    // actions ("L1 being L2"). Neither has a layout there — AOSP ships none for the Elite
+    // Series 2 over Bluetooth (`045e:0b05`) on ANY version, and the DualSense's
+    // (`054c:0ce6`) both postdates Fire OS and carries `requires_kernel_config
+    // CONFIG_HID_PLAYSTATION`, which a Fire TV kernel does not have. A DualSense reporting
+    // straight through puts L2 on `0x136`, which `Generic.kl` calls BUTTON_L1: the reported
+    // symptom exactly.
+    //
+    // The fix is to resolve buttons from the SCANCODE, which is the pad's own report position and
+    // is immune to the layout file — the same reason [Keymap.toVk] reads `scanCode` for keyboards.
+    // Two things keep it from breaking a pad that already works:
+    //
+    //  1. Nothing is corrected on a pad that names its triggers ([padButtons]). A descriptor
+    //     well-formed enough to call them Accelerator/Brake puts its buttons at the standard
+    //     positions too, and that is the fact — not the model — that separates the two firmwares
+    //     of the SAME Xbox pad, only the older of which needs any of this.
+    //  2. Past that gate the correction still applies ONLY where the delivered keycode is what
+    //     `Generic.kl` would have said ([genericKeyCode]). A different keycode means a
+    //     device-specific layout IS in force and knows this pad better than we do.
+    //
+    // Moonlight carries the same two tables AND the same gate (`ControllerHandler`'s
+    // `isNonStandardDualShock4` / `isNonStandardXboxBtController`, the latter on `gasRange == null`),
+    // which is why both pads work there on the same box.
+    //
+    // The first cut of this asked `hasKeys(BUTTON_C, BUTTON_Z)` on its own, on the reasoning that a
+    // pad numbering straight through reaches keycodes no controller has a button for. It does — but
+    // so does every pad that merely DECLARES six buttons, because `hid-input` allocates `BTN_A + n`
+    // straight through for the whole descriptor whether or not the pad ever presses them. That fired
+    // the correction on pads Android was already reading correctly (2026-08-21: an Xbox pad
+    // answering X with Y, Y with LB, and both shoulders with a menu button), and it could not have
+    // done otherwise: the signal is identical on the firmware that needs correcting and the one that
+    // does not. Declaration is not report order. Only the axes tell them apart.
+
+    /** [MotionEvent] axis id meaning "this pad has no such axis" — see [PadMap]. */
+    const val AXIS_NONE = -1
+
+    /**
+     * The report order a controller's buttons are numbered in, and with it which scancode carries
+     * which physical button. Resolved once per device by [padButtons] from what the device
+     * declares; [correct] then maps one scancode to the keycode it should have produced.
+     */
+    enum class PadButtons {
+        /**
+         * The keycode Android delivered is already right — a device-specific key layout is in
+         * force, or the generic one happens to agree. [correct] changes nothing.
+         */
+        NATIVE,
+
+        /**
+         * A Sony pad numbering straight through with no kernel driver behind it: □ ✕ ○ △ L1 R1
+         * L2 R2 Create Options L3 R3 PS, i.e. `0x130`..`0x13c` in that order. The analog trigger
+         * value rides `AXIS_RX`/`AXIS_RY` on such a pad, so the digital L2/R2 fold to keycodes
+         * [buttonBit] deliberately drops — the wire carries the axis, never both.
+         */
+        GENERIC_SONY,
+
+        /**
+         * An Xbox-layout pad numbering straight through: A B X Y LB RB View Menu LS RS, i.e.
+         * `0x130`..`0x139`. Also the fallback for an unbranded pad, which near-universally
+         * clones the Xbox layout — the same assumption [styleFor] makes for its glyphs.
+         */
+        GENERIC_XBOX,
+
+        /**
+         * A Sony pad WITH a kernel driver (`hid-playstation` / `hid-sony`) but still no key
+         * layout — the combination an Android 11 box on a 5.10 kernel lands in. Such a driver
+         * emits the modern Linux gamepad codes, where `0x133` is BTN_NORTH (△) and `0x134` is
+         * BTN_WEST (□); `Generic.kl` reads those two as BUTTON_X and BUTTON_Y, so exactly the
+         * face pair comes out swapped and nothing else is wrong.
+         */
+        SONY_MODERN,
+        ;
+
+        /**
+         * The keycode scancode [scan] should have produced, given Android delivered [keyCode].
+         *
+         * Returns [keyCode] untouched unless it is precisely what [genericKeyCode] would have
+         * said for [scan] — anything else is a device-specific layout's answer, which outranks
+         * this table. That guard is what makes the correction idempotent and safe to run on
+         * every pad: it can only ever fire where Android was guessing in the first place.
+         */
+        fun correct(scan: Int, keyCode: Int): Int {
+            if (this == NATIVE) return keyCode
+            if (keyCode != genericKeyCode(scan)) return keyCode
+            val fixed = when (this) {
+                GENERIC_SONY -> when (scan) {
+                    0x130 -> KeyEvent.KEYCODE_BUTTON_X // □
+                    0x131 -> KeyEvent.KEYCODE_BUTTON_A // ✕
+                    0x132 -> KeyEvent.KEYCODE_BUTTON_B // ○
+                    0x133 -> KeyEvent.KEYCODE_BUTTON_Y // △
+                    0x134 -> KeyEvent.KEYCODE_BUTTON_L1
+                    0x135 -> KeyEvent.KEYCODE_BUTTON_R1
+                    0x136 -> KeyEvent.KEYCODE_BUTTON_L2 // analog: AXIS_RX
+                    0x137 -> KeyEvent.KEYCODE_BUTTON_R2 // analog: AXIS_RY
+                    0x138 -> KeyEvent.KEYCODE_BUTTON_SELECT // Create / Share
+                    0x139 -> KeyEvent.KEYCODE_BUTTON_START // Options
+                    0x13a -> KeyEvent.KEYCODE_BUTTON_THUMBL
+                    0x13b -> KeyEvent.KEYCODE_BUTTON_THUMBR
+                    0x13c -> KeyEvent.KEYCODE_BUTTON_MODE // PS
+                    // 0x13d touchpad click / 0x13e mute: no wire button, dropped as before.
+                    else -> KeyEvent.KEYCODE_UNKNOWN
+                }
+                GENERIC_XBOX -> when (scan) {
+                    0x132 -> KeyEvent.KEYCODE_BUTTON_X
+                    0x133 -> KeyEvent.KEYCODE_BUTTON_Y
+                    0x134 -> KeyEvent.KEYCODE_BUTTON_L1
+                    0x135 -> KeyEvent.KEYCODE_BUTTON_R1
+                    0x136 -> KeyEvent.KEYCODE_BUTTON_SELECT // View
+                    0x137 -> KeyEvent.KEYCODE_BUTTON_START // Menu
+                    0x138 -> KeyEvent.KEYCODE_BUTTON_THUMBL
+                    0x139 -> KeyEvent.KEYCODE_BUTTON_THUMBR
+                    else -> keyCode // 0x130 A / 0x131 B already agree
+                }
+                // Only the face pair; every other row of Generic.kl is right for these codes.
+                SONY_MODERN -> when (scan) {
+                    0x133 -> KeyEvent.KEYCODE_BUTTON_Y // BTN_NORTH = △
+                    0x134 -> KeyEvent.KEYCODE_BUTTON_X // BTN_WEST  = □
+                    else -> keyCode
+                }
+                NATIVE -> keyCode
+            }
+            return fixed
+        }
+    }
+
+    /**
+     * AOSP `Generic.kl`'s gamepad rows — the layout Android falls back to when no device-specific
+     * key layout matches the pad's VID/PID. Scancodes outside it answer [KeyEvent.KEYCODE_UNKNOWN],
+     * which never equals a real delivered keycode, so [PadButtons.correct]'s guard leaves those
+     * events alone.
+     */
+    fun genericKeyCode(scan: Int): Int = when (scan) {
+        0x130 -> KeyEvent.KEYCODE_BUTTON_A
+        0x131 -> KeyEvent.KEYCODE_BUTTON_B
+        0x132 -> KeyEvent.KEYCODE_BUTTON_C
+        0x133 -> KeyEvent.KEYCODE_BUTTON_X
+        0x134 -> KeyEvent.KEYCODE_BUTTON_Y
+        0x135 -> KeyEvent.KEYCODE_BUTTON_Z
+        0x136 -> KeyEvent.KEYCODE_BUTTON_L1
+        0x137 -> KeyEvent.KEYCODE_BUTTON_R1
+        0x138 -> KeyEvent.KEYCODE_BUTTON_L2
+        0x139 -> KeyEvent.KEYCODE_BUTTON_R2
+        0x13a -> KeyEvent.KEYCODE_BUTTON_SELECT
+        0x13b -> KeyEvent.KEYCODE_BUTTON_START
+        0x13c -> KeyEvent.KEYCODE_BUTTON_MODE
+        0x13d -> KeyEvent.KEYCODE_BUTTON_THUMBL
+        0x13e -> KeyEvent.KEYCODE_BUTTON_THUMBR
+        else -> KeyEvent.KEYCODE_UNKNOWN
+    }
+
+    /**
+     * How one controller must be read: its button report order plus the axes its right stick and
+     * analog triggers actually arrive on. Resolved once per device by [padMap].
+     */
+    class PadMap(
+        val buttons: PadButtons,
+        val rightStickX: Int = MotionEvent.AXIS_Z,
+        val rightStickY: Int = MotionEvent.AXIS_RZ,
+        /**
+         * The trigger axes, or [AXIS_NONE] for a pad Android already names them on — that case
+         * keeps folding LTRIGGER with BRAKE and RTRIGGER with GAS by max, which is what pads that
+         * report one pair, the other, or both have always needed.
+         */
+        val leftTrigger: Int = AXIS_NONE,
+        val rightTrigger: Int = AXIS_NONE,
+        /** Those trigger axes rest at −1 rather than 0, measured off the device's own range. */
+        val triggersSigned: Boolean = false,
+    ) {
+        /** One resolved trigger axis value, folded to the 0..1 the wire scale expects. */
+        fun level(v: Float): Float = if (triggersSigned) (v + 1f) / 2f else v
+    }
+
+    /** The map every pad with a key layout uses: Android's own names, unchanged. */
+    private val NATIVE_MAP = PadMap(PadButtons.NATIVE)
+
+    /**
+     * Resolved [PadMap]s, keyed by [InputDevice.getDescriptor] — the device's stable identity
+     * hash, so a pad that reconnects is recognised and a model resolves once for the process.
+     * Nothing here depends on a live connection, so entries never need evicting.
+     */
+    private val padMaps = ConcurrentHashMap<String, PadMap>()
+
+    /**
+     * Which report order [dev]'s buttons follow — [namedTriggers] is whether the pad reports its
+     * triggers under a name Android knows (see [padMap]), and [declaresCZ] whether it declares
+     * BUTTON_C and BUTTON_Z.
+     *
+     * `namedTriggers` decides it, and a pad that has them is [PadButtons.NATIVE] whatever else it
+     * says. A HID gamepad describes its triggers either as the Accelerator/Brake usages, which
+     * become `ABS_GAS`/`ABS_BRAKE` and axis names Android has words for, or as two more generic
+     * axes on `ABS_Z`/`ABS_RZ`, which it does not — and a report descriptor well-formed enough to
+     * name its triggers puts its buttons at the standard positions too, the ones `Generic.kl`
+     * already reads correctly. It is the same fact Moonlight decides this on (`gasRange == null`
+     * beside the `"Xbox Wireless Controller"` name), and it is the one that separates the two
+     * firmwares of the SAME pad: an Xbox Wireless Controller over Bluetooth reports GAS/BRAKE
+     * after its firmware update and Z/Rz before it, and only the older one needs correcting.
+     *
+     * `declaresCZ` cannot make that call and must never be asked to. `hasKeys` answers for what a
+     * device DECLARES, not what it reports: `hid-input` allocates `BTN_A + n` straight through for
+     * every button in the descriptor, so BTN_C (`0x132`) and BTN_Z (`0x135`) are set on any pad
+     * declaring six or more — a standard-layout pad that never presses either included. Read alone
+     * it fired the correction on pads whose buttons were already right, which is how an Xbox pad
+     * came to answer X with Y and Y with LB (field reports, 2026-08-21). It stays as the narrower
+     * question it can answer — WHICH straight-through order, once `namedTriggers` has established
+     * there is one — where a false positive costs nothing.
+     */
+    fun padButtons(dev: InputDevice, namedTriggers: Boolean): PadButtons {
+        val has = dev.hasKeys(KeyEvent.KEYCODE_BUTTON_C, KeyEvent.KEYCODE_BUTTON_Z, 0)
+        return padButtons(namedTriggers, dev.vendorId == VID_SONY, declaresCZ = has[0] && has[1])
+    }
+
+    /** [padButtons]'s choice over plain facts — the seam its truth table is tested at (an
+     * [InputDevice] cannot be built off a device). */
+    fun padButtons(namedTriggers: Boolean, sony: Boolean, declaresCZ: Boolean): PadButtons = when {
+        namedTriggers -> PadButtons.NATIVE
+        declaresCZ && sony -> PadButtons.GENERIC_SONY
+        declaresCZ -> PadButtons.GENERIC_XBOX
+        sony -> PadButtons.SONY_MODERN
+        else -> PadButtons.NATIVE
+    }
+
+    /**
+     * The [PadMap] for [dev] — its button report order and the axes its right stick and triggers
+     * arrive on, resolved once per device model and cached.
+     *
+     * Axes get the same treatment as buttons: a pad Android has a layout for names its triggers
+     * LTRIGGER/RTRIGGER (or BRAKE/GAS, or BRAKE/THROTTLE) and is left exactly as it was. A pad
+     * with NONE of those names is one Android never mapped, and its triggers are sitting on two
+     * raw axes under the names the HID report gave them. Which two depends on the same report
+     * order the buttons did:
+     *
+     *  - a Sony pad reporting straight through lays out X, Y, Z, Rz, Rx, Ry = left stick, right
+     *    stick, then the triggers — so the right stick is already right and only the triggers
+     *    (`AXIS_RX`/`AXIS_RY`) are missed;
+     *  - every other such pad puts the right stick on Rx/Ry and the triggers on Z/Rz, which is
+     *    the shape that makes pulling a trigger swing the right stick.
+     *
+     * Whether those axes idle at −1 is MEASURED from the device's own range rather than assumed,
+     * so a pad that reports an honest 0..1 is not rescaled to a permanent half-pull.
+     */
+    fun padMap(dev: InputDevice?): PadMap {
+        if (dev == null) return NATIVE_MAP
+        padMaps[dev.descriptor]?.let { return it }
+        fun has(a: Int) = axis(dev, a) != null
+        val named = (has(MotionEvent.AXIS_LTRIGGER) && has(MotionEvent.AXIS_RTRIGGER)) ||
+            (has(MotionEvent.AXIS_BRAKE) && has(MotionEvent.AXIS_GAS)) ||
+            (has(MotionEvent.AXIS_BRAKE) && has(MotionEvent.AXIS_THROTTLE))
+        val buttons = padButtons(dev, namedTriggers = named)
+        val rx = axis(dev, MotionEvent.AXIS_RX)
+        val hasRxRy = rx != null && has(MotionEvent.AXIS_RY)
+        // Whichever pair the fallback is about to pick, ask THAT one where it rests.
+        val restsNegative = if (buttons == PadButtons.GENERIC_SONY) {
+            (rx?.min ?: 0f) < -0.5f
+        } else {
+            (axis(dev, MotionEvent.AXIS_Z)?.min ?: 0f) < -0.5f
+        }
+        val map = padMap(buttons, namedTriggers = named, hasRxRy = hasRxRy, restsNegative = restsNegative)
+        padMaps[dev.descriptor] = map
+        return map
+    }
+
+    /**
+     * The axis half of [padMap], decided from four facts about the device so it can be pinned
+     * without one — see `PadButtonsTest`. [namedTriggers] is whether the pad calls its triggers
+     * anything Android knows (LTRIGGER/RTRIGGER, BRAKE/GAS, BRAKE/THROTTLE); if it does, nothing
+     * here applies and the pad is read exactly as it always was. [restsNegative] is measured off
+     * whichever axis pair the fallback picks, never assumed.
+     */
+    fun padMap(
+        buttons: PadButtons,
+        namedTriggers: Boolean,
+        hasRxRy: Boolean,
+        restsNegative: Boolean,
+    ): PadMap = when {
+        namedTriggers || !hasRxRy -> PadMap(buttons)
+        // X, Y, Z, Rz, Rx, Ry = left stick, right stick, triggers. The sticks already read right.
+        buttons == PadButtons.GENERIC_SONY -> PadMap(
+            buttons,
+            leftTrigger = MotionEvent.AXIS_RX,
+            rightTrigger = MotionEvent.AXIS_RY,
+            triggersSigned = restsNegative,
+        )
+        // Right stick on Rx/Ry and triggers on Z/Rz — the shape in which reading Z/Rz as the
+        // right stick makes pulling a trigger swing it.
+        else -> PadMap(
+            buttons,
+            rightStickX = MotionEvent.AXIS_RX,
+            rightStickY = MotionEvent.AXIS_RY,
+            leftTrigger = MotionEvent.AXIS_Z,
+            rightTrigger = MotionEvent.AXIS_RZ,
+            triggersSigned = restsNegative,
+        )
+    }
+
+    /** [dev]'s range for one joystick [axis], under either source class a pad reports on. */
+    private fun axis(dev: InputDevice, axis: Int): InputDevice.MotionRange? =
+        dev.getMotionRange(axis, InputDevice.SOURCE_JOYSTICK)
+            ?: dev.getMotionRange(axis, InputDevice.SOURCE_GAMEPAD)
+
+    /**
+     * The keycode [event] should have carried, given the controller it came from — [event]'s own
+     * keycode for every pad Android has a key layout for, and the scancode's true button for one
+     * it does not (see the block comment above [PadButtons]).
+     *
+     * A drop-in for `event.keyCode` at every gamepad reader: the console UI's navigation, the
+     * Controllers screen's tester, and the streaming branch all route through it, so a mis-mapped
+     * pad is fixed in the menus and in the game at once. Events from anything that is not a
+     * controller, and events with no scancode (soft keyboards, synthetic events), pass through
+     * untouched.
+     */
+    fun padKeyCode(event: KeyEvent): Int {
+        val dev = event.device ?: return event.keyCode
+        if (event.scanCode == 0 || !isPad(dev)) return event.keyCode
+        return padMap(dev).buttons.correct(event.scanCode, event.keyCode)
+    }
+
     /**
      * 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
@@ -306,7 +683,12 @@ object Gamepad {
      * node (DualSense/DS4 motion sensors), which reports every pad axis as 0. [onMotion] therefore
      * folds the event straight in without re-qualifying it.
      */
-    class AxisMapper(private val handle: Long, private val pad: Int) {
+    class AxisMapper(
+        private val handle: Long,
+        private val pad: Int,
+        /** Which axes this controller's right stick and triggers arrive on — see [padMap]. */
+        private val map: PadMap = NATIVE_MAP,
+    ) {
         // Sentinel so the first real value (incl. 0) always sends once after attach (Linux parity).
         private val last = IntArray(6) { Int.MIN_VALUE }
         private var hatX = 0 // -1 / 0 / +1
@@ -317,30 +699,18 @@ object Gamepad {
             // Sticks: Android floats −1..1, +y = down → ±32767, negate Y for the wire's +y = up.
             sendAxis(AXIS_LS_X, stick(event.getAxisValue(MotionEvent.AXIS_X)))
             sendAxis(AXIS_LS_Y, stick(-event.getAxisValue(MotionEvent.AXIS_Y)))
-            sendAxis(AXIS_RS_X, stick(event.getAxisValue(MotionEvent.AXIS_Z)))
-            sendAxis(AXIS_RS_Y, stick(-event.getAxisValue(MotionEvent.AXIS_RZ)))
+            sendAxis(AXIS_RS_X, stick(event.getAxisValue(map.rightStickX)))
+            sendAxis(AXIS_RS_Y, stick(-event.getAxisValue(map.rightStickY)))
 
             // Triggers: pads report LTRIGGER/RTRIGGER or BRAKE/GAS (some mirror both) — merge
             // with max, the same fold as the Controllers screen probe, so a pad that reports
-            // only one pair and a pad that reports both behave identically; 0..1 → 0..255.
-            sendAxis(
-                AXIS_LT,
-                trigger(
-                    maxOf(
-                        event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
-                        event.getAxisValue(MotionEvent.AXIS_BRAKE),
-                    ),
-                ),
-            )
-            sendAxis(
-                AXIS_RT,
-                trigger(
-                    maxOf(
-                        event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
-                        event.getAxisValue(MotionEvent.AXIS_GAS),
-                    ),
-                ),
-            )
+            // only one pair and a pad that reports both behave identically; 0..1 → 0..255. A pad
+            // reporting NONE of those names is one Android has no key layout for, and [map]
+            // carries the raw axes its triggers really landed on instead.
+            val lt = resolved(event, map.leftTrigger, MotionEvent.AXIS_LTRIGGER, MotionEvent.AXIS_BRAKE)
+            val rt = resolved(event, map.rightTrigger, MotionEvent.AXIS_RTRIGGER, MotionEvent.AXIS_GAS)
+            sendAxis(AXIS_LT, trigger(lt))
+            sendAxis(AXIS_RT, trigger(rt))
 
             // HAT → dpad button transitions. Android BATCHES joystick ACTION_MOVEs, so a rapid d-pad
             // tap (press+release inside one batch window) lives only in the historical samples — the
@@ -383,6 +753,17 @@ object Gamepad {
             hatY = 0
         }
 
+        /**
+         * One trigger's 0..1 value: [resolvedAxis] when this pad needed one resolved for it,
+         * else the max of the two names Android gives a trigger it does know.
+         */
+        private fun resolved(event: MotionEvent, resolvedAxis: Int, named: Int, alias: Int): Float =
+            if (resolvedAxis == AXIS_NONE) {
+                maxOf(event.getAxisValue(named), event.getAxisValue(alias))
+            } else {
+                map.level(event.getAxisValue(resolvedAxis))
+            }
+
         private fun sendAxis(id: Int, v: Int) {
             if (last[id] == v) return
             last[id] = v

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

@@ -605,7 +605,7 @@ class GamepadRouter(
         // for the slot's life; the sensor path reads it on every sample.
         val slot = Slot(
             index,
-            Gamepad.AxisMapper(handle, index),
+            Gamepad.AxisMapper(handle, index, Gamepad.padMap(dev)),
             NativeBridge.nativePadMotionReaches(handle, pref),
         )
         slots[dev.id] = slot

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

@@ -298,6 +298,18 @@ object NativeBridge {
         surfaceH: Int,
     )
 
+    /**
+     * Re-report the video SurfaceView's on-screen pixel size — call it from every `surfaceChanged`.
+     *
+     * The ASurfaceControl present backend composites the picture into exactly this rectangle, and
+     * the view grows AFTER [nativeStartVideo] has run: the stream screen hides the system bars and
+     * switches the window to draw into the display cutout a frame or two later, and neither
+     * recreates the surface. Without this the layer keeps painting at its start-up size in the
+     * corner of a now-bigger surface. Non-positive values are ignored. No-op on a `0` handle;
+     * cheap (one atomic store), UI-safe.
+     */
+    external fun nativeVideoSurfaceSize(handle: Long, width: Int, height: Int)
+
     /** Stop + join the decode thread without closing the session. No-op on `0`. */
     external fun nativeStopVideo(handle: Long)
 

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

@@ -0,0 +1,254 @@
+package io.unom.punktfunk.kit
+
+import android.view.KeyEvent
+import android.view.MotionEvent
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Pure JVM test of [Gamepad.PadButtons.correct] — the scancode resolution for controllers Android
+ * has no key layout for. Only `KeyEvent`'s compile-time-inlined keycode constants are involved, so
+ * no Android runtime is needed. Run: `./gradlew :kit:testDebugUnitTest`.
+ *
+ * The regression it pins is a field report from a Fire TV Stick 4K Max (2026-08-20): a DualSense
+ * and an Xbox Elite Series 2, both over Bluetooth, both identified correctly but with buttons
+ * landing on the wrong actions — "L1 being L2". Neither pad has a key layout on that box (AOSP
+ * ships none for `045e:0b05` at all, and the DualSense's requires `CONFIG_HID_PLAYSTATION`), so
+ * both fall back to `Generic.kl`, which names keycodes by scancode POSITION. A pad with no kernel
+ * driver numbers its HID buttons 1..n straight through in its own report order, so every keycode
+ * after the first divergence belongs to a different button.
+ *
+ * The table below is the pad's physical button on the left and where `Generic.kl` put it on the
+ * right; the assertions read it back the other way.
+ */
+class PadButtonsTest {
+
+    private fun sony(scan: Int) =
+        Gamepad.PadButtons.GENERIC_SONY.correct(scan, Gamepad.genericKeyCode(scan))
+
+    private fun xbox(scan: Int) =
+        Gamepad.PadButtons.GENERIC_XBOX.correct(scan, Gamepad.genericKeyCode(scan))
+
+    /**
+     * The exact report: a DualSense's L2 sits at scancode `0x136`, which `Generic.kl` calls
+     * BUTTON_L1 — so pulling L2 read as a shoulder press, and L1 (at `0x134`, read as BUTTON_Y)
+     * read as a face button.
+     */
+    @Test
+    fun `a DualSense's shoulders stop being each other's buttons`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, sony(0x134)) // L1, delivered as BUTTON_Y
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R1, sony(0x135)) // R1, delivered as BUTTON_Z
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L2, sony(0x136)) // L2, delivered as BUTTON_L1
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R2, sony(0x137)) // R2, delivered as BUTTON_R1
+    }
+
+    /** ✕ is the bottom button — the one A means everywhere else — and □ is the left one. */
+    @Test
+    fun `a DualSense's face buttons land on their Xbox positions`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, sony(0x130)) // □
+        assertEquals(KeyEvent.KEYCODE_BUTTON_A, sony(0x131)) // ✕
+        assertEquals(KeyEvent.KEYCODE_BUTTON_B, sony(0x132)) // ○
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, sony(0x133)) // △
+    }
+
+    /**
+     * Create/Options/L3/R3/PS. Select in particular: without this it arrived as BUTTON_THUMBL,
+     * which took the exit, mic and stats chords with it — every one of them is built on Select.
+     */
+    @Test
+    fun `a DualSense's menu buttons and stick clicks are themselves`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_SELECT, sony(0x138)) // Create
+        assertEquals(KeyEvent.KEYCODE_BUTTON_START, sony(0x139)) // Options
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBL, sony(0x13a)) // L3
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBR, sony(0x13b)) // R3
+        assertEquals(KeyEvent.KEYCODE_BUTTON_MODE, sony(0x13c)) // PS
+    }
+
+    /** The touchpad click and mute have no wire button; they must resolve to nothing, not to R3. */
+    @Test
+    fun `a DualSense's touchpad and mute are dropped rather than mistaken`() {
+        assertEquals(KeyEvent.KEYCODE_UNKNOWN, sony(0x13d))
+        assertEquals(KeyEvent.KEYCODE_UNKNOWN, sony(0x13e))
+        assertEquals(0, Gamepad.buttonBit(sony(0x13d)))
+    }
+
+    /** An Xbox-layout pad numbering straight through: A B X Y LB RB View Menu LS RS. */
+    @Test
+    fun `an Xbox pad numbering straight through keeps its own layout`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_A, xbox(0x130))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_B, xbox(0x131))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, xbox(0x132))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, xbox(0x133))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, xbox(0x134))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R1, xbox(0x135))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_SELECT, xbox(0x136)) // View
+        assertEquals(KeyEvent.KEYCODE_BUTTON_START, xbox(0x137)) // Menu
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBL, xbox(0x138))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBR, xbox(0x139))
+    }
+
+    /** `hid-playstation` emits the modern Linux codes, where only the face pair reads swapped. */
+    @Test
+    fun `a driver-backed Sony pad has only its face pair corrected`() {
+        val m = Gamepad.PadButtons.SONY_MODERN
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, m.correct(0x133, KeyEvent.KEYCODE_BUTTON_X)) // △
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, m.correct(0x134, KeyEvent.KEYCODE_BUTTON_Y)) // □
+        for (scan in listOf(0x130, 0x131, 0x136, 0x137, 0x13a, 0x13b, 0x13c)) {
+            assertEquals(Gamepad.genericKeyCode(scan), m.correct(scan, Gamepad.genericKeyCode(scan)))
+        }
+    }
+
+    /**
+     * The guard that makes all of this safe to run on every pad: a keycode that is NOT what
+     * `Generic.kl` would have said came from a device-specific key layout, which knows this
+     * controller better than any table here. Correcting it would break a pad that works.
+     */
+    @Test
+    fun `a keycode a device layout already resolved is never second-guessed`() {
+        // AOSP's DualSense layout puts △ on BUTTON_Y itself. Every profile must leave it be.
+        for (p in Gamepad.PadButtons.entries) {
+            assertEquals(KeyEvent.KEYCODE_BUTTON_Y, p.correct(0x133, KeyEvent.KEYCODE_BUTTON_Y))
+        }
+        // Same for a scancode outside the generic gamepad block entirely — a pad's Back key.
+        assertEquals(
+            KeyEvent.KEYCODE_BACK,
+            Gamepad.PadButtons.GENERIC_SONY.correct(158, KeyEvent.KEYCODE_BACK),
+        )
+    }
+
+    /** Correcting twice is correcting once — the output is never itself a generic-layout answer. */
+    @Test
+    fun `correction is idempotent`() {
+        for (p in Gamepad.PadButtons.entries) {
+            for (scan in 0x130..0x13e) {
+                val once = p.correct(scan, Gamepad.genericKeyCode(scan))
+                assertEquals(once, p.correct(scan, once))
+            }
+        }
+    }
+
+    /**
+     * The axis half. A pad that names its triggers something Android knows is read exactly as it
+     * always was — this is the branch that must NOT fire on the pads that already work.
+     */
+    @Test
+    fun `a pad that names its triggers is read unchanged`() {
+        for (p in Gamepad.PadButtons.entries) {
+            val map = Gamepad.padMap(p, namedTriggers = true, hasRxRy = true, restsNegative = true)
+            assertEquals(MotionEvent.AXIS_Z, map.rightStickX)
+            assertEquals(MotionEvent.AXIS_RZ, map.rightStickY)
+            assertEquals(Gamepad.AXIS_NONE, map.leftTrigger)
+            assertEquals(Gamepad.AXIS_NONE, map.rightTrigger)
+        }
+        // Same when there is no Rx/Ry to fall back to in the first place.
+        val none = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = false, restsNegative = false)
+        assertEquals(Gamepad.AXIS_NONE, none.leftTrigger)
+    }
+
+    /**
+     * A Sony pad reporting straight through lays out X, Y, Z, Rz, Rx, Ry — left stick, right
+     * stick, then the triggers. Only the triggers were being missed; the sticks already read
+     * right and must be left alone.
+     */
+    @Test
+    fun `an unmapped Sony pad keeps its sticks and gains its triggers`() {
+        val map = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = true, restsNegative = false)
+        assertEquals(MotionEvent.AXIS_Z, map.rightStickX)
+        assertEquals(MotionEvent.AXIS_RZ, map.rightStickY)
+        assertEquals(MotionEvent.AXIS_RX, map.leftTrigger)
+        assertEquals(MotionEvent.AXIS_RY, map.rightTrigger)
+    }
+
+    /**
+     * Every other unmapped pad is the opposite way round: right stick on Rx/Ry, triggers on Z/Rz.
+     * Reading Z/Rz as the right stick there is what makes pulling a trigger swing it — so the two
+     * pairs must never be mixed up, which is the whole point of pinning them.
+     */
+    @Test
+    fun `an unmapped Xbox-layout pad has its stick and triggers the other way round`() {
+        for (p in listOf(Gamepad.PadButtons.GENERIC_XBOX, Gamepad.PadButtons.SONY_MODERN)) {
+            val map = Gamepad.padMap(p, namedTriggers = false, hasRxRy = true, restsNegative = false)
+            assertEquals(MotionEvent.AXIS_RX, map.rightStickX)
+            assertEquals(MotionEvent.AXIS_RY, map.rightStickY)
+            assertEquals(MotionEvent.AXIS_Z, map.leftTrigger)
+            assertEquals(MotionEvent.AXIS_RZ, map.rightTrigger)
+        }
+    }
+
+    /**
+     * A trigger axis that idles at −1 is rescaled; one that idles at 0 must NOT be, or it would
+     * read as a permanent half-pull. Which it is gets measured off the device, never assumed —
+     * both the DualSense's raw RX/RY and the Xbox pad's Z/Rz report an honest 0..1.
+     */
+    @Test
+    fun `only a trigger that idles negative is rescaled`() {
+        val signed = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = true, restsNegative = true)
+        assertEquals(0f, signed.level(-1f), 1e-6f)
+        assertEquals(0.5f, signed.level(0f), 1e-6f)
+        assertEquals(1f, signed.level(1f), 1e-6f)
+
+        val unsigned = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = true, restsNegative = false)
+        assertEquals(0f, unsigned.level(0f), 1e-6f)
+        assertEquals(1f, unsigned.level(1f), 1e-6f)
+    }
+
+    /** A pad Android does know is untouched, which is most of them. */
+    @Test
+    fun `a pad with a key layout is left alone`() {
+        for (scan in 0x130..0x13e) {
+            val generic = Gamepad.genericKeyCode(scan)
+            assertEquals(generic, Gamepad.PadButtons.NATIVE.correct(scan, generic))
+        }
+    }
+
+    /**
+     * The regression that made this gate necessary (field reports, 2026-08-21): an Xbox Wireless
+     * Controller and a GameSir G8+, both with their buttons at the standard positions and both
+     * corrected anyway, because `hasKeys` says BUTTON_C and BUTTON_Z for any pad that DECLARES six
+     * buttons — `hid-input` allocates the whole descriptor `BTN_A + n` straight through whether the
+     * pad ever presses them or not. Naming the triggers is what tells the two apart.
+     */
+    @Test
+    fun `a pad that names its triggers is never corrected, whatever it declares`() {
+        for (sony in listOf(false, true)) {
+            for (declaresCZ in listOf(false, true)) {
+                assertEquals(
+                    Gamepad.PadButtons.NATIVE,
+                    Gamepad.padButtons(namedTriggers = true, sony = sony, declaresCZ = declaresCZ),
+                )
+            }
+        }
+    }
+
+    /**
+     * The four buttons the field reports named, on a pad whose report order is already standard:
+     * X answering Y, Y answering LB, and both shoulders answering a menu button. NATIVE is what
+     * keeps them themselves — the correction tables are right for the pads they are for, and this
+     * is about not reaching one of them.
+     */
+    @Test
+    fun `an Xbox pad at the standard positions keeps X, Y and its shoulders`() {
+        val native = Gamepad.PadButtons.NATIVE
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, native.correct(0x133, KeyEvent.KEYCODE_BUTTON_X))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, native.correct(0x134, KeyEvent.KEYCODE_BUTTON_Y))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, native.correct(0x136, KeyEvent.KEYCODE_BUTTON_L1))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R1, native.correct(0x137, KeyEvent.KEYCODE_BUTTON_R1))
+        // What the old heuristic did to each of them, kept here so the difference stays visible.
+        val wrong = Gamepad.PadButtons.GENERIC_XBOX
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, wrong.correct(0x133, KeyEvent.KEYCODE_BUTTON_X))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, wrong.correct(0x134, KeyEvent.KEYCODE_BUTTON_Y))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_SELECT, wrong.correct(0x136, KeyEvent.KEYCODE_BUTTON_L1))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_START, wrong.correct(0x137, KeyEvent.KEYCODE_BUTTON_R1))
+    }
+
+    /** Past the gate, which straight-through order to read is still the question it always was. */
+    @Test
+    fun `an unnamed-trigger pad still resolves its report order`() {
+        fun order(sony: Boolean, declaresCZ: Boolean) =
+            Gamepad.padButtons(namedTriggers = false, sony = sony, declaresCZ = declaresCZ)
+        assertEquals(Gamepad.PadButtons.GENERIC_SONY, order(sony = true, declaresCZ = true))
+        assertEquals(Gamepad.PadButtons.GENERIC_XBOX, order(sony = false, declaresCZ = true))
+        assertEquals(Gamepad.PadButtons.SONY_MODERN, order(sony = true, declaresCZ = false))
+        assertEquals(Gamepad.PadButtons.NATIVE, order(sony = false, declaresCZ = false))
+    }
+}

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

@@ -0,0 +1,67 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The truth table behind "is a controller attached" — the question the console UI's
+ * "With a controller" mode is answered by. A false positive here is not cosmetic: it pins the
+ * console UI on with no pad in the room, and no setting short of turning the whole thing off can
+ * dismiss it, because the phantom pad never disconnects.
+ */
+class PadPresenceTest {
+
+    /** A real pad: the source class plus hardware behind it, in either of the two shapes. */
+    @Test
+    fun realPadsCount() {
+        assertTrue(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = true, hasFaceButtons = true,
+            ),
+        )
+        // An arcade stick / d-pad-only pad — buttons, no analog stick.
+        assertTrue(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = false, hasFaceButtons = true,
+            ),
+        )
+        // A wheel or flight stick — axes, no A/B.
+        assertTrue(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = true, hasFaceButtons = false,
+            ),
+        )
+    }
+
+    /** The gaming-phone shoulder triggers and OEM game-mode overlays: a virtual device wearing the
+     * gamepad source class. This is the field report — the console UI that could not be dismissed. */
+    @Test
+    fun virtualDevicesAreNotControllers() {
+        assertFalse(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = true, hasStick = true, hasFaceButtons = true,
+            ),
+        )
+    }
+
+    /** A device that claims a pad source with nothing behind it is not a pad either. */
+    @Test
+    fun aSourceClaimWithoutHardwareIsNotAController() {
+        assertFalse(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = false, hasFaceButtons = false,
+            ),
+        )
+    }
+
+    /** And a keyboard/mouse with sticks it never reports on the joystick source stays out. */
+    @Test
+    fun nonPadSourcesNeverCount() {
+        assertFalse(
+            Gamepad.looksLikeController(
+                padSource = false, virtual = false, hasStick = true, hasFaceButtons = true,
+            ),
+        )
+    }
+}

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

@@ -45,6 +45,10 @@ struct CreateOptions {
     device_name: String,
     /// Skia's resource budget, bytes (Kotlin sizes it from `ActivityManager.memoryClass`).
     gpu_cache_bytes: usize,
+    /// Whether the touch shell exists as a fallback (phones/tablets; false on a TV) —
+    /// gates the console-off settings row. Default false: absent means don't offer it.
+    #[serde(default)]
+    fallback_ui: bool,
     /// The settings snapshot the shell starts from (`pf_client_core::trust::Settings` JSON).
     settings: pf_client_core::trust::Settings,
     /// The profile catalog as `[[id, name], …]`.
@@ -150,6 +154,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConsoleCrea
         let console_opts = ConsoleOptions {
             device_name: opts.device_name,
             deck: false,
+            fallback_ui: opts.fallback_ui,
             store: Some(store.clone()),
             platform: Platform::Android,
             gpu_cache_bytes: opts.gpu_cache_bytes.max(16 << 20),

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

@@ -142,21 +142,21 @@ pub(super) struct AscBackend {
 impl AscBackend {
     /// Create the reader + compositor layer, or `None` on API < 29 / init failure (the caller then
     /// runs the SurfaceView presenter). `window` is the SurfaceView's `ANativeWindow`; `src_w/h` the
-    /// negotiated decode size; `panel_hz` the mode-table panel rate (seeds the learner);
+    /// negotiated decode size; `surface_size` the LIVE view size the layer composites into;
+    /// `panel_hz` the mode-table panel rate (seeds the learner);
     /// `dataspace` the `ADataSpace` from the negotiated colour; `source_hz` the negotiated stream rate.
     #[allow(clippy::too_many_arguments)]
     pub(super) fn create(
         window: &NativeWindow,
         src_w: i32,
         src_h: i32,
-        surface_w: i32,
-        surface_h: i32,
+        surface_size: std::sync::Arc<std::sync::atomic::AtomicU64>,
         panel_hz: i32,
         dataspace: i32,
         source_hz: u32,
         priority: PresentPriority,
     ) -> Option<AscBackend> {
-        let layer = Layer::create(window, surface_w, surface_h)?;
+        let layer = Layer::create(window, surface_size)?;
         let usage = ndk::hardware_buffer::HardwareBufferUsage::GPU_SAMPLED_IMAGE
             | ndk::hardware_buffer::HardwareBufferUsage::COMPOSER_OVERLAY;
         let reader = match ImageReader::new_with_usage(

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

@@ -96,8 +96,7 @@ pub(super) fn run_async(
         present_priority,
         smooth_buffer,
         panel_hz,
-        surface_w,
-        surface_h,
+        surface_size,
     } = opts;
     boost_thread_priority();
     let mode = client.mode();
@@ -199,8 +198,7 @@ pub(super) fn run_async(
             &window,
             mode.width as i32,
             mode.height as i32,
-            surface_w,
-            surface_h,
+            surface_size,
             panel_hz,
             initial_ds,
             mode.refresh_hz,

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

@@ -91,7 +91,14 @@ const NO_VIDEO_PATIENCE: std::time::Duration = std::time::Duration::from_millis(
 
 /// Re-ask cadence once [`NO_VIDEO_PATIENCE`] has elapsed with still nothing received. Slow, because
 /// this state is either self-healing on the first ask or not ours to heal — and each pass logs.
-const NO_VIDEO_RETRY: std::time::Duration = std::time::Duration::from_millis(2000);
+///
+/// ⚠ Taken from core, NOT a local number. `FLUSH_COOLDOWN` (the jump-to-live rate limit) is 2000 ms,
+/// and the host classifies a keyframe-recovery cadence by matching a cooldown's period ±10 % to
+/// decide WHICH client failure it is looking at. The two are opposites — "I have received nothing"
+/// versus "I am drowning in frames I cannot drain" — so while this was also 2000 ms the host
+/// confidently reported the wrong one, and a black-screen field case was diagnosed as a slow decoder
+/// for days (2026-08-20). Keeping the value in core is what stops the two drifting back together.
+const NO_VIDEO_RETRY: std::time::Duration = punktfunk_core::client::NO_VIDEO_RETRY;
 
 /// Whether low-latency mode uses the event-driven async decode loop (default) or the synchronous
 /// poll loop. Flip to `false` to A/B the two on the HUD (`design/…`); the async loop presents a
@@ -133,12 +140,12 @@ pub(crate) struct DecodeOptions {
     /// named here is not necessarily the one the panel ends up in. The measured timeline spacing
     /// corrects it in both directions ([`punktfunk_core::phase::PanelGrid`]).
     pub panel_hz: i32,
-    /// The video `SurfaceView`'s on-screen pixel size (the aspect-fitted display footprint), from
-    /// Kotlin at `surfaceCreated`. The ASurfaceControl backend composites its layer in this
-    /// coordinate space — NOT the window's buffer geometry, which is rotated/scaled. `0` = Kotlin
-    /// couldn't read it yet, and the backend falls back to the window buffer size.
-    pub surface_w: i32,
-    pub surface_h: i32,
+    /// The video `SurfaceView`'s LIVE on-screen pixel size (the aspect-fitted display footprint),
+    /// packed by [`crate::session::pack_surface_size`] and re-reported by Kotlin on every
+    /// `surfaceChanged`. The ASurfaceControl backend composites its layer in this coordinate space
+    /// — NOT the window's buffer geometry, which is rotated/scaled. `0` = Kotlin couldn't read it
+    /// yet, and the backend falls back to the window buffer size.
+    pub surface_size: std::sync::Arc<std::sync::atomic::AtomicU64>,
 }
 
 /// The decode entry point on the `pf-decode` thread: dispatches to the async or synchronous loop.

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

@@ -24,6 +24,7 @@ use ndk::hardware_buffer::HardwareBuffer;
 use ndk::native_window::NativeWindow;
 use std::ffi::c_void;
 use std::os::fd::{FromRawFd, OwnedFd, RawFd};
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::{mpsc, Arc};
 
 use super::async_loop::DecodeEvent;
@@ -276,9 +277,14 @@ unsafe extern "C" fn on_complete(context: *mut c_void, stats: *mut ASurfaceTrans
 pub(super) struct Layer {
     api: Api,
     sc: Arc<ScHandle>,
-    /// Destination rectangle (the SurfaceView's pixel size) — the buffer is scaled to fill it.
-    dest_w: i32,
-    dest_h: i32,
+    /// The SurfaceView's LIVE pixel size, packed by `pack_surface_size` and re-read before every
+    /// present — the destination rectangle the buffer is scaled to fill. Live rather than captured
+    /// because the view resizes under a surface that is never recreated (see `dest`).
+    surface_size: Arc<AtomicU64>,
+    /// Fallback destination for as long as `surface_size` is still `0` (Kotlin hadn't measured the
+    /// view when video started): the window's own buffer geometry, the best remaining guess.
+    fallback_w: i32,
+    fallback_h: i32,
     /// `true` once the first transaction has made the layer visible + set its z-order + frame rate.
     configured: bool,
 }
@@ -287,13 +293,16 @@ impl Layer {
     /// Create the compositor layer over `window` (the SurfaceView's `ANativeWindow`), or `None` on
     /// API < 29 / a null layer — the caller then uses the SurfaceView presenter.
     ///
-    /// `dest_w/h` are the SurfaceView's **on-screen pixel size** — the coordinate space the child
-    /// layer is composited into, which is the display footprint of the (aspect-fitted) video view,
-    /// NOT the window's buffer size. `ANativeWindow_getWidth/Height` return the buffer geometry in a
-    /// rotated/scaled space (observed 1260×567 for a 2800×1260 full-bleed stream) — using it shrank
-    /// the picture to the top-left corner. A non-positive `dest_w/h` (Kotlin couldn't read the view
-    /// yet) falls back to that buffer size as the best remaining guess.
-    pub(super) fn create(window: &NativeWindow, dest_w: i32, dest_h: i32) -> Option<Layer> {
+    /// `surface_size` carries the SurfaceView's **on-screen pixel size** — the coordinate space the
+    /// child layer is composited into, which is the display footprint of the (aspect-fitted) video
+    /// view, NOT the window's buffer size. `ANativeWindow_getWidth/Height` return the buffer
+    /// geometry in a rotated/scaled space (observed 1260×567 for a 2800×1260 full-bleed stream) —
+    /// using it shrank the picture to the top-left corner. It is read fresh on every present
+    /// because that view RESIZES mid-stream under a surface that is never recreated: the stream
+    /// screen hides the system bars and switches on cutout drawing a frame or two after
+    /// `surfaceCreated`, and each one grows it. An empty `surface_size` (Kotlin hadn't measured the
+    /// view yet) falls back to the buffer size as the best remaining guess.
+    pub(super) fn create(window: &NativeWindow, surface_size: Arc<AtomicU64>) -> Option<Layer> {
         let api = Api::resolve()?;
         // SAFETY: `window.ptr()` is the live `ANativeWindow` the decode thread owns; the name is a
         // static NUL-terminated string; the call returns null on failure (checked).
@@ -303,20 +312,11 @@ impl Layer {
             log::warn!("asc: createFromWindow returned null — falling back to SurfaceView");
             return None;
         }
-        let dest_w = if dest_w > 0 {
-            dest_w
-        } else {
-            window.width().max(1)
-        };
-        let dest_h = if dest_h > 0 {
-            dest_h
-        } else {
-            window.height().max(1)
-        };
+        let fallback_w = window.width().max(1);
+        let fallback_h = window.height().max(1);
         log::info!(
-            "asc: layer created, dest {dest_w}x{dest_h} (window buffer {}x{})",
-            window.width(),
-            window.height(),
+            "asc: layer created, dest {:?} (window buffer {fallback_w}x{fallback_h})",
+            crate::session::unpack_surface_size(surface_size.load(Ordering::Relaxed)),
         );
         Some(Layer {
             sc: Arc::new(ScHandle {
@@ -324,12 +324,20 @@ impl Layer {
                 release: api.ac_release,
             }),
             api,
-            dest_w,
-            dest_h,
+            surface_size,
+            fallback_w,
+            fallback_h,
             configured: false,
         })
     }
 
+    /// The destination rectangle for this present: the live view size, or the window's buffer
+    /// geometry while Kotlin has reported nothing.
+    fn dest(&self) -> (i32, i32) {
+        crate::session::unpack_surface_size(self.surface_size.load(Ordering::Relaxed))
+            .unwrap_or((self.fallback_w, self.fallback_h))
+    }
+
     /// Present one decoded buffer at `desired_present_ns` (`CLOCK_MONOTONIC`; `0` = ASAP). Consumes
     /// `acquire_fence` (ownership passes to SurfaceFlinger via `setBuffer`). Registers a one-shot
     /// completion that reports the real latch + the previous buffer's release fence on `ev_tx`,
@@ -370,11 +378,12 @@ impl Layer {
                 right: src_w.max(1),
                 bottom: src_h.max(1),
             };
+            let (dest_w, dest_h) = self.dest();
             let dst = ARect {
                 left: 0,
                 top: 0,
-                right: self.dest_w,
-                bottom: self.dest_h,
+                right: dest_w,
+                bottom: dest_h,
             };
             (self.api.txn_set_geometry)(txn, sc, &src, &dst, TRANSFORM_IDENTITY);
             if dataspace != 0 {

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

@@ -50,8 +50,7 @@ pub(super) fn run_sync(
         panel_hz: _,
         // The ASurfaceControl backend is async-loop only; the sync loop renders straight to the
         // SurfaceView, so it never needs the view's on-screen size.
-        surface_w: _,
-        surface_h: _,
+        surface_size: _,
     } = opts;
     boost_thread_priority();
     let mode = client.mode();

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

@@ -470,6 +470,8 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
                 // 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),
+                // Reported by Kotlin at `surfaceCreated` and on every resize after it.
+                surface_size: Arc::new(std::sync::atomic::AtomicU64::new(0)),
             };
             Box::into_raw(Box::new(handle)) as jlong
         }

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

@@ -26,7 +26,7 @@ mod probe;
 
 use punktfunk_core::client::NativeClient;
 use std::panic::AssertUnwindSafe;
-use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread::JoinHandle;
 
@@ -87,6 +87,37 @@ pub(crate) struct SessionHandle {
     /// `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,
+    /// The video `SurfaceView`'s LIVE on-screen pixel size ([`pack_surface_size`]), written by
+    /// `nativeStartVideo` and by every `nativeVideoSurfaceSize` the `surfaceChanged` callback
+    /// sends, read by the ASurfaceControl presenter before each present.
+    ///
+    /// Shared and live rather than a start-time parameter because the view RESIZES under a surface
+    /// that is never recreated: hiding the system bars and switching the window to
+    /// `LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS` both happen a frame or two AFTER `surfaceCreated`,
+    /// and each one grows the video view. A destination rect captured once at creation then keeps
+    /// compositing the picture at its old, smaller size anchored at the layer's origin — the
+    /// "stream in the top-left corner" field report. `0` = nothing reported yet, and the layer
+    /// falls back to the window's buffer geometry.
+    pub surface_size: Arc<AtomicU64>,
+}
+
+/// Pack a surface's pixel size into one `u64` — so the presenter reads width and height as a
+/// single atomic load and can never see a torn pair (a new width against an old height).
+/// Non-positive values pack as `0`, the "not reported yet" sentinel.
+pub(crate) fn pack_surface_size(w: i32, h: i32) -> u64 {
+    if w <= 0 || h <= 0 {
+        return 0;
+    }
+    ((w as u64) << 32) | (h as u64 & 0xffff_ffff)
+}
+
+/// The inverse of [`pack_surface_size`]: `None` for the `0` sentinel.
+#[cfg_attr(not(target_os = "android"), allow(dead_code))]
+pub(crate) fn unpack_surface_size(packed: u64) -> Option<(i32, i32)> {
+    if packed == 0 {
+        return None;
+    }
+    Some((((packed >> 32) as u32) as i32, (packed as u32) as i32))
 }
 
 struct VideoThread {
@@ -160,3 +191,29 @@ fn parse_hex32(s: &str) -> Option<[u8; 32]> {
     }
     Some(out)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{pack_surface_size, unpack_surface_size};
+
+    /// The pair the presenter reads as one atomic load must survive the round trip — including a
+    /// size wider than a signed 16-bit value, which every panel this runs on now is.
+    #[test]
+    fn surface_size_round_trips() {
+        assert_eq!(
+            unpack_surface_size(pack_surface_size(2800, 1260)),
+            Some((2800, 1260))
+        );
+        assert_eq!(unpack_surface_size(pack_surface_size(1, 1)), Some((1, 1)));
+    }
+
+    /// "Not reported yet" — and anything nonsensical — is the one sentinel, so the layer falls back
+    /// to the window's buffer geometry rather than composing into an empty rectangle.
+    #[test]
+    fn non_positive_sizes_are_the_sentinel() {
+        assert_eq!(pack_surface_size(0, 0), 0);
+        assert_eq!(pack_surface_size(1920, 0), 0);
+        assert_eq!(pack_surface_size(-1, 1080), 0);
+        assert_eq!(unpack_surface_size(0), None);
+    }
+}

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

@@ -72,6 +72,13 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
         let client = h.client.clone();
         let sd = shutdown.clone();
         let st = h.stats.clone(); // session-lifetime stats (gate survives surface recreate)
+
+        // Seed the live view size with what the view measures right now; `surfaceChanged` keeps it
+        // current from here on (the bars hide and the cutout mode changes AFTER this call).
+        h.surface_size.store(
+            super::pack_surface_size(surface_w, surface_h),
+            std::sync::atomic::Ordering::Relaxed,
+        );
         let opts = crate::decode::DecodeOptions {
             decoder_name: decoder,
             ll_feature,
@@ -80,8 +87,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
             present_priority,
             smooth_buffer,
             panel_hz: panel_fps,
-            surface_w,
-            surface_h,
+            surface_size: h.surface_size.clone(),
         };
         let join = std::thread::Builder::new()
             .name("pf-decode".into())
@@ -93,6 +99,37 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
     .resolve::<LogErrorAndDefault>()
 }
 
+/// `NativeBridge.nativeVideoSurfaceSize(handle, width, height)` — the video `SurfaceView`'s
+/// on-screen pixel size, re-reported on every `surfaceChanged`.
+///
+/// The ASurfaceControl presenter composites its child layer into exactly this rectangle, and the
+/// view resizes UNDER a surface that is never recreated: the stream screen hides the system bars
+/// and asks to draw into the display cutout a frame or two after `surfaceCreated`, both of which
+/// grow it. Without this the layer would keep painting the picture at its start-up size, in the
+/// corner of a bigger surface. Non-positive values are ignored (they'd blank the picture).
+/// No-op on a `0` handle. Stored whether or not video is running — the next `nativeStartVideo`
+/// then starts from a measured view rather than the window's guess. Not android-gated: 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_nativeVideoSurfaceSize(
+    _env: EnvUnowned,
+    _this: JObject,
+    handle: jlong,
+    width: jni::sys::jint,
+    height: jni::sys::jint,
+) {
+    jni_guard((), || {
+        let packed = super::pack_surface_size(width, height);
+        if handle == 0 || packed == 0 {
+            return;
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.surface_size
+            .store(packed, std::sync::atomic::Ordering::Relaxed);
+    })
+}
+
 /// `NativeBridge.nativeVideoMime(handle): String` — the MediaCodec MIME for the codec the host
 /// resolved (`"video/hevc"` / `"video/avc"` / `"video/av01"`), so Kotlin can rank `MediaCodecList`
 /// decoders for it before calling [`Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo`].

clients/probe/src/main.rs

@@ -53,9 +53,9 @@ use punktfunk_core::config::Role;
 use punktfunk_core::input::{InputEvent, InputKind};
 use punktfunk_core::packet::FLAG_PROBE;
 use punktfunk_core::quic::{
-    endpoint, io, window_loss_ppm, BitrateChanged, CursorRenderMode, Hello, LossReport,
-    ProbeRequest, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe, SetBitrate, Start,
-    Welcome,
+    endpoint, io, window_loss_ppm, BitrateChanged, CursorRenderMode, DeliveryReport, Hello,
+    LossReport, ProbeRequest, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe, SetBitrate,
+    Start, Welcome,
 };
 use punktfunk_core::transport::UdpTransport;
 use punktfunk_core::{CompositorPref, Mode, PunktfunkError, Session};
@@ -987,10 +987,18 @@ async fn session(args: Args) -> Result<()> {
         let mut ls = send;
         let lp = loss_ppm.clone();
         let df = dropped_frames.clone();
+        // Delivery truth for the host's dead-data-plane check: report what actually landed on the
+        // wire, so the probe reproduces a real client's answer rather than the "cannot answer"
+        // sentinel — which is exactly what makes it usable for testing that path.
+        let rxp = rx_wire_packets.clone();
         tokio::spawn(async move {
             use std::sync::atomic::Ordering::Relaxed;
             let mut last_report = std::time::Instant::now();
             let mut last_dropped = 0u64;
+            // Mirrors the real clients' rule (see `pump/data.rs`): report the delivery count every
+            // window while it is zero, once when the first packets land, then stop — so a host that
+            // predates the message is not flooded with "unknown control message" on a good session.
+            let mut delivery_confirmed = false;
             loop {
                 tokio::time::sleep(std::time::Duration::from_millis(100)).await;
                 let d = df.load(Relaxed);
@@ -1007,6 +1015,25 @@ async fn session(args: Args) -> Result<()> {
                 if last_report.elapsed() >= std::time::Duration::from_millis(750) {
                     last_report = std::time::Instant::now();
                     let v = lp.swap(u32::MAX, Relaxed);
+                    // Independent of whether there is a fresh loss sample: "no fresh sample" is
+                    // exactly the shape a dead data plane has, so gating it on one would silence
+                    // it in the state it exists to report.
+                    let received = rxp.load(Relaxed);
+                    if received == 0 || !delivery_confirmed {
+                        delivery_confirmed = received > 0;
+                        if io::write_msg(
+                            &mut ls,
+                            &DeliveryReport {
+                                packets_received: received,
+                            }
+                            .encode(),
+                        )
+                        .await
+                        .is_err()
+                        {
+                            break; // control stream gone
+                        }
+                    }
                     if v != u32::MAX
                         && io::write_msg(&mut ls, &LossReport { loss_ppm: v }.encode())
                             .await

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

@@ -148,6 +148,10 @@ pub(crate) enum HintKey {
     /// there isn't (the library grid spends up on rows) the same menu hangs off
     /// [`HintKey::Tertiary`] instead; the button differs, the word "Options" does not.
     Up,
+    /// ▼ — the home carousel's other spare direction, which opens Settings. Advertised in
+    /// place of [`HintKey::Tertiary`] where no pad is attached, because that is exactly the
+    /// device that has no X to press: a TV remote is a D-pad, OK and Back.
+    Down,
     Key(&'static str),
 }
 
@@ -272,7 +276,7 @@ fn glyph_width(fonts: &Fonts, key: HintKey, style: GlyphStyle, k: f64) -> f64 {
     match resolved(key, style) {
         Resolved::Badge(_) | Resolved::Adjust => BADGE_D * k,
         Resolved::Shoulders => 2.0 * shoulder_w(fonts, k) + 3.0 * k,
-        Resolved::Up => BADGE_D * k,
+        Resolved::Up | Resolved::Down => BADGE_D * k,
         Resolved::Key(text) => keycap_w(fonts, text, k),
     }
 }
@@ -294,6 +298,9 @@ enum Resolved {
     /// The d-pad's up — drawn the same in every style, because it is a direction rather
     /// than a button whose label changes with the pad.
     Up,
+    /// The d-pad's down — the same triangle stood on its head, and style-free for the
+    /// same reason [`Resolved::Up`] is.
+    Down,
     Key(&'static str),
 }
 
@@ -317,6 +324,7 @@ fn resolved(key: HintKey, style: GlyphStyle) -> Resolved {
             HintKey::Shoulders => Resolved::Key("Tab"),
             HintKey::Adjust => Resolved::Adjust,
             HintKey::Up => Resolved::Up,
+            HintKey::Down => Resolved::Down,
             HintKey::Key(t) => Resolved::Key(t),
         };
     }
@@ -327,6 +335,7 @@ fn resolved(key: HintKey, style: GlyphStyle) -> Resolved {
         HintKey::Secondary => Resolved::Badge(Face::Y),
         HintKey::Shoulders => Resolved::Shoulders,
         HintKey::Adjust => Resolved::Adjust,
+        HintKey::Down => Resolved::Down,
         HintKey::Up => Resolved::Up,
         HintKey::Key(t) => Resolved::Key(t),
     }
@@ -394,17 +403,23 @@ fn draw_glyph(
                 pen += w + 3.0 * k;
             }
         }
-        Resolved::Up => {
-            // ▲ — one solid triangle in a badge-sized slot.
+        g @ (Resolved::Up | Resolved::Down) => {
+            // ▲ / ▼ — one solid triangle in a badge-sized slot, the same triangle either
+            // way up: apex toward the direction it names, base at the other end.
             let r = BADGE_D * k / 2.0;
             let (cx, cyf) = ((x + r) as f32, cy as f32);
             let (tw, th) = ((5.5 * k) as f32, (4.5 * k) as f32);
-            let mut up = PathBuilder::new();
-            up.move_to((cx, cyf - th));
-            up.line_to((cx - tw, cyf + th));
-            up.line_to((cx + tw, cyf + th));
-            up.close();
-            canvas.draw_path(&up.detach(), &fill(fg(0.85)));
+            let (apex, base) = if matches!(g, Resolved::Down) {
+                (cyf + th, cyf - th)
+            } else {
+                (cyf - th, cyf + th)
+            };
+            let mut tri = PathBuilder::new();
+            tri.move_to((cx, apex));
+            tri.line_to((cx - tw, base));
+            tri.line_to((cx + tw, base));
+            tri.close();
+            canvas.draw_path(&tri.detach(), &fill(fg(0.85)));
         }
         Resolved::Adjust => {
             // ◀ ▶ — two small solid triangles.

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

@@ -63,6 +63,10 @@ pub(crate) struct Ctx<'a> {
     pub pads: &'a [PadInfo],
     /// Steam Deck: never draw our keyboard — Steam's types via SDL text input.
     pub deck: bool,
+    /// The host app has another interface to fall back to when the console is switched
+    /// off (an Android phone/tablet's touch shell) — see
+    /// [`crate::shell::ConsoleOptions::fallback_ui`]. Gates the console-off settings row.
+    pub fallback_ui: bool,
     /// The name the HOST stores this client under when pairing (the machine's
     /// hostname, resolved by the binary).
     pub device_name: &'a str,

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

@@ -396,6 +396,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads,
             deck,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         }

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

@@ -255,6 +255,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -301,6 +302,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -323,6 +325,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };

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

@@ -941,6 +941,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &[],
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };

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

@@ -378,6 +378,7 @@ mod tests {
             platform,
             pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -429,6 +430,7 @@ mod tests {
                 platform,
                 pads,
                 deck: false,
+                fallback_ui: false,
                 device_name: "t",
                 t: 0.0,
             }

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

@@ -206,7 +206,17 @@ impl HomeScreen {
                 }
                 _ => Some(MenuPulse::Boundary),
             },
-            MenuEvent::Move(_) => None,
+            // Down is Settings — the same screen X opens. The carousel is horizontal, so
+            // down is the other free direction, and it is the only route to Settings on a
+            // device whose input has no face buttons: an Android TV remote is a D-pad, OK
+            // and Back, and X never arrives. (Apple hit this on the Siri Remote too, and
+            // answered it by moving rows out to the ordinary Settings app.)
+            MenuEvent::Move(MenuDir::Down) => {
+                fx.push(Screen::Settings(super::settings::SettingsScreen::new(
+                    ctx.store,
+                )));
+                Some(MenuPulse::Confirm)
+            }
         }
     }
 
@@ -279,7 +289,15 @@ impl HomeScreen {
         {
             hints.push(Hint::new(HintKey::Up, "Options"));
         }
-        hints.push(Hint::new(HintKey::Tertiary, "Settings"));
+        // Name the route this device actually has. With no pad attached the legend is
+        // already speaking keyboard, and the one input that reaches here with neither a
+        // pad NOR letter keys is a TV remote — for which X is not a button that exists.
+        // Down opens Settings for everyone; only the advertisement changes.
+        hints.push(if ctx.pads.is_empty() {
+            Hint::new(HintKey::Down, "Settings")
+        } else {
+            Hint::new(HintKey::Tertiary, "Settings")
+        });
         hints.push(Hint::new(HintKey::Back, "Quit"));
         hints
     }
@@ -859,6 +877,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };
@@ -885,6 +904,67 @@ mod tests {
         ));
     }
 
+    /// Everything this screen offers must be reachable from a D-pad, OK and Back alone —
+    /// an Android TV remote has no face buttons, so Settings (X) and the options menu
+    /// would otherwise be unreachable there. Up is the menu, down is Settings, and the
+    /// legend names the direction rather than X when nothing is plugged in.
+    #[test]
+    fn a_remote_reaches_settings_and_options_without_face_buttons() {
+        let mut settings = ctx_settings();
+        let hosts = [host("paired", true, true, false)];
+        let pads: Vec<pf_client_core::menu_nav::PadInfo> = Vec::new();
+        let library = crate::library::LibraryShared::default();
+        let mut ctx = Ctx {
+            hosts: &hosts,
+            library: &library,
+            settings: &mut settings,
+            store: crate::store::file_store(),
+            platform: crate::platform::Platform::Android,
+            pads: &pads,
+            deck: false,
+            fallback_ui: true,
+            device_name: "test",
+            t: 0.0,
+        };
+        let mut s = HomeScreen::new();
+
+        // Down opens the same screen X opens.
+        let mut fx = Outbox::default();
+        s.menu(MenuEvent::Move(MenuDir::Down), &mut ctx, &mut fx);
+        assert!(
+            matches!(fx.nav, Some(crate::screens::Nav::Push(ref sc)) if matches!(**sc, Screen::Settings(_))),
+            "down must open Settings"
+        );
+        // Up still opens the host's own menu — the library hangs off that menu now.
+        let mut fx = Outbox::default();
+        s.menu(MenuEvent::Move(MenuDir::Up), &mut ctx, &mut fx);
+        assert!(
+            matches!(fx.nav, Some(crate::screens::Nav::Push(ref sc)) if matches!(**sc, Screen::HostOptions(_))),
+            "up must open the host options menu"
+        );
+        // With no pad the legend advertises the direction, not a button that isn't there.
+        assert!(
+            s.hints(&ctx).iter().any(|h| h.key == HintKey::Down),
+            "a padless device is told about down"
+        );
+        // With a pad it goes back to naming X, which is faster to press.
+        let pads = vec![pf_client_core::menu_nav::PadInfo {
+            name: "Pad".into(),
+            key: "045e:028e:Pad".into(),
+            pref: punktfunk_core::config::GamepadPref::Xbox360,
+            steam_virtual: false,
+            battery: None,
+            detail: "045E:028E · gamepad".into(),
+            forwarded: true,
+            rumble: false,
+        }];
+        ctx.pads = &pads;
+        assert!(
+            s.hints(&ctx).iter().any(|h| h.key == HintKey::Tertiary),
+            "a pad is told about X"
+        );
+    }
+
     /// A pinned card's A-press is a connect WITH its profile (one-off), titled so the
     /// connecting takeover says which settings are coming (§5.2a).
     #[test]
@@ -908,6 +988,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };
@@ -932,6 +1013,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };

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

@@ -2218,6 +2218,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &[],
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         }

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

@@ -34,6 +34,10 @@ use skia_safe::{Canvas, Rect};
 enum Action {
     Wake,
     SendLogs,
+    /// Open this host's game library — the same shelf the home carousel's Y opens, offered
+    /// here because Y is a face button and a TV remote has none. Saved-and-paired only,
+    /// exactly like that Y (an unpaired host has no shelf to fetch).
+    Library,
     CopyLink,
     Edit,
     /// Choose the profile the host's primary tile connects with (opens the
@@ -154,6 +158,12 @@ impl OptionsScreen {
         if host.paired && host.online {
             a.push(Action::SendLogs);
         }
+        // The shelf, on the same terms the carousel's Y offers it. Ahead of Copy link
+        // because it is the one row here that goes somewhere rather than acting on the
+        // host — and on a remote-only device it is the ONLY way to the library.
+        if host.paired && host.saved {
+            a.push(Action::Library);
+        }
         a.extend([
             Action::CopyLink,
             Action::Edit,
@@ -171,6 +181,7 @@ impl OptionsScreen {
         match a {
             Action::Wake => "Wake host".into(),
             Action::SendLogs => "Send logs to host".into(),
+            Action::Library => "Library".into(),
             Action::CopyLink => "Copy link".into(),
             Action::Edit => "Edit\u{2026}".into(),
             Action::BindProfile => "Default profile\u{2026}".into(),
@@ -234,7 +245,7 @@ impl OptionsScreen {
             ListMsg::Adjust(_) => Some(MenuPulse::Boundary),
             ListMsg::None => pulse,
             ListMsg::Activate => {
-                self.run(action, ctx.store, fx);
+                self.run(action, ctx, fx);
                 pulse
             }
         }
@@ -257,7 +268,8 @@ impl OptionsScreen {
         }
     }
 
-    fn run(&mut self, action: Action, store: &dyn crate::store::SettingsStore, fx: &mut Outbox) {
+    fn run(&mut self, action: Action, ctx: &Ctx, fx: &mut Outbox) {
+        let store = ctx.store;
         let key = self.host_key().to_string();
         match action {
             Action::Wake => {
@@ -289,6 +301,24 @@ impl OptionsScreen {
                 }
                 fx.pop();
             }
+            // Same two steps the home carousel's Y takes: ask for the shelf, then open it
+            // on the epoch read BEFORE the command drains, so the screen can tell its own
+            // fetch's titles from the ones already in the model. `replace`, not push — the
+            // menu has said its piece, and Back from the shelf belongs on the carousel
+            // rather than on a menu about the host you just left.
+            Action::Library => {
+                let host = self.host();
+                fx.cmds.push(ConsoleCmd::FetchLibrary {
+                    addr: host.addr.clone(),
+                    mgmt: host.mgmt_port,
+                    fp_hex: host.fp_hex.clone(),
+                });
+                let epoch = ctx.library.fetch_epoch();
+                fx.replace(Screen::Library(super::library::LibraryScreen::new(
+                    self.host(),
+                    epoch,
+                )));
+            }
             Action::Edit => fx.replace(Screen::AddHost(super::add_host::AddHostScreen::edit(
                 self.host(),
             ))),
@@ -407,6 +437,27 @@ mod tests {
     use crate::model::ProfileChip;
     use crate::screens::Nav;
 
+    /// Activate one row. `run` reads the store, and — for Library — the shared library's
+    /// fetch epoch; nothing else in this menu touches the context, so one throwaway is
+    /// enough for every action test here.
+    fn run_action(s: &mut OptionsScreen, action: Action, fx: &mut Outbox) {
+        let mut settings = pf_client_core::trust::Settings::default();
+        let library = crate::library::LibraryShared::default();
+        let ctx = Ctx {
+            hosts: &[],
+            library: &library,
+            settings: &mut settings,
+            store: crate::store::file_store(),
+            platform: crate::platform::Platform::Desktop,
+            pads: &[],
+            deck: false,
+            fallback_ui: false,
+            device_name: "test",
+            t: 0.0,
+        };
+        s.run(action, &ctx, fx);
+    }
+
     fn host() -> HostRow {
         HostRow {
             key: "aa".into(),
@@ -510,6 +561,38 @@ mod tests {
         assert_eq!(s.host_key(), "aa");
     }
 
+    /// The shelf is on this menu, which is the only route to it that survives a device with
+    /// no face buttons: home's Y opens it too, but an Android TV remote has no Y. Offered on
+    /// the same terms that Y is (saved AND paired), and it REPLACES the menu, so Back from
+    /// the shelf lands on the carousel rather than on a menu about the host just left.
+    #[test]
+    fn the_library_hangs_off_the_menu_for_a_padless_device() {
+        let mut s = OptionsScreen::for_host(&host());
+        assert!(s
+            .actions(crate::platform::Platform::Android)
+            .contains(&Action::Library));
+
+        let mut fx = Outbox::default();
+        run_action(&mut s, Action::Library, &mut fx);
+        assert!(
+            matches!(fx.cmds.first(), Some(ConsoleCmd::FetchLibrary { .. })),
+            "opening the shelf asks for it first"
+        );
+        match fx.nav {
+            Some(Nav::Replace(screen)) => assert!(matches!(*screen, Screen::Library(_))),
+            _ => panic!("expected the shelf to replace the menu"),
+        }
+
+        // An unpaired host has no shelf to fetch — the row is absent, not inert.
+        let unpaired = OptionsScreen::for_host(&HostRow {
+            paired: false,
+            ..host()
+        });
+        assert!(!unpaired
+            .actions(crate::platform::Platform::Android)
+            .contains(&Action::Library));
+    }
+
     /// "Default profile…" swaps the menu for the chooser — a Replace like Edit's, and for
     /// the same reason — addressed to the HOST's plain key even from rows that carry a
     /// composite one.
@@ -520,7 +603,7 @@ mod tests {
             .actions(crate::platform::Platform::Desktop)
             .contains(&Action::BindProfile));
         let mut fx = Outbox::default();
-        s.run(Action::BindProfile, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::BindProfile, &mut fx);
         match fx.nav {
             Some(crate::screens::Nav::Replace(screen)) => match *screen {
                 Screen::BindProfile(b) => assert_eq!(b.host_name(), "Desk"),
@@ -537,7 +620,7 @@ mod tests {
         let mut s = OptionsScreen::for_host(&host());
         assert!(s.label(Action::Clipboard).ends_with("Off"));
         let mut fx = Outbox::default();
-        s.run(Action::Clipboard, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Clipboard, &mut fx);
         assert_eq!(
             fx.cmds,
             vec![ConsoleCmd::SetClipboard {
@@ -551,7 +634,7 @@ mod tests {
         });
         assert!(s.label(Action::Clipboard).ends_with("On"));
         let mut fx = Outbox::default();
-        s.run(Action::Clipboard, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Clipboard, &mut fx);
         assert_eq!(
             fx.cmds,
             vec![ConsoleCmd::SetClipboard {
@@ -569,12 +652,12 @@ mod tests {
         s.list.cursor = i;
         let mut fx = Outbox::default();
 
-        s.run(Action::Forget, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Forget, &mut fx);
         assert!(fx.cmds.is_empty(), "the first press only arms");
         assert!(s.armed);
         assert!(s.label(Action::Forget).contains("press again"));
 
-        s.run(Action::Forget, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Forget, &mut fx);
         assert_eq!(
             fx.cmds,
             vec![ConsoleCmd::ForgetHost { key: "aa".into() }],
@@ -597,6 +680,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &[],
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };
@@ -659,7 +743,7 @@ mod tests {
             OptionsScreen::for_game(&host(), &game()),
         ] {
             let mut fx = Outbox::default();
-            s.run(Action::CopyLink, crate::store::file_store(), &mut fx);
+            run_action(&mut s, Action::CopyLink, &mut fx);
             assert!(matches!(fx.nav, Some(Nav::Pop)));
             assert!(fx.toast.is_some());
         }

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

@@ -497,6 +497,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "living-room-deck",
             t: 0.0,
         };
@@ -537,6 +538,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "deck",
             t: 0.0,
         };

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

@@ -233,6 +233,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -274,6 +275,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };

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

@@ -104,6 +104,12 @@ enum RowId {
     Sc2Passthrough,
     /// DualSense raw-USB capture (touchpad, motion, adaptive triggers).
     DsCapture,
+    /// Whether the console UI fronts the app at all — the touch settings' switch
+    /// (`Settings.gamepadUiEnabled`), reachable from inside the console it turns off.
+    /// Only offered where there is another interface to fall back to
+    /// ([`Ctx::fallback_ui`]): on a TV or the desktop session this console is the only
+    /// UI, and an off switch would strand the user in nothing.
+    GamepadUi,
     /// When the console UI fronts the app: with a controller attached, or always.
     GamepadUiMode,
     /// The platform's connected-controllers view (an action row — opens a native screen).
@@ -121,6 +127,7 @@ mod android_keys {
     pub const SC2: &str = "android.sc2_capture";
     pub const DS_CAPTURE: &str = "android.ds_capture";
     pub const GAMEPAD_UI_MODE: &str = "android.gamepad_ui_mode";
+    pub const GAMEPAD_UI: &str = "android.gamepad_ui_enabled";
 }
 
 /// The Android console-UI mode's stored values (`GamepadUi.kt`).
@@ -245,6 +252,7 @@ const TABS: [(&str, &[RowId]); 7] = [
             RowId::Stats,
             RowId::Fullscreen,
             RowId::AutoWake,
+            RowId::GamepadUi,
             RowId::GamepadUiMode,
             RowId::Licenses,
         ],
@@ -384,7 +392,7 @@ impl SettingsScreen {
                 .1
                 .iter()
                 .copied()
-                .filter(|id| row_on(*id, ctx.platform) && row_applies(*id, ctx.settings))
+                .filter(|id| row_on(*id, ctx.platform) && row_applies(*id, ctx))
                 .collect();
         }
         if self.profiles.is_empty() {
@@ -675,6 +683,7 @@ fn row_on(id: RowId, platform: crate::platform::Platform) -> bool {
             | RowId::PhoneGyro
             | RowId::Sc2Passthrough
             | RowId::DsCapture
+            | RowId::GamepadUi
             | RowId::GamepadUiMode
             | RowId::Controllers
             | RowId::Licenses
@@ -694,9 +703,22 @@ fn row_on(id: RowId, platform: crate::platform::Platform) -> bool {
     }
 }
 
-fn row_applies(id: RowId, s: &pf_client_core::trust::Settings) -> bool {
+fn row_applies(id: RowId, ctx: &Ctx) -> bool {
     match id {
-        RowId::SmoothBuffer => s.present_priority == "smooth",
+        RowId::SmoothBuffer => ctx.settings.present_priority == "smooth",
+        // The console-off switch needs somewhere for "off" to land: only clients with a
+        // fallback interface (an Android phone/tablet's touch shell) get the row — on a TV
+        // this console is the only UI, and off would strand the user (the touch settings'
+        // subtitle even promises "A TV always uses it").
+        RowId::GamepadUi => ctx.fallback_ui,
+        // The same two conditions the mode decides anything under: a TV is in console mode
+        // whatever the mode says (`GamepadUi.kt`: the tv term alone satisfies the OR), and
+        // while the switch above is off nothing fronts the console at all. Hidden rather
+        // than dimmed, like the touch screen's picker, and it sits directly below the row
+        // that drops it so the cursor is never under anything that moves.
+        RowId::GamepadUiMode => {
+            ctx.fallback_ui && extra_bool(ctx.settings, android_keys::GAMEPAD_UI, true)
+        }
         _ => true,
     }
 }
@@ -962,9 +984,17 @@ fn row_spec(id: RowId, ctx: &Ctx, profiles: &[(String, String)]) -> RowSpec {
             "DualSense over USB",
             on_off(extra_bool(s, android_keys::DS_CAPTURE, true)).into(),
         ),
+        RowId::GamepadUi => (
+            None,
+            "Controller-optimized UI",
+            on_off(extra_bool(s, android_keys::GAMEPAD_UI, true)).into(),
+        ),
         RowId::GamepadUiMode => (
             None,
-            "Controller UI",
+            // The touch screen's word for the same picker, which now sits under the same
+            // switch it does there — "Controller UI" beside "Controller-optimized UI"
+            // would be two rows a reader has to tell apart by their tails.
+            "Show it",
             label_for(
                 &GAMEPAD_UI_MODES,
                 extra_str(s, android_keys::GAMEPAD_UI_MODE, "connected"),
@@ -1145,9 +1175,14 @@ fn detail(id: RowId, platform: crate::platform::Platform) -> &'static str {
             "Capture a wired DualSense directly (touchpad, motion, adaptive triggers). \
              Needs the USB grant when the pad is plugged in."
         }
+        RowId::GamepadUi => {
+            "Front the app with this console instead of the touch interface. Off returns \
+             to the touch home immediately — switch it back on there."
+        }
         RowId::GamepadUiMode => {
             "When this console fronts the app: whenever a controller is attached, or \
-             always. The touch settings' \"Controller-optimized UI\" switch turns it off."
+             always — for a device that lives docked to a TV. The switch above turns it \
+             off altogether."
         }
         RowId::Controllers => "Connected controllers, their grants and a rumble/haptics test.",
         RowId::Licenses => "The open-source licences this app ships under.",
@@ -1375,6 +1410,7 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
         RowId::PhoneGyro => toggle_extra(s, android_keys::PHONE_GYRO, false, delta, wrap),
         RowId::Sc2Passthrough => toggle_extra(s, android_keys::SC2, true, delta, wrap),
         RowId::DsCapture => toggle_extra(s, android_keys::DS_CAPTURE, true, delta, wrap),
+        RowId::GamepadUi => toggle_extra(s, android_keys::GAMEPAD_UI, true, delta, wrap),
         RowId::GamepadUiMode => {
             let mut v = extra_str(s, android_keys::GAMEPAD_UI_MODE, "connected").to_string();
             step_str(&GAMEPAD_UI_MODES, &mut v, delta, wrap).map(|()| {
@@ -1504,6 +1540,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1538,6 +1575,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1603,6 +1641,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1652,6 +1691,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1686,6 +1726,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1727,6 +1768,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1757,6 +1799,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1793,6 +1836,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1867,6 +1911,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1900,6 +1945,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1931,6 +1977,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1960,6 +2007,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2009,6 +2057,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2060,6 +2109,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2105,6 +2155,7 @@ pub(super) mod tests {
                 RowId::Sc2Passthrough,
                 RowId::DsCapture,
                 RowId::Controllers,
+                RowId::GamepadUi,
                 RowId::GamepadUiMode,
                 RowId::Licenses,
             ]
@@ -2147,6 +2198,9 @@ pub(super) mod tests {
                 extra_str(ctx.settings, android_keys::GAMEPAD_UI_MODE, "connected"),
                 "always"
             );
+            assert!(extra_bool(ctx.settings, android_keys::GAMEPAD_UI, true));
+            assert!(adjust(RowId::GamepadUi, 1, true, ctx));
+            assert!(!extra_bool(ctx.settings, android_keys::GAMEPAD_UI, true));
             // Only `extra` moved.
             let mut after = ctx.settings.clone();
             after.extra = before.extra.clone();
@@ -2154,6 +2208,34 @@ pub(super) mod tests {
         });
     }
 
+    /// The console-off switch exists only where there is a fallback interface for "off"
+    /// to land in, and the mode row under it only where the mode decides anything: not on
+    /// a TV (always console, whatever the mode says) and not while the switch is off.
+    #[test]
+    fn console_off_switch_needs_a_fallback_ui() {
+        with_ctx(|ctx| {
+            ctx.platform = crate::platform::Platform::Android;
+            // A TV: no off switch (it would strand the user), and no mode row either —
+            // `gamepadUiActive`'s tv term satisfies the OR on its own.
+            assert!(
+                !row_applies(RowId::GamepadUi, ctx),
+                "a TV offers no off switch"
+            );
+            assert!(!row_applies(RowId::GamepadUiMode, ctx));
+            // A phone or tablet with the console on: both rows.
+            ctx.fallback_ui = true;
+            assert!(row_applies(RowId::GamepadUi, ctx));
+            assert!(row_applies(RowId::GamepadUiMode, ctx));
+            // Switched off: the switch stays (it is the way back), the mode row goes.
+            set_extra_bool(ctx.settings, android_keys::GAMEPAD_UI, false);
+            assert!(row_applies(RowId::GamepadUi, ctx));
+            assert!(
+                !row_applies(RowId::GamepadUiMode, ctx),
+                "the mode row decides nothing while the switch above it is off"
+            );
+        });
+    }
+
     #[test]
     fn every_row_has_exactly_one_tab() {
         let mut seen: Vec<RowId> = Vec::new();
@@ -2168,9 +2250,9 @@ pub(super) mod tests {
         // 2026-08 sweep found them bridged but unreachable) later passes added, minus the
         // game-library toggle: this screen never read it, and the library is offered on any
         // paired host now.
-        // 35 desktop rows + the eight Android-only ones (design android-skia-console-port.md
-        // D3): six `extra`-backed settings and two platform-screen action rows.
-        assert_eq!(seen.len(), 43, "{seen:?}");
+        // 35 desktop rows + the nine Android-only ones (design android-skia-console-port.md
+        // D3): seven `extra`-backed settings and two platform-screen action rows.
+        assert_eq!(seen.len(), 44, "{seen:?}");
         assert!(seen.contains(&RowId::Palette));
         assert!(seen.contains(&RowId::ReduceMotion));
         assert!(seen.contains(&RowId::AudioFormat));
@@ -2209,6 +2291,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2250,6 +2333,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2295,6 +2379,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2373,6 +2458,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };

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

@@ -183,6 +183,11 @@ pub struct ConsoleOptions {
     pub device_name: String,
     /// Steam Deck: Steam's keyboard types (SDL text input); ours never draws.
     pub deck: bool,
+    /// Whether the host app has another interface to fall back to when the console is
+    /// switched off — an Android phone/tablet's touch shell. Shows the console-off switch
+    /// on the settings screen; false where this console is the only UI there is (the
+    /// desktop session, an Android TV), where offering "off" would strand the user.
+    pub fallback_ui: bool,
     /// Where settings persist and the profile catalog comes from. `None` = the desktop
     /// file store (`pf_client_core::trust`), which is what the Vulkan session wants and the
     /// only store there is on Linux/Windows; every other host must supply one.
@@ -203,6 +208,7 @@ impl ConsoleOptions {
         ConsoleOptions {
             device_name,
             deck,
+            fallback_ui: false,
             store: None,
             platform: Platform::Desktop,
             gpu_cache_bytes: DEFAULT_GPU_CACHE_BYTES,
@@ -247,6 +253,8 @@ pub(crate) struct Shell {
     hosts_gen: u64,
     device_name: String,
     deck: bool,
+    /// See [`ConsoleOptions::fallback_ui`].
+    fallback_ui: bool,
     pub(crate) in_stream: bool,
     connecting: Option<Connecting>,
     /// The last host title a connect was raised for, kept past the connect itself so
@@ -352,6 +360,7 @@ impl Shell {
             hosts_gen: u64::MAX,
             device_name: opts.device_name,
             deck: opts.deck,
+            fallback_ui: opts.fallback_ui,
             in_stream: false,
             connecting: None,
             last_connect_title: None,
@@ -888,6 +897,7 @@ impl Shell {
                 platform: self.platform,
                 pads: &self.pads,
                 deck: self.deck,
+                fallback_ui: self.fallback_ui,
                 device_name: &self.device_name,
                 t: self.t0.elapsed().as_secs_f64(),
             };
@@ -951,6 +961,10 @@ impl Shell {
                     // navigation but "open this tile's menu". Without this the context menu —
                     // and with it the only way to copy a host's link — is pad-only.
                     crate::glyphs::HintKey::Up => Some(MenuEvent::Move(MenuDir::Up)),
+                    // ▼ is the same kind of hint: a direction that steers nothing, because
+                    // the only screen publishing it is the home carousel, where down means
+                    // "open Settings". A finger must be able to press what it advertises.
+                    crate::glyphs::HintKey::Down => Some(MenuEvent::Move(MenuDir::Down)),
                     _ => None,
                 };
                 if let Some(ev) = ev {
@@ -970,6 +984,7 @@ impl Shell {
                 platform: self.platform,
                 pads: &self.pads,
                 deck: self.deck,
+                fallback_ui: self.fallback_ui,
                 device_name: &self.device_name,
                 t: self.t0.elapsed().as_secs_f64(),
             };

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

@@ -172,6 +172,7 @@ impl Shell {
             platform: self.platform,
             pads: &self.pads,
             deck: self.deck,
+            fallback_ui: self.fallback_ui,
             device_name: &self.device_name,
             t,
             glyphs: self.glyphs,
@@ -331,6 +332,8 @@ struct LayerEnv<'a> {
     platform: crate::platform::Platform,
     pads: &'a [PadInfo],
     deck: bool,
+    /// See [`crate::shell::ConsoleOptions::fallback_ui`] — a screen's row set can ask.
+    fallback_ui: bool,
     device_name: &'a str,
     t: f64,
     glyphs: GlyphStyle,
@@ -365,6 +368,7 @@ impl LayerEnv<'_> {
             platform: self.platform,
             pads: self.pads,
             deck: self.deck,
+            fallback_ui: self.fallback_ui,
             device_name: self.device_name,
             t: self.t,
         };

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

@@ -402,10 +402,11 @@ fn a_replace_carries_the_screen_it_replaced() {
     assert!(matches!(s.stack.last(), Some(Screen::HostOptions(_))));
     finish_motion(&mut s);
 
-    // Walk to "Edit…" and take it. The first fixture host is paired and online and cannot
-    // wake, so its menu is [Send logs, Copy link, Edit…, Forget, Cancel] — Edit is two down.
-    // Pressed exactly rather than searched, so that reordering the menu fails HERE instead of
-    // quietly landing this test's Confirm on "Forget".
+    // Walk to "Edit…" and take it. The first fixture host is paired, saved and online and
+    // cannot wake, so its menu is [Send logs, Library, Copy link, Edit…, …] — Edit is three
+    // down. Pressed exactly rather than searched, so that reordering the menu fails HERE
+    // instead of quietly landing this test's Confirm on something destructive.
+    s.handle_menu(MenuEvent::Move(MenuDir::Down));
     s.handle_menu(MenuEvent::Move(MenuDir::Down));
     s.handle_menu(MenuEvent::Move(MenuDir::Down));
     s.handle_menu(MenuEvent::Confirm);

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

@@ -396,9 +396,16 @@ pub(crate) fn panel_highlight(canvas: &Canvas, rect: Rect, corner: f32, k: f32)
         ),
         None,
     ));
-    canvas.draw_rrect(RRect::new_rect_xy(inset, corner * k, corner * k), &p);
+    // Concentric, the same rule the halo states: pulled in by half a unit, so the radius
+    // comes in by half a unit too or the lit edge crosses the panel's own corner arc.
+    let r = ((corner - 0.5) * k).max(0.0);
+    canvas.draw_rrect(RRect::new_rect_xy(inset, r, r), &p);
 }
 
+/// How far [`focus_halo`] is grown past the card on every side, in design units. Both the
+/// rect AND the corner radius take it — see the draw there.
+const HALO_OUTSET: f32 = 4.0;
+
 /// An accent-tinted glow under the focused card — the palette-aware mark that says "this
 /// one" from across a room, where a 2 % scale difference says nothing at all. Drawn behind
 /// [`drop_shadow`], and only ever for the ONE focused tile, so it costs a single extra
@@ -439,8 +446,13 @@ pub(crate) fn focus_halo(canvas: &Canvas, rect: Rect, corner: f32, k: f32, f: f3
     // it overran the coverflow's 58 dp focused-to-neighbour gap, and since the strip paints
     // farthest-first the focused card's corona landed on top of its neighbours — which is
     // what made every card look like it was glowing.
-    let spread = rect.with_outset((4.0 * k, 4.0 * k));
-    canvas.draw_rrect(RRect::new_rect_xy(spread, corner * k, corner * k), &p);
+    let spread = rect.with_outset((HALO_OUTSET * k, HALO_OUTSET * k));
+    // Concentric: a shape grown by `d` on every side keeps its corners parallel to the
+    // original's only if its radius grows by `d` too (the two arcs then share a centre).
+    // Reusing the card's own radius left the halo squarer than the card it sits under, so
+    // it read as a misaligned outline at the four corners and a clean glow along the edges.
+    let r = (corner + HALO_OUTSET) * k;
+    canvas.draw_rrect(RRect::new_rect_xy(spread, r, r), &p);
 }
 
 pub(crate) fn drop_shadow(canvas: &Canvas, rect: Rect, corner: f32, k: f32, alpha: f32) {

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

@@ -116,11 +116,16 @@ static MANAGED_LAUNCH: std::sync::Mutex<()> = std::sync::Mutex::new(());
 /// (single-instance), so [`schedule_restore_tv_session`] can restart them when the client disconnects.
 static STOPPED_AUTOLOGIN: std::sync::Mutex<Vec<String>> = std::sync::Mutex::new(Vec::new());
 
-/// The display-manager unit we stopped for the takeover (any DM that drove a LIVE gaming session
-/// is stopped for the stream — see [`dm_plan`]), so the restore brings the box back via
+/// A display-manager unit stopped for a takeover, so the restore brings the box back via
 /// `reset-failed` + `restart` of the DM instead of a `--user start` of the gamescope unit (which
 /// cannot work on a mask-fragile flavor: without a DM login session there is no seat, so gamescope
 /// never gets DRM master — live-proven on the Nobara repro VM 2026-07-24).
+///
+/// ⚠ **Adoption-only since 0.31.0**: the takeover idles the box's autologin session
+/// ([`install_idle_dropin`]) and leaves the DM up, so nothing in this process ever writes this any
+/// more — only [`restore_takeover_on_startup`], for a takeover stranded by a host old enough to
+/// have stopped one. It is therefore NOT the marker of a live takeover; [`takeover_idled`] is.
+/// Reading it as that marker is what silently unreachable-d the in-stream switch gate in 0.31.0.
 static STOPPED_DM: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None);
 
 /// Whether this takeover runtime-masked the [`STOPPED_AUTOLOGIN`] units ([`mask_unit`]) — i.e.
@@ -136,12 +141,16 @@ static STOPPED_DM: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None
 static AUTOLOGIN_MASKED: std::sync::Mutex<bool> = std::sync::Mutex::new(false);
 
 /// mtime of the `steamos-session-select` sentinel as of the takeover — the baseline the in-stream
-/// "Switch to Desktop" detector compares against. Steam's session-select script writes
-/// `~/.config/steamos-session-select` unconditionally in its USER pass, before any of its
-/// display-manager checks — so it advances even under a DM-stop takeover, where the script's
-/// config-rewrite tail is a silent no-op (every write branch is gated on the DM *running*;
-/// diagnosed live on the Nobara repro VM 2026-07-24). An advanced mtime after a capture loss is
-/// therefore the one durable trace of the user's switch request.
+/// "Switch to Desktop" detector compares against. The ChimeraOS-layout `os-session-select`
+/// (Nobara, ChimeraOS) writes `~/.config/steamos-session-select` unconditionally in its USER pass,
+/// before any of its display-manager checks, so an advanced mtime after a capture loss is the one
+/// durable trace of the user's switch request — the switch itself leaves nothing else behind that
+/// this host can see.
+///
+/// ⚠ Bazzite/SteamOS write NO sentinel: their `os-session-select` is a thin wrapper over
+/// `steamosctl` D-Bus calls. The detector is therefore inert there by construction, which is
+/// exactly right — those platforms default the mid-stream session watcher ON
+/// ([`is_steam_htpc_platform`]) and follow the switch with it instead.
 ///
 /// Two levels of `Option`, because "no baseline" and "no sentinel" mean opposite things:
 /// * **outer `None`** — never baselined (no takeover this host lifetime). Nothing can read as an
@@ -674,21 +683,28 @@ fn create_managed_session(client: &str, mode: Mode, hdr: bool) -> Result<Virtual
     if steamos_session_present() {
         return create_managed_session_steamos(mode, hdr);
     }
-    // In-stream "Switch to Desktop" under a DM-stop takeover: the user's session-select inside
-    // the streamed game mode advanced the sentinel, but its config rewrite was a silent no-op
-    // (every write branch needs the DM running, and the takeover stopped it) — so without this,
-    // the capture loss it caused would just relaunch game mode ("thrown back in", field-tested
-    // 2026-07-24). Honor the request instead: restore the DM and replay the switch.
-    let dm_takeover = STOPPED_DM.lock().unwrap_or_else(|e| e.into_inner()).clone();
-    if let Some(dm) = dm_takeover {
-        if session_select_requested() {
-            *STOPPED_DM.lock().unwrap_or_else(|e| e.into_inner()) = None;
-            honor_session_select_switch(dm);
-            return Err(anyhow!(
-                "the user switched the box to the desktop session — display manager restored; \
-                 re-detection follows the desktop compositor as it comes up"
-            ));
-        }
+    // In-stream "Switch to Desktop": the user's session-select inside the streamed game mode
+    // advanced the sentinel, so the box is on its way to a desktop session. Without this, the
+    // capture loss that switch causes just relaunches game mode over the booting desktop — the
+    // "thrown back in" field report of 2026-07-24, and again on Nobara 2026-08-20.
+    //
+    // ⚠ Gated on the IDLED takeover, not on [`STOPPED_DM`]. Until 0.31.0 the takeover stopped the
+    // display manager, and setting that static was what armed this gate; the idled takeover
+    // replaced both the stop and the static ([`install_idle_dropin`]) and nothing re-armed the
+    // gate, so this branch became unreachable on every box. Bazzite did not notice — its
+    // `os-session-select` is a `steamosctl` D-Bus call that writes no sentinel, and its session
+    // watcher is on by default ([`is_steam_htpc_platform`]) so the stream follows the switch
+    // anyway. The ChimeraOS-layout distros are the ones that lost their handling: their
+    // `os-session-select` DOES write the sentinel, and `ID=nobara` matches no HTPC default.
+    if takeover_idled() && session_select_requested() {
+        // `take`, so an adopted DM stop is consumed exactly once — see
+        // [`honor_session_select_switch`] for why a 0.31.0 takeover has none to consume.
+        let adopted_dm = std::mem::take(&mut *STOPPED_DM.lock().unwrap_or_else(|e| e.into_inner()));
+        honor_session_select_switch(adopted_dm);
+        return Err(anyhow!(
+            "the user switched the box to the desktop session — the box's own game mode is handed \
+             back; re-detection follows the desktop compositor as it comes up"
+        ));
     }
     // Post-honor grace: while the selected desktop boots, a managed relaunch would win the race
     // (gamescope+Steam start faster than KWin) and a delivering pipeline ends the rebuild's
@@ -1349,19 +1365,34 @@ fn install_idle_dropin() -> Result<()> {
         .parent()
         .context("the idle drop-in path has no parent directory")?;
     std::fs::create_dir_all(dir).with_context(|| format!("create {}", dir.display()))?;
-    std::fs::write(
-        &path,
-        format!(
-            "[Service]\nExecStart=\nExecStart={} infinity\n",
-            sleep_binary()
-        ),
-    )
-    .with_context(|| format!("write {}", path.display()))?;
+    std::fs::write(&path, idle_dropin_body(sleep_binary()))
+        .with_context(|| format!("write {}", path.display()))?;
     systemctl_user(&["daemon-reload"]);
     *IDLE_DROPIN_ARMED.lock().unwrap_or_else(|e| e.into_inner()) = true;
     Ok(())
 }
 
+/// The idle drop-in's body (the unit-testable core of [`install_idle_dropin`]).
+///
+/// The **empty `ExecStart=` comes first and is load-bearing**: `ExecStart` is a list-valued
+/// directive, so a drop-in that only adds a line APPENDS to the box's own — which would run the
+/// real gamescope session *and* the sleep, i.e. exactly the Steam-fighting session the takeover
+/// exists to get out of the way, with no symptom pointing here. The reset is what replaces it.
+fn idle_dropin_body(sleep_bin: &str) -> String {
+    format!("[Service]\nExecStart=\nExecStart={sleep_bin} infinity\n")
+}
+
+/// Does THIS host hold the box's game mode idled right now? The successor to "did we stop the
+/// display manager" as the marker of a live managed takeover, and so what arms the in-stream
+/// switch gate in [`create_managed_session`].
+///
+/// Reads [`IDLE_DROPIN_ARMED`] — this process's own memory — deliberately, unlike
+/// [`remove_idle_dropin`]: a drop-in on disk that we did not write belongs to a dead host, and
+/// honoring a "switch" against someone else's takeover would hand back a box we never took.
+fn takeover_idled() -> bool {
+    *IDLE_DROPIN_ARMED.lock().unwrap_or_else(|e| e.into_inner())
+}
+
 /// Remove the idle drop-in so the box's own Game Mode runs for real again; reports whether one was
 /// there. Deliberately NOT gated on [`IDLE_DROPIN_ARMED`] — the flag is this process's memory, and
 /// the drop-in outliving a host that died is exactly the case that has to be swept.
@@ -2282,10 +2313,36 @@ fn switch_ends_mask_window(kind: super::ActiveKind) -> bool {
 }
 
 /// The host's mid-stream session watcher calls this on every switch it confirms; see
-/// [`switch_ends_mask_window`] for which ones actually lift the mask.
+/// [`switch_ends_mask_window`] for which ones end the takeover's hold on the box's own game mode.
+///
+/// This is the SECOND of the two ways a box can leave our takeover mid-stream — the sentinel
+/// detector in [`create_managed_session`] is the other — and both owe the box the same hand-back.
+/// The watcher is the one that covers Bazzite/SteamOS, where it is on by default
+/// ([`is_steam_htpc_platform`]) and no sentinel is ever written; the detector covers the
+/// ChimeraOS-layout distros, which are the reverse. Fixing only one leaves the other's boxes
+/// holding an idled game mode.
 pub fn release_autologin_mask(switched_to: super::ActiveKind) {
-    if switch_ends_mask_window(switched_to) {
-        lift_autologin_mask();
+    if !switch_ends_mask_window(switched_to) {
+        return;
+    }
+    lift_autologin_mask();
+    // The idle drop-in is the mask's successor and inherits its whole hazard: it replaces the
+    // box's game-mode `ExecStart` with a sleep, and a switch to a desktop is exactly where that
+    // stops being ours to hold. Left on, the user's "Return to Gaming Mode" starts a unit that
+    // only sleeps — the same barred way back this function's mask lift exists to prevent, and
+    // measured in that state on Bazzite `.41` 2026-08-20 (`ExecStart=/usr/bin/sleep infinity`
+    // still on the unit after a completed switch to KDE).
+    //
+    // Deliberately NOT a full [`clear_takeover`]: the takeover outlives this window, exactly as
+    // the mask lift's own note says. The box may come back to game mode, and the disconnect
+    // restore still owes [`STOPPED_AUTOLOGIN`] a start. All this says is "the box's own game mode
+    // runs for real again".
+    if remove_idle_dropin() {
+        tracing::info!(
+            switched_to = ?switched_to,
+            "gamescope: the box left our game session for a desktop — removed the takeover's idle \
+             drop-in so its own Game Mode runs for real again"
+        );
     }
 }
 
@@ -2754,11 +2811,12 @@ fn session_select_mtime() -> Option<std::time::SystemTime> {
 
 /// Record the sentinel baseline, so a LATER write (the user's in-stream "Switch to Desktop") is
 /// distinguishable from the switch that led into this session. Taken at **takeover** (the moment
-/// [`STOPPED_DM`] is set, which is what arms the honor gate) and again at a successful launch: the
-/// switch INTO game mode writes the sentinel on its way in, and that write must never read as a
-/// request to go back out. Baselining only at launch left the window in between — a takeover whose
-/// launch failed, then a client retry inside the restore debounce — reading a months-old sentinel
-/// as a live request and pushing the box to the desktop the user never asked for.
+/// the idle drop-in goes in, which is what arms the honor gate — see [`takeover_idled`]) and again
+/// at a successful launch: the switch INTO game mode writes the sentinel on its way in, and that
+/// write must never read as a request to go back out. Baselining only at launch left the window in
+/// between — a takeover whose launch failed, then a client retry inside the restore debounce —
+/// reading a months-old sentinel as a live request and pushing the box to the desktop the user
+/// never asked for.
 fn record_session_select_baseline() {
     *SESSION_SELECT_BASELINE
         .lock()
@@ -2801,11 +2859,11 @@ fn sentinel_advanced(
 ///
 /// The caller then refuses managed relaunches for [`SWITCH_HONOR_GRACE`] so the capture-loss
 /// re-detection follows the desktop compositor once it's up instead of racing it.
-fn honor_session_select_switch(dm: String) {
+fn honor_session_select_switch(adopted_dm: Option<String>) {
     tracing::info!(
-        %dm,
-        "gamescope: in-stream session-select detected — restoring the display manager and \
-         switching the box to the desktop session"
+        adopted_dm = ?adopted_dm,
+        "gamescope: in-stream session-select detected — handing the box's own game mode back and \
+         following the desktop session the user selected"
     );
     // Consume the takeover state up front: from here on the box is the DM's again. The mask goes
     // FIRST and while the unit list still exists — this path discards that list, and it is the only
@@ -2818,7 +2876,43 @@ fn honor_session_select_switch(dm: String) {
     clear_takeover();
     *MANAGED_SESSION.lock().unwrap_or_else(|e| e.into_inner()) = None;
     stop_session(SESSION_UNIT); // dead already (the switch shut its Steam down) — clear the unit
-    if let Err(e) = restore_display_manager(&dm) {
+                                // Give the box its own Game Mode back before anything else can ask for it. The takeover
+                                // replaced that session's `ExecStart` with a sleep ([`install_idle_dropin`]), and a switch is
+                                // the one exit that used to leave it behind: the disconnect restore sweeps it, but a switch is
+                                // not a disconnect. Without this the user's next "Return to Gaming Mode" starts a unit that
+                                // does nothing at all — measured on the Nobara VM 2026-08-20, and on glass it is
+                                // indistinguishable from broken hardware.
+    if remove_idle_dropin() {
+        tracing::info!(
+            "gamescope: removed the takeover's idle drop-in — the box's own Game Mode runs for \
+             real again"
+        );
+    }
+    // Only an ADOPTED takeover still owes a display-manager restore. 0.31.0 leaves the DM up for
+    // exactly this reason, so by the time we get here the OS's own switch has already done the
+    // whole job — config rewrite and relogin (measured end to end on the Nobara VM). A takeover
+    // inherited from a host old enough to have STOPPED the DM has not: for it the switch really
+    // was the silent no-op that every write branch of `os-session-select` becomes without a
+    // running DM, so that one still has to be replayed.
+    if let Some(dm) = adopted_dm {
+        replay_switch_under_restored_dm(&dm);
+    }
+    record_session_select_baseline();
+    *SWITCH_HONORED_AT.lock().unwrap_or_else(|e| e.into_inner()) = Some(Instant::now());
+}
+
+/// Restore a display manager an ADOPTED takeover stopped, then replay the user's switch under it —
+/// every verb live-validated on the Nobara repro VM:
+/// 1. start the DM (its autologin heads back into game mode briefly — the config still names it);
+/// 2. run the distro's own `os-session-select desktop` as the user (its internal pkexec is
+///    `allow_any`-authorized), which rewrites the DM autologin config to the desktop session;
+/// 3. stop the autologin gamescope unit — the login session exits, and `Relogin=true` relogs
+///    into the now-selected desktop.
+///
+/// Reachable only from [`honor_session_select_switch`], and only for a takeover inherited from a
+/// pre-0.31.0 host: nothing stops a display manager any more.
+fn replay_switch_under_restored_dm(dm: &str) {
+    if let Err(e) = restore_display_manager(dm) {
         tracing::warn!(
             %dm,
             reason = %e,
@@ -2831,7 +2925,7 @@ fn honor_session_select_switch(dm: String) {
         // Budgeted: this is a 10 s loop, and a single unbounded `is-active` against a system
         // manager that is itself mid-restart would consume the whole window in one tick.
         let active = crate::proc::output_within(
-            Command::new("systemctl").args(["is-active", &dm]),
+            Command::new("systemctl").args(["is-active", dm]),
             UNIT_STATE_BUDGET,
         )
         .map(|o| String::from_utf8_lossy(&o.stdout).trim() == "active")
@@ -2888,8 +2982,6 @@ fn honor_session_select_switch(dm: String) {
              session instead of switching to the desktop"
         );
     }
-    record_session_select_baseline();
-    *SWITCH_HONORED_AT.lock().unwrap_or_else(|e| e.into_inner()) = Some(Instant::now());
 }
 
 /// Stop every autologin gaming-mode session (`gamescope-session-plus@*.service`) so its
@@ -2979,6 +3071,13 @@ fn stop_autologin_sessions() -> Result<()> {
     // switch.
     if plan.dm_relogins {
         install_idle_dropin().context("idling the box's autologin game session for the stream")?;
+        // Baseline the switch sentinel HERE, not only at a successful launch: arming the idle
+        // drop-in is what arms the honor gate in [`create_managed_session`], so from this instant
+        // an unbaselined sentinel would read as an in-stream "Switch to Desktop" — including the
+        // write left by the switch that just brought the box INTO game mode. A successful launch
+        // re-baselines (tighter still). This moved here from the display-manager stop that 0.31.0
+        // retired; losing it with that stop is what left the gate unarmed.
+        record_session_select_baseline();
     }
     let units: Vec<String> = listed.into_iter().map(|(u, _)| u).collect();
     let mut stopped = Vec::new();
@@ -5233,9 +5332,10 @@ mod tests {
     use super::{
         any_output_size_is, cancel_pending_restore, cgroup_is_punktfunk_owned,
         classify_output_size, connected_connector_under, display_manager_unit_under, dm_plan,
-        game_hz, gamescope_output_size, hdr_args, is_steam_launch, mask_unit, missing_flags,
-        mode_mismatch, nested_wrapper_script, our_wsi_layer_dir, plan_bind, release_autologin_mask,
-        script_hardcodes_gamescope, sentinel_advanced, shape_dedicated_command,
+        game_hz, gamescope_output_size, hdr_args, idle_dropin_body, idle_dropin_path,
+        install_idle_dropin, is_steam_launch, mask_unit, missing_flags, mode_mismatch,
+        nested_wrapper_script, our_wsi_layer_dir, plan_bind, release_autologin_mask,
+        remove_idle_dropin, script_hardcodes_gamescope, sentinel_advanced, shape_dedicated_command,
         switch_ends_mask_window, takeover_state_is_live, unmask_unit, xwayland_refusal_marker,
         BindOff, BindPlan, BoxOutputSize, DmHelperError, SessionBind, TakeoverState, WsiPlan,
         AUTOLOGIN_MASKED, DISTRO_GAMESCOPE_PATH, PENDING_RESTORE, RESTORE_FLIGHT,
@@ -5434,6 +5534,25 @@ mod tests {
         assert!(!sentinel_advanced(Some(Some(t0)), None));
     }
 
+    /// `ExecStart` is list-valued, so the reset line is the whole mechanism: without it the
+    /// drop-in APPENDS the sleep to the box's own session command and both run — the takeover
+    /// would then be fighting the very Steam it set out to free, and nothing on the box would say
+    /// why. Pins the reset, its order, and that the resolved `sleep` is the one that gets run.
+    #[test]
+    fn idle_dropin_replaces_exec_start_rather_than_appending() {
+        let body = idle_dropin_body("/usr/bin/sleep");
+        assert_eq!(
+            body, "[Service]\nExecStart=\nExecStart=/usr/bin/sleep infinity\n",
+            "{body}"
+        );
+        let lines: Vec<&str> = body.lines().collect();
+        assert_eq!(lines[1], "ExecStart=", "the reset must come first: {body}");
+        // The path is resolved per box ([`sleep_binary`]) and must reach the unit verbatim — a
+        // bare `sleep` would depend on the unit's PATH, and an ExecStart that fails to EXECUTE is
+        // the failing unit the display manager relogin-loops against.
+        assert!(idle_dropin_body("/bin/sleep").contains("ExecStart=/bin/sleep infinity"));
+    }
+
     #[test]
     fn nested_wrapper_script_shapes() {
         let relay = std::path::Path::new("/run/user/1000/pf-ei");
@@ -5661,10 +5780,32 @@ mod tests {
         release_autologin_mask(crate::ActiveKind::None);
         assert_eq!(is_enabled(), "masked-runtime");
 
+        // The idle drop-in is the mask's successor and shares this exact window, so it has to come
+        // off with it. A takeover that leaves it on has replaced the box's game-mode `ExecStart`
+        // with a sleep — a "Return to Gaming Mode" that starts and does nothing, which is the same
+        // barred way back, measured on Bazzite `.41` 2026-08-20.
+        install_idle_dropin().expect("arm the takeover's idle drop-in");
+        assert!(idle_dropin_path().exists());
+
+        // Mid-stream, with the box still ours: the mask is doing its job and must stay. `Gaming` is
+        // what our own managed session reads as, and `None` is one momentarily down between
+        // relaunches — lifting on either would void the mask for the whole stream.
+        release_autologin_mask(crate::ActiveKind::Gaming);
+        release_autologin_mask(crate::ActiveKind::None);
+        assert_eq!(is_enabled(), "masked-runtime");
+        assert!(
+            idle_dropin_path().exists(),
+            "the idle drop-in must survive a switch that is not to a desktop"
+        );
+
         // The user switched the box to its own desktop mid-stream: the window is over, and the way
         // back into game mode has to be clear before they ask for it.
         release_autologin_mask(crate::ActiveKind::DesktopKde);
         assert_ne!(is_enabled(), "masked-runtime");
+        assert!(
+            !idle_dropin_path().exists(),
+            "the idle drop-in outlived the switch — the box's Game Mode is a sleep now"
+        );
         // The restart list SURVIVES the lift: the mask's lifetime is shorter than the takeover's,
         // and the disconnect restore still owes these units a `start`.
         assert_eq!(STOPPED_AUTOLOGIN.lock().unwrap().as_slice(), [PROBE]);
@@ -5673,6 +5814,7 @@ mod tests {
         assert_ne!(is_enabled(), "masked-runtime");
 
         unmask_unit(PROBE);
+        remove_idle_dropin();
         STOPPED_AUTOLOGIN.lock().unwrap().clear();
         *AUTOLOGIN_MASKED.lock().unwrap() = false;
     }

crates/punktfunk-core/cbindgen.toml

@@ -215,6 +215,7 @@ include = ["PunktfunkEndReason"]
 "MSG_CLOCK_PROBE" = "PUNKTFUNK_MSG_CLOCK_PROBE"
 "MSG_CURSOR_RENDER" = "PUNKTFUNK_MSG_CURSOR_RENDER"
 "MSG_CURSOR_SHAPE" = "PUNKTFUNK_MSG_CURSOR_SHAPE"
+"MSG_DELIVERY_REPORT" = "PUNKTFUNK_MSG_DELIVERY_REPORT"
 "MSG_LOSS_REPORT" = "PUNKTFUNK_MSG_LOSS_REPORT"
 "MSG_PAIR_CHALLENGE" = "PUNKTFUNK_MSG_PAIR_CHALLENGE"
 "MSG_PAIR_PROOF" = "PUNKTFUNK_MSG_PAIR_PROOF"

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

@@ -1,7 +1,9 @@
 //! `CtrlRequest` (the embedder's control-stream requests) and `Negotiated` (the handshake result).
 
 use crate::config::{CompositorPref, GamepadPref, Mode};
-use crate::quic::{ClipControl, ClipOffer, ColorInfo, LossReport, ProbeRequest, RfiRequest};
+use crate::quic::{
+    ClipControl, ClipOffer, ColorInfo, DeliveryReport, LossReport, ProbeRequest, RfiRequest,
+};
 
 /// A control-stream request the embedder makes on the open handshake stream: a mode switch or a
 /// speed test. One outbound channel carries both so the worker's `select!` has a single writer
@@ -15,6 +17,10 @@ pub(crate) enum CtrlRequest {
     /// forcing a full IDR. See [`RfiRequest`].
     Rfi(RfiRequest),
     Loss(LossReport),
+    /// How many data-plane packets have reached us all session — sent straight after every
+    /// [`CtrlRequest::Loss`], because `loss_ppm` is ambiguous at zero (no loss and no packets look
+    /// identical) and only this separates them. See [`DeliveryReport`].
+    Delivery(DeliveryReport),
     /// Adaptive bitrate: ask the host to re-target its encoder (kbps). Sent by the pump's
     /// [`BitrateController`] when the user's bitrate setting is Automatic.
     SetBitrate(u32),

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

@@ -57,6 +57,21 @@ pub(crate) const FLUSH_AFTER: Duration = Duration::from_millis(250);
 /// the number, so the two can never drift apart.
 pub const FLUSH_COOLDOWN: Duration = Duration::from_secs(2);
 
+/// Spacing of a client's keyframe re-asks while it has received **no video at all** — the other
+/// reason a client asks on a perfectly fixed cadence, and the OPPOSITE fault to [`FLUSH_COOLDOWN`]'s
+/// (nothing arriving, versus more arriving than it can drain).
+///
+/// **Public, and deliberately a different value, for the same reason [`FLUSH_COOLDOWN`] is public.**
+/// While both were 2000 ms the host's recovery-cadence detector could not tell which failure it was
+/// looking at, and reported the confident wrong one: a 2026-08-20 field case where not one byte of
+/// video ever reached the client was diagnosed for days as a client too slow to keep up. Embedders
+/// own the no-video timer (it lives in each decode loop), so this is the value they must use — a
+/// local copy is exactly the drift that made the two indistinguishable in the first place.
+///
+/// The delivery count on [`crate::quic::LossReport`] settles it outright for clients new enough to
+/// send one; this keeps the period itself informative for those that are not.
+pub const NO_VIDEO_RETRY: Duration = Duration::from_millis(2600);
+
 /// A clock-triggered jump-to-live that discarded fewer datagrams than this (and no queued AUs)
 /// found NO local backlog: the frames read as late, but nothing here was actually behind. Two
 /// causes, and flushing helps neither: a **wall-clock step** (NTP mid-session on either end)

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

@@ -42,7 +42,7 @@ mod recovery;
 mod rumble;
 mod worker;
 
-pub use self::frame_channel::FLUSH_COOLDOWN;
+pub use self::frame_channel::{FLUSH_COOLDOWN, NO_VIDEO_RETRY};
 pub use self::planes::AudioPacket;
 pub use self::probe::ProbeOutcome;
 pub use self::rumble::{ActuatorQuirks, RumbleCommand};

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

@@ -11,9 +11,9 @@ use crate::abr::BitrateController;
 use crate::config::Role;
 use crate::packet::FLAG_PROBE;
 use crate::quic::{
-    io, wall_clock_ns, window_loss_ppm, BitrateChanged, ClipState, ClockEcho, ClockResync, Hello,
-    LossReport, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe, ResyncAdmit, ResyncGuard,
-    ResyncStep, SetBitrate, Start, Welcome,
+    io, wall_clock_ns, window_loss_ppm, BitrateChanged, ClipState, ClockEcho, ClockResync,
+    DeliveryReport, Hello, LossReport, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe,
+    ResyncAdmit, ResyncGuard, ResyncStep, SetBitrate, Start, Welcome,
 };
 use crate::session::Session;
 use crate::transport::UdpTransport;

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

@@ -107,6 +107,7 @@ impl ControlTask {
                         }
                         CtrlRequest::Rfi(r) => r.encode(),
                         CtrlRequest::Loss(r) => r.encode(),
+                        CtrlRequest::Delivery(r) => r.encode(),
                         CtrlRequest::SetBitrate(k) => SetBitrate { bitrate_kbps: k }.encode(),
                         CtrlRequest::ClockResync => {
                             if clock_rtt_ns.is_none() {

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

@@ -77,6 +77,12 @@ impl DataPump {
                                           // size FEC to the link. Suppressed during a speed test (its FLAG_PROBE filler would skew it).
         const ADAPT_REPORT_INTERVAL: Duration = Duration::from_millis(750);
         let mut last_report = Instant::now();
+        // Has the host been told, once, that data-plane packets are reaching us? See the send site:
+        // the delivery count is reported every window while it is ZERO (the state the host acts on)
+        // and once more when the first packets land, then never again. A host that predates the
+        // message logs "unknown control message" for each one, so a healthy session must not stream
+        // them — one line per session is a fair price on an old host, eighty a minute is not.
+        let mut delivery_confirmed = false;
         let (
             mut last_recovered,
             mut last_late,
@@ -415,6 +421,27 @@ impl DataPump {
                     );
                 } else {
                     let _ = ctrl_tx.try_send(CtrlRequest::Loss(LossReport { loss_ppm }));
+                    // Rides with the loss report — it is what makes `loss_ppm = 0` readable at the
+                    // host, which cannot otherwise tell a flawless link from one delivering
+                    // nothing. The session TOTAL, not this window's, so one message stands on its
+                    // own. Deliberately inside the same arm: a discarded window is discarded
+                    // because the host was rebuilding or a probe distorted it, and staying silent
+                    // there keeps that contract exact. Nothing is lost — the state this reports
+                    // (no packets at all) produces no discards, so its windows always send.
+                    //
+                    // Sent every window while the count is ZERO, then ONCE when the first packets
+                    // land (so the host stops guessing and can name the other failure confidently),
+                    // then never again: a healthy session must not stream a message that older
+                    // hosts log as unknown on every arrival.
+                    // ponytail: only start-of-session death is covered. A path that dies MID-stream
+                    // leaves the count frozen above zero and silent, which the host still reads as
+                    // healthy — detecting that needs a stalled-counter check with its own timing,
+                    // worth adding if a mid-session case is ever reported.
+                    if should_report_delivery(st.packets_received, &mut delivery_confirmed) {
+                        let _ = ctrl_tx.try_send(CtrlRequest::Delivery(DeliveryReport {
+                            packets_received: st.packets_received,
+                        }));
+                    }
                 }
                 // Standing-latency bleed: close the detector's window with this report's loss
                 // verdict and run its escalation ladder — re-sync first (free; a stale offset
@@ -757,10 +784,58 @@ fn take_pipeline_gap(slot: &AtomicU32) -> Option<u32> {
     }
 }
 
+/// Does this report window owe the host a [`DeliveryReport`], and record that it has been told?
+///
+/// Every window while `packets_received` is ZERO — that is the state the host escalates on, and it
+/// must keep hearing it — then exactly ONCE more when the first packets land, so the host learns
+/// delivery works and can stop hedging its stall diagnosis. Silent after that: a host that predates
+/// the message logs every unknown control message, and a healthy hours-long session must not fill
+/// its log with them.
+fn should_report_delivery(packets_received: u64, confirmed: &mut bool) -> bool {
+    let owed = packets_received == 0 || !*confirmed;
+    *confirmed = packets_received > 0;
+    owed
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    /// The host must keep hearing "zero" for as long as it is true (that is the black-screen
+    /// signal), get exactly one confirmation when video starts, and then silence — the noise budget
+    /// on an older host, which warns per unknown message, is what pays for the first two.
+    #[test]
+    fn the_delivery_count_is_reported_while_zero_then_once_more_and_never_again() {
+        let mut confirmed = false;
+        // Nothing arriving: reported every window, for as long as it stays true.
+        for _ in 0..5 {
+            assert!(
+                should_report_delivery(0, &mut confirmed),
+                "a dead data plane must be re-reported every window"
+            );
+        }
+        // First packets land: one confirmation, so the host can name the other failure confidently.
+        assert!(should_report_delivery(500, &mut confirmed));
+        // Healthy from here: silent.
+        for n in [900, 1_200, 90_000] {
+            assert!(
+                !should_report_delivery(n, &mut confirmed),
+                "a healthy session must not stream delivery reports"
+            );
+        }
+    }
+
+    /// A session that never receives anything must never look confirmed, no matter how long it runs
+    /// — the whole point is that the host keeps being told.
+    #[test]
+    fn a_session_that_receives_nothing_never_reports_itself_healthy() {
+        let mut confirmed = false;
+        for _ in 0..100 {
+            assert!(should_report_delivery(0, &mut confirmed));
+            assert!(!confirmed);
+        }
+    }
+
     #[test]
     fn a_pipeline_gap_is_taken_exactly_once() {
         let slot = AtomicU32::new(0);
@@ -935,8 +1010,8 @@ mod tests {
             .expect("the window after the gap reports on schedule");
         assert!(
             matches!(reported, Some(CtrlRequest::Loss(_))),
-            "the window after the gap must produce a loss report — an idle session's only \
-             outbound request"
+            "the window after the gap must produce a loss report — the first of the two requests \
+             an idle session makes (the delivery count follows it)"
         );
         assert!(
             started.elapsed() >= Duration::from_millis(1_400),

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

@@ -97,6 +97,33 @@ pub struct LossReport {
     pub loss_ppm: u32,
 }
 
+/// `client → host`, sent immediately after each [`LossReport`]: data-plane packets this client has
+/// received all session, cumulative.
+///
+/// ⚠ Exists because `loss_ppm` alone is **ambiguous at zero**: a client receiving a flawless stream
+/// and a client receiving *nothing at all* both report `loss_ppm = 0` — loss is a ratio over a
+/// window whose denominator is the packets that arrived, so no-packets is indistinguishable from
+/// no-loss. That ambiguity let a host decay adaptive FEC to its floor while the client sat behind a
+/// black screen having received zero bytes, and the host's own stall diagnosis blamed the client for
+/// "not sustaining the stream" it had never been sent (field 2026-08-20: a Windows host whose
+/// per-session data port was closed inbound, so the client's hole-punch never opened the return
+/// path). `0` while the host has sent frames is the one unambiguous statement of "the video data
+/// plane is not reaching me" — the control plane carrying this report is, by construction, healthy.
+///
+/// ⚠ A SEPARATE MESSAGE rather than a field appended to [`LossReport`], and that is load-bearing:
+/// `LossReport::decode` length-checks EXACTLY, so a longer report is rejected outright by every host
+/// already shipped — a new client would silently lose adaptive FEC against them. Mixed versions are
+/// normal here (the field case that motivated this ran a current host against a months-old client),
+/// so the compatible shape is a new type byte an older host simply ignores, exactly as it already
+/// ignores every other control message it predates.
+///
+/// Cumulative, not per-window, so a single message is self-contained; `u64` to match the counter it
+/// mirrors, with no saturation to reason about.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct DeliveryReport {
+    pub packets_received: u64,
+}
+
 /// `client → host`, any time after [`Start`]: reconfigure the encoder to a new target bitrate
 /// without reconnecting — the mid-stream lever of adaptive bitrate. The host clamps the request
 /// exactly like [`Hello::bitrate_kbps`] (its `[MIN, MAX]` band; `0` → host default), answers with
@@ -270,6 +297,8 @@ pub const MSG_SHARD_PAYLOAD_ACK: u8 = 0x09;
 /// and [`BitrateChanged`] already feed. Deliberately NOT in the 0x30 clock block — it carries a
 /// duration precisely so that no clock domain is involved.
 pub const MSG_PIPELINE_GAP: u8 = 0x0A;
+/// Type byte of [`DeliveryReport`].
+pub const MSG_DELIVERY_REPORT: u8 = 0x0B;
 /// Type byte of [`ProbeRequest`].
 pub const MSG_PROBE_REQUEST: u8 = 0x20;
 /// Type byte of [`ProbeResult`].
@@ -436,6 +465,26 @@ impl LossReport {
     }
 }
 
+impl DeliveryReport {
+    pub fn encode(&self) -> Vec<u8> {
+        // magic[0..4] type[4] packets_received[5..13]
+        let mut b = Vec::with_capacity(13);
+        b.extend_from_slice(CTL_MAGIC);
+        b.push(MSG_DELIVERY_REPORT);
+        b.extend_from_slice(&self.packets_received.to_le_bytes());
+        b
+    }
+
+    pub fn decode(b: &[u8]) -> Result<DeliveryReport> {
+        if b.len() != 13 || &b[0..4] != CTL_MAGIC || b[4] != MSG_DELIVERY_REPORT {
+            return Err(PunktfunkError::InvalidArg("bad DeliveryReport"));
+        }
+        Ok(DeliveryReport {
+            packets_received: u64::from_le_bytes(b[5..13].try_into().unwrap()),
+        })
+    }
+}
+
 impl SetBitrate {
     pub fn encode(&self) -> Vec<u8> {
         // magic[0..4] type[4] bitrate_kbps[5..9]
@@ -1291,6 +1340,41 @@ mod tests {
         .is_err());
     }
 
+    #[test]
+    fn delivery_report_roundtrip() {
+        for packets_received in [0u64, 1, 9_999, u32::MAX as u64 + 1, u64::MAX] {
+            let r = DeliveryReport { packets_received };
+            assert_eq!(DeliveryReport::decode(&r.encode()).unwrap(), r);
+        }
+        assert!(DeliveryReport::decode(&RequestKeyframe.encode()).is_err());
+        assert!(DeliveryReport::decode(&LossReport { loss_ppm: 0 }.encode()).is_err());
+    }
+
+    /// The delivery count MUST NOT ride on [`LossReport`]: that message is length-checked EXACTLY,
+    /// so lengthening it would make every already-shipped host reject the loss reports its adaptive
+    /// FEC runs on — a silent regression for a new client against an old host, which is the normal
+    /// mixed-version case here (the field report that motivated this ran a current host against a
+    /// months-old client). Its own type byte keeps `LossReport` byte-identical while an older host
+    /// simply ignores the message it does not know.
+    #[test]
+    fn the_delivery_count_does_not_disturb_the_loss_report_wire_form() {
+        let loss = LossReport { loss_ppm: 42 }.encode();
+        assert_eq!(loss.len(), 9, "LossReport must stay the 9-byte wire form");
+        assert_eq!(loss[4], MSG_LOSS_REPORT);
+
+        let delivery = DeliveryReport {
+            packets_received: 0,
+        }
+        .encode();
+        assert_ne!(
+            delivery[4], MSG_LOSS_REPORT,
+            "a distinct type byte is what makes an old host ignore it instead of failing"
+        );
+        // Neither can be silently mis-parsed as the other.
+        assert!(LossReport::decode(&delivery).is_err());
+        assert!(DeliveryReport::decode(&loss).is_err());
+    }
+
     #[test]
     fn window_loss_ppm_estimates_and_caps() {
         // No traffic → 0. A clean window (nothing recovered) → 0.

crates/punktfunk-host/src/gamelease.rs

@@ -114,9 +114,18 @@ pub enum LeaseKind {
     Child,
     /// A launcher owns the game; it is recognized by its [`DetectSpec`].
     Matched,
-    /// Nothing identifies this title's process — no detect signals and no child we own. Both
-    /// lifetime behaviors stay inert for it, and the host says so once in the log rather than
-    /// guessing.
+    /// A launcher owns the game and **tells us** when it starts and stops
+    /// ([`crate::runstate`]) — no process signal of our own.
+    ///
+    /// The one lease kind whose liveness the host does not determine for itself, and the answer to
+    /// a title that has nothing to scan for: Playnite launches an emulated or manually-added game
+    /// through its own tracking and reports the edges, where the host could see only a
+    /// `playnite://` forwarder exiting. Before this such a title was [`Untracked`](Self::Untracked)
+    /// — the honest answer at the time, and a dead end.
+    Reported,
+    /// Nothing identifies this title's process — no detect signals, no child we own, and no
+    /// provider reporting on it. Both lifetime behaviors stay inert for it, and the host says so
+    /// once in the log rather than guessing.
     Untracked,
 }
 
@@ -126,6 +135,7 @@ impl LeaseKind {
             Self::Nested => "nested",
             Self::Child => "child",
             Self::Matched => "matched",
+            Self::Reported => "reported",
             Self::Untracked => "untracked",
         }
     }
@@ -387,6 +397,12 @@ pub fn open(req: LeaseRequest, on_exit: OnExit) -> GameLease {
         LeaseKind::Child
     } else if !spec.is_empty() {
         LeaseKind::Matched
+    } else if crate::runstate::speaks_for(game.id.as_deref()) {
+        // Nothing to scan for, but the provider that published this title is reporting liveness for
+        // it — so it is tracked after all. Asked once, here, rather than every poll: a lease's kind
+        // is what decides whether it is watched at all, and a title that flipped kind mid-flight
+        // would make both lifetime behaviors depend on a plugin's uptime.
+        LeaseKind::Reported
     } else {
         LeaseKind::Untracked
     };
@@ -551,6 +567,27 @@ fn watch(
         s.is_some_and(|p| !scanner.alive(&[p]).is_empty())
     };
 
+    // What this title's provider says about it, when one reports at all ([`crate::runstate`]) —
+    // `None` on every host with no reporting plugin, which is what keeps all of this inert until
+    // someone opts in. Re-read each poll rather than captured: the whole value of it is that it
+    // changes while the lease is alive.
+    let reported = || shared.game.id.as_deref().and_then(crate::runstate::opinion);
+
+    // What a `Child` lease falls back to once its child turns out to be a shim: the store's own
+    // signals, else the provider's reporting, else nothing. The same ladder [`open`] walks, minus
+    // the child that has just gone away — and the reason a hint-less Playnite title is tracked at
+    // all on Windows, where the launch is `explorer.exe "playnite://…"` and therefore ALWAYS a
+    // hand-off, so every such lease arrives here.
+    let fallback_kind = || {
+        if !shared.spec.is_empty() {
+            LeaseKind::Matched
+        } else if crate::runstate::speaks_for(shared.game.id.as_deref()) {
+            LeaseKind::Reported
+        } else {
+            LeaseKind::Untracked
+        }
+    };
+
     // ---- Phase 1: wait for the game to show up. ----
     let start_deadline = spawned_at + START_GRACE;
     loop {
@@ -567,8 +604,10 @@ fn watch(
             && !spawned_up(&spawned)
         {
             spawned = None;
-            if spawned_at.elapsed() < SHIM_WINDOW {
-                if shared.spec.is_empty() {
+            let quick = spawned_at.elapsed() < SHIM_WINDOW;
+            kind = fallback_kind();
+            if quick {
+                if matches!(kind, LeaseKind::Untracked) {
                     tracing::info!(
                         title = %shared.game.title,
                         "the launch command exited immediately (a launcher handing off) and this \
@@ -582,11 +621,10 @@ fn watch(
                 }
                 tracing::debug!(
                     title = %shared.game.title,
-                    "the launch command handed off and exited — recognizing the game by its store \
-                     signals instead"
+                    kind = kind.as_str(),
+                    "the launch command handed off and exited — recognizing the game another way"
                 );
-                kind = LeaseKind::Matched;
-            } else if shared.spec.is_empty() {
+            } else if matches!(kind, LeaseKind::Untracked) {
                 // It ran long enough to have BEEN the game, and nothing else identifies it.
                 shared.was_running.store(true, Ordering::Relaxed);
                 finish(&shared, &on_exit, "the launched process exited");
@@ -604,31 +642,30 @@ fn watch(
                     shared.forget_child();
                     if quick && status.success() {
                         // A launcher that handed the game off and exited. Fall back to recognizing
-                        // the game by its store's signals; with none, stop tracking entirely rather
-                        // than pretend the shim's exit was the game's.
-                        kind = if shared.spec.is_empty() {
+                        // the game by its store's signals (or its provider's reporting); with
+                        // neither, stop tracking entirely rather than pretend the shim's exit was
+                        // the game's.
+                        kind = fallback_kind();
+                        if matches!(kind, LeaseKind::Untracked) {
                             tracing::info!(
                                 title = %shared.game.title,
                                 "the launch command exited immediately (a launcher handing off) and \
                                  this title has no detect signals — stopping game tracking for it"
                             );
-                            LeaseKind::Untracked
-                        } else {
-                            tracing::debug!(
-                                title = %shared.game.title,
-                                "the launch command handed off and exited — recognizing the game by \
-                                 its store signals instead"
-                            );
-                            LeaseKind::Matched
-                        };
-                        if matches!(kind, LeaseKind::Untracked) {
                             shared.set_state(GameState::Untracked);
                             return;
                         }
+                        tracing::debug!(
+                            title = %shared.game.title,
+                            kind = kind.as_str(),
+                            "the launch command handed off and exited — recognizing the game \
+                             another way"
+                        );
                     } else {
                         // It ran long enough to have BEEN the game (or failed outright). Either way
                         // the game is gone; only a success after a real run counts as "played".
-                        if shared.spec.is_empty() {
+                        kind = fallback_kind();
+                        if matches!(kind, LeaseKind::Untracked) {
                             if spawned_at.elapsed() >= SHIM_WINDOW {
                                 shared.was_running.store(true, Ordering::Relaxed);
                                 finish(&shared, &on_exit, "the launched process exited");
@@ -642,11 +679,7 @@ fn watch(
                 Some(Err(e)) => {
                     tracing::debug!(error = %e, "could not poll the launched child — falling back to scanning");
                     child = None;
-                    kind = if shared.spec.is_empty() {
-                        LeaseKind::Untracked
-                    } else {
-                        LeaseKind::Matched
-                    };
+                    kind = fallback_kind();
                     if matches!(kind, LeaseKind::Untracked) {
                         shared.set_state(GameState::Untracked);
                         return;
@@ -680,7 +713,12 @@ fn watch(
             && (child.is_some() || spawned.is_some())
             && spawned_at.elapsed() >= SHIM_WINDOW;
         let live = scanner.find(&shared.spec, shared.launch_stamp);
-        if !live.is_empty() || child_alive {
+        // A provider saying so is as good as seeing it — better, for a title there is nothing to
+        // see: it is the launcher that started the game telling us it did. This is the only way a
+        // [`LeaseKind::Reported`] lease ever leaves this phase, and for a `Matched` one it just
+        // gets there sooner than the scan would.
+        let said_running = reported().is_some_and(|l| l.running);
+        if !live.is_empty() || child_alive || said_running {
             known = live.clone();
             publish(&live);
             shared.was_running.store(true, Ordering::Relaxed);
@@ -754,6 +792,27 @@ fn watch(
             gone_since = None;
             vetoed = false;
             shared.last_seen_ms.store(now_ms(), Ordering::Relaxed);
+        } else if let Some(said) = reported() {
+            // Nothing of the game is visible to us, but its provider is still reporting on it — and
+            // that report is decisive in BOTH directions, where `running_hint` below may only ever
+            // delay an exit.
+            //
+            // The difference is what backs each claim. Steam's registry flag is a leftover that
+            // survives an unclean exit, so believing it indefinitely produces a session that never
+            // ends; a provider report is an event from the launcher that started the game, restated
+            // continuously, and it stops counting the moment it goes stale
+            // ([`crate::runstate::REPORT_TTL`]) — after which this branch simply stops being taken
+            // and the scan-only path below resumes. So a *live* provider is allowed to hold the
+            // session open for a game the host cannot see at all, which is the entire point for a
+            // title with no detect signals, and a dead one costs at most one TTL.
+            if said.running {
+                gone_since = None;
+                vetoed = false;
+                shared.last_seen_ms.store(now_ms(), Ordering::Relaxed);
+            } else {
+                finish(&shared, &on_exit, "its provider reported the game stopped");
+                return;
+            }
         } else {
             // How long the game's processes have been CONTINUOUSLY absent. Deliberately not reset by
             // the veto below — letting it run on is exactly what bounds the veto.
@@ -909,7 +968,7 @@ fn terminate_blocking(shared: &LeaseShared) {
                 "released the nested session's kept display to end its game"
             );
         }
-        LeaseKind::Child | LeaseKind::Matched => {
+        LeaseKind::Child | LeaseKind::Matched | LeaseKind::Reported => {
             #[cfg(target_os = "linux")]
             unix_term_ladder(shared);
             #[cfg(windows)]
@@ -919,6 +978,26 @@ fn terminate_blocking(shared: &LeaseShared) {
     }
 }
 
+/// The process this lease's provider reports for its game, re-resolved and pinned to its start
+/// time, or `None`.
+///
+/// The reason the wire carries a pid at all: for a [`LeaseKind::Reported`] title the matcher finds
+/// nothing by construction, so without this "End" would have no target and would silently do
+/// nothing — the exact failure a spawned pid was folded into the Windows ladder to fix. Resolved at
+/// the moment of use rather than stored on the lease, so a report that has since gone stale, or a
+/// pid the kernel has since recycled, contributes nothing.
+#[cfg(any(target_os = "linux", windows))]
+fn reported_proc(shared: &LeaseShared) -> Option<crate::procscan::ProcRef> {
+    let pid = shared
+        .game
+        .id
+        .as_deref()
+        .and_then(crate::runstate::opinion)
+        .filter(|l| l.running)?
+        .pid?;
+    crate::procscan::resolve(pid)
+}
+
 /// SIGTERM everything that belongs to the game, wait, then SIGKILL whatever ignored it.
 ///
 /// Every pid is re-verified against its recorded start time immediately before each signal, so a pid
@@ -942,11 +1021,22 @@ fn unix_term_ladder(shared: &LeaseShared) {
         // `OwnedChild::group_leader`) — never for a child sharing the host's own group.
         unsafe { libc::kill(target, sig) == 0 }
     };
+    // Everything the matcher can find, plus the pid the provider reported (see `reported_proc`) —
+    // which for a `Reported` lease is the only member of this set.
+    let targets = || {
+        let mut procs = scanner.find(&shared.spec, shared.launch_stamp);
+        if let Some(p) = reported_proc(shared) {
+            if !procs.iter().any(|q| q.pid == p.pid) {
+                procs.push(p);
+            }
+        }
+        procs
+    };
     let signal_matched = |sig: i32| -> usize {
         // Re-scan and re-verify immediately before signalling, so a pid recycled since the last
         // sweep is never hit.
         scanner
-            .alive(&scanner.find(&shared.spec, shared.launch_stamp))
+            .alive(&targets())
             .into_iter()
             // SAFETY: as above, for a single pid just re-verified to be the process we adopted.
             .filter(|p| unsafe { libc::kill(p.pid as i32, sig) == 0 })
@@ -965,9 +1055,7 @@ fn unix_term_ladder(shared: &LeaseShared) {
     let deadline = Instant::now() + TERM_GRACE;
     while Instant::now() < deadline {
         std::thread::sleep(POLL);
-        let still = scanner
-            .alive(&scanner.find(&shared.spec, shared.launch_stamp))
-            .len();
+        let still = scanner.alive(&targets()).len();
         // Signal 0 only probes for existence — the child (or its group) is gone once it fails.
         let child_gone = !signal_child(0);
         if still == 0 && child_gone {
@@ -1000,11 +1088,19 @@ fn windows_term_ladder(shared: &LeaseShared) {
     let live = || {
         let mut procs = scanner.alive(&scanner.find(&shared.spec, shared.launch_stamp));
         // Re-verified like everything else, so a dead or recycled pid contributes nothing, and
-        // de-duplicated: the matcher may well have found this same process by its image.
-        if let Some(p) = shared.spawned {
+        // de-duplicated: the matcher may well have found this same process by its image. The
+        // provider's reported pid joins on the same terms, and for a `Reported` lease it is the
+        // only thing here (see `reported_proc`).
+        let mut fold = |p: crate::procscan::ProcRef| {
             if !scanner.alive(&[p]).is_empty() && !procs.iter().any(|q| q.pid == p.pid) {
                 procs.push(p);
             }
+        };
+        if let Some(p) = shared.spawned {
+            fold(p);
+        }
+        if let Some(p) = reported_proc(shared) {
+            fold(p);
         }
         procs
     };
@@ -1570,6 +1666,54 @@ mod tests {
         assert!(!l.shared().is_trackable());
     }
 
+    /// A title with nothing to scan for is tracked after all when its provider reports on it.
+    ///
+    /// This is the Playnite case the static `detect` hints could never reach: an emulated game, a
+    /// manually added one, a library plugin that records no install directory. The launch is a
+    /// `playnite://` hand-off, so the host holds nothing; the spec is empty, so the matcher finds
+    /// nothing; and the honest verdict used to be [`LeaseKind::Untracked`] — no exit detection, and
+    /// `POST /game/end` with nothing to aim at. Playnite knew the whole time.
+    #[test]
+    fn a_reported_title_is_tracked_where_it_used_to_be_untracked() {
+        // The same request with no provider reporting: unchanged, and the control for what follows.
+        let l = open(
+            req("playnite:lease-test", DetectSpec::default(), false),
+            Box::new(|| {}),
+        );
+        assert!(matches!(l.shared().kind(), LeaseKind::Untracked));
+        assert!(!l.shared().is_trackable());
+        drop(l);
+
+        // A provider that speaks for the title — while reporting it NOT running, which is exactly
+        // what a report looks like at the moment a game is launched. Trackability follows from the
+        // provider *reporting*, not from what it currently says; a lease whose kind flipped with
+        // the answer would make both lifetime behaviours depend on a plugin's timing.
+        crate::runstate::report(
+            "playnite-lease-test",
+            ["playnite:lease-test".to_string()].into_iter().collect(),
+            std::collections::HashMap::new(),
+        );
+        let l = open(
+            req("playnite:lease-test", DetectSpec::default(), false),
+            Box::new(|| {}),
+        );
+        assert!(matches!(l.shared().kind(), LeaseKind::Reported));
+        assert!(
+            l.shared().is_trackable(),
+            "so its exit is noticed and `POST /game/end` has a target"
+        );
+        drop(l);
+        crate::runstate::forget("playnite-lease-test");
+
+        // …and once the provider is gone, so is the tracking. Pinned because a report that outlived
+        // its plugin is the one way this could hold a session open forever.
+        let l = open(
+            req("playnite:lease-test", DetectSpec::default(), false),
+            Box::new(|| {}),
+        );
+        assert!(matches!(l.shared().kind(), LeaseKind::Untracked));
+    }
+
     #[test]
     fn an_untracked_lease_is_never_terminated() {
         let l = open(

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

@@ -30,7 +30,7 @@
 use super::{AppState, CONTROL_PORT};
 use crate::inject::gamepad::GamepadManager;
 use anyhow::{anyhow, Context, Result};
-use punktfunk_core::input::InputEvent;
+use punktfunk_core::input::{GamepadEvent, InputEvent};
 use punktfunk_core::quic::{classify, GrantClass, HdrMeta, GRANT_ALL};
 use rusty_enet::{Event, Host, HostSettings, Packet, PeerID};
 use std::net::UdpSocket;
@@ -229,6 +229,65 @@ fn permitted(mask: u32, class: GrantClass, drops: &mut GrantDrops) -> bool {
     false
 }
 
+/// The virtual Xbox pad a Moonlight session presents, and the one place this plane decides which
+/// backend builds it.
+///
+/// On Windows there are two, and they are not interchangeable to a game: the XUSB companion
+/// registers only `GUID_DEVINTERFACE_XUSB` and exposes no HID collection, so Steam's hidapi
+/// enumeration, SDL, RawInput, DirectInput, `joy.cpl` and WGI/GameInput cannot see it at all —
+/// only classic `XInputGetState` can. The native plane made the HID pad its default on
+/// 2026-08-09 for exactly that reason; this plane kept constructing
+/// [`GamepadManager`](crate::inject::gamepad::GamepadManager) directly and so kept handing
+/// Moonlight clients a pad most games cannot enumerate. Both planes now read the same knob —
+/// `native::gamepad::windows_xbox_hid` (not an intra-doc link: it is `cfg(windows)`, so the link
+/// would not resolve on any other target) — so `PUNKTFUNK_XBOX_BACKEND=xusb` reverts both
+/// together and neither can drift again.
+///
+/// Everywhere else the choice does not exist: Linux has one uinput X-Box pad, and the stub
+/// backend on other platforms drops events.
+enum SessionPads {
+    /// Linux uinput / the Windows XUSB companion — `crate::inject::gamepad`.
+    Xusb(GamepadManager),
+    /// The Windows UMDF HID Xbox pad, what the native plane builds by default.
+    #[cfg(target_os = "windows")]
+    Hid(crate::inject::xbox_windows::XboxWindowsManager),
+}
+
+impl SessionPads {
+    /// Build this session's pad manager, honoring the shared Windows backend knob.
+    fn new() -> SessionPads {
+        #[cfg(target_os = "windows")]
+        if crate::native::gamepad::windows_xbox_hid() {
+            return SessionPads::Hid(crate::inject::xbox_windows::XboxWindowsManager::new());
+        }
+        SessionPads::Xusb(GamepadManager::new())
+    }
+
+    /// Apply one decoded controller event (create/destroy by mask, then state).
+    fn handle(&mut self, ev: &GamepadEvent) {
+        match self {
+            SessionPads::Xusb(m) => m.handle(ev),
+            #[cfg(target_os = "windows")]
+            SessionPads::Hid(m) => m.handle(ev),
+        }
+    }
+
+    /// Service the pads' feedback protocol and relay changed rumble levels. Games block inside the
+    /// kernel/driver handshake until answered, so call this every tick.
+    ///
+    /// The HID pad's rich-feedback plane is discarded rather than plumbed: an Xbox pad has no
+    /// lightbar or adaptive triggers to report, and GameStream has no vocabulary for one either —
+    /// its rumble message (`0x010B`, [`super::gamepad::rumble_plaintext`]) carries the two handle
+    /// motors and nothing else, which is also why the trigger levels are dropped at the call site.
+    fn pump_rumble(&mut self, rumble: impl FnMut(u16, u16, u16, u16, u16)) {
+        match self {
+            SessionPads::Xusb(m) => m.pump_rumble(rumble),
+            #[cfg(target_os = "windows")]
+            SessionPads::Hid(m) => m.pump(rumble, |_| {}),
+        }
+    }
+}
+
 /// Reconcile the control port to the paired-client list: bound while at least one pairing
 /// exists, closed when none remain. Idempotent and race-free (see [`Gate::running`]); call it
 /// wherever the paired list changes — startup, pairing phase 4, unpair.
@@ -362,7 +421,7 @@ fn spawn(state: Arc<AppState>) -> Result<Running> {
             // by every outbound message (rumble + the HDR-mode signal): the GCM nonce is derived
             // from `seq`, so a per-message-type counter would reuse (key, nonce) pairs across
             // message types in the host direction.
-            let mut pads = GamepadManager::new();
+            let mut pads = SessionPads::new();
             // Pen/touch translator (SS_PEN/SS_TOUCH → virtual tablet / wire touch). Sent only
             // by clients that saw our SS_FF_PEN_TOUCH_EVENTS feature flag (rtsp.rs).
             let mut pointer = super::pen::GsPointer::new();
@@ -480,7 +539,7 @@ fn spawn(state: Arc<AppState>) -> Result<Running> {
                                 hdr_sent = false;
                                 // Unplug the session's virtual pads + tablet (destroying the
                                 // uinput pen releases any held tool/tip kernel-side).
-                                pads = GamepadManager::new();
+                                pads = SessionPads::new();
                                 pointer = super::pen::GsPointer::new();
                                 // Surface the session's enforcement-drop totals (WP13).
                                 drops.end_of_session();
@@ -583,7 +642,7 @@ fn spawn(state: Arc<AppState>) -> Result<Running> {
                         detected = None;
                         decrypt_fails = 0;
                         hdr_sent = false;
-                        pads = GamepadManager::new();
+                        pads = SessionPads::new();
                         pointer = super::pen::GsPointer::new();
                         drops.end_of_session();
                     }
@@ -689,7 +748,7 @@ fn on_receive(
     detected: &mut Option<Scheme>,
     decrypt_fails: &mut u64,
     inj_tx: &Sender<InputEvent>,
-    pads: &mut GamepadManager,
+    pads: &mut SessionPads,
     pointer: &mut super::pen::GsPointer,
     grants: u32,
     drops: &mut GrantDrops,

crates/punktfunk-host/src/main.rs

@@ -105,6 +105,9 @@ mod plugins;
 // session⇄game lifetime binding (design/session-game-lifetime.md §4). Per-OS matchers inside; on a
 // platform with neither (macOS, which has no launch path either) the module is an empty shell.
 mod procscan;
+// The live half of the same binding: what a provider PLUGIN reports about its titles' liveness,
+// where `procscan` can only look at the process table.
+mod runstate;
 mod send_pacing;
 #[cfg(target_os = "windows")]
 #[path = "windows/service.rs"]

crates/punktfunk-host/src/mgmt.rs

@@ -372,6 +372,7 @@ fn api_router_parts() -> (Router<Arc<MgmtState>>, utoipa::openapi::OpenApi) {
             library::reconcile_provider_entries,
             library::delete_provider_entries
         ))
+        .routes(routes!(library::report_provider_running))
         .routes(routes!(library::get_library_art))
         .routes(routes!(stats::stats_capture_start))
         .routes(routes!(stats::stats_capture_stop))

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

@@ -250,6 +250,10 @@ pub(crate) fn plugin_may_access(method: &Method, path: &str) -> bool {
         (&Method::DELETE, "/api/v1/library/custom/{}"),
         (&Method::PUT, "/api/v1/library/provider/{}"),
         (&Method::DELETE, "/api/v1/library/provider/{}"),
+        // Liveness reporting for a provider's OWN titles. No new authority: the host maps the
+        // report through the catalog, so a plugin can only ever speak about entries it published,
+        // and the worst a defective one can do to someone else's session is nothing at all.
+        (&Method::PUT, "/api/v1/library/provider/{}/running"),
         // Stats / telemetry.
         (&Method::POST, "/api/v1/stats/capture/start"),
         (&Method::POST, "/api/v1/stats/capture/stop"),

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

@@ -607,12 +607,130 @@ pub(crate) async fn delete_provider_entries(Path(provider): Path<String>) -> Res
             if removed > 0 {
                 tracing::info!(provider, removed, "library provider entries removed");
             }
+            // Its entries are gone, so its opinions about them are meaningless — and a lease must
+            // never be held open by a provider that no longer exists.
+            crate::runstate::forget(&provider);
             Json(ProviderRemoved { removed }).into_response()
         }
         Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
     }
 }
 
+/// One running title in a provider's liveness report.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct RunningTitle {
+    /// The provider's own stable id for the title — the same key its reconcile payload uses.
+    pub external_id: String,
+    /// The process id the provider started for it, when it knows one. Optional, and never trusted
+    /// as a bare number: the host re-resolves it and pins it to its start time before it is ever
+    /// signalled, so a stale or recycled pid simply contributes nothing.
+    #[serde(default)]
+    pub pid: Option<u32>,
+}
+
+/// Request body for `reportProviderRunning`.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct ProviderRunningInput {
+    /// Every title of this provider's that is running **right now**. The full set, not a delta:
+    /// anything absent from it is reported as stopped.
+    #[serde(default)]
+    pub running: Vec<RunningTitle>,
+}
+
+/// The result of a liveness report.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct ProviderRunningAccepted {
+    /// How many reported titles matched an entry this provider currently publishes.
+    matched: usize,
+    /// How many were ignored because no such entry exists (a report that raced a reconcile).
+    unknown: usize,
+    /// Seconds this report stays authoritative without being restated — re-report inside it while
+    /// anything is running.
+    ttl_s: u64,
+}
+
+/// Report which of a provider's titles are running
+///
+/// The **live** counterpart to the `detect` hints in a reconcile payload: that one says *how to
+/// recognize* a title's process, this one says *it is running now* (design §9,
+/// [`crate::runstate`]). For a provider that starts games itself and knows when they stop —
+/// Playnite tracks every launch and fires an event on both edges — this is a fact the host would
+/// otherwise have to re-derive by scanning, and for a title with nothing to scan for (an emulated
+/// game, a manually added one) could not derive at all.
+///
+/// Declarative and idempotent, like the reconcile: the body is the provider's **complete** running
+/// set, so a missed event, a plugin restart or an install mid-game all self-correct on the next
+/// report rather than drifting.
+///
+/// The report **expires** after `ttl_s` (90s) unless restated, which is what makes it safe for a
+/// live provider to keep a streaming session open for a game the host cannot see: a plugin that
+/// dies with a game running stops counting shortly after, and the host falls back to process
+/// scanning exactly as it does without one. Re-report on every change **and** on a timer well
+/// inside the window.
+///
+/// Titles the provider does not currently publish are ignored (counted in `unknown`), not an error:
+/// a report may legitimately race its own reconcile.
+#[utoipa::path(
+    put,
+    path = "/library/provider/{provider}/running",
+    tag = "library",
+    operation_id = "reportProviderRunning",
+    params(("provider" = String, Path, description = "The provider id ([a-z0-9._-], `manual` reserved)")),
+    request_body = ProviderRunningInput,
+    responses(
+        (status = OK, description = "The report was accepted", body = ProviderRunningAccepted),
+        (status = BAD_REQUEST, description = "Invalid provider id or payload", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn report_provider_running(
+    Path(provider): Path<String>,
+    ApiJson(input): ApiJson<ProviderRunningInput>,
+) -> Response {
+    if let Err(e) = crate::library::validate_provider_name(&provider) {
+        return api_error(StatusCode::BAD_REQUEST, &e);
+    }
+    // Resolve the provider's own keys to the ids the rest of the host uses. A plugin knows its
+    // titles by `external_id`; a lease knows them by the library id the catalog assigned
+    // (`playnite:<guid>`), and only the catalog can map between the two — which is also what makes
+    // this authorization-safe, since a provider can only ever speak about entries it published.
+    let mine: Vec<(String, String)> = crate::library::load_custom()
+        .into_iter()
+        .filter(|e| e.provider.as_deref() == Some(provider.as_str()))
+        .filter_map(|e| {
+            let external = e.external_id.clone()?;
+            Some((external, crate::library::library_id_for(&e)))
+        })
+        .collect();
+    let owned: std::collections::HashSet<String> = mine.iter().map(|(_, id)| id.clone()).collect();
+
+    let mut running = std::collections::HashMap::new();
+    let mut unknown = 0usize;
+    for t in &input.running {
+        match mine.iter().find(|(external, _)| *external == t.external_id) {
+            Some((_, id)) => {
+                running.insert(id.clone(), t.pid);
+            }
+            None => unknown += 1,
+        }
+    }
+    let matched = running.len();
+    tracing::debug!(
+        provider,
+        owned = owned.len(),
+        matched,
+        unknown,
+        "provider liveness report"
+    );
+    crate::runstate::report(&provider, owned, running);
+    Json(ProviderRunningAccepted {
+        matched,
+        unknown,
+        ttl_s: crate::runstate::REPORT_TTL.as_secs(),
+    })
+    .into_response()
+}
+
 /// Fetch one cover-art image for a library entry
 ///
 /// Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams

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

@@ -1440,6 +1440,16 @@ fn every_route_is_classified_for_the_plugin_and_cert_lanes() {
         ("DELETE", "/api/v1/library/custom/{id}", true, false),
         ("PUT", "/api/v1/library/provider/{provider}", true, false),
         ("DELETE", "/api/v1/library/provider/{provider}", true, false),
+        // Liveness for a provider's own titles: the plugin lane's, like the reconcile beside it,
+        // and for the same reason — the host maps the report through the catalog, so a provider can
+        // only ever speak about entries it published. Never the cert lane: a streaming client has
+        // no titles of its own to report on.
+        (
+            "PUT",
+            "/api/v1/library/provider/{provider}/running",
+            true,
+            false,
+        ),
         // ---- stats.
         ("POST", "/api/v1/stats/capture/start", true, false),
         ("POST", "/api/v1/stats/capture/stop", true, false),
@@ -2935,3 +2945,54 @@ async fn provider_reconcile_validation() {
     let (s, _) = send(&app, del).await;
     assert_eq!(s, StatusCode::BAD_REQUEST);
 }
+
+/// Liveness reporting: the provider id is validated like every other provider write, and a title
+/// the provider does not publish is *counted*, not refused.
+///
+/// That tolerance is the point. A report races its own reconcile by construction — a game can start
+/// before the entry that describes it has landed — and 400-ing the whole report over one unknown id
+/// would throw away the liveness of every other running title, which is precisely the failure the
+/// launcher-tile 400 taught us to avoid (`sanitize_launcher_entries`). The developer's real catalog
+/// is not touched here, so every id in this test is `unknown` by construction — which is exactly
+/// the case being pinned.
+#[tokio::test]
+async fn provider_running_report_validation() {
+    let app = test_app(test_state(), None);
+    let put = |provider: &str, body: serde_json::Value| {
+        axum::http::Request::put(format!("/api/v1/library/provider/{provider}/running"))
+            .header(axum::http::header::CONTENT_TYPE, "application/json")
+            .body(Body::from(body.to_string()))
+            .unwrap()
+    };
+
+    let (s, json) = send(&app, put("manual", serde_json::json!({"running": []}))).await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+    assert!(json["error"].as_str().unwrap().contains("reserved"));
+    let (s, _) = send(&app, put("Bad%2FName", serde_json::json!({"running": []}))).await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+
+    // An unreported provider is a legitimate report of "nothing is running".
+    let (s, json) = send(&app, put("playnite", serde_json::json!({"running": []}))).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(json["matched"], 0);
+    assert_eq!(json["unknown"], 0);
+    assert!(json["ttl_s"].as_u64().unwrap() > 0);
+
+    // An id this provider does not publish is ignored, not an error.
+    let (s, json) = send(
+        &app,
+        put(
+            "playnite",
+            serde_json::json!({"running": [{"external_id": "no-such-title", "pid": 4242}]}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(json["matched"], 0);
+    assert_eq!(json["unknown"], 1);
+
+    // A report leaves no opinion behind about a title nobody published, so nothing this test did
+    // can hold a real lease open.
+    assert!(!crate::runstate::speaks_for(Some("playnite:no-such-title")));
+    crate::runstate::forget("playnite");
+}

crates/punktfunk-host/src/native.rs

@@ -48,8 +48,10 @@ mod compositor;
 use compositor::resolve_compositor;
 
 /// Virtual-gamepad backend resolution (plan §W1); `serve_session` + the `Pads` state machine reach
-/// `resolve_gamepad`/`resolve_pad_kind`/`route_decision` here.
-mod gamepad;
+/// `resolve_gamepad`/`resolve_pad_kind`/`route_decision` here. Crate-visible because the choice of
+/// Windows Xbox backend (`windows_xbox_hid`) is not the native plane's alone — the GameStream plane
+/// presents the same virtual pad and has to make the same choice, from one definition.
+pub(crate) mod gamepad;
 use gamepad::{resolve_gamepad, resolve_pad_kind, route_decision};
 
 /// The SPAKE2 pairing ceremony (plan §W1); `serve_session` dispatches a PairRequest connection here.
@@ -154,9 +156,33 @@ pub struct Punktfunk1Options {
 /// the client's reported address, no hole-punch"; `false` (random port, or a busy fixed port) means
 /// "hole-punch". The socket is held from the handshake through streaming — no drop-then-rebind
 /// window in which a concurrent session could steal a fixed port.
-fn bind_data_socket(data_port: Option<u16>) -> std::io::Result<(std::net::UdpSocket, bool)> {
+///
+/// `local_ip` is the address the client's QUIC connection was RECEIVED on (`Connection::local_ip`),
+/// and binding to it is load-bearing on a multi-homed host. The client's data socket is
+/// `connect`ed to the host IP it dialed, so its kernel accepts video only from THAT source
+/// address; a wildcard bind here lets the routing table pick the egress interface independently of
+/// the one the control plane arrived on, and the two differ whenever a host has two paths to the
+/// client — Ethernet and Wi-Fi both up on the same LAN is the everyday case. Every video datagram
+/// is then dropped by the client's kernel before userspace: nothing counts it, `loss_ppm` stays 0
+/// (no packets, no gaps), the hole-punch still arrives so the host logs `punched=true`, and the
+/// control plane — which quinn pins to the right local address — stays perfectly healthy. That is
+/// the "connects fine, black screen forever" shape with every gauge green, and it is invisible on
+/// both ends. `None` (platform can't report it) or a bind failure falls back to the wildcard.
+fn bind_data_socket(
+    data_port: Option<u16>,
+    local_ip: Option<std::net::IpAddr>,
+) -> std::io::Result<(std::net::UdpSocket, bool)> {
+    // An IPv4-mapped v6 local address (dual-stack endpoint) must be unmapped before it can bind a
+    // socket that will `connect` to a v4 peer — the families have to match.
+    let local_ip = local_ip.map(|ip| match ip {
+        std::net::IpAddr::V6(v6) => v6.to_ipv4_mapped().map_or(ip, std::net::IpAddr::V4),
+        v4 => v4,
+    });
+    let wildcard = |ip: Option<std::net::IpAddr>| {
+        ip.unwrap_or(std::net::IpAddr::V4(std::net::Ipv4Addr::UNSPECIFIED))
+    };
     if let Some(p) = data_port.filter(|p| *p != 0) {
-        match std::net::UdpSocket::bind(("0.0.0.0", p)) {
+        match std::net::UdpSocket::bind((wildcard(local_ip), p)) {
             Ok(sock) => return Ok((sock, true)),
             Err(e) => tracing::warn!(
                 data_port = p,
@@ -166,7 +192,23 @@ fn bind_data_socket(data_port: Option<u16>) -> std::io::Result<(std::net::UdpSoc
             ),
         }
     }
-    Ok((std::net::UdpSocket::bind("0.0.0.0:0")?, false))
+    match std::net::UdpSocket::bind((wildcard(local_ip), 0)) {
+        Ok(sock) => Ok((sock, false)),
+        // The control plane arrived on this address moments ago, so a failure here means it just
+        // went away (an adapter dropped mid-handshake). The wildcard still reaches a client the
+        // routing table can route to — degraded, not dead — so take it and say why.
+        Err(e) if local_ip.is_some() => {
+            tracing::warn!(
+                local_ip = ?local_ip,
+                error = %e,
+                "could not bind the data plane to the address the control connection arrived on \
+                 — falling back to the wildcard. On a multi-homed host video may now egress from \
+                 a different interface than the client dialed, which it silently drops."
+            );
+            Ok((std::net::UdpSocket::bind("0.0.0.0:0")?, false))
+        }
+        Err(e) => Err(e),
+    }
 }
 
 /// The native (punktfunk/1) trust store + on-demand arming PIN, shared with the management API.
@@ -1402,6 +1444,12 @@ async fn serve_session(
     // evidence (a refusal without the score left a 23-minute floor-pinned field session with no
     // trace of why).
     let cadence_behind_score = Arc::new(AtomicU32::new(0));
+    // Delivery truth, control task → data plane: the packet count the client reports having
+    // received all session (`u32::MAX` until a client new enough to answer sends one). The data
+    // plane needs it to tell a clean link from a dead one — `loss_ppm = 0` means both — before it
+    // blames the client for a stream that never reached it.
+    let client_packets_received = Arc::new(AtomicU32::new(u32::MAX));
+    let client_packets_received_ctl = client_packets_received.clone();
     let (probe_tx, probe_rx) = std::sync::mpsc::channel::<ProbeRequest>();
     let (probe_result_tx, probe_result_rx) = tokio::sync::mpsc::unbounded_channel::<ProbeResult>();
     // Mode-switch outcome, data plane → control task (same pattern as `probe_result_tx`): the accept
@@ -1533,6 +1581,7 @@ async fn serve_session(
         encoder_ceiling_kbps.clone(),
         cadence_degraded.clone(),
         cadence_behind_score.clone(),
+        client_packets_received_ctl,
         fec_target_ctl,
         phase_ctl_control,
         reconfig_tx,
@@ -2048,6 +2097,10 @@ async fn serve_session(
     // stages ride the same per-session trace; resizes write their totals into the shared slot.
     let bringup_dp = bringup.clone();
     let resize_ms_dp = resize_ms.clone();
+    // The address the control connection arrived on, for the data plane's source-address check
+    // below — the one comparison that distinguishes "the client is filtering our video" from
+    // "the video never left". Captured here because the send loop runs on a blocking thread.
+    let control_local_ip = conn.local_ip();
     let result: Result<()> = async {
         let stream_thread = tokio::task::spawn_blocking(move || -> Result<()> {
             // Bring up the (already-bound) data-plane socket. Default: hole-punch — wait briefly
@@ -2082,15 +2135,64 @@ async fn serve_session(
                 }
             };
             bringup_dp.mark("punch_done");
+            // Post-`connect`, `local_addr` reports the source address the kernel will actually
+            // stamp on every video datagram — the number that has to match the host IP the client
+            // dialed, because its data socket is connected and its kernel drops anything else
+            // before userspace. Logged unconditionally: a black-screen report is unanswerable
+            // without it (this session's showed only the port).
+            let local = transport.local_addr().ok();
             tracing::info!(
                 %client_udp,
                 udp_port,
                 direct,
                 punched,
+                local = ?local,
                 "data plane bound (direct=true → fixed --data-port, streaming to the reported \
                  address with no hole-punch; else punched=true → the client's observed source, \
                  false → no punch seen, the reported address)"
             );
+            // A video source address that isn't the one the control plane arrived on means the
+            // client will discard every datagram we send, however healthy this end looks.
+            if let (Some(l), Some(c)) = (local.map(|a| a.ip()), control_local_ip) {
+                let c = match c {
+                    std::net::IpAddr::V6(v6) => {
+                        v6.to_ipv4_mapped().map_or(c, std::net::IpAddr::V4)
+                    }
+                    v4 => v4,
+                };
+                if !l.is_unspecified() && l != c {
+                    tracing::warn!(
+                        video_source_ip = %l,
+                        control_local_ip = %c,
+                        "the video data plane egresses from a DIFFERENT host address than the one \
+                         this client connected to — its data socket is connected to the address it \
+                         dialed, so its kernel drops every video datagram before userspace: black \
+                         screen, zero reported loss, healthy control plane. Usual cause is two \
+                         live paths to the client (Ethernet and Wi-Fi both up on the same LAN, or \
+                         a VPN/overlay adapter claiming the route)"
+                    );
+                }
+            }
+            // A punch that never arrives is not a routine fallback — it is the fingerprint of a
+            // data port the client cannot reach INBOUND, and every client punches (5/s for the
+            // first three seconds, then every two). Video then goes to an address the client only
+            // CLAIMED, unverified, and if anything on the path needed the flow opened client-first
+            // it silently goes nowhere: black picture, healthy control plane, no error anywhere.
+            // On Windows the usual cause is a firewall rule that opens fixed ports only, while
+            // this port is ephemeral and different every session (fixed by the program-scoped rule
+            // `service install` now adds — an install predating it still has the old rules).
+            // `direct` skips the punch by operator choice, so it is not a failure there.
+            if !direct && !punched {
+                tracing::warn!(
+                    %client_udp,
+                    udp_port,
+                    "no hole-punch reached this host's data port — inbound UDP to it looks \
+                     BLOCKED, so video is being sent to the address the client reported without \
+                     any confirmed return path. If the picture stays black while the session is \
+                     otherwise healthy, this line is the reason: allow inbound UDP for the host \
+                     executable (any port), or pin --data-port and open that one"
+                );
+            }
             let mut session = Session::new(cfg, Box::new(transport))
                 .map_err(|e| anyhow!("host session: {e:?}"))?;
             match source {
@@ -2125,6 +2227,7 @@ async fn serve_session(
                         encoder_ceiling_kbps,
                         cadence_degraded,
                         cadence_behind_score,
+                        client_packets_received,
                         bitrate_auto,
                         bit_depth,
                         chroma,
@@ -2485,7 +2588,7 @@ mod tests {
         // No fixed port (and the explicit-0 alias) → a random ephemeral port, and NOT direct: the
         // caller hole-punches.
         for req in [None, Some(0)] {
-            let (sock, direct) = bind_data_socket(req).expect("bind random data socket");
+            let (sock, direct) = bind_data_socket(req, None).expect("bind random data socket");
             assert!(!direct, "req={req:?} must hole-punch, not stream direct");
             assert_ne!(sock.local_addr().unwrap().port(), 0);
         }
@@ -2502,13 +2605,14 @@ mod tests {
             .port();
 
         // A free fixed port binds exactly it, in DIRECT mode (no hole-punch).
-        let (held, direct) = bind_data_socket(Some(free)).expect("bind fixed data socket");
+        let (held, direct) = bind_data_socket(Some(free), None).expect("bind fixed data socket");
         assert!(direct, "a fixed --data-port must stream direct");
         assert_eq!(held.local_addr().unwrap().port(), free);
 
         // While it's held, a second session on the same fixed port can't bind it → it must fall
         // back to a random port + hole-punch rather than fail (so concurrency never regresses).
-        let (fallback, direct2) = bind_data_socket(Some(free)).expect("busy fixed port falls back");
+        let (fallback, direct2) =
+            bind_data_socket(Some(free), None).expect("busy fixed port falls back");
         assert!(!direct2, "a busy fixed port must fall back to hole-punch");
         assert_ne!(
             fallback.local_addr().unwrap().port(),
@@ -2517,6 +2621,30 @@ mod tests {
         );
     }
 
+    /// The multi-homed black screen: video must egress from the address the client's control
+    /// connection arrived on, because the client's data socket is connected to the host address it
+    /// dialed and its kernel drops every datagram from any other source — silently, before
+    /// userspace, so nothing on either end counts it. A wildcard bind here lets the routing table
+    /// choose a different interface whenever the host has two paths to the client.
+    #[test]
+    fn data_socket_binds_the_address_the_control_plane_arrived_on() {
+        let loopback = std::net::IpAddr::V4(std::net::Ipv4Addr::LOCALHOST);
+        let (sock, direct) =
+            bind_data_socket(None, Some(loopback)).expect("bind pinned data socket");
+        assert!(!direct);
+        assert_eq!(sock.local_addr().unwrap().ip(), loopback);
+
+        // An IPv4-mapped v6 local address (a dual-stack QUIC endpoint reports one) has to be
+        // unmapped, or the socket binds v6 and can never `connect` to the v4 client.
+        let mapped = std::net::IpAddr::V6(std::net::Ipv4Addr::LOCALHOST.to_ipv6_mapped());
+        let (sock, _) = bind_data_socket(None, Some(mapped)).expect("bind mapped data socket");
+        assert_eq!(sock.local_addr().unwrap().ip(), loopback);
+
+        // No reported local address (platform can't say) keeps the old wildcard behaviour.
+        let (sock, _) = bind_data_socket(None, None).expect("bind wildcard data socket");
+        assert!(sock.local_addr().unwrap().ip().is_unspecified());
+    }
+
     /// Freeze the gamepad wire contract: every button bit + axis id pinned to its exact value in
     /// `punktfunk_core::input::gamepad` — the single source both the punktfunk/1 native wire and the
     /// GameStream/Limelight wire read from (they are one and the same). Renumbering a bit in core

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

@@ -30,6 +30,10 @@ pub(super) async fn run(
     encoder_ceiling_kbps: Arc<AtomicU32>,
     cadence_degraded: Arc<AtomicBool>,
     cadence_behind_score: Arc<AtomicU32>,
+    // Delivery truth, published from every `DeliveryReport` for the data plane's stall diagnosis:
+    // the packets the client says it has received all session (`u32::MAX` = a client too old to
+    // send one, the pre-seeded value).
+    client_packets_received: Arc<AtomicU32>,
     fec_target_ctl: Arc<AtomicU8>,
     // Phase-locked capture bridge: client PhaseReports land here latest-wins; the encode loop's
     // controller drains at its own ~1 Hz cadence (design/phase-locked-capture.md).
@@ -162,6 +166,16 @@ pub(super) async fn run(
                     if rfi_tx.send((req.first_frame, req.last_frame)).is_err() {
                         break; // data plane gone
                     }
+                } else if let Ok(rep) = punktfunk_core::quic::DeliveryReport::decode(&msg) {
+                    // What the client has actually RECEIVED — published unconditionally, because it
+                    // is what lets the data plane read `loss_ppm = 0` correctly and must survive
+                    // both the `adaptive_fec` opt-out and a pinned FEC percentage (a host with
+                    // PUNKTFUNK_FEC_PCT set is exactly as blind to a dead data plane otherwise).
+                    // Saturated into the u32 bridge; the value only ever matters near zero.
+                    client_packets_received.store(
+                        rep.packets_received.min(u32::MAX as u64 - 1) as u32,
+                        Ordering::Relaxed,
+                    );
                 } else if let Ok(rep) = LossReport::decode(&msg) {
                     // Adaptive FEC: size recovery to the loss the client is seeing. The data-plane
                     // send loop reads `fec_target_ctl` and applies it per frame. Ignored when FEC

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

@@ -363,8 +363,13 @@ fn degrade_xbox_identity(chosen: GamepadPref) -> GamepadPref {
 ///
 /// The two backends are mutually exclusive per pad by construction (one match arm or the other) —
 /// presenting both would hand a game two controllers for one pair of hands.
+///
+/// Read by BOTH input planes. The native plane branches on it in `Pads::handle`; the GameStream
+/// plane in `gamestream::control::SessionPads`. It was `pub(super)` while only the native plane
+/// consulted it, and that is exactly how Moonlight sessions spent two releases on the XUSB pad
+/// after this default flipped — the knob was unreachable from the module that needed it.
 #[cfg(target_os = "windows")]
-pub(super) fn windows_xbox_hid() -> bool {
+pub(crate) fn windows_xbox_hid() -> bool {
     match std::env::var("PUNKTFUNK_XBOX_BACKEND") {
         Ok(v) if v.trim().eq_ignore_ascii_case("xusb") => false,
         // Anything else — unset, empty, "hid", or a typo — takes the default. A misspelled opt-out

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

@@ -780,7 +780,9 @@ pub(super) async fn negotiate(
     // bind→read→drop→rebind window a concurrent session could race for a fixed port). A fixed
     // `--data-port` yields `direct = true` (stream straight to the client's reported address,
     // no punch-wait); otherwise a random ephemeral port + hole-punch.
-    let (data_sock, direct) = bind_data_socket(data_port)?;
+    // Bound to the address THIS connection arrived on, not the wildcard: the client only accepts
+    // video from the host IP it dialed (see `bind_data_socket`).
+    let (data_sock, direct) = bind_data_socket(data_port, conn.local_ip())?;
     let udp_port = data_sock.local_addr()?.port();
 
     // The session's video geometry (see the `shard_payload` field below). Resolved before the

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

@@ -1319,6 +1319,14 @@ pub(super) struct SessionContext {
     /// of what held it there — the score is the missing discriminator between "the detector's
     /// budget is wrong" and "this encoder genuinely can't hold cadence").
     pub(super) cadence_behind_score: Arc<AtomicU32>,
+    /// Data-plane packets the CLIENT says it has received all session, from the latest
+    /// [`punktfunk_core::quic::DeliveryReport`] ([`u32::MAX`] = a client too old to send one).
+    ///
+    /// The one signal that distinguishes "the link is clean" from "nothing is arriving": both look
+    /// like `loss_ppm = 0`, because loss is a ratio over the packets that DID arrive. Read by the
+    /// keyframe-cadence diagnosis below, which without it accuses the client of being too slow for
+    /// a stream it has never received a byte of.
+    pub(super) client_packets_received: Arc<AtomicU32>,
     /// The client asked for "Automatic" (`Hello::bitrate_kbps == 0`), so `bitrate_kbps` came from
     /// the host's codec-aware default. For PyroWave that default is the ~1.6 bpp operating point of
     /// the NEGOTIATED MODE (`resolve_bitrate_kbps_for`) — a mid-stream mode switch re-resolves it
@@ -1598,6 +1606,7 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
         encoder_ceiling_kbps,
         cadence_degraded,
         cadence_behind_score,
+        client_packets_received,
         bitrate_auto,
         bit_depth,
         // The resolved chroma is already captured in `plan` (above); ignore the duplicate here.
@@ -3006,16 +3015,73 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                     // subsystems while the real chain was: client refused the codec → demoted to
                     // a slower decode rung → could not sustain the rate → standing queue.
                     // Perfect periodicity argues FOR a software cooldown, not against it.
-                    if matches_client_flush_cadence(period) {
-                        tracing::warn!(
+                    let client_rx = client_packets_received.load(Ordering::Relaxed);
+                    // The client has TOLD us it has received nothing all session (a v1 client
+                    // leaves the `u32::MAX` seed, so this only fires on an explicit zero). That
+                    // outranks both cadence verdicts below, which are about a client drowning in
+                    // frames — the opposite failure, and indistinguishable by period alone because
+                    // a client that got no picture re-asks on its own no-video timer at very
+                    // nearly the same spacing. Diagnosing this as "too slow" cost a 2026-08-20
+                    // field investigation days: the host was blameless-looking (`sent` climbing,
+                    // `loss_ppm = 0`, FEC decayed to the floor) while not one byte of video ever
+                    // reached the client.
+                    if client_rx == 0 {
+                        tracing::error!(
                             period_s = format!("{:.1}", period.as_secs_f64()),
-                            "client keyframe recoveries match the client's jump-to-live cooldown \
-                             — the CLIENT cannot sustain the stream and is shedding a standing \
-                             receive queue (check its log for 'receive backlog stopped draining' \
-                             with queue_depth, and for a decode rung that demoted); a slower \
-                             decode path or a link below the bitrate does this, and it is NOT a \
-                             host display disturbance"
+                            frames_sent = sent,
+                            "THE VIDEO DATA PLANE IS NOT REACHING THE CLIENT — it reports 0 \
+                             packets received all session while this host has sent the frames \
+                             counted here, so the picture is black and every keyframe we force is \
+                             wasted. The control plane is healthy (this report arrived on it), so \
+                             the session looks alive: audio, input and the library keep working. \
+                             READ THE 'data plane bound' LINE ABOVE — it says which leg failed, \
+                             and this line cannot. `punched=false`: the client's hole-punch never \
+                             arrived, so inbound UDP to this host's per-session data port is \
+                             blocked — open it (the ports are ephemeral, so the rule must be \
+                             program-scoped, not port-scoped). `punched=true`: inbound is FINE and \
+                             the failure is on the return leg — compare that line's `local=` \
+                             source address against the host address this client dialed, because \
+                             its data socket is connected and its kernel silently drops video from \
+                             any other source. If those match, the datagrams left this host \
+                             correctly and the client either never received them (a hop on the \
+                             path) or received them and could not open them: this counter is \
+                             incremented AFTER decrypt and replay checks, so a session whose every \
+                             datagram failed to open reports exactly this same zero"
                         );
+                    } else if matches_client_recovery_cooldown(period) {
+                        if client_rx == u32::MAX {
+                            // This client predates the delivery count, so the period alone has to
+                            // carry the verdict — and it CANNOT: both client cooldowns live in this
+                            // band and they mean opposite things. Say so instead of picking one.
+                            // The old confident wording sent a field investigation after the
+                            // decoder for days while the real fault was that nothing arrived.
+                            tracing::warn!(
+                                period_s = format!("{:.1}", period.as_secs_f64()),
+                                frames_sent = sent,
+                                "client keyframe recoveries land on a client software cooldown, \
+                                 but this client is too old to report whether any video reached \
+                                 it — so this is EITHER a client that cannot sustain the stream \
+                                 and is shedding a standing receive queue, OR a client that has \
+                                 received nothing at all and is re-asking on its no-video timer. \
+                                 They are opposite faults; the host cannot tell them apart from \
+                                 the period. Its log does: 'receive backlog stopped draining' \
+                                 (with queue_depth) means the first, 'no video received … into \
+                                 the session' means the second. Upgrading the client makes this \
+                                 line decide on its own"
+                            );
+                        } else {
+                            tracing::warn!(
+                                period_s = format!("{:.1}", period.as_secs_f64()),
+                                client_packets_received = client_rx,
+                                "client keyframe recoveries match the client's jump-to-live \
+                                 cooldown, and it confirms video IS arriving — the CLIENT cannot \
+                                 sustain the stream and is shedding a standing receive queue \
+                                 (check its log for 'receive backlog stopped draining' with \
+                                 queue_depth, and for a decode rung that demoted); a slower \
+                                 decode path or a link below the bitrate does this, and it is NOT \
+                                 a host display disturbance"
+                            );
+                        }
                     } else {
                         tracing::warn!(
                             period_s = format!("{:.1}", period.as_secs_f64()),
@@ -4191,6 +4257,26 @@ fn matches_client_flush_cadence(period: std::time::Duration) -> bool {
     period.abs_diff(flush) < flush / 10
 }
 
+/// The client's OTHER re-ask cooldown: it has received no video whatsoever and is asking for a
+/// keyframe on its no-video timer. Kept separate from [`matches_client_flush_cadence`] because the
+/// two describe opposite faults — drowning in frames versus receiving none — and only the client's
+/// reported delivery count can say which. Both are host-side-irrelevant either way: a fixed
+/// software cooldown is never the periodic *disturbance* the metronomic branch reports.
+///
+/// Compared against the SHARED constant, never a copy of the number — the same discipline
+/// [`matches_client_flush_cadence`] follows, and the one that was missing when the two cooldowns
+/// were both 2000 ms and the host could not even tell that it was guessing.
+fn matches_client_no_video_cadence(period: std::time::Duration) -> bool {
+    let no_video = punktfunk_core::client::NO_VIDEO_RETRY;
+    period.abs_diff(no_video) < no_video / 10
+}
+
+/// Either client cooldown — the band in which a period tells us about the CLIENT's software, not
+/// about anything physical on this host.
+fn matches_client_recovery_cooldown(period: std::time::Duration) -> bool {
+    matches_client_flush_cadence(period) || matches_client_no_video_cadence(period)
+}
+
 /// One mode's capture/encode pipeline: (capturer, encoder, first frame, frame interval).
 /// Dropping the capturer tears down the PipeWire stream and the virtual output with it.
 type Pipeline = (
@@ -5068,6 +5154,29 @@ mod tests {
         assert!(!matches_client_flush_cadence(std::time::Duration::ZERO));
     }
 
+    /// The two client cooldowns must stay TELLABLE APART by period, and both must stay out of the
+    /// display-disturbance branch. While they were both 2000 ms a black-screen field case (nothing
+    /// ever reached the client) was reported as "the client cannot sustain the stream" — the exact
+    /// opposite fault — because the periods were identical and the host guessed.
+    #[test]
+    fn the_two_client_cooldowns_are_distinguishable_and_both_excluded_from_display_blame() {
+        let flush = punktfunk_core::client::FLUSH_COOLDOWN;
+        let no_video = punktfunk_core::client::NO_VIDEO_RETRY;
+        assert_ne!(
+            flush, no_video,
+            "identical cooldowns make the host's verdict a coin flip"
+        );
+        // Neither may fall inside the other's ±10% band, or the period stops discriminating.
+        assert!(!matches_client_flush_cadence(no_video));
+        assert!(!matches_client_no_video_cadence(flush));
+        // Both are client software cooldowns: never the metronomic display-disturbance branch.
+        assert!(matches_client_recovery_cooldown(flush));
+        assert!(matches_client_recovery_cooldown(no_video));
+        // A real periodic disturbance still reaches that branch.
+        assert!(!matches_client_recovery_cooldown(flush * 3));
+        assert!(!matches_client_recovery_cooldown(std::time::Duration::ZERO));
+    }
+
     #[test]
     fn an_escalated_but_caught_up_encoder_stops_refusing_climbs() {
         const DEGRADE: u32 = 10;

crates/punktfunk-host/src/runstate.rs

@@ -0,0 +1,217 @@
+//! What a provider plugin **says** is running — the one liveness signal the host cannot work out
+//! for itself.
+//!
+//! [`crate::procscan`] answers "is this game running" by looking at the process table, and
+//! [`crate::gamelease`] turns that into a session lifetime. That works because most stores leave
+//! something recognizable behind: an install directory, an executable, a Steam reaper. Some do not,
+//! and one store in particular *already knows the answer*: Playnite starts the game itself, tracks
+//! it with the mode the person configured (process, directory, original-process), and fires an
+//! event on both edges — carrying the pid it started. Every bit of that was being thrown away, and
+//! the host was left re-deriving a worse version of it by scanning.
+//!
+//! So this is the inbound half of [`crate::library::DetectHint`]. That one is *static* ("here is
+//! how to recognize my title's process"); this one is *live* ("that title is running right now, and
+//! here is its pid"). A provider PUTs its full running set; the host keeps it here; the lease
+//! watcher consults it.
+//!
+//! ### Why the whole set, and why a TTL
+//!
+//! The wire is declarative — the same shape as the library reconcile, for the same reason. A
+//! provider that missed an event, restarted, or was installed mid-game converges on its next PUT
+//! instead of drifting forever; there is no per-event delta to lose.
+//!
+//! And a report **expires**. A plugin that dies with a game running would otherwise leave a claim
+//! that is true today and a lie tomorrow — and unlike Steam's registry flag (which
+//! [`crate::procscan::running_hint`] must treat as merely a bounded veto because Steam leaves it
+//! set on any unclean exit) this claim is allowed to *keep a session alive on its own*. That is
+//! only safe while something is actively restating it, so a report older than [`REPORT_TTL`] stops
+//! counting and the host falls back to scanning, exactly as it does today. The provider's side of
+//! that bargain is to re-PUT well inside the window while anything is running.
+
+use std::collections::{HashMap, HashSet};
+use std::sync::{Mutex, MutexGuard, OnceLock};
+use std::time::{Duration, Instant};
+
+/// How long a provider's report stays authoritative without being restated.
+///
+/// Generous enough that a plugin refreshing every 30s survives a slow reconcile or a paused runner,
+/// short enough that a *dead* plugin stops vetoing a session end within a couple of minutes. The
+/// cost of expiring too early is the pre-existing behaviour (scan-only); the cost of never expiring
+/// is a session that can never end on its own, which is the bug this whole area exists to kill.
+pub const REPORT_TTL: Duration = Duration::from_secs(90);
+
+/// What a provider says about one of its titles.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Liveness {
+    /// Whether the provider lists this title as running right now.
+    pub running: bool,
+    /// The pid the provider started for it, when it knows one. Never trusted as a bare number —
+    /// every use re-verifies it through [`crate::procscan`], which pins it to its start time.
+    pub pid: Option<u32>,
+}
+
+/// One provider's most recent report.
+struct Report {
+    /// When it landed — the TTL clock.
+    at: Instant,
+    /// Every library id this provider speaks for. What makes "not in `running`" mean *not running*
+    /// rather than *no opinion*: without it an omitted title is indistinguishable from a title
+    /// belonging to some other provider entirely.
+    owned: HashSet<String>,
+    /// The subset that is running, each with the pid the provider started (when it has one).
+    running: HashMap<String, Option<u32>>,
+}
+
+impl Report {
+    fn fresh(&self) -> bool {
+        self.at.elapsed() < REPORT_TTL
+    }
+}
+
+fn table() -> MutexGuard<'static, HashMap<String, Report>> {
+    static TABLE: OnceLock<Mutex<HashMap<String, Report>>> = OnceLock::new();
+    TABLE
+        .get_or_init(|| Mutex::new(HashMap::new()))
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+}
+
+/// Record a provider's report, replacing whatever it said before.
+///
+/// `owned` is every library id the provider currently publishes; `running` is the subset that is
+/// running, keyed the same way, valued by pid where one is known.
+pub fn report(provider: &str, owned: HashSet<String>, running: HashMap<String, Option<u32>>) {
+    table().insert(
+        provider.to_string(),
+        Report {
+            at: Instant::now(),
+            owned,
+            running,
+        },
+    );
+}
+
+/// Forget everything a provider said — its entries are gone, so its opinions are meaningless.
+pub fn forget(provider: &str) {
+    table().remove(provider);
+}
+
+/// What a *fresh* provider says about this library id, or `None` when none speaks for it.
+///
+/// `None` is the answer for every title on a host with no reporting plugin, which is what keeps
+/// this entirely inert until someone opts in.
+pub fn opinion(app_id: &str) -> Option<Liveness> {
+    let table = table();
+    table
+        .values()
+        .filter(|r| r.fresh())
+        .find(|r| r.owned.contains(app_id))
+        .map(|r| match r.running.get(app_id) {
+            Some(pid) => Liveness {
+                running: true,
+                pid: *pid,
+            },
+            None => Liveness {
+                running: false,
+                pid: None,
+            },
+        })
+}
+
+/// Whether any fresh provider reports liveness for this title at all — regardless of what it
+/// currently says.
+///
+/// Asked once, when a lease opens: a title whose provider will tell us when it stops is trackable
+/// even with no detect signals whatsoever, which is the whole point (see
+/// [`crate::gamelease::LeaseKind::Reported`]).
+pub fn speaks_for(app_id: Option<&str>) -> bool {
+    app_id.is_some_and(|id| opinion(id).is_some())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn owned(ids: &[&str]) -> HashSet<String> {
+        ids.iter().map(|s| (*s).to_string()).collect()
+    }
+
+    fn running(ids: &[(&str, Option<u32>)]) -> HashMap<String, Option<u32>> {
+        ids.iter().map(|(s, p)| ((*s).to_string(), *p)).collect()
+    }
+
+    // The table is process-global and these tests run in parallel, so each takes a provider id and
+    // app ids only it uses, and cleans up only its own row. An earlier draft shared the id
+    // `playnite` and cleared the whole table between cases, which made the three of them flip each
+    // other's answers depending on scheduling — the same shape as `mgmt`'s `local_summary` race.
+
+    /// The three answers, and the distinction the whole module turns on: a title its provider omits
+    /// is *not running*, while a title nobody speaks for has *no opinion*. Conflating them would
+    /// make every unreported game on the box look like it had just quit.
+    #[test]
+    fn omitted_is_not_running_but_unknown_is_no_opinion() {
+        report(
+            "answers-test",
+            owned(&["answers:a", "answers:b"]),
+            running(&[("answers:a", Some(4242))]),
+        );
+        assert_eq!(
+            opinion("answers:a"),
+            Some(Liveness {
+                running: true,
+                pid: Some(4242)
+            })
+        );
+        assert_eq!(
+            opinion("answers:b"),
+            Some(Liveness {
+                running: false,
+                pid: None
+            })
+        );
+        assert_eq!(opinion("answers:never-published"), None);
+        assert!(speaks_for(Some("answers:b")));
+        assert!(!speaks_for(Some("answers:never-published")));
+        assert!(!speaks_for(None));
+        forget("answers-test");
+    }
+
+    /// A report replaces its predecessor wholesale. The set is the message: a title that dropped out
+    /// of it has stopped, and carrying the old entry forward would be exactly the stuck-running
+    /// state this exists to prevent.
+    #[test]
+    fn a_report_replaces_the_previous_one() {
+        report(
+            "replace-test",
+            owned(&["replace:a"]),
+            running(&[("replace:a", None)]),
+        );
+        report("replace-test", owned(&["replace:a"]), running(&[]));
+        assert_eq!(
+            opinion("replace:a"),
+            Some(Liveness {
+                running: false,
+                pid: None
+            })
+        );
+        forget("replace-test");
+        assert_eq!(opinion("replace:a"), None);
+    }
+
+    /// A stale report stops counting — the bound that makes it safe to let a plugin's claim hold a
+    /// session open. Seeded with an aged timestamp rather than by sleeping for 90 seconds.
+    #[test]
+    fn a_stale_report_has_no_opinion() {
+        table().insert(
+            "stale-test".to_string(),
+            Report {
+                at: Instant::now() - REPORT_TTL - Duration::from_secs(1),
+                owned: owned(&["stale:a"]),
+                running: running(&[("stale:a", Some(7))]),
+            },
+        );
+        assert_eq!(opinion("stale:a"), None);
+        assert!(!speaks_for(Some("stale:a")));
+        forget("stale-test");
+    }
+}

crates/punktfunk-host/src/windows/service.rs

@@ -1587,6 +1587,7 @@ fn add_firewall_rules(allow_public: bool) {
             eprintln!("warning: could not add firewall rule '{name}' (add it manually if needed)");
         }
     }
+    add_data_plane_firewall_rule(profile);
     if !allow_public {
         println!(
             "Note: streaming ports are open on Private/Domain networks only. On a network Windows \
@@ -1596,7 +1597,75 @@ fn add_firewall_rules(allow_public: bool) {
     }
 }
 
+/// Rule name for the program-scoped data-plane rule (see [`add_data_plane_firewall_rule`]).
+const FW_DATA_PLANE_RULE: &str = "Punktfunk UDP (data plane)";
+
+/// Inbound UDP for the host executable itself, at **any** local port.
+///
+/// The media data plane binds an EPHEMERAL port per session (`0.0.0.0:0`, reported to the client in
+/// the Welcome), so no `localport=` rule can cover it — the port-scoped rules above open the fixed
+/// control/GameStream/mDNS ports and nothing else. Without this, Windows Firewall drops the client's
+/// hole-punch (`PUNCH_MAGIC` → the host's data port) on EVERY session: that is what `punched=false`
+/// on the host's "data plane bound" line means. The punch then never opens the return path, video
+/// falls back to blind-sending at the address the client merely *reported*, and the moment anything
+/// on the path needs the flow opened client-first the stream goes black while the control plane
+/// stays healthy — no reconnect, no error, just a session that never shows a picture.
+///
+/// Program-scoped rather than a pinned port: it covers whatever port the session picks, needs no
+/// second rule when the range moves, and cannot collide with another host (a pinned data port in
+/// 47998-48010 would land on Sunshine/Apollo's GameStream range). The port rules above are kept as
+/// they are — an install whose recorded exe path later moves still has its fixed ports open.
+fn add_data_plane_firewall_rule(profile: &str) {
+    let exe = match std::env::current_exe() {
+        Ok(p) => p,
+        Err(e) => {
+            eprintln!(
+                "warning: could not resolve the host executable path ({e}) — skipping the \
+                 data-plane firewall rule; streams may show a black picture behind a healthy \
+                 connection on networks that need the client's hole-punch to open the path"
+            );
+            return;
+        }
+    };
+    let ok = run_quiet(
+        "netsh",
+        &[
+            "advfirewall",
+            "firewall",
+            "add",
+            "rule",
+            &format!("name={FW_DATA_PLANE_RULE}"),
+            "dir=in",
+            "action=allow",
+            "protocol=UDP",
+            &format!("program={}", exe.to_string_lossy()),
+            profile,
+        ],
+    );
+    if ok {
+        println!(
+            "Firewall rule added: {FW_DATA_PLANE_RULE} (any UDP port for {}) [{profile}]",
+            exe.display()
+        );
+    } else {
+        eprintln!(
+            "warning: could not add firewall rule '{FW_DATA_PLANE_RULE}' — the per-session video \
+             data port stays closed to inbound, so the client's hole-punch cannot reach it"
+        );
+    }
+}
+
 fn remove_firewall_rules() {
+    let _ = run_quiet(
+        "netsh",
+        &[
+            "advfirewall",
+            "firewall",
+            "delete",
+            "rule",
+            &format!("name={FW_DATA_PLANE_RULE}"),
+        ],
+    );
     for suffix in ["TCP", "UDP"] {
         // Capital P is the brand; netsh matches a rule name case-INSENSITIVELY, so this still
         // reaps the lowercase rules every release up to 0.22.1 created — no orphans on upgrade.

docs-site/content/docs/client-settings.md

@@ -230,13 +230,15 @@ How the client itself looks. None touches a stream, so none can live in a
 
 **Gamepad-optimized browsing** — *default: on.* Swaps the touch/desktop home for the
 controller-optimized one: host carousel, larger focus targets, a swipeable cover browser, steppable
-settings. Apple and Android have the switch; on Linux, Windows and the Steam Deck the
-controller-optimized home is a separate entry point. An Android TV is always in this mode.
+settings. Apple and Android have the switch — on Android in both places, ordinary Settings and the
+controller-optimized settings themselves, so that home can be left from inside it; on Linux, Windows
+and the Steam Deck the controller-optimized home is a separate entry point. An Android TV is always
+in this mode, so the switch is not offered there.
 
 **Show it** — *default: With a controller.* Shown while the switch above is on. **With a
 controller**: the controller-optimized home appears as a pad connects, the touch interface returns
 when the last one disconnects. **Always** keeps it either way — for a phone or tablet docked to a
-TV. Apple and Android (an Android TV is in that mode regardless).
+TV. Apple and Android (an Android TV is in that mode regardless, so the row is not offered there).
 
 **Background** — *default: Violet.* The colour family of the controller-optimized home's backdrop.
 Thirteen: seven dark — **Violet**, **OLED**, **Nebula**, **Abyss**, **Ember**, **Moss**,
@@ -244,9 +246,11 @@ Thirteen: seven dark — **Violet**, **OLED**, **Nebula**, **Abyss**, **Ember**,
 flip the interface to dark text on a light field. The backdrop recolours as you step the row.
 **OLED** is true black: most of the frame is pixels switched off — no glow, no power on an
 OLED/AMOLED panel. Stored under the same name on every client. The row lives in the
-controller-optimized settings (**X** from the controller-optimized home) everywhere that has one,
-including the Steam Deck and the Linux/Windows console home; the Apple TV carries it in ordinary
-Settings next to **Show it** instead, so it's reachable from the Siri Remote.
+controller-optimized settings (**X**, or **down** on the host carousel, from the controller-optimized
+home) everywhere that has one, including the Steam Deck and the Linux/Windows console home — down is
+the route where there are no face buttons to press, such as an Android TV remote, and the hint bar
+names whichever your device has; the Apple TV carries it in ordinary Settings next to **Show it**
+instead, so it's reachable from the Siri Remote.
 
 ## Overlay
 

docs-site/content/docs/game-library.md

@@ -137,8 +137,9 @@ runs what it already knows about the title, so a client can never hand the host
   keep a **Show game library** switch, on by default, for turning it off. See
   [Client settings](/docs/client-settings).
 - **Android** — the library lives only in the controller-optimized home, which a TV always uses and a
-  phone or tablet switches to when a controller is connected. Press **Y** on a saved host, or open its
-  options and choose **Library**.
+  phone or tablet switches to when a controller is connected. Press **Y** on a saved host, or press
+  **up** for its options and choose **Library** — the route a TV remote takes, having no **Y** to
+  press.
 - **Steam Deck (Decky)** — the panel is a launcher and browses nothing itself: tap **Open
   Punktfunk**, which opens the client's console home, where a paired host's **Library** button is —
   full-screen covers, gamepad-navigable, and a press starts the stream with the title launching. See

docs-site/public/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.31.0"
+    "version": "0.31.1"
   },
   "paths": {
     "/api/v1/client-logs": {
@@ -1860,6 +1860,69 @@
         }
       }
     },
+    "/api/v1/library/provider/{provider}/running": {
+      "put": {
+        "tags": [
+          "library"
+        ],
+        "summary": "Report which of a provider's titles are running",
+        "description": "The **live** counterpart to the `detect` hints in a reconcile payload: that one says *how to\nrecognize* a title's process, this one says *it is running now* (design §9,\n[`crate::runstate`]). For a provider that starts games itself and knows when they stop —\nPlaynite tracks every launch and fires an event on both edges — this is a fact the host would\notherwise have to re-derive by scanning, and for a title with nothing to scan for (an emulated\ngame, a manually added one) could not derive at all.\n\nDeclarative and idempotent, like the reconcile: the body is the provider's **complete** running\nset, so a missed event, a plugin restart or an install mid-game all self-correct on the next\nreport rather than drifting.\n\nThe report **expires** after `ttl_s` (90s) unless restated, which is what makes it safe for a\nlive provider to keep a streaming session open for a game the host cannot see: a plugin that\ndies with a game running stops counting shortly after, and the host falls back to process\nscanning exactly as it does without one. Re-report on every change **and** on a timer well\ninside the window.\n\nTitles the provider does not currently publish are ignored (counted in `unknown`), not an error:\na report may legitimately race its own reconcile.",
+        "operationId": "reportProviderRunning",
+        "parameters": [
+          {
+            "name": "provider",
+            "in": "path",
+            "description": "The provider id ([a-z0-9._-], `manual` reserved)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProviderRunningInput"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "The report was accepted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProviderRunningAccepted"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid provider id or payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/library/scanners": {
       "get": {
         "tags": [
@@ -7792,6 +7855,46 @@
           }
         }
       },
+      "ProviderRunningAccepted": {
+        "type": "object",
+        "description": "The result of a liveness report.",
+        "required": [
+          "matched",
+          "unknown",
+          "ttl_s"
+        ],
+        "properties": {
+          "matched": {
+            "type": "integer",
+            "description": "How many reported titles matched an entry this provider currently publishes.",
+            "minimum": 0
+          },
+          "ttl_s": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Seconds this report stays authoritative without being restated — re-report inside it while\nanything is running.",
+            "minimum": 0
+          },
+          "unknown": {
+            "type": "integer",
+            "description": "How many were ignored because no such entry exists (a report that raced a reconcile).",
+            "minimum": 0
+          }
+        }
+      },
+      "ProviderRunningInput": {
+        "type": "object",
+        "description": "Request body for `reportProviderRunning`.",
+        "properties": {
+          "running": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunningTitle"
+            },
+            "description": "Every title of this provider's that is running **right now**. The full set, not a delta:\nanything absent from it is reported as stopped."
+          }
+        }
+      },
       "ReleaseDisplayRequest": {
         "type": "object",
         "description": "Request body for `releaseDisplay`.",
@@ -7846,6 +7949,28 @@
           }
         }
       },
+      "RunningTitle": {
+        "type": "object",
+        "description": "One running title in a provider's liveness report.",
+        "required": [
+          "external_id"
+        ],
+        "properties": {
+          "external_id": {
+            "type": "string",
+            "description": "The provider's own stable id for the title — the same key its reconcile payload uses."
+          },
+          "pid": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int32",
+            "description": "The process id the provider started for it, when it knows one. Optional, and never trusted\nas a bare number: the host re-resolves it and pins it to its start time before it is ever\nsignalled, so a stale or recycled pid simply contributes nothing.",
+            "minimum": 0
+          }
+        }
+      },
       "RuntimeRequest": {
         "type": "object",
         "required": [

docs/releases/v0.31.1.md

@@ -0,0 +1,55 @@
+Wire-compatible with 0.31.x — everything you have already paired keeps working, and you can update one side at a time. Nothing here changes how a host and a client agree on what to send each other, so an old client on a new host, or the other way round, streams exactly as it does today.
+
+This is a fix release, and the largest thing in it has been wrong on every Windows host since there have been Windows hosts: the port your video actually travels on was never opened in the firewall, so on any network that needs your client to knock first, the connection succeeded, every health signal stayed green, and the picture never arrived. Two more are about controllers that were connected, correctly identified, and doing the wrong thing anyway — Moonlight-compatible sessions on Windows were building the one kind of virtual controller Steam and most games cannot see, and on a Fire TV a DualSense's L2 was arriving as L1. The rest is Android: a console that could not be dismissed, a picture that sat in the top-left corner, and a television remote that could not reach Settings or your library. There is one new thing too — a library add-on can now tell your host which of its games are running, which is how a game your host cannot find on disk finally ends its own session.
+
+## TL;DR
+
+- **Windows: streams that connected and then stayed black.** The per-session video port was never covered by any firewall rule, on any Windows host, ever. Update with the installer and the rule is added for you — see *Before you update*.
+- **Windows: controllers did nothing in Moonlight-compatible sessions.** Every client, every device, same result. Those sessions built a virtual controller most games cannot enumerate; they now build the same one ordinary Punktfunk sessions do.
+- **Android: controllers Android has no layout for pressed the wrong buttons.** A DualSense or an Xbox Elite Series 2 over Bluetooth on a Fire TV had L2 arriving as L1, with Circle and R1 doing nothing at all.
+- **Android: the controller console would not go away, and the picture sat in the corner.** Both fixed — and the console now carries its own switch for turning itself off.
+- **A television remote can reach Settings and your library again.** Both were on controller face buttons a remote does not have.
+- **Android: every setting that only exists in the controller console did nothing when you changed it.** Low latency, the phone's own rumble and motion, controller capture — all saved to somewhere nothing read back.
+- **Nobara hosts: "Switch to Desktop" during a stream threw you straight back into the stream.** And on Steam Deck-style hosts, a mid-stream switch could leave Gaming Mode unable to start afterwards.
+- **NixOS: the host installed a compositor that was not there.** The package shipped the small launcher and deleted the program it launches.
+- **Games your host cannot see on disk can now end their own session.** A library add-on can tell the host which of its titles are running, which is the missing half for anything launched by handing off to another program — emulated titles, manually added ones.
+
+## Before you update
+
+- **Windows hosts: run the installer rather than replacing the program by hand.** The black-picture fix is a new firewall rule, and it is added by the host's own service-install step, which the installer runs for you on every update. If you run the host some other way, run `punktfunk-host service install` once as an administrator — or add an inbound rule for `punktfunk-host.exe` yourself. Uninstalling Punktfunk removes the rule again. Nothing on the client side needs doing.
+- **NixOS hosts: expect a rebuild.** The compositor is now pinned to the exact version every other packaging channel ships, rather than to whatever the packages you happened to have carried, so its build inputs change. The binary cache added in 0.31.0 covers it if you have it configured.
+- **Add-on authors: `@punktfunk/plugin-kit` 0.4.4 is what you depend on for the running-report above.** The call and its types were reachable only through a deep import path before, so nothing could reach them from the package root. Nothing else in the add-on contract moved.
+- **Arch and SteamOS hosts: this release finally offers you a compositor upgrade you have been owed since 0.30.0.** The package's declared version had been left behind while the program inside it moved on, so your package manager saw nothing to do — which is why non-US keyboard layouts kept typing US characters on those machines even after the fix shipped.
+
+## New
+
+- **A library add-on can tell your host which of its games are running.** Your host normally works out whether a game is still going by looking for it on the machine — which needs something recognisable there to look for. A title that Playnite launches by handing off to another program has none: an emulated game, a manually added one, anything whose add-on records no folder. So the host never noticed those ending, your session stayed open on a game that had already exited, and anything set to happen when a game ends did not. The add-on knew the whole time, and can now say so. It is deliberately hard to get stuck on: a report expires unless it is repeated, so an add-on that crashes or is uninstalled stops speaking for your games within a minute and your host goes back to looking for itself. **This is the host's half.** It does something for you once an add-on sends those reports — the Playnite one is the first and updates separately, on its own schedule.
+- **The controller console can switch itself off.** On an Android phone or tablet the console's own Settings now carries a Controller-optimized UI switch, so you can leave the console from inside it and land back on the touch interface immediately. Until now that switch existed only in the touch settings — which someone stuck inside the console had no way to reach, and since 0.31.0 the console is the only interface Android shows when a controller is attached. It appears only where switching off has somewhere to land: not on a television, and not on the desktop console, where turning it off would leave you with nothing.
+
+## Improved
+
+- **A host can tell a silent connection from a perfect one.** Packet loss is a proportion of what arrived, so a link delivering nothing and a flawless link both reported zero loss — and the host read the silence as perfection, complete with confident wording about the client's network in the log. Clients now also report how much they have actually received, so a host that is sending into a void says so, and names the video path rather than blaming the client. A client too old to answer gets a warning that says as much instead of a guess.
+- **The Connected controllers page can be trusted again.** It read your button presses the same wrong way the stream did, so it agreed with the bug and confirmed a mistranslated pad as correct. It now shows what the controller actually reported alongside what Android made of it, and names the layout it resolved — which is also what makes an unrecognised pad fixable from a bug report, without the hardware in hand.
+
+## Fixed
+
+- **A Windows host could stream into a black screen with nothing anywhere saying why.** One field host sent 1,919 frames of video that were never seen while its own log blamed the client's network. The cause: the firewall rules Punktfunk installs cover fixed port numbers, but the video itself travels on a port chosen fresh for each session — a port no such rule can ever cover. So Windows dropped the client's opening knock on **every session on every Windows host**, including ones that worked; those worked only because nothing on the path needed the client to open the way first. When something did — many home routers, most mobile networks, anything doing address translation in front of the host — the control connection stayed perfectly healthy and the video went nowhere. The host now installs a rule that follows the program instead of the port number, so whichever port a session picks is covered. It is scoped to the program deliberately: pinning a port would have collided with Sunshine and Apollo on machines running both.
+- **Controllers did nothing at all in Moonlight-compatible sessions on Windows**, reported across every client and every device someone tried, which is what showed it was not a client problem. Windows has two ways to present a virtual Xbox controller, and only one of them is visible to Steam, to games using the common input libraries, and to the Windows Game Controllers panel. Ordinary Punktfunk sessions moved to that one over a year of reports; Moonlight-compatible sessions kept the invisible one purely because both were reached by the same internal name. They now make the same choice, and switching them both back is still one setting if you need it.
+- **Controllers pressed the wrong buttons on devices Android has no layout for.** Reported from a Fire TV Stick 4K Max with a DualSense and an Xbox Elite Series 2, both over Bluetooth, both identified by name and both wrong under the fingers: L2 arrived as L1, and Circle and R1 were dropped entirely. Android names a controller's buttons from a file matched to that exact model, and when there is no such file it falls back to guessing by the order the buttons appear in the controller's own report — which is only right if that order happens to match. Neither pad has a file on a Fire TV. Punktfunk now reads the button's position in the controller's report directly, which is what the controller means rather than what the guess made of it, and does so only where the guess was in play, so a device that already worked is untouched. Triggers get the same treatment: on a pad Android never mapped they sit on raw axes, which is why pulling a trigger could swing the right stick instead. Whether a trigger rests at zero or at the bottom of its range is now measured from the device rather than assumed. **Not yet confirmed on the reporter's own hardware** — the fix is proven against what those two controllers report, but a Fire TV is the test that settles it, so please say if yours still misbehaves. One thing stays broken and cannot be fixed here: the Xbox pad's Guide button is delivered by Android as the Home key, which it never passes to an app.
+- **The controller console could not be dismissed on some Android phones.** Turning it off is a matter of no controller being attached, and the app decided that by asking whether a device claimed to be a gamepad — which is the right question for routing a button press and the wrong one for knowing a pad is in the room. Manufacturer game-mode overlays and gaming-phone shoulder triggers make that claim without being controllers, and one of them was enough to pin the console on forever, because a pad that was never there can never be unplugged. The app now also asks whether the hardware is there behind the claim — a stick, a directional pad or real face buttons — and the new switch above is the guaranteed way out either way.
+- **Changing an Android-only setting inside the controller console did nothing.** Low latency, the phone's own rumble and motion controls, the controller capture switches and the console's own display mode could each be changed in the console, and each quietly went nowhere: the console filed those settings one level deeper than the settings file keeps them, so nothing ever read one back. The row showed its own default, your change came back as the value it had just been handed, and nothing downstream ever heard that anything had moved — which is also why the new off switch above needed this fixed before it could work at all. Settings written by the previous build carry a dead wrapper; it is discarded the next time anything is saved rather than followed around for the life of the install.
+- **The glow behind a focused card was squarer than the card.** The halo grows the card by a few units on every side but kept the card's own corner radius, and a shape grown outward only stays parallel if its corners grow with it — so the two arcs stopped sharing a centre and the corners read as a badly drawn outline instead of light spilling out from behind. Every card in the console goes through that path: the home tiles, the library grid, the coverflow and the collections deck.
+- **The picture sat in the top-left corner of an Android screen.** The video layer took the size of the view once, at the moment it was created — and the stream screen hides the system bars and expands into the display cutout a frame or two later, each of which grows the view underneath a layer that never hears about it. The size is now read fresh for every frame, which also means rotating the phone and multi-window both simply work.
+- **Settings and your game library could not be reached with a television remote.** A remote has a directional pad, OK and Back, and the console had put Settings and the library shelf on controller face buttons it does not have — so on an Android TV neither could be opened at all. Pressing down on the home row now opens Settings, and the library has joined each machine's own options menu, which is where the documentation had been telling you to find it all along. The on-screen hints name whichever route the device in your hand actually has.
+- **On Nobara, "Switch to Desktop" during a stream threw you straight back into the stream.** The switch takes the picture away, Punktfunk reads that as a problem and rebuilds the session, and the rebuild put Gaming Mode back over the desktop that was trying to start. 0.31.0 changed how the host takes Gaming Mode over and left nothing watching for the switch, which Steam Deck and Bazzite machines never noticed because they follow it another way — Nobara has neither. Also fixed on both: a mid-stream switch used to leave Gaming Mode replaced by a placeholder, so the machine's own "Return to Gaming Mode" afterwards started something that did nothing. Both routes now hand the machine back intact.
+- **On NixOS the host installed a compositor consisting only of its launcher.** The packaging trims the installed programs down to the one that is needed and had been matching it by name — but the program with that name is a small launcher that sets things up and then runs the real compositor, which the trim deleted. What shipped was a launcher pointing at nothing. That is the true cause of the version banner printing nothing, the marker "missing from the binary", and every HDR-related NixOS failure chased alongside them. Separately, NixOS was the only channel not pinning which compositor version it patches, so a package update could and did break the build outright — and since HDR is on by default, that failure landed on anyone enabling the host at all.
+
+## Thanks
+
+Every fix above came from someone describing precisely what did not happen. The Windows black screen was found in two field logs from a host that looked healthy in every respect; the dead controllers in Moonlight-compatible sessions were reported with the detail that made them findable, that it reproduced on every client and device tried; the Fire TV report named which button arrived as which; and one Android user sent two reports in a day that turned out to be the same mistake made twice. Thank you — that is what makes a fault findable rather than merely believable.
+
+## For developers
+
+Protocol, ABI, driver and embedder detail — including the version table — is in [CHANGELOG.md](https://git.unom.io/unom/punktfunk/src/tag/v0.31.1/CHANGELOG.md).
+
+The short version: the streaming protocol, the embedding interface, the driver protocol and the gamepad channel are all exactly where 0.31.0 left them, so nothing needs rebuilding, re-pairing or re-packaging in any direction. The management API and the add-on toolkit each gain one thing by pure addition — the running-report route above, and the toolkit call for it in 0.4.4 — and an add-on that ignores both keeps working unchanged. One control message is added to the wire — clients reporting how much they have received, which is what lets a host tell a dead video path from a clean one — but it takes a spare message number rather than changing an existing message, and an older host on the other end ignores it after one note in its log.

docs/releases/whatsnew/v0.31.1.txt

@@ -0,0 +1,4 @@
+• Fixes every console-only setting doing nothing when you changed it — low latency, rumble, motion and controller capture all went nowhere.
+• Fixes controllers pressing the wrong buttons on boxes Android has no layout for — on a Fire TV a DualSense's L2 arrived as L1.
+• The controller console can now be switched off from inside it, and a TV remote can reach Settings and your library.
+• The picture no longer sits in the top-left corner.

include/punktfunk_core.h

@@ -1224,6 +1224,11 @@
 #define PUNKTFUNK_MSG_PIPELINE_GAP 10
 #endif
 
+#if defined(PUNKTFUNK_FEATURE_QUIC)
+// Type byte of [`DeliveryReport`].
+#define PUNKTFUNK_MSG_DELIVERY_REPORT 11
+#endif
+
 #if defined(PUNKTFUNK_FEATURE_QUIC)
 // Type byte of [`ProbeRequest`].
 #define PUNKTFUNK_MSG_PROBE_REQUEST 32

packaging/gamescope/PKGBUILD

@@ -19,7 +19,7 @@ pkgname=punktfunk-gamescope
 # bump it with the marker so pacman sees a new version when only our patches moved.
 _gsver=3.16.25
 _gsrev=5fb8dce4a09d0a68d097b9faf9513782106bc843
-pkgver="${_gsver}.pfhdr7"
+pkgver="${_gsver}.pfhdr8"
 # 2: patch 0006 (never destroy the Vulkan device/output at exit). No capability moved, so the
 # `.pfhdrN` level deliberately stays put — see README.md.
 # 3: pin moved 8c676c39 -> 5fb8dce4 (3.16.25-1 -> 3.16.25-11), which brings upstream's own
@@ -45,6 +45,11 @@ pkgver="${_gsver}.pfhdr7"
 # racing steamcompmgr's vulkan_screenshot on the same device — a SIGSEGV precisely in the linger
 # window, so a kept display was dead and reconnect lost the game session. No capability the host
 # probes for, but "reconnect lost my game" triage has to read the difference off the banner.
+#
+# pfhdr8 / rel 1: patch 0010 gives the seat's stub keyboard the compiled `XKB_DEFAULT_*` keymap, so
+# a session follows the box's configured layout instead of typing US characters. The host PROBES the
+# banner for this one (`>= 8`), so the level HAS to move here too — leaving it at pfhdr7 made pacman
+# see no upgrade at all, and every Arch/SteamOS host kept a compositor the probe rejects.
 pkgrel=1
 pkgdesc="gamescope with 10-bit BT.2020/PQ PipeWire capture, for punktfunk HDR streaming"
 arch=('x86_64' 'aarch64')

packaging/nix/gamescope.nix

@@ -31,11 +31,39 @@
 {
   lib,
   gamescope,
+  fetchFromGitHub,
   python3,
   patchDir,
   manifestRewriter,
 }:
 let
+  # PIN THE COMPOSITOR SOURCE, rather than patching whatever gamescope nixpkgs happens to carry.
+  # Every other channel already ships this exact commit — packaging/gamescope/README.md,
+  # punktfunk-gamescope.spec, the PKGBUILD and build-punktfunk-gamescope.sh — and nix was the
+  # only one tracking nixpkgs' version and hoping ten patches still applied.
+  #
+  # They did not, and the failures were not academic (MEASURED 2026-08-19/20):
+  #   * nixpkgs shipped 3.16.24 and patch 0009's context did not exist there at all, so the
+  #     build died at patchPhase — every `services.punktfunk.host.enable = true` with it.
+  #   * bumping the lock to 3.16.25 fixed that, then `--version` printed NOTHING: upstream's
+  #     `gamescope::PrintVersion()` landed AFTER the 3.16.25 tag. The host reads that banner to
+  #     decide a session's bit depth and cursor compositing BEFORE the virtual display exists,
+  #     so a silent banner means a silent fall back to SDR — the exact failure every guard in
+  #     this file is written to prevent.
+  # Both are the same bug: nixpkgs' gamescope is older than the tree these patches target.
+  # Pinning makes the nix package agree with every other channel byte for byte.
+  #
+  # Bumping this: move the rev, then `nix-prefetch-git --url https://github.com/ValveSoftware/gamescope
+  # --rev <new> --fetch-submodules` for the hash, and keep packaging/gamescope/README.md in step.
+  pfRev = "5fb8dce4a09d0a68d097b9faf9513782106bc843";
+  pfVersion = "3.16.25-11-g5fb8dce";
+  pfSrc = fetchFromGitHub {
+    owner = "ValveSoftware";
+    repo = "gamescope";
+    rev = pfRev;
+    fetchSubmodules = true;
+    hash = "sha256-pGBiO+7LSdIc0k9K+SQnv/Og2DYD/cjvOImxIl91L2A=";
+  };
   # As of nixos-unstable (checked 2026-07-28) `gamescope` IS the buildable derivation — pname
   # "gamescope", version 3.16.25, carrying `src`/`patches`/`mesonFlags`. Revisions that wrap it
   # (to wire the WSI layer + capabilities) expose the build as `.unwrapped`, so prefer that where
@@ -76,6 +104,8 @@ let
 in
 unwrapped.overrideAttrs (old: {
   pname = "punktfunk-gamescope";
+  version = pfVersion;
+  src = pfSrc;
 
   # Read the patch DIRECTORY rather than naming files: `builtins.attrNames` sorts
   # lexicographically, which for `000N-` prefixes is exactly the apply order, and a patch added or
@@ -96,7 +126,19 @@ unwrapped.overrideAttrs (old: {
     substituteInPlace src/meson.build \
       --replace-fail \
         "vcs_tag = run_command(vcs_tag_cmd, check: false).stdout().strip()" \
-        "vcs_tag = '${old.version}'"
+        "vcs_tag = '${pfVersion}'"
+
+    # Source-level gate, the same one packaging/gamescope/build-punktfunk-gamescope.sh applies.
+    # Splits a missing marker into its two possible stages: fire HERE and patch 0005 or the
+    # substitution above lost it; pass here and fail the ELF check later, and it was lost in
+    # meson configuration or compilation instead. Without this the two are indistinguishable,
+    # at a full compositor build per guess.
+    grep -q '+pfhdr' src/meson.build || {
+      echo "punktfunk-gamescope: +pfhdr is not in src/meson.build after patching" >&2
+      echo "  --- version block as patched: ---" >&2
+      sed -n '/^vcs_tag_cmd/,/^gamescope_version_conf/p' src/meson.build | sed 's/^/    | /' >&2
+      exit 1
+    }
   '';
 
   # Ship the compositor, renamed, AND the WSI layer built beside it. Everything else nixpkgs
@@ -134,7 +176,17 @@ unwrapped.overrideAttrs (old: {
     chmod -R u+w $out
 
     find $out -mindepth 1 -maxdepth 1 ! -name bin -exec rm -rf {} +
-    find $out/bin -mindepth 1 ! -name gamescope -delete
+    # KEEP `.gamescope-wrapped`. nixpkgs wraps this package: makeWrapper leaves the real
+    # compositor ELF at bin/.gamescope-wrapped and installs a small launcher at bin/gamescope
+    # that sets PATH (xwininfo) before exec'ing it. A prune that keeps only `gamescope` deletes
+    # the compositor and ships the launcher alone — MEASURED 2026-08-20 (run 19622): $out/bin
+    # held a single 16 KB file, `--version` printed nothing because the launcher exec'd a path
+    # that no longer existed, and no +pfhdr marker was present because a wrapper carries no
+    # version string. Every symptom chased for three builds came from this one line.
+    #
+    # The launcher references its target by ABSOLUTE path, so renaming the launcher is safe
+    # while the target keeps its name.
+    find $out/bin -mindepth 1 ! -name gamescope ! -name '.gamescope-wrapped' -delete
     mv $out/bin/gamescope $out/bin/punktfunk-gamescope
 
     install -Dm0755 "$TMPDIR/pf-layer.so" \
@@ -147,8 +199,38 @@ unwrapped.overrideAttrs (old: {
   doInstallCheck = true;
   installCheckPhase = ''
     runHook preInstallCheck
-    $out/bin/punktfunk-gamescope --version 2>&1 | grep -q '+pfhdr' \
-      || { echo "punktfunk-gamescope: the +pfhdr marker is missing — the patches did not take"; exit 1; }
+    # Assert the marker is compiled INTO the shipped binary, rather than running it.
+    #
+    # Running it does not work here and never did: `--version` produced EMPTY output under the
+    # build sandbox on BOTH nixpkgs' 3.16.25 and the pinned 5fb8dce4 (MEASURED 2026-08-19/20,
+    # runs 19551 / 19573 / 19594). That is a property of the sandbox, not a defect in the binary:
+    # gamescope calls PrintVersion() before the getopt loop (src/main.cpp:721 at the pinned rev),
+    # so `gamescope --version` DOES print the banner on a real system — which is what the host's
+    # capability probe reads.
+    #
+    # packaging/gamescope/build-punktfunk-gamescope.sh makes the same call, asserting on
+    # src/meson.build. Grepping the installed ELF is strictly stronger: the version string reaches
+    # .rodata through GamescopeVersion.h's k_szGamescopeVersion, so this proves the marker survived
+    # patching, meson configuration AND compilation into the artifact we actually ship, and it
+    # cannot be defeated by the binary being unable to start.
+    # Grep the WRAPPED ELF: bin/punktfunk-gamescope is nixpkgs' launcher and carries no version
+    # string at all, so asserting on it would pass only by accident. Fall back to the launcher
+    # for a future nixpkgs that stops wrapping.
+    gsElf=$out/bin/.gamescope-wrapped
+    [ -f "$gsElf" ] || gsElf=$out/bin/punktfunk-gamescope
+    grep -aq '+pfhdr' "$gsElf" || {
+      echo "punktfunk-gamescope: the +pfhdr marker is not in the installed binary." >&2
+      echo "  src/meson.build carried it (asserted in postPatch), so it was lost between" >&2
+      echo "  meson configuration and the linked artifact. Evidence:" >&2
+      echo "  --- $out/bin ---" >&2
+      ls -l $out/bin 2>&1 | sed 's/^/    | /' >&2
+      echo "  --- anything under $out mentioning pfhdr ---" >&2
+      grep -ral 'pfhdr' $out 2>/dev/null | sed 's/^/    | /' >&2 || echo "    | (nothing)" >&2
+      echo "  --- version-ish strings in the binary ---" >&2
+      grep -aoE '[0-9]+\.[0-9]+\.[0-9]+[^ ]*' "$gsElf" 2>/dev/null \
+        | sort -u | head -5 | sed 's/^/    | /' >&2 || true
+      exit 1
+    }
     # The manifest must name a library this derivation actually installed. A manifest pointing at a
     # path that does not exist is the worst shape of this bug: the loader reads it, finds nothing,
     # and carries on silently, so the box looks healthy and every game renders SDR.

plugin-kit/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@punktfunk/plugin-kit",
-	"version": "0.4.3",
+	"version": "0.4.4",
 	"description": "Effect-based framework for punktfunk plugins: lifecycle runtime, config/state, sync engine, UI serving, CLI scaffold, and browser helpers.",
 	"type": "module",
 	"license": "MIT OR Apache-2.0",

plugin-kit/src/index.ts

@@ -22,6 +22,7 @@ export {
 } from "./paths.js";
 export {
 	Artwork,
+	DEFAULT_RUNNING_TTL_S,
 	DetectHint,
 	GameMeta,
 	LaunchSpec,
@@ -29,6 +30,8 @@ export {
 	ProviderClient,
 	type ProviderClientService,
 	ProviderEntry,
+	type RunningAccepted,
+	type RunningTitle,
 } from "./reconcile.js";
 export {
 	definePluginKit,

plugin-kit/src/reconcile.ts

@@ -9,6 +9,14 @@ import type { ProviderEntry } from "./wire.js";
 
 export * from "./wire.js";
 
+/**
+ * The host's liveness-report TTL, in seconds, when it does not say.
+ *
+ * Only a fallback for parsing an unexpected answer — the authority is the `ttlS` the host returns.
+ * A reporter should refresh at a fraction of this, so one missed call is not a lapse.
+ */
+export const DEFAULT_RUNNING_TTL_S = 90;
+
 /** What the host echoed back for one reconciled entry — enough to tell whether a claim took. */
 export interface ReconciledEntry {
 	readonly id: string;
@@ -35,6 +43,36 @@ export interface ProviderClientService {
 		entries: ReadonlyArray<ProviderEntry>,
 		store?: string,
 	) => Effect.Effect<ReadonlyArray<ReconciledEntry>, HostRequestError>;
+	/**
+	 * Report which of this provider's titles are running **right now** — the live counterpart to the
+	 * static `detect` hints in {@link reconcile}.
+	 *
+	 * `detect` says *how to recognize* a title's process; this says *it is running*, and carries the
+	 * pid where the provider knows one. For a launcher that starts games itself and is told when
+	 * they stop, this is a fact the host would otherwise re-derive by scanning — and for a title
+	 * with nothing to scan for (an emulated game, a manually added one, a launcher that records no
+	 * install directory) could not derive at all: its lease is `untracked`, its exit is never
+	 * noticed, and the streaming session outlives the game.
+	 *
+	 * **Send the complete set, not a delta.** Anything absent is reported stopped, so a missed
+	 * event, a plugin restart or an install mid-game all self-correct on the next call.
+	 *
+	 * **The host expires a report** (`ttlS` in the answer, 90s at the time of writing) unless it is
+	 * restated — which is what makes it safe for the host to keep a session open for a game it
+	 * cannot see. Call this on every change **and** on a timer well inside that window while
+	 * anything is running; a plugin that stops reporting simply hands tracking back to the host's
+	 * process scan.
+	 *
+	 * Titles the host has no entry for are counted in `unknown`, not refused: a report may
+	 * legitimately race its own reconcile.
+	 *
+	 * Fails on a host that predates the route (404) — treat that as "this host tracks games by
+	 * scanning" and carry on, exactly as with any other optional capability.
+	 */
+	readonly reportRunning: (
+		providerId: string,
+		running: ReadonlyArray<RunningTitle>,
+	) => Effect.Effect<RunningAccepted, HostRequestError>;
 	/**
 	 * Remove every entry this provider owns **and release its store claim** (the explicit-uninstall
 	 * path). Releasing is what brings the host's built-in scanner back.
@@ -44,6 +82,29 @@ export interface ProviderClientService {
 	) => Effect.Effect<void, HostRequestError>;
 }
 
+/** One running title in a {@link ProviderClientService.reportRunning} call. */
+export interface RunningTitle {
+	/** The provider's own stable id — the same key its reconcile payload uses. */
+	readonly external_id: string;
+	/**
+	 * The process the provider started for it, when it knows one. Optional, and never trusted as a
+	 * bare number: the host re-resolves it and pins it to its start time before it is ever
+	 * signalled, so a stale or recycled pid contributes nothing. Worth sending anyway — it is what
+	 * gives "End game" something to aim at for a title the host's matcher cannot find.
+	 */
+	readonly pid?: number;
+}
+
+/** What the host answered to a liveness report. */
+export interface RunningAccepted {
+	/** How many reported titles matched an entry this provider currently publishes. */
+	readonly matched: number;
+	/** How many were ignored because no such entry exists (a report that raced a reconcile). */
+	readonly unknown: number;
+	/** Seconds the report stays authoritative without being restated. */
+	readonly ttlS: number;
+}
+
 export class ProviderClient extends Context.Service<
 	ProviderClient,
 	ProviderClientService
@@ -72,6 +133,27 @@ export class ProviderClient extends Context.Service<
 										: [],
 								),
 							),
+					reportRunning: (providerId, running) =>
+						host
+							.request("PUT", `/library/provider/${providerId}/running`, {
+								running,
+							})
+							.pipe(
+								// Same posture as the reconcile echo above: the counts are a
+								// diagnostic, not a contract, so a host that answers something
+								// unexpected must not fail a plugin's report loop. The TTL falls
+								// back to the host's own documented default.
+								Effect.map((body) => {
+									const b = (body ?? {}) as Record<string, unknown>;
+									const num = (v: unknown, fallback: number) =>
+										typeof v === "number" && Number.isFinite(v) ? v : fallback;
+									return {
+										matched: num(b.matched, 0),
+										unknown: num(b.unknown, 0),
+										ttlS: num(b.ttl_s, DEFAULT_RUNNING_TTL_S),
+									} satisfies RunningAccepted;
+								}),
+							),
 					remove: (providerId) =>
 						host
 							.request("DELETE", `/library/provider/${providerId}`)

scripts/ci/docs-undocumented-env-baseline.txt

@@ -180,6 +180,7 @@ PUNKTFUNK_MSG_CLOCK_ECHO
 PUNKTFUNK_MSG_CLOCK_PROBE
 PUNKTFUNK_MSG_CURSOR_RENDER
 PUNKTFUNK_MSG_CURSOR_SHAPE
+PUNKTFUNK_MSG_DELIVERY_REPORT
 PUNKTFUNK_MSG_LOSS_REPORT
 PUNKTFUNK_MSG_PAIR_CHALLENGE
 PUNKTFUNK_MSG_PAIR_PROOF