punktfunk/CHANGELOG.md

# Changelog

Protocol, ABI, driver and embedder detail, one section per stable release, newest first.

This is the **technical** half of a release. The other half — what changed for people who *use*
Punktfunk — is `docs/releases/vX.Y.Z.md`, and it deliberately contains no internal names. The two
were one document through v0.24.0; they split at v0.25.0 because the engineering section had grown
long enough to bury the user-facing half it was appended to. See `docs/releases/README.md`.

If you embed `punktfunk-core`, package Punktfunk, or write a plugin, this file is for you. Start
with the version table of the release you are moving to, then read **Breaking changes**.

---

## v0.31.3

41 commits since v0.31.2 (26 non-merge), counted at the tip this was cut from.

**One versioned surface moves, and additively: the management API.** `WIRE_VERSION` stays **2**, the
C ABI stays **25** — `include/punktfunk_core.h` is **byte-identical to the v0.31.2 tag**, as it was
to v0.31.1 — and so do the driver protocol, the gamepad channel, the plugin index schema and the
host event schema. `pf-driver-proto` shows no diff. No `#[repr(C)]` struct moves and no C function
changes signature, so an embedder takes this release without recompiling anything.
`api/openapi.json` gains **one route and one field** (`PATCH /clients/{fingerprint}`, the
`RenameClient` schema, and `PairedClient.label`); nothing existing changes shape, so a consumer that
ignores both is unaffected. **`@punktfunk/host` is re-cut to 0.1.6** so a plugin can actually reach
the generated types for that route; `@punktfunk/plugin-kit` stays at 0.4.4. One dependency moves,
lockfile-only, for a security advisory.

The cycle is fix-shaped and the faults share a family resemblance: **a session degrading or ending
against something ordinary that nothing was checking**. The host mistaking Steam's pre-launch trees
for the game and then reading their exit as the game's (#372); a fullscreen game mode-setting the
virtual display under both stream loops, which no in-place encoder rebuild can converge on (#373);
the forced-keyframe coalesce window measured in frames rather than time (#377); an Android TV
negotiating the refresh its own console pin had installed rather than what the panel outputs
(#378); a startup capacity probe large enough to black-hole the link it was measuring (#379); a
hand-back that never verified the panel came back (#375); a half-minted audio devnode that nothing
afterwards recognised (#381); and a failed compositor build that unlinked the working one it never
replaced (#382). Alongside: two Android input/present fixes (#376, #380), the console's
per-frame cost and its new resolution switch (#384, #385), one feature (#374), and CI (#370, #383).

### Versions

| | v0.31.2 | v0.31.3 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged. No message added, removed or re-shaped |
| C ABI | 25 | **25** | unchanged. `include/punktfunk_core.h` has **no diff at all** against the v0.31.2 tag — the second release running |
| 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.2 tag |
| Windows virtual-gamepad channel | 3 | **3** | unchanged. #374 exercises the UMDF HID pad through `devtest` but changes no backend |
| Plugin index schema | 1 | **1** | unchanged |
| Host event schema | 1 | **1** | unchanged (`punktfunk-host/src/events.rs`) |
| `api/openapi.json` | 0.31.2 | **0.31.3** | **additive**: one route (`PATCH /clients/{fingerprint}`), one schema (`RenameClient`), one response field (`PairedClient.label`), plus the `info.version` stamp. Regenerated in #374 on a runner where `openapi_document_is_complete_and_checked_in` executes; **re-stamped** here, not regenerated — `punktfunk-host` does not build on macOS. `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` still declares `pfhdr8`. #382 fixes the Deck **source** build, not the patch set |
| `@punktfunk/host` (SDK) | 0.1.5 | **0.1.6** | **cut**, for the generated client `sdk/src/gen/punktfunk.ts` — it carries `PATCH /clients/{fingerprint}`, `RenameClient` and `PairedClient.label`, and a plugin resolves `@punktfunk/host` from the registry, so those types reach nobody until a version ships them. `SDK_VERSION` moves with `package.json`; see the drift note at the end |
| `@punktfunk/plugin-kit` | 0.4.4 | **0.4.4** | unchanged; nothing under `plugin-kit/` moved. 0.4.4 remains the registry's `latest` |

### ⚠ Breaking changes

**None.** No wire change, no ABI change, no driver-protocol change, no plugin-contract change, and
the one API change is additive. Every 0.31.x host, client, driver and plugin keeps interoperating in
both directions with no re-pairing and no rebuild.

Five **behaviour** changes that break no build but change what a machine does:

- **`GameRunning` is reported up to `SHIM_WINDOW` (5 s) later than before** for a lease matched by
  process scan. A scan match must now be seen *continuously* for that window before it latches out
  of the start phase. A provider plugin's runstate report still latches immediately — that is the
  launcher's own statement, not an inference — and exit detection is untouched.
- **The GameStream stream loop now re-opens the encoder at a source-driven mode**, and does not tell
  the client. GameStream has no mid-stream mode-change message, so Moonlight decodes a bitstream
  that disagrees with the resolution it configured its decoder from. Tolerant decoders re-init off
  the SPS; a strict one (Media Foundation on Xbox) may stall. This is the same bargain the first
  open in that function already takes for the monitor-mirror case (§7.3), and the alternative it
  replaces is ending the session outright.
- **`GET /api/v1/clients` grows `label`**, and `PairedClient.subject` is now documented as *not* a
  device name. A console or integration that displayed `subject` should prefer `label` and fall back
  to `subject` only when it is unset.
- **The startup capacity probe no longer bursts at a flat 2 Gbps.** Its target is derived from
  `stream_cap_kbps × 2`, still capped at 2 Gbps. `PUNKTFUNK_ABR_PROBE_KBPS` and its `> 0` filter are
  unchanged, so an embedder that pins the probe explicitly sees no difference.
- **Android no longer pins the panel to its highest refresh mode on a TV.** `highRefreshModeId`
  stays 0 there, which `setConsoleHighRefreshRate` already treats as a no-op. Phones and tablets are
  unaffected — the pin exists for their refresh governors.

### `PATCH /clients/{fingerprint}`: an operator label for a paired client

Every moonlight-common-c client self-signs with the same fixed subject (`CN=NVIDIA GameStream
Client`), so the certificate carries no device identity at all: five paired devices are five
identical rows, distinguishable only by fingerprint prefix — most sharply when choosing which to
unpair. Reported from the field as a rename request.

The label is operator-supplied and stored host-side, keyed by fingerprint:

- **`client-labels.json`, a SIDECAR to `paired.json`, not a field inside it.** `paired.json` is a
  bare `Vec<Vec<u8>>` of DERs; giving it a shape would be a migration on the one file that decides
  who may connect, and a label is not part of that trust decision — a corrupt or missing label file
  must never be able to lock anybody out. Every read failure degrades to "no names". Writes take the
  same atomic temp-file + rename as `save_paired`, serialized by `LABELS_LOCK` so two concurrent
  renames cannot lose one of the two names in a whole-file rewrite. Fingerprints are normalized to
  lowercase hex.
- **Route semantics.** A whitespace-only body **clears** rather than storing a blank name; only an
  already-paired fingerprint may be named (a label for an unknown one would be invisible and never
  cleaned up); unpairing forgets the label, so the file cannot grow without bound and re-pairing the
  same certificate starts unnamed.
- **Scrubbing reuses `native_pairing::sanitize_device_name`** rather than growing a second one — it
  already strips C0/C1 controls and Unicode bidi overrides and caps at 64. That is not cosmetic
  here: the label is the *only* thing distinguishing two paired devices in the console, so an
  unscrubbed one could dress a stranger's device up as the operator's TV and be spared an unpair on
  that basis.
- **Lanes.** The new route takes the plugin/cert lanes of the `DELETE` beside it — neither may reach
  it — not the roster `GET`'s read permission.
  `every_route_is_classified_for_the_plugin_and_cert_lanes` pins that.
- **Console.** A pencil on Moonlight rows opens the existing `promptText` dialog seeded with the
  current label, not the `CN=…` fallback (or every rename would start by deleting boilerplate).
  Native rows keep their pairing-supplied name and get no pencil.

Test: `client_label_round_trips_scrubs_and_is_forgotten_on_unpair` — name it, see it in the list,
watch a bidi override and collapsed whitespace get scrubbed, clear it two ways, reject a malformed
and an unpaired fingerprint, and assert the unpair forgot it on disk.

### The encoder follows an autonomous source mode or format change

A fullscreen game can mode-set the virtual display mid-session with no client `Reconfigure`. The
IDD-push capturer already handles that — it re-opens its ring at the new mode on a confirmed
descriptor change — but nothing re-opened the **encoder**, which is the one component that cannot
follow a resolution change in place. Every submit then failed with `captured frame 1920x1080 !=
encoder 3840x2160`, and the submit-error path only rebuilds the encoder IN PLACE, at the SAME
configured size, which cannot converge on a size the source has already left. All five resets burned
on it and the video session ended ~3 s later with audio still running.

Field report 2026-08-22 (host 0.31.2, RX 6800 XT, AMF/HEVC 4K60):

```
IDD push: display descriptor changed — recreating the ring at the new mode
  target_id=259 from=3840x2160 hdr=true to=1920x1080 hdr=true
encoder submit failed — encoder rebuilt in place, forcing an IDR
  error=captured frame 1920x1080 != encoder 3840x2160 reset=1 max=5
... reset=5 max=5
encoder did not recover after repeated in-place rebuilds — ending the video session ... resets=6
```

Both stream loops now track what the encoder was opened against `(format, width, height)` and, when
the source delivers something else, re-open through the same `open_video` path a client-initiated
resize uses:

- **Native (`native/stream.rs`)** publishes the new mode to the client exactly as an accepted resize
  does, so its mode slot, stats and aspect follow. PyroWave's `Automatic` rate is re-resolved for
  the new mode — it is a per-mode bpp pin, so carrying the old one across hands the encoder the
  wrong operating point; H.26x rates stay with ABR, and an explicit client rate is never
  second-guessed.
- **GameStream (`gamestream/stream.rs`)** does the same bookkeeping the capture-loss rebuild in that
  loop already does (ring depth, RFI caps, forced IDR, in-flight numbering restart), and derives
  `gs_bit_depth(frame.format)` per open so an HDR flip that recreates the ring at P010 re-opens at
  the right depth. It cannot notify the client; see the behaviour note above.

A failed re-open does **not** end the session on the first try: the mode-set is exactly the kind of
event that leaves the driver settling, which is the transient the submit path's backoff exists for
("NVENC session open failing after a codec switch", 2026-07). It spends the shared `encoder_resets`
budget at the existing exponential pace (100 ms → 1.6 s), re-entering the follow-the-source guard
each round — the same ~3 s ceiling as before, but every round is now a real attempt at the new mode
rather than an in-place re-init that cannot converge. The exhausted path is tagged accurately as an
encoder **reopen** failure, not a submit failure.

This also covers a mid-session frame-format change (an HDR flip re-creating the ring at a new
format), which failed identically.

### The forced-keyframe coalesce window gets an absolute floor

`keyframe_coalesce` was `frame_interval * 2`. The window bounds IDR emission in **time** — it has to
outlast the round trip in which the client receives and decodes the IDR it already asked for — so a
frame count is the wrong unit, and it collapses exactly where it matters: 16.7 ms at 120 fps, while
a Moonlight client that has lost decode sync re-asks roughly every 30 ms. The gate never closed
between requests, so effectively every request became a full keyframe, whose bulk saturates the send
path, which causes the loss that prompts the next request. The storm sustains itself and reads as
stutter at a flat latency, because frames are being lost rather than queued.

Field log (AMD RX 7800 XT, Bazzite 44, 1080p120 HEVC over the GameStream plane): **1118 IDR requests
in one 91 s session, 1115 honoured, 3 coalesced** — about one full IDR every tenth frame at a
100 Mbps target. The same session's H.264 leg (libav VAAPI, same bitrate) took 2 requests and was
clean, which is what made it read as an HEVC fault.

`keyframe_coalesce_window(frame_interval)` is now `(frame_interval * 2).max(100 ms)`. 100 ms matches
the encoder-reset backoff in the same loop and is about one IDR's service time on a saturated link.
Note this is **not a 120-only fix**: 60 fps sat at 33.3 ms, also under the floor. A slow stream keeps
the frame-scaled window — the floor only ever raises it. NVENC ref-invalidation (cheap, no IDR
spike) is still never rate-limited. `keyframe_coalesce_window_outlasts_a_clients_request_cadence`
pins all three cases.

### The game lease stops latching on Steam's pre-launch trees

`reaper SteamLaunch AppId=<appid>` is the **appid's** wrapper, not the game's, and Steam wraps its
pre-launch work for a title in one too — so a launch is a chain of appid-tagged trees and only the
last is the game. The lease matched the first tree two seconds in, and that single sighting latched
it out of `START_GRACE` (300 s, ending nothing) into `EXIT_CONFIRM` (3 s, ending the session). When
that tree exited with the game still starting, the watch called it the game exiting and closed the
connection with `APP_EXITED`. Reported as having to launch Rocket League twice: the first launch
streamed the "Processing Vulkan shaders" dialog and dropped ten seconds in.

Linux has nothing else to catch it — `procscan::running_hint` is Windows-only and no provider
reports runstate for Steam, so an appid scan with three seconds of slack is the whole signal.
(Steam's `registry.vdf` is not an option: `RunningAppID` is no longer set on modern Steam Linux, and
the per-app `Running` key is unreliable.)

Two layers, because only one of them can be certain:

- The matcher **rejects** a `SteamLaunch AppId=` reaper whose payload is `fossilize_replay` —
  Steam's shader replayer, never a game. `program_name` handles the full-path form.
- A scan match must be seen **continuously for `SHIM_WINDOW`** before it latches. This is the rule
  already applied to a spawned child ("a launcher about to hand off looks exactly like the game for
  its first few seconds"); the scan side never had it. It bounds the pre-launch trees nobody has
  named yet, at the cost of the `GameRunning` latency in the behaviour note above.

Exit detection is untouched, and a provider report still latches immediately. Diagnostics: the log
said `procs=1` and never *which* process, which is what made this unclosable from a log alone —
`procscan::names` puts the short names on the line.

### The startup capacity probe is sized from the session, not from a flat ceiling

The probe burst at a flat 2 Gbps on the reasoning that it must measure the link and not itself. That
reasoning is obsolete: the ABR already clamps the measured ceiling to `stream_cap_kbps` (what this
session's mode + codec could plausibly use), so **every bit measured above `cap / 0.7` is discarded
the moment it lands**. The height bought a number nothing reads and paid bufferbloat for it — a
constrained link can black-hole under it. Measured on webOS: a 6 s probe timeout delaying first
video to **14 s**, and a "successful" probe still reporting `send_dropped=20211`; the same shape is
now reported on a Fire TV Stick 4K Max.

The target is `stream_cap_kbps × 2`, capped at the old 2 Gbps. **×2 is the smallest multiplier that
can still prove the cap** — the ceiling is `delivered × 0.7`, so proving `cap` needs
`delivered ≥ cap × 1.43` — so this can never cap anyone: a session whose mode justifies a high
ceiling asks for a high target by itself, and a mode `stream_ceiling_kbps` declines to size still
gets 2 Gbps. Deliberately **not** a platform `cfg!`: the constraint is the session's, not Android's,
and webOS has the same bug.

Second half of the black screen: if the burst takes the first keyframe down with it, nothing
re-requested one and the client sat on black until an unrelated recovery path happened to fire. A
keyframe is now requested at probe end when no frame completed across the burst — compared against
the count snapshotted at the burst's **leading edge** rather than against 0, so it also covers a
mid-session embedder speed test that kills a running stream. One request per probe, through the
control task's coalescer, so it cannot IDR-storm.

### Android: the console's high-refresh pin is not applied on a TV

Field report: on Android TV / Fire Stick, latency explodes whenever the client's refresh differs
from the host's, and setting the refresh by hand is the only workaround. The client was
manufacturing that mismatch itself, in three steps:

1. `MainActivity.onCreate` pins the panel to its highest-refresh mode for the console UI
   (`setConsoleHighRefreshRate(true)`) — unconditionally, TVs included. That pin exists for phone
   refresh governors (Nothing OS's LTPO logic among them) which cap third-party apps at 60 Hz. No TV
   has one.
2. At connect, `nativeDisplayMode` resolves "Native" refresh from `display.mode` — which now reports
   the mode the pin installed, not the TV's real HDMI output. So the session negotiates (say) 120.
3. `StreamScreen` releases the pin again on TV, by design: there the decoder's own
   `setFrameRate(CHANGE_FRAME_RATE_ALWAYS)` governs the HDMI mode. The panel falls back to 60 while
   the host is already serving 120.

A 120 fps stream on a 60 Hz output, by construction, on exactly the two form factors in the report.
Picking a refresh explicitly is precisely what bypasses step 2, which is why that is the workaround
people found. The mode comparator sorts refresh before area, so the same pin could also drop a 4K TV
to 1080p120 and negotiate the stream at that.

Fixed at the choke point: `resolveHighRefreshMode` returns early on a TV, leaving `highRefreshModeId`
at 0, which `setConsoleHighRefreshRate` already treats as a no-op — so all three of its callers are
covered by the one guard.

Also in the same chain: `nativeDisplayMode` **truncated** the panel rate, so a TV reporting the
fractional NTSC rates over HDMI (59.94, 29.97, 23.976) asked the host for 59 / 29 / 23 — rates no
display mode has, which the host serves by clamping down to the highest it advertises at or below.
Rounded now, which also makes it agree with `MainActivity.streamPanelFps`; the two describe the same
panel and must not disagree.

### Android: `acquireLatestImageAsync` hands back a fence it already gave away

Every `pf-decode` SIGABRT on the Shield is fdsan catching a double-close of the acquire fence the ASC
presenter passes to `ASurfaceTransaction_setBuffer`, in three shapes: inside `Fence::Fence(int)`
under `setBuffer` when the number had already been re-owned (`fd N is owned by unique_fd, was
expected to be unowned`), at the end of `Transaction::apply` when the layer state is torn down, and
in `Parcel::freeDataNoInit` once the number churns.

The fence is not ours to give. `AImageReader::acquireLatestImage` drains with a **single `int*`
out-param it overwrites per image**, then releases each dropped image with whatever that out-param
currently holds — the successor's fence — and returns the last value written. So as soon as a burst
gives it two images to collapse, the caller receives an fd the reader has already adopted and
closed, plus one leaked fd per extra drop. **This is unfixed as of AOSP main**, so the newest-wins
collapse has to happen on our side.

Both present intents now drain with `acquireNextImageAsync`, whose fence is always a fresh dup we
exclusively own, and latency picks the newest itself — the loop the smoothing FIFO already ran.
Superseded candidates drop as before (image back to the pool, its own acquire fence closed). Reader
drops now show up in `skipped` instead of vanishing inside the reader lock.

### Android: a DualSense's buttons, touchpad click and Mute

Three defects reported against a Bluetooth DualSense on a Fire TV Stick 4K Max, **re-implemented
from #371's diagnosis**. #371 itself is not merged: all three problems are real and correctly
identified, but each fix as sent lands somewhere that breaks more hardware than it repairs.

1. **Some buttons never reach the stream.** Fire OS tags certain DualSense buttons `SOURCE_KEYBOARD`
   even though the keycodes are standard `BUTTON_*`, and `MainActivity`'s
   `event.isFromSource(SOURCE_GAMEPAD)` gate then drops them. The event's source class is the
   platform's per-event guess; the DEVICE's is the fact. New `MainActivity.fromPad` widens to the
   device — but ONLY for `KeyEvent.isGamepadButton` keycodes. That exclusion is the whole safety of
   it: DPAD keycodes are a keyboard's arrow keys and BACK is a remote's way out of the stream, and
   both share their keycodes with a pad. `Gamepad.isPad` is untouched (source-class only), and no
   vendor-id or device-name matching is added anywhere — the field report records both pads being
   IDENTIFIED correctly; only their button positions were wrong.
2. **Touchpad click and Mute were dropped.** Both have wire bits (`BTN_TOUCHPAD`, `BTN_MISC1`) and no
   Android keycode, so `GENERIC_SONY`'s `0x13d`/`0x13e` rows borrow `BUTTON_15`/`BUTTON_16` to carry
   them into `buttonBit`. Inside `GENERIC_SONY` and nowhere else: `0x13d`/`0x13e` are
   `BTN_THUMBL`/`BTN_THUMBR` — L3 and R3 — in the standard Linux mapping, and they mean touchpad and
   mute only inside the straight-through report order a driverless pad uses. A row in `SONY_MODERN`,
   or an override above `padMap(dev)`, would cost every Xbox pad, Switch Pro, 8BitDo, Steam Deck and
   hid-playstation DualSense both stick clicks. `correct()`'s `genericKeyCode` guard is unchanged.
3. **Mute toggles the mic** — once per press, and only on a pad that has one. Edge-triggered through
   the existing `completesChord` as the one-button chord it is: `onButton` still calls
   `slotButton(down = true)` on auto-repeat, so an unguarded check would flap the mic for as long as
   the button is held. Gated on a new `Slot.hasMuteButton`.

### The console's per-frame cost, and a resolution switch for 4K boxes

A field report of a sluggish console UI on a Fire TV Stick 4K Max and a Valerion projector. The Skia
shell is faster than the Compose one it replaced per unit of work; it was doing far more work than
anyone had counted, on every frame whether or not anything had changed. Four costs, **none of which
change a pixel**:

- `Fonts::paragraph` built a `ParagraphBuilder`, added its text and called `layout()` on every call —
  the whole shaper, HarfBuzz, line breaking and font fallback, for every string on screen, sixty
  times a second. Now built once per distinct `(text, shape, weight, size, width, colour)` and kept.
  Position is deliberately **not** in the key, so a shelf that scrolls and a screen that slides both
  re-use what they already shaped. Cold entries are dropped past a ceiling by the two frames that
  last drew them, so the live set is what is on screen and paging a large library cannot grow it
  forever.
- `LayerEnv::paint` raised an unbounded `save_layer` **unconditionally** — including on the settled
  path, where alpha is 1, scale is 1 and slide is 0. That allocates an offscreen the size of the
  whole SURFACE and composites it back, to apply an alpha of one, on every frame the console sat
  still. Skia does not elide it: `SkCanvas::saveLayerAlphaf` forwards alpha ≥ 1 straight to
  `saveLayer(bounds, nullptr)`, whose only early-out is an empty clip. On a 4K panel that is a
  **33 MB render target per frame against a 64 MB budget** on a 2 GB box — evicting real work to do
  nothing. Dropping it is pixel-identical rather than close: nothing in this crate draws with a
  blend mode other than `SrcOver`, `SrcOver` is associative, and there is no LCD subpixel text to
  gain or lose an isolation.
- The toast's layer was unbounded too, for a 34 dp pill; it takes the pill's rect now.
- `draw_clipped` measured its ellipsis fit by allocating a `String` **per character**, for every
  over-long title on screen, every frame. It measures out of a stack buffer now.

On the Android host the render thread takes the same priority lift the decode thread has always had
(`-8`, a band below the stream's `-10`, so the two do not compete when the console is up
mid-session). And the console logged its GLES version and cache budget but never its render
resolution or frame cost, so "it feels sluggish" could not be triaged from a log bundle at all — it
now names the surface size and reports mean and peak draw time once a minute, timed around the
**draw** and not the swap (`eglSwapBuffers` blocks on vsync, so wall-clock per iteration is always
the panel period and says nothing).

**`Reduce interface resolution`** (#384) is the lever that commit deliberately left out: an
off-by-default Android switch, under Reduce motion, capping the buffer's long edge at 1920 via
`SurfaceHolder.setFixedSize` and letting the compositor scale up. Two things it had to get right:
`setFixedSize` shrinks the BUFFER and not the VIEW, so everything speaking in surface pixels is
scaled to match — safe-area insets, the design-unit scale, and pointer coordinates, which a mouse
still reports in view pixels and which would otherwise land the cursor at twice its true offset (one
factor on both axes, so aspect survives exactly). And the buffer is sized from the `SurfaceView`'s
laid-out size via `onSizeChanged`, **not** `displayMetrics`, which has a long history of disagreeing
with a view's real size by a system bar. The factor reaches the pointer listeners through
`rememberUpdatedState` — `AndroidView`'s `factory` runs once, so a captured value would freeze at 1.

⚠ This is the INTERFACE only and shares nothing with the stream: picture size is `effectiveMode` off
`Display.mode.physicalWidth`, and picture scaling is the separate `renderScale`.

`platform_row_split_hides_only_the_other_platforms_concepts` pins the exact ordered set of rows the
desktop does not show; the new switch is Android-only by design, so #385 grows that expected list by
one between the Controllers action row and the console-UI switch. The row-COUNT assertion beside it
was already updated and passed, which is why only the ordered-set one went red.

### gamescope: the hand-back verifies the panel came back

Field reports on 0.31.x, Bazzite and Nobara: after disconnecting, the box's own physical screen stays
black. **It could not be reproduced** — #375 carries the full negative write-up, five scenarios
across both distro families on real VMs, all recovering cleanly, and the mechanism first proposed
disproved on glass. So this does not guess at the trigger; it closes the gap that lets ANY trigger
end as a dark panel.

`do_restore_tv_session` issued a lifecycle verb and logged what systemd said about the **job**. "The
job succeeded" and "the box shows a picture" are different questions, and nothing in that file had
ever asked the second — the restore walked away the moment the verb returned, so every way of ending
dark looked identical to success in the log.

It now measures. After the hand-back a detached watcher polls `detect_active_session()`, whose `None`
means no compositor of our uid is running at all — exactly the symptom. Still dark 25 s later, it
climbs a ladder of remedies, each measured on both images (Bazzite 44.20260818, Nobara f44,
2026-08-22):

1. **STOP** the autologin unit. Its login session's script is parked on `systemctl --user --wait
   start <unit>` on both images, so a stop releases that wait, the session exits, and `Relogin=true`
   logs back in — starting the unit inside a session with a seat. `stop`, not `restart`: a restart
   does **not** release the parked waiter (measured), which is why it cannot rescue a box the
   ordinary restart already failed to bring back.
2. Restart the display manager — what the pre-0.31.0 takeover did on every disconnect, and proven on
   the Bazzite VM to return the box to game mode.
3. `PUNKTFUNK_RECOVER_SESSION_CMD`, then an ERROR naming the command a human has to run.

### Windows audio: an abandoned devnode is adopted, and capture endpoints stamp the right hive

Minting an audio devnode is two PnP steps: `SetupDiRegisterDeviceInfo` makes it real and bindable,
then the owner marker goes into Device Parameters. A host that dies between them — the 0.30.0
TLS-destructor abort did exactly this, five times on one field box — leaves a registered,
driver-bound, endpoint-serving devnode carrying **no marker**.

Nothing resolved it afterwards. `find_role_devnode` matches on the marker, so the next pass minted a
SECOND devnode and the orphan stayed: a duplicate `Punktfunk Speakers` / `Punktfunk Microphone` in
the Sound zoo that no uninstall removed, because `devnode_cleanup` is marker-matched too. A field box
showed exactly this shape — `Punktfunk Speakers (3- Punktfunk)` beside an unstamped `Punktfunk
Speakers (4- Steam Streaming Speakers)`. Reproduced on .173 against the shipping 0.31.2 binary by
clearing the marker: `ROOT\MEDIA\0005` was minted and `0004` abandoned, still active and still
serving two live microphone endpoints.

- `minted.rs` **adopts before it mints**: an unmarked `ROOT\MEDIA\NNNN` devnode carrying the role's
  Steam hardware id is re-marked and reused, so the endpoint GUID survives and no device-change
  broadcast is paid.
- `devnode_cleanup` sweeps the same shape, so orphans already on a box go at uninstall instead of
  outliving the product.
- The instance prefix is what keeps both off Valve's own devices: Steam's devnodes carry these
  hardware ids and are ROOT-enumerated too, but live under `ROOT\SteamStreamingSpeakers\*` /
  `ROOT\SteamStreamingMicrophone\*`. Only `ROOT\MEDIA\*` can come from our
  `SetupDiCreateDeviceInfoW(DICD_GENERATE_ID)`. `is_abandoned_mint` carries that rule with unit
  tests.

Separately, `write_stamps` falls back to a raw-registry write when the property store denies it, and
that fallback built its path from `MMDEV_RENDER_PATH` **unconditionally** — so stamping the minted
microphone's CAPTURE endpoint reached for `…\MMDevices\Audio\Render\{capture-guid}\Properties`, a key
that cannot exist. `RegOpenKeyExW` failed, `write_stamps` returned the error, and `stamp_identity`
degraded to "keeps the driver's default name". Invisible to the pad program (render-only endpoints)
and on any box where the property store route succeeds — it only bites where the property store is
denied, exactly the boxes the ACL repair exists for. The hive now follows the direction the endpoint
id encodes, with render as the default for anything unrecognised. Unit-tested.

### Steam Deck: a failed gamescope rebuild took HDR from boxes whose compositor still worked

ROOT CAUSE of "HDR stopped working after updating to 0.31.2" on a Deck **source** install. Two
defects, one symptom.

1. `scripts/steamdeck/build-gamescope.sh` has been **unbuildable since 2026-08-13**, when `3ac4548c`
   turned `-Denable_gamescope_wsi_layer=true` on. The layer needs `x11-xcb`, which Debian splits into
   its own `libx11-xcb-dev`; the distrobox apt list — last touched 2026-07-31 — never got it.
   Measured on `debian:trixie` against that list verbatim, gamescope at the pinned `5fb8dce4`:
   `Run-time dependency x11-xcb found: NO` → `src/layer/meson.build:3:14: ERROR: Dependency
   "x11-xcb" not found`. `meson setup` exits 1 with the list as it was and 0 with `libx11-xcb-dev`
   added, and `build-punktfunk-gamescope.sh` treats a missing layer as a hard error, so the whole
   build fails. `ci/gamescope-trixie.Dockerfile` walked into the identical trap one release later
   (`1b28a7f7`, v0.28.1) and asserts x11-xcb at image build; this list never got the same fix.
   Debian-family only — Arch's libx11 and Fedora's libX11-devel carry `x11-xcb.pc`. `xkbcommon-x11`
   and `libdisplay-info` measured absent too and are added with it.
2. The build-failure branch then called `unwire`, deleting `PUNKTFUNK_GAMESCOPE_BIN` from `host.env`.
   **A failed build REPLACED NOTHING** — the previously installed binary is still on disk and still
   passes `verifies`. So a rebuild that never landed took HDR away from a box that had been streaming
   it minutes earlier: the script warns into a log nobody reads and exits 0, the update reports
   success, and the host then resolves the distro's stock `/usr/bin/gamescope` at patch level 0 and
   fixes the session at 8-bit SDR in the Welcome — which the `punktfunk/1` handshake cannot take
   back.

`libdisplay-info` is also pinned to the vendored subproject, like wlroots, so a system copy cannot
change what the build links.

### Measured and dropped: the UMDF pad input-silence theory

`devtest` grows `--idle-after N` / `--resume-after M`, which stop and restart the state frames while
still pumping, to test what a Moonlight client actually does. The hypothesis:
`UhidManager::heartbeat` documents that a UMDF pad "treats a multi-second input silence as an
unplugged controller", the native plane calls it every tick and `SessionPads::pump_rumble` does not
— and the two planes differ in exactly the way that would expose it, since punktfunk's own client
re-sends every live pad's snapshot every 100 ms (`input_task.rs` refresh tick) while
moonlight-common-c sends a controller packet only on **change**.

**Measured on .173 (Win11 26200) and it does NOT reproduce**: with `--xboxhid --idle-after 12
--seconds 75` the pad sat through 58 s of total input silence with `SWD\PUNKTFUNK\PF_XBOX_0` at
Status=OK and its promoted `HID\PUNKTFUNK&IG_00` child present throughout. The one-line "add a
heartbeat to the GameStream arm" fix this was going to justify is therefore **not** warranted, and
was not made.

Two things the same run did establish, and they are real:

- **Two live processes wanting pad index 0 collide** exactly as
  `PadCreateFault::IndexOwnedElsewhere` describes (`Global\pfds-boot-0`, ACCESS_DENIED because the
  mailbox DACL is SYSTEM+LocalService). `dfcffcdd` (v0.31.1) put **both** input planes on that one
  name — before it, GameStream used `Global\pfxusb-boot-0` and the two could never collide — so the
  hazard is new even though it is not what the reporter hit. A clean release-then-retake does not
  collide (0 s, 1 s and 3 s gaps all created their pad), so an ordinary client reconnect is not the
  trigger.
- **`PUNKTFUNK_HOST_CMD=serve` on .173 means GameStream is switched off there**, so that box has
  never exercised the plane `dfcffcdd` changed — which is how a compile-only fix reached users
  unexercised.

### Dependencies

- **`h2` 0.4.15 → 0.4.18, for RUSTSEC-2026-0258** (unbounded empty DATA frames, disclosed
  2026-08-17; fixed in 0.4.16). Lockfile-only and transitive — no manifest declares `h2`, and
  `cargo metadata --locked` accepts the two-line change with no other package moving, so the
  resolver needed nothing else. This was the only finding across all five Rust lockfiles; the two
  remaining `cargo audit` lines (`audiopus_sys`, `paste`) are the pre-existing *unmaintained*
  warnings already allowed in `.cargo/audit.toml`.
  ⚠ `THIRD-PARTY-NOTICES.txt` still records `h2 0.4.15` and is **not** regenerated here: the
  generator walks the dependency closure of the machine it runs on, and on macOS that drops the
  `rusqlite` / `libsqlite3-sys` / `fallible-iterator` cluster (575 → 566 crates) — removing
  attributions a Linux or Windows build genuinely links. Regenerate it on Linux. Nothing gates the
  checked-in copy, and every packaging script regenerates it on its own platform, so this is
  cosmetic drift rather than a shipped inaccuracy.

### CI

- **The flatpak build stopped updating runtimes it already has.** Every attempt died on
  `dl.flathub.org` serving a 404 for one object of the then-current `rust-stable//25.08` commit;
  `retry.sh` burned all 10 attempts (~9 min) on it and `flatpak-builder` segfaulted on its own error
  path (rc=139), so the wrapper could not tell a dead end from a load blip. Root cause is ours:
  `--install-deps-only` does not install what is missing, it **updates** what is present, and
  `ci/flatpak-ci.Dockerfile` bakes the entire runtime set — so that update was a pure no-op on a
  healthy run while making every build depend on Flathub's health at that minute. Nothing wanted the
  newer commit; the manifest pins a runtime **version**, not a commit.
  `scripts/ci/flatpak-deps-present.sh` now asks first and reaches for Flathub only on a real miss;
  it fails **open** (anything it cannot parse takes the full install path) and has a `--self-test`
  that stubs `flatpak` over baked / cold / each dep missing / wrong version / unreadable manifest.
  `--install-deps-from=flathub` is dropped from the build step: `builder_manifest_install_deps()`
  runs whenever that flag is set, so the step billed as offline was re-running the same update.
  `packaging/flatpak/build-flatpak.sh` keeps it — a dev box has no baked image. `flatpak.yml` now
  also triggers on the deps-check script itself, so a change to that decision cannot ship untested.
- **A dropped Skia download read as a lint failure.** `scripts/ci/retry.sh` wraps every single-shot
  network call in CI, but one of the largest fetches was never wrappable that way: `skia-bindings`
  pulls ~19 MB of prebuilt Skia per target from INSIDE its build script, with a bare `curl -sS -f -L`
  and no retry. Measured on main 2026-08-22, android job: `curl: (18) end of response with 17054400
  bytes missing` — 2 MB of 19,057,024 arrived before the connection closed. `skia-bindings` then
  swallowed it, falling through to starting a full from-source Skia build the CI containers carry no
  deps for, so the job surfaced as something else entirely.
- **`mgmt/tests.rs` has one `ConfigDirOverride`, not one copy per test.** The unsafe-hygiene gate
  failed at 6 process-global-API mentions against a baseline of 3: the new rename test had
  copy-pasted the existing `EnvGuard` + lock + tempdir dance, which is exactly the duplication gate
  C exists to catch. The single guard also makes the pairing harder to get wrong — the lock is a
  **field** rather than a separate `_serial` binding a test could forget, and `Drop::drop` runs
  before any field drops, so the environment is restored while the guard still holds the lock. Back
  to 3.

### `sdk/src/gen/punktfunk.ts` had drifted from its own generator

The generated client in #374 is bigger than the feature. Regenerating it from the **unchanged**
committed spec already produced a ~700-line diff — the checked-in copy had drifted from its own
pinned generator, and nothing in CI regenerates or verifies it (unlike `api/openapi.json` and
`include/punktfunk_core.h`, which are both gated). #374 lands the clean regeneration rather than
hand-patching generated code.

**`@punktfunk/host` 0.1.6 is cut for it** (`sdk-v0.1.6`, published by `sdk-publish.yml`), because a
plugin resolves the SDK from the registry: the types for `PATCH /clients/{fingerprint}` could not
reach one while they sat in `sdk/` unpublished. That single regenerated file is the whole diff since
`sdk-v0.1.5`.

`SDK_VERSION` in `sdk/src/version.ts` moves with `package.json`. It is a hand-maintained constant —
`tsconfig.build.json` sets `rootDir: "src"` so it cannot import `package.json`, and the runner ships
as one bundled `runner-cli.js` with no manifest beside it — and the runner compares it against the
SDK installed in the plugins tree to decide whether to reinstall. Shipping 0.1.6 with the constant
still reading 0.1.5 would publish the types and then never deliver them; `version.test.ts` exists for
exactly that and gates it.

---

## v0.31.2

10 commits since v0.31.1 (6 non-merge), counted at the tip this was cut from.

**Nothing versioned moves, and this time nothing versioned even changes shape.** `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. `include/punktfunk_core.h` is **byte-identical to the
v0.31.1 tag** — unlike the last two releases, which each added a `#define` — and `pf-driver-proto`
shows no diff either. No route is added or removed, no `#[repr(C)]` struct moves, and neither
`@punktfunk/host` (0.1.5) nor `@punktfunk/plugin-kit` (0.4.4) is re-cut. An embedder can take this
release without recompiling anything, and a packager has one thing to notice: the Windows firewall
rules below.

`api/openapi.json` changes in **documentation only** — two `description` strings on `HostInfo`, no
route, schema, field or type — plus the `info.version` stamp. That documentation change is
load-bearing, though, because it records a behaviour change: `local_ip` is now read per request.

The release is entirely fix-shaped. Three of the six non-merge commits are the same class of fault —
the host using the wrong local address — reached from three directions: the data socket's source
address (#367), the advertised address after a cold boot (#366), and the firewall rules that
admitted anyone to the ports those addresses point at (#368). The fourth is an Android regression
from v0.31.1 (#365); the remaining two are a refactor and a test in support of #366.

### Versions

| | v0.31.1 | v0.31.2 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged. No message added, removed or re-shaped; `DeliveryReport` (`0x0B`) from v0.31.1 is the most recent addition and is untouched |
| C ABI | 25 | **25** | unchanged. `include/punktfunk_core.h` has **no diff at all** against the v0.31.1 tag — not even a constant |
| 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.1 tag |
| Windows virtual-gamepad channel | 3 | **3** | unchanged; no file under the gamepad backends is touched by this release |
| Plugin index schema | 1 | **1** | unchanged |
| Host event schema | 1 | **1** | unchanged (`punktfunk-host/src/events.rs`) |
| `api/openapi.json` | 0.31.1 | **0.31.2** | **description-only**, plus the stamp (`info.version` is `CARGO_PKG_VERSION`). The two `HostInfo` strings that change are quoted under **`Host::local_ip`** below; no route, schema, required-field or type differs. Re-stamped here, not regenerated — `punktfunk-host` does not build on macOS; the document itself was regenerated in #366 on a runner where `openapi_document_is_complete_and_checked_in` executes. `api/` and `docs-site/public/` are byte-identical to each other |
| gamescope patch level (`+pfhdrN`) | 8 | **8** | unchanged; no new patch files, and `packaging/gamescope/PKGBUILD` still declares `pfhdr8` after the v0.31.1 correction |
| `@punktfunk/host` (SDK) | 0.1.5 | **0.1.5** | unchanged; nothing under `sdk/` moved |
| `@punktfunk/plugin-kit` | 0.4.4 | **0.4.4** | unchanged; nothing under `plugin-kit/` moved. 0.4.4 remains the registry's `latest` |

### ⚠ Breaking changes

**None.** No wire change, no ABI change, no driver-protocol change, no plugin-contract change, no
API-surface change. Every 0.31.x host, client, driver and plugin keeps interoperating in both
directions with no re-pairing and no rebuild.

Two **behaviour** changes that break no build but change what a machine does:

- **Windows `service install` now scopes every inbound rule to a program.** The five fixed-port
  rules gain `program=<exe>` while keeping their `localport=`. If you provision firewall rules
  yourself rather than letting `service install` do it, the equivalent is `program=` on each; if you
  do nothing, `service install` re-runs on every upgrade and rewrites them for you. **Externally
  visible:** 5353 is punktfunk's alone now, so anything else on the machine that was reachable on
  mDNS through punktfunk's any-program rule needs its own rule.
- **`HostInfo.local_ip` is no longer static for the life of the process.** It was a field
  snapshotted at `Host::detect()`; it is a method that re-reads on every request. A consumer that
  cached it once at startup was caching a value that could be `127.0.0.1` forever (see below) and
  should poll instead. The two `description` strings in `api/openapi.json` say so.

### Windows: the fixed-port firewall rules admitted any program on the machine

`service install` added `dir=in action=allow` rules carrying only `localport=`. A rule of that shape
admits **any process** that binds the port — GameStream (47984/47989/47998-48010/48010), the native
plane (9777), mgmt (47990), mDNS (5353) and the console pair (47992/47993). Binding a high port on
Windows requires no elevation, so an unprivileged program could take any of them and become
LAN-reachable simply by binding first, and **silently**: our rule is precisely what suppresses the
"Allow this app to communicate on…" prompt that would otherwise be the only way in.

Every rule is now scoped to the executable that actually listens on it, keeping the ports — program
**and** port is strictly tighter than either alone. The host rules name the host exe (resolved once
via `current_exe()` and shared with the data-plane rule, which already worked this way and is the
pattern the rest now follow); the console rules name the bundled `<app>/bun/bun.exe` the supervisor
spawns. `fw_add_rule_args` is the new single constructor for the whole shape.

The old argument for leaving them unscoped — "an install whose recorded exe path later moves still
has its fixed ports open" — does not hold: `service install` re-runs the whole remove-then-add on
every upgrade, so the path is refreshed rather than left stale.

Fallbacks are deliberate and **asymmetric**. A fixed-port rule whose program cannot be resolved
falls back to the old any-program form, because a looser rule still streams and no rule is a black
screen. The data-plane rule instead **skips**: it has no `localport=` to fall back to, so a
program-less version of it would not be a looser rule but an open host. The installer prints the
5353 note only when the scoping actually happened — claiming it while the rules are still wide open
would be worse than saying nothing.

Reported by a user on 2026-08-21, immediately after the source-IP fix below cleared their black
screen.

### The data socket binds the address the control plane arrived on

`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 dialled, so its kernel drops every datagram
from any other source — in the kernel, 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 documented the mirror of this assumption for
the *client's* source IP; the host side was never checked.

The socket now binds `Connection::local_ip()` (unmapping an IPv4-mapped v6 address so it can still
`connect` to a v4 peer), falling back to the wildcard **loudly** when that is unavailable.

Two diagnostics changed with it, because the field session's log could not answer the question:

- the `data plane bound` line 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, contradicting its
  own advice and sending an investigation to 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 as one that received nothing.

### `Host::local_ip` re-reads, and mDNS adverts follow it

`Host::detect()` snapshotted the LAN address once at process start and every consumer read that
frozen field forever. On a cold boot the host wins the race against the network — the Windows
service is registered `AutoStart` with no dependencies — so `primary_local_ip()`'s route probe to
8.8.8.8 failed with `ENETUNREACH` and the loopback fallback stuck for the life of the process.
Restarting the host re-ran `detect()` on a live network, which is the workaround users found.

Four surfaces broke together off that one field: both mDNS adverts (`_punktfunk._udp`,
`_nvstream._tcp`) published `127.0.0.1` as their A record; `session_url_xml()` handed Moonlight
`rtsp://127.0.0.1:48010` after `/launch`; `wol::wake_macs()` found no interface for loopback and
dropped the `mac` TXT record, silently disabling Wake-on-LAN; and `HostInfo.local_ip` reported
loopback to the web console.

Fixed at the choke point rather than per caller:

- `primary_local_ip()` never returns loopback or the unspecified address. When the route probe
  fails it falls back to `first_lan_ipv4` — the first non-loopback interface address, which exists
  as soon as the NIC is configured even if the default route is not installed yet, the common shape
  of the boot race. It is split out so a test can assert the one thing that matters: it never hands
  back the loopback `get_if_addrs` also reports.
- `Host::local_ip` becomes a method that re-reads instead of a field that freezes. A `connect(2)` on
  an unconnected UDP socket sends no packets and costs nothing beside the HTTP response it is
  serialized into.
- mDNS records are **pushed, not polled**: a live advert re-registers when the routed address
  changes (`discovery::advertise_live`, shared by both service types). It polls the routed address
  rather than subscribing to the daemon's `IpAdd` events because the boot race usually resolves
  without one — the NIC often has its address before we register, and only the route lands late.

This also covers the sibling cases that were never reported: DHCP handing out a different lease, and
a host moved between Wi-Fi and Ethernet.

The re-announce loop's stop signal is now the `mpsc` channel it already sleeps on, rather than an
`Arc<AtomicBool>` plus a `Drop` impl: the `Advert` dropping its sender wakes the thread immediately
instead of leaving it to notice a flag up to `IP_RECHECK` (10 s) later.

### Android: the button correction is gated on named triggers, not declared keys

v0.31.1 corrected button positions for pads Android has no key layout for, and gated it on
`hasKeys(BUTTON_C, BUTTON_Z)`. That gate 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 buttons —
including a standard-layout pad that never presses either. The signal was therefore identical on the
pad that needs correcting and the pad that does not, and no tightening of it could have separated
them.

Two field reports on 2026-08-21 (a GameSir G8+ and an "Xbox Wireless Controller" over Bluetooth) had
X answering Y, Y answering LB, and both shoulders answering menu buttons — exactly what
`GENERIC_XBOX` does to scancodes `0x133`/`0x134`/`0x136`/`0x137`. It is the same pad model on both
sides of the bug: an Elite Series 2 needed the correction on a Fire TV, and another was broken by it
here.

What separates them is the **axes**. A HID gamepad describes its triggers either as the
Accelerator/Brake usages — which become `ABS_GAS`/`ABS_BRAKE`, names Android has words for — or as
two generic axes on `ABS_Z`/`ABS_RZ`, which it does not. A descriptor well-formed enough to name its
triggers puts its buttons at the standard positions too. It is also the firmware line on the pad in
the report: an Xbox Wireless Controller reports GAS/BRAKE after its firmware update and Z/Rz before
it, and only the older one was ever wrong.

`padButtons` now takes `namedTriggers` and answers `NATIVE` whenever it is set — no correction of
any kind, on buttons or axes, for a pad Android already reads. `padMap` computed that fact one line
below and only ever spent it on the axes; it now decides both. `hasKeys` stays for the narrower
question it can answer — *which* straight-through order, once the axes have established there is
one — where a false positive costs nothing. This is the same discriminator Moonlight uses
(`ControllerHandler`, `gasRange == null` beside the `"Xbox Wireless Controller"` name); v0.31.1
cited its tables and then replaced its discriminator, which is where this came in.

`PadButtonsTest` is at 16 cases, 3 new: the gate holds for every vendor/declaration combination, the
four reported buttons stay themselves, and the report-order choice past the gate is unchanged.

**Not fixed here:** a DualSense report filed alongside these, with Triangle dead in both the client
UI and the stream. A button reaching neither is one `buttonBit` maps to nothing, which no branch of
the correction produces for Triangle.

---

## 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.

One versioned surface moves, additively: the **C ABI goes 24 → 25**, a single new symbol
(`punktfunk_set_log_callback`) that lets an embedder hear the core's own log lines. Nothing else
does — `WIRE_VERSION` stays **2**, the driver protocol, gamepad channel and plugin index schema are
unchanged, and no `trust::Settings` field, capability bit or control-message type byte was added.
No existing C function changed its signature or behaviour and no `#[repr(C)]` struct grew a field,
so an embedder that adopts nothing rebuilds against the new header and is done. Every 0.30.x host,
client, driver and plugin keeps interoperating in both directions, with no re-pairing.

Beneath the versioned surfaces, four things are worth a packager's or embedder's attention: the
**Windows client's default download changes** to a per-user installer plus a portable zip, with the
MSIX kept for the Store; the Linux host package installs **three new system files** (a udev rule, a
WirePlumber policy and an ALSA UCM drop-in) that the DualSense audio path depends on; the Linux
desktop-audio capture **flipped topology by default** (`PUNKTFUNK_STREAM_SINK` unset now means a
host-owned `null-audio-sink`, with `=stream` a one-release escape hatch to the 0.30 shape); and the
Android app's Compose console is **deleted** — `pf-console-ui` over Skia/GL is now the console on all
three ABIs, which removes the Compose screenshot scenes.

### Versions

| | v0.30.0 | v0.31.0 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged |
| C ABI | 24 | **25** | one additive step: v25 adds `punktfunk_set_log_callback` and the `PunktfunkLogCb` typedef (below). No existing declaration moved and no struct grew a field. Also new in `punktfunk-core`, Rust-only: three RT-safe DSP helpers (`crossfade_insert`, `pcm::raised_cosine_tail`, `pcm::raised_cosine_head`) |
| 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.30.0 tag |
| Windows virtual-gamepad channel | 3 | **3** | unchanged |
| Plugin index schema | 1 | **1** | unchanged |
| Host event schema | 1 | **1** | unchanged (`punktfunk-host/src/events.rs`) |
| `api/openapi.json` | 0.29.0 | **0.31.0** | **the stamp only** — no management-API surface moved this cycle. The file had been left at 0.29.0 while the crate was already 0.31.0; #337's regenerate-and-diff caught it and it was regenerated, which is a one-line change to both copies. `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` still says `pfhdr7` — pre-existing at v0.30.0, not a regression this cycle, but the Arch package builds a binary the host's `>= 8` probe rejects for the keymap path |
| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.5** | cut — `sdk/src/config.ts` and `runner-cli.ts` carry the `mgmt-endpoint` fix below, and plugins resolve the SDK from the registry, so it could not reach them until it shipped |
| `@punktfunk/plugin-kit` | 0.4.2 | **0.4.3** | cut, for the two `sync-engine.ts` changes that cannot reach a plugin any other way: `minInterval` (below) and the always-apply sync reasons (`startup`/`manual` publish even when the fingerprint matches, so a host-side art drop is recoverable by restarting rather than by deleting the plugin's cache). Note the registry skips 0.4.2: `plugin-kit-v0.4.2` was tagged but its publish never landed, and the tag is left where it is rather than moved |

⚠ The SDK and plugin-kit version independently of the app (`sdk-v*` / `plugin-kit-v*` tags,
`sdk-publish.yml` / `plugin-kit-publish.yml`), so their rows record what the registry holds, not
what this tag ships. Both were cut during this cycle rather than left owed — a plugin resolves them
from the registry, so a fix that never ships there never reaches one.

### ⚠ Breaking changes

**None that break a build.** No wire change, no driver-protocol change, no plugin-contract change.
The C ABI moves 24 → 25 by **addition only**:

- **v25 — `punktfunk_set_log_callback(max_level, cb, user)`.** The core logs through `tracing`; an
  embedder that installs no Rust subscriber hears none of it — transport warnings, connection events,
  handshake notes — and a client log bundle carries the shell's half alone, which is exactly what an
  Apple TV field report turned out to be. The call registers a `log::Log` backend behind a C callback
  (`PunktfunkLogCb`: level, target, message, user), gated by `log::set_max_level` so anything above
  the ceiling costs no formatting; `NULL` detaches, and it answers `Unsupported` when another log
  backend already owns the process (`android_logger`). Both strings are borrowed for the call only,
  and an interior NUL drops the line rather than truncating it. `punktfunk-core` now declares
  `tracing`'s `log` feature explicitly — it had been on transitively via quinn, which an ABI promise
  must not rest on. An embedder that never calls it is byte-compatible with v24; see
  `docs/embedding-the-c-abi.md` §2.6.
- **One header comment was wrong and is corrected, with no signature change:**
  `punktfunk_connect_ex10`'s summary still stated the pre-2026-08-16 rule that only a format other
  than 48000/16 requests the lossless plane. Any non-zero format at all does, 48000/16 included —
  which is what its own warning already said and what the code always did. Embedders reading the
  summary were reading the old rule.

Five more things are worth attention; none breaks a build:

- **`refactor(android)!` — the Compose console is deleted.** `pf-console-ui` (the Skia shell the
  desktop session binary draws) is now Android's console on arm64-v8a, x86_64 **and** armeabi-v7a;
  the gate is simply "does the native host exist", and where it does not a controller drives the
  touch UI through focus. ~6.5 kLOC of `GamepadHome`, `GamepadSettingsScreen`,
  `GamepadAddHostScreen`, `GamepadDialogs`, `HomeTiles`, the console halves of `LibraryScreen`,
  `ConnectOverlay`/`ConnectTakeover`, the `gamepadUi` branches of `ConnectScreen`/`ConnectPrompts`/
  `AdaptiveDialogs`, `App.kt`'s `GamepadShell`/`GamepadScreen` and their tests are gone. The `!` is
  for the **store-screenshot surface**: the Compose console's marketing scenes cannot be rendered by
  Roborazzi any more (the shell draws over native GL); its shots come from the desktop screenshot dump
  or a device capture. Sysprop `debug.punktfunk.console_backend=compose` is meaningless; `=none`
  still forces the touch UI on glass.
- **Linux desktop-audio capture topology flipped by default** — see the audio section. `=stream`
  restores 0.30 for **one release only**.
- **Hyprland / sway: `topology: exclusive` now does what it says.** Both backends accepted it,
  echoed it as the session's effective topology, and dropped it with a warning; because `auto`
  resolves to Exclusive on any unpinned host, the *default* policy on every auto-detected Hyprland
  or sway box was an Exclusive that behaved as Extend. Operators who relied on that get their
  monitors disabled for the session now (closes #284).
- **Three new system files in the Linux host package** — the DualSense audio path does not work
  without them. Downstream repackagers: see the packaging section.
- **The Windows client's default download is a per-user installer, not the MSIX.** The MSIX stays,
  for the Store; the installer and a portable zip are what the download page now offers, and the
  release carries `punktfunk-client-setup_<arch>.exe` and `..._<arch>-portable.zip` alongside it.
  Anyone scripting against the MSIX asset name is unaffected; anyone scripting against "the Windows
  client download" gets a different artifact. See the Windows client section.

### DualSense audio and haptics on Linux: five faults, and the files they needed

The whole in-game path — GE-Proton's haptic router → the pad's ALSA card → the voice coils — had
never once worked against our virtual pad. In wire order:

- **`usbip`: the calibration feature report was 42 bytes; `hid-playstation` asks for 41.** On a USB
  backend an over-long reply is not truncated: the kernel treats it as hostile and tears down the
  connection, not the transfer — the pad vanished ~400 ms after enumerating, and the dmesg order made
  the teardown look like the cause. Three changes so the trap is not left set: the constant is 41 and
  all three feature-report sizes are pinned by test; `clamp_reply` clamps every reply to the requested
  length in the transport and drops any payload a handler returns on an OUT (the kernel never reads
  one; those bytes would misframe every following PDU); `DualSenseUsbip::open` waits for the kernel
  to actually bind a HID driver before reporting success (vhci attach succeeds immediately and
  enumerates asynchronously), so bring-up faults return `Err` and the uhid fallback catches them.
  New `PUNKTFUNK_USBIP_TRACE` (both socket directions to disk) and `scripts/usbip-trace-analyse.py`.
- **`usbip`: every non-ISO OUT was answered with an empty buffer, i.e. `actual_length = 0`.** vhci
  copies that field verbatim into the URB's actual length; the driver returned 0 as the write's byte
  count; Wine's bus driver reads 0 as failure and prints the thread's *stale* errno — so the ENOENT /
  EINVAL / EAGAIN in the GE logs were never kernel verdicts. New
  `UsbIpResponse::usbip_ret_submit_out_success(header, accepted)`; the debug assertion now pins
  "OUT carries no buffer", not "OUT claims 0"; two wire-byte tests pin both directions. **The Steam
  Controller 2 shares this handler.** `usbip-trace-analyse.py` had flagged *any* nonzero OUT
  actual_length as a desync — the rule that would have hidden this bug — and now flags an OUT reply
  claiming more than it was sent, or 0 against a non-empty write.
- **`usbip`: ISO completions were paced by relative sleeps**, so timer slop, socket I/O and lock waits
  accumulated per transfer: the pad's clock ran ~26 % slow (~35,700 frames/s against 48 kHz), its PCM
  backed up into dropouts, and because completion *is* the pad's audio clock, on the test box the pad
  sink became the graph driver and pulled desktop capture to 50 % delivery. Now a per-endpoint
  absolute deadline ledger (a stall > 20 ms re-anchors instead of fast-forwarding a burst); measured
  after: 48,005 frames/s. Two paused-clock tests pin the rate and the re-anchor.
- **`usbip`: the capture forwarded the pad's hardware quad as the wire's speaker pair.** Hardware
  is HP-L, HP-R+mono-speaker, coil-L, coil-R; the wire puts the speaker pair first. Now: the speaker
  channel duplicated across the wire's speaker pair, coils passed through, HP-L dropped. The
  stream-sink (uhid) capture path already emitted the logical layout and is unchanged.
- **`usbip`: `iSerialNumber` was the literal `"Serial"`.** A real DualSense reports none, ALSA bakes it
  into the card id (`…Wireless_Controller_Serial-00` vs `…Wireless_Controller-00`) and PipeWire
  carried it into every node name and `device.serial`. Cleared. Explicitly *not* a fix for anything
  observed broken — GE's winepulse leg matched the placeholder — and *not* a UCM-selection fix
  (alsa-ucm-conf keys on `${CardComponents}`, `USB054c:0ce6`).
- **The pad's ALSA card was root-only.** It is created mid-session-bringup with no seat session
  active, so logind's ACL never materialises; WirePlumber's probe got EACCES and the card never
  appeared in PipeWire at all. `scripts/60-punktfunk.rules` gains two `SUBSYSTEM=="sound"` rules for
  `054c:0ce6` / `054c:0df2` (`GROUP="input" MODE="0660" TAG+="uaccess"`), matching physical pads too.
  Verified live on Bazzite f44.
- **The DualSense's only playback route was a 1-channel `Default__Speaker__sink`**, from which
  GE-Proton mints its synthetic endpoint, and *Marvel's Spider-Man Remastered* overruns it ~74 s in
  (`EXCEPTION_ACCESS_VIOLATION`, write; the copy loop past the frame count, 5206/5207 vs 5034 — a
  game/GE bug on a code path that only exists when the mono sink does). Fix: delete the sink. New
  ALSA UCM drop-in `scripts/alsa-ucm2/USB-Audio/conf.d/{054c-0ce6,054c-0df2}.conf` +
  `scripts/alsa-ucm2/USB-Audio/Punktfunk/DualSense-PS5-Haptic{,-HiFi}.conf` raises a `SpeakerHaptic`
  device at playback priority 200 against `Speaker`'s 100, so the card takes the 4-channel HiFi
  profile and the mono sink never exists. Shipped **without** replacing a file `alsa-ucm-conf` owns:
  `USB-Audio.conf` ends with an unconditional optional include of `conf.d/{vid}-{pid}.conf`
  (verified against alsa-lib source; hook and DualSense profile both since 1.2.15). New CI guard
  `scripts/ci/check-dualsense-ucm.sh` runs the chain on a real distro tree via UCM's card-less
  `conf.virt.d`, negative-tested both ways. **NixOS is not covered** (no `/usr/share/alsa/ucm2` to
  drop into).
- **WirePlumber met every new pad card at `default-sink-volume` 0.4 — cubed, i.e. −23.88 dB — and
  both ends minted one**, so haptics reached the coils at 0.064² = −47.8 dB (field-measured −48).
  Client: `pin_sink_volume` from `correlate_pad_sink` at every pick (skipped for the `split_parent`
  pick). Host: new `audio/linux/pad_card_volume.rs`, started when `PadUsbCapturer::open` succeeds
  (the host half matters because `pad_usb` captures at the ISO OUT endpoint, downstream of this
  sink), retrying 15 s because the USB device is live before its ALSA card is; only sinks of a
  DualSense **card** are touched (`device.id` keeps it off the host's own minted pad sink). Neither
  end restores on exit, deliberately. New `PUNKTFUNK_PAD_SINK_VOLUME=0` disables both ends for
  bisecting. Both pins unit-tested for one unity float per channel — PipeWire silently ignores a
  `channelVolumes` whose length mismatches the port count.
- **`scripts/60-punktfunk-dualsense.conf`** — a new WirePlumber policy installed to
  `/usr/share/wireplumber/wireplumber.conf.d/` by rpm/deb/arch/nix: `node.always-process` + no
  suspend on the pad's `alsa_output` (GE opens the backing device raw when it is free, then hits
  "busy" against its own handle and spins a 100 Hz refresh loop — SteamOS never shows this because
  PipeWire always holds the device there), and `priority.driver = 0`. **Zero, not one**: the field is
  unsigned and a driver is skipped only when `<= 0`; at 1 the pad was merely *last*, and last is still
  elected whenever nothing above it qualifies — the ordinary in-session state on a host that has
  claimed its own sink as default and idled the real card. A second rule sets `priority.driver = 0`
  on the same cards' `alsa_input` (in the Pro Audio profile that node carries 2600 and clocked a
  reporter's whole desktop session with nothing linked to it). The rule's first landing duplicated
  its `%files` line into `%install`, which killed every RPM build on main for a few hours (fixed same
  day, no release affected).
- **`0xD1` lane split:** speaker = Opus `Application::Audio` @ 96 kbps (~120 B / 10 ms frame),
  haptics = `Application::LowDelay` @ 64 kbps CBR, unchanged.
- **`punktfunk-session --pad-audio-test`** now prints the effective `pad_speaker` / `pad_haptics`
  before the tone (the capability is never advertised when the toggle is off, so no later log line can
  catch it); the Android settings row states its default. Android is the one client defaulting pad
  speaker **off**; `pf_client_core`'s `default_pad_speaker` is `"pad"` and always was.

### The Linux desktop-audio capture drives its own graph group

The stream sink was a `pw_stream` wearing `media.class = Audio/Sink`. A stream is structurally a
follower, so its group had no clock and PipeWire assigned it to the highest-priority *running*
driver on the box. On a reporter's host that was a DualSense forwarded over VirtualHere in the Pro
Audio profile — never suspended, nothing linked, its frame counter a kernel stub logging "not yet
implemented" and returning 0 ~1900×/s. Not xruns: 11 errors in 15 min, wait never past 111 µs; the
loss was *between* cycles — 3.9 delivery holes/s, worst 142 ms, **15.4 % synthesized silence** over
a 15-minute session.

Now a `support.null-audio-sink` adapter created on our own connection, captured through its monitor
(the same object `pactl load-module module-null-sink` creates). Three load-bearing properties:
`node.passive` on the monitor tap (idle between sessions, so the null sink's timer parks — the
objection that kept `node.always-process` off the old stream sink); `node.force-quantum`, not
`node.latency` (a driver's quantum is the smallest follower latency rounded **down** to a power of
two under the default `default.clock.power-of-two-quantum`, which is why the 240-frame ask has been
served as **128** — 2.67 ms callbacks, not the 5 ms it is designed around — on every stock Linux host
since the capture was written; force-quantum skips the rounding and forces nothing on anyone else,
since this sink drives only its own group); and `node.dont-fallback` **with** `node.linger`, never
one alone (WirePlumber 0.5 reads dont-fallback alone as licence to destroy the stream when its target
is not visible). Routing claim, capture callback, stats line and everything downstream untouched.
`PUNKTFUNK_STREAM_SINK`: unset = new topology, `stream` = 0.30's (one release), `0` = the legacy
default-sink-monitor follower. Documented at last in `configuration.md`, with a new troubleshooting
section on the `punktfunk-audio-…` recording stream and on another device clocking your capture.

Around it, from the same 2026-08-14/17 field logs:

- The host binds its own node and reads `node.driver-id` from its `info` event (a node-id→name map
  from the registry): on change, `audio capture graph driver` names the clocking node — WARN in the
  null-sink mode (exactly one right answer), INFO in the legacy topologies (they borrow a clock by
  design).
- `CaptureStats::observe_gap` is now the one accounting behind both feeds (Linux callback cadence and
  the Windows discontinuity flag) and buckets holes at <20 / <50 / <100 / ≥100 ms — the client
  concealment edges. Both capture lines print `gap_hist=a/b/c/d missing_ms=`; the sum closes the
  arithmetic against `delivered_pct`. The Windows loopback **reader** thread now takes
  `boost_thread_priority(true)` like the paced sender it feeds.
- **The pacer's schedule was wall clock; the source was not.** A missed 2.7 ms cycle is below the gap
  counter's floor and the infill threshold, so the schedule kept the debt and repaid the next ≥ 10 ms
  hole as a burst of (lag + 10)/5 silence frames (field: 33–72 % departures late, worst 99 ms,
  re-anchors 0). The infill decision now sees schedule lag; `after()` follows the real quantum
  (`InfillPolicy::note_quantum`) — one chunk plus one frame, never under two frames; a slot whose
  backlog exceeds one chunk plus one frame sends a second frame in the same slot (at most two), since
  a fast source clock could otherwise only grow the backlog — 5 ms of host latency per 50 s at
  100 ppm. Holes fade out over 1 ms (`pcm::raised_cosine_tail`) and the first real frame after fades
  in (`raised_cosine_head`).

### The client jitter ring can now grow without de-priming

`JitterStep::insert_front` mirrors `drop_front`: when the sync loop wants more than the adaptive
target and the depth EWMA has sat > `INSERT_MARGIN_MS` below the request for `INSERT_SUSTAIN_MS` of
consumed audio, duplicate one frame at the front, crossfaded (`crossfade_insert`, the RT-safe twin
of `crossfade_drop`). Sync-only, primed-only, below-target-only. `hollow` is judged against the
**adaptive** target, never the sync request — the bug was that a ≥ 10 ms sync request read as hollow
on the next callback and the next late packet cost 15–60 ms of silence, since ~0.24/0.25. Margin is
half the sync loop's ±10 ms deadband (a margin at or above it would leave every request it is allowed
to make unanswered). Also fixes `crossfade_drop`'s seam: the fade-out source is now the continuation
of the sample the device just played, not the tail of the discarded region — a hard-cap trim stepped
2,688 samples where it now stays under 17. Wired into the PipeWire, WASAPI and AAudio rings
(`PlaybackVitals.inserts`, `drift_inserts=` on the 10 s lines) and ported line for line to the Swift
ring (`insertOneFrame()`, `AudioRingDriftTests` carrying the same vectors). No new `pub const`; the
C header is unchanged.

Beside it: the Linux desktop client's playback stream now connects with `RT_PROCESS` (it ran on the
main-loop thread at nice 0, and when late PipeWire rendered silence for our node and moved on — an
underrun no counter saw); the ring is pre-reserved so `extend` never reallocates on the RT loop; new
`audio_vitals::PlaybackVitals` printed from the decode thread on wall clock. New `audio_rt` module
raises the decode, pad-audio, PipeWire-loop and Linux mic threads: `setpriority` where `RLIMIT_NICE`
allows → inside a Flatpak the `org.freedesktop.portal.Realtime` portal → else rtkit
`MakeThreadHighPriorityWithPID`. The split is `module-rt`'s and not optional: rtkit-daemon has no
PID-namespace translation (verified on the Deck, rtkit 0.14), so a direct call from a sandbox is
ENOENT; the portal maps pid/tid. Never setcap / `SCHED_RR`. Windows: MMCSS "Pro Audio" +
`THREAD_PRIORITY_HIGHEST` on the render and mic loops. Acceptance on the Deck: `ps -eLo
cls,rtprio,ni,comm` shows the decode thread at nice −10 after connect.

The client log ring drops DEBUG/TRACE from `cros_codecs` (its WARN+ still lands) and normalizes
`log`-bridge events to their real target: a dozen DPB lines per frame at 120 fps last three seconds
in a 4,096-line ring — a 2026-08-17 Deck bundle read "2,037,456 older lines evicted". `Cargo.lock`
gains two direct deps already in the graph.

### Android: `pf-console-ui` is the console, presented through `ASurfaceControl`

- **`pf-client-core` un-gated for Android** (trust::Settings, known-hosts store, profiles model,
  deep links, the library *model*; the ureq fetches stay desktop), with `audio_format`,
  `decoder_pref`, `menu_nav` (`MenuEvent`/`MenuNav`/`PadInfo`) and `console` (`OverlayAction`,
  `PointerInput`, `SessionPhase`) split out and re-exported. `pf-console-ui`: Vulkan overlay + SDL
  event path behind the default `vulkan-overlay` feature (clients/session unchanged); a `Key` enum
  replaces SDL scancodes; a `SettingsStore` seam (desktop = the file, `SnapshotStore` across a
  language boundary); `Viewport{width,height,insets,scale}`; `Platform` filters the settings rows;
  `ConsoleOptions`; a portable `Console` driver. skia-safe features are target-specific: desktop
  `jpegd-jpege-pdf-textlayout-vulkan` (the flatpak pin), Android `gl-jpegd-jpege-pdf-textlayout`.
  Model types derive serde — the wire IS the model. `MenuNav` gains the stick hysteresis
  (`MENU_RELEASE = 0.3`) both the Apple and Android shells had grown on glass.
- **`clients/android/native/src/console/`**: hand-declared EGL binding, Skia GL `DirectContext` over
  FBO 0, one render thread paced by `eglSwapBuffers`, ~28 `nativeConsole*` JNI seams; a run of GL
  setup failures ends the render thread through the normal release path, which raises the
  `SkiaConsole.healthy` handover to the touch UI. `SkiaConsoleShell` (SurfaceView + lifecycle,
  insets = systemBars ∪ displayCutout in surface px, system bars hidden transiently while the console
  is up, phone density floor **0.6 → 0.75**, pad probes into the shared `MenuNav`, remote D-pad,
  hardware keys, Back as B, touch as pointer). Pad-listener slot is a **stack** with removal by
  identity (a leaving Controllers/Licences page used to null the console's claim). Android-only
  settings rows ride `Settings::extra` `android.*` keys; `row_on()` keeps them off the desktop list.
  New `ConsoleCmd::PadAction { action, pad_key }` (`sc2_bluetooth`, `sc2_usb`, `ds_usb`, rumble,
  pad-audio self test); `PlatformScreen::Controllers` removed (the mechanism stays for Licences);
  `PadInfo` gains detail line / forwarded / rumble. Detail band 84 → 64 units; the grid's two-column
  minimum shrinks covers instead of clipping.
- **Skia prebuilts** for all three ABIs come from `unom/skia-binaries` release **0.99.0** on
  git.unom.io (R2-backed), mirroring rust-skia's `{tag}/{key}` layout; the armv7 archive
  (`a25a0fdb7d90429aa2d1-armv7-linux-androideabi-gl-jpegd-jpege-pdf-textlayout`, sha256
  `4867856b…`) is built by us since rust-skia publishes none. GitHub is out of the Android build path;
  `-PskiaBinariesUrl` / `SKIA_BINARIES_URL` remain as overrides.
- **Present path:** the codec renders into an `AImageReader`; frames are composited onto an
  `ASurfaceControl` layer via a transaction carrying a desired present time, and completion reports
  the real latch time and the previous buffer's release fence — so the panel period is learned from
  real latches (Android down-rates a game process's vsync callbacks; the old presenter could learn 60
  on a 120 Hz panel) and the frame budget is bounded by real completions. `ASurfaceControl` /
  `ASurfaceTransaction` are not in ndk-sys 0.6, so `surface_control.rs` hand-declares them and
  resolves via `dlsym` from `libandroid.so` (all API 29, above minSdk 28), same pattern as `adpf.rs` /
  `vsync.rs`. Memory safety does not rest on the fences (an `AImage` keeps its buffer alive through
  SurfaceFlinger's own reference; a mishandled fence is at worst a tear). **Default**; auto-fallback
  to the SurfaceView presenter, byte-for-byte unchanged, on API < 29 or any init failure; escape hatch
  `debug.punktfunk.present_backend=surfaceview`. The layer is sized to the view's on-screen pixels,
  not the window buffer (which is reported in a rotated/scaled space — 1260×567 for a 2800×1260
  stream, drawing into the top-left 45 %). The present-time grid uses the mode table's seed period
  for spacing and the last real latch only for phase (learning the period from latches was
  self-fulfilling and locked the panel at 60). On glass at 2800×1260@120: e2e p50 30 → ~18 ms,
  skipped 40–50/s → 0. Whether the panel *holds* 120 is the OEM's LTPO governor — measured: no
  app-side API (`preferredDisplayModeId`, `preferredRefreshRate`, the layer rate vote,
  `frameRatePowerSavingsBalanced`) raises the render-range floor — so the ineffective pins were
  removed again and `pf.present` gained the cadence loop's late-permille / jitter / cushion /
  re-anchors / qDepth.
- **Colour tagging, which the SurfaceView path never had to do.** MediaCodec tags its own window
  buffers; with `AImageReader` → `ASurfaceControl` the transaction is the only carrier, and a
  dataspace of 0 means `setBufferDataSpace` is never called. Two consequences, both fixed inside the
  cycle: **HDR** was seeded from a hardcoded `BT2020_ITU_PQ` guess and then overwritten by whatever
  the codec echoed on the first output-format change — a decoder that omits color-transfer (common)
  echoes None, clobbering the dataspace to 0 before the first present, so P010 buffers composited as
  sRGB, and an HLG stream was mis-seeded PQ. The initial dataspace now derives from `client.color`
  (PQ vs HLG, range) and a format change only *refines* it when the codec actually reports an HDR
  transfer, never resets it — the SurfaceView path's semantics. And **SDR** was untagged entirely:
  a limited-range BT.709 buffer read as full range shows black (16) as grey, so SDR now maps to
  `ADATASPACE_BT709` and every ASC buffer is tagged.
- **One owner for the system bars.** Console → stream rides an `AnimatedContent` cross-fade, so the
  outgoing console shell stays composed until the fade ends and its
  `onDispose { show(systemBars()) }` fired *after* `StreamScreen`'s hide — parking the status and
  gesture bars over the video for the whole session. Hide/show now lives once in `App.kt`, keyed on
  the resolved intent (streaming or console fronting = immersive, touch shell = bars back), and both
  screens' per-screen bar management is deleted.
- **Idle gates** (from the console-ui sweep): the reachability sweep only probes while the console is
  attached, and the render thread drops to half rate after 60 s without input.

### Hyprland / sway: `topology: exclusive` (closes #284)

`exclusive` disables the operator's outputs for the session and restores them when the display
group's last member is torn down, through the same registry hand-off KWin uses (the compositor never
sees zero enabled outputs; a sibling session's desk is never re-enabled under it). The disable filter
is group-aware — enabled, not ours (`PF-<pid>-<n>` on Hyprland, the `HEADLESS-` prefix on sway), not
managed. **The Hyprland restore is `hyprctl reload`, and that is measured, not chosen**: re-applying
the head's own mode/position/scale does not undo a disable (probed 2026-08-18 against 0.56.2
hyprlang and 0.55.4 Lua — every targeted form was accepted at exit 0 and changed nothing, including
`,enable`, `preferred,auto,1`, `monitorv2 disabled=false`, `keyword unset monitor`, the Lua
`disabled = false`, `dispatch dpms on`, `forcerendererreload`); a runtime rule is additive and the
disable keeps winning. Disable is spelled per config era (`keyword monitor <n>,disable` under
hyprlang; `hl.monitor{ output = "<n>", disabled = true }` under Lua) and confirmed by **read-back**,
not exit status. `hyprctl_dispatch` now also matches "can't" (the Lua manager's "keyword can't work
with non-legacy parsers"). `primary` stays extend and warns distinctly. ⚠ **The sway half is not
exercised on a live sway** — no box in the fleet runs one; both argv shapes are pinned by tests and
the read-back turns a wrong guess into a warning naming the outputs. Six new unit tests.

### Gaming Mode takeover: it no longer touches the display manager at all

This landed in two steps within the cycle, and the second retired the first — read the end state.

**The storm.** On an SDDM-autologin box the runtime mask the takeover laid sat in SDDM's relogin
path, so every autologin failed in milliseconds and `Relogin=true` has no backoff: 962 logind
sessions in 3.7 min, system buttons re-scanned 5,688×, udev `change` at ~20/s, iio-sensor-proxy
crash-looping ~16 starts/s, load 26 on 12 cores — and Wine's bus driver, re-enumerating udev per
event, read the pad at ~1.4 Hz. Masking without stopping the display manager is not a weaker
defence; it is the storm's engine.

**Then stopping the DM proved wrong too.** With no display manager there is nothing on the box able
to start a desktop session, so Steam's own "Switch to Desktop" sat on its modal until a reboot
(field report 2026-08-18, `.41`). It could not even be detected and worked around: on a
steamos-manager box every trace of that switch is written by the component we had just stopped —
the `~/.config/steamos-session-select` sentinel is never written (that is the ChimeraOS/Nobara
layout), `/var/lib/sddm/state.conf` only advances when sddm actually *starts* a session,
`get-default-login-mode` stays `game` for a non-persistent switch, and `graphical-session.target`
going inactive fires at takeover time as well.

**End state: idle the autologin, leave the display manager alone.** The takeover drops a unit
override over the `gamescope-session-plus@` template replacing `ExecStart` with a process that
sleeps. The autologin still *succeeds*, so there is no failed unit to relogin against; the session
runs nothing, so Steam is free; and the DM is alive, so the box can service its own session switch.
No privilege, no DM-flavour matrix, no detection. Measured on `.41` in both directions: takeover
leaves `steam` down, `sddm` active, the unit `active (running)` with `NRestarts=0`; the switch that
used to hang brings Plasma up in ~10 s; the restore puts Steam back within 5 s. The drop-in lives
under `$XDG_RUNTIME_DIR` (a copy outliving the host would be a box whose Game Mode silently does
nothing), is swept unconditionally at startup, and its removal sits above every early return in the
restore — the desktop-active return is exactly the path that would leak it. The restore *restarts*
rather than starts, because `start` on an active-but-idle unit is a no-op that would log success
over it.

With nothing stopping a display manager any more, the whole chain built to survive doing so is
deleted: `try_stop_display_manager`, `ensure_host_survives_dm_stop`, `host_is_under_user_manager`,
`cgroup_under_user_manager`, `linger_enabled` and `dm_plan`'s mask input — 142 lines out, 17 in.
**Two shipped facts became false and are corrected:** the takeover no longer has to stop the display
manager, and it no longer needs the `punktfunk` group (the docs and the shipped Bazzite `host.env`
both said it did). That group still gates the usbip nodes the virtual Steam Deck pad attaches
through, which is what the advice now narrows to. Kept from the first step: `any_live` counts
`deactivating` and `reloading` (a unit mid-teardown used to read as a dead leftover, so a box that
*is* in gaming mode sampled as idle); `DmHelperError::shape()`; `watch_for_relogin_storm()` (two
`read_dir`s of `/run/systemd/sessions` 5 s apart, ERROR above 1/s, detect-only, and it states that
no audio, input or PipeWire measurement taken during a storm is valid); and `systemctl_system`
capturing stderr at DEBUG, since that verb is *expected* to fail on an unprivileged host and its
"requires interactive authentication" line was going to the journal on the successful path.

### KWin 6.6 creates our virtual output disabled, and refuses to stream it

On KWin ≥ 6.6 `streamVirtualOutput` creates the output on the backend and then hands
`workspace()->findOutput(output)` to the stream — null for an output the workspace does not manage
(`wantsToManage` = `isEnabled() && !isNonDesktop()`). An output KWin creates **disabled** is
therefore refused with "Could not find output", translated into the session's language and logged
nowhere, because disabling an output is a perfectly valid configuration that applies successfully.
6.4/6.5 passed the backend output straight through and streamed it either way. It repeats forever:
the host asks for a *stable* per-client output name precisely so KWin persists that client's scale
and mode against it, so a stored configuration naming it `enabled: false` is reapplied to every
future session for that client — and the user cannot fix it in System Settings, because the output
only exists for the few milliseconds the request is alive. The host now enables the output and
retries. Related, from the same investigation: a **translated** KWin refusal used to burn all 8
retries because the match was against KWin's message rather than our own prefix.

### Windows client: a per-user installer and a portable zip, because Steam must spawn the exe

A user report — launching through Big Picture does not work and the Steam overlay never appears —
turned out to be nothing to do with the app being UWP (it is full-trust Win32 under MSIX too) and
everything to do with the MSIX install **shape**: the exe lives under the ACL'd `WindowsApps`
directory that Steam's non-Steam-game picker cannot browse, and alias / `shell:AppsFolder`
activation defeats the overlay's injection. Steam has to spawn the exe itself, from a normal path.

- **`punktfunk-client.iss`** — a per-user Inno Setup install (no UAC) to
  `%LOCALAPPDATA%\Programs\Punktfunk`, re-creating in `HKCU` what the MSIX manifest granted: the
  `punktfunk://` scheme, the Start entries, and `{app}` on the user PATH for the `punktfunk` CLI. It
  fetches the Windows App Runtime when missing.
- **`pack-client-installer.ps1`** consumes `pack-msix.ps1`'s layout (one assembly, three artifacts),
  signs the four exes individually and emits `setup.exe` plus a portable zip — same signing backends
  and fail-closed-on-tags rule as its siblings, and no `.cer`, because an exe runs untrusted.
- **`windows-client.yml`** packs after the MSIX and publishes/attaches the new artifacts;
  canary/latest aliases are `punktfunk-client-setup_<arch>.exe` and `..._<arch>-portable.zip`.
- **`deeplink.rs`**: `write_shortcut` targets the app-execution alias only under package identity —
  an unpackaged install has no alias but does have a stable path, so it targets `current_exe()`.
  `has_package_identity()` is now shared with `main.rs`'s AppUserModelID probe.
- Uninstall is `Settings → Apps → Installed apps` (per-user, no admin prompt) or
  `unins000.exe /VERYSILENT`; a portable unzip registers nothing and is deleted by hand. Documented
  in install-client (with a "Launching through Steam" section), channels, clients, uninstall, and
  both copies of `platforms.json`.

### Windows host: two session-killers

- **`untune_process` logged from a TLS destructor.** By then `tracing`'s own thread-local state can be
  gone; the log call panicked, and a panic escaping a TLS destructor aborts. The panic hook then hid
  the evidence — it logged through the same framework and panicked the same way, and a panic inside
  the hook is a case where std deliberately does not format the message (the field log: a location, a
  blank line, "thread panicked while processing panic. aborting."). The service manager restarted the
  host ~6 s later, so it read as a reconnect. `untune_process` no longer logs (still atomic under the
  refcount lock); the panic hook writes straight to the `LogRing` (`OnceLock` + `Mutex`, TLS-free;
  `thread::current()` and `Backtrace::force_capture()` verified safe during TLS destruction).
  Reproduced standalone on 1.96.0, byte-identical to the field log.
- **A Windows launch is a hand-off, and 0.30 read its exit as the game's.** `explorer.exe
  "playnite://…"`, `Steam.exe "steam://…"` and shell app-folder links spawn a forwarder that quits a
  second later (launcher already running) or *becomes* the launcher (it was not); the shim window that
  guards this was skipped for hint-less titles — the one shape that needs it — so the lease reported
  running, then the forwarder's exit closed the connection. The forwarder was also a termination
  target. `WinRecipe::owns_game` records which recipe lines start the game (only `gog`, `command` and
  a plugin's own recipe) and which forward; a forwarder's pid is dropped; the shim window applies to a
  bare child or pid whatever the spec holds; giving up on tracking lands on `GameState::Untracked`
  instead of `launching` forever. Fixture in `a_pid_only_launch_reports_its_exit` widened 4 → 8 s
  (it passed only because of the bug); new ignored test drives the field report.

### `scripts/install.sh`: a guided Linux host install (preview)

Plain POSIX `sh`, dash-clean, `curl -fsSL https://punktfunk.unom.io/install.sh | sh`. Detect the
distro from os-release (apt / dnf / pacman / rpm-ostree→sysext; NixOS, SteamOS, Windows and unknown
distros get a one-line pointer and stop; Debian 12 / Ubuntu 24.04 / Mint 22 / Fedora 45 hit the
documented floors with the right docs link) → install using the `data/platforms.json` lines
**verbatim** (channel and the Fedora group are edited into the string at run time) → run
`punktfunk-host detect-conflicts` (exit 1 = an active Sunshine-family host) → offer to keep both by
moving the management API port (`PUNKTFUNK_MGMT_BIND`, default 47991, which the firewall step then
opens) → input group (`ujust` on Bazzite) → optional `punktfunk` group, GameStream compat and shared
clipboard, all defaulting to no → firewalld/ufw profiles → enable host + console (+ the plugin
runner where it is not) → optional linger → verify (unit active, UDP 9777 bound) and print the
console URL, the password command and the pairing steps.

`--dry-run` prints every command and changes nothing; `--uninstall` reverses the install and the
service enable per family (user units off first, then only the punktfunk packages actually
installed, then the repo — config, groups and firewall stay, as `/docs/uninstall` states). Every
prompt has a `PUNKTFUNK_INSTALL_*` environment twin so `--yes` (or no terminal) runs unattended, and
stdin is never read, because under `curl | sh` stdin *is* the script. Re-running is safe. The
end-of-run check catches the two NVIDIA silent failures on every family — no driver at all, and a
module the kernel refused to load under Secure Boot — via an `nvidia-smi` probe pointing at the
troubleshooting anchor.

It is labelled **PREVIEW** on purpose: the per-distro docs pages remain the documented default until
it has mileage. CI runs it: a new `installer-smoke.yml` exercises install and `--uninstall` per
package family, and `check-docs-drift.sh` gate 7 runs the 16-file os-release detection matrix
through the real script under `--dry-run` on every push. One bug fixed by the first smoke run: the
`/dev/tty` probe used `-r`/`-w`, which answer yes in a container that has the node but no
controlling terminal, so the redirect failed — it opens the device instead now.

### One home per fact: `data/platforms.json`, and CI gates against drift

Install commands, repo URLs and port numbers had drifted across four surfaces. They now live in
`data/platforms.json` and nowhere else: the docs-site install pages quote it through an
`<Install platform="…"/>` MDX component reading a byte-identical snapshot at
`docs-site/src/data/platforms.json` (the Docker build context is `docs-site/` alone, the same
arrangement `openapi.json` uses), `<Ports/>` renders the port table from it, the website download
page vendors it, and `install.sh` runs it. `scripts/ci/check-docs-drift.sh` gates the parse, the
snapshot sync, undocumented `PUNKTFUNK_*` knobs (against a checked-in baseline) and the detection
matrix; `check-docs-links.sh` covers dead links.

⚠ **Two consequences for whoever cuts this release.** The website vendors `platforms.json` and only
refreshes when someone runs `bun run sync-platforms` in punktfunk-website and commits — the release
flow in `docs/releases/README.md` gained that step, and `platforms.json` **did** change this cycle
(the Windows client download). And the `.gitea/PULL_REQUEST_TEMPLATE.md` now asks the one question
CI cannot: did a user-facing fact change, and is the page that owns it updated in the same PR.

### Clients can send their logs to the host, on every platform that has a console

0.30 shipped "Send logs to host" on the Gaming Mode console alone and named the Apple and Android
legs as follow-ups. Both landed here.

- **Apple** — a `ClientLog` drop-in for `Logger(subsystem: "io.unom.punktfunk", category:)` with the
  same call shape, writing os_log *and* a process-global ring bounded at 4096 lines / 768 KiB (under
  the host's 1 MiB cap), stamped wall-clock ISO-8601 so a bundle lines up with the host log;
  `.debug` stays out of the ring, which is the Steam Deck DPB lesson applied in advance. 13 `Logger`
  declarations swapped. `MgmtTransport`/`MgmtConnection` POST a length-framed body on the same
  pooled, pinned mTLS connection; `SendLogs.toHost` requires identity and pinned fingerprint, the
  same gates as the library. Reachable from the host card's context menu and the gamepad host
  options. Paired with ABI v25 above, the Swift client finally hears the core's own lines too
  (`core.<crate>`, info ceiling by default, `PUNKTFUNK_CORE_LOG_LEVEL` raises it).
- **Android** — `pf-client-core`'s logring RING half (note/render/wallclock, std-only) is
  Android-enabled, with `send_to_host` still desktop-gated alongside the ureq fetches; `wallclock`
  moves in from the session's ring layer so every feeder stamps lines identically. `JNI_OnLoad`
  installs a `RingTee`, so every `log` record goes to logcat **and** into the ring in the desktop
  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,
  the runner's log shipper and the tray dialing a dead port (task Running, plugins never registering,
  empty library, "no logs at all"). `sdk/src/config.ts::publishedMgmtUrl` reads
  `<config_dir>/mgmt-endpoint`; `resolveConfig` uses it after `PUNKTFUNK_MGMT_URL` and before the
  default; `runner-cli.ts` exports it into `PUNKTFUNK_MGMT_URL` before any plugin loads (older
  vendored SDK copies follow too). New `pf_paths::published_mgmt_port`; `punktfunk-tray` depends on
  `pf-paths` and its `mgmt_port` is `Option<u16>` — `None` re-reads the file every poll. SDK 83 tests
  (4 new). **Unpublished — `sdk-v0.1.5` owed.**
- **`scripts/windows/scripting-run.cmd`** redirects the runner's stdout+stderr to
  `%ProgramData%\punktfunk\plugin-state\runner.log` (previous run rotated to `.1`; writability probed
  with `copy /y nul`; no `goto`, the file is LF). Verified by reading only.
- **`@punktfunk/plugin-kit`: `SyncSettings.minInterval`** (optional; `LibraryPluginDef.minInterval`
  overrides), default `DEFAULT_FS_CHANGE_MIN_INTERVAL` = 30 s — a floor on top of the 3 s debounce,
  which cannot bound the *rate* under sustained churn (`plugin:steam sync (fs-change)` 102× in
  27 min). Changes inside the hold coalesce into one trailing sync. **Unpublished — `plugin-kit-v0.4.3`
  owed.** Narrowing the Steam plugin's watch set lives in the steam plugin repo.
- **Nix binary cache at `https://nix.unom.io`** (`nix.yml` third tier: build Rust packages +
  gamescope, sign, publish on every main push; a release needs no new trigger since `Cargo.toml` is
  in the path filter). Only punktfunk's own store paths (~300 MB per publish); the step asserts every
  output matches the name filter; NARs before narinfos, rsync without `--delete`. New
  `packaging/nix/server/{Caddyfile,compose.production.yml,prune.sh}` (a `caddy:2-alpine` static tree
  on unom-1 beside the flatpak repo) and `scripts/setup-nix-cache.sh` (five stages; the secret key is
  shown once and never written to disk; four stages after #318, which also made it detect an
  installed key and refuse to casually regenerate one). The signing key is generated and installed as
  the `NIX_CACHE_SIGNING_KEY` Actions secret; its public half,
  `punktfunk-cache-1:yhOJmHxzg6tzXpxSFzlYn6Pc6r0jHprsWqt8MZC654o=`, is pinned in `install.md` and
  `packaging/nix/README.md` and served by the cache at `/punktfunk-cache.pub` (the wizard compares the
  two and warns on mismatch). DNS for `nix.unom.io` is provisioned through `unom/infra`'s OpenTofu
  (`terraform/cloudflare/records.tf`, applied by `dns-cutover.yml`) — not a dashboard click.
  `inputs.punktfunk.inputs.nixpkgs.follows` defeats the cache entirely. Rejected: Gitea's package
  registry (no Nix type), storage.unom.io (home uplink, and S3 answers 403 not 404 for a missing key,
  which nix treats as fatal).
- **Apple console-UI parity** (Swift, PunktfunkKit/PunktfunkShared): `LibraryCollation` ports
  `pf-console-ui`'s `collate.rs` (the desktop's eight tests by name; both read
  `clients/shared/library-collate-vectors.json`, new — desktop is the source of truth and regenerates
  it); `GameEntry.platform` (sent in `GameMeta` all along, dropped by `Codable`); `LibraryPlaceStack`,
  `CollectionsHandover.decide`, `LibraryGridCursor` (port of `GridShape`/`grid_step`/`grid_col_hint`,
  nine grid tests by name), `GridGeometry` (the grid owns its scroll offset — no trackpad wheel on the
  grid, a named trade); `ConsoleContract.swift` pins `ConsoleMotion` to the shared vectors'
  `motion_spring` (response 0.42, damping 0.88, slide 36, scales 0.985/0.96, reveal 0.4,
  interruptible; the v1 `$deprecated` note now names Android as the last v1 reader — and Android
  moved to the shared shell in this same release). Device keys `librarySort` / `libraryView` /
  `libraryCollections` / `libraryGroupBy` — presentation only, never in a profile. `PosterImage`
  decodes at the drawn size (`CGImageSourceCreateThumbnailAtIndex`). `HostCardView`'s primary action
  reverted to connect (`22fdea66` reverted; `swift test` 375/0). New dev hooks
  `PUNKTFUNK_FAKE_LIBRARY=<file.json>`, `PUNKTFUNK_SHOT_EDITING=<field>`, `PUNKTFUNK_SHOT_INTERACTIVE=1`
  (screenshot harness only).
- **New environment variables:** `PUNKTFUNK_PAD_SINK_VOLUME` (`=0` skips both pad-sink pins),
  `PUNKTFUNK_DUALSENSE_USBIP_GRACE_MS` (pad-arrival grace), `PUNKTFUNK_USBIP_TRACE` (byte-level
  USB/IP trace prefix, off by default), `PUNKTFUNK_CORE_LOG_LEVEL` (Apple: raises the ABI v25 log
  sink's ceiling above its info default), the three Apple screenshot-harness hooks above, and nine
  `PUNKTFUNK_INSTALL_*` twins for `install.sh`'s prompts (`_YES`, `_CHANNEL`, `_GAMESTREAM`,
  `_CLIPBOARD`, `_PUNKTFUNK_GROUP`, `_LINGER`, `_MGMT_PORT`, `_DRY_RUN`, `_OS_RELEASE`).
  `PUNKTFUNK_STREAM_SINK` gained the `stream` value and is documented for the first time.
- **A Steam Deck never learned a host's wake MAC, so Wake-on-LAN was skipped there in silence.**
  Every wake gate reads `!host.mac.is_empty()`, and the MAC only ever reached the store through
  `trust::learn_mac`, whose two callers were the GTK and WinUI hosts pages — neither of which runs
  in Gaming Mode. Rather than add the missing call twice, the three per-field learners (`learn_mac`,
  `learn_os`, `learn_mgmt_port`) collapse into one `learn_from_advert`, called wherever an advert
  meets a saved record: both desktop hosts pages, the console home, and the CLI's `discover`.
  Remembering one call is not something a front-end can half-do; remembering three is what produced
  this (#322).
- **`HostRow` gains `clipboard_sync`** (`#[serde(default)]`) and `ConsoleCmd` two variants,
  `BindProfile` and `SetClipboard` — additive and default-tolerant. From the 2026-08-19 console-ui
  sweep, which also brought touch deferred-tap and drag-to-scroll to the console (a swipe across the
  settings list used to cycle whatever value it landed on, because `MenuList` presses focus *and*
  activate), Controller haptics/speaker rows, and two Android idle gates (the reachability sweep
  only probes while the console is attached, and the render thread halves its rate after 60 s
  without input).
- **Cancelling a connect returns the console immediately.** The takeover could only be dismissed by
  a session phase coming back from the embedder and nothing guaranteed one would: Android's shell
  sent no phase at all on the cancelled path, and the desktop shell waited on a pump parked inside
  the blocking `NativeClient::connect*`, which had no abort — 15 s on a normal dial, **185 s** on a
  request-access connect the host holds pending approval. The private `connect_*` inner fn takes a
  trailing `cancel: Option<Arc<AtomicBool>>`; not exported through the C ABI.
- **A portable Playnite's covers survive the art confinement.** A Playnite unzipped outside the
  users base keeps its library beside the exe, so every cover it exports sits outside every default
  art root: the games synced and all **70** covers were dropped, with `PUNKTFUNK_LIBRARY_ART_ROOTS`
  the only way out. The Playnite install dirs are art roots now, exactly as Steam's install root
  already was, and `playnite_install_dirs` learned to find a portable copy at all — it registers no
  uninstall entry and sits under no profile, but it does register the `playnite://` handler, which
  is the very registration the launch path already follows. So a portable install also gets its
  Fullscreen launcher tile, which it never had. The confinement is not loosened: roots come from the
  host's own registry and filesystem probes, never from the plugin lane that supplies the art path.
  Paired with the plugin-kit fix below, a fixed host no longer needs a cache file deleted.
- **`plugin-kit`: `startup` and `manual` sync reasons always publish.** The fingerprint says the
  plugin would compute the same entries again; it does *not* say the host still holds them — and the
  host may accept a payload and store less of it (an art path outside its roots is stripped and the
  games kept, deliberately, because a cover must not cost a library). Once that happened the
  fingerprint was a permanent "no changes", and the only way out was deleting the plugin's cache
  file, which is exactly the advice a portable-Playnite library with 70 dropped covers was given.
  The two triggers with a person behind them now always apply.
- **Nix:** nixpkgs bumped because its gamescope 3.16.24 no longer took our patch 0009 (the publish
  tier was red on every build); `enableWsi` is a nixpkgs *function argument* defaulting to false, so
  the plain derivation shipped a compositor with **no WSI layer at all** and nothing under it could
  obtain an HDR10 swapchain — our own postInstall assertion caught it. Also: the prune makes `$out`
  writable first (reshade installs read-only), the bun builds are serialised and the OOM is measured
  against the real 7 GiB cgroup cap rather than guessed at, and a dispatch opt-in compared against
  the string `"true"` silently skipped when the API delivered a real JSON boolean — the step was
  skipped and the job still reported success.
- **New packaging payload (Linux host, rpm/deb/arch; nix where noted):** `scripts/60-punktfunk.rules`
  (+2 sound rules), `scripts/60-punktfunk-dualsense.conf` (WirePlumber, also nix),
  `scripts/alsa-ucm2/…` (UCM drop-in, **not** nix). Bazzite sysext inherits all three from the RPMs.
- **Docs:** `AGENTS.md` + `docs/agents/` (issue tracker is Gitea via the `gitea` MCP server; the
  five triage labels; single-context domain docs). A host audio-source comment corrected
  (`pw_impl_node_set_driver` marks props changed but leaves the flush to the next info emission).
- **CI:** the Nix publish job records `df` after the build as well as before; the
  `linux-client-screenshots` run publishes its PNGs to the generic package registry as well as the
  v3 artifact store (which is browser-only, so nothing could reuse the shots for the docs — that is
  how the get-started track got its fifth screenshot, a client's host list); and **every Linux
  `bun install` is now wrapped in `scripts/ci/retry.sh`**. That last one is a real failure, not
  tidying: `bun install` streams download-and-extract, so a tarball truncated by the runner's
  packet loss under parallel load surfaces as `error: Fail extracting tarball for "<pkg>"` and
  names a package that is perfectly intact — measured on run 19630, where docs-site died on
  `@rolldown/binding-linux-x64-gnu` while the web job installed the same registry in the same run
  and run 19632 installed the identical lockfile seven minutes later. The tarball's sha512 matches
  the lockfile and bun 1.3.13 and 1.3.14 both extract it from disk, so neither the package nor the
  floating `oven/bun:1` bump was ever at fault. `retry.sh`'s header had already diagnosed this
  class and said to wrap every single-shot network command; `bun install` was the one still
  unwrapped. Three attempts rather than the usual five, so a genuinely stale lockfile still fails
  fast under `--frozen-lockfile`.
- **The web console's Virtual displays page** put the Streamed-screen and session-lifetime cards
  below the tab shell, so both rendered on both tabs; they are policy surfaces and now sit inside
  the Configuration tab, leaving the Live tab as the live list plus arrangement.

### Verification status

Gates run on the release tree (this MacBook, rustc/rustfmt 1.96.0 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 android.yml
Play notes gate run verbatim — 456/500 characters and not byte-identical to any prior release's;
both openapi copies `cmp` identical, both stamped 0.31.0; notes voice scan clean outside the
For developers section.

⚠ **This release was cut more than once.** The first cut (`601f040f`, merged as #320) was never
tagged, and 41 more non-merge commits landed on top of it — the Windows client installer, the
guided Linux installer, the docs overhaul, ABI v25, the KWin 6.6 repair and the takeover's final
shape among them; a handful more (the Virtual displays tab fix, the fifth get-started screenshot)
arrived while the second cut was being written. This section, the version table and the notes are
all re-measured on the latest tip; where the cuts disagreed, the earlier text was **rewritten
rather than appended to**, because none of
the intervening work ever shipped. Specifically: the "C ABI unchanged / header byte-identical"
claim is gone (it is 25 now), the openapi row moved off 0.29.0, the SDK and plugin-kit rows record
cuts that have happened rather than cuts that were owed, and the Gaming Mode takeover section
describes idling the autologin rather than stopping the display manager — a within-cycle correction
no user could have seen.

⚠ **The C ABI harness (`tests/c_abi.rs`) did not run on this cut**, and this time the header *did*
change: it links the staticlib with `-lopus` and this machine has no libopus (`ld: library 'opus'
not found`), which is an environment gap, not a code fault. `punktfunk_set_log_callback` is
therefore compiled by cbindgen and by the Rust unit tests here, but the generated header has not
been compiled by a C compiler on this cut — the CI runner is its first. Worth naming because ABI 25
is the one versioned surface that moved.

⚠ **Verified by reading only** — compiled nowhere available to the cutting host: the Windows client
installer and portable zip (`punktfunk-client.iss`, `pack-client-installer.ps1` — the pack step is a
Windows runner's), the Windows runner log redirect (`scripting-run.cmd`), the tray's `Option<u16>`
port on Windows, and the sway half of `topology: exclusive` (no live sway in the fleet, as with
#283).

⚠ **Not verified on hardware by this cut**, named rather than left to be discovered: the null-sink
capture topology's on-glass validation (pw-top showing our sink at the top of its own group, 5 min
of loud audio at `delivered_pct=100 gaps=0` on a box where a hardware sink also runs) was still owed
when it landed; the 96 kbps speaker lane was judged on glass by ear only; the Android
`ASurfaceControl` path was verified on one device (Nothing Phone 3), with the fallback presenter
byte-for-byte the 0.30 one; the Mac Accessibility intercept (the tap ahead of Spotlight, inside the
sandbox) needs a granted Accessibility switch the dev machine does not have; and `install.sh` is
smoke-tested per package family in CI containers but is shipped **preview** precisely because it has
no real-box mileage, Bazzite above all.

⚠ **Owed outside this repository:** `data/platforms.json` changed this cycle (the Windows client
download), and the website's download page vendors a copy that only refreshes when someone runs
`bun run sync-platforms` in punktfunk-website and commits — step 1 of `docs/releases/README.md`.

---

## v0.30.0

175 commits since v0.29.0 (131 non-merge).

Two large surfaces landed in this cycle and both are **additive**: a lossless PCM audio plane
alongside Opus, and per-client access grants on the trust record. Between them the C ABI moves
**20 → 24** in four steps, every one of them a new symbol — no existing function changed its
signature or its behaviour, and no `#[repr(C)]` struct grew a field. `WIRE_VERSION` stays **2**:
everything new rides the trailing-field append discipline the `Welcome` has used since v20, so an
older peer stops reading earlier and negotiates exactly what it always did. Every 0.29.x host,
client, driver and plugin keeps interoperating in both directions, with no re-pairing.

Three things need a hand rather than merely an update. The keyboard-layout fix needs a gamescope
rebuilt at `+pfhdr8`; two Windows hardening changes alter what the service will adopt out of
`%ProgramData%\punktfunk\host.env`; and two **defaults flipped** — the host now serves the lossless
audio plane unless told not to, and the "Show game library" client setting is gone along with the
field behind it.

### Versions

| | v0.29.0 | v0.30.0 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged — `Hello` and `Welcome` grew trailing fields older peers never read, and one new control message took a free type byte (below) |
| C ABI | 20 | **24** | four additive steps: 21 `connect_ex10`, 22 access, 23 `audio_plc`, 24 `connect_ex11` (below) |
| Rust edition | 2024 | **2024** | unchanged |
| MSRV (`rust-version`) | 1.85 | **1.85** | unchanged |
| Workspace crate dirs | 27 | **27** | unchanged |
| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3); `pf-driver-proto` shows no diff against the v0.29.0 tag |
| Windows virtual-gamepad channel | 3 | **3** | unchanged |
| Plugin index schema | 1 | **1** | unchanged |
| `api/openapi.json` | 0.28.0 | **0.29.0** | regenerated for diagnostics, client-log bundles, access grants and the game-lifetime fields; it keeps the stamp it was regenerated under. ⚠ The ungated `docs-site/public/openapi.json` copy had drifted (see below) and is re-synced byte-identical in this release commit |
| gamescope patch level (`+pfhdrN`) | 7 | **8** | patch 0010 puts the compiled keymap on the seat's stub keyboard (below) |
| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.4** | unchanged |
| `@punktfunk/plugin-kit` | 0.4.1 | **0.4.2** | the Steam art scan learned the newer filenames and the flat layout |

### ⚠ Breaking changes

- **C ABI 20 → 24, addition only.** Four bumps landed in one cycle; each adds symbols and removes
  nothing. An embedder that compares `PUNKTFUNK_ABI_VERSION` at build time rebuilds against the new
  header and is done; one that adopts none of the new calls behaves exactly as it did on 20.
  - **v21 — `punktfunk_connect_ex10`**: `connect_ex9` plus `device_name`, the label an unpaired
    client knocks with. The C ABI had no such parameter, so every embedder took the OS default,
    which resolves through `COMPUTERNAME`/`HOSTNAME` — neither of which exists in an Apple GUI
    process, leaving every Mac, iPad, iPhone and Apple TV knocking as the literal "This device".
    `ex9` keeps its parameter list *and* its behaviour (it passes a null name, selecting that same
    default). The name rides `Hello::name`, which hosts have read since the pending list existed.
  - **v22 — the per-client access surface**: `punktfunk_connection_grants` and
    `punktfunk_connection_access_expires_in` read the session's live access state; 
    `punktfunk_connection_end_reject` reports the typed rejection a mid-session close carried
    (`PUNKTFUNK_STATUS_REJECTED_*`, `0` = none), because `end_reason` can only file an
    access-expiry close under `HOST_ERROR` and that is the wrong sentence for "your access
    expired". The host enforces grants either way — an embedder that never adopts these simply
    lacks the courtesy UX.
  - **v23 — `punktfunk_connection_audio_plc`**: one frame of libopus packet-loss concealment
    synthesized from the connection's *own* decoder state, for an embedder whose playout ring is
    draining because nothing is arriving. A second decoder is not a substitute: PLC extrapolates
    from the last decoded frame, so a fresh instance conceals from empty state. Frames it returns
    carry `seq` and `pts_ns` of `0` — concealed audio was never on the wire and must not reach an
    A/V-sync observation.
  - **v24 — the lossless plane's client surface**: `punktfunk_connect_ex11` asks for a sample rate
    and depth; `punktfunk_connection_audio_sample_rate` / `punktfunk_connection_audio_bits` report
    what the host actually **resolved**, which may be lower;
    `punktfunk_connection_next_audio_pcm` decodes both planes behind one call.
    ⚠ **The format is read through accessors, never through a struct field, and the distinction has
    teeth here.** The natural home for a rate is a field on `PunktfunkAudioPcm`, which is
    `#[repr(C)]` with no `struct_size` guard and is allocated **by value** by every C embedder —
    growing it would change its layout under all of them at once. `PunktfunkStats` is in the same
    position. This is the rule v18 set with `next_rumble_cmd2`.
    `PUNKTFUNK_AUDIO_SAMPLE_RATE_HZ` keeps its value and its meaning as the **default/legacy** rate,
    so a ring sized from it stays correct for every session that resolves to Opus — which is every
    session an ABI-23 embedder can ask for.
- **`PUNKTFUNK_AUDIO_HIRES` on the host defaults ON — explicit-off grammar (operator-visible).** The
  host's half of the lossless gate was an operator opt-in; it is now `0`/`false`/`off`/`no` to
  refuse and anything else to allow, the same shape as `PUNKTFUNK_444`, `PUNKTFUNK_CHACHA20` and
  `PUNKTFUNK_10BIT`. The field stops being the one `Option<bool>` in `pf-host-config` read as
  `unwrap_or(false)` and becomes a plain `bool`. The old default rested on "this spends bandwidth
  the host's owner never agreed to" — every clause of which is still true, except that the operator
  is not who spends it: the *client's* menu choice is, and that still ships OFF. What actually
  protects a link is mechanical rather than consent-based (the capture path must honestly deliver
  the rate, the cost must fit a quarter of the session's video bitrate, and a frame must fit a
  datagram at that channel count), so the operator gate was not keeping modest links safe — it was
  keeping the feature unreachable. **No wire or ABI movement:** `HOST_CAP_AUDIO_HIRES` is set only
  when a session actually resolved to PCM, so it remains a statement about that session's wire
  rather than a capability advert, and an ordinary session without `CLIENT_CAP_AUDIO_HIRES` is
  byte-identical to before. ⚠ The Android comments warning that sending `48000/16` as a stand-in for
  "default" silently opts a user into PCM described the blast radius as "any host with
  `PUNKTFUNK_AUDIO_HIRES=1`" — that is now every host that has not deliberately opted out, so the
  `0`/`0` sentinel is load-bearing in a way it was not before.
- **`trust::Settings::library_enabled` is removed, and the "Show game library" row with it.** The
  console never read the field — its row rendered a value and flipped a bool while every library
  affordance in that shell was gated on pairing alone, so it showed "Game library · Off" and handed
  you the library on Y anyway. What the flag *actually* gated was GTK and WinUI, which hid
  "Browse library…" unless it was on, with a stored default of `false`. Deleting only the row would
  therefore have left every user who never found the switch with a hidden library in the desktop
  apps. **Migration is by construction, not by luck:** `Settings` is `#[serde(default)]` with a
  `#[serde(flatten)] extra` map, so a stored `"library_enabled": false` parses into `extra`,
  round-trips untouched and is ignored — everyone who had it off now has the library, and a
  downgraded binary still finds its old value under the same key. A test pins that contract. At the
  four GTK/WinUI menu sites the flag is replaced by the **pairing** predicate rather than dropped
  for an unconditional item: the library fetch authenticates with the paired identity, and GTK's
  saved cards include trusted-but-unpaired hosts, so an unconditional entry would promote a latent
  "fetch that cannot authenticate" into the default experience. Apple and Android keep their own
  toggles for now, deliberately — both already default TRUE, so nobody there loses anything.
- **Windows: `host.env` keys are now allow-listed into the service environment (operator-visible).**
  `load_host_env` used to import **every** key of `%ProgramData%\punktfunk\host.env` into the
  LocalSystem service's own environment. `%ProgramData%` lets `BUILTIN\Users` pre-create the
  directory, so an unprivileged user could plant `host.env` before install; a planted `SystemRoot`
  then redirected the absolute `icacls.exe`/`powershell.exe` paths the host builds from it — code
  execution as SYSTEM. Only the `PUNKTFUNK_*` and `RUST_LOG` keys the child already allow-lists at
  the spawn boundary are imported now. **An operator who kept unrelated keys in `host.env` will find
  they no longer reach the service.**
- **Windows: a non-admin-owned `host.env` or `web-password` is no longer trusted (operator-visible).**
  A `host.env` whose owner SID is not privileged is renamed aside and the default written over it; a
  non-admin-owned console-password file is rotated to a fresh random instead of being kept as an
  "upgrade". A file from a prior privileged install is Administrators-owned and is kept untouched.
  If you hand-authored either file as a normal user, re-create it from an elevated prompt.
- **gamescope must be rebuilt at `+pfhdr8` for the keyboard-layout fix (packager-visible).** The
  host hands the session `XKB_DEFAULT_*` on all four gamescope launch paths, gated behind a
  `+pfhdr8` probe — an older binary gets a warning naming the reason rather than a silent
  US keymap. The patch series applies `git am`-clean at the pinned `5fb8dce4`.
- **GameStream's UDP/ENet media plane now binds to the launch owner.** The Moonlight-compat video
  and audio endpoints used to bind to the first datagram from anyone, and any ENet peer could hold a
  connection (pinning per-peer reassembly memory). Source IPs that are not the launch owner's are
  now discarded until the 10 s learn budget is spent, and non-owner datagrams are dropped before
  ENet allocates per-peer state. GameStream is runtime opt-in and off in the shipped unit.
- **Re-pairing can no longer escalate access.** `TrustStore::add()` used to *replace* the record; it
  is name-only on re-pair now, so a device that was approved as a guest cannot re-pair its way to
  full control. Records with no grants recorded — every record written before this release — read as
  full and permanent, so nothing changes for an existing install.

### The lossless audio plane: PCM on `0xD3`, alongside Opus

Opus is 48 kHz *by construction* (`opus_encoder_create` rejects 96 000), so hi-res was never a
constant to raise. A second audio plane carries interleaved little-endian PCM under
`AUDIO_CODEC_PCM` (`0xD3`); `AUDIO_CODEC_OPUS` (`0xC9`) and its `0xD2` redundancy are untouched and
remain the default for every session that does not ask.

- **Rates and depths.** `audio::pcm::rate_is_supported` admits 44 100, 48 000, 88 200, 96 000 and
  176 400 Hz, at 16 or 24 bits, including hi-res surround. The 44.1 kHz family took a fix to reach:
  the rate was divided before it was multiplied, and `rate_hz / 1_000_000` is 0 for every rate below
  a megahertz.
- **Frames are sized from RAW worst case, not from a coded estimate.** A datagram over the path MTU
  is not sent at all and this plane is never fragmented. The real ladder at default MTU is
  48/16 → 5 ms, 48/24 → 4 ms, 96/16 → 3 ms, **96/24 → 2 ms**. ⚠ A frame carries a whole number of
  samples *per channel*, so `frame_us` is a **label, not a duration** — at 44 100 Hz a nominal 5 ms
  frame is 220 samples per channel, which is 4 988 662 ns. Size from `samples_per_frame`; take time
  from `frame_duration_ns`, never from `frame_us`.
- **FLAC was planned and deliberately not shipped.** It buys nothing structural here: its worst case
  is a VERBATIM subframe (raw + header), so it gets the same frame duration, packet rate and
  send-buffer sizing and saves *average* bytes only — while this plane rides outside the ABR loop
  and is therefore provisioned for peak. The host also quantises f32 → 24-bit without dither, so the
  low bits barely compress; at 24 bits a lossless coder saves least. `AUDIO_CODEC_FLAC_RESERVED = 1`
  keeps the numbering so FLAC stays purely additive later.
- **Capability bits.** `HOST_CAP_AUDIO_HIRES = 0x80` and `CLIENT_CAP_AUDIO_HIRES = 0x10`.
  ⚠ **`0x80` was the LAST free `host_caps` bit** — `video_caps` was already full, so the next host
  capability needs a second byte and an ABI bump. ⚠ `Hello`'s post-HDR tail is capped at 27 bytes
  (with no HDR block the decoder disambiguates by remaining length, so a 28-byte tail is misread
  *as* an HDR block); **8 of those 27 are now spent**.
- **The host serves it by default; the client's menu choice is the opt-in.** See the breaking-changes
  entry above — `PUNKTFUNK_AUDIO_HIRES=0` is now the refusal, and the decline log names the opt-out
  and the value it must have rather than sending people looking for something to enable.
- **Cost and the affordability rule.** The plane costs **1.4–8.5 Mbps** in stereo — up to **33.9** for
  176.4 kHz/24-bit 7.1 — against Opus's 256 kbps, and it rides QUIC datagrams **outside the ABR
  loop**, off the top of the link where ABR can neither see it nor claw it back. A session therefore
  gets it only if the cost fits **a quarter of that session's video bitrate**: a 5 Mbps session can
  afford no rung at all. On game content it is very unlikely to be *audible* — 256 kbps Opus is
  already effectively transparent and nothing above 24 kHz is hearable — so the win is
  **bit-exactness**: no lossy stage anywhere, and no resample for a host whose interface genuinely
  runs at 96 kHz.
- **The host's gate, and what it can and cannot promise.** Every decline lands back on
  Opus at 48 kHz. ⚠ The gate checks format validity, not delivery: on Linux, PipeWire ships
  `clock.allowed-rates = [ 48000 ]`, and a rate that is not listed is **resampled into the running
  graph rather than switched to** — so a sink declaring 96 kHz on a stock box gets resampled and the
  gate does not catch it. Add the rates to `clock.allowed-rates` to make the sink the graph driver.
  (`clock.rate` in the settings metadata is the *default*, not the live graph rate; read `pw-top`.)
  On Windows the decline is floored at 48 kHz so only a hi-res request can lose — declining whenever
  `engine_hz < requested` would open capture at 44 100 on an ordinary endpoint, which libopus
  rejects, regressing the shipped Opus path.
- **Client-side gating happens before the connect, because that is the last point at which declining
  is free.** Windows reads the render endpoint's own mix format and withholds the capability bit
  when the engine cannot carry the rate (`autoconvert` would otherwise silently downsample a 96 kHz
  stream on arrival while every log line agreed the session was hi-res). Android probes an AAudio
  stream at the requested rate, reads back what was granted and closes it without starting it —
  AAudio never substitutes a rate, so a 48 kHz rung under a 96 kHz session could only ever produce
  2× playback. The ladder is 96 → 48-keeping-depth → the legacy pair.
- ⚠ **48 kHz/16-bit lossless is unreachable through the parameter pair** — that request is
  byte-identical to a legacy one, and the capability is derived from "asked for a non-default
  format". 48/24 is the real bottom rung.
- **Settings vocabulary is shared across all four clients** under the key `audio_format`, so a
  profile round-trips between a phone, a TV and the desktop. ⚠ **The menus are not all the same
  length.** Apple and Android list the full ladder — `opus`, `lossless441`, `lossless48`,
  `lossless882`, `lossless96`, `lossless1764` — while `pf_client_core::AUDIO_FORMATS` (Linux,
  Windows and the Gaming Mode console) lists only `opus`, `lossless48`, `lossless96`. A value a
  build does not recognise resolves to Opus rather than refusing the connect, which is what makes
  the shorter list safe. On the desktop clients `PUNKTFUNK_AUDIO_HIRES` overrides the setting in
  **both** directions with a richer grammar (`1`, a bare rate, `<rate>/<bits>`, or `0`); an
  unparseable value warns and is ignored rather than meaning "off". ⚠ Note the two spellings of the
  same variable name: on a box that is both host and client one line configures both halves, and
  `0` is the one value that means *off* to each.
- ⚠ **`pf-client-core` filters a surround request out before it reaches the wire**, so the desktop
  clients and the Gaming Mode console stay on Opus whenever `audio_channels != 2` — even though the
  host's `channels != 2` decline is gone and the arithmetic supports surround (at 48 kHz both 5.1
  and 7.1 fit a 1 ms frame). Apple reaches the host through `connect_ex11` directly and is not
  subject to it. Delete the arm when the client-side filter learns the ladder, not when the host
  rule changes — the comment at the site says so.

### Per-client access: grants on the trust record

Six bits, an exhaustive classifier and a `Welcome` advert. `PUNKTFUNK_GRANT_GAMEPAD`, `_POINTER`,
`_KEYBOARD`, `_CLIPBOARD`, `_MIC`, `_LAUNCH`; `PUNKTFUNK_GRANT_ALL` is their union and
`PUNKTFUNK_GRANT_RESERVED` its complement. Presets: `_PRESET_FULL` (= ALL), `_PRESET_CONTROLLER_ONLY`
(= GAMEPAD), `_PRESET_VIEW_ONLY` (= 0).

- **Storage is back-compatible by absence.** The grant mask and `expires_unix` are optional serde
  fields on `PairedClient` in `punktfunk1-paired.json`; absent means full and permanent.
- **Enforcement is default-deny and happens at setup**, not per-event: no uinput pads are created,
  no mic is attached, no clipboard coordinator is started for a device that lacks the bit. Launch is
  refused at the handshake with a typed reject. QoS messages (reconfigure, bitrate) are deliberately
  ungoverned.
- **Expiry is wall-clock**, warned at T−5m and T−1m over a new `AccessUpdate` control message, and
  closed with `RejectReason::AccessExpired` (`ACCESS_EXPIRED_CLOSE_CODE = 0x69`). An expired device
  falls into the knock path for one-click re-grant.
- **The mgmt API carries grants in its payloads**, with `PATCH` to change them live; a per-fingerprint
  watch pushes the edit into any running session. ⚠ `PATCH` 404s on a Moonlight client with no
  registry record — the console shows those as "Full (ungoverned)" until the mgmt upsert lands.
- **Moonlight/GameStream**: an absent registry record is ungoverned `GRANT_ALL`; an existing record
  governs launch, input and the clock.
- ⚠ **Three limits are documented rather than papered over** (`docs-site` → Access levels):
  shared-desktop visibility is not isolation, Moonlight rows are ungoverned until they have a
  record, and older clients are *enforced* but get none of the chrome (no chip, no countdown).

### The presentation clock: play frames out on the source's cadence

Every client used to present a frame the moment it was decoded, so the transport's jitter landed on
the glass 1:1. `CadenceClock` estimates the offset between the source clock and the present clock
and returns a due time on the source's own timeline plus a cushion sized to the measured jitter.

- It is **type-2** (offset *and* per-frame rate) because two free-running crystals produce a ramp and
  a proportional-only loop lags a ramp forever. Fixed-point `i64` throughout, so it runs identically
  on every client and in the offline harness.
- **It smooths the OFFSET, never the timestamps.** Genuine variation in the source's own cadence — a
  variable-rate renderer, an irregular capture tick — passes straight through. Anything that made due
  times more evenly spaced than the source would be a bug, and `preserves_source_cadence` is the test
  that says so.
- **Domain-agnostic by construction**: a constant offset between clock domains is absorbed by the
  offset estimator, so each client feeds `ready_ns` and reads `due_ns` in one domain with no
  conversion anywhere in the path.
- **VRR stops being merely not-worse.** Where the presenter has *measured* variable refresh (the
  existing `CadenceProbe` verdict, not a capability bit), the snap is skipped and the frame is
  presented at its due time under `free_running()` tuning. `Unknown` reverts to snapping — the
  absence of a measurement is not a measurement.
- **The host half is the prerequisite, not the alternative.** All three Linux publish sites stamped
  `pts_ns` with `SystemTime::now()` inside *our* PipeWire process callback — the instant the buffer
  was delivered to us, not the instant the compositor produced it. Source-timestamp playout would
  have faithfully reproduced that jitter. The compositor's `spa_meta_header.pts` is now rebased into
  the wire's realtime domain from a re-sampled clock pair, with a per-frame plausibility gate falling
  back to the delivery stamp (counted, never silent) beyond 50 ms. `PUNKTFUNK_CAPTURE_HDR_PTS=0`
  restores delivery stamps.
- ⚠ **`host_us` and `e2e` now read HIGHER** by the delivery delay that was previously not counted.
  The numbers moved because they got truer.
- ⚠ One-present-per-slot is now `PresentGate`'s job. Where present timing is live that is strictly
  better; where it is unavailable the gate is inert and a faster-than-panel stream can submit two
  presents into one vblank. That was already `latency`'s behaviour on those boxes but it is new for
  `smooth`.

### Audio robustness: droughts, holes and what the counters actually mean

- **Drought concealment on the decode thread.** The decode path already concealed a *seq gap*, but
  that only fires when a later packet arrives to reveal it. When the wire simply goes quiet the ring
  drains, the callback runs short, and the de-jitter policy de-primes and re-primes a whole target's
  worth of fresh silence — an artifact far longer than the audio actually missing. `DroughtConceal`
  is bounded by `JitterTuning::plc_max_ms()`, **twice the preset's own de-prime fuse, derived rather
  than added as a fifth field** so it cannot drift from the thing it protects. Denominated in
  **time**, never in frames or callbacks — that is the recorded lesson from this very fuse, where a
  count gave an iPad a third of a Mac's slack. `plc_ms=` joins the 10 s playback line at all three
  Rust sites; Apple reaches the same behaviour through ABI 23's `audio_plc`.
- **A capture hole cost more than itself.** `audio_thread` blocked in `next_chunk` for the whole
  duration of a hole and nothing left the host. The loop is deadline-driven now
  (`next_chunk_within`) and covers a hole with silence frames on the existing pacer schedule,
  continuous in `seq` and `pts`, for up to 500 ms. Past that the host is not glitching, it is quiet.
  The capture counters deliberately measure *upstream* of the infill, so infill can never make that
  line look healthy.
- **`delivered_pct` could not distinguish an outage from starvation.** `CaptureStats` gains
  `gaps`/`max_gap_ms`/`missed_dequeues`, and `pauses`/`paused_ms` beside the percentage they explain
  — a 16.2 s `Paused` span scored `gaps=0` correctly and hid the outage inside `delivered_pct`,
  because the reporting window is flushed from the process callback and stretches by exactly the
  time we were absent. The negotiated quantum now tracks what the graph actually hands over (a new
  size must survive three callbacks before it is believed) instead of latching the first callback.
- **`audio egress` is a new 30 s line** — `sent`/`infilled`/`late`/`max_late_ms`/`max_spacing_ms`/
  `reanchors`. The send path had no periodic metric of any kind, which left "the host paces audio
  badly" unfalsifiable. Note `reanchors` in particular: the pacer forgives accumulated debt
  silently, and that is precisely the event that leaves no trace and then gets blamed on the network.
- **The minted sink sets `session.suspend-timeout-seconds=0`** — deliberately *not*
  `node.always-process`, which would keep the node scheduled with nothing connected and run its
  callback 200 times a second on a host sitting between sessions.
- **The capture phase lock stops flapping.** Engagement now needs five consecutive coherent reports,
  each incoherent cycle backs off longer than the last (10 ticks doubling to 320), and a host that
  has torn down an engaged grid eight times parks the lock for the session. Only a disengage that
  tore down an *engaged* grid counts toward the fuse, so a launch-time shader storm cannot fuse a
  host that then locks perfectly for hours. The disengage line gains `coherence_milli`.

### ABR: the behind-cadence deadline was the negotiated refresh

A frame's encode work was scored against the negotiated interval (8.33 ms at 120 Hz), but a frame's
real budget is the arrival of the next frame that actually exists — a 60 fps source gives every
frame twice that. An encoder keeping up with every real frame could be marked behind on most of
them, latch `behind_score` past `DEPTH_DEGRADE` and refuse every climb the client asked for. The
budget is now the **observed source-delivery period**: an EMA over real frames' arrival spacing
(repeats excluded), clamped to `[interval, 4 × interval]` so a source at or above the negotiated
rate keeps today's deadline bit-for-bit and a hitchy source cannot disarm the detector. Every
`cadence_degraded` transition now logs `behind_score`, `escalated` and budget/interval/observed
period, rate-limited to one line per 5 s with suppressed flips counted; the climb-refusal line
carries the live `behind_score`.

### ABR, client side: a host-local rebuild is no longer read as congestion

A Windows exclusive-topology eviction rebuilds the capture ring and encoder in place — a few hundred
milliseconds, entirely host-local, not one packet lost. The client decides on 750 ms windows, so a
window straddling that rebuild sees almost no stream: the 0.29 field log shows 401 ms of rebuild
producing `actual_kbps=390` against a 20 000 target with `loss_ppm=0`, read as congestion, costing
×0.7 plus slow start and three minutes at ~15 Mbps on a link that never dropped a packet. Three
independent changes:

- **`PipelineGap` — a new control message, type byte `10` (`0x0A`).** It extends the video/rate-control
  block (`0x01`–`0x09`) it belongs to, because its only consumer is the same ABR controller
  `LossReport`, `SetBitrate` and `BitrateChanged` already feed — deliberately **not** in the `0x30`
  clock block, since it carries a *duration* precisely so that no clock domain is involved. The host
  is the one party that knows, and it now says so; the client already knew how to throw a window
  away (`discard_abr_window` feeds the controller nothing, sends no `LossReport` so a bogus window
  cannot spike the host's adaptive FEC, and closes the standing-latency detector as not-loss-free).
  That path had exactly one cause — the tail of the client's own speed test — and this is its second.
  ⚠ The header gains `PUNKTFUNK_MSG_PIPELINE_GAP` as a `#define`; a message-type constant is additive
  and takes a free type byte, so neither `PUNKTFUNK_ABI_VERSION` nor `WIRE_VERSION` moves.
- **A starved window cannot report the encoder as slow.** `encode_us` is a per-AU host measurement
  averaged over the window; when almost no AUs flowed, the mean is taken over the handful that
  straddled whatever interrupted them and carries that interruption rather than the cost of encoding
  at this rate. It is not a measurement, so it is now withheld entirely when the window is `STARVED`
  — passed as **absent** rather than ignored, so it cannot teach the rolling-minimum baseline either.
  Deliberately narrow: loss, a flush and a dropped frame describe what reached the *client* and mean
  the same thing however little flowed, so those still back off on one window as
  `STARVED_DELIVERY_DIV`'s own comment requires. Only the host-encode signal is withheld, because
  only it is measured over AUs that did not exist.
- **The learned climb ceiling is bounded by what the stream could plausibly use.** The ceiling was
  pure link capacity (`delivered_kbps * 0.7`) with no term for resolution, frame rate, codec or bit
  depth, and the utilization gate cannot supply one — a hardware encoder in CBR mode genuinely fills
  whatever target it is handed, so the field log shows 99 % utilization the whole way up. On a
  gigabit LAN the probe measured 939 Mbps and the session walked to **657 Mbps for 1440p120** — 1.49
  bits per pixel — in 37 seconds, taking client decode latency from 0.78 ms to 10 ms.
  `stream_ceiling_kbps` computes a bound from pixel rate and a bits-per-pixel allowance varying by
  codec generation, bit depth and chroma; `set_ceiling` holds the measured link ceiling to it and
  logs both numbers whenever it binds. Deliberately generous — a bound on the absurd, not a quality
  opinion: 1440p120 HEVC Main10 lands at ~414 Mbps while 1080p60 HEVC keeps ~93 Mbps. It binds only
  what the probe **learns**: a negotiated start rate is a number the host resolved on purpose, and an
  explicit bitrate and every PyroWave session are outside the controller entirely.

### AV1 never decoded on AMD, because the bit reader refused 32-bit reads

Every AV1 session on an AMD host died after ~287 frames and silently fell back to H.265 — the client
log named it on the first access unit ("AV1 parse: more than 31 (32) bits were requested") and then
"No sequence header parsed yet" for every AU after, because the sequence header never parsed and each
new keyframe re-hit the same wall. The vendored cros-codecs `BitReader` refused any read wider than
31 bits "because that would break the `read_bits_signed()` function" — true of the signed path's
`i32` accumulator, and misplaced: AV1 needs 32 bits in five places (`timing_info`'s
`num_units_in_display_tick` and `time_scale`, `decoder_model_info`'s `num_units_in_decoding_tick`,
and the variable-width buffer-delay and `buffer_removal_time` fields). **AMF sets
`timing_info_present_flag`; NVENC does not** — which is why the rung's own evidence string ("one
vendor, no soak") described a codec that had never once decoded on AMD.

Relaxing the guard alone would have been worse than the bug; three edits are required together: the
trailing mask is `u32::MAX` at 32 (`1u32 << 32` overflows — a debug panic, and in release a mask of
zero, i.e. a silent `0`); the byte cursor is advanced before the accumulation loop when it sits at
zero remaining bits (at ≤31 bits the mask discarded those bits, so it was invisible); and
`read_bits_signed` keeps its own `> 31` guard, which is the limit the original comment was actually
protecting. That last guard made a latent panic reachable by test — the sign extension
`-1 ^ ((1 << num_bits) - 1)` overflows at `num_bits == 31`, rewritten as `-1i32 << num_bits`.
**Blast radius is provably AV1-only**: neither H.264 nor H.265 has a read wider than 31 bits, literal
or variable, and every dynamic-width call site in the vendored tree is in the AV1 parser. The 52
upstream conformance tests still pass unchanged. Recorded as PROVENANCE deviation 8; owed upstream as
a cros-codecs issue.

### Game lifetime: a lease nothing is watching now says so

Quitting a game mid-stream could leave the session up and the console showing it as "running"
forever, with no setting that made any difference — because a lease with nothing to recognise its
game by set its **own** state to `Running`, on the reasoning that the host had just launched it. That
made three situations indistinguishable: a game being watched, a game that quit and was never
noticed, and a game the host cannot see at all. `session_on_game_exit` can never fire for a lease
nothing is watching, which is why no setting helped.

- **`GameState::Untracked`** — surfaced in `/status`, the console card and the tray label. Keyed on
  "is anything watching this" rather than on the lease kind, so a nested gamescope lease (whose exit
  the capture loop catches) still correctly reads `running`.
- **`LeaseRequest::spawned`** carries the pid Windows already knew and discarded, pinned to its start
  time by a new `Scanner::resolve` so a recycled pid cannot impersonate it. Windows never holds a
  `Child`, so a title whose provider published no detect hint had *nothing* identifying it: its exit
  went unseen and `POST /game/end` had no pid to signal, while the same title on Linux was fully
  tracked through its child. The same fix closes a second defect — a launch that adopted nothing
  answered `Unknown`, fell back to the 90-second in-flight window, and past it started a **second**
  copy, which is why "click the game that is already running" resumed on Linux and relaunched on
  Windows.
- **`game_on_new_launch` (`keep`|`end`, default `keep`)** — close this client's previous game before
  starting a different one. Its own axis rather than a fourth `game_on_session_end` value: wanting a
  game to survive a disconnect says nothing about wanting it kept when you deliberately pick another.
  Four safety rules, made pure and unit-tested — never another client's game, never one the player
  started themselves, never the title being launched, and never a record whose liveness is merely
  `Unknown`. Scoped to launches this host performed itself (`crate::launchreg`).

### The virtual DualSense can arrive as a real USB device (opt-in)

A game that drives DualSense haptics pairs "my controller" with "my controller's speaker" by Windows
`ContainerId`, and wine derives that by walking the HID device through udev up to a `usb_device`
parent. Our pad is uhid, so its sysfs chain has no USB ancestor anywhere: winebus logs "Failed to get
parent device" and every endpoint registers as `GUID_NULL`. Measured against Spider-Man Remastered
under GE-Proton11-5, the game resolves both endpoints, reads their `FriendlyName` and
`PhysicalSpeakers`, and then declines to open either. The same missing fact blocks GE's other route:
its haptic path enumerates real **ALSA cards** (`snd_card_next` → `snd_ctl_pcm_next_device` →
`snd_pcm_open` demanding 48 kHz / S16 / 4 channels), and minted PipeWire nodes are not ALSA cards
however faithfully their proplist impersonates one — in the field log that scan never ran at all.

So `PUNKTFUNK_DUALSENSE_USBIP=1` presents the pad over `vhci_hcd`, reproducing the hardware's own
4-interface composite layout from an lsusb capture of a wired `054c:0ce6` — audio control, audio
streaming out (isochronous, S16LE 4ch 48 kHz: haptics + speaker), audio streaming in (the headset
mic), and HID. Because interfaces 0–2 are a genuine UAC 1.0 device, `snd-usb-audio` binds them and
mints a real ALSA card, and PipeWire's ALSA monitor builds the `HiFi__Speaker__sink` /
`HiFi__SpeakerHaptic__sink` nodes itself from the distro's DualSense UCM — the node graph stops being
impersonated. The transport rides the ladder `steam_controller` already established (usbip → uhid,
degrading on failure) and reuses the udev grant packaging already ships for the virtual Deck, so it
needs no new privilege, module or packaging. The descriptor set is pinned by test against the
hardware's published `wTotalLength` of `0x00E3`.

Pad-audio capture follows the pad: with the usbip pad the host mints nothing, so capture moves to the
**isochronous OUT endpoint** — the same point a physical pad's samples reach, which is what makes any
route a game takes land in one place. The `0xD1` wire path downstream is untouched; only the source
moves. The two capture modes are mutually exclusive by construction and the choice is read from the
transport flag rather than from whether a stream happens to have been published, or the race between
pad arrival and the streamer thread starting would decide it. `pad-usbip-test` is the on-glass gate
with no client and no game involved.

⚠ **Opt-in while it awaits on-glass verification** — it changes the pad's whole kernel presentation,
including superseding the minted pad-audio sinks with a real card. The uhid pad remains the
long-validated default.

### Recovery anchors are now corroborated

`USER_FLAG_RECOVERY_ANCHOR` is the host asserting a fact about the *client's* decoder — "the picture
I coded this P-frame against is one you still hold, intact" — and the gate took it on faith, on the
first occurrence. The host derives that claim from bookkeeping that tracks what the client
**received**, not what it managed to **decode**, and those diverge exactly when the client had to
conceal. `pf-bitstream`'s planners now carry a per-picture clean bit (damage propagates down the
prediction chain), surfaced as `PicturePlan::references_clean` and carried on `DecodedVkFrame`; the
gate gains `AnchorEvidence` and refuses an anchor whose references the client can prove were damaged.
Refusing can only ever hold **longer** — the freeze stays up and the backstop fires on its original
deadline. Lanes with no local parser pass `Unavailable` and are bit-for-bit unchanged; all 29
pre-existing reanchor tests pass untouched. On the host side, the slot-family RFI backends no longer
pick an anchor over damage the client has already reported.

⚠ **The H.264 decoder reached parity here, having been the only one of the three that failed OPEN**:
a DPB slot with no bound image was traced and decoded anyway, `reference_count` was computed after
the held-slot loop so a dropped reference silently took an unrelated slot's picture, and there was no
`RecoveryLatch`. Both latches landed with HEVC and AV1 in August; H.264 predates them and was never
retro-fitted.

### New management API surface

- `GET /api/v1/diagnostics` and `POST /api/v1/diagnostics/refresh` — **admin lane only**, because
  these verdicts carry the host user's name, its group layout and device-node state. `inapplicable`
  is a first-class status rather than an absent row, so the console can answer "why isn't this check
  relevant here?" instead of silently hiding it. Probes stay in their owning crates
  (`pf-vdisplay`, `pf-inject`) and export plain verdict enums; the host does the mapping, so there is
  no reverse dependency. A check id the console has never heard of still renders, from the host's
  English `summary`/`impact`/`remedy.text` — that is what makes console N paired with host N+1
  survivable, and it is enforced as a test.
- `POST /api/v1/client-logs` — **the cert lane's first and only WRITE.** Paired mTLS devices may
  upload (write-only: no read of anything, not even their own bundle), while list/fetch/delete stay
  on the loopback bearer lane; the lane matrix pins all four rows. The gate uses `effective()`, so an
  expired guest's upload is refused (403) while any live-authorized device — including a view-only
  guest — may send. No input grant is required: uploading one's own diagnostics is not an input
  capability. Storage is a bounded file store under `<config-dir>/client-logs` (traversal-proof ids,
  newest 5 bundles per device, 1 MiB cap) and deliberately **not** the log ring, which a
  multi-thousand-line bundle would evict.
- `PUT /api/v1/library/provider/{p}` now runs the console-password gate. It had no BFF handler and
  fell through to the `/api/**` catch-all, which injects the full admin bearer — so a bare session
  cookie could plant a persistent `prep`/`launch.kind:command` entry without the password.
- **Schema additions**: `GameOnNewLaunch` (`keep`|`end`) with the `game_on_new_launch` settings field,
  and `untracked` joins the game-state enum described on `/status`. ⚠ A client reading the state enum
  must tolerate `untracked` — the console and the Rust/Android clients treat it and `grace` as "up",
  and only a confirmed `exited` as not.
- ⚠ **`docs-site/public/openapi.json` had drifted from `api/openapi.json` and is re-synced here.**
  The mgmt drift test compares the *live route table* against the generated document, not the two
  on-disk copies, and nothing else gates the docs-site mirror — so the game-lifetime regeneration
  updated `api/openapi.json` alone and CI stayed green while the published API reference silently
  described the previous release. The two are byte-identical again as of this commit. **Regenerating
  one means copying it to the other**; there is no build step that does it for you.

### New environment variables

| Variable | Effect |
|---|---|
| `PUNKTFUNK_AUDIO_HIRES` | Forces the lossless plane on or off, overriding the stored `audio_format` setting in both directions |
| `PUNKTFUNK_CAPTURE_HDR_PTS=0` | Puts Linux capture back on delivery stamps instead of the compositor's own `spa_meta_header.pts` |
| `PUNKTFUNK_SESSION_LAYOUT=0` | Disables `sync_session_keyboard_layout()` — the leg that points an adopted gamescope session's Xwayland at the box's configured layout |
| `PUNKTFUNK_PAD_AUDIO_PROFILE=0` | Stops the Linux client moving a DualSense card to Pro Audio when no four-channel node exists |
| `PUNKTFUNK_PAD_SINK_SPLIT_NAME` | Overrides or drops the host sink's `api.alsa.split.name` (GE-Proton's haptic-leg target) |
| `PUNKTFUNK_PAD_SPEAKER_PATH` / `_VOLUME` | Field levers for the DualSense speaker-enable packet — hex or decimal. The path byte is empirical (SDL's vendored `SDL_hidapi_ps5.c` pins the struct layout but never writes these fields) but is now settled on glass at a ~300× margin |
| `PUNKTFUNK_DUALSENSE_USBIP=1` | Presents the virtual DualSense over `vhci_hcd` as a real USB device with its own ALSA card, instead of uhid. Opt-in; changes the pad's whole kernel presentation |

### Keyboard layout: the wire is US-positional, and nothing carried the host's layout

The key wire is US-positional **by design** — a client sends the physical key, `vk_to_evdev` turns it
into an evdev code, and the session's keymap picks the character. So the contract is "host layout ==
the layout on the client's keyboard", and nothing was upholding it. `localectl set-x11-keymap de`
writes a file only Xorg reads, libxkbcommon's fallback chain stops at `XKB_DEFAULT_*`, and no session
manager sets them — so a properly configured German box compiled `evdev/pc105/us`, silently.
`pf_host_config::layout` now resolves what the box actually recorded (`XKB_DEFAULT_*`, then
`xorg.conf.d`, then vconsole's `XKBLAYOUT` — **never** vconsole's `KEYMAP`, whose names are console
names that do not map onto xkb's). The wlroots injector compiles its uploaded keymap from that, all
four gamescope launch paths export `XKB_DEFAULT_*`, and `sync_session_keyboard_layout()` covers the
adopted-autologin case where no launch-time decision applies.

gamescope patch **0010** is the other half: gamescope builds a keymap from `XKB_DEFAULT_*` but puts
it only on `keyboard_group`, while the *seat* carries `virtual_keyboard_device` — a stub whose own
comment says it exists "only to set the keymap" and which never gets one. `wlserver_keyboardfocus()`
rebinds that stub on every focus change, and the real group only reaches the seat from a libinput key
event, which a `--backend headless` session never has.

### Controller audio on Linux: what a real DualSense actually presents

We minted a single `AUX0..AUX3` node wearing the mono sink's `Speaker__sink` name. A game that
renders DS5 haptics writes a **positioned** FL/FR/RL/RR quad — the only public 4-channel surface a
physically connected pad publishes — so that write was position-remixed on arrival and the coil pair
folded away, measured at `peak_speaker=0.2441` with `peak_coils=0.0000`. Nothing errored, nothing
logged. The host now mints the three-node split a real pad presents (a 4-channel `AUX` parent, a
positioned `HiFi__SpeakerHaptic__sink`, a mono `HiFi__Speaker__sink`), all summed onto one hardware
quad. The profile suffix is `-00.HiFi__Speaker__sink`, because GE-Proton's
`is_dualsense_speaker_sink()` is a substring test for `Speaker__sink` and three separate behaviours
hang off it; `api.alsa.split.name` is published, without which `get_dualsense_haptic_target()`
returns NULL and the leg cannot engage at all. `device.vendor.id`/`device.product.id` gained the
`0x` prefix the specimen publishes — `strtoul(s,_,0)` reads a bare `054c` as octal, stops at the `c`
and yields 44.

The client half matched a sink by name signature alone and had the same folding problem. Correlation
now walks nodes **and** devices, requires `device.id` (which is also what keeps a Punktfunk host's own
minted pad sink out, since it carries the full DualSense identity on purpose), prefers unpositioned
AUX quads, and falls back to moving the card to Pro Audio for the session. The stream sets
`stream.dont-remix` with `AUX0..AUX3`, so channel *k* reaches channel *k* whatever the node
advertises. `punktfunk-session --pad-audio-test` prints every DualSense object in the graph, the node
it chose, and drives a tone into the coils — separating "the plane never arrived" from "it arrived
and the graph folded it away" with no host, no game and no pairing.

⚠ **Channel 1 of the DualSense's audio function is the headphone jack's right channel *and* the
built-in mono speaker**, and which one physically sounds is chosen by `ucAudioEnableBits` (report
byte 8). A pad powers up pointing at the jack, so with nothing plugged in the speaker pair went
nowhere — which is why haptics worked the instant routing was right and the speaker did not. A tier-A
slot with the speaker capability now sends a default speaker-enable packet; a game's own `AudioCtl`
still overrides it verbatim.

**The path byte is now settled, and was not when it first landed.** `0x20` was originally chosen from
a sweep that cleared the pad-mic noise floor by only ~5×, and was recorded as unsettled. A second
sweep on glass (DS5 wired to a Steam Deck client, 330 Hz into the speaker pair) swept the whole byte
at a **~300×** margin: `0x20` and `0x30` sound, `0x10`/`0x40`/`0x50` do not — so **bit 5 is the
speaker-path enable and bit 4 alone does nothing**. `0x20` stays the default over the marginally
louder `0x30`, which asserts a second path bit whose effect on the headphone leg was never measured.
Two properties the one-shot depends on were measured the same day: the setting persists (unchanged
40 s after a single write) and survives the pad's USB audio stream stopping and restarting, so it
needs no re-assertion when the renderer opens its output. Verified end to end — forcing the pad to
`0x00` dropped the pad mic to the `0.000000` floor and silenced the speaker; a fresh slot open
restored it.

### Bazzite: our virtual DualSense triggers an SELinux audit storm

The virtual DualSense/DualShock 4 binds `hid-playstation`, and Valve's `ds_inhibit`
(steamos-manager) reacts to every open/close of any such hidraw by walking `/proc/*/fd` — with no
VID/PID or virtual filtering. SELinux denies `steamos_manager_t` that walk at ~324 AVCs/sec, and
`setroubleshootd` amplifies it into a box-wide fork storm (267+ procs/sec, a core burned, RSS
climbing for 15+ minutes *after* the denials stop) that starves the stream to 0 fps and session
death. Punktfunk is the trigger, not the defect — but we ship the trigger.
`packaging/bazzite/punktfunk-ds-inhibit.cil` is a **dontaudit** drop-in, not an `allow`: granting
another vendor's daemon `sys_ptrace`/`dac_*` is not ours to do, and the scan failing quietly leaves
the pad uninhibited, which is what we want anyway. The RPM ships the source under
`/usr/share/punktfunk/selinux/` (the policy *store* is host state, so a sysext image can only carry
source) and it is inserted idempotently by `punktfunk-sysext post_merge`/`reapply` and best-effort by
the RPM `%post`, both keyed on the steamos-manager binary and the module name. ⚠ **Rename the `.cil`
if its rules ever change, or existing installs never converge.** `warn_if_ds_inhibit_storm` puts the
cause in *our* logs, because the AVC lines read `comm="tokio-rt-worker"` and look like us.

### udev: the virtual Steam Controller 2's hidraw node was root-only

`60-punktfunk.rules` grants hidraw access per product id and never listed the SC2 identities the host
mints — wired `28DE:1302` and Puck `28DE:1304`. For any other pad that would be a degradation; for
this one it is total, because no kernel driver claims the PID (mainline `hid-steam` stops at the
Deck) and the state reports ride a vendor collection, so there is no evdev node either. Steam is the
only consumer there is. Both identities are added in the same two forms the Deck uses (`KERNELS` for
the UHID shape, `ATTRS` for the usbip/gadget one). Single source of truth: every distro installs this
file, and the NixOS module takes it from the package.

### Other embedder-visible notes

- **Android**: `NativeBridge` and the audio path gained the format vocabulary; every Opus session was
  previously advertising the lossless capability, and the ABI doc told it to. The CI test filter is
  an allowlist and eleven classes sat outside it, including the audio HUD ones — all eleven pass,
  but nothing was gating them. They are listed explicitly now.
- **`pf-client-core` still filters a surround request out before it reaches the wire**, so the
  console's audio-format row stays gated under 5.1 even though the host's `channels != 2` decline is
  gone and the arithmetic supports surround at 48 kHz.
- **Reassembly memory is metered per block.** The reassembler's firewall counted only `FrameBuf::buf`
  bytes; `BlockState` (have-data + recovery vectors, both sized from attacker-declared header fields)
  was unmetered, so a slice-streamed frame could mint thousands of distinct-index blocks and commit
  multiple GB against a ~13 MB accounted figure. `block_state_bytes()`/`frame_cost()` now gate each
  new block on the same `IN_FLIGHT_BUF_FACTOR × max_frame_bytes` budget.
- **PyroWave**: a duplicate `block_index` with `payload_words == 0` spun the client decode thread at
  100 % CPU forever, inside FFI with no allocation and no timeout. The minimum-size check is hoisted
  into `push_packet` before `decode_packet` is consulted. Carried as vendored patch 0008.
- **Apple**: `HTTPResponse` overflowed `bodyStart + length` on a malicious `Content-Length`, and Swift
  integer overflow **traps** rather than throwing. `art_path_is_confined`'s UNC guard was a leading
  double-*backslash* string test, so `//server/share` and mixed forms slipped past and
  `canonicalize()` would coerce the SYSTEM host into outbound SMB auth.
- **CI**: `ci.yml`'s cargo-home cache shared an unnamespaced key with the signed release builds, so a
  fork PR could poison a release artifact through `registry/src`. The key is namespaced to
  `cargo-home-ci-`. The pinned `bun-windows-x64.zip` is now sha256-verified before it is staged and
  Authenticode-signed. ⚠ The Linux `curl|bash` sites (arch/rpm/deb + builder Dockerfiles) still need
  version+hash pinning.
- **`@punktfunk/plugin-kit` 0.4.2**: `library_capsule.jpg` is the newer name for the 2:3 cover and
  `header.jpg` the newer name for the header — measured against a real 779-app `librarycache`, 46
  appids carry only the former and 594 carry the latter, with **no appid carrying both spellings of
  either**. The `<appid>/<name>` layout with no hash directory is the **majority** (623 of 779), and
  `findLocalArtFile` walked only `<appid>/<hash>/<name>` and the oldest `<appid>_<name>`. Per-appid
  art found locally went portrait 25 → 328, hero 75 → 323, header 86 → 716, logo 66 → 295. ⚠ Each
  plugin vendors its own nested copy of the kit, so a plugin only picks this up when it is
  republished.

### Console UI: nothing was anti-aliased, and cover art sampled nearest

Reported from a Steam Deck, where a 1280×800 panel gives sub-pixel error nowhere to hide. Two
independent causes, both API defaults. **`SkPaint`'s default constructor sets `fAntiAlias = false`**,
and skia-safe's `Paint::new(colour, None)` is that constructor with a colour on it — so the terse,
natural spelling of a draw call silently produces hard-stepped edges. The crate had 70 paint sites
and 15 were anti-aliased, in an exact pattern: paints that got *mutated* for some other reason picked
up a `set_anti_alias(true)` on the way past, and every inline argument did not. The console drew
smooth 1 px rings on top of jagged fills, which looks worse than no ring — the smooth edge gives the
eye a reference for how wrong the fill is. Text was never affected, since glyph anti-aliasing is
`SkFont::Edging` and defaults on. Separately, **`Canvas::draw_image_rect` samples with
`SamplingOptions::default()`, which is `FilterMode::Nearest` with no mipmaps** — every 600×900 poster
minified into a ~180×270 Deck cell simply discarded rows and columns.

`theme::fill`, `stroke`, `shaded`, `shaded_stroke` and `layer` are now the only sanctioned paint
constructors and all 70 sites go through them; `theme::art_sampling` (linear + linear mipmaps) covers
the three image draws. ⚠ **`shaded` earns its place the hard way: Skia modulates a shader's output by
the PAINT's alpha**, so building a gradient paint from a transparent placeholder draws *nothing* —
not dimmer, absent. `Paint::default()` happened to be opaque black, which is the only reason the
console's gradients and the SkSL aurora never met the rule; building them transparently erased the
backdrop, badge, vignette and skeleton sheen at once, **and all 124 tests still passed**, because a
test that only renders a frame cannot tell a missing layer from a dark one. `shaded` is opaque by
construction so the trap cannot be set again. Three tests pin it, each verified to fail with the fix
backed out — including one that scans the crate's own source, because the aliased spelling is the
natural one and will be written again by whoever adds the next draw call.

### Other client and console notes

- **Client log bundles merge into the host log viewer** rather than sitting in a table beneath it.
  The Logs page had two axes fighting: `All | Host | Plugins` was a filter over one stream, while
  uploaded bundles were a different artifact kind stacked underneath. The format itself resolved it —
  the session ring layer writes `<ISO8601-Z> <LEVEL> <target> <msg>`, the same four fields as a host
  `LogEntry` and wall-clock stamped precisely so a bundle correlates with the host log. The source
  control is now multi-select chips over one merged pane with devices as peers of Host and Plugins,
  so "the client stalled at 12:03:47, what was the host doing?" is expressible for the first time.
  Bundles were previously undiscoverable twice over (the card returned null when empty, and when
  non-empty sat below a 65vh viewer) and could not be **read** in the console at all, only downloaded.
- **The library round-trip reached Android and the Gaming Mode console** — catalog cached per host
  and rendered immediately marked stale (keyed on the pinned fingerprint, so a new DHCP lease is
  still the same host), the host woken on library **entry** with the fetch retried across the boot
  window rather than at CONNECT which is too late to help, titles already up badged Resume and
  sorted first from `/status`, running-first ordering **within** each group only (`GridShape` lays
  launcher entries out as a prefix, so a running game jumping the fence would put the cursor
  arithmetic and the renderer on two different fields), and the grid returning to the last title
  *opened* rather than a pixel offset. Forgetting a host now drops its cached catalog. ⚠ **Item 1 of
  that set was reverted at review**: a host card's primary press stays "connect" on both carousels,
  because Y already opened the library there with a legend hint — the flip spent entrenched muscle
  memory on an affordance that already existed one press away.
- **A masked-color I-beam was forwarded as a fully transparent pointer** on Windows capture: `AND=1`
  plus a non-zero colour pixel is *invert*, not transparent, so treating it as a simple alpha mask
  dropped the text cursor and the client installed nothing over every text field.
- **The Apple client's settings captions went from 2 097 words to 973.** The rule applied throughout:
  one clause of what the setting does, one of what it costs. Numbers survive; rationale moves to the
  code comment above each caption. ⚠ The lossless gate riders are gone from all five rows and said
  **once** in the Audio section footer — that footer sentence is now the only thing keeping
  `audioFormatCaption` honest about the design's rule that the picker must never read as a promise of
  the *resolved* format, and its doc comment says so. `bitrateFooter` lost its speed-test sentence
  entirely rather than being shortened: that string is tvOS-only and directed Apple TV users to a
  context menu, and tvOS has no context menus.
- **An encode worker that died before the `Hello` landed reported `EPIPE`** instead of naming the
  handshake, and `pf-win-display`'s EDID unlock logged its expected no-op as a warning.
- **Flatpak CI: 21 minutes → 9.** The job reinstalled its whole toolchain every run (now a baked
  builder image), pulled 3.84 GB to publish 28 MB, and — the real defect — its "offline" build step
  **re-fetched every git source**, so one upstream 503 killed the build.

### Verification status

Gates green on the release tree: `cargo fmt --all --check`, `cargo metadata --locked`,
`cargo test -p punktfunk-core` including the C ABI harness, the whatsnew character and uniqueness
gates, and the release-notes voice scan.

⚠ **Not verified on hardware by this cut**, and named rather than left to be discovered: the 96 kHz
lossless path on Apple and Android devices (§13.2's on-glass tone check passed host → Mac at
96 kHz/24-bit, but the mobile legs gate on hardware); the on-glass guest rehearsal for per-client
access and a real-Moonlight run; a BLE-paired Steam Controller 2 on Android; and the diagnostics page
against the real `.181` box in all three vhci states.

⚠ **Verified by reading only** — these compile nowhere available to the cutting host, so a CI runner
is their first compiler: the WinUI half of the library-toggle removal (`punktfunk-client-windows` is
`cfg(windows)`), and the Apple library-browse pin gate.

⚠ **`PUNKTFUNK_DUALSENSE_USBIP` is opt-in precisely because it is unverified on glass.** It changes
the pad's whole kernel presentation and supersedes the minted pad-audio sinks with a real ALSA card;
`pad-usbip-test` exists to be the gate that closes this, and it has not been run against real
hardware. The uhid pad remains the default and is unaffected.

---

## v0.29.0

53 commits since v0.28.1 (36 non-merge).

The headline contract change is one **additive** C ABI bump: the host now tells the client, in-band,
where its management API lives, and the connection grew an accessor for it. The wire protocol, the
driver protocol and the plugin contract do not move; every 0.28.x host, client, driver and plugin
keeps interoperating with 0.29.0 in both directions, with no re-pairing. The one thing that needs an
operator's hand is on Windows: the MSIX package identity changed with the move to a publicly
trusted signing certificate, so that install path needs a one-time uninstall + reinstall.

### Versions

| | v0.28.1 | v0.29.0 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged — `Welcome` grew a trailing field older peers never read (below) |
| C ABI | 19 | **20** | one symbol added: `punktfunk_connection_mgmt_port` (below) |
| Rust edition | 2024 | **2024** | unchanged |
| MSRV (`rust-version`) | 1.85 | **1.85** | unchanged |
| Workspace crate dirs | 27 | **27** | unchanged |
| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3); `pf-driver-proto` shows no diff against the v0.28.1 tag |
| Windows virtual-gamepad channel | 3 | **3** | unchanged |
| Plugin index schema | 1 | **1** | unchanged |
| `api/openapi.json` | 0.28.0 | **0.28.0** | the management API surface did not change; the file keeps the stamp it was regenerated under |
| gamescope patch level (`+pfhdrN`) | 7 | **7** | unchanged — the patch series is untouched |
| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.4** | unchanged |
| `@punktfunk/plugin-kit` | 0.4.1 | **0.4.1** | unchanged |

### ⚠ Breaking changes

- **C ABI 19 → 20, addition only.** `include/punktfunk_core.h` gains exactly one declaration,
  `punktfunk_connection_mgmt_port(const PunktfunkConnection *, uint16_t *)` — the management-API
  port the host advertised in its `Welcome`, or the documented default when it advertised none.
  Nothing is removed or reshaped; an embedder that compares `PUNKTFUNK_ABI_VERSION` at build time
  rebuilds against the new header and is done. Nothing in-tree compares it at runtime.
- **The Windows MSIX package identity changed.** Releases are now signed by Azure Artifact Signing
  (below), and the MSIX manifest `Publisher` must equal the signer subject byte-for-byte — so it
  moved from the self-signed `CN=unom` to the verified subject. Package identity is Name +
  Publisher: Windows treats the new package as a different app, and an in-place upgrade is
  impossible by design. One-time uninstall + reinstall for MSIX installs; the `.exe` installer and
  winget-via-installer paths upgrade normally.
- **Android embedder edge, additive:** `NativeBridge` gains `nativeHostMgmtPort`, and the native
  discovery record gains its 9th field, `mgmt` (the record's append-only rule; 0, non-numeric and
  out-of-range all parse as unknown). Out-of-tree JNI callers are unaffected unless they want the
  value.

### The management port is movable, survives, and is learned in-band

47990 is the management API's port and also the web-UI port of Sunshine and its forks — with the
GameStream planes off, the only port the two still contend for. Moving it now actually works, end
to end:

- **`PUNKTFUNK_MGMT_BIND` joins `host.env`** (the `PUNKTFUNK_GAMESTREAM` shape: env or CLI flag,
  the flag wins), so the choice survives package upgrades that rewrite the unit file. `serve`
  publishes the port it *actually bound* to `~/.config/punktfunk/mgmt-endpoint` (KEY=VALUE, written
  write-then-rename), and the console, the Windows service and the unit files all derive from that
  one file; the six hardcoded 47990 literals survive only as the old-host fallback.
- **`Welcome.mgmt_port`** — a trailing `u16` after the cipher block, the same additive discipline
  as the eight fields before it, so `WIRE_VERSION` stays 2 and an older peer stops earlier and uses
  the default. ⚠ One encode subtlety, pinned by test: `cipher` used to be emitted only when
  non-default, and appending the port to an AES `Welcome` would land its low byte at offset 68 —
  exactly where every shipped 0.28.x client reads `cipher`, fail-closed. `encode` therefore writes
  an explicit cipher byte whenever a port rides along; a host advertising no port still emits
  exactly 68 bytes. The standalone `punktfunk1-host` binary advertises `0` (it has no management
  API).
- **Clients persist it**: `KnownHost.mgmt_port` + `effective_mgmt_port()` across the Rust clients
  (three-rung: live advert → stored → default), the session console, Android (through
  `DiscoveredHost`), and Apple — where `StoredHost.mgmtPort` had existed all along but nothing ever
  wrote it, so every Apple client resolved 47990 regardless. A host that has never been seen over
  mDNS (VPN, routed subnet, multicast-dead network) now learns the port from the authenticated
  connection itself.
- **`PUNKTFUNK_NATIVE_PORT`** completes the pair for the data plane — `--native-port` was CLI-only
  and died on upgrade. A bad value is a startup **error**, not a silent fall back to 9777.
- The Windows shell's half of the client-side learn landed separately (#241): `trust.rs` re-exports
  `learn_mgmt_port`, the shell's own mDNS browser parses the `mgmt` TXT, and `HostTarget` carries
  the port like the mac client's target does.

### Linux thread priority: the renice was a no-op on every install to date

`boost_thread_priority`'s `setpriority()` needs `CAP_SYS_NICE` or a raised `RLIMIT_NICE`; no
channel granted either, and the host binary can never carry a file capability (a capped process's
`/proc/<pid>/exe` is unreadable to KWin — the 0.26.0-1 incident). So capture/encode/send ran at
nice 0, and a shader-compile storm could deschedule them hard enough to stutter audio and drag ABR
to its floor at zero loss. Now:

- **RealtimeKit fallback** — `MakeThreadHighPriorityWithPID`, the same unprivileged broker
  PipeWire clients use. Only the nice verb, never `MakeThreadRealtime`; nothing enters the
  permitted set, KWin identification is untouched.
- **The audio plane is boosted at all, for the first time**: the 5 ms Opus
  capture→encode→send loop, the PipeWire capture mainloop, and the pad-audio streamer (on Windows
  too, via the existing `SetThreadPriority` arm).
- **Packaging ships headroom for rtkit-less boxes**: `packaging/linux/50-punktfunk-nice.conf`
  (`user@.service.d`, `LimitNICE=-15` — a limit, not a grant; effective from next login) on rpm,
  Arch and deb, written to `/etc/systemd/system/user@.service.d` by the Steam Deck installer; deb
  and rpm gain a weak `Recommends: rtkit`, Arch an optdepends hint, and the NixOS module sets
  `security.rtkit.enable = mkDefault true`.

### Host capture gain works on `punktfunk/1`, and boosting no longer hard-clips

`PUNKTFUNK_AUDIO_GAIN` existed only on the GameStream plane, and where it applied it was a hard
`clamp(-1.0, 1.0)` — flat-topping, so pushing past ~1.5× sounded broken long before it got loud
(WASAPI loopback taps upstream of the endpoint's master volume, so the host's own slider never
changes the sent level either). `punktfunk_core::audio::apply_gain` now serves **both planes** with
a tanh soft knee above `SOFT_LIMIT_KNEE` (0.7, ≈−3.1 dBFS): C1-continuous, bounded by
construction, odd-symmetric, memoryless (zero added latency). Unity is a no-op inside the function
itself, so the default wire stays byte-for-byte identical. `capture_gain` rejects non-positive
values and caps at 8.0 (+18 dB). This buys headroom, not loudness — it is deliberately not a
compressor, and the docs say so. `SOFT_LIMIT_KNEE` is excluded from cbindgen on purpose.

### Windows binaries are signed by Azure Artifact Signing

Account `unomsigning`, profile `unom-io`, signed by a service principal holding only the
profile-scoped signer role. Azure mints a **per-request leaf that expires in ~3 days**, which
changes two rules: a timestamped countersignature is now *mandatory* (the old retry-without-
timestamp fallback is a hard failure in Azure mode — it would ship an artifact that goes untrusted
days later, everywhere at once), and leaf pinning is structurally impossible (the updater's
`AUTHENTICODE_SHA256` note claiming otherwise is corrected). `pack-msix.ps1` reads the signature
back off the packed `.msix` and fails on Publisher drift. Driver catalogs are deliberately
untouched: they keep the `DRIVER_CERT_*` cert and the installer still plants it as a machine root
(PnP trust is independent of SmartScreen/UAC trust). Canary and fork builds keep the `.pfx` and
ephemeral fallbacks.

### Library: a launcher the host cannot open no longer costs the whole sync

`valid_launcher_ui` conflated vocabulary with environment. It is now split: `known_launcher_ui`
(an unknown launcher kind is a plugin bug — still a hard 400) and `resolvable_launcher_ui` (the
launcher just is not installed on this box — the entry is dropped with one warn and the games
sync). Same shape as the unservable-cover fix, on the launch side. And Playnite is actually
findable now: the old lookup read the LocalSystem service's own HKCU and `%LOCALAPPDATA%` (the
SYSTEM profile — a per-user Playnite is invisible there) and matched a registry key name Inno Setup
never writes. Now: every loaded hive under `HKEY_USERS` plus both HKLM views, matched on
`DisplayName`, then `C:\Users\*\AppData\Local\Playnite`.

### Hyprland/sway capture: six defects, all ours, and streaming now survives past one session

The wlr portal route looked environmental and never was. Measured on Hyprland 0.55.4 +
xdg-desktop-portal-hyprland 1.3.12, fixed in one arc (#240):

- **The dmabuf pod offered `BGRx`; xdph offers `BGRA`.** The modifier lists intersect perfectly,
  the fourcc never does, so PipeWire failed the link itself (`no more input formats`) — and the
  pods live only in the PipeWire *daemon's* log, which is why it read as a GPU/modifier problem.
- **A per-cast tokio runtime orphaned ashpd's process-global D-Bus connection.** ashpd caches its
  connection in a `OnceLock`; the first cast's runtime hosted zbus's reader task and then died
  with the cast, so the first stream of a host process worked and every later one went black.
  Both wlr backends now share one long-lived portal runtime.
- **Teardown removed the captured output before closing the cast**, and xdph spun on the wreckage;
  the order is now cast-then-output.
- **A hung portal handshake leaked its thread** and the leak poisoned every later cast; the
  handshake is now bounded.
- **The wlr absolute-motion injector aimed at the operator's head**, never the streamed one; the
  pointer is now bound to the streamed output.
- **The cursor park schedule read a missing cursor overlay as a lost pointer** — an Embedded-mode
  portal never sends one.

### Everything else an integrator might notice

- **vdisplay/KDE:** a bare-spawn gamescope session under an exclusive topology now darkens the
  physical panels over `org_kde_kwin_dpms` (new in-process `kwin_dpms` module,
  `kscreen-doctor --dpms` fallback), refcounted host-wide so concurrent spawns compose; DPMS is
  non-persistent, so a dead host leaves nothing to journal. Managed and Attach routes untouched.
- **macOS client:** `Settings::inhibit_shortcuts` is finally implemented on Apple — a local
  keyDown monitor claims every ⌘ chord while input is captured and forwards it host-side (AppKit
  dispatches menu key equivalents before the stream view sees them, so ⌘Q used to quit the
  client). ⌘⎋ and ⌃⌘F stay client-side; ⌘Tab/⌘Space/Mission Control are out of reach without a
  CGEventTap. Chord matching no longer compares Caps Lock and `.function`/`.numericPad` bits raw.
- **Android client:** `Gamepad.padButtonBit` resolves a gamepad-sourced `KEYCODE_BACK` to
  `BTN_BACK` — pads that report Select as plain BACK (the Android-TV shape) no longer quit the
  stream on one press, and the Select chords (exit chord, mic mute, stats tier) become reachable
  on exactly those pads. `FLAG_FALLBACK` events stay excluded.
- **CI:** Android canaries now feed Play **open testing (beta) and closed testing (alpha)** from
  one Play edit (`play-upload.py --also-track`); tags still publish production only, and a manual
  `android.yml` dispatch can now opt into publishing (`publish=true`), so a lost merge run is no
  longer a dead end. Windows
  runners provision the .NET 8 runtime and a machine-wide signing client (a mixed-mode dlib with
  no runtime makes signtool exit 3 in silence).



60 commits since v0.28.0.

A patch release in the strict sense: **nothing on the wire, in the C ABI, in the driver protocol or
in the plugin contract moves.** Every host, client, driver and plugin built against v0.28.0 keeps
working against v0.28.1 and vice versa, in both directions and with no re-pairing.

### Versions

| | v0.28.0 | v0.28.1 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged |
| C ABI | 19 | **19** | unchanged — `include/punktfunk_core.h` is byte-identical to the v0.28.0 tag |
| Rust edition | 2024 | **2024** | unchanged |
| MSRV (`rust-version`) | 1.85 | **1.85** | unchanged |
| Workspace crate dirs | 27 | **27** | unchanged |
| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3) |
| Windows virtual-gamepad channel | 3 | **3** | unchanged |
| Plugin index schema | 1 | **1** | unchanged |
| `api/openapi.json` | 0.27.0 | **0.28.0** | the management API **did** change (two collection deletes, below); the file carries the stamp it was regenerated under, not `0.28.1` |
| gamescope patch level (`+pfhdrN`) | 6 | **7** | 8 patches → 9 (the linger crash); no new capability |
| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.4** | unchanged |
| `@punktfunk/plugin-kit` | 0.4.1 | **0.4.1** | unchanged |

⚠ **The `api/openapi.json` stamp is not a per-release counter** and should not be read as one. The
drift test (`openapi_document_is_complete_and_checked_in`) normalizes `info.version` on both sides,
so only the *surface* is gated and a version bump alone never invalidates the snapshot. The table
row says what the file actually says. Regenerating it needs a Linux or Windows host build —
`punktfunk-host` does not compile on macOS.

### ⚠ Breaking changes

**None.** No wire change, no C ABI change, no driver-protocol change, no plugin-contract change.
Three things are worth an embedder's or packager's attention anyway, none of which break a build:

- **The Rust crate gained one public constant.** `punktfunk_core::client::FLUSH_COOLDOWN` was
  `pub(crate)`; the host now compares against it rather than against a copy of the number (see the
  keyframe-cadence fix below). Addition only.
- **`NativeBridge.nativeStartAudio` takes a third argument** on Android — `isTv`. Detail in the
  Android section; this is a JNI signature change, so an out-of-tree caller must pass it.
- **Every Linux packaging channel now ships a second gamescope artifact**, the Vulkan WSI layer,
  and a package that carries the compositor without it is *fatal* rather than degraded. If you
  repackage `punktfunk-gamescope` downstream, read the gamescope section before rebuilding.

### The management API gains two collection deletes — "unpair all"

Clearing a host's trust store meant one row-level delete per device, each with its own
confirmation. Two new endpoints, one per pairing plane:

```
DELETE /api/v1/clients          -> {"unpaired": N}
DELETE /api/v1/native/clients   -> {"unpaired": N}
```

They are **not** a loop over the per-fingerprint deletes. Each empties its store in ONE persisted
write, because N deletes would rewrite and atomically rename the store N times and a failure
partway leaves a half-emptied store with nothing saying which half. The two planes are separate
endpoints because they own separate trust stores with separate persistence and separate revocation
duties.

Being collection deletes, they carry the single delete's revocation guarantees across the whole
set: a live session owned by any removed certificate is ended, and on the GameStream side the ENet
control port (UDP 47999) closes, because no pairing is left to hold it open.

**200 with a count, not the single delete's 204/404.** "Unpair everything" is idempotent — an
already-empty store satisfies it — and the count still distinguishes three devices from none.

⚠ **Both are admin-token only.** The route-classification gates match on (method, path), so the
roster's plugin-readable `GET` does not carry over to emptying it; both new routes have explicit
rows in the table, like every other pairing-administration route. The native endpoint answers
**503** on a host built without that plane, which is why the console calls only the planes that
actually have a row.

`UnpairAllResult` is the one new schema. `api/openapi.json` is regenerated;
`docs-site/public/openapi.json` is re-synced from it (see **Documentation** at the end).

### The pad-audio "Wireless Controller" speaker hides while no client pad is attached

Field-confirmed (2026-08-14, the same Helldivers 2 reports as below): the per-pad audio endpoint
the Windows host mints — a Steam-Streaming-Speakers instance stamped with a DualSense's name,
container and 4 ch/48 kHz formats, **pre-provisioned at every host start** — is deliberately
indistinguishable from a real DualSense speaker. That disguise is the feature during a pad
session (libScePad titles route haptics audio at it) and a trap the rest of the time: an idle
Helldivers 2 finds the endpoint by identity, engages its DualSense-haptics path against a device
nothing services, and drops to 2–5 FPS 1% lows — with the host completely idle, no controller
plugged in, and no session ever run. The reporter isolating "the DualSense speaker" and disabling
it in mmsys.cpl restored full performance; that manual remedy is now automatic.

The endpoint now parks **hidden** (`DEVICE_STATE_DISABLED`, via `IPolicyConfig::
SetEndpointVisibility` — the exact call behind mmsys.cpl's Disable) whenever no client pad is
attached: provisioning hides it at startup (and a `PUNKTFUNK_PAD_AUDIO=0` host hides leftovers
from earlier runs), the per-pad streamer shows it for exactly the pad's lifetime — to a game,
indistinguishable from a DualSense arriving and leaving. The devnode, driver binding and stamps
stay put, so the flips raise no PnP traffic and the expensive provisioning still happens once at
boot.

⚠ **Operator-visible:** "Speakers (Wireless Controller)" now shows as *disabled* in the Sound
control panel while no client pad is connected — that is the parked state, not a defect. The
`pad-endpoint` devtest grew `show`/`hide` verbs; `tone`/`capture` need a `show` first.

### An idle Windows host no longer owns the box's default microphone

Field report (the second Helldivers 2 one — the first led to v0.28.0's mint-retry fix): with the
host **idle**, a locally played Helldivers 2 tanks to 2–5 FPS 1% lows, and Windows' own Sound
settings Recording tab goes unresponsive. Root cause: the audio wiring pass asserted *default
recording = the virtual mic's capture side* on **every** pass, including the mic pump's eager
boot pass — and `SetDefaultEndpoint` covers eCommunications, so every game's voice input bound a
virtual microphone whose feeder only runs during a stream. Nothing ever restored it: not session
end, not service stop. Games that hold an always-open voice capture (Helldivers 2 is Wwise +
in-game voice — its own wiki calls the game "finicky with audio devices") stall on that dead
endpoint.

The recording default is now **session-scoped**, exactly like the playback default has always
been: parked on the virtual mic only while a desktop-audio capture is open, the operator's device
remembered (plus an on-disk crash marker, `audio-default-rec.prev`), restored when the capture
closes, recovered at next boot after a crash, and unparked by the uninstaller. A game launched
*during* a stream still records the client's mic; one launched before the stream keeps the
operator's own microphone.

Boxes wedged by earlier builds (which recorded nothing to restore) heal themselves: an idle
wiring pass that finds the default recording sitting on the plan's mic capture moves it back to
the first real microphone.

⚠ **Operator-visible:** outside a stream, the default recording device is now whatever you set —
Punktfunk only takes it for the duration of a stream. If you *want* apps to record the client mic
while idle, select "Punktfunk Microphone" manually; the host no longer re-asserts it (idle
re-assertion used to stomp a manual choice within one mic-pump reopen).

### The NixOS module started a second host in root's systemd, which stole the ports from the real one

Found on the first real deployment of `packaging/nix/nixos-module.nix` (NixOS 26.05, punktfunk
0.28.0-nix). The host crash-looped forever on one line:

```
ERROR punktfunk_host: start RTSP server: bind RTSP 48010: Address already in use (os error 98)
```

`systemd.user.*` has no per-user form in NixOS: it installs units into **every** user's systemd
manager. `host.autoStart` then adds them to `default.target` — for every user, including **root**,
whose `user@0.service` springs into existence the moment anybody so much as SSHes in as root. Root's
copy of the host won the race for the fixed ports, and the desktop user's copy could never bind.

The failure is nastier than it sounds because every *other* listener binds first and logs success —
the version banner, mDNS on 47989, the GameStream warning all print normally — so the log reads like
a conflict with some unrelated program. A second copy of *itself*, running as root, is the last
thing anyone looks for. `host.users` did not help: that option only granted `input`/`punktfunk`
group membership and never scoped the units.

Fixed by rendering `ConditionUser=` on all four user units (`punktfunk-host`, `punktfunk-web`,
`punktfunk-web-init`, `punktfunk-scripting`) from `host.users`. Each entry is written `|user` — the
pipe makes it a *triggering* condition, which systemd ORs; plain repeated `ConditionUser=` lines are
ANDed and would have matched nobody. With `host.users` empty the units fall back to
`ConditionUser=!@system`, which still keeps root out while leaving a normal login free to run the
host by hand, as the module header documents.

`packaging/nix/module-check.nix` gained three assertions covering both branches and the fact that
`punktfunk-web-init` keeps its pre-existing (non-triggering) `ConditionPathExists` alongside the new
condition. They run in the `eval` leg of `nix.yml`, and were verified to fail against the unfixed
module before being committed.

### The Steam plugin synced nothing on Windows: its art is in Program Files, the art roots were not

Field report — the plugin installed, the grid stayed empty, and the only clue was one host warn per
sync:

```
plugin:steam sync (fs-change) failed: HostRequestError: PUT /library/provider/steam?store=steam
  failed: art.hero: local art must be an image file (…) inside an allowed art root
```

Two independent defects, both fixed here.

**1. Steam's art was never inside an allowed root on Windows.** `art_roots()` defaulted to the users
base (`C:\Users`, from `%PUBLIC%`'s parent), which covers the launchers that install per-user —
Playnite under `%APPDATA%`, Heroic under `%APPDATA%` — but *not* Steam, which installs to
`C:\Program Files (x86)\Steam` and keeps both the art the plugin publishes there:
`appcache\librarycache\<appid>\<hash>\` and each account's `userdata\<id>\config\grid\` overrides.
Every cover the plugin emitted was out of root. This is a v0.28.0 regression: the built-in scanner
the plugin replaced served its covers through the legacy `steam:` art-proxy branch, which never
passed through the H-2 confinement — deleting the scanner routed that art through a gate it had
never been measured against. `art_roots()` now also includes every Steam install root it can find,
from `%ProgramFiles(x86)%` / `%ProgramFiles%` / `%ProgramW6432%` and from HKLM
`Valve\Steam\InstallPath` (so a Steam on another drive is covered too). POSIX needed no equivalent —
every Steam layout there, native and Flatpak, is already under `$HOME`.

This does not weaken the confinement. It exists to stop the host (SYSTEM) reading files the plugin
lane (LocalService) cannot reach itself; the Steam directory is readable by LocalService already, so
nothing there is reachable *because* the host is privileged. The extension, regular-file, magic-byte
and config-dir gates all still apply, so Steam's own `config.vdf` and `ssfn*` credential blobs are
not servable from it — there is a test.

**2. One unservable cover threw away the entire library.** `PUT /library/provider/{p}` validated art
per entry and returned 400 for the whole payload on the first bad value, so a path mismatch cost the
operator *every game from that store*, not a thumbnail — and the plugin, which only ever sees
`HostRequestError`, could not say which. A provider reconcile now **strips** unservable local art and
syncs the rest (`sanitize_art_paths`), logging one aggregated warn naming the count, an example path
and the env var. The invariant the 400 held is unchanged: no unservable path is ever persisted. The
operator's own single-entry custom writes keep the hard 400 — there the path was typed by hand, and
silence would be the wrong answer.

⚠ **Operator-visible:** an art-root mismatch no longer fails a sync. If covers are blank where you
expect art, the cue is the host log's `dropped local art the proxy may not serve` line, and the knob
is `PUNKTFUNK_LIBRARY_ART_ROOTS` (which **replaces** the defaults — list every root you need).

### Hyprland/Sway — the wlr-family backends asserted a cursor mode instead of negotiating it

🛑 **Every cursor-forward session on current Hyprland died at `select_sources`** — "pipeline build
failed" and a black client, with `unavailable cursor mode 4` in the portal log.

Hyprland and wlroots both hardcoded portal `CursorMode::Metadata` whenever the session had
negotiated the cursor channel, and never asked the backend what it supports. That is **not** a soft
failure: xdg-desktop-portal's **frontend** validates the requested mode against the backend's
`AvailableCursorModes` and fails the call with `"Unavailable cursor mode %x"` before the backend
ever sees it.

⭐ **Measured on glass 2026-08-14, and worse than the report suggested.** Against a live Hyprland
0.56.2 with xdg-desktop-portal-hyprland 1.4.1 and xdg-desktop-portal 1.22.1 — all current —
`AvailableCursorModes` reads **3** (`Hidden|Embedded`) on both the backend impl interface and the
frontend. **xdph does not offer the metadata cursor at all**, so this broke every cursor-forward
session on current Hyprland, not merely on old installs, and **updating the portal would not have
helped.** xdpw is the same from the other end: its `screencast.c` refuses `METADATA` outright.

`pf-capture`'s own portal path has always negotiated (`choose_cursor_mode`); this restates that
ladder in `pf-vdisplay`, which may not depend on `pf-capture`. The downgrade is graceful rather than
merely survivable: with the portal on `Embedded` no `SPA_META_Cursor` arrives, so the host feeds the
cursor channel nothing and a cursor-forward client draws nothing of its own — **one pointer, not
two.**

**`PUNKTFUNK_PORTAL_CURSOR_MODE=auto|hidden|embedded|metadata`** pins the preference for a backend
that advertises a mode it implements badly, which negotiation cannot detect. It is a preference
only: a pin runs the same ladder, so no value can re-create the refused request.

⚠ The module is declared **unconditionally**, so its ladder tests run on every CI leg rather than
only the one that compiles `mod hyprland` — including a Linux-only test pinning our bit values
against ashpd's enum (ashpd answers 4 for `Metadata`, the number in the report), verified
non-vacuous by planting a wrong discriminant.

### Android — the audio plane trusted AAudio, and a TV box that opened a stream it never played was silent for the session

🛑 **Reported from the field: no audio at all on an NVIDIA Shield Android TV, stereo, with the same
host and settings that play fine on an Apple TV.** Video unaffected. Turning off the client's
low-latency mode — which is what gates the forced HDMI mode switch and the `usage=Game` tagging —
changed nothing.

The Android client opens AAudio directly (the Apple client goes through AVAudioEngine, which
reconfigures itself on a route change; that difference is why this was Android-only). Opening
AAudio is a negotiation with a vendor HAL, and this plane treated it as a formality: one Exclusive
attempt, one Shared retry, and everything after the open taken on trust. **Three distinct failures
all presented as "the app has no sound" behind a healthy-looking log**, and none of them was
detected:

- **A configuration that opens but routes nowhere.** Nothing ever checked that the device actually
  pulled a sample, so the decode thread would happily decode Opus into a dead stream forever.
- **`request_start` failing.** The old code gave up on the spot instead of trying anything else, so
  one unhappy configuration disabled audio for the whole session.
- **A disconnect.** By AAudio's contract a disconnected stream is dead and the only recovery is
  close + open a new one. The error callback logged a warning and did nothing else — so an HDMI
  mode switch, an AVR re-handshake or any route change meant silence for the rest of the session.
  On a TV that is not a rare event: the client itself drives an HDMI mode switch on the video
  plane, and the platform's own match-content-frame-rate setting drives more.

The open now walks a **ladder**, every rung has to **prove the device is pulling** before it is
accepted, and a **supervisor** owns the plane for the session and reopens it when the device goes
away (bounded retries across the settling time of a route change, so a reopen landing mid-switch
does not permanently disable audio). The granted rate/channel-count/format are checked against what
was asked for rather than assumed — the realtime callback casts AAudio's buffer to `f32` and writes
`num_frames × channels` of them, so a HAL that disagreed was an out-of-bounds write on the audio
thread, not merely a mistuning.

⚠ **Behaviour change on TV boxes: they now start at Shared instead of Exclusive.** Exclusive is
MMAP, the lowest-latency path AAudio has, and the one rung whose routing cannot be verified from
inside the process. The latency it buys here was never actually banked — the jitter-ring depths are
unchanged from the Shared-only era (`JitterTuning::AAUDIO` still primes at 25 ms) — so on a
mains-powered HDMI box the few ms are worth less than not betting the audio plane on it. Phones,
tablets and handhelds are unchanged and still try Exclusive first. If no rung proves itself, the
first one that opened and started is used anyway: the watchdog must never be able to turn working
audio into no audio.

⚠ **Embedder-visible:** `NativeBridge.nativeStartAudio` takes a third argument, `isTv`
(`FEATURE_LEANBACK`, the same source the video plane already used).

Three new sysprops bisect all of it on a device that cannot be handed a custom build, alongside the
existing `debug.punktfunk.no_av_sync`: `debug.punktfunk.audio_sharing` (`exclusive`|`shared`),
`debug.punktfunk.audio_perf` (`lowlatency`|`none`) and `debug.punktfunk.audio_reopen` (`0` pins the
old give-up-on-disconnect behaviour). A stream that stops taking samples after it started now says
so at `error` level instead of looking exactly like an app with no sound.

### gamescope — we ship our own Vulkan WSI layer, so a game can reach an HDR10 swapchain (⚠ packager-visible)

🛑 **On essentially every box running a distro gamescope, no game could render HDR at all** — and
nothing said so.

A game nested under gamescope gets an HDR10 swapchain from the FROG WSI layer and from nothing
else: gamescope advertises no runtime colour-management protocol a Mesa/NVIDIA WSI could negotiate
through. That layer speaks `gamescope_swapchain` to the compositor, and when the two disagree the
compositor rejects the client's `swapchain_feedback` and **every Vulkan client dies on a black
screen** with sound and input intact and no error anywhere.

We shipped our own compositor and *not* a layer, on the recorded grounds that the layer is
"version-independent of the compositor binary". It is not — `wsi_layer_matches_our_gamescope()`
exists precisely because it is not — so the host was left guessing from version triples, and that
guess is wrong in both directions. A distro at the same upstream tag that patched the protocol
compares EQUAL and keeps a layer that will black-screen every game; a distro at a different tag
with a byte-identical protocol compares unequal and loses HDR for nothing. **Since we pin a rev,
the second case is the normal one.**

We now build the layer from the same tree at the same rev as the compositor and ship it, so the two
cannot drift and the guess stops being load-bearing. It installs under **our own** name
(`VK_LAYER_PUNKTFUNK_gamescope_wsi`), at our own path, with our own enable/disable variables, so it
coexists with the distro's rather than colliding — the Vulkan loader keys implicit layers on that
name — and the host switches the two independently within one session.

`WsiPlan` resolves three states once per launch (the fallback spawns `--version` probes):

| state | condition | action |
|---|---|---|
| `Ours` | our layer is installed | enable ours, force the distro's off — **both halves, or it is a bug** |
| `DistroKept` | no layer of ours, distro's looks compatible | touch nothing |
| `DistroDisabled` | no layer of ours, distro's untrusted | v0.28.0's behaviour |

That last arm is the fail-safe: a host newer than its gamescope package behaves exactly as it did,
rather than enabling a layer that is not there.

⚠ **What packagers must know.** The layer manifest carries an **absolute** `library_path` baked in
at build time, so every channel installs the `.so` at exactly that path: literal
`/usr/lib/punktfunk` — **not** `%{_libdir}` (which is `/usr/lib64` on Fedora) and not a Debian
multiarch triplet. Nothing links it by soname (the loader `dlopen`s it by that path), so multilib
has no claim. rpm and nix read the path back **out of the manifest** and fail if it names a file the
package does not install, because a manifest pointing at nothing is the silent shape of this bug.
A missing layer is **fatal in every channel**, not best-effort: a package carrying the compositor
without it looks completely healthy and then silently denies every game an HDR10 swapchain.

The packaging scripts now take `--stage` (the DESTDIR the gamescope build script wrote) instead of
a path to one binary, and CI caches the whole staged tree; the `gs-cache` key already hashes
`packaging/gamescope/**`, so stale caches in the old single-file shape cannot be restored into the
new layout. The manifest rewrite lives in `packaging/gamescope/rewrite-wsi-layer-manifest.py`
rather than a heredoc, because the FHS builds and the Nix store both need it and must rename the
layer identically. **NixOS has no `/usr`**, so the layer lives inside the gamescope derivation and
the host's path is overridable with **`PUNKTFUNK_GAMESCOPE_WSI_LAYER_DIR`**, which the module sets
— the same posture as `PUNKTFUNK_GAMESCOPE_BIN`.

### gamescope — HDR sessions anchored SDR white a stop bright, and never said game HDR was unreachable

🛑 **Field report: Steam's Big Picture UI glaring and over-saturated while HDR game content looked
washed out, on the same stream.** Those are one error.

gamescope maps everything that is not an HDR game — the desktop, the Steam overlay, an SDR title —
into the session's PQ container at `--hdr-sdr-content-nits`, and we passed that flag **only** when
an operator had set `PUNKTFUNK_GAMESCOPE_SDR_NITS`. Unset, gamescope used its own default of
**400**, while every first-party client anchors diffuse white at **203** (BT.2408 reference white;
the Apple presenter hands exactly that to `CAEDRMetadata.hdr10`'s `opticalOutputScale`). The two
ends sat nearly a stop apart, so the UI landed above SDR white and the client's tone-mapper worked
from a reference point the host had never used, flattening the content around it.

**The flag is now always passed, defaulting to 203.** `PUNKTFUNK_GAMESCOPE_SDR_NITS` still
overrides it for anyone who wants a brighter or dimmer desktop — it is the anchor, not a taste
knob. ⭐ Because it is an env var, a field A/B needs **no rebuild**.

Separately, and visible in the same log: the two HDR decisions in a gamescope session were made
independently. `hdr_args()` never consulted `wsi_layer_matches_our_gamescope()`, so when the layer
check fired the session launched **advertising HDR while having made an HDR10 swapchain
unreachable for every game in it** — a title told to render HDR rendered it into an SDR swapchain
and looked washed out, with nothing anywhere saying why. It now warns. The behaviour of the check
itself is deliberately unchanged; the section above is the real fix.

### punktfunk-gamescope `+pfhdr7` — a lingered session no longer dies of its own capture teardown

🛑 **On client disconnect the host keeps the headless gamescope alive so a reconnect resumes the
same session — and gamescope could SIGSEGV in exactly that window, so the kept display was dead and
reconnect silently got a fresh compositor with the game lost.** When the capture consumer leaves,
PipeWire's `remove_buffer` (and the stale-push path in `dispatch_nudge`) destroyed idle buffers on
the **PipeWire thread**; dropping the last `CVulkanTexture` reference there calls into the Vulkan
driver (`vkDestroyImage`/`FreeMemory`/dmabuf fds) while steamcompmgr can still be inside
`vulkan_screenshot` on another buffer of the same 4-buffer pool. On NVIDIA that races to a SIGSEGV
in `CVulkanCmdBuffer::insertBarrier` — timed at stream end, which is why it selectively killed
linger. The journal signature: linger line → coredump → `kept display was dead — recreating`.

Patch 0009 queues those corpses on the PipeWire thread and has steamcompmgr reap them on every
vblank — including while the stream is paused, which is precisely the linger state. Found, fixed
and proven live by **luxus** ([punktfunk-overlay#9](https://github.com/luxus/punktfunk-overlay/issues/9)):
four coredumps on 4K60 HDR + composited cursor, zero after; disconnect/reconnect now reuses the
lingered session. Banner `+pfhdr6` → `+pfhdr7` (no new capability — but "reconnect lost my game"
triage must be able to read a box's exposure off its banner, the same rule as `+pfhdr5`/`6`).

### Apple — the stats overlay lied three ways, and every host-anchored number with it

🛑 **Two sessions minutes apart on the same wire read `hostnet_p50` 17–21 ms, then a physically
impossible 4.4 ms** — host-side encode alone is ~4.7. Three independent defects, all of which
corrupt any measurement taken against a host clock:

- **A frozen clock-offset.** The client consumed the **connect-time** skew offset and cached it —
  in a `Stage2Pipeline` field, in a `StreamPump` `let`, and in a `ContentView` closure **capture
  list** feeding the hostnet meter and the host/network splitter. The core keeps a *live* estimate
  (`punktfunk_connection_clock_offset_now_ns`, ABI v10, re-synced every 60 s and on suspected
  wall-clock steps) whose own doc says the connect-time value "silently corrupts every
  capture-clock comparison" after an NTP step — **and a VM host steps.**
  `PunktfunkConnection.clockOffsetNs` is now the live read (an atomic load behind the FFI), read at
  use: per record, per AU, per enqueue. The Swift audio plane's AvSync observation takes the same
  live value.
- **Silently trimmed impossible samples.** `LatencyMeter`'s guard (≤ 0 after offset correction)
  dropped samples without counting them, so a wrong offset did not invalidate a window — it trimmed
  the impossible half of the shifted distribution and presented the surviving tail as a plausible
  small number. That is the origin of the historical "0 ms network / 0 ms e2e" readings. Refusals
  are now counted and drained **separately from `Stats`** — deliberately, because a fully-poisoned
  window drains to `nil` and a count inside `Stats` would vanish with it. The HUD shows an orange
  **`clock offset suspect`** line and the stats line grew **`skew_trim=N`**; nonzero means
  disregard `e2e`/`hostnet` for that window.
- **`-1` fallbacks printing as `NaN`.** In a `CVarArg` context `cond ? someDouble : -1` does **not**
  unify to `Double` — the literal goes in as `Int`, and `%f` reads `Int64(-1)`'s all-ones bit
  pattern, which is a quiet NaN. Latent since the 1 Hz stats line existed. All fallbacks are now
  typed `-1.0`.

⚠ **Any client-side e2e or hostnet figure recorded before this release is suspect** and worth
re-measuring rather than trusted as a baseline.

Two new levers ship with the tvOS present-floor investigation, both env-only:
**`PUNKTFUNK_FRAME_LATENCY`** (float 0…4, default 1) makes the `preferredFrameLatency` ask
adjustable, so an on-device ladder can establish whether the property does anything on tvOS — the
previous "immovable two-refresh floor" verdict rested on a **readback** of a plain read-write
float, which is not a grant. **`PUNKTFUNK_PRESENTER=stage1` now resolves on Release builds** (the
persisted picker stays DEBUG-gated; an env var takes a `devicectl`/Xcode launch to exist, so it is
never a leftover). Stage-1 presents on the hardware video plane rather than through the GPU
compositor — the one rung that can dodge the two-refresh regime — and the field A/B that concluded
otherwise had silently run stage-4, because the gate keyed on build config.

### Apple — two colour faults: an SDR stream shipped untagged, and it forced the TV into HDR10

- **The SDR layer was never tagged.** `configure(hdr:)` guards on `hdr != hdrActive` and
  `hdrActive` starts `false`, so a session that is SDR from its first frame matched the initial
  state, fell through the guard, and `configureColor` never ran once — the layer kept `make()`'s
  bare configuration, which assigns no colour space. An untagged `CAMetalLayer` gets no colour
  matching: a BT.709 stream is drawn in the display's native space. Mild oversaturation on a P3 Mac
  or iPad; on a tvOS display composited for HDR it also lifts the black floor. ⚠ It also made
  `PUNKTFUNK_SDR_COLORSPACE` **dead code on exactly the sessions it exists to fix**, so a field A/B
  of that knob would have shown no change.
- **An SDR stream drove an HDR-capable TV into PQ output.** `applyDisplayCriteriaIfNeeded` builds a
  synthetic format description hardcoding BT.2020 primaries, ST.2084 and the BT.2020 matrix, then
  hands it to `AVDisplayManager` — and its guard checked only that no criteria had been set and that
  the user's HDR *setting* was on, never that **the stream** was HDR. That setting defaults to true.
  The Apple TV switches HDMI to limited range in its HDR modes, so a set configured for full range
  renders code 16 as grey rather than black. Now gated on `connection.isHDR` as well; layout re-runs
  it, so a session that flips to HDR mid-stream still picks the mode up.

### Apple — the macOS device-change recovery could answer itself forever (mic on)

**Streaming from a Mac with the microphone enabled cut audio AND input on a ~2.5 s metronome
while video ran untouched** (field, 2026-08-14: a Mac Studio whose default input is a 6-channel
device). The chain: the voice-processing engine cannot start on that mic, every rebuild re-tried
it, and the failed attempt's HAL churn (VPIO builds and tears down an aggregate device) stopped
the healthy fallback engines — which posted the `AVAudioEngineConfigurationChange` that scheduled
the next rebuild. Each ~1.9 s rebuild runs on the main thread, where macOS input capture and
sending live, so input froze on the same beat — and since audio, input and mic share the QUIC
datagram plane while video rides its own socket, the wire signature read as a network fault and
the host's METRONOMIC heuristic pointed at the display stack. Three defenses, layered because no
single one covers every feedback shape:

- **A voice-processing start failure latches per input device** (`CombinedTopologyGate`): a
  rebuild goes straight to the split topology instead of re-running a failure that is a property
  of the device. A different default input earns exactly one fresh attempt.
- **A configuration change posted by an engine that is RUNNING is the rebuild's own echo, and is
  ignored**: an engine stops itself before posting, so a live poster was already restarted.
- **Rebuilds that chain anyway back off exponentially** (`RebuildBackoff`: 0.5 s floor doubling
  to a 30 s cap, reset by 10 s of quiet) — an unforeseen loop costs one blip per half-minute
  instead of a metronome, and the chaining itself logs a WARN that names the condition.

iOS/tvOS behaviour is untouched (routes are session-managed there; nothing is latched). Until a
client carries this, the field workaround is turning the client microphone off.

**And the engines no longer start on the main thread at all.** An engine start can block on the
audio server for seconds (~1.9 s per attempt in the field case) and macOS captures and sends the
stream's input from the main thread — so even a single legitimate device switch froze input for
the length of the rebuild, loop or no loop. All engine build/start/teardown now runs on a
per-session serial `engineQueue`; the main queue keeps only the trigger bookkeeping (debounce,
backoff, retry ladder), which is cheap by construction. ⚠ Embedder-visible edge:
`SessionAudio.start()` is now asynchronous on macOS too (it always was on iOS/tvOS) — playback is
live shortly after the call, not on return, and `stats` is safe from any thread.

### Apple gamepad UI — a host menu, and About becomes a page

**UP on a saved tile opens Wake / Copy link / Edit… / Forget pairing / Remove.** The desktop and
Android consoles have had this for a while; this is the Apple port, so the three consoles are
learned once. Wiring UP takes the whole vertical axis away from scrolling (down goes inert) — a
horizontal carousel has no vertical travel to spend, and one meaning per direction is what makes
the gesture learnable. **Remove arms on the first press and fires on the second**, disarming if
focus wanders off the row: the touch grid gets a system confirmation dialog, and a thumbstick from
across a room deserves at least as much. Edit reuses `GamepadAddHostView` seeded from the record and
writes a **copy** back through `HostStore.update`, so the fingerprint, MACs, pins and binding the
form never shows survive a rename; it **replaces** the menu rather than stacking on it, keeping the
shell's "depth ≤ 1 by construction" true. A pinned profile card offers only Unpin — it is a
shortcut, not a second host.

**The start-of-stream shortcut banner is retired.** Telling someone the controls for six seconds,
over the stream they just connected to, answers the question at the one moment nobody is asking it
— and it put a composited overlay above the stream to do it. The words are now a catalogue rendered
in an About page you can open, which is also its own section rather than the last row of Interface.
Its remaining fixes: the identity card became a version line under the rows, a zero-radius clip is
still a clip (it cropped the TV's wide icon), and the card ignored the row column.

⚠ **Apple console screens read the ink they publish.** A SwiftUI screen cannot read the environment
value it publishes in the same view — so a pale palette stayed white-on-white on Apple TV. Fixed
across every console screen.

### Console UI — Skia sized its function table to the loader, not to what we promised

🛑 **On a Steam Deck the console home died on update**, and in a stream the same failure quietly
cost the stats OSD and capture HUD.

The skia-safe 0.87 → 0.99 move swapped `BackendContext::new` for `new_builder(…, None)` and
recorded the `None` as "byte-for-byte what the removed constructor did". True of the **value**,
false of the **behaviour**: `None` leaves Skia's `fMaxAPIVersion` at its `0` sentinel, and the newer
Skia acts on that sentinel by falling back to **`vkEnumerateInstanceVersion()` — the loader's
ceiling, not ours.** The presenter declares 1.3; a current Mesa answers 1.4 (1.4.321 on SteamOS
3.7, host and inside the flatpak sandbox alike). Skia then validates a 1.4 function table against an
instance that only promised 1.3, `vkGetDeviceProcAddr` returns null for the entry points in
between, and `make_vulkan` hands back `None`. At 0.87 the sentinel was inert because that Skia knew
nothing of Vulkan 1.4 — **which is why this surfaced the moment v0.28.0 landed.**

`run.rs` makes an overlay that cannot init fatal for `--browse`, so the Decky panel's button and the
gamepad-UI library shortcut both failed to open. The presenter now publishes
`SharedDevice::api_version` — `min(what we declared, what the loader reports)` — and
`SkiaOverlay::init` passes it instead of `None`. ⚠ `pf-presenter`'s `vk` module is
`cfg(any(linux, windows))`, so this was never Deck-specific.

### pf-vkdecode — AV1's "maximum parameters" level is not a level above the ceiling

🛑 **Every AV1 session demoted to D3D11VA** with `stream level (seq_level_idx 31) above the device's
maxLevel (AV1 Std level 23)` — on hardware decoding the stream trivially on the rung it fell
through to.

`seq_level_idx` is a 5-bit field: Annex A defines 0…23 (levels 2.0…7.3), reserves 24…30, and makes
**31 the "maximum parameters" level — the spec's own way of saying the bitstream is not constrained
to a level.** `StdVideoAV1Level` stops at 7.3 = 23, so 31 has no Std code point and the index-coded
comparison that holds across 0…23 says nothing: `31 > 23` is true even of a device that decodes
everything AV1 can name, which is what makes it useless as a capability test. We write no AV1 level
on any host encode path, so whichever sentinel the vendor's encoder defaults to is what the client
must accept. This is the AV1 half of the same defect fixed for H.264/H.265 in v0.28.0, which was
left alone on the premise that no over-declaration had been seen in the field — the reporter's log
from that same day already showed otherwise.

### Client stats — the stage line is a partition again

A field reader added up `host 5.4 · net 0.3 · decode 6.6 · display 1.4` against `e2e 8.1` and asked
why the parts did not sum. Fair question: they sum **without** `decode`.

The stages *are* a per-frame partition of e2e — pts →(host+net)→ received →(decode)→ decoded
→(display)→ displayed — for as long as the `decoded` stamp is a **completion** stamp. On the
synchronous rungs it is. On the **native-Vulkan** rung `receive_frame` returns at *submission*
(~0.1 ms) and the stamp is taken there, so `display` is measured from submit and the GPU decode
happens **inside** it. `host+net` and `display` already tile e2e; the `decode` figure (received →
fence-complete) re-counts the GPU work `display` contains — two figures with one overlap, printed
as though they tiled.

On that rung `decode` now leaves the stage line and gets its own, carrying the two caveats a reader
needs: it is **one sample per window** there, not the p50 every other figure on that line is, and it
is already inside `display`, so adding it double-counts. The synchronous rungs are untouched.
⚠ **Deliberately not changed:** the one-sample-per-window design. A per-frame fence wait serialises
the decode pipeline (an APU's 19 ms decode capping a 5120×1440 stream at ~51 fps) and polling
quantises every sample up by a frame interval. The reporting was the defect, not the sampling.

### Host — two warnings that named the wrong subsystem

Both fired in the same 2026-08-13 field log, and both sent an investigation somewhere innocent:

- **"Client keyframe recoveries are METRONOMIC — a periodic host/display disturbance … is the
  likely cause"**, at `period_s=2.0`, naming three host subsystems. **2.0 s is the *client's*
  `FLUSH_COOLDOWN`.** The receive-backlog guard sheds a standing queue with a flush plus a keyframe
  request, rate-limited to one per cooldown, so a client that cannot sustain the stream asks for a
  keyframe at exactly that spacing for as long as it stays behind. **Perfect periodicity is the
  signature of a fixed software cooldown, not of a physical disturbance.** The host now compares
  against `punktfunk_core::client::FLUSH_COOLDOWN` itself rather than a copy of the number, so the
  two cannot drift.
- **"The audio encode thread could not keep up — captured audio was DROPPED"**, worst case
  `dropped_chunks=11251`. Not one sample anybody wanted was lost. PipeWire negotiated a 128-frame
  quantum, so the plane produces 48000/128 = 375 chunks/s and a 30 s window holds exactly 11250 —
  a 100 % drop rate at `peak_db=-120.0`, digital silence. Every one of the ten warnings straddled a
  **session boundary**, and `dropped_chunks/375` matches the seconds with *no live session* in that
  window to within a fraction of a second. The warning no longer fires for idle seconds.

### NixOS — the plugin runner was installed, running, and reported missing

🛑 **On NixOS every plugin *package* op failed with "the plugin runner isn't installed", on a box
where the runner was installed, enabled and running.** `punktfunk-host plugins status` said so, and
the console's Plugins screen still refused to install anything.

The host resolved `punktfunk-scripting` by checking FHS locations exclusively —
`/usr/bin/punktfunk-scripting`, the `/usr/lib` + `/usr/share` pair behind it, and the `~/.local`
mirror the SteamOS installer lays down. Nix installs a wrapper at `$out/bin/punktfunk-scripting` in
a **derivation of its own**, so it is neither beside the host binary nor anywhere under `/usr`, and
nothing the resolver looked at could ever match. Service ops (`enable`/`disable`/`status`) go
through systemd and were unaffected, which is what made the failure read as arbitrary: the runner
demonstrably worked, and only the half that had to *locate the executable* was blind.

Resolution now matches `punktfunk-encode-worker`'s: **`PUNKTFUNK_SCRIPTING` → beside the host
binary → `PATH` → the `/usr` layout → the `~/.local` layout.** `PATH` is the rung Nix lands on. The
`/usr` rungs are kept after it rather than dropped, because a systemd unit's `PATH` need not include
`/usr/bin`. As with the encode worker, an explicit `PUNKTFUNK_SCRIPTING` is deliberately *not*
existence-checked — a named path that is wrong should fail naming itself, not fall through to some
other runner. The "not installed" text now also names NixOS and the override, instead of pointing
every operator at `apt`.

⚠ **Packager-visible, and the other half of the fix:** the NixOS module now puts
`services.punktfunk.scripting.package` on the **host unit's** `path`. `environment.systemPackages`
only ever covered an operator's interactive shell, and the console installs plugins from *inside*
the host service — whose `PATH` is exactly that unit list. Without it the CLI would have been fixed
and the console would not. Anyone packaging the host separately wants the same property: the runner
must be on the service's `PATH`, or `PUNKTFUNK_SCRIPTING` set for it.

The `ln -s "$(command -v punktfunk-scripting)" ~/.local/bin/punktfunk-scripting` workaround is no
longer needed and can be removed.

### `/bin/true` and `/bin/false` are not portable — two tests failed on NixOS

NixOS ships only `sh` in `/bin`, so `gamelease`'s hand-off test and `pyrowave_remote`'s
handshake-rung test failed there for reasons unrelated to the code under test. Both now resolve a
real binary rather than assuming an FHS path.

### Documentation

**`docs-site/public/openapi.json` was stale again, and by the same mechanism as last release.**
v0.28.0 fixed it once (it was five releases behind at `0.21.0`); the scanner-removal regen then
updated `api/openapi.json` alone and it drifted a second time inside that same cycle. It has now
drifted a third time, across the unpair-all endpoints — the docs-site copy was still stamped
`0.27.0` and missing both collection deletes. Re-synced; the two files are byte-identical again.

⚠ **The copy is a documented manual step (`cp api/openapi.json docs-site/public/openapi.json`,
CONTRIBUTING.md) and nothing in CI enforces it.** Three drifts in two release cycles is the
argument for gating it; until something does, **treat the copy as part of regenerating, not as a
follow-up.**

### Linux — the data-plane threads finally get the priority they ask for (⚠ packager-visible)

**On every Linux host to date, `pf_frame::thread_qos`'s per-thread renice was a silent no-op** —
it needs CAP_SYS_NICE or a raised RLIMIT_NICE, no packaging channel granted either, and the host
binary can never carry a file capability (KWin identification, the 0.26.0-1 incident). So the
capture/encode and send threads ran at nice 0, and a CPU-saturating burst on the host — a fresh
game launch's shader-compile storm is the canonical one — descheduled them at will. A 2026-08-14
field log showed the result end to end: 5 ms audio datagrams leaving late enough to stutter, the
client's delay signal rising, and ABR cutting a gigabit-Ethernet session to its 5 Mbps floor with
zero packet loss — while the box carried 708 Mbps cleanly minutes later, once the storm passed.

**The renice now falls back to RealtimeKit** (`MakeThreadHighPriorityWithPID`, one blocking
system-bus call per boosted thread) — the same unprivileged broker PipeWire clients use, present
on effectively every desktop install. No capability enters the host's permitted set, so KWin
identification is untouched. Boxes with neither rtkit nor the new limit keep today's best-effort
no-op, one debug line per thread.

**The audio plane is boosted at all for the first time.** The 5 ms Opus capture→encode→send loop,
the PipeWire capture mainloop thread (its `process` callbacks run there — PipeWire's own
`module-rt` only covers data loops we don't use), and the pad-audio streamer now take the same
boost the video threads always asked for. The audio loop is `critical`: a scheduling stall there
is directly audible where a late video frame is one presentation slip.

⚠ **Packagers: a new `user@.service.d` drop-in.** rpm/deb/Arch (and the Bazzite sysext, via the
RPM) now ship `packaging/linux/50-punktfunk-nice.conf` →
`/usr/lib/systemd/system/user@.service.d/50-punktfunk-nice.conf` (`LimitNICE=-15`), so the direct
`setpriority()` also works where rtkit isn't running. It raises a session *limit*, from the next
login — nothing is reprioritized by itself. The NixOS module instead sets
`security.rtkit.enable = lib.mkDefault true` (rtkit is not a given there). It remains true that
**no channel may ever grant the host binary a file capability** — this change is the sanctioned
route to the same end.

---

## v0.28.0

180 commits since v0.27.0.

### Versions

| | v0.27.0 | v0.28.0 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged |
| C ABI | 18 | **19** | `punktfunk_connection_note_frame_index_ex` + `punktfunk_reanchor_gate_arm_expecting_drops` **added**; nothing removed, nothing widened |
| Rust edition | 2021 | **2024** | the whole tree bar four vendored crates |
| MSRV (`rust-version`) | 1.82 | **1.85** | the *declared floor* only — the pinned toolchain is unchanged |
| Workspace crate dirs | 27 | **27** | unchanged (39 members; two `tools/` crates still deliberately *excluded*) |
| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3) |
| Windows virtual-gamepad channel | 3 | **3** | unchanged |
| Plugin index schema | 1 | **1** | unchanged |
| `api/openapi.json` | 0.25.0 | **0.27.0** | the management API **did** change this release (below); the file was regenerated mid-cycle, so it carries the then-current stamp, not `0.28.0` |
| gamescope patch level (`+pfhdrN`) | 5 | **6** | 7 patches → 8 (`GAMESCOPE_NO_FOCUS`); no new capability |
| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.4** | unchanged |
| `@punktfunk/plugin-kit` | 0.4.0 | **0.4.1** | publishes the `icon` field |

⚠ **`crates/pf-driver-proto` changed again**, as it did in v0.27.0 — but *not* in its contract. The
wire bytes, `PROTOCOL_VERSION` (6) and `MIN_DRIVER_PROTOCOL_VERSION` (3) are all untouched; what
moved is the manifest (`edition`/`rust-version` now inherit from the workspace) and one test that
was reading a `[u8; 40]` through `bytemuck::from_bytes` — an alignment assumption a favourable
stack slot had been hiding, and the kind of thing Miri exists to catch (below). If you ship the
driver or the gamepad channel, this release needs no re-integration.

⚠ **`api/openapi.json` is still not gated by CI** — nothing regenerates or diffs it in a workflow.
A unit test (`openapi_document_is_complete_and_checked_in`) does compare the checked-in copy against
the served document, with `info.version` normalized on both sides, so the *surface* is protected
even though the stamp drifts. The docs-site copy is a plain file copy and was **not** protected:
see the note under **Documentation** below.

### ⚠ Breaking changes

**None on the wire, and none that break an embedder at runtime.** Wire protocol 2 is unchanged, so
existing pairings and every shipped client keep working; the C ABI moves by addition only. What
follows changes what the **host itself does**, how you **build**, and what a **stock package does by
default**.

- 🛑 **The host no longer scans any launcher itself — the six built-in library scanners are
  deleted and replaced by plugins.** This is the only change here that can leave a working install
  visibly emptier: **a host with no library plugins installed has an empty grid.** Full detail and
  the (deliberately absent) migration below.
- **Rust edition 2024, MSRV floor 1.85.** If you vendor or patch any workspace crate, your toolchain
  must be ≥ 1.85. Our pinned toolchain did not move — only the declared floor.
- **Building from source now needs a working C compiler**, because `aws-lc-sys` compiles AWS-LC.
  No CMake, Go or NASM for the default (non-FIPS) build. Detail under the TLS section below.
- **GameStream is opt-in on every route.** A packaged host that served Moonlight by default becomes
  native-only until the operator sets `PUNKTFUNK_GAMESTREAM=1`. Full detail below.
- **No punktfunk process holds REALTIME GPU priority any more.** Both levers (the driver's
  `IddCxSetRealtimeGPUPriority` raise and the host's `HIGH → REALTIME` auto-upgrade) default OFF;
  the ladders that re-enable them are new opt-ins. This is a field-convicted stall fix, below.
- **The shipped Bazzite `host.env` template no longer pins `PUNKTFUNK_GAMESCOPE_ATTACH=1`.** If you
  copied it verbatim — which the docs told you to — Game Mode was mirroring the box's screen. Below.

### The six built-in library scanners are gone — every game source is a plugin (⚠ operator-visible)

The host no longer scans any launcher itself. `library/{steam,epic,gog,heroic,lutris,xbox}.rs` and
the `scanner_defs()` table are deleted; `GET /library/scanners` now lists exactly what the operator
has installed, and every row reports `origin: "plugin"`. This is M6/WP6.4, the end of the migration
whose bridge half shipped in v0.26.0 — the plugins have been published and index-pinned since
2026-08-08.

**A host with no library plugins installed has an empty grid.** That is the upgrade note: the
console's Library page offers one-click install per source (the D9 nudge, still there and still
never auto-installing), and nothing about a title changes when its plugin takes over.

Why that last part is true, and why this was safe to do as a deletion rather than a rewrite: a
plugin **claims** its store (D2), and a claimed entry surfaces under the deterministic
`<store>:<external_id>` id the scanner used to produce. Entry ids, GameStream FNV-1a app ids,
client-side art caches, Moonlight pins, the operator's per-source toggles and their per-entry hides
are all keyed on that id and none of them move. `library-scanners.json` keeps its name, its shape
and its contents — an operator who had `steam` switched off still has it switched off, with no
migration step.

What survives the scanners, deliberately:

- **`launch.rs` in full.** Launch is host-owned by design D1 — a plugin publishes a validated
  *value* and the host builds the command — so every typed kind (`steam_appid`, `steam_ui`,
  `launcher_ui`, `epic`, `gog`, `aumid`, `xbox`, `lutris_id`, `playnite`) stays exactly as it was.
  `xbox_pfn()` moved here from the deleted `xbox.rs`: resolving a package Identity to its
  PackageFamilyName needs `AppRepository` enumeration, which is readable by the host (LocalSystem)
  and denied to the plugin runner (LocalService), and that measured asymmetry is the entire reason
  the `xbox` launch kind exists.
- **`SourceOrigin::Builtin`.** No host build emits it, but the web console ships as its own package
  and is expected to drive an N-1 host that still does, so the variant stays in the schema and the
  console keeps its `builtin` handling.
- **The store-label table.** Six ids keep their display names (`steam` → "Steam", …) so a source row
  does not rename itself to a bare id the day its plugin takes over.

Removed with them: the background cover-art warmer and its on-disk cache (they existed only for the
GOG and Xbox scanners, the two sources that had to ask a network catalog what a cover was — a
plugin resolves art while it scans), the legacy `steam:` branch of the art proxy, and the
`GameMeta::pc()` helper. **The host now makes no outbound HTTP request to build a library at all.**

⚠ **Dependency drop (packager-visible):** `rusqlite` (with its bundled, `cc`-compiled SQLite) and
`roxmltree` leave the host's dependency graph — they had no other users. `winreg` stays: `launch.rs`,
`procscan/windows.rs` and the two `audio/windows/` modules still need it. `base64`/`ureq` stay, as
the M6 plan predicted.

A stale `library-art-cache.json` from an older host is ignored, not migrated.

### GameStream is now opt-in on EVERY route (⚠ packager-visible default change)

The secure native-only host is the default everywhere; the Moonlight-compat planes (plain-HTTP
pairing + the legacy GCM path, security-review #5/#9) are enabled only by an explicit choice:

- **The shipped systemd user unit** (`scripts/punktfunk-host.service`, installed by deb/RPM/Arch/
  sysext) runs bare `serve` — `--gamestream` is no longer baked into `ExecStart`. Opt in via the
  new **`PUNKTFUNK_GAMESTREAM=1`** knob in `host.env` (pf-host-config; equivalent to the flag —
  either source enables), so no unit editing survives-upgrades dance is needed.
  ⚠ **Upgrade note:** a packaged host that served Moonlight by default becomes native-only until
  the operator sets the knob (a hand-made `ExecStart` drop-in keeps winning as before).
- **NixOS module**: `services.punktfunk.host.gamestream` default flipped `true` → `false`
  (module-check gained a "default is native-only" assertion); enabling it still opens the
  GameStream firewall ports.
- **Steam Deck installer**: `--gamestream` opts in (was on-by-default with `--no-gamestream`;
  the old flag is still accepted as explicit-off).
- Windows was already opt-in (unchecked installer task) and is unchanged.

### TLS moved to aws-lc-rs, with post-quantum key exchange (⚠ build-visible for packagers/embedders)

The rustls backend across the whole workspace — host, tray, clients and `punktfunk-core` — is now
**aws-lc-rs** instead of `ring`, which enables rustls's `prefer-post-quantum`: every TLS 1.3
handshake (management API, the native `punktfunk/1` control plane, QUIC) now offers the
**X25519MLKEM768** hybrid key exchange first. Ring has no ML-KEM, which is why the backend had to
move. This is negotiation-only and additive — the classical curves stay in the list, so any client
that does not implement ML-KEM connects exactly as before, and no wire format, ABI or pairing
record changes. The session AEAD (AES-128-GCM / ChaCha20-Poly1305) is a separate mechanism and is
untouched.

⚠ **Building from source now needs a working C compiler**, because `aws-lc-sys` compiles AWS-LC.
No CMake, Go, or NASM is required for the default (non-FIPS) build — on Windows x86_64 rustls turns
on `aws-lc-rs/prebuilt-nasm`, so no NASM has to be installed. If you add a crate that depends on
`aws-lc-rs` *directly*, name `features = ["prebuilt-nasm"]` on it: a package selection that pulls
`aws-lc-rs` without also enabling rustls's `aws_lc_rs` feature otherwise fails on Windows.

`punktfunk-core` gains an off-by-default **`ureq-tls`** feature (`tls::ureq_agent`) that builds a
blocking HTTP agent around a caller-supplied `rustls::ClientConfig` — the only way to install the
fingerprint-pinning verifier, since ureq's own `TlsConfig` has no hook for one. The desktop client
and the tray enable it; the Apple/Android cdylib embedders do not, and pull no HTTP stack.

**`ring` is gone from the tree entirely** — aws-lc-rs is now the only crypto backend on every
target we ship. Getting there needed the `ureq 2 → 3` upgrade in the same change, because ureq 2
named `rustls/ring` inside its own dependency declaration where no dependent could switch it off.
ureq 3 declares rustls with `default-features = false` and picks no backend, so the choice is
finally ours. ⚠ Spell that dependency `features = ["rustls-no-provider", "rustls-webpki-roots"]`:
ureq 3's convenience `rustls` feature pulls `_ring` and would quietly restore the second backend.

The ureq upgrade is otherwise internal, but two behaviours are worth knowing. Response size caps
are now enforced by the body reader, so an over-cap response is an **error** instead of ureq 2's
silent truncation (which used to surface as a confusing signature failure). And a fingerprint
mismatch is now matched on ureq 3's typed `Error::Rustls(..)` rather than by sniffing a substring
out of a transport error message — the old test could also fire on unrelated certificate errors.
Conditional requests are unchanged: ureq 3 still returns 304 as `Ok`, only 4xx/5xx become `Err`.

**Embedders of `punktfunk-core` that build their own rustls configs** should still call
`punktfunk_core::tls::install_default_provider()` at startup, or use `builder_with_provider`. With
one backend present rustls can infer it, so this is now insurance rather than a requirement — but
it is what stops a future second backend from turning config construction into a panic.

### The ENet control port now exists only while a pairing does (rust-safety WP0)

`rusty_enet` — a c2rust-style transpile of C ENet, and the host's only pre-auth-reachable unsafe
surface — no longer listens unconditionally: UDP 47999 binds when the paired-client list becomes
non-empty and is torn down when the last pairing is removed (a live client gets the same
TERMINATION+disconnect farewell as a host-side session end). Pairing itself is HTTPS on nvhttp and
never touches the port, so a never-paired `--gamestream` host exposes no ENet at all. En route:
the management API's unpair endpoint never persisted (`save_paired` was missing), so an unpair
lasted only until the next restart — fixed. `rusty_enet` is now pinned `=0.4.0`.

**Unpair is now a complete revocation, on both planes.** Beyond the persistence fix above, an
unpair used to leave the revoked client's LIVE session streaming until the client chose to
leave. Now: unpairing a GameStream client whose certificate owns the active launch ends that
session (the client gets the standard TERMINATION+disconnect, and unpair-all still closes the
ENet port); unpairing a native client deliberately stops its live punktfunk/1 session(s)
(matched by certificate fingerprint — anonymous/TOFU sessions are unaffected, they have no
pairing to revoke). The unpair endpoint's long-standing docstring caveat ("removes the client
from the listing without severing its ability to reconnect") is retired: TLS-level handshakes
still complete by design, but authorization is per-request and a live session no longer
survives its own revocation.

### GameStream is now a cargo feature (compile-time isolation — packager-visible)

The Moonlight-compat planes (nvhttp pairing, RTSP, the ENet control stream, `_nvstream` mDNS,
the compat media path) are gated behind a new **`gamestream` cargo feature — default ON**, so
every stock package is behaviorally identical (GameStream stays runtime-opt-in via
`--gamestream` / `PUNKTFUNK_GAMESTREAM`). Building with
`--no-default-features --features pyrowave` produces the **hardened native-only host**:

- **no `rusty_enet`** — the c2rust-transpiled C ENet stack (158 unsafe sites) is absent from
  the binary, provably (`cargo tree -i rusty_enet` finds nothing; CI asserts it);
- **no `rsa`** — the native planes run on the P-256 identity (above), and the legacy-identity
  fallback is a pem-only read (rustls/ring serves an existing RSA cert without the crate), so
  the accepted Marvin advisory (RUSTSEC-2023-0071) no longer applies to native-only builds;
- ~6,700 lines of Moonlight protocol code gone; `serve --gamestream` (or the env knob) against
  such a binary **refuses to start** with a clear error rather than serving less than asked;
- the native-only management API (and its OpenAPI document) has no GameStream PIN endpoints
  (`/api/v1/pair`, `/api/v1/pair/pin`); everything else — including the paired-client list and
  unpair — is identical, so consoles work unchanged.

The checked-in `api/openapi.json` remains the default-features document.

### The identity split — the native planes get their own (P-256) host identity

One RSA-2048 identity historically served every plane, because Moonlight mandates RSA and the
planes grew out of the GameStream host. The native punktfunk/1 QUIC plane and the management API
now share a separate **ECDSA P-256** identity (`native-cert.pem`/`native-key.pem`): generated by
rcgen on the workspace's aws-lc-rs backend, browser-compatible (Ed25519 server certs are not),
carrying real SANs
(localhost, loopback, the machine hostname — the legacy cert had none), and free of the accepted
`rsa`-crate Marvin advisory. The GameStream plane keeps the RSA identity untouched.

**Migration is pin-preserving by construction**: clients TOFU-pin the leaf-cert SHA-256 at
pairing and use that one pin for both QUIC and the mgmt/library API, so the new identity is
adopted **only when the native trust store is empty** (fresh installs, or after an explicit
unpair-all + restart). An upgraded host with live native pairings keeps presenting the legacy
RSA cert those clients pinned, and logs the migration path. Fingerprint pinning is
algorithm-agnostic, so existing shipped clients pair against P-256 hosts unchanged.

Follow-the-identity consumers updated in-tree: the tray's loopback pin and the plugin SDK's
mgmt CA now prefer `native-cert.pem` (falling back to `cert.pem`), and the Windows runner ACL
grant covers both. ⚠ A plugin bundling an **older** `@punktfunk/host` SDK on a **fresh**
(P-256) host trusts the wrong cert — set `PUNKTFUNK_MGMT_CA=<config>/native-cert.pem` in its
environment or rebuild against the current SDK.

⚠ **It is ECDSA P-256, not Ed25519 — deliberately.** rcgen can generate either, and Ed25519 would
be the obvious modern pick, but **no mainstream browser accepts an Ed25519 server certificate** and
an operator opens `/api/docs` in one. P-256 is the strongest curve that keeps the management API
reachable from a browser.

#### 🗓 Deprecation: the legacy-identity fallback goes away on **1 October 2026**

The fallback in `load_or_adopt` — "an upgraded host with live native pairings keeps presenting the
legacy RSA cert those clients pinned" — is a **migration aid, not a permanent branch**. From
**2026-10-01** the host stops taking it: a host that still holds only `cert.pem`/`key.pem` will mint
the P-256 identity and its native clients will have to re-pair once.

**Scope, precisely** — this affects the **native punktfunk/1 plane and the management API only**:

- **The GameStream/Moonlight plane is NOT deprecated and keeps its RSA identity permanently.**
  Moonlight mandates RSA and its pairing hashes bind the cert's X.509 signature bytes, so that
  identity cannot move without breaking every Moonlight client. Nothing about that changes on any
  date.
- Operators who want the split **today** need no new release: unpair all native clients, restart the
  host, re-pair. The host already logs exactly this.
- Fresh installs since v0.28.0 are already on P-256 and are unaffected.

⚠ **This date is a published commitment**, tracked as
[#201](https://git.unom.io/unom/punktfunk/issues/201) (due 2026-10-01), which carries the arm to
delete, the three identity-following consumers to re-check, and the test that has to invert. Without
it the notes would have promised something that silently never happens — the same shape as the
v0.22.3 notes describing a feature that release never contained.

### Memory-safety, compiler-enforced (embedder-visible lint tightening)

`punktfunk-core` now carries `#![deny(unsafe_code)]` crate-wide: everything that parses network
bytes is safe Rust by compiler-enforced invariant. The documented `#![allow]` carve-outs are the
client surface (`abi`, `client`) and the platform syscall-batching shims under `transport`
(`udp/{apple,linux,windows}`, `qos_windows`) — none of which interpret attacker bytes. In
`punktfunk-host`, the modules a secure-default host exposes (`native`, `native_pairing`, `mgmt`,
`mgmt_token`, `discovery`, `wol`) are `#[forbid(unsafe_code)]`. If you embed `punktfunk-core` and
patch it, new unsafe outside the carve-outs is now a compile error.

### NixOS + KDE — session detection, the other half

🛑 **v0.27.0's NixOS session-detection fix did not reach a stock NixOS + Plasma 6 box.** It resolved
the nixpkgs wrapper decoration through `/proc/<pid>/exe` (below) — and on that exact box the kernel
refuses to let us read that link. Reading `/proc/<pid>/exe` is not gated on owning the process: it
goes through `cap_ptrace_access_check`, which requires the reader's effective set to be a superset
of the target's **permitted** set. NixOS's own Plasma module ships
`security.wrappers.kwin_wayland = { capabilities = "cap_sys_nice+ep"; }`, so KWin holds a capability
and the host — which must stay uncapped, because a capability is exactly what makes it
unidentifiable to KWin (v0.27.0, above) — gets `EACCES`. The two traps compose: the name *needs*
`exe` because nixpkgs wrapped the binary, and `exe` is *denied* because NixOS capped it. Detection
went straight back to `ActiveKind::None`, `wayland` to `-`, and every connect to
`no usable compositor`. It presents identically to the v0.27.0 bug, which is why a box that had been
worked around with a decoy process broke again the moment the decoy was removed.

Name resolution now falls through to `argv[0]` (`/proc/<pid>/cmdline`) when the kernel refuses `exe`.
That reads correctly for the same reason `ps` does: make-wrapper's wrapper `exec -a "$0"`s the hidden
binary, so `argv[0]` survives the decoration `comm` does not. Measured on Linux 6.x against a capped
target, for a file capability and for the ambient form `security.wrappers` uses, identically: the
`/proc/<pid>` directory keeps its real owner (so the uid filter was never the problem), `comm` and
`cmdline` stay readable, and only `exe` fails. `argv[0]` is consulted **last** and never overrides a
readable `exe` — it is the process's own claim about itself, and a same-uid process can set it to
anything; the worst a spoof achieves is aiming detection at a backend that then fails its own
availability probe. The `comm` fast path is still one read for every ordinary distro.

Also reached by the same rung: `gamescope` carries `cap_sys_nice` on a number of distros, so a
*wrapped and capped* gamescope was equally invisible to the foreign-gamescope probe.

### Game Mode on Nobara — the WSI opt-out never reached the games

🛑 **v0.27.0's fix for the distro Vulkan WSI layer was clobbered by the session script, so games ran
on a black screen** while the host's own log claimed the layer had been disabled. Steam Big Picture
came up, showed the right mode, showed the perf overlay — and then every game played sound and took
input over a black picture, with no error on either side.

The layer (`VkLayer_FROG_gamescope_wsi`) ships with the *distro's* gamescope and speaks its
`gamescope_swapchain` protocol; ours disagrees, so the compositor rejects the client's
`swapchain_feedback` and kills it. v0.27.0 turned the layer off with `ENABLE_GAMESCOPE_WSI=0` on the
session unit. `gamescope-session-plus` then runs an unconditional `export ENABLE_GAMESCOPE_WSI=1`
near the top of the script — before it launches anything — so the opt-out survived exactly as long
as it took the script to start, and every process the session spawned got the layer back. Nothing
looked wrong because the casualty is Vulkan clients specifically: Steam's own UI is not one.

The opt-out is now `DISABLE_GAMESCOPE_WSI=1` as well. The Vulkan loader reads an implicit layer's
two manifest knobs in a fixed order: `enable_environment` must equal `"1"` to switch the layer on,
and `disable_environment` is then consulted last and wins on **presence alone**, at any value. The
session script never mentions that second variable, so it is the one that survives. Both spellings
go out, on the transient unit and on the box's own session drop-in.

### punktfunk-gamescope `+pfhdr6` — a NO_FOCUS window can no longer steal the composite

🛑 **A mapped-but-unpainted window carrying `GAMESCOPE_NO_FOCUS=1` could win gamescope's focus
selection and turn the composite — and the stream fed from it — black while every health signal
stayed green.** Bazzite's hhd-ui (Handheld Daemon overlay) sets that atom once at init, stamps
Steam's appid, and crash-loops under a headless takeover; each respawn remapped a fullscreen black
window that steamcompmgr then chose over Big Picture (observed on a Bazzite box: client stats
happily decoding 60 fps at 0.1 Mb/s of black; killing hhd-ui restored the picture instantly). No
gamescope — upstream or Bazzite's fork — ever consumed the atom; its setters (hhd-ui, MangoHud)
show and hide via the `STEAM_OVERLAY` protocol and rely on never being focusable. Patch 0008 wires
`GAMESCOPE_NO_FOCUS` exactly like `GAMESCOPE_EXTERNAL_OVERLAY` (read at map, PropertyNotify-tracked,
skipped by both focus-candidate collectors) without touching compositing or `appID`. Banner
`+pfhdr5` → `+pfhdr6`; no new capability — the bump is so a field box's banner tells the two
behaviors apart.

### Linux capture — the truncated first attempt no longer latches sticky downgrades

🛑 **The pipeline retry loop's deliberately short (2.5 s) first-frame attempt could permanently
downgrade the whole host process.** On expiry, the portal capturer's timeout diagnosis latched
whichever offer it implicated — HDR capture off (per source), the raw-dmabuf offer off, the
EGL→CUDA offer off — as if the compositor had refused it, when the budget was truncated by design
and a gamescope cold start routinely needs longer before delivering anything. One lost race at
connect then pinned every later session to SDR and/or CPU capture until the host restarted. The
truncated attempt is now declared provisional end to end
(`Capturer::next_frame_within_provisional`): its expiry names the same suspect in the error text
but latches nothing; only the full-length attempts that follow hand down negotiation verdicts. The
classification is a pure function with tests
(`pf_capture::linux::first_frame_timeout_tests`).

### Windows host — an idle box can sleep again (virtual-mic stream idle-stop)

🛑 **Installing the host blocked system sleep forever, client connected or not.** The
host-lifetime mic pump kept a WASAPI render stream RUNNING on the virtual-mic device
(typically the Steam Streaming Microphone), writing silence 24/7 — and any running stream makes
the Windows audio stack hold a kernel power request ("An audio stream is currently in use" in
`powercfg /requests`, attributed to that device) that vetoes sleep. The render loop now stops
the stream (`IAudioClient::Stop`; the client stays initialized and the mic *endpoint* keeps
existing for apps to bind) after 10 s of silence-only output and resumes on the next mic frame
within one device period — below the jitter buffer's prime depth, so nothing is audible.
Streaming sessions still hold the box awake through their own `PowerRequest` assertions, as
before. New knob: `PUNKTFUNK_MIC_ALWAYS_ON=1` restores the old always-running stream in case a
third-party virtual audio driver misbehaves while its render side is paused.

### Windows host — audio no longer costs local-game frame time

🛑 **The host could tank a locally-played game's frame lows** (field-reported 2026-08-12:
Helldivers 2 at 1% lows of 2–5 FPS, cured by uninstalling). Two mechanisms, both fixed:

- **The minted-endpoint retry storm.** The virtual-mic resolve ran a FULL provisioning pass on
  every reopen with no cooldown, no in-flight guard, and no give-up — and the pass reached
  `UpdateDriverForPlugAndPlayDevicesW` even over an already-existing devnode. On a box where
  minting cannot converge, the pump's reopen backoff (capped 60 s) turned that into a SetupAPI
  sweep + PnP driver re-bind + default-device writes roughly once a minute, forever — each
  raising the system-wide device-change broadcast games service by rebuilding their audio
  graphs. Provisioning now short-circuits to a no-PnP fast path while the minted devices are
  healthy, waits on an in-flight pass instead of racing a second one, honours the 60 s retry
  cooldown from the blocking path too, and stops for the host lifetime after five unlatched
  passes (a service restart re-arms minting).
- **Session tuning never reverted.** The first streaming session put the whole host process at
  HIGH priority class with a 1 ms global timer (`timeBeginPeriod`) and DWM MMCSS, documented as
  "reverts at process exit" — but the host is a 24/7 service, so after one stream it competed
  at HIGH priority against whatever the user played locally, forever. The process-wide tuning
  is now refcounted across the hot stream threads and reverts when the last one exits
  (= session teardown), the same lifetime the per-thread MMCSS effects already ride.

### Debian 13 is a supported target, and `punktfunk-gamescope` reaches apt for the first time

🛑 **The `punktfunk-gamescope` .deb had never been published — not once, in any release.** It was
built inside the host job's Ubuntu 24.04 image, where it cannot build: our pin vendors wlroots
0.19.3, which floors `wayland-server` at 1.23.1, and noble ships 1.22.0 (it also has no
`libxcb-errors-dev` and only libdisplay-info 0.1.1). Every rung of that path was a `::warning::`
returning 0, and the one hard gate ran last by design so good artifacts still shipped — so
**v0.26.0 and v0.27.0 both released with the package missing** while the release notes and
docs-site told Debian/Ubuntu users to `apt install` it. The same tag shipped it fine for Arch,
Fedora 44 and Bazzite; apt was the only platform affected.

It now has its own job on **Debian 13** (`ci/gamescope-trixie.Dockerfile`), the oldest apt base the
tree configures on. One package serves Debian 13 **and** Ubuntu 26.04 — verified by installing and
running it on both — because the build additionally vendors libdisplay-info
(`build-punktfunk-gamescope.sh --extra-fallback libdisplay-info`, opt-in so the Arch/Fedora/nix
outputs are unchanged): linked against the distro copy it would demand `libdisplay-info2` on trixie,
which Ubuntu 26.04 does not have (it carries `libdisplay-info3`). **Ubuntu 24.04 gets no gamescope
package** — its wayland is too old to run one, however it is built.

⭐ **Debian 13 is now a documented, CI-tested host target** ([docs](https://docs.punktfunk.unom.io/docs/debian)).
It required no packaging change: the host .deb's glibc-2.39 floor and bundled FFmpeg already made
it installable, and it had been working for a long time while docs-site said Debian was unsupported
and unverified. The desktop **client** remains Ubuntu-26.04-only (built there, floors at
`libc6 >= 2.43`; Debian 13 has 2.41).

⚠ **Cinnamon (Linux Mint, LMDE) cannot host a virtual display**, and compositor detection now says
so instead of advising a `PUNKTFUNK_COMPOSITOR` value that cannot help. Muffin forked from Mutter
3.36: `org.cinnamon.Muffin.ScreenCast` has only `RecordMonitor`/`RecordWindow`, never
`RecordVirtual`, and `xdg-desktop-portal-xapp` implements no ScreenCast at all. The error names the
route that does work on those boxes — a headless gamescope, which needs no desktop compositor.

New CI job **`smoke-install`** installs every published package from the registry in pristine
`ubuntu:24.04`, `ubuntu:26.04` and `debian:trixie` images and asserts the version served is the one
the run just built. Nothing in `deb.yml` had ever installed a package it produced, which is how
both facts above survived for so long.

### 🛑 The six built-in library scanners become plugins (M6/WP6.4 — breaking)

The host no longer scans any launcher. `library/{steam,epic,gog,heroic,lutris,xbox}.rs` and the
`scanner_defs()` table are **gone**; `GET /library/scanners` now lists exactly what the operator
installed, every row `origin: "plugin"`. This ends the migration whose bridge half shipped in
v0.26.0 — the plugins have been published and index-pinned since 2026-08-08, so the replacement has
been in the field for the whole bridge window.

⚠ **The upgrade note is the whole of it: a host with no library plugins installed has an empty
grid.** The console's one-click install per source is unchanged and still never auto-installs.

⭐ **There is no migration, by construction, and that is why this could be a deletion rather than a
rewrite.** A plugin *claims* its store (D2), and a claimed entry surfaces under the same
deterministic `<store>:<external_id>` id the scanner used to produce. Entry ids, GameStream FNV-1a
app ids, client art caches, Moonlight pins, the per-source toggles and the per-entry hides all key
on that id and **none of them move**. `library-scanners.json` keeps its name, shape and contents —
an operator who had `steam` off still has it off.

Kept deliberately:

- **`launch.rs` in full.** Launch is host-owned by design (D1): a plugin publishes a validated
  value, the host builds the command, so every typed kind survives. `xbox_pfn()` **moved here** out
  of the deleted `xbox.rs` — resolving a package Identity to its PackageFamilyName needs
  `AppRepository` enumeration, readable by the host (LocalSystem) and **denied to the plugin runner**
  (LocalService). That measured asymmetry is the entire reason the `xbox` launch kind exists, so the
  resolver is launch vocabulary, not scanner vocabulary.
- **`SourceOrigin::Builtin`.** No host build emits it any more, but the console ships as its own
  package and drives an N-1 host that still does, so the variant stays in the schema.
- **A store-label table**, so a source row does not rename itself from "Steam" to `steam` the day
  its plugin takes over.

Removed with the scanners: the background cover-art warmer and its on-disk cache (they existed only
for GOG and Xbox, the two sources that had to ask a network catalog what a cover was — a plugin
resolves art while it scans), the legacy `steam:` branch of the art proxy, and `GameMeta::pc()`.

### Mutter monitor rebuilds are serialized end to end — the two-client chain no longer kills GNOME

🛑 **Chaining two clients through a kept (keep-alive) Mutter display segfaulted gnome-shell in
`meta_monitor_manager_rebuild` (libmutter-18) and took the whole desktop down**; every later session
then failed `RemoteDesktop.CreateSession: ServiceUnknown` until GDM restarted, so the client just sat
black. ⭐ **A/B'd on .21 during this release's validation: byte-identical on the released 0.27.0 and
on the 0.28.0 RC — it was never a regression, the trigger had been there all along.**

`TOPOLOGY_LOCK` already serialized every topology-mutating D-Bus call, but two gaps let Mutter's
*rebuilds* overlap:

- **Teardown was fire-and-forget.** `StopGuard::drop` set a flag and returned; the session thread
  only noticed on its ≤200 ms park tick. The dead-reuse path (reused kept display dead on first
  frame → `mark_failed` → re-create) therefore issued its fresh `RecordVirtual` with the doomed
  monitor's removal still pending — the fresh session could even win the lock *before* the old
  thread had woken to take it, adding a monitor while the dead one still stood. The drop now waits
  (bounded, 20 s) for the session thread to finish.
- **The lock was released while the shell was still rebuilding.** `Stop` / `RecordVirtual` /
  `ApplyMonitorsConfig` all return mid-rebuild, and an `APPLY_TEMPORARY` config auto-reverts
  asynchronously on top. Every locked mutation now ends with `settle_topology()` — poll
  `GetCurrentState` until a removed connector is actually gone and the config serial holds still
  across two consecutive reads — before the guard drops. Bounded at 4 s and best-effort (a read
  error means the shell is gone; a hotplug storm must not park sessions), degrading to exactly the
  old behaviour.

Cost when Mutter is already quiet: one confirming read plus one 150 ms recheck per setup/teardown.

### KWin ≤60 Hz — the virtual output's real size is finally read back

🛑 **A 4K60 GameStream session captured 1920×1080.** `create()` asked KWin for 3840×2160, KWin built
something else, and nothing compared the two: only the >60 Hz arm read anything back, and it gets
that for free because it installs a custom mode. The ≤60 Hz arm installs nothing, which is exactly
why it never noticed.

⚠ **The line that should have caught it was the one that hid it.** `spawn_vout` returns a node id,
never a size, so `tracing::info!(node_id, width, height, "KWin virtual output ready")` was echoing
the **request** — the field log stated 3840×2160 while the output was 1080p, and the first pass at
diagnosing this was done against that number. It now logs `requested_w`/`requested_h` with the
readback beneath it.

### Apple/Android audio — the de-prime fuse counted callbacks, not time

🛑 **An iPad gave up on its audio ring three times sooner than a Mac**, which is the residual Apple
jitter that survived both the PLC fix (#82) and the jitter-policy fix (#111).
`JitterTuning::deprime_after` counted **callbacks**, and a callback is not a unit of time: the same
`4` was ~44 ms of starvation slack on a Mac's ~11 ms quantum and **20 ms on iOS**, whose session asks
for a short IO buffer — the shortest fuse of any client, on the one with the burstiest transport. A
100 ms Wi-Fi delivery stall therefore de-primed the Apple ring on every bunching cycle while the
identical policy rode it out everywhere else. It is now **`deprime_ms`**, measured in starved audio,
with a `MIN_DEPRIME_CALLBACKS` floor so a large-quantum device keeps real hysteresis instead of
de-priming on the first short read. ⚠ **Android was latently exposed too** — AAudio's low-latency
burst is ~4–5 ms, so its `5` was also ~20 ms.

Measured by driving the real policy through a simulated link (100 ms stall / 5 s, −30 ppm, 10 min)
at a 5 ms quantum: **120 audible gaps and 690 ms of dead air before, 2 gaps and 60 ms after.**

### Console — "Update all" on the plugins screen

The Installed tab could only update one plugin at a time, one dialog and one watched job each. The
bulk action now sits beside the list it acts on, plus a count badge on the Installed tab trigger
(Browse is the tab the page opens on, and a control nobody passes is a control nobody finds).
⚠ **The host takes ONE package operation at a time** — 409 otherwise, because bun operations share a
lockfile and a `node_modules` tree — so this is a queue the console works through job by job, driven
by each job settling rather than by a timer, carrying its own copy of what is left.

### Android — the in-stream mic control leaves the stream overlay

The mic element sat in the top-right of every stream that opened a capture (a standing button on
touch, a Muted badge on TV). It is gone for now; the on-screen overlay UI being built will carry
mute as one of its controls. **Mute itself is untouched** — `micRunning`/`micMuted`/`setMicMuted`
still back the Select + Y chord, which is now the whole of the control, and `MicChordHint` is its
only on-screen feedback.

### ⚠ Flatpak — the currency wave's one loose end

🛑 **Every flatpak leg died after #193.** The dependency currency wave took skia-safe/skia-bindings
0.87.0 → 0.99.0 in `crates/pf-console-ui/Cargo.toml`, but `packaging/flatpak/io.unom.Punktfunk.yml`
still pinned the **0.87.0** prebuilt archive, so the build failed with
`no variant … named 'Default' found for enum 'SkPathFillType'` inside
`skia-bindings-0.99.0/src/defaults.rs`. Nothing in that message points at the manifest, so it reads
like a crate bug — it is not: `SKIA_BINARIES_URL: file://…` makes skia-bindings unpack the pinned
tarball verbatim, **including its `bindings.rs`**. Archive pinned to 0.99.0.
⇒ **If you bump `skia-safe`, bump the flatpak archive in the same commit.**

### Rust edition 2024 across the tree (MSRV floor 1.85)

The whole main workspace and `pf-vkhdr-layer` move to **edition 2024**; `[workspace.package]`
declares `edition = "2024"` and `rust-version = "1.85"`. The pinned toolchain did not move — only
the declared floor — but if you vendor or patch a workspace crate, 1.85 is now the minimum.

This is the safety half of the rust-safety programme's §8.4, not a tidy-up: in edition 2024
`std::env::set_var`/`remove_var` are **`unsafe fn`**, which converts an entire bug class from
invisible to counted. The environ data race the programme found the hard way lived in a file
containing zero occurrences of the word `unsafe`; every one of the 20 files that mutate the
environment now carries an `unsafe` block with a SAFETY comment naming the actual serialization
argument (a named lock, or a `--test-threads=1` contract, or single-threaded startup).

What a downstream integrator sees:

- The 13 crates that pinned `edition = "2021"` **literally** now inherit from the workspace. A root
  bump alone would have reached only the `edition.workspace = true` crates and left `pf-encode`,
  `pf-capture`, `pf-inject` and friends on 2021 while reading as complete.
- 148 `#[no_mangle]` → `#[unsafe(no_mangle)]` (83 of them in `abi.rs`), and 12 bare `extern` blocks
  → `unsafe extern`. Done textually across **all** `cfg` branches, because 44% of the host's unsafe
  is Windows-only and a one-platform `cargo fix` silently misses it.
- `gen` is a reserved keyword in 2024, so `pf-vdisplay`'s generation stamps and the WinUI shell's
  animation counters rename `gen` → `generation`. **Internal identifiers only — no serde field, no
  wire name and no API surface changed.**
- The four **vendored** crates (`fec-rs`, `cros-codecs`, `usbip-sim`, the patched `ndk`) stay on
  2021 deliberately: upstream code stays pristine.

### No punktfunk process holds REALTIME GPU priority by default (⚠ default change)

🛑 **Both of our REALTIME GPU-scheduling levers were convicted of *generating* the metronomic
capture-stall class the stall program has chased for weeks** — compose-silence holes of 150–800 ms
in which ETW shows no process presenting while the GPU stays responsive. From the RX 9070 XT field
A/B: the virtual-display driver's `IddCxSetRealtimeGPUPriority` raise beat at ~1.75–1.78 s, and the
host's `HIGH → REALTIME` auto-upgrade beat at ~3.58 s in the sessions where it promoted. Disabling
each removed its own metronome; pinning both left the stall rate at the clean-run baseline.

Neither period matches **any** punktfunk clock — the full periodic-actor census (driver drain,
16 ms `E_PENDING` wait, 33 ms cursor poll, 3 s watchdog; host descriptor poll, VRAM gate, exclusive
re-assert, pinger, stats, phase-lock, LTR marks) has nothing in the 1.69–2.29 s band, and the period
even differs by *which* of our processes holds REALTIME. The periodicity is emergent from holding an
unreachable-priority queue against the WDDM scheduler on this AMD family. There is therefore no
punktfunk cadence to fix; the fix is to stop holding REALTIME, which is also canonical parity — no
shipping IDD raises it, and HIGH is the class that delivered the original encode win.

- **Driver:** the old `PFVD_NO_RT_GPU` opt-**out** (default ON) becomes the **`PFVD_RT_GPU` ladder,
  default OFF on every vendor**. Unset = no raise = canonical IDD behaviour.
- **Host:** the `pf-frame` auto-gate no longer upgrades to REALTIME. `PUNKTFUNK_GPU_PRIORITY_CLASS`
  still pins a class explicitly.

### The reanchor gate learns gap WIDTH — two new C ABI exports (ABI 19)

🛑 **Every unrecoverable loss armed the client's freeze gate twice**, and on AMD hosts the second arm
re-froze a stream that had already healed. The two signals are the frame-index gap (instant, and what
fires the RFI) and the reassembler ageing the lost frame into `frames_dropped` (~120 ms later, which
re-armed unconditionally). An LTR-RFI recovery anchor lands in ~60 ms — *between* them — so the stale
climb re-froze a bit-exact-healed picture, the host swallowed the re-ask as an RFI echo, and the
stream stayed frozen until the overdue backstop extracted a full IDR. This is the field
"H.265 freezes on every loss, AV1 fine" signature: AMF is the only LTR-RFI backend, and the slower
IDR path usually lands after the climb and dodged the race.

The gap-arm now **pre-credits** the climb it knows is coming (`ReanchorGate::arm_expecting_drops`;
the credit expires after `DROP_CREDIT_WINDOW` so a straggler-filled gap cannot mask a later real
loss), and `poll()` consumes credited climbs instead of re-arming. Plumbed through every embedder:
`pf-client-core`'s session pump, Android's sync and async loops (`note_frame_index` now returns the
gap width), and the Swift client via the two new exports —
**`punktfunk_connection_note_frame_index_ex`** and **`punktfunk_reanchor_gate_arm_expecting_drops`**.
Both originals keep their signatures and their behaviour, so an embedder that adopts neither is
unchanged; it simply keeps the race. Nothing new goes on the wire.

### ⚠ `punktfunk_send_input` now rejects an unrecognized event kind

`punktfunk_send_input` and `punktfunk_connection_send_input` **validate `ev->kind` before forming a
reference** and return `InvalidArg` for a value that is not a recognized `InputKind`. Previously the
byte was transmuted into an enum, which is UB for an out-of-range discriminant — a caller passing an
uninitialized or garbage `kind` had undefined behaviour rather than an error return. The safety
contract in the header relaxes correspondingly: `ev` need only point to *a readable
`InputEvent`-sized allocation*, not to an already-valid `InputEvent`. **If you build an event by
zeroing a struct and setting fields, nothing changes.** If you relied on an unknown kind being
silently forwarded, it is now an error.

### Linux hosts stream pad audio — the per-pad PipeWire sink (WP3)

The 0xD1 per-gamepad audio plane (DualSense haptics + speaker) was **Windows-host-only**:
`host_cap()` answered false everywhere else and `spawn()` was a stub, so a tier-A Android client
against a Linux host negotiated the capability off and fell back to wire rumble. The downstream
machinery — framer, silence gate, lanes, 0xD1 send — was already capture-agnostic; only the capturer
was WASAPI.

Linux hosts now mint **one PipeWire Audio/Sink node per DualSense-family pad**, carrying the identity
the game-side matchers read (ALSA-style `node.name` with the pad's pairing MAC, description
"Wireless Controller", bus/vendor/product/form-factor proplist, per-pad serial), 4-channel F32
48 kHz FL/FR/RL/RR, claiming no default sink, `priority.session 50`. The `process()` callback *is*
the capture. `host_cap()` on Linux = client asked **and** `PUNKTFUNK_PAD_AUDIO` **and** a reachable
PipeWire socket; the sink is minted lazily in the streamer thread. `PUNKTFUNK_PAD_SINK_NAME` /
`_DESC` override the strings for field debugging (`{pad}`/`{mac}` expand).
`PUNKTFUNK_PAD_AUDIO{,_SLOTS}` are no longer documented as Windows-only. Verified on a Bazzite 44
host: identity served through `pipewire-pulse`, rear-pair voice-coil tone captured bit-exact over
both the native and Pulse legs. The Linux sink speaks GE-Proton's AUX0–3 channel shape.

### Wake-on-LAN now works over Wi-Fi (WoWLAN)

The host's arming check asked **`ethtool`** about every NIC, which is the wrong question for
wireless: the magic-packet trigger lives in nl80211's WoWLAN state, and most Wi-Fi drivers print
`Wake-on: d` whether or not it is armed. An armed Wi-Fi host was therefore reported as *not* armed
and handed an `ethtool -s wlan0 wol g` its driver rejects. A NIC with an nl80211 phy
(`/sys/class/net/<i>/phy80211`) is now asked `iw phy <phy> wowlan show`, and the warning carries
WoWLAN-correct guidance (`iw … wowlan enable magic-packet`, plus the NetworkManager
`802-11-wireless.wake-on-wlan magic` that survives a reconnect). Two fallbacks for when `iw` cannot
answer: a **positive** ethtool reading counts (brcmfmac and friends do report there), a negative one
never does, and sysfs `device/power/wakeup` reading `disabled` is conclusive in the negative.

The **client sender** now emits from a socket bound to each non-loopback interface's own address
instead of leaving the choice to the routing table. A station in WoWLAN sleep stays associated and
its AP buffers broadcast frames until the next DTIM beacon — but only if the datagram reaches the
wireless segment at all, and with a VPN or mesh interface holding the default route
`255.255.255.255` never did. A failed bind falls back to the routed socket, so no segment is lost.

### Zero-copy capture withholds buffers until the encoder has finished reading

🛑 **Gamescope streams could tear pink at 120 fps.** The raw-dmabuf passthrough handed the SPA buffer
back to gamescope at `.process` return while the encode thread had not yet imported — let alone read
— its dmabuf, and nothing ordered the producer's writes against the consumer's read (there is no
explicit sync, and the implicit-fence wait measures `NoFence` on every compositor × vendor pairing we
have). On the direct-VCN arms (native NV12, RGB-direct EFC) the captured buffer *is* the encode
source for the whole 2-deep encode ring plus the phase-lock hold, so at 120 fps gamescope cycles back
into the buffer mid-encode: luma/chroma desync (the magenta tint) plus block corruption propagating
through the P-chain until the next intra. KDE sessions were clean because `cursor_blend` routes them
to the compute-CSC copy arm, whose read window is microseconds.

A published passthrough frame now carries a **`FrameHold`**, and the buffer rejoins the producer's
pool only when the last clone drops. The Vulkan encoder clones the hold into the ring slot at submit
and releases it when that slot's fence retires, extending "the producer must not rewrite this" across
exactly the GPU read. The host loop's repeat path is fixed by the same mechanism.

### Bazzite Game Mode no longer mirrors the box's screen (⚠ shipped-template default)

🛑 **Our own template caused it.** `packaging/bazzite/host.env` set
`PUNKTFUNK_GAMESCOPE_ATTACH=1`, and every install path — rpm, deb, Arch, nix — ships that file as
`/usr/share/punktfunk/host.env.bazzite` with the docs telling people to copy it verbatim. So the
*recommended* Bazzite setup turned the attach override on for everyone.

That override is **rung 2** of `pick_gamescope_mode`, above `dedicated_launch` at rung 3. The rung
comment calls the operator overrides a debug/CI escape hatch — correct, but we were shipping one as
a distro default, so on a Bazzite box the managed takeover and the dedicated game session were both
unreachable, and a game launched from a client's library could not get a session of its own. With a
physical display connected, attach then takes the `physical_display_connected()` arm and streams the
box's own head at the box's own mode: the mirror the field report described.

The template now forces nothing and lets per-connect detection answer, which on a box with
`gamescope-session-plus` is MANAGED. Attach stays available, documented as the opt-in it is, with the
mirror and the dedicated-session cost stated.

### `edid_lock` — pin AMD connector EDID emulation while streaming (EXPERIMENTAL)

A new display-policy axis beside `ddc_power_off` / `pnp_disable_monitors`, orthogonal to presets and
**off by default**. At the first Exclusive isolate the host pins each occupied AMD connector's live
EDID plus `ADL_EMUL_MODE_ALWAYS` — the software equivalent of an HPD-holding dummy plug — **before**
the physicals deactivate, so an awake sink answers its own live-EDID read; last-member teardown
unlocks. It targets the standby-sink stall class at its source: with emulation pinned the kernel-mode
driver stops servicing the sleeping sink's HPD/DDC/link.

Pinned emulation outlives the process, so a crash journal (`edid-lock-active.json`) unlocks on the
next host start, mirroring the `pnp_disable_monitors` recovery. Inert without an AMD driver
(`atiadlxx.dll` absent) and on non-Windows. The ADL FFI lives once in `pf_win_display::adl_emul`, so
the new **`display-disturb adl-emul`** probe and the host exercise byte-identical driver calls. The
console shows the toggle **only** when the GPU inventory lists an AMD adapter — a toggle that can
never act is exactly the "saved, then did nothing" trap the enforced-axes list exists to prevent.

### An over-declared stream level no longer demotes native Vulkan decode

A HEVC stream whose declared level exceeds what the device advertises is now treated as a **clamp**
rather than a refusal, so native Vulkan decode survives an encoder that over-declares. The Windows
client legs also build again: the edition-2024 `clients/session` binary could not compile on Windows,
and `pf-presenter` now spells `MAKEINTRESOURCE(1)` as `ptr::without_provenance` — clippy 1.96's
`manual_dangling_ptr` reads the integer-ordinal cast as a dangling pointer and fails the Windows
`-D warnings` gate, which was masked on main by the client bins failing to build first.

### Library, launcher marks and plugin-kit 0.4.1

- **Launcher tiles carry their launcher's mark.** A brand **token** goes on the wire (`steam`,
  `heroic` — never bytes, never a URL) and each client draws the vector it already ships. `icon`
  joins `GameEntry` and `CustomEntry` in the management API, and is hand-settable for the same
  reason `role` is: an operator's own "Steam" tile should be able to look like one.
- **`@punktfunk/plugin-kit` 0.4.1 publishes the `icon` field.** The kit had shipped the field
  without a version bump, so no plugin could name its mark.
- **Every pinned card gets a library, and it launches with that card's profile.**

### Decky: one library shortcut, not one per boot

🛑 A boot race minted a **new** Steam library shortcut on every plugin load, so the library
accumulated duplicates indefinitely. Fixed, and the plugin no longer toasts on every launch and every
failed panel refresh.

### A stats tier picked between streams now applies without a restart

The console latched the stats tier at stream start, so a tier chosen between two streams reached
nothing until the app was restarted.

### Miri, sanitizers, and the lint ratchets

- **Miri** now interprets the FFI-free leaf crates, one of them at **MSVC layout**. It immediately
  earned its place: `pf-driver-proto`'s legacy-`AddRequest` test read a `[u8; 40]` (align 1) through
  `bytemuck::from_bytes`, which takes a *reference into* the buffer and panics unless that buffer
  happens to be 8-aligned — as a stack array usually is. Now `pod_read_unaligned`.
- **ASAN + LSAN over the C ABI boundary**: a `c-abi-asan` job in `audit.yml` runs the harness under
  both, weekly and on demand, behind a `PF_SAN` sanitizer gate.
- **Two soundness fixes**: `InputKind` is validated before a `&InputEvent` is formed (above), and the
  Windows `TOKEN_USER` buffer is properly aligned with `EqualSid` made to fail closed.
- **WP4**: `AvFrame`/`AvSwsContext` are RAII across all three libav backends in `pf-encode`.
- **The lint ratchets (WP2b + WP2c)**: crate-level gaps closed, the unsafe lints hoisted into the
  workspace tables across all three workspaces, and three blocking unsafe-hygiene grep gates in
  `ci.yml`. The two bindings-only `sys` crates are explicitly exempted from the hoisted deny.

### Dependencies, audit and licences

The 2026-08-13 dependency sweep, acted on in full:

- **Security:** `event-listener` 5.4.1 → 5.4.2 (RUSTSEC-2026-0221, unsound `Send`/`Sync`);
  `spin` 0.9.8 → 0.9.9 (0.9.8 is **yanked** and was genuinely compiled); `wayland-scanner`
  0.31.10 → 0.31.11, which moves `quick-xml` 0.39 → 0.41 and lets **both** RUSTSEC-2026-0194/0195
  ignores be deleted rather than left as permanent exceptions. Only RUSTSEC-2023-0071 (`rsa` Marvin,
  still unfixed upstream) remains.
- ⚠ **Two CI gates that scanned nothing.** `cargo audit` only ever reads the **root** `Cargo.lock`,
  so the drivers lock was in the job's `paths:` filter while being ignored; all four secondary
  workspaces now get an explicit `--file`. And `packaging/windows/pf-vkhdr-layer` had **no lockfile
  at all** while shipping as a DLL in the host installer, so neither cargo-audit nor cargo-about had
  ever seen it — lockfile generated, committed, and added to `paths:`. `audit.toml` now also says out
  loud that `cargo audit` reports unsoundness as a *warning* and the job fails only on
  vulnerabilities, which is why the `event-listener` advisory sat unnoticed.
- **13 unused dependencies removed from `punktfunk-host`** (the Wayland stack, xkbcommon, reis,
  khronos-egl, ash, usbip-sim, parking_lot, bytemuck) — the code moved to `pf-inject`/`pf-zerocopy`
  in the subsystem extraction and those crates declare them; only the manifest entries and their
  now-false comments stayed. Plus unused `bytes`, `anyhow`, `tracing`, `serde` in five other crates,
  and the high-level `wdk` crate from all five driver crates.
- **Latent breakage fixed** — crates that compiled only through feature unification now declare what
  they use: `pf-inject` (`tokio` `macros`), `pf-capture` (`tokio` `sync`), `pf-client-core` (two
  windows-rs headers). `pf-console-ui` took `pf-client-core` **without** `default-features = false`,
  unlike every other consumer; that default compiles the vendored PyroWave C++, which is fatal on
  Windows ARM64 and only safe today because that leg passes `--no-default-features`.
- **Licences:** `ring`'s `OpenSSL` exception and its per-crate acceptance are retired now that ring
  is gone. THIRD-PARTY-NOTICES regenerated — 601 → 580 → 582 crates across the sweep.

### The dependency currency wave — thirteen majors, and a silently-disabled AES path

The currency half the sweep above deferred, landed as one wave. Most of it is version hygiene, but
one item is a real defect and one changes a build flag you may be carrying.

🛑 **Hardware AES was silently off on every Android build.** `aes` 0.8 enabled the ARMv8 AES
instructions on aarch64 only behind `--cfg aes_armv8`, and `polyval` 0.6 gated its PMULL GHASH path
behind `--cfg polyval_armv8` — both set in `.cargo/config.toml`. A `RUSTFLAGS` environment variable
**overrides config rustflags entirely**, and `cargo-ndk` sets its own for every Android build, so
those two cfgs vanished and the per-packet decrypt path fell back to **software AES**. `aes` 0.9
runtime-detects through `cpufeatures` and `polyval` 0.7 selects its armv8 backend by `target_arch`,
so neither cfg exists any more and the flags are **deleted** from `.cargo/config.toml`. If you carry
a fork of that file, drop them: they are dead, and keeping them costs nothing but confusion.

- **The RustCrypto family moves as ONE change** — `aes` 0.9, `aes-gcm` 0.11, `sha2` 0.11, `hmac` 0.13,
  `cbc` 0.2, `chacha20poly1305` 0.11. They share the `crypto-common`/`digest` traits, so a partial
  bump strands crates on trait generations that cannot interoperate. The API generation forces
  `AeadInPlace` → `AeadInOut` (`{encrypt,decrypt}_inout_detached` over `InOutBuf`), `generic-array` →
  `hybrid-array`, `Mac::new_from_slice` → `KeyInit::new_from_slice`, and the `BlockCipher*`/
  `BlockMode*` renames. ⚠ **The GameStream wire formats are untouched** — AES-128-ECB no-padding, the
  CBC audio path and the GCM control-stream seal all keep their exact byte behaviour; only type
  plumbing moved.
- ⚠ **`rsa` 0.9 cannot come along**: it is built on `digest` 0.10, whose 0.11 line is release-candidate
  only — not something the Moonlight pairing ceremony should ride. The three sites where a digest is
  an `rsa` *type parameter* now name `rsa::sha2::Sha256` explicitly; everything else is on sha2 0.11.
- **`skia-safe` 0.87 → 0.99** in `pf-console-ui` — twelve releases carrying Skia milestones 140–150.
  Only three reach us: m143 **deleted `SkPath`'s mutating API** (geometry is built through
  `PathBuilder` and frozen with `snapshot()`/`detach()`; 34 errors over eight call sites), 0.93
  deprecated `gradient_shader` for `gradient` (a warning, but the gate runs `-D warnings`), and the
  Vulkan surface path came through untouched.
- **`wasapi` 0.23 → 0.24.** ⭐ 0.24 fixes upstream the dangling-`PCWSTR` bug this tree routes around
  in five places — `DeviceEnumerator::get_device` built its argument as
  `PCWSTR::from_raw(HSTRING::from(id).as_ptr())`, dropping the `HSTRING` at the end of that statement
  so `GetDevice` read freed memory. The five comments asserting that bug in the present tense are
  corrected. ⚠ **The workarounds stay** — `open_wasapi_device` is still the one resolution path whose
  errors name the endpoint id, and `device_by_id` additionally filters to ACTIVE endpoints, which the
  crate's `get_device` does not. Removing them would be a behaviour change, not currency.
- **Ten more**: `jni` 0.21 → 0.22 (the Android bridge), `rcgen` 0.13 → 0.14, `rand` 0.8 → 0.9 (the
  host was the last crate on the old major), `base64` 0.22 → 0.23, `x509-parser` 0.16 → 0.18 — which
  takes `thiserror` 1.0 out of the host graph entirely — `libloading` 0.8 → 0.9 across the five crates
  that `dlopen`, `mdns-sd` 0.20 → 0.21 with `if-addrs` 0.13 → 0.15 (together, they share types),
  `x11rb` 0.13 → 0.14, `xkbcommon` 0.8 → 0.9, `reis` 0.6.1 → 0.7.1, `windows-service` 0.7 → 0.8
  (removing the last `windows-sys` 0.52 in the tree), `android_logger` 0.14 → 0.15, and `criterion`
  0.5 → 0.8 (dev-only, benches).
- **New test coverage**: the TLS 1.2 Moonlight handshake, and the post-quantum group is pinned by a
  test so a backend change cannot silently drop it.
- THIRD-PARTY-NOTICES regenerated across every client and the host for the wave.

### Documentation and the docs site

⚠ **`docs-site/public/openapi.json` had drifted far behind `api/openapi.json`** — it was stamped
`0.21.0` against the checked-in spec's `0.27.0`, and was missing five endpoints (`/library/hidden/{id}`, `/plugins/logs`, and all
three `/update/*` routes), so the published API reference described a host nobody was running. The
copy is a documented manual step (`cp api/openapi.json docs-site/public/openapi.json`) that nothing
in CI enforces, and it had simply been skipped. Re-synced for this release; the two files are now
byte-identical.

⚠ **It drifted again within the same release cycle** — the scanner-removal regen updated
`api/openapi.json` and not the docs-site copy, which is the failure mode repeating in miniature.
Re-synced a second time. **Until something gates it, treat `cp api/openapi.json
docs-site/public/openapi.json` as part of regenerating the spec, not a follow-up.**

### CI

- The C/C++ half of the build is cached and links with **mold**; the debug/release target caches no
  longer collide.
- `release.yml` folds into `apple.yml`, and the two Windows-client workflows consolidate into one.
- The web console builds **once per push** instead of once per packaging job.
- The `smoke-install` job (see the Debian section) installs every published package from the registry
  in pristine `ubuntu:24.04`, `ubuntu:26.04` and `debian:trixie` images and asserts the served
  version is the one the run just built.
- ⚠ Gate C counted **comments**: a comment that named the env mutators verbatim satisfied the gate it
  was documenting.

## v0.27.0

87 commits since v0.26.0.

### Versions

| | v0.26.0 | v0.27.0 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged |
| C ABI | 17 | **18** | `punktfunk_connection_next_rumble_cmd2` **added**; nothing removed or changed |
| Workspace crate dirs | 26 | **27** | `crates/punktfunk-encode-worker` (39 members; two `tools/` crates deliberately *excluded*) |
| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3) |
| Windows virtual-gamepad channel | 3 | **3** | unchanged — three `device_type`s added additively |
| Plugin index schema | 1 | **1** | unchanged |
| `api/openapi.json` | 0.25.0 | **0.25.0** | unchanged — no management-API edits this release |
| gamescope patch level (`+pfhdrN`) | 4 | **5** | 6 patches → 7 (the PipeWire use-after-free); `pkgrel` resets 3 → 1 |
| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.4** | unchanged |
| `@punktfunk/plugin-kit` | 0.4.0 | **0.4.0** | unchanged |

⚠ **`crates/pf-driver-proto` is no longer byte-identical to the previous release.** It was through
both v0.25.0 and v0.26.0, so if you ship the virtual-display driver or the gamepad channel and have
been skipping this crate, stop skipping it here. The change is purely additive — three `device_type`
constants, no field moved, no size changed.

### ⚠ Breaking changes

**None** for embedders or the wire. Every embedder, packager and plugin that works against v0.26.0
works against v0.27.0 unchanged; the C ABI moves, but by addition only (below).

Two things change shape for **packagers** and one **default** flips:

- **A second installed binary**, `punktfunk-encode-worker` — see the section below. It is the only
  file that may carry `cap_sys_nice=ep`, and it must be a separate file.
- **`PUNKTFUNK_XBOX_BACKEND` now defaults to `hid`** on Windows, so an Xbox pad is built as a real
  HID device rather than the XUSB companion. `=xusb` is the escape hatch.
- **NixOS `scripting.autoStart` now defaults ON**, matching every other packaging (detailed below).

### `punktfunk-encode-worker` — the GPU-priority capability moves off the host

0.26.0 left the PyroWave priority ladder wired and inert: it needs `CAP_SYS_NICE`, and 0.26.0-1
proved the host can never hold one — see **PyroWave on Linux — Wave 2**, PW1, under v0.26.0 below. A
capability-carrying process cannot be identified by KWin (`cap_ptrace_access_check` refuses
`/proc/<pid>/exe` to a reader whose effective set is not a superset of the target's **permitted**
set), so it never gets `zkde_screencast_unstable_v1` and every KDE desktop session dies. Neither
`prctl(PR_SET_DUMPABLE, 1)` nor systemd `AmbientCapabilities=` nor a NixOS `security.wrappers` entry
changes that — all three land the capability in the same permitted set.

The capability therefore moves to a process that fronts nothing. **`punktfunk-encode-worker`** is a
new workspace member and a new installed binary: it owns the priority-elevated Vulkan device for
PyroWave sessions, receives capture dmabufs over a `SOCK_SEQPACKET` pair from its parent, and returns
compressed access units. It connects to no compositor, no D-Bus and no network, so its
non-dumpability costs nothing and its blast radius is one socket to the host that spawned it.

🛑 **The invariant, for anyone packaging this:** the worker is a **separate file**. Never a hardlink
to `punktfunk-host` and never a subcommand of it — a shared inode shares the file capability, which
silently re-creates 0.26.0-1 on every KDE box. `punktfunk-host` carries no capability, on any
channel, ever.

- **The grants are re-targeted, not re-introduced.** Every channel that granted in 0.26.0-1 grants
  again, at the worker: Arch `.install` (`post_install` **and** `post_upgrade` — a replaced binary is
  a new inode), RPM `%caps(cap_sys_nice=ep)` in `%files` (never a `%post setcap`; this covers Fedora
  and Bazzite layering), the Bazzite sysext staging tree pre-`mksquashfs` (which does record
  `security.capability`), the deb `postinst`, the Deck installer, and NixOS
  `security.wrappers.punktfunk-encode-worker`. Every #136 host-side removal stays verbatim, including
  the sysext's host hard-fail.
- **The sysext assertion is amended, not removed** — host must be empty (hard fail), worker must
  carry **exactly** `cap_sys_nice=ep`. A *missing* worker capability is not an error: the grant is
  best-effort everywhere.
- **A new release-CI leg asserts the getcap matrix** on the built Arch package, the deb and the
  mounted sysext raw. The 0.26.0-1 lesson was "verify the package, never the board"; this is that,
  mechanized, and it is what would have caught the original break.
- **On NixOS the env override is load-bearing**, not a convenience: a file capability cannot live on
  a read-only store path, so the module wraps the worker and sets `PUNKTFUNK_ENCODE_WORKER` to the
  wrapper path in the unit. An ambient grant is fine *here* — the worker is not a KWin client. The
  host's `ExecStart` stays on the plain store path (the #136 fix stands).

**Fallback ladder — no rung can kill a negotiated session.** Binary not found → spawn failure →
handshake timeout → protocol or workspace-version mismatch → socket EOF mid-session all fall back to
the **in-process encoder exactly as today**, at default priority, with one warning. Host and worker
are different files now, so the version check is load-bearing rather than decorative; they ship
lockstep in every channel. The in-process path stays compiled and tested — it is the floor, not dead
code. `PYROWAVE_QUEUE_PRIORITY` keeps its 0.26.0 grammar and is now forwarded **explicitly** in the
handshake rather than read from the worker's environment, which is sanitized at spawn; one env var
still means one thing on both platforms.

### NixOS — session detection, module defaults, and a CI gate that was never running

🛑 **The host could not detect any graphical session on NixOS, at all.** The live-session probe
matched `/proc/<pid>/comm` exactly against `kwin_wayland` / `gamescope` / `gnome-shell` /
`Hyprland`. `comm` is the kernel's name for the **executed file**, truncated to 15 bytes — not
`argv[0]` — and nixpkgs wraps essentially every graphical binary: `wrapProgram` moves the real ELF
aside to `.<name>-wrapped` and installs a wrapper that `exec -a "$0"`s it. So the kernel reports
`.kwin_wayland-w` while `ps` and `pgrep -a` show a perfectly ordinary `kwin_wayland`, because they
read argv. Every probe answered `ActiveKind::None` on a running desktop, and nothing downstream
could recover: `wayland` logged as `-`, a correct `WAYLAND_DISPLAY` changed nothing, `Auto` returned
the *detected* backend so a live KWin already in `available()` was never chosen, and a
`PUNKTFUNK_COMPOSITOR` pin turned the miss into a hard error through `pinned_at_a_dead_session`.
sway and river survived by accident — nixpkgs' wrapper execs a binary still called `sway`.

Names are now resolved through `/proc/<pid>/exe`, whose file name is untruncated, with the nixpkgs
decoration stripped. Stripping requires **both** the leading `.` and a trailing `-wrapped`, so
KWin's own real `kwin_wayland_wrapper` binary keeps its name instead of collapsing into
`kwin_wayland` and handing the probe the parent's PID. The `comm` fast path is unchanged for every
ordinary distro — one read, no readlink — and no name that matched before can stop matching. Also
applied to the foreign-gamescope probe, which had the same defect.

**Module changes** (`services.punktfunk`):

- **`host.desktopSession`** *(new, default `false`)* — binds the host to `graphical-session.target`,
  the declarative form of the `punktfunk-host-desktop-session.conf` drop-in. Without it a
  Plasma/GNOME restart leaves the host holding a Wayland socket and portal D-Bus connection that
  died with the old compositor: it still listens, still answers, and every session after that fails
  at capture. Off by default because an appliance may never reach that target and would be left
  permanently stopped.
- ⚠ **`scripting.autoStart` now defaults ON** *(behaviour change)*, matching the deb `postinst` and
  RPM `%post`, which both `systemctl --global enable` the runner, and the sysext's baked-in
  `default.target.wants` symlink. It was opt-in here on the reasoning that the runner is inert until
  you add automation — untrue since the game-library scanners became plugins, so a NixOS host came
  up with an empty library and no obvious cause. Opt out with `scripting.autoStart = false` or
  `systemctl --user mask punktfunk-scripting`.
- **Three divergences from the shipped units, ported.** `punktfunk-web` gains
  `StartLimitIntervalSec=0` (without it, 5 starts / 10 s against `RestartSec=2` gives up permanently
  after ~10 s — exactly the window before the host's first `serve` writes the mgmt token, so a
  console enabled before the host's first run stayed dead) and `Restart=always` rather than
  `on-failure`. `punktfunk-scripting` gains the sandbox the deb/rpm unit has all along
  (`NoNewPrivileges`, `ProtectSystem=strict`, `ReadWritePaths=%h /tmp`, restricted address families,
  `PrivateTmp=no`) — it is the one unit that runs arbitrary operator TypeScript by design, and it
  had been running strictly less confined on NixOS than anywhere else.
- A **warning** when the host is enabled and `xdg.portal.enable` is not.

🛑 **`nix flake check` does not check `nixosModules`** — worth knowing for anyone maintaining a
flake. It forces the value and asserts it is a lambda taking an open attribute set, and stops;
nix's source still carries `// FIXME: if we have a 'nixpkgs' input, use it to check the module.`
Measured: a module with a nonexistent option, a nonexistent `pkgs` attribute **and** a nonexistent
`lib` function passes, printing `checking NixOS module ... all checks passed!`. `nix.yml`'s header
claimed that leg covered the module; it never had. `checks.<system>.nixos-module`
(`packaging/nix/module-check.nix`) now evaluates it against real nixpkgs across four scenarios and
asserts on the rendered units, including a guard that the host's `ExecStart` stays on the plain
store path while the encode worker points at the wrapper. Its assertions are pure Nix, so
instantiation runs them and the existing `--no-build` leg is enough. `punktfunk-gamescope` gains a
`build-gamescope` dispatch input — it is on the critical path of every host build yet nothing
compiled it, and it tracks nixpkgs' gamescope, so a `flake.lock` bump is what breaks it.

### C ABI 17 → 18

**`punktfunk_connection_next_rumble_cmd2` is new.** The `0xCA` rumble plane carries the two Xbox
impulse-trigger motors (v3, below) and `punktfunk_connection_next_rumble_cmd`'s fixed out-params
have no room for them:

```c
PunktfunkStatus punktfunk_connection_next_rumble_cmd2(
    PunktfunkConnection *c, uint16_t *pad, uint16_t *low, uint16_t *high,
    uint16_t *left_trigger, uint16_t *right_trigger,
    uint32_t *backstop_ms, uint32_t timeout_ms);
```

**Added, not widened.** `_cmd` keeps its signature *and* its values bit-identical for handle-only
traffic; all four rumble entry points remain exported. An exported parameter list is part of the
contract, and growing one in place breaks every out-of-tree embedder at once — with a
stack-corruption signature rather than a link error. This follows the existing
`next_rumble` → `next_rumble2` precedent.

⚠ **One behavioural delta on the old symbol**, documented in `abi.rs` and pinned by a test: against
a host driving the trigger motors, a `_cmd` caller now receives commands with `low == high == 0`
where the demux previously dropped the update entirely. They are idempotent handle stops — the
command as a whole is not silent, so redundant-stop suppression cannot fold them. Zero cost today:
nothing sources non-zero trigger levels yet.

**Render trigger levels only on a pad that has trigger motors.** Do not fold them into the handles —
impulse-trigger content is continuous, so folding it drones the handle motors flat-out. Query
`SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN` or `GCDeviceHaptics.supportedLocalities`.

🛑 **This delivery path is deliberately built ahead of its producer and nothing here claims
otherwise.** Exactly one backend can ever source these levels — the Windows HID Xbox pad's output
report `0x03` — because `XINPUT_VIBRATION` and evdev `FF_RUMBLE` both have two members. That
producer is reachable only through GameInput, which does not enumerate an `xinputhid`-promoted Xbox
pad at all (measured against a real Microsoft Elite, equally invisible there while classic XInput
reads it live). The wire, the engine and this entry point are exercised by synthetic levels only.

### Gamepads

- **`PUNKTFUNK_GAMEPAD_XBOXELITE = 11`** — a new `GamepadPref` wire byte, appended to
  `Hello`/`Welcome`. The `Auto` sentinel in the round-trip test moved 11 → 12. An older peer
  degrades an unknown byte to `Auto`, so this is graceful in both directions.
- **`XboxOne` is now a distinct HID identity on Windows** (`045E:02FD`, Bluetooth Xbox One S)
  through the UMDF minidriver. It used to fold to `Xbox360` there, because the only Windows Xbox
  backend was the XUSB companion, which presents one fixed 360 identity and cannot vary it.
- **Three new `pf_driver_proto::gamepad` device types**, contiguous and sharing one report
  descriptor byte for byte (they are the same pad in HID terms; the descriptor is the report
  *shape*, the identity is what the OS keys mappings off):

  | const | value | identity |
  |---|---|---|
  | `DEVTYPE_XBOX` | 4 | `045E:0B13` Xbox Wireless Controller |
  | `DEVTYPE_XBOX_ONE_S` | 5 | `045E:02FD` Xbox Wireless Controller (One S) |
  | `DEVTYPE_XBOX_ELITE` | 6 | `045E:0B22` Xbox Elite Wireless Controller Series 2 |

  ⚠ The Xbox input report is **not** 64 bytes like its siblings — it is `XBOX_INPUT_REPORT_LEN`
  (16). The driver serves per-identity report lengths, because hidclass sizes its buffer from the
  descriptor and refuses an over-long source.
- ⚠ **Elite paddles are not implemented.** `BTN_PADDLE1..4` still fold or drop exactly as on the
  other Xbox classes. `DualSenseEdge` remains the only virtual pad with native back-button slots.
- **All three Xbox identities install `pfGamepadXbox`**, their own DDInstall section, which attaches
  the `xinputhid` bus filter. Merging it back into the shared `pfGamepad` section is a one-line edit
  that looks like tidying and would hand a DualSense, DualShock 4, Edge and Steam Deck to
  Microsoft's Xbox translator. `only_the_xbox_identity_installs_the_xinputhid_section` asserts the
  split in both directions.

**What actually promotes the pad — two registry values, and the pairing is the whole finding.**
`UpperFilters=xinputhid` is a `.HW` AddReg (hardware key); `DevicePropertyFlags=1` is a DDInstall
AddReg (software key). A one-value A/B on real hardware: removing `DevicePropertyFlags` alone
reverts everything — no `IG_00`, no XUSB interface, no XInput, no WGI entry — while `UpperFilters`
alone is completely inert. `1` = `BusDevice`, which Microsoft's own comment glosses as "a focused
bus filter driver for the IG_ problem". **This retracts an earlier in-tree conclusion that the
filter should never ship**: it was never broken, it had simply never been switched on.
⚠ Microsoft's allow-list contains `02D1, 02DD, 02E3, 02EA, 0B00, 0B0A, 0B13, 02FF` — neither `02FD`
nor `0B22` is on it, and promotion happens anyway, because it comes from our own AddReg.

### Wire (no version change)

**The `0xCA` rumble datagram gains a v3 form**, `PUNKTFUNK_RUMBLE_V3_LEN = 14`:

```
v1   7 B: [0xCA][u16 pad][u16 low][u16 high]
v2  10 B: … [u8 seq][u16 ttl_ms]
v3  14 B: … [u16 left_trigger][u16 right_trigger]
```

v3 is built *from* v2's bytes, so the prefix relationship is structural rather than a convention two
encoders must keep agreeing on, and every reader gates with `>=`. All four levels share one `seq`
and one TTL deliberately: they are one statement of the pad's feedback at one instant, so the entire
v2 apparatus — renewal cadence, stop burst, the client's seq gate, the lease clamp — governs the
triggers with no new code. The new `RumbleUpdate` fields are plain `u16`, not `Option`: on a
level-triggered plane "absent" must mean zero, because "absent → keep the previous value" is the
stuck-rumble bug in a new costume.

⚠ **The two trigger `enable`-mask bits remain conjecture.** Bits 2/3 (the handles) are measured;
bits 0/1 are inferred from field order and nothing else. No test asserts them. XInput cannot settle
this; it has two motors.

### Packaging

- **gamescope pin `8c676c39` → `5fb8dce4`** (3.16.25-1 → 3.16.25-11), all six patches rebased, plus
  a **seventh**: the PipeWire use-after-free that aborted a session on every connect. The marker
  moves `+pfhdr4` → **`+pfhdr5`**, so `pkgrel` resets to 1.
- **Patch 0001 offers `xBGR_210LE` before `xRGB_210LE`.** ⚠ Deliberately *not* done by calling
  upstream's `vulkan_get_rgb10_capture_format()` — that symbol landed after 3.16.25 and would break
  `packaging/nix/gamescope.nix` with an opaque C++ error instead of a patch conflict.
- **Every `punktfunk-gamescope` RPM ever published was unsigned.** `Sign RPMs` runs right after
  `Build RPM`, while the gamescope RPM is built ~90 steps later behind its own cache, so it missed
  the signing pass entirely — and the repo file we ship carries `gpgcheck=1`. A second pass signs it
  before publish, fail-closed on a tag.
- ⚠ **The v0.26.0 gamescope gate failed the job at the *build* step**, which in `deb.yml` runs before
  both the apt publish and the release attach — so a missing *extra* withheld the host `.deb` itself,
  and the `.deb` published on v0.26.0 still carries the `CAP_SYS_NICE` grant. `rpm.yml` had the
  identical latent bug. Both now warn at build/package time and gate as the **last** step of the job.
- **`driver uninstall --audio`** — a third Inno `[UninstallRun]` entry that removes the MEDIA-class
  devnodes the host mints at runtime. Marker-matched, never name-matched: our instances are
  name-identical to Steam's, and a `ROOT\` enumeration guard means a marker-shaped value on a real
  sound card can never cost the user their hardware.
- **The sysext `post_merge` step re-runs when already current, plus a new `reapply` verb.** A sysext
  upgrade is driven by the script from the **old** image, so a `post_merge` step added in a release
  is executed by nobody, permanently, on exactly the installs that need it.

### Host

- **HDR capture offers `xBGR_210LE` before `xRGB_210LE`.** gamescope's capture textures are
  mappable, hence linear-tiled, and NVIDIA does not implement linear-tiled STORAGE for
  `A2R10G10B10_UNORM_PACK32` — so `imageStore` lands in XBGR order while the buffer is still
  *labelled* `XRGB2101010`. Every mapping on both ends audits clean because the label was right and
  only the content was wrong. Fixed host-side because the deployed gamescope cannot self-correct.
- **One NVENC open failure no longer kills every session on the box**, and the 10-bit capability
  probe no longer wedges a direct-SDK host process-wide with `NV_ENC_ERR_INVALID_VERSION`.
- **`/api/v1/local/summary` reports the resolution the session actually got**, not the negotiated
  one it was seeded with.

### Workspace

`crates/punktfunk-encode-worker` joins as a member (above). Two bring-your-own-hardware measurement
tools are added and **excluded** in the root manifest, so `cargo build --workspace` and CI never see
them: `tools/hid-descriptor-dump` (dumps and decodes a real HID report descriptor; pulls `hidapi`)
and `tools/win-input-matrix` (asks each Windows input API what it can see — ⚠ `wake_wgi()` is not
optional there: both WGI collections return a cache a console app has never started filling, so
without subscribing first they come back empty with real controllers attached).

### Host and client environment variables

- **`PUNKTFUNK_XBOX_BACKEND`** *(new, host, Windows)* — `hid` (the new **default**) or `xusb` (the
  escape hatch). The HID pad is now a superset of the XUSB companion: it keeps classic XInput while
  gaining Steam, SDL, RawInput, DirectInput, `joy.cpl` and WGI, plus rumble, which XUSB could not
  source at all. The escape hatch stays because promotion leans on Microsoft's inbox
  `xinputhid.inf`; if a servicing update changes it, one env var restores the old behaviour with no
  reinstall. An unrecognised value takes the **default**, not the opt-out, so a typo cannot silently
  drop a user onto the path with no HID collection.
- **`PUNKTFUNK_GAMESCOPE_BIND`** *(new, host, Linux)* — unset = auto, `0` = never, `1` = force.
  Governs whether the host binds the patched gamescope over the distribution's `/usr/bin/gamescope`
  inside a session's mount namespace.
- **`PUNKTFUNK_ENCODE_WORKER`** *(new, host, Linux)* — where to find the encode worker. Resolution
  order: this variable → alongside `/proc/self/exe` → `PATH`. `off` forces the in-process encoder,
  the debug escape hatch that makes the A/B a one-line change. Load-bearing on NixOS (above).
- **`PYROWAVE_QUEUE_PRIORITY`** *(unchanged grammar, new consumer)* — the *intent*, forwarded to the
  worker; the granted class comes back in the handshake and the host logs it centrally, so the
  in-process INERT warning does not double-fire. When the worker is uncapped as well — an operator
  stripped it, or the filesystem cannot store the capability — the same INERT wording fires, now
  naming the worker binary rather than the host.

### Documentation

- `docs-site` **Running as a service → GPU scheduling priority** rewritten around the split: the
  worker carries the capability, the host never does, and `setcap` on `punktfunk-host` is called out
  as the thing an operator must never do, with the `zkde_screencast_unstable_v1` symptom spelled out
  so anyone who already did it can self-diagnose. The anchor is unchanged, so existing links hold.
- `configuration.md` gains the `PUNKTFUNK_ENCODE_WORKER` row and rewrites `PYROWAVE_QUEUE_PRIORITY`
  off "the packages deliberately do not grant this".
- The 0.26.0 user-facing notes describe a privilege that is deliberately not granted. That is the
  record of what 0.26.0 shipped and is **not** rewritten; the new phrasing — granted to the worker,
  never to the host — lives in `docs/releases/v0.27.0.md`.
- `install.md` **NixOS** documents `desktopSession`, and its `punktfunk-scripting` bullet no longer
  claims the runner "ships disabled": that was true only of Arch and source installs — apt, dnf, the
  Bazzite sysext and now the NixOS module all start it, because the library scanners are plugins.
  `bazzite.md` carried the same stale claim and is corrected. **Running as a service → Restart the
  host with your desktop** gains the NixOS one-liner beside the drop-in.
- `packaging/nix/README.md`: `desktopSession`, `gamescopeHdr`/`gamescopePackage` and the
  `punktfunk` group added to the option tables; the "what the module configures" list gains the
  `security.wrappers` entry, with the KWin-identification reasoning for why the capability is on the
  worker and not the host; and a caveat recording that `nix flake check` does not check the module,
  plus the two rules for editing `module-check.nix`.

---

## v0.26.0

52 commits since v0.25.0.

### Versions

| | v0.25.0 | v0.26.0 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged |
| C ABI | 17 | **17** | unchanged — no symbol added, removed or changed |
| Workspace crate dirs | 26 | **26** | unchanged (40 workspace members) |
| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3) |
| Windows virtual-gamepad channel | 3 | **3** | unchanged |
| Plugin index schema | 1 | **1** | unchanged |
| `api/openapi.json` | 0.24.0 | **0.25.0** | tracks API edits, lags one release by convention |
| gamescope patch level (`+pfhdrN`) | 2 | **4** | 3 patches → 6; `pkgrel` 1 → 2 |
| `@punktfunk/host` (SDK) | 0.1.2 | **0.1.4** | |
| `@punktfunk/plugin-kit` | 0.3.2 | **0.4.0** | the `plugin` launch kind |

`crates/pf-driver-proto` is byte-for-byte identical to v0.25.0 and to v0.24.0 — if you ship the
virtual-display driver or the gamepad channel, the last two releases have not touched you.

### ⚠ Breaking changes

**None.** This is a fixes release. Every embedder, packager and plugin that works against v0.25.0
works against v0.26.0 unchanged. Two behaviour changes are worth knowing about anyway, because both
make a client advertise *less* than it used to — see **Capability advertisement** below.

### Capability advertisement

- **`VIDEO_CAP_444` is now probed, not asserted.** It rode the "Full chroma" setting alone. That was
  safe while a software HEVC decoder sat underneath it; M8 removed one (there is no permissively
  licensed HEVC CPU decoder, so `software_decodable_codecs()` is `H264|AV1`). The host grants 4:4:4
  on HEVC **only** and answers the resolved chroma in the `Welcome` *before* the client builds a
  decoder — so on a device with no 4:4:4 decode the toggle did not cost crispness, it cost the whole
  codec: the Vulkan rung refuses the shape at construction, VAAPI refuses it too, there is no CPU
  rung, and the session reconnects on H.264. No AMD silicon has HEVC 4:4:4 decode, so every Steam
  Deck with that switch on lost HEVC. Per-profile and default-off, which is why it read as
  intermittent.

  Now gated on `hevc_444_hardware_decodable`, which asks the driver through the same code the rung
  uses at construction (`VkH265Decoder::probe_stream_support`). **Both depths are required**, not
  either: with HDR the host may resolve 4:4:4 10-bit, and a device offering `YUV444_8` but not
  `YUV444_10` lands in the same hole. Answering from the Vulkan rung alone is exact rather than
  approximate — it is the only rung in this build that implements 4:4:4 at all
  (`pf_vaadec::profile_for` errors on `chroma_format_idc 3`, pf-dxvadec refuses anything but 4:2:0,
  the CPU rung is 8-bit 4:2:0).

  ⚠ Deliberately **not** extended to `VIDEO_CAP_10BIT`/HDR: all three rungs implement 10-bit 4:2:0,
  so a Vulkan-only probe there would withdraw HDR from boxes whose VAAPI/DXVA rung decodes it
  perfectly — a regression against a case never observed.

  The bit arithmetic moved into `video::video_caps_for` so the part that was wrong is testable
  without a GPU, a host or a `Hello`; the test is verified non-vacuous against the planted defect.

### Host and client environment variables

Four new, one clarified. Verified new by `git grep` at the v0.25.0 tag, not assumed —
`PUNKTFUNK_JUMBO`, `PUNKTFUNK_WIRE_MTU`, `PUNKTFUNK_STREAMED_AU`, `PUNKTFUNK_LIBRARY_ART_ROOTS`,
`PUNKTFUNK_RECOVER_SESSION_CMD`, `PUNKTFUNK_GAMESCOPE_SDR_NITS`, `PUNKTFUNK_MAX_FPS` and
`PUNKTFUNK_ON_CONNECT_CMD` all already existed.

- **`PUNKTFUNK_OVERLAY_MASK`** *(new, client)* — controls the Steam-overlay input mask below.
- **`PUNKTFUNK_PYROWAVE_CHUNK_KIB`** *(new)* and **`PUNKTFUNK_PYROWAVE_STREAMED_AU`** *(new)* —
  PyroWave AU chunking and the streamed-AU path.
- **`PYROWAVE_QUEUE_PRIORITY`** *(existed, but was inert on Linux — see below)* — grammar: unset →
  realtime, ASCII-lowercased, `off` alone disables, `high` asks for HIGH only, junk falls back to
  the ladder rather than to off. ⚠ **One env var must not mean two things on two platforms**, so
  the Rust grammar is unit-tested against the C patch's, including where both are deliberately
  un-clever (neither trims).
- **`PUNKTFUNK_GAMESCOPE_REFRESH_RATES=60,90,120`** *(new)* — widens the set a gamescope session
  offers in Steam's in-session display settings. The rate the session actually runs at is always
  included, so it can only add options; junk entries are skipped rather than failing the host.
  Requires gamescope patch level 3+.
- **`PUNKTFUNK_COMPOSITOR`** *(behaviour clarified, not changed)* — documented as "which backend to
  drive", it also silently discarded `game_session=dedicated`: `resolve_compositor` gated the
  dedicated route on `!overridden` and logged nothing either way. The pin still wins — it is the
  operator's explicit knob — but it now says so and names itself. Two further holes closed with it:
  the pin put its backend into `available()` unconditionally *and* skipped `apply_session_env`'s
  `XDG_CURRENT_DESKTOP` scrub, so `pick_compositor` could never return `None` — the one call site of
  `try_recover_session()`, which left `PUNKTFUNK_RECOVER_SESSION_CMD` unreachable behind that arm.
  Liveness is now read on both paths. `needs_live_session()` exempts gamescope, which stands up its
  own session, so pinning it on a headless box stays supported.

### Client settings keys

All additive; an older client ignores what it does not know, and a newer value can never trap an
older client.

- **`gamepad_ui_mode`** — `"connected"` (default, and exactly what the previous lone Bool meant) or
  `"always"`. Splits *whether* the controller UI is offered from *when* it appears.
  `GamepadUIEnvironment.isActive` takes the mode with **no default argument** on purpose: a call
  site that forgot it would silently strand everyone who chose Always. An unrecognized value waits
  for a controller.
- **`ui_palette`** gains `oled` at **index 1**, directly after the brand default — keeping
  `PALETTES[0]` the unknown-id fallback and the dark-to-pale cycling order intact. Hand-mirrored in
  three languages (`pf-console-ui`'s `library.rs`, `GamepadPalette.swift`, `GamepadPalette.kt`); each
  port carries an `oled_is_actually_black` test that measures the claim (mean cell luminance 0.019
  against Violet's 0.254) rather than restating the table.
- **`library-hidden.json`** — per-title hide list, mirroring how `library-scanners.json` holds
  disabled sources. Deliberately **not** stored on the entry: a scanner's and a plugin's titles are
  rebuilt from scratch on every scan and reconcile, so a flag written onto one would be erased
  minutes later. Applied in `all_games`, the single funnel every play surface already goes through
  (client grid, native clients, the GameStream app list, launch resolution).

### gamescope patches

Three → six, and the marker patch moves last so the banner is stamped after the capabilities it
advertises.

- **0003 — headless: advertise the virtual display's mode and refresh rates.** `CHeadlessConnector`
  returned empty spans from `GetModes()` and `GetValidDynamicRefreshRates()` and reported
  `GAMESCOPE_SCREEN_TYPE_INTERNAL`, so `update_mode_atoms` **deleted** the mode-list atom and
  wlserver fell through to a one-entry refresh list built from `g_nOutputRefresh` — which, with
  `--nested-refresh` absent, is `Init()`'s 60 Hz default. That is why a 1920x1080@120 client saw
  "gamescope only shows 60hz" and Overwatch capped itself to 60 while the stream ran at 120. Now
  populates both from the resolved mode, reports `EXTERNAL`, and adds `--custom-refresh-rates`.
  gamescope-session-plus has probed for that flag for years; upstream never had it, so the
  `CUSTOM_REFRESH_RATES` env it plumbs was a no-op everywhere.
- **0004 — pipewire: optionally composite the external overlay into the capture stream.** That layer
  is mangoapp. `paint_pipewire` has never referenced it on any version. Behind
  `--pipewire-composite-external-overlay`, off by default.
- **0006 — never destroy the Vulkan device or output.** `g_device` (`CVulkanDevice`) and `g_output`
  (`VulkanOutput_t`) were plain globals, so glibc ran their destructors from `__run_exit_handlers`
  once `main()` returned — calling back into an ICD that had already been torn down and unloaded.
  Faulting address equalling the instruction pointer is the signature. Reproducible with
  `gamescope --backend headless -W 1280 -H 720 -r 60 --xwayland-count 1 -- true` (exit 139, every
  time). Both globals get storage constructed exactly as before but never destroyed; pinning only
  the device relocated the fault into `~VulkanOutput_t`, hence a shared `CNoDestroy<T>`.

  ⚠ **`+pfhdrN` deliberately does not move for 0006.** The marker is a capability tier the host
  probes via `gamescope_patch_level()` *before* it spawns; this patch adds no capability, so bumping
  it would advertise a tier that does not exist. Ships as a `pkgrel` bump instead.

⚠ gamescope CI legs are best-effort — a broken patch is a **missing package**, not a red run.

### Virtual-display handle ownership (Windows)

The control-device sharing contract was "bare `HANDLE` copies, never closed for the process
lifetime": retired handles were kept alive because pinger/linger threads and capture closures held
raw copies whose soundness depended on no-close. An open control handle is exactly what vetoes the
PnP disable — and can wedge the `pnputil` restart — that wake-from-sleep recovery leans on, so every
post-wake adapter reload came back REFUSED. `reset-pf-vdisplay.ps1` stops the whole host service
precisely to get those handles closed; the in-process recovery could not.

Ownership is now `Arc` all the way out: `ensure_device` / `device_handle` / `control_device_handle`
hand out `Arc<OwnedHandle>` clones, every consumer holds its clone across its IOCTLs (ending the
`isize` smuggling — `Arc<OwnedHandle>` is `Send + Sync`), and retiring drops only the manager's
reference. `DeviceSlot::retired` is gone.

⚠ **Nothing may store a bare control `HANDLE` again.** The whole fix is that the handle closes when
the last in-flight user drains.

### Presenter — points are not pixels

`SDL_GetDesktopDisplayMode` reports a mode in **screen coordinates** and hands the pixels-per-point
ratio back separately as `pixel_density`; `m.w`/`m.h` were read raw. KDE advertises a 2560x1600 panel
at 150 % as 1707x1067 points with a density of ~1.4997, `render_scale::apply` even-floors both odd
axes, and 1706x1066 went on the wire. Multiplying by the density recovers 2560x1600 to the pixel.

⚠ Inert on X11 and Windows: SDL never sets a density there and `SDL_video.c` normalizes the unset
0.0 to 1.0. **This bug needed a compositor doing fractional scaling.**

Second, independent defect: the SDL window was created without `HIGH_PIXEL_DENSITY`, so the Wayland
surface stayed at buffer scale 1 and the swapchain was built at 1707x1067 for KWin to upscale. That
one also silently shrank "Match window", which asks the host for `size_in_pixels()`.

### Apple audio session

`micEnabled` and `echoCancel` both default to `true`, so the **default** iOS session is
`.playAndRecord` — and that branch set `.defaultToSpeaker`. That option is an output **override**,
not a preference, and it outranks an A2DP route. ⚠ **Wired headphones beat it, Bluetooth does not**,
so testing with a cable returns the wrong answer — which is what the comment sitting on it asserted.

Now solved against the route actually given: after activation, if the current output is
`.builtInReceiver`, override to speaker; anything external (Bluetooth, wired, CarPlay, AirPlay) is
left strictly alone. The override is a property of the current route — iOS drops it on every route
change, which is what lets a newly-connected headset win — so it is re-applied per route via an
observer, registered only for `.playAndRecord`, removed in `stop()` before deactivate, `deinit` as
backstop. Without it, dropping Bluetooth mid-stream lands on the earpiece.

⚠ Deliberately **not** adding `.allowBluetooth`: it would make a headset's mic usable but drag the
whole route onto HFP/SCO and collapse game audio to narrowband.

### Audio jitter policy

`JitterPolicy` (`punktfunk-core/src/audio.rs`, used by Linux/Windows/Android) and its mirror in
Swift `AudioRing`. The policy learned exclusively from audible failures on both sides: growth needed
**three** audible underruns; the A/V sync loop re-tested a shallower ring every five quiet seconds
and paid an audible starvation event every time it was wrong, forever; and a grown target was never
re-banked (growth raises a threshold — only a re-prime deepens the ring), so a bunching link rode
the knife edge with the "grown" target sitting inert.

Three mechanisms: **near-miss** (a read served with less than one protocol frame left over is the
same evidence as an underrun, heard by no one — grows one step per window, *before* the click);
**shrink probes** (every shrink armed for 5 s, undone on the spot if answered by an underrun or
near-miss, with a doubling backoff 60 s → 8 min on a failed sync-driven shrink; a surviving probe
resets it); **hollow re-prime** (an underrun while the depth *average* runs more than a step below
target re-primes immediately — the average, not the instant, separates a hollow ring from one late
packet, and it is seeded on prime so a fresh ring is never spuriously hollow).

Measured on a ten-minute simulation of the Wi-Fi power-save pattern (25 ms gaps / 300 ms, −50 ppm
skew): **~2000 audible events → 9.**

### Plugins, SDK and the runner

- **`category` never shipped.** The console correctly keeps `category: "library"` plugins out of the
  nav; the host reported no category for them at all. `defineLibraryPlugin` sets it and
  `sdk/src/ui.ts` forwards it — what shipped did not: `@punktfunk/host` was bumped to 0.1.2 on
  2026-07-20 and `category` landed 2026-08-05 without a bump, so the registry's 0.1.2 is the
  pre-category build. ⚠ **Inert until published.** `serveUi` now reads its own directory entry back
  and warns once when a requested category did not land.
- **Local art sync failed on a `file://` disagreement.** `local_art_bytes` decodes a `file://` value
  before testing containment; `validate_art_paths` handed the raw value to `Path::new`. Same defect
  produced both the unreachable settings and `sync (startup) failed: HostRequestError`.
- **The runner now carries SDK updates.** The copy each installed plugin runs was pinned at install
  time, so an SDK fix could never reach it.
- **`bun publish` runs `prepare`, and `prepare` needs bun2nix** — the SDK could not be published at
  all. Also fixed: a corrupt committed `bun.lock` in plugin-kit.
- **Decky client update.** `flatpak remote-info punktfunk-origin io.unom.Punktfunk` names no branch;
  the remote publishes `stable` **and** `canary`, so the ref is ambiguous and flatpak refuses it —
  ⚠ one branch being *installed* does not disambiguate, the ambiguity is on the remote. The call
  failed on every box, every time, and returned `available=False`, which the panel rendered as good
  news. Every query now names the ref in full via `_flatpak_ref()` (no subprocess), carrying the
  **scope** too, so a system-wide install is no longer invisible to a check that hardcoded `--user`.
  A check that cannot run now reports `client_error`.

### Packaging

- **The `punktfunk` group is created everywhere the udev rule needs it.** `60-punktfunk.rules`
  chgrp's the usbip vhci attach/detach nodes to a dedicated group (security review 2026-08-05 M-4:
  writing `attach` materialises an arbitrary emulated USB device, so it must not ride on `input`).
  **Four of six install paths shipped that rule in 0.25.0 without creating the group** — chgrp
  failed, nodes stayed `root:root 0644`, the virtual Deck pad silently never attached, and
  `usermod -aG punktfunk` failed outright. Fixed in arch `post_upgrade()` (only `post_install` was
  correct, so every box that reached 0.25.0 by `pacman -Syu` missed it), nix (`users.groups.punktfunk`
  did not exist), the bazzite sysext (a group is host state and cannot ride an image), and the Steam
  Deck scripts. deb and rpm were correct throughout.
- **`punktfunk-gamescope` now builds for RPM and apt**, not Arch only.
- **Arch release-rebuild prune** called a helper that cannot exist in a release rebuild. Together
  with the FFmpeg 9 repackage this closes the 0.25.0-1 → 0.25.0-2 episode in the pipeline rather
  than by hand.
- **Steam Deck `update.sh` / `install.sh`.** The web step ran `bun install --frozen-lockfile` with
  no `--ignore-scripts`, so web's `postinstall` (`bun2nix -o bun.nix`) rewrote a **tracked** file on
  every update; the SDK step below it had always passed `--ignore-scripts`, and that asymmetry is
  the whole bug. Now `--ignore-scripts` plus an explicit `bun run codegen` — provably equivalent,
  since web's `prepare` is literally `"bun run codegen"` and `src/api/gen`, `src/paraglide` and
  `src/routeTree.gen.ts` are gitignored. `--pull` restores `web/bun.nix` and `sdk/bun.nix` before
  pulling, which is lossless by construction. ⚠ Deliberately **not** `git reset --hard`: `$SRC`
  defaults to the operator's own checkout. Also: `web.env` secret hygiene — `chmod 600` sat inside
  the create-only branch, so an install set up once and only updated since kept it world-readable.
  ⚠ `packaging/debian/build-web-deb.sh`, `packaging/arch/PKGBUILD` and `packaging/rpm/punktfunk.spec`
  still lack `--ignore-scripts` for web — harmless (throwaway build trees), left as follow-up.

### Triage tooling

**`--probe-decode` described a different device from the one that streams.** The RADV
video-decode opt-in sat *after* the `--list-adapters` / `--probe-decode` / `--list-audio` / `--pair`
early exits, so the triage tool never had it. Measured on a Deck, same binary back to back: bare
`--probe-decode` printed "vulkan video decode: no", "driver decode ops: none (0x0)", "no queue
family advertises VIDEO_DECODE"; with `RADV_PERFTEST=video_decode` in the environment, "YES" and
"H.264, H.265, AV1, VP9". ⚠ **Any Deck triage that consulted it reached the opposite of the truth.**
Hoisted to the top of `run`, ahead of every early exit.

### PyroWave on Linux — Wave 2

The program's own measurement, from patch 0005's header: `encode_gpu_synchronous` goes from ~2 ms
to **15–18 ms at 95 % game load**, with the stream frame rate collapsing. PyroWave encodes on the
same shader cores a game saturates; NVENC is immune because it has its own ASIC.

- **PW1 — the GPU-priority lever had never fired on Linux.** The vendored patch requests an elevated
  global-priority queue, gated `if (!inherit_info)` — and **only Windows leaves `inherit_info` null**
  (`pyrowave_create_device_by_compat`, where Granite builds the device itself). Linux passes its own
  create-infos, Granite's `get_existing_create_info()` hands them back, `create_device` takes the
  inherit branch, and the whole block is skipped. Now wired natively in `open_inner`'s `DeviceHold`,
  ladder REALTIME → HIGH → no-priority, stepping only on refusal; a refused class can never fail the
  open. The extension probe reuses the `dev_ext_props` already fetched for `queue_family_foreign` and
  takes KHR or the EXT alias — the same spelling pf-zerocopy probes, so the two cannot disagree.
  ⭐ **Needs `CAP_SYS_NICE`**, which the packaging granted in `0.26.0-1`; without it the lever does
  nothing.
  🛑 **Corrected in `0.26.0-2`: the packaging no longer grants it, and must not.** Every channel that
  did (Arch `.install`, RPM `%caps()`, the Bazzite sysext image, the deb postinst, the NixOS
  `security.wrappers` entry) broke desktop streaming on KDE outright — field-reported on CachyOS and
  Bazzite as `KWin does not expose zkde_screencast_unstable_v1 to this client`. KWin identifies a
  client by resolving its `/proc/<pid>/exe` against an installed `.desktop`, and the kernel refuses
  that readlink to any reader whose effective set is not a superset of the target's **permitted**
  set (`cap_ptrace_access_check`) — KWin has no capabilities, so a capability-carrying host is
  unidentifiable and the restricted globals are never advertised. Neither `prctl(PR_SET_DUMPABLE, 1)`
  nor systemd `AmbientCapabilities=` rescues it; only an uncapped process is identifiable. The lever
  therefore stays wired but unexercised on a stock install (the ladder degrades to default priority),
  and is opt-in for gamescope-only hosts, which have no such identity check.
- **PW5 — two encoder handles.** `Encoder::Impl` owns exactly one each of `wavelet_img_high_res`,
  `bucket_buffer`, `meta_buffer`, `block_stat_buffer`, `payload_data`, `quant_buffer`, and
  `Impl::encode` *opens* by discarding them (an image barrier with `VK_IMAGE_LAYOUT_UNDEFINED` as the
  old layout, plus three `fill_buffer` clears). Two encodes submitted to one queue have **no**
  execution dependency in Vulkan — submission order orders the start, not the completion — so N+1's
  DWT would overwrite N's wavelet bands while N's block packing still reads them. Content-dependent
  and silent. Overlap therefore means two handles alternated, one per slot. ⚠⚠ **The landmine:**
  `sequence_count` also lives on `Impl`, and it is the **3-bit** counter stamped into every block
  header. Two handles each counting 1,2,3… put 1,1,2,2,3,3… on the wire, and the decoder restarts a
  frame only when the value *changes* — so a repeat reads as more blocks of the same frame. Depth is
  **still 1**; the handles alternate with one in flight.
- **PW3 — the fence wait moved out of submit.** PyroWave was the one backend waiting its fence inside
  `submit`.
- **PW7a — the jumbo leg was dead code.** quinn caps a peer's MTU-discovery search at
  `min(MtuDiscoveryConfig::upper_bound, the other side's advertised max_udp_payload_size)`, and
  `EndpointConfig::max_udp_payload_size` **defaults to 1472**. Nothing in the repo had ever touched
  `EndpointConfig`, so raising the host's probe ceiling could never make discovery settle above 1472
  — and the shipped mid-session grow's `settled >= sealed_datagram_bytes(target)` gate was
  unreachable on **every path that has ever existed**. Two smaller contributors fixed with it: the
  watcher stopped sampling the moment `settled >= 1472`, discarding the very climb the proof needs;
  and a session sealed above the 1500-byte default was never checked against the path at all.

  The advertisement is raised on the **client** endpoint under the same `jumbo_wire_mtu()` opt-in,
  because it is not free: quinn sizes its endpoint receive buffer
  `max_udp_payload_size × max_receive_segments × BATCH_SIZE` — on a GRO-capable Linux/Android client
  that is ~2.9 MiB at the default and **~18 MiB at jumbo** (47 KiB → 288 KiB on Apple/Windows).
  PyroWave is the codec that most wants this: it can never be re-keyed mid-stream (its client parses
  chunk-aligned AUs in windows of the `Welcome` value, read once over the C ABI), so it should
  *start* at the big shard. At an 8908-byte shard that is ~6× fewer datagrams per frame — **~49k → ~8k
  pps at 550 Mb/s**.

### Zero-copy capture

- **The dmabuf latch conflated two causes with different lifetimes.** One `AtomicBool` served both
  "the encoder repeatedly failed to import what this compositor allocates" (unrecoverable, a driver
  fact) and "the dmabuf-only capture offer never negotiated" (which can just mean the compositor was
  mid-restart). Sharing it made the second as permanent as the first: **one timeout, and every later
  session on that host captured CPU frames until the process restarted** — including sessions against
  a different compositor and a different node that had never failed at anything, with nothing said.
  Now a `RawDmabufLatch` owning both: import failures stay sticky (unchanged 3-consecutive threshold);
  negotiation timeouts get a retry budget of **2** — deliberately small, since each failure costs a
  ~10 s stall the user pays in dead air; a capture that negotiates credits the budget back; and both
  are keyed to a capture identity (node id + portal bit).
- **The zero-copy path never asked for buffer headroom.** `build_dmabuf_buffers` set
  `SPA_PARAM_BUFFERS_dataType` and stopped — no `SPA_PARAM_BUFFERS_buffers` at all, so the pool depth
  every zero-copy safety argument rests on was entirely the producer's choice and we never expressed
  a preference. Now asks for 8 (min 2, max 16) as a **Choice Range, deliberately not a fixed count**:
  SPA intersects consumer and producer params, so a fixed 8 against a producer that can only afford 4
  empties the intersection and the link stalls in "negotiating" with no error anywhere — ⚠ the exact
  trap that once cost this codebase the entire Linux cursor channel, when a 256² cursor-meta max
  failed to intersect Mutter's fixed 384². 8 buffers is ~133 ms of pool at 60 Hz and ~33 ms at 240 Hz;
  16 is a ceiling, not a request (a 4K 4:4:4 buffer is ~25 MB).
- **A PyroWave session could drop to CPU capture and log nothing.** The CPU-fallback warning was gated
  on `backend_is_vaapi`, which reads the **host-global** encoder pref — but a PyroWave session is
  negotiated **per session**, so on an NVIDIA/auto host that gate is false and the session fell out of
  every arm of the negotiation log chain while paying a full-resolution CPU pixel touch every frame.
  A degraded host and a healthy one produced identical logs. Now asks the per-session question
  (`consumer_kind`), widened to every GPU consumer and excluding only the software encoder, whose
  native input *is* CPU frames. ⚠ `pyrowave_session` must outrank `backend_is_vaapi`, because a
  PyroWave pref flips `backend_is_vaapi` on too.

### Steam-overlay input masking (Steam Deck)

On a Deck in Gaming Mode the Steam menu and the QAM are driven by the **same physical controller** the
client forwards, so opening either moved the game on the host as well — a second, invisible player.
Steam Input masks a normal game here; it cannot mask us, because masking happens on Steam Input's
virtual pad and we deliberately forward the **real** one (the virtual pad has no gyro, trackpads or
paddles).

⚠ **SDL's own gate cannot fire on a Deck.** SDL drops presses while a process has windows but no
keyboard focus, and it is on by default — but gamescope resolves focus per Xwayland ctx and the client
sits alone in its own, so the Steam overlay (which lives in the root ctx) never takes our X focus and
no `FocusOut` is ever generated. Measured on glass: with the QAM open, X input focus inside the
client's ctx stayed on its window for the whole 4 s while `GAMESCOPE_FOCUSED_APP` flipped to 769
(Steam) and `GAMESCOPE_FOCUSED_APP_GFX` stayed on the app. **That pair of atoms is the signal.**

⚠ `overlay_focus` watches them on the gamescope **root** ctx, which is *not* our own `$DISPLAY` under
`--xwayland-count 2` — hence the socket-directory walk and the flatpak filesystem line.

⚠⚠ Masking is deliberately **not** `set_forwarding`: that closes the slot and sends `GamepadRemove`,
so the game would see a controller **unplug** every time somebody opened the QAM. Every slot stays
open and only transitions stop, after flushing what the host believes is held (so a stick deflected at
overlay-open stops steering instead of freezing at its last value). On the way back, held buttons are
**adopted rather than replayed** — the A that picked a QAM row must not fire in the game as it closes
— while axes *are* re-sent, since a stick has no press to ghost and SDL only speaks on change.

### The `plugin` launch kind

The 2026-08-05 review made `launch.kind = "command"` operator-only, and a reconcile refuses on the
**first** offending entry — so rom-manager, whose every ROM is `<emulator> <args> <rom>`, stopped
putting anything in the library at all. Playnite hit the same wall and was rescued with a typed kind
the host resolves itself; there is no fixed scheme for "whichever emulator the operator configured,
with the core and flags they chose", so that trick does not generalise.

The entry now carries an **opaque key and nothing executable**, and the host asks the owning plugin
what to run at launch time, over the loopback UI port and per-boot secret it already registered.
⭐ **A stolen plugin token stops being command execution:** planting an entry is not enough, because
the live plugin answers 404 for a key it never published. Nothing executable is persisted or served to
a client, and an emulator that moved is picked up on the next launch rather than leaving a dead tile
(same reasoning as `xbox` resolving its AUMID at launch time).

⚠ **The host still spawns it**, because only the host can put the process where the stream can see it:
on Linux that is either gamescope's own argv or a spawn carrying the session's compositor env, and the
returned child is what session-game-lifetime tracks to know the game exited. A plugin spawning the
emulator itself would land it outside both.

### Verification status

| | |
|---|---|
| gamescope 0006 | 6/6 exit 0 on a release build at the real spawn shape (`2752x2064@120 --steam --xwayland-count 1`); distro control SIGSEGVs |
| Decky client update | on the Deck against the real install — pre-fix `available=False remote=''`, post-fix `available=True remote=ca010668` |
| `--probe-decode` | on a Deck, same binary back to back, with and without the RADV opt-in |
| Apple audio | builds on arm64-apple-ios17.0 (the triple that compiles the `#if os(iOS)` blocks — a plain `swift build` is macOS and skips them), arm64-apple-tvos17.0, macOS; 257 Swift tests |
| Audio jitter | 10-minute Wi-Fi power-save simulation, ~2000 → 9 audible events |
| 4:4:4 gate | test verified non-vacuous against the planted original defect |
| Steam Deck scripts | `bash -n` + shellcheck 0.11.0 clean at `-S warning`; exec bits preserved |
| Steam-overlay masking | on glass on a Deck — atom flip and X-focus non-flip both measured over a 4 s QAM open |
| PyroWave depth 2 | exercised on real hardware **without shipping depth 2** (dedicated test, shipped depth stays 1) |
| PW6 streamed AU | the trap is real, and at 2 % loss it costs exactly nothing |

⏳ **Owed on glass:** iPhone + Bluetooth listen, Apple TV stats overlay, MacBook audio listen, the
Deck HEVC/4:4:4 retest, a Windows wake-from-sleep cycle, and the PyroWave-under-game-load A/B on a
Linux host with `CAP_SYS_NICE` actually granted — the number this whole wave is aimed at. ⚠ That
last one now needs a **gamescope-only** host, or a hand-granted capability on a box you are not
streaming the KDE desktop from: see the `0.26.0-2` correction under PW1 above.

---

## v0.25.0

407 commits since v0.24.0.

### Versions

| | v0.24.0 | v0.25.0 | Notes |
|---|---|---|---|
| Wire protocol | 2 | **2** | unchanged — every addition below is optional or capability-gated |
| C ABI | 14 | **17** | three steps; see below |
| Workspace crate dirs | 22 | **26** | `pf-bitstream` (+ vendored `cros-codecs`), `pf-vkdecode`, `pf-dxvadec`, `pf-vaadec` added; `pf-ffvk` removed |
| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3) |
| Windows virtual-gamepad channel | 3 | **3** | unchanged |
| Plugin index schema | 1 | **1** | unchanged |
| `api/openapi.json` | 0.23.0 | **0.24.0** | tracks API edits, lags one release by convention |

`crates/pf-driver-proto` is byte-for-byte identical to v0.24.0 — if you ship the virtual-display
driver or the gamepad channel, nothing in this release touches you.

**Why the wire did not move.** It grew a lot and still did not break: an optional trailing
`max_shard_payload: u16` on `Hello` (absent/0 = legacy, doubling as the renegotiation capability
flag and the jumbo receive ceiling); two control messages `ShardPayloadChanged` (`0x08`) and
`ShardPayloadAck` (`0x09`); a redundant desktop-audio datagram tag `0xD2` beside the plain `0xC9`; a
controller-audio plane at `0xD1`; a new `0xCD` kind `0x06`; arrival flag bits 8/9; and
`MAX_DATAGRAM_BYTES` 2048 → 9216. Old peers never send or read any of it. Bump `WIRE_VERSION` only
when the handshake or planes change *incompatibly* — riding a C-ABI bump onto the wire once locked
every new client out of every deployed host (`ABI mismatch: client 3 host 2`, observed live).

### C ABI 14 → 17

- **v15 — the rumble policy engine's C surface.** `punktfunk_connection_next_rumble_cmd`,
  `punktfunk_connection_set_rumble_quirks`, `PUNKTFUNK_RUMBLE_QUIRK_*`. These symbols are **not
  new**: they landed while the constant still read 7 and no bump was made, so every core since has
  exported them while advertising a version that never promised them. A shipped binary says what it
  says, so this cannot be corrected retroactively — **v15 is the floor that guarantees them.** At or
  above 15 the surface is present; below it, probe for the symbol. No code changed with this bump.
- **v16 — the controller-audio client surface.** `punktfunk_connection_next_pad_audio` (the `0xD1`
  per-gamepad DualSense haptics/speaker plane), `punktfunk_connection_set_pad_audio_caps`, and the
  `PUNKTFUNK_CLIENT_CAP_PAD_AUDIO` / `PUNKTFUNK_HOST_CAP_PAD_AUDIO` mirrors.
- **v17 — session end reason.** `punktfunk_connection_end_reason` + the `PUNKTFUNK_END_REASON_*`
  vocabulary: after a session ends, ask *why* — this client closed it, the host's launched game
  exited (its close carried `APP_EXITED_CLOSE_CODE`, which the host had been sending for a long time
  with nothing consuming it), the host ended it cleanly, the host reported a failure, or the
  connection was lost. Purely a read of state the core already had: **no new call is required of an
  embedder**, a client that never calls it is unchanged, and the host sends identical bytes either
  way.

### ⚠ Breaking changes

**1. 149 unprefixed macros are now `PUNKTFUNK_`-prefixed** (139 `#define`s renamed in the checked-in
header). Names as generic as `MAX_PADS`, `TAG_LEN`, `ABI_VERSION`, `WIRE_VERSION`, `INPUT_MAGIC` and
the whole `BTN_*` / `AXIS_*` family were landing in the namespace of every program that included the
header.

*What to do:* add the prefix. Values are identical; the change is mechanical.

*It cannot break silently.* The old spellings cease to exist, so this is always an
undeclared-identifier error, never a wrong value — which is precisely the failure being removed. A
colliding `#define` does **not** fail to compile: the preprocessor silently takes the last
definition, so an embedder whose own header defined `MAX_PADS` previously got a wrong value at
runtime. Associated constants are untouched; the generator already qualifies those by type name.

**2. Linux hosts: the virtual Steam Deck controller moved to its own `punktfunk` group.** The
capability rode on `input`, which every gamepad guide tells users to join — but it can emulate
arbitrary USB hardware. Operators must `usermod -aG punktfunk "$USER"` and re-login or the pad stops
attaching. Ordinary virtual gamepads are unaffected.

> **Known issue in 0.25.0, fixed after it.** Four of the six install paths shipped
> `60-punktfunk.rules` — whose `RUN+=` does `chgrp punktfunk` on the vhci `attach`/`detach` nodes —
> without ever creating the group, so the `chgrp` failed, the nodes stayed root-only, and the pad
> silently never attached. The `usermod` above also fails outright on those boxes with *group
> 'punktfunk' does not exist*. Affected: **Arch/CachyOS upgraded** rather than freshly installed
> (`post_upgrade` called only `_ensure_update_group`), the **NixOS module** (no
> `users.groups.punktfunk`), the **Bazzite sysext** (a group is host state and cannot ride an
> image), and **Steam Deck source installs** (`scripts/steamdeck/install.sh`/`update.sh` handled
> only `input`). The deb and rpm scriptlets were correct throughout — they run one `%post`/`postinst`
> on install and upgrade alike. All four now create the group, and the two that know which user
> runs the host (the Deck scripts and the NixOS module's `host.users`) add that user to it as well.
> Workaround on an unpatched box:
> `sudo groupadd --system punktfunk`, then the `usermod`, then re-login.

**3. Plugins may no longer set `launch.command` or the pre-launch command.** Both run through a
shell and are now operator-token only; a plugin that sets them is refused. Third-party plugins that
populated them need updating — use the `launcher_ui` / `xbox` launch kinds instead.

**4. Plugin UIs moved to their own origin** on a second listener (default `PORT + 1`,
`PUNKTFUNK_UI_PLUGIN_PORT`). Reverse proxies and firewalls must forward that port; a self-signed
console needs it trusted separately.

### Capability bits

Four added, all in the handshake's client/host capability bytes:

| Bit | Constant | Meaning |
|---|---|---|
| client `0x04` | `CLIENT_CAP_AUDIO_RED` | can decode the redundant desktop-audio plane |
| host `0x20` | `HOST_CAP_AUDIO_RED` | is sending it |
| client `0x08` | `CLIENT_CAP_PAD_AUDIO` | can render controller audio |
| host `0x40` | `HOST_CAP_PAD_AUDIO` | is sending it |

⚠ **Pressure worth watching:** `client_caps` has four bits free; **`host_caps` is down to its last
one (`0x80`)**; `video_caps` has been full since 0.23.0 (`VIDEO_CAP_MULTI_SLICE = 0x80`). The next
video capability needs a second byte *and* an ABI bump — plan for it rather than discovering it.

### Wire planes

- **Controller audio, `0xD1`** — `[0xD1][u8 pad][u8 kind][u32 seq LE][u64 pts_ns LE][opus payload]`,
  one Opus frame per datagram behind a 15-byte header. `PAD_AUDIO_KIND_HAPTICS = 0` is the pad's
  BACK channel pair (the voice coils) at 5 ms frames; `PAD_AUDIO_KIND_SPEAKER = 1` is the FRONT pair
  at 10 ms. Best-effort like every audio plane: loss is a sequence gap concealed by the gap tracker,
  silence is a frozen sequence under the mic-mute discipline, host gating at −60 dBFS with a 250 ms
  hangover. `0xD2` (redundant desktop audio) deliberately skipped `0xD1` to reserve it for this.
- **`HidOutput::AudioCtl`** — `0xCD` kind `0x06`, carrying the DualSense output report's
  volume/routing bytes, change-only and value-deduped. Older clients drop it as an unknown kind.
- **Arrival flags** — bits 8 (haptics) and 9 (speaker), sent only toward a `HOST_CAP_PAD_AUDIO` host.
- **Adaptive-trigger effects are length-bounded** on encode and decode against one shared constant;
  the header emits `uint8_t effect[PUNKTFUNK_HID_EFFECT_MAX]` in place of a literal `11` (same value,
  so the struct layout is byte-identical). A zero-length effect body is now rejected rather than
  decoding as an empty — that is, a *release* — effect.
- Out-of-range pad indices are dropped before **either** rumble consumer sees them. The reorder gate
  bounds-checked and the legacy queue did not, so an embedder draining it could be handed an index it
  would use to subscript its own array. The client also clamps the host's rumble lease receive-side
  at 5 s, where the ceiling had been sender-side only.

### Host environment variables

| Variable | Default | Notes |
|---|---|---|
| `PUNKTFUNK_AUDIO_QUALITY` | `high` | `low`/`standard`/`high`; `high` = stereo 256 kbps. `standard` reproduces the pre-0.25 encoder exactly for an A/B. A typo warns once rather than silently downgrading. |
| `PUNKTFUNK_AUDIO_REDUNDANCY` | unset = automatic | on when the client supports it and the budget allows |
| `PUNKTFUNK_AUDIO_OUTPUT_MODE` | `client_only` | `client_only`/`host_and_client`/`follow_default`. **Windows host only.** |
| `PUNKTFUNK_PAD_AUDIO` | on | `0` disables controller audio host-wide |
| `PUNKTFUNK_PAD_AUDIO_SLOTS` | `1` | max 4; multi-pad needs an operator to raise it |
| `PUNKTFUNK_PAD_AUDIO_STAMPS` | unset | debug bisect hook |
| `PUNKTFUNK_WIRE_MTU` | unset | pins on-wire IP MTU for all sessions; above 1500 also enables jumbo |
| `PUNKTFUNK_JUMBO` | unset (off) | fixed 9000-MTU profile |
| `PUNKTFUNK_UI_PLUGIN_PORT` | `PORT + 1` | the plugin-UI origin |
| `PUNKTFUNK_LIBRARY_ART_ROOTS` | platform default | art-serving roots; POSIX now defaults to `$HOME` |
| `PUNKTFUNK_DECODER` | client | **values changed**: `native-vulkan` · `native-vaapi` (Linux) · `native-d3d11va` (Windows) · `software`. Legacy `vulkan`/`vaapi`/`d3d11va` still accepted and migrated. Now **trimmed** — a trailing space used to fall through to `auto` silently. |
| `PUNKTFUNK_VAAPI_DEVICE` | client | **new** — pin the VAAPI render node |
| `PUNKTFUNK_DUMP_VIDEO` / `PUNKTFUNK_AU_DUMP` | client | **new** — capture exact decoder input / the AU as it arrived from the host |
| `PUNKTFUNK_AU_FAULT=drop\|truncate\|flip[:period]` | client | **new** — deliberate decoder-input corruption for recovery testing; native rungs only |
| `PUNKTFUNK_NVENC_SPLIT_ARBITRATE=1` | host | **new** — opt-in live split-encode arbitration (Linux-wired) |
| `PUNKTFUNK_NO_AUDIO_MINT` | host (Win) | **new** — opt out of minted endpoints; restores the name ladder |
| `PUNKTFUNK_GPU_PRIORITY` | host (Win) | **removed** — superseded by `PUNKTFUNK_GPU_PRIORITY_CLASS`, a strict superset |
| `PUNKTFUNK_FFMPEG_LOG` | client | **removed** with the av_log machinery |

Legacy `PUNKTFUNK_HOST_AUDIO=1` and `PUNKTFUNK_KEEP_DEFAULT=1` still work, mapping to
`host_and_client` and `follow_default`; `follow_default` wins if both are set. New devtest command:
`punktfunk-host pad-endpoint ensure|remove|status`.

### Security

- **Origin isolation.** A second listener serves `/plugin-ui/**` and nothing else; the console origin
  refuses those paths and the plugin origin refuses everything else, `/api/**` above all. Different
  origin (scheme+host+port) so same-origin policy *is* the boundary; same site so the `SameSite=Lax`
  session cookie still flows. Bind failure disables plugin UIs rather than falling back.
  `x-pf-listener` is stripped inbound and set by the entry; active ports republish as
  `*_PORT_ACTIVE`; the plugin origin's CSP names the console as its only `frame-ancestors`; the proxy
  allowlist drops the plugin's `Clear-Site-Data`, `Access-Control-Allow-Origin` and `Set-Cookie`.
  ⚠ The kit's `postMessage(..., "*")` is **load-bearing** — narrowing it to `location.origin` would
  target the plugin's own origin and drop every message.
- **Authorization is an allowlist with a build-time gate.** `plugin_may_access` is a list of
  permitted `(method, path)` pairs with `{}` segment matching, enforced by a test that walks the live
  route table and **fails the build on any unclassified route** — the block-list it replaces let new
  endpoints through silently. Field authority is tracked separately from route reachability:
  requests carry the lane that authorized them, and `prep` / `launch.kind = "command"` are
  operator-token only.
- **Art serving** gained an extension whitelist plus magic-byte sniffing, canonicalize-or-refuse, UNC
  refusal, config-dir exclusion and root checking, with `file://` percent-decoded *before*
  canonicalization so `%2e%2e` cannot hide. Validation also runs at write time, so an unservable path
  can no longer be persisted.

### Native decode — FFmpeg is gone from the client

268 files, +129k / −25k. `cargo tree -p punktfunk-client-session` finds zero `ffmpeg`. **The host
keeps `libavcodec` unconditionally** (pf-encode); no host workflow, packaging script or licence file
was touched.

| Platform | v0.24.0 | v0.25.0 |
|---|---|---|
| Linux desktop | ffmpeg-next: Vulkan hwcontext (`pf-ffvk`) → VAAPI → libavcodec sw | `pf-vkdecode` (ash, presenter's own `VkDevice`, zero-copy) → `pf-vaadec` (dlopen'd libva, DRM-PRIME dmabuf) → `openh264` + `rav1d` |
| Windows desktop | ffmpeg-next Vulkan → libavcodec D3D11VA half | `pf-vkdecode` → `pf-dxvadec` (plans into `ID3D11VideoDecoder`) → `openh264` + `rav1d` |
| Android | MediaCodec (never had FFmpeg) | unchanged |
| Apple | VideoToolbox (never had FFmpeg) | unchanged |

**Workspace members:** added `pf-bitstream` (+ vendored `cros-codecs`, compiler-enforced
`unsafe`-free), `pf-vkdecode`, `pf-dxvadec`, `pf-vaadec`; removed `pf-ffvk`. **Deleted:**
`video_vulkan.rs`, `video_vaapi.rs`, `video_libav.rs`, the libavcodec half of `video_d3d11.rs`, the
`av_log` machinery, `ffmpeg::codec::Id` as decoder vocabulary, `DecodedImage::VkFrame`/`::Dmabuf`,
the `ffmpeg-fallback` feature, and swscale — and with it the BT.601 default its correction code
existed to undo.

**Software rung:** `openh264 = "0.9"` (BSD-2) and `rav1d = { version = "1", default-features =
false, features = ["bitdepth_8"] }` (BSD-2). `dav1d-sys` was rejected because it is `system-deps`-
only and would add a system library plus a `.pc` to every client package. `default-features = false`
drops `asm` — rav1d's `build.rs` *panics* without nasm, unlike openh264-sys2, which degrades quietly.
**`bitdepth_8` only** ⇒ software AV1 refuses 10-bit by contract, read from the sequence header before
any byte reaches the decoder.

**⚠ HEVC has no CPU floor.** An HEVC session that exhausts its hardware rungs tears down and re-dials
advertising HEVC-less caps, and the host picks H.264 (`last_rung_verdict` / `NoSoftwareRung`). This is
a first-class path, not a failure.

**Rung × codec × hardware evidence** (`native_evidence`) — the admission filter is driven by this, so
an unproven rung yields only to one that is both verified for the codec and usable on the device:

| Rung | Codecs | Evidence |
|---|---|---|
| `native-vulkan` | H.264, H.265 Main/Main10/4:4:4 | **yes** — bit-exact vs libavcodec, 250/250 AUs on 3 drivers + 92-min soak |
| | AV1 | **yes** — 250/250 bit-identical on one vendor, no soak |
| `native-d3d11va` | H.264, H.265 | **yes** — frame-hash parity on RTX 4090 + AMD iGPU, 30-min soak |
| | AV1 | **not proven** — decoded 4K60 once, no parity, no soak ⇒ excluded from the filter |
| `native-vaapi` | H.264, H.265, AV1 | **NO — has never decoded a frame anywhere**; no VAAPI hardware was reachable |
| `software` | H.264 (openh264), AV1 (rav1d) | **not proven**; openh264 has never run on glass. No HEVC at all. |

Vendor order (unchanged): Linux NVIDIA/AMD `vk → vaapi → sw`; Linux Intel/unknown
`vaapi → vk → sw`; Windows NVIDIA/AMD `vk → d3d11va → sw`; Windows Intel/unknown
`d3d11va → vk → sw`.

**AV1 advertisement** now answers from device facts (`av1_hardware_decodable`: Vulkan `DECODE_AV1`
queue op, or the Windows D3D11 import path) rather than `ffmpeg::decoder::find(AV1)`, which was true
on any build linking libdav1d. **Settings migration:** stored `vulkan`/`vaapi`/`d3d11va` migrate to
`native-*` at decoder construction *and* at each dialog's lookup — the second is load-bearing, since
an unmatched value renders as "Automatic" and a save would silently rewrite the preference.

### The three decode data-loss bugs

**AV1 sub-frame truncation — shipped in v0.24.0, host-side.** NVENC sub-frame readback has two halves
armed by *different* conditions: `build_init_params` arms the writer from `subframe_on` alone, while
the chunked reader additionally requires `slices >= 2` — and `resolve_slices` returns `1` for AV1
unconditionally, because AV1 partitions via tiles, not slices. So an AV1 session told the driver to
publish tile-by-tile and then took only the first tile. Measured at 4K60: every AU carried a header
declaring two tile rows plus a single Tile Group OBU with `tg_start = tg_end = 0`; libdav1d rejected
**835/836** AUs. NVIDIA's *hardware* decoder accepts it (so Vulkan Video looked healthy at 60 fps);
its DXVA path did not. 1080p is one tile and unaffected; 4K splits into two tile rows and loses half
the picture. Fixed by disarming sub-frame for AV1 while leaving `split_mode` untouched — AV1 keeps
every engine. Arming the reader instead is *not* a drop-in: the reader cuts at
`bitstreamSizeInBytes` on the reasoning that slices are contiguous Annex-B, which AV1 OBUs are not.
Post-fix 654/654 clean. The test that had pinned the old behaviour as *correct* is replaced by one
pinning the disarm, plus one comparing the reader's gate against the writer's — the comparison
nothing made.

**HEVC DPB from the level ceiling — new in this release, client-side.** `dpb_limit` computed
`max(A-2_level_ceiling, sps_max_dec_pic_buffering_minus1 + 1)`. HEVC equation A-2 is a **ceiling on
what an SPS may legally signal**, not a statement of need, and it branches on picture size against
the *level's* `MaxLumaPs`. The host is blameless: NVENC autoselects L5.1 because the bitrate exceeds
L5.0's ceiling, and signals six pictures at every resolution. At 720p and 1080p the A-2 branch yields
16 frames / **17 slots** — one more than NVIDIA's `maxDpbSlots` of 16 — so every AU fell outside
device caps, flushed, waited for an IRAP, and the fresh IDR needed 17 again; rungs exhausted, and
there is no software HEVC. It hid because the path was only ever exercised at 4K, the one size that
falls through to the honest answer. Fixed to `buffering.min(16)`: the `max()` bought no tolerance,
since `Dpb::needs_bumping` already evicts at the signalled depth — it only over-allocated ten
surfaces per 1080p session. **H.264 escaped by luck** (its ceiling lands at 13 for 1080p) and is left
alone, because H.264's DPB size genuinely *is* level-derived absent a VUI `bitstream_restriction`.

**rav1d aborts the process — new in this release, client-side.** rav1d 1.1.0 `abort()`s on *any*
decode error while holding one frame context: the `c.fc.len() == 1` branch decodes inline, always
finishes in `rav1d_decode_frame_exit` which unconditionally takes `frame_hdr`, then on `Err` re-enters
an `on_error` whose first act is `frame_hdr.as_ref().unwrap()` on the `None` it just left. The panic
unwinds into `dav1d_send_data`, which is `extern "C"` ⇒ `panic_cannot_unwind` ⇒ `abort()`. **No
`catch_unwind`, no rung demotion and no refusal can catch it**, and every `rav1d_*` entry is
`pub(crate)`, so no in-process guard is possible. 4K was only *where* the first error happened — the
CPU rung does 35–39 fps against a 60 fps stream, the backlog stopped draining, the pump flushed to
live, and the next AU referenced undecoded frames. Fixed by opening with `n_fc >= 2` and asking
`dav1d_get_frame_delay` what the settings actually bought. Decode now drains **past** the first
`EAGAIN`, which is why two frame contexts cost no latency (20–42 ms/unit at `n_fc=2` vs 21–53 at
`n_fc=1`). On glass: 4K60 AV1 was SIGABRT on the second frame every run; after, exit 0 with 1204
frames and 13 decode errors recovered across 17 backlog flushes. Reported upstream as **rav1d#1497**
with a reproducer. Does **not** make the CPU rung panic-proof.

**Settings loader BOM — shipped in v0.24.0, client-side.** `.and_then(|s| from_str(&s).ok())` turned
every parse failure into `Default`. `Set-Content -Encoding UTF8` writes `EF BB BF`, serde_json
correctly rejects at byte 0, and every setting vanished silently. A shared `load_json_or_default` now
strips the BOM and warns with path plus serde line/column, covering settings, known-hosts (where a
BOM silently unpaired every host) and profiles on both desktop clients. The result is deliberately
still `Default`, never an error.

### Other decode/encode

- **Intel Arc pNext ordering.** `vkGetPhysicalDeviceVideoCapabilitiesKHR` was called with the codec
  caps struct chained *before* `VkVideoDecodeCapabilitiesKHR` (`push_next` prepends). Arc/Windows
  fills those two **by position, not by sType**, and returned them swapped — we read a level as a
  capability bitmask. Measured A/B: `decode_flags_raw=12 max_level_idc=1` before,
  `decode_flags_raw=1 max_level_idc=12` after. NVIDIA and RADV dispatch by sType, which is why the
  fleet stayed green. ⚠ **This does not yet give Arc Vulkan Video** — the refusal only moves down: the
  device advertises only COINCIDE, and its NV12 coincide entry does not advertise `SAMPLED` usage,
  which the zero-copy presenter needs. Unresolved whether that is ours or an Intel constraint.
- **NVENC split encode.** The 10-bit rule sat *above* the pixel-rate arm and took no codec, so it
  vetoed 10-bit 4K120 — the exact case the pixel-rate arm exists for — and applied an
  HEVC-Main10-on-Ada result to AV1 10-bit, which has no such measurement. Re-measured on Ada and
  Blackwell: 4K60 2.06×, 5120×1440@240 1.31×, 4K120 1.89× — **split wins at every mode on both
  architectures, including the configuration the veto came from.** New order: env override →
  pixel-rate arm (now taking `max_forced_split_mode(engines)`, not a hard-coded 2) →
  HEVC-Main10-below-the-bar → AUTO. Operator over-asks are clamped with a warning because **the driver
  honours an over-ask and silently encodes narrower**. Also newly logged: HEVC + plain AUTO +
  sub-frame is **silently single-engine** — the fleet's default shape, and nothing said so.
  ⚠ **Unvalidated consequence:** 5120×1440@240 Main10 now clears the pixel-rate bar and *will* be
  forced to split — the exact configuration the old veto came from. `PUNKTFUNK_SPLIT_ENCODE=0` is the
  escape.
- **PyroWave on Windows stamped over the host's GPU scheduling policy.** It raised the process WDDM
  class to HIGH at every session open, while `auto_priority_gate` already owns that process-wide —
  starting at HIGH, *upgrading* to REALTIME once safe, and leaving a monitor that drops back when VRAM
  tightens (REALTIME + NVIDIA + HAGS + near-full VRAM is a documented NVENC hang). Opening PyroWave
  stamped HIGH back and **orphaned the monitor's decision**. Removed rather than reconciled.
- **A `pf-vkdecode` AV1 use-after-free fix had stabilised the wrong pointer** —
  `OwnedStdAv1SequenceHeader` kept the Std struct *inline*, so `pStdSequenceHeader` was a dead stack
  address; it worked only because NVIDIA happened to retain `pColorConfig` instead. Std structs are
  now boxed inside each owning wrapper, and create-time arrays are fields of the stored parameters
  assembled at their final address. The same shape was fixed pre-emptively in H.264/H.265.

### A/V sync — it did not previously exist

The host has always stamped `pts_ns` on every audio datagram. **Every client decoded it into
`AudioPacket` / `AudioPCM` and never read it.** Video's `pts_ns` was used end to end; audio free-ran
at whatever depth its jitter ring reached; nothing compared them. The A/V offset was an emergent
property of buffer depths — it moved whenever the ring ratcheted under underrun pressure, and it got
**worse every time video got faster**, because a quicker decoder lowers the video leg and leaves
audio's where it was. That is why shaving milliseconds off the audio budget had never helped.

Two host defects were prerequisites:
- **`pts_ns` was stamped at encode time**, inside the loop draining an already-accumulated chunk, so
  every frame of a chunk carried near-identical timestamps describing *when we got round to
  encoding*. Now derived from the chunk's arrival instant minus queued-frame duration, re-anchored
  per chunk.
- **The host did not pace.** One capture callback hands over a whole quantum (5 ms honoured, **21.3 ms
  on a VM**, where stock PipeWire raises `min-quantum` to 1024), drained into back-to-back
  `send_datagram` calls — a 4–5 frame burst then ~21 ms of nothing, which a ring could only absorb by
  standing a burst period deep. Frames now leave on the audio clock (`FRAME_INTERVAL` 5 ms,
  `PACE_MAX_SLEEP` 10 ms, `PACE_REANCHOR` 100 ms). Costs no average latency.

```
audio_e2e = (now + buffered_ahead + clock_offset) − pts_ns
av_offset = audio_e2e − video_e2e            (> 0 ⇒ audio behind the picture)
```

`AvSync` EWMAs it (`AV_EWMA_TAU_MS = 2000`), ignores anything inside `AV_DEADBAND_MS = 10`, waits
`AV_MIN_OBSERVATIONS = 100` before a first correction, and **refuses rather than clamps** beyond
`AV_SANE_LIMIT_MS = 1000` — a wall-clock step must not steer the ring.

⭐ **Video is the master, and continuity outranks sync.** `JitterPolicy::set_sync_target` takes only a
*request*, clamped between the existing underrun-driven adaptive floor and the hard cap: a link whose
jitter genuinely needs more buffer than the picture is away keeps its buffer, and the residual is
reported rather than forced. `None`/`nil` reproduces prior behaviour bit-identically, which is how
the four rings adopted it one at a time.

Per client: the Rust desktop reference is a new `video_e2e_ns` atomic beside `clock_offset`, written
by the presenter and read by the audio thread. **Android** publishes `OnFrameRendered` — the one
place that knows a frame *latched* — **raw, not floor-shaved** (the HUD shaves the OS present floor;
sound must reach the ear when light reaches the eye), and stays inert below API 33 rather than
substituting the release instant, which targets a future vsync 8–21 ms ahead of glass. **Apple**
publishes its `LatencyMeter` sample as an *expiring level*, because that client has a backgrounded
keep-alive that keeps audio playing while dropping video decode; its clamp raises the ceiling to the
floor rather than `min(max(…))`, which on a device whose callback quantum alone exceeds the hard cap
would otherwise hand back the cap, silently below the continuity floor.

Escape hatches: `PUNKTFUNK_NO_AV_SYNC=1` everywhere, plus
`adb shell setprop debug.punktfunk.no_av_sync 1` on Android (a launcher-started app inherits no
environment). Observability: `buffer_ms`/`target_ms` had only ever been a `tracing::debug!` line —
and on a Deck the client runs under Steam's `reaper` with stdout on a pipe nobody can read, so the
one number identifying a deep ring was unobtainable *on the device reporting the latency*. Now on the
HUD and in the 1 Hz stats log on every client.

### Decode-target aliasing — caught before it shipped

⚠ **None of this ever shipped.** `git ls-tree v0.24.0 crates/` has no `pf-vkdecode`, `pf-dxvadec`,
`pf-vaadec` or `pf-bitstream`; v0.24.0's decode rungs were libavcodec. This was a ship-blocker for
the new stack, cleared — not a field bug.

Three of the four native rungs released a picture's surface **inside the plan→submission
conversion**, then assigned the decode target a slot. `SlotMap::assign` returns the *lowest free
slot* — the one just vacated. The submission then named one surface as both decode target and its own
reference: `CurrPicTextureIndex == RefFrameMapTextureIndex[k]` on DXVA, or `pSetupReferenceSlot`
sharing an array layer with `pReferenceSlots` on Vulkan. **Decode into the surface you are predicting
from.**

- **AV1 / D3D11VA** — AV1 applies `refresh_frame_flags` *after* decode (7.20), so "read a slot then
  overwrite it" is the ordinary case: **268 of the vendored vector's 274 frames**, first at frame 6.
- **H.264 / both Vulkan and D3D11VA** — `H264Planner` snapshots `dpb_refs` in `begin_picture`, before
  8.2.5 marking and the C.4.5.3 bump, so a picture the sliding window unmarks and the bump evicts
  lands in *both* `dpb_refs` and `dpb.removed`. Both conditions coincide only in low-delay H.264 —
  and NVENC guarantees it (`max_num_ref_frames = 3` alongside `max_dec_frame_buffering = 3`, plus
  `max_num_reorder_frames = 0`). Result: **297 of every 300 access units of every stream a punktfunk
  host emits**, at every resolution, on both rungs.
- **H.265 is exempt, now measured rather than argued** — 0 of 120 aliases, with a counterfactual that
  moves the snapshot one call earlier and reproduces 115 of 120.
- **VAAPI's exemption was incidental**: the precondition is fully present (117 of 120 AUs) but
  `plan_to_va` never invents a surface. That held only because three call sites happened to write
  `free_surface()` and `surface_table()` adjacently; `acquire_target` now returns index, surface and
  table together so a later edit cannot split them.

Fix is uniform: the plans grow `release_after_decode`, conversions hand removals back, callers
release once the decode op is issued. Costs no slot (`SlotMap::new` allocates `max_dpb_frames + 1`).
Both rungs hold the `Result` rather than `?`-ing it so the deferred release runs on failure paths —
seven exits sat between conversion and release, each of which would have leaked a slot.

**Why four gates missed it**, all recorded: the conformance vector is *structurally blind* (level 1.3,
no VUI `bitstream_restriction` ⇒ a 7-frame DPB against 2 reference frames, and it reorders) and
passed 250/250 for two milestones; **a test had encoded the bug as correct**; another assertion was
*vacuous* (it asserted the decode target was never also a reference while handing every picture its
own never-reused surface id — distinct integers cannot collide); and **it streamed clean** — *"the
2026-08-07 field sessions that looked clean were looking at wrong pixels."*

`gpu_parity` is now **11 legs** (not 9 — that note was written mid-PR): each decodes a vendored stream,
reads back every output frame's NV12, crops to the display region and SHA-256s in *display order*
against libavcodec goldens, frame count and flush tail included. The three new legs are our own
encoder's output rather than conformance vectors — H.264 because the vector is blind to the shape,
H.265 because an exemption with no stream behind it is how the H.264 defect survived two milestones,
AV1 because the vector is one tile on all 274 frames while our encoder splits 4K into two tile rows,
so every tile array the conversions fill had only ever been written at index 0. `video_vaapi_native`
parity is new entirely: 7 legs, bit-identical on RDNA3.

⚠ Promoting D3D11VA AV1 to `verified` **changes rung selection** on Windows Intel/unknown vendors, not
just a label. VAAPI stays `verified = false` deliberately — one vendor, never soaked; flipping it
would move `auto` off Vulkan Video on every Linux AMD/Intel client including the Deck.

### FFmpeg 9, and the Arch soname trap

`pf-encode` now builds against **FFmpeg 9**. The host still links libavcodec unconditionally; the
client has none (see above).

⚠ **`pacman` is the only one of our packaging formats that does not derive dependencies from ELF
`DT_NEEDED`.** rpm auto-generates `libavcodec.so.62()(64bit)`, `dpkg-shlibdeps` emits `libavcodec62`,
nix pins the closure — but a bare `depends=('ffmpeg')` let `pacman -Syu` walk the host across a
soname bump with no warning and no conflict. FFmpeg 8 → 9 (`2:9.0-5`: libavutil .60→.61, libavcodec
.62→.63, libavfilter .11→.12, libavdevice .62→.63, libswscale .9→.10) therefore **bricked every
Arch/CachyOS install**: the dynamic loader cannot start the binary, so it is **exit 127 before
`main()`** in a systemd restart loop, with nothing in the host's own log to explain it.
`ldd /usr/bin/punktfunk-host | grep "not found"` is the one-line diagnosis.

⭐ The fix is **SONAME deps, not a hand-written version bound**: `depends=(… 'libavcodec.so'
'libavutil.so' …)`. Arch's ffmpeg declares matching `provides=(libavcodec.so=63-64 …)`, and makepkg
rewrites each bare `libfoo.so` into `libfoo.so=<soname>-<arch>` by reading the built binary's
`DT_NEEDED` — so the bound tracks whatever FFmpeg the builder linked against with nothing to
maintain across the next bump. A literal `ffmpeg<2:9` would go stale on every bump. pacman now
refuses the upgrade instead of bricking the install. All seven libs are listed even though
`--as-needed` currently drops two: an unlinked soname is left bare by makepkg and satisfied by any
ffmpeg, so listing it costs nothing and a future link picks up the bound automatically.

🛑 **The v0.25.0 Arch packages shipped with that bound pointing at the WRONG FFmpeg — install
`punktfunk-host 0.25.0-2` or newer.** The soname fix and the FFmpeg-9 build landed as one merge;
the release tag was pushed four minutes later, while the CI builder image was still being
rebuilt. arch.yml deliberately runs no `-Syu` ("the image's snapshot IS the build environment"),
so the release was linked against FFmpeg 8 and published `libavcodec.so=62-64` — a bound no
up-to-date Arch box can satisfy. It fails *safely* (pacman refuses; nothing bricks), but it fails
**loudly and broadly**: pacman prepares one transaction, so an unsatisfiable dependency of ours
stopped affected users' entire `pacman -Syu`. `0.25.0-2` is the identical source rebuilt against
FFmpeg 9. Only Arch was exposed — every other format derives its dependency from the ELF at build
time and could not disagree with itself this way.

Two guards now stand where only a convention did. arch.yml compares the builder's libav
`provides` against the live repos before building and `-Syu`s itself if they differ; and no
package is published until a **pristine-`--dbpath`** `pacman -U --print` resolves it, which asks
"would a real, up-to-date Arch box install this?" instead of "does the builder happen to satisfy
it?" — the distinction that let this ship. Keeping `ci/arch-ci.Dockerfile` current is still the
cheap path; the guards are the backstop.

### Linux playback filled the buffer ceiling

The PipeWire playback callback sized its writes from the mapped buffer's **capacity** — PipeWire's
quantum limit, 8192 frames ≈ 170 ms — instead of the graph's per-cycle ask (`pw_buffer.requested`).
Every cycle queued up to 170 ms of PCM downstream of the ring **and** taught `JitterPolicy` that the
device drains 170 ms per callback, so the underrun floor (want + one frame) rose above any depth the
A/V sync loop could request: sync measured audio ~280 ms late and was then forbidden — **by its own
continuity rule** — from draining it. The first on-glass run of the latency overhaul showed exactly
that: `audio buffer 272 ms, a/v +284 ms`, stable. Now honours `requested` (capacity remains both the
ceiling and the fallback when `requested == 0`) and logs requested-vs-capacity once per stream.
Needs libpipewire ≥ 0.3.49; every ship target clears it.

### Windows audio substrate

The host now mints its **own** devnodes from Valve's INFs (`SteamStreamingSpeakers.inf` /
`SteamStreamingMicrophone.inf` under `{CommonProgramFiles(x86)}\Steam\drivers\Windows10\…`) instead
of bundling VB-CABLE.

- **Two persistent endpoints**, `Punktfunk Speakers` (client-only loopback sink — the wiring plan
  parks the default playback on it during a stream, its WASAPI loopback feeds the encoder, the host
  stays silent) and `Punktfunk Microphone` (host writes decoded client voice into the render side;
  the capture side surfaces as the mic). Both survive host restarts and re-resolve by marker.
- **Identity is the recorded endpoint id, never the name** — a minted instance is name-identical to
  Steam's primaries. Durable marker `PunktfunkAudioRole` (1 = Speakers, 2 = Mic) under Device
  Parameters. Name stamping is device-desc + device-name **only**: a wider stamp set makes
  `AudioEndpointBuilder` re-mint under a new GUID. Best-effort via the SYSTEM ACL route; on failure
  the endpoint still wires and simply keeps the driver's default name.
- **Format stamps are per-direction.** Render gets the PCM16-device / float-mix stereo split; capture
  gets the **device-format key only** — mix and host-format keys are render-engine properties, and
  stamping them onto a capture endpoint breaks its shared-mode graph (`IsFormatSupported` reports
  2ch/48k fine, `Initialize` then fails `0x88890008`).
- **`MintedIds` is tier-0 in the wiring plan.** The mic takes its minted device outright (paired by
  provider id — a name search cannot distinguish it from the primary); the loopback prefers the
  minted sink at the head of the silent tier. Below that the old ladder is unchanged: Steam primaries
  → cable → real hardware. `PUNKTFUNK_MIC_DEVICE` still beats everything.
- **Mic-vs-loopback arbitration**: the mic may hold the Streaming Microphone only while the loopback
  still gets a non-last-resort pick; otherwise the loopback takes it and `mic_withheld` is set. This
  fixes a field case where a headless Steam-only host streamed **silence**.
- **New `AudioReadiness`** — `Full` / `AudioOnly` / `MicOnly` / `Nothing`, logged on every plan
  change and surfaced at `GET /api/v1/status` → `RuntimeStatus.audio` (`AudioWiring`, Windows-only,
  absent before the first wiring pass; a status poll triggers no COM work or `IPolicyConfig` writes).
  The console Dashboard renders it as an "Audio wiring" card.
- **Requires Steam installed** (never running) — without the INFs the host streams video only, and
  picks the drivers up automatically if Steam is installed later. Opt out entirely with
  `PUNKTFUNK_NO_AUDIO_MINT`, which restores the previous name-based ladder exactly.
- ⚠ **VB-CABLE is no longer bundled but is deliberately NOT uninstalled** — it is a third-party
  shared component other apps may use, and it stays in the ladder as a live fallback. Demoting it was
  considered and rejected: on a box where minting transiently fails, that would let the Steam
  Streaming Microphone outrank an installed cable, steal the silent sink and make stream audio
  audible on the host.
- ⚠ **The minted endpoints survive Punktfunk's uninstall by design** (they are plain instances of
  Steam's drivers and are inert without the host). There is no user-facing removal path; cleanup is
  the devtest `punktfunk-host audio-probe cleanup`.
- New devtest: `punktfunk-host audio-probe ssm|sink|sss-primary|mint|plan|micpitch|micpins|cleanup`.
  `plan` is the field-triage command; `micpins` maps exclusive+shared `IsFormatSupported` across
  {1,2}ch × {16,32}bit × {44.1,48,96}kHz on both mic pins.

### Apple audio

- **The microphone was never in the render graph.** On the combined (voice-processing) engine — made
  default a week earlier and never run on a device — the input node carried a tap and **no
  connection**, so nothing pulled it: the IO unit came up, the recording indicator lit for a beat,
  and not one buffer ever reached the tap, with no error and no failed start. The 10 s silence
  tripwire counts *captured* frames, so it never fired. Input now runs through a silent sink into the
  main mixer at `outputVolume = 0` (Apple's own voice-processing sample topology). Two more: the tap
  read the input format **before** `prepare()`, and enabling voice processing swaps in the VPIO unit
  and renegotiates, so the pre-swap read could be 0 Hz / 0 ch; and a mic-chain failure on the
  voice-processed engine took the whole uplink down for the session — it now falls back to the split
  path, because **the mic outranks the AEC**.
- **No packet-loss concealment on the one client that decodes Opus in core.** Linux, Windows and
  Android all feed an `AudioGapTracker` and synthesize libopus PLC; the in-core path had the tracker
  sitting unused in the same crate and decoded only packets that arrived. At ~200 packets/s of 5 ms
  frames every lost datagram was a hard time-domain gap — one click per loss. The redundant plane
  (`0xD2`) hides single losses, so the survivors were exactly the burstier gaps that most needed
  concealing. Concealed frames now land in front of the arriving frame in one contiguous buffer, a
  DTX marker advances accounting without being decoded, and the output buffer is pre-sized for a full
  concealment run so the borrow-until-next-call pointer cannot dangle (50 ms cap).
- **The Apple jitter ring never grew.** The shared Rust `JitterPolicy` has an adaptive target floor;
  the hand-written Apple mirror mirrored the *shed* half but not the *growth* half, pinning its
  target at the 20 ms base forever. On Wi-Fi that bunches arrivals, 20 ms is regularly shorter than
  one delivery stall, so the ring re-primed through every stall for the whole session. Now the full
  `note_read` mirror: 3 underruns in a 5 s window grow the target 10 ms (capped at CoreAudio's 70),
  30 s of quiet steps back, and the write-side hard trim follows the grown target.

### Clients

- **Nothing in the desktop console had ever been clickable.** `SkiaOverlay::handle_event` matched
  only `KeyDown` and `TextInput`, so every mouse button, wheel and touch contact fell past the console
  into the run loop, which routes pointer input exclusively at `stream.capture` — `None` while
  browsing. New `Overlay::handle_pointer` carries mouse/touch in swapchain pixels; the run loop
  converts (it owns the window and hence display scale); the console hit-tests the rects it drew last
  frame. Only **direct** touch devices are offered — an indirect trackpad already drives the mouse.
  Widgets act on **press**, not release, because both carousels scroll the focused item toward centre
  and what you pressed would slide out from under your finger. Host menu on Up from a saved tile;
  `UpdateHost` edits **in place** (remove-and-re-add would silently drop the fingerprint, learned MAC,
  pinned cards and profile binding), and `ForgetHost` arms on first press and fires on second.
- **Discovery went permanently deaf three ways**, each needing an app relaunch: a failed resolve was
  never retried (`browseResultsChangedHandler` fires only when the result *set* changes, and a host
  whose resolve failed is still in the set); a stuck resolve never ended (`NWConnection` has no
  timeout, so the throwaway UDP flow could sit in `.preparing` forever, and a service with a
  connection in flight was skipped); and an `NWBrowser` parking in `.waiting` was ignored — **which is
  exactly where iOS's local-network privacy prompt lands on first launch, and granting it does not
  revive the browser that was already waiting.** A 1 Hz sweep now times out stuck resolves, retries
  failed ones on a 1→30 s backoff, and re-arms a dead browser; the advert's TXT is re-read on every
  browse report. `discovery::Rescan` forces a fresh mdns-sd query — the browse otherwise re-queries on
  a doubling backoff **capped at one hour**, so a long-lived browse is effectively passive. ⚠
  `clients/windows/src/discovery.rs` is a **second copy** of the browse that the earlier IPv4 pinning
  missed; it took an arbitrary first address, so a host whose OS responder answered AAAA rendered a
  card that failed on every click.
- **Phone gyro mirror**, off by default, player 1 / wire pad 0 only, and only while that pad has no
  motion source of its own. iOS/iPadOS only on Apple (`DeviceGyro` wraps `CMDeviceMotion` at ~100 Hz
  on a dedicated serial queue — the controller path's main-queue delivery is a known jitter source);
  Android phones with a gyroscope at ~200 Hz with `maxReportLatencyUs = 0`, since batching is poison
  for gyro aim. Both rotate from the device's natural frame into the controller frame by interface
  orientation, and both send **one zero-gyro sample on stand-down** — the host holds motion as state
  and re-emits it, so a leftover nonzero angular velocity reads as endless rotation.
- **Safe-area resolution** is purely a *sizing* change — no layout change, no input change; pointer
  mapping follows for free since both clients derive the picture rect from the live host mode. Full
  native height, width less left+right safe insets. Portrait settings screens report the housing on
  `top` with zero horizontal insets, so the portrait top inset stands in (gated so an iPad's status
  bar never fabricates one). Android adds the rounded-corner radius, which it does not count as
  cutout. Both even-floor and clamp, because `validate_dimensions` rejects odd dimensions and an inset
  subtraction lands odd about half the time.
- **Gamepad UI**: six sections (Stream · Video · Audio · Controller · Interface · Profiles, plus Input
  on the desktop console) walked with L1/R1 with per-section cursor memory; 12 palettes under one
  shared `ui_palette` key, Violet keeping its explicit sixteen colours so existing installs are an
  identity transform. Presentation only → **device preference, never part of a profile**. Palette
  maths ported three times (Rust/Swift/Kotlin) with the same assertions pinned in each language;
  `every_palette_is_multi_tone` fails under 45° hue spread and caught Ember at 35° and Graphite at 3°.
  Three render-only findings: additive blending blows out over a pale ground, a white scrim at the
  dark field's strength bleaches the gradient, and white glass over a bright field needs more body.

### Session and game lifetime

- **`PunktfunkEndReason` replaces a single "closed" bit** (ABI 17, additive, wire untouched). Five
  values — local, game exited, host ended, host error, lost — classified by the connection watcher
  from close codes already on the wire (`APP_EXITED_CLOSE_CODE` had been sent for a long time with
  nothing consuming it). **Latched before the shutdown flag**, because the two are read by different
  threads and the reason must never arrive second. Exposed as `punktfunk_connection_end_reason` +
  `is_normal()`. Shells fall back to the old wording when there is no verdict (older core, or a close
  that raced the read).
- **The Steam `Running` registry hint was an unbounded veto.** Honouring it reset the absence window
  every pass, so a flag Steam left set — Steam crashed, was closed first, the game re-parented —
  pinned a lease in `running` for the life of the host process. The absence timer now runs
  regardless; past `VETO_LIMIT` (30 s) with nothing of the game on the box, the session ends anyway
  and logs at WARN. Extracted as a pure `exit_confirmed(gone_for, hint_running)` with tests — the
  watch loop polls a live process table and cannot be unit-tested, which is exactly how the
  unbounded veto shipped.
- **New `launchreg.rs`: one record per `(client fingerprint, library id)`**, written at launch and
  independent of the termination policy. The old fingerprint-keyed reclaim only ran under
  `GameOnSessionEnd::Always`, so under the default `Keep` nothing was recorded — and a client retry
  re-sent `Hello::launch` verbatim, which the host obeyed unconditionally. Steam/Epic URIs hid it
  (the launcher just focuses the running copy) but a `gog:`/`custom:` target genuinely started a
  second instance over the same save files. The same retry also minted a fresh `launch_stamp`, so
  procscan refused to adopt a game older than 2 s and **a reconnected session lost game-exit
  detection for the rest of its life.** Identity now flows backwards from the watcher, which
  publishes the concrete `ProcRef`s it adopted; liveness is `Scanner::alive` over that recorded set,
  re-verified by `(pid, start)`. Tradeoffs: a `custom:` command with no detection hints stays
  `Unknown` forever (trading exit detection for not double-spawning), and `IN_FLIGHT_WINDOW` is a
  fixed 90 s, deliberately not `disconnect_grace_seconds`.
- **A launcher entry is `LeaseKind::Untracked` unconditionally**, checked ahead of
  `nested`/`child`/`spec`. Its lifetime previously depended on invisible state: launcher not running
  → live child → `Child` lease → quitting the launcher ended the session; launcher already running →
  command forwards and exits inside `SHIM_WINDOW` → `Untracked` → session persists. Steam Big Picture
  is a *mode*, not a process (and on a Deck it is always running); Heroic is single-instance
  Electron. The real trap was the GameStream path, whose `GsApp` intermediate silently dropped the
  field.

### Library and plugins

- **Store claims keep identity across the scanner-to-plugin handover.** `library.json` gains a v2
  `{entries, claims}` shape that reads the old bare array unchanged and rewrites on first mutation.
  `PUT /library/provider/{p}?store=<s>` claims a store; entries then surface as
  `<store>:<external_id>` rather than `custom:<id>`, so entry ids, GameStream app ids, client art
  caches and Moonlight pins all survive. One provider per store (409 otherwise); while a claim is
  held the matching built-in scanner is skipped, so the two never double-list.
- `GET/PUT /library/scanners` is now a **sources** endpoint over the same disabled-set file.
- New entry fields: `role: game|launcher`; launch kinds `steam_ui` (`bigpicture|desktop`),
  `launcher_ui` (platform-gated, 400 on invalid) and `xbox`.
- **Plugin kit 0.3.0** adds a `./library` subpath: `defineLibraryPlugin` plus ported total parsers —
  text VDF/ACF, the binary `shortcuts.vdf` walker with CRC-32 appid derivation, read-only immutable
  SQLite, a registry wrapper that refuses HKCU, path-confinement joins. `GET/PUT /__config` returns
  `{schema, value}` and persists raw, so a plugin with settings need not ship an SPA.

### Platform and packaging

- **The client's config writer** falls back to an in-place write when the atomic replace is
  unavailable, verifies it by reading the bytes back, and records the last persistence failure
  centrally so the UI can surface it. Scratch files are now per-process, closing a real collision
  between the five processes that write these stores (shell, session, console UI, CLI, Decky) — one
  could previously rename its half-written temp over another's target.
- **Host send pacing** gained a pure, unit-tested budget function: oversized frames are budgeted at
  the pacing rate with a 100 ms absolute ceiling rather than compressed into one frame interval.
  Steady-state schedules are byte-identical, the legacy behaviour stays reachable via an environment
  escape hatch, and the GameStream-compatible path is untouched.
- **Mid-session shard renegotiation is gated off for PyroWave sessions**, which parse the video
  stream in windows fixed at session start — re-sizing mid-stream would corrupt the parse. Those
  sessions get the next-session clamp only and are excluded from jumbo. The ABR decode-cap latch
  likewise does not apply to PyroWave, where adaptive bitrate is open-loop by design.
- **The Deck's Vulkan compatibility layer is built from source**, pinned to the same upstream
  revision as the host's own packaged build — bump both together. ~4 MB of app content replaces a
  94 MB external extension, and Flathub is no longer needed at install time. ⚠ `subprojects/vkroots`
  is a gamescope **submodule** and flatpak-builder clones submodules by default; declaring it again
  as an explicit source breaks the build during extraction. `glm` and `stb` are `.wrap` files, not
  submodules, and *do* need explicit sources.
- **Build-container images push to an authenticated registry endpoint**, and `:latest` is reconciled
  against the content key on every push to main — an out-of-band tag move is detected and repaired
  rather than silently inherited.
- **Windows pad drivers** publish their sequence counters with release ordering (the host was already
  loading with acquire and pairing with nothing) and serialize the output-ring publish. The
  `/dev/uhid` event ABI, previously transcribed into all five Linux gamepad backends, is consolidated
  into one module.

### Verification status

Honest about what has and has not been on hardware, because several things in this release have not:

- **Controller audio has never run on a real DualSense.** Its entire verification is unit tests and
  compile checks, and its rumble arbitration rests on an explicitly retracted assumption about
  whether the voice coils and the rumble motors are the same actuators. The evidence-based 500 ms
  idle window is correct either way, but the underlying exclusivity is unsettled. Android's arbiter
  is the evidence-based one; the desktop twin and the coil restore on Android's stop path are owed.
  Some Android OEM kernels refuse the isochronous claim outright, which degrades to ordinary rumble.
- The **plugin-UI origin split** is validated against a fake console and a fake plugin, not yet in a
  real browser.
- The **packaging default-on changes** have had no installer run or package build.
- **No launcher tile has been clicked on a real host** — the first source that would publish one does
  not exist yet.
- Desktop-audio, packet-sizing and iPad-pointer work is build-verified only.
- ⚠ **The FFmpeg-deletion milestone itself has never executed on a GPU.** It was gated on
  cross-clippy, 160 tests, a workspace check and an `ffmpeg` count of 0 in the client / 2 in the host.
  The software on-glass check, the D3D11 and VAAPI AV1 hardware legs and the field bake were all owed
  at merge; later commits closed some of that but not all. The "no FFmpeg" claim is verified by
  `cargo tree` and a notices-generator mention count, not by inspecting a shipped binary.
- ⚠ **`pf-vaadec` has never decoded a frame anywhere** — no VAAPI hardware was reachable. It is the
  *first* rung on Linux/Intel and unknown vendors; the evidence filter bars it there in favour of
  `pf-vkdecode`, but an explicit pin reaches it.
- **openh264 has never run on glass**; the H.264 software rung is unit-tested only.
- **`native-d3d11va` AV1 is deliberately `verified = false`** — one 25 s 4K60 session, no parity.
- **Split arbitration is opt-in and Linux-wired only**; the Windows arm is built and unit-tested but
  not on hardware. The 5120×1440@240 Main10 behaviour flip is explicitly unvalidated and is named as
  the first thing to re-measure.
- **Software throughput is unmeasured in general** — the CPU rung does 35–39 fps at 4K AV1 against a
  60 fps stream, which is why the backlog flush that triggered the rav1d abort happens at all.
- **The Apple mic fix is a proven root cause, not a verified session.** Its own commits call it "a
  strong inference plus one proven logic defect rather than a confirmed fix" and close "awaiting the
  reporter's on-device confirmation" — which nothing later in the range records. It also leaves a
  known gap: nothing reports whether the uplink actually opened, so the HUD still offers a Mute
  Microphone button over a session that may be sending nothing.
- **The Windows audio substrate is, by contrast, well-evidenced on hardware** — repeated "measured on
  the target box", a live bisect on a fresh endpoint, and a `micpitch` proof reading 440 Hz in →
  440 Hz out at exact peak. The one thing not evidenced is a real client speaking through the minted
  microphone end to end; the pitch proof is probe-driven.
- **The phone-gyro mirror is not recorded as hardware-verified** — remap matrices are pinned by unit
  tests in both languages, but there is no "played a game with a clip-on pad" evidence in the tree.
- **The iOS gamepad-UI pale-palette sweep on glass is still owed**, per its own commit.
- ⚠ **The CI runner scripts are hand-installed** (`/usr/local/bin/ci-docker-prune.sh`,
  `/usr/local/sbin/ci-docker-reclaim.sh`). Merging does not deploy them — both runner hosts need the
  files copied out of `scripts/ci/`, and the missing `192.168.1.58:5011` insecure-registry entry on
  one host is routed around, not fixed.