Files
hyprland-headless-stream-pl…/README.dev.md
T
HermenixandClaude Opus 5 a6a4094e6a Stage 3: vm-keyboard, and the helper derivation that never built
The keyboard's only purpose is that a client receives symbols, so a unit
suite alone was testing the shape of a request nobody answered --
docs/TODO/scroll-has-no-compositor-proof.md is the precedent. This is
the compositor proof: two nixosTests, 16 subtests each, real time, no
injected clock.

  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard
    test script finished in 281.06s   (16/16, exit 0)
  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard-de
    test script finished in 278.15s   (16/16, exit 0)

The victim, checks/lib/keyboard_target.py, decodes every keysym from the
keymap the COMPOSITOR forwarded rather than from a table of its own.
That is the mutation rule PLAN §14 asks for: a driver that stopped
uploading leaves the client with nothing to decode with, every key
arrives as `sym=?`, and the character assertions go red. A victim with
its own keymap would decode `hello` either way and the check would be
asserting that the check can spell.

What the client actually reported, which is the point of reading back
the application's state rather than the broker's intention:

  type A        [(30, 1, 'A'), (30, 0, 'A')]   masks [1, 1, 0, 0]
                -- evdev 30 decoded as A, so the mask arrived BEFORE the
                   key, and no code 42 anywhere
  key Return    [(28, 1, 'Return'), (28, 0, 'Return')]
  TTL expiry    [(42, 1, 'Shift_L'), (42, 0, 'Shift_L')] masks [1,1,0,0]
                -- lifted by the sweeper alone, mask cleared with it
  chord         depressed mask [4, 4] while Control held, still held
                   after the type returned

It runs TWICE because `sessions.keyboard.layout` reaches the uploaded
keymap through exactly one path -- `--xkb-layout` on the driver unit's
argv -- and one layout cannot tell that path from a hardcoded `us`:

  us:  symbols=pc_us_inet(evdev)  bytes=35572
       type y -> [(21, 1, 'y')]   type z -> [(44, 1, 'z')]
       type cafü -> exit 2, "scalar 3 (U+00FC) is not typeable", and the
                    client reported [] -- no prefix typed
  de:  symbols=pc_de_inet(evdev)  bytes=37532
       type y -> [(44, 1, 'y')]   type z -> [(21, 1, 'z')]   (swapped)
       type cafü -> {'chars': 4, 'ok': True}
                    client decoded ['c', 'a', 'f', 'udiaeresis']

Hyprland's own input:kb_layout is left at `us` in BOTH runs, so a client
that ignored our keymap would decode the us answer on the de machine.

The decisive subtest is "acquire takes the KEYBOARD as well as the
cursor". With session B holding keyboard focus because its window mapped
last, acquire on A delivered wl_pointer.enter AND wl_keyboard.enter to A
and wl_keyboard.leave to B, with focus == "warp". A check that asserted
only pointer delivery would have gone green while A had the cursor, B
had the keys, and the first keystroke of the lease went to B -- which is
exactly what one warp does. §B3's "one warp" and the Stage 0 review's
"do not assert enter on acquire" are superseded by the two-warp acquire,
and the header says so.

One deviation from §B3, with reasons in the header: its subtest 4 says
`type y` decodes to sym `z`, which is wrong for a victim that decodes
from the forwarded keymap -- the same paragraph requires that. `type y`
resolves keysym y against the uploaded layout and sends that layout's
code; the client decodes it back to `y`. The sym is `y` on both layouts
by construction. What differs is the CODE, the symbols name, and whether
ü is typeable at all, and those are what this asserts.

── AND A PRE-EXISTING BUG THE FIRST RUN EXPOSED ──────────────────────

checks/lib/session-tools.nix opened a heredoc with `<<EOF` and closed it
with an INDENTED `  EOF`. A delimiter has to be at column zero, so it
never closed: it swallowed the rest of the builder -- both `install`
lines and every self-test -- into the shim's own text. The derivation
built anyway, with `hhs-ipc-watch` alone in $out/bin:

  $ ls /nix/store/wy3lp3...-hhstream-session-tools/bin/
  hhs-ipc-watch

So hhs-pointer-target has NEVER existed in that derivation either.
vm-pointer execs that absolute path, and vm-keyboard failed the same
way: the broker reported `target exited immediately (exit code 127)`,
which is true about a path that was never created and says nothing about
why. hhs-ipc-watch's own first line was `  #!...`, indented, which is
not a shebang, so vm-ipc is affected too. The build-time self-tests that
exist to catch exactly this had themselves become heredoc text. The
unquoted delimiter also expanded the swallowed text, so the builder ran
`hhstreamd.ipc` as a command.

The shim is a writeTextFile now -- no delimiter to indent wrong -- and
`test -x` on all three programs is the guard that would have caught it.

NOT DONE, and it needs doing: vm-pointer and vm-ipc have not been
re-run. checks/default.nix says one VM at a time on this two-core box
and I did not want to perturb the keyboard runs. That they WOULD have
failed is read off the store listing above, not off a run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 20:23:14 +00:00

422 lines
22 KiB
Markdown

# Developing and testing `hyprland-headless-stream-plugin`
The interface everything here asserts is [`docs/CONTRACT.md`](docs/CONTRACT.md).
That document is authoritative: if a test and the code disagree, the document
decides, and if the document is wrong it gets a version bump, not an edit.
## Prerequisites
- Nix with flakes enabled.
- `/dev/kvm` readable, for the six VM checks. They are `nixosTest`s; without
KVM they still run, just slowly enough that the timeouts below get tight.
- No GPU. Nothing in the test suite needs one — the compositor runs on
Hyprland's headless backend over software rendering.
Nothing in the checks touches the host: no `/etc/nixos`, no network, and no
socket outside the build sandbox or the test VM.
## The dev shell
```bash
nix develop
```
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH
and sets `PYTHONPATH=$PWD/src`, so `import hhstream` picks up the working tree
rather than an installed copy.
## Build
```bash
nix build .#hhstream # the package
ls result/bin # hhstream-server, hhstream-client, hhstream,
# hhstreamd, hhstream-pointer
```
Five entry points: the frame server and a reference reader for it, the `hhstream`
front-door CLI (frames, `run`, and the `session` namespace), the session broker,
and the pointer driver.
## The checks
| Check | What it proves | Needs a VM |
|---|---|---|
| `unit` | the framing, the capture backend, the server's client handling, the broker, the CLI, the containers, the lease and the pointer driver — in-process, against the `nix/package.nix` build | no |
| `vm-basic` | the NixOS module brings up both units and publishes a contract-conformant socket, with a **fake** capture backend | yes |
| `vm-hyprland` | the same, capturing the **real** headless compositor through `grim` | yes |
| `vm-sessions` | the **session broker**: a real GUI application launched into the compositor as a tracked session, seen by the compositor's own IPC, killed as a tree, reaped on its idle deadline (and *not* reaped when touched), and adopted back after the broker restarts | yes |
| `vm-ipc` | the **compositor's IPC**: both sockets exist at the names `docs/CONTRACT-sessions.md` §5 freezes and fit inside `sun_path`, `hyprctl` answers, the broker's own `HyprlandIPC` reaches it, and a subscriber on the **event** socket receives an `openwindow` for a window the test creates | yes |
| `vm-containers` | one `hh-*` output per session at the container mode, the application's window on it, a second window of the same application beside it, an unmatched window **quarantined**, `grim -o` capturing that container alone, and teardown removing the output and freeing its workspace slot | yes |
| `vm-pointer` | the **lease and the driver**: a version-2 virtual pointer, a warp that lands where it was aimed *as the application reports it*, a click delivered as one press and one release, a contended acquire refused with BUSY, an expired lease swept with its held button lifted, and a broker restart that leaves the lock free, the bookmark intact and the driver reachable | yes |
All of them at once:
```bash
nix flake check -L
```
`nix flake check` stops at the first failing check, which makes it a poor way to
see the whole picture while the tree is still red. **Run the VM checks one at a
time** anyway — each boots a guest with a software-rendered compositor, and two
at once on a two-core machine make the timing-sensitive assertions flake. A
flaky green is worth less than a slow one.
```bash
nix build -L .#checks.x86_64-linux.unit
nix build -L .#checks.x86_64-linux.vm-basic
nix build -L .#checks.x86_64-linux.vm-hyprland
nix build -L .#checks.x86_64-linux.vm-sessions
nix build -L .#checks.x86_64-linux.vm-ipc
nix build -L .#checks.x86_64-linux.vm-containers
nix build -L .#checks.x86_64-linux.vm-pointer
```
`-L` is not optional in practice: without it, Nix hides the build log, and the
build log *is* the test report. Do **not** pipe a check into `tail` or `grep`:
the pipeline's exit status is the last command's, so a build that cannot fail
is not a test. Redirect to a file instead.
Each VM check's test script is type-checked before the guest boots, which is
much cheaper than finding a typo after a five-minute boot:
```bash
nix build -L .#checks.x86_64-linux.vm-pointer.driver --no-link
```
Watch for names the driver already defines — `log` is an `AbstractLogger` in
that namespace, and assigning a string to it is a type error, not a shadowing
warning.
### `unit`
pytest over `tests/unit/`, run in the build sandbox with `PYTHONPATH` pointing at
what `nix/package.nix` installed (`nix/package.nix` sets `doCheck = false` on
purpose, so this is the only place the suite runs in a build).
The check fails if the suite is **empty**, not just if it is red. `pytest` exits
5 on "collected nothing", but it exits 0 when every test was skipped or
deselected, so `checks/lib/check_report.py` parses the JUnit report and refuses
a run with zero collected or zero executed tests. A green check that tested
nothing is worse than no check. On success the report is copied to
`result/junit.xml`.
To run the same tests directly, without Nix:
```bash
nix develop
pytest tests/unit -v # PYTHONPATH=$PWD/src comes from the shell
pytest tests/unit/test_protocol.py -v # one file
pytest tests/unit -k "hello or frame" -v # one theme
pytest tests/unit -x --ff # stop at the first failure, failures first
```
Note that the unit suite's *negative* tests use the `rejects` fixture from
`tests/unit/conftest.py` rather than `pytest.raises(Exception)`. `rejects`
treats `NotImplementedError` as a failure, because a plain `raises(Exception)`
is satisfied by an unimplemented stub — the test would then be green precisely
because nothing had been written.
### `vm-basic`
Boots one machine with `services.hyprland-headless-stream.enable = true` and
`captureCommand` pointed at `tests/fake_capture.py`, which writes one fixed,
deterministic PNG of the configured size to stdout. Because the image never
changes, "two frames arrived and they are the *same bytes*" is a real assertion
about the framing rather than a coincidence.
It checks, in order: both units start; the socket exists and is
`hhstream:hhstream` mode `0660`; the Hello parses with `magic = "HHS1"` and
non-zero width/height matching the configured output; two frames arrive with
length > 0, identical bytes, and an IHDR matching the Hello; two clients are
served concurrently; and a client that dies mid-frame leaves the server serving.
The reader is `tests/assert_stream.py`, a second, independent implementation of
the contract that shares no code with `hhstream.client` — so a framing bug
present in both the server's writer and the shipped client's reader still fails
the test. It validates the length prefix strictly (`0|[1-9][0-9]*`: no leading
zeros, no sign, no spaces), never reads past a newline, and prints the Hello,
every frame's size and SHA-256, and the parsed IHDR before it decides anything.
### `vm-hyprland`
The same machine with **no** `captureCommand` override, so the module's default
(`grim`) captures the real compositor.
This is the check expected to be flaky, so it is deliberately impatient: every
wait has a bounded timeout, nothing is retried in a loop, and any failure dumps
diagnostics before it propagates. It asserts a frame is a valid PNG whose IHDR
dimensions match the configured output, and that it is more than a blank buffer:
- the IDAT must decompress;
- the decompressed scanlines must contain a non-zero byte and at least two
distinct byte values — a zero-filled framebuffer fails both;
- the payload must be larger than a best-case blank PNG of the same geometry
(`blank_png_size()` in `tests/assert_stream.py`: an all-zero raster at zlib
level 9, i.e. the smallest a blank frame of that size can be encoded).
It also runs `grim` directly against the session as a separate subtest, which
separates "grim cannot see the compositor" from "the server is wrong" — the two
failures that look identical from the socket.
## When `vm-hyprland` fails: where the logs are
Every failing subtest in both VM checks runs `hhs-hyprland-diagnostics`
(`tests/hyprland_diagnostics.sh`) in the guest first and prints its output to the
build log. So the answer to "where are the logs" is usually **in the build log
you already have**, above the traceback, between
`########## diagnostics: ... ##########` markers. Re-read it with:
```bash
nix log .#checks.x86_64-linux.vm-hyprland
```
What the dump contains, and where it comes from in the guest:
| Section | Source |
|---|---|
| `units` | `systemctl list-units --all 'hyprland*'` |
| per-unit `status` / `journalctl` | `hyprland-headless.service` and `hyprland-headless-stream.service`, 200 lines each |
| `socket and runtime directories` | `/run/hypr-stream`, `/run/user/*` |
| `hyprland logs` | every `hyprland*.log` found under `/run`, `/var/log`, `/tmp`, `/home` |
| `hyprctl monitors` | run once per instance found, with the right `XDG_RUNTIME_DIR` and `HYPRLAND_INSTANCE_SIGNATURE` |
| `processes` | `ps aux` filtered to `hypr`, `hhstream`, `grim` |
Hyprland writes its log to
`$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log`, and the
compositor runs on a *private* `XDG_RUNTIME_DIR`, so the path is not knowable in
advance — that is why the script searches for it rather than naming it. The
instance signature is the directory name under `<runtime>/hypr`, which is also
what `hyprctl` needs in the environment:
```bash
XDG_RUNTIME_DIR=/run/user/$(id -u hhstream) \
HYPRLAND_INSTANCE_SIGNATURE=$(ls /run/user/$(id -u hhstream)/hypr | head -1) \
hyprctl monitors
```
### Poking at a live VM
The nicest way to debug a VM failure is to keep the machine:
```bash
nix build .#checks.x86_64-linux.vm-hyprland.driverInteractive
./result/bin/nixos-test-driver
```
That drops you in a Python REPL with `machine` bound. `start_all()`, then
`machine.shell_interact()` for a root shell in the guest, or run the test script
a line at a time. `machine.succeed("hhs-hyprland-diagnostics")` works there too.
## Layout
```
checks/
default.nix wiring only: the checks the flake exposes
unit.nix pytest in the sandbox, against the nix/package.nix build
vm-basic.nix nixosTest, fake capture backend
vm-hyprland.nix nixosTest, real compositor + grim
vm-sessions.nix nixosTest, the broker's lifecycle against the compositor
vm-ipc.nix nixosTest, the compositor's request and event sockets
vm-containers.nix nixosTest, one output and one workspace per session
vm-pointer.nix nixosTest, the lease, the driver and a click that lands
vm-keyboard.nix nixosTest, the uploaded keymap, keyboard focus, and a
symbol a client decoded. Exposed TWICE -- `vm-keyboard`
(layout us) and `vm-keyboard-de` -- because the layout
reaches the keymap only through the driver unit's argv
lib/test-tools.nix packages the tests/ helpers for the guest
lib/session-tools.nix packages the two guest programs below
lib/session-machine.nix the guest the three session checks share
lib/session-prelude.nix their test-script helpers (no assertions live here)
lib/gpu-session.nix the hardware a bare test machine does not have
lib/check_report.py JUnit report -> build verdict (and the empty-suite guard)
lib/ipc_watch.py subscribes to the event socket: hhs-ipc-watch
lib/pointer_target.py a Wayland window that reports pointer events it receives:
hhs-pointer-target
lib/keyboard_target.py a Wayland window that reports KEY events, decoded with
the keymap the compositor forwarded: hhs-keyboard-target
tests/
fake_capture.py writes one fixed PNG to stdout: hhs-fake-capture
assert_stream.py independent contract reader/asserter: hhs-assert-stream
hyprland_diagnostics.sh the failure dump: hhs-hyprland-diagnostics
keyboard_probe.py THROWAWAY: measures the compositor's keyboard behaviour
against the live socket. See README-keyboard-probe.md
and the transcript beside it; delete both once
checks/vm-keyboard.nix asserts the same properties.
unit/ ipc/ containers/ pointer/ sessions/ the pytest suite
```
`checks/lib/test-tools.nix` and `checks/lib/session-tools.nix` self-test their
programs at build time (the fake emits a PNG of the size it was asked for; the
asserter starts; the event subscriber can import the broker's IPC client; the
pointer target refuses to start without an app id), because a broken helper
otherwise surfaces as a baffling failure three layers away.
`hhs-ipc-watch` deliberately runs the **shipped** `hhstreamd.ipc.HyprlandIPC`
rather than a second implementation — the opposite choice from
`tests/assert_stream.py`. The difference is what each proves: `assert_stream`
asserts a wire format two programs must agree on, so a shared bug must still
fail it; `vm-ipc` asserts that *this* client receives events from *this*
compositor, which a reimplementation could not say anything about.
`hhs-pointer-target` exists because no application in nixpkgs does both of the
things the session checks need: set its `xdg_toplevel` app id from
`$HHSTREAM_APP_ID` (so its window matches its session's container rule) and
print the pointer events it receives with the coordinates it was given.
`foot` and `wev` do neither and ignore the environment entirely, which makes
them good *unmatched* windows and useless as matched ones.
`hhs-keyboard-target` is its sibling, and the thing that makes it a separate
program rather than a flag is **where its symbols come from**: it compiles the
keymap the compositor forwarded over `wl_keyboard.keymap` and decodes every key
through that. A client with its own keymap would decode `hello` whether or not
the driver ever uploaded one, so the check would be asserting that the check
can spell. It is also why `session-tools.nix` builds it against a python with
`xkbcommon` while the pointer target gets one with only `pywayland`.
Adding a unit test: drop a `test_*.py` under `tests/`. Nothing needs
registering, but the basename must be unique across the tree. Adding a check:
one file in `checks/`, one line in `checks/default.nix`.
## Typing into a session: the keyboard layout
Keys reach whichever surface the compositor's one seat has focused. A virtual
keyboard is seat-global and has no output argument, so unlike the pointer there
is nothing to aim — what aims it is the pointer, and `pointer acquire` takes
both (see item 3 under the known gaps for why that is two warps and not one).
```bash
hhstream session pointer acquire <id> # also authorises typing
hhstream session keyboard type <id> 'hello world' # one argument, raw UTF-8
hhstream session keyboard key <id> Return # a tap: down then up
hhstream session keyboard down <id> Control_L # a chord, held
hhstream session keyboard type <id> c # ...is Ctrl+C
hhstream session keyboard up <id> Control_L
hhstream session pointer release <id> # lifts buttons AND keys
```
`hhstream session pointer state` reports held keys beside held buttons.
### The layout is an operator setting
**The driver compiles one XKB keymap at start-up and uploads it once. That
keymap is the only thing that decides what an injected key means.** Every verb
names an XKB *keysym* — `a`, `A`, `Return`, `BackSpace`, `Left`, `Control_L` —
and the driver resolves that name against the keymap to get the evdev code and
the modifier mask the compositor is sent.
| Option | Default | Notes |
| --- | --- | --- |
| `services.hyprland-headless-stream.sessions.keyboard.layout` | `"us"` | One group only: the option's type refuses `us,ru`, and so does the driver |
| `…sessions.keyboard.model` | `"pc105"` | |
| `…sessions.keyboard.variant` | `""` | A variant whose characters are *dead keys* (`us(intl)`) cannot be typed by v1 |
| `…sessions.keyboard.options` | `""` | Passed to `xkb_keymap_new_from_names`; a value it rejects stops the driver with exit 2 |
```nix
services.hyprland-headless-stream.sessions.keyboard.layout = "de";
```
Three things worth knowing before an agent types anything:
1. **Hyprland's own `input:kb_layout` is not read and has no effect on
injected keys.** It describes the layout for physical keyboards, of which a
headless session has none, and reading it would mean a `hyprctl` reload
could silently change what every agent types. The two can therefore
disagree, and only the option above matters.
2. **A character the layout cannot produce fails the whole string.** There is
no partial type: `keyboard type <id> 'café'` on `us` is exit 2 and emits
nothing, rather than typing `caf` and stopping. The refusal names the scalar
*index*, never the character and never the string, because a typed string is
a password as often as not and these messages are logged. The audit log
records a character count and nothing else.
3. **`keyboard down` of a non-modifier floods the window.** The compositor
sends one key event and publishes a repeat rate; the *application* repeats,
so a held `a` inserts characters until the key-up or the lease TTL (default
30 s). Measured on this build at 25/s after 600 ms. It is not ours to
rate-limit — we do not generate the repeats — so the only safe hold is a
modifier, which is what chords are for.
The layout reaches the driver as `--xkb-layout` on `hhstream-pointer`'s command
line, and **only** there. It is deliberately not a key in the broker's TOML:
that file is read by `hhstreamd`, and the driver is a different unit that never
opens it, so a `[keyboard]` table there would be a setting an operator could
change while every injected key stayed on `us`.
## Known gaps in the interface (as of this branch)
Every item the previous revision of this section listed is closed: the module
has a `config` side, `package` has a default, `src/hhstream/*.py` is written,
and the frame server's command line is the one the module passes. What is open
is below. These are defects in code this branch does not own; they are recorded
here because the checks are written against the contract and therefore trip
over them.
The deep versions of these — the issue, more than one idea, and why each one
matters — live in [`docs/TODO/`](docs/TODO/README.md). Update the file there
when one closes, so this list stays a description of what is still true.
1. **The container host can be switched off, and the broker now honours it.**
*(This item previously read "the broker reads none of the container or
pointer configuration." That is fixed: `policy.py` parses those settings
beside `Policy`, read in `__main__`, and a host that is switched off reports
itself unavailable with the reason naming the key — so a disabled machine
cannot be mistaken for one whose compositor is down. The reason it matters is
what follows.)* Containers are consequently **off on the deployment machine**:
no window can be put in one yet, and enabling them quarantines every
allowlisted app. That join is the first item in `docs/TODO/`.
2. **`session start --no-container` is refused, not honoured.** PLAN §9 lists
the flag; `docs/CONTRACT-sessions.md` §4 leaves `start` unchanged, and
`SessionManager.start` takes no such argument. A request carrying a
`no_container` field would be accepted and ignored, and the session would
get a container anyway — so the CLI exits 2 and names the disagreement
instead of lying about what it did.
3. **Fixed: `nix/hyprland-conf.nix` sets `input:follow_mouse = 1`.** *(This
item previously said it ships `0`, that pointer input therefore reaches
nothing but the focused window, and that whether to change it was a
decision for the keyboard work. The conf file sets `1`, and the keyboard
work has made that decision; what follows is why, and what is left.)*
The original measurement, by `vm-pointer`, with two sessions and the second
holding focus because its window opened last:
```
aimed at target-le22h7: it reports [] <- the session the warp named
focused is target-s76taj: it reports [] <- the session with focus
cursor now at {'x': 2048, 'y': 288} <- exactly where it was aimed
```
With `0`, the compositor moved the cursor to the right pixel, inside the
right window, on the right output, and told no client at all. That defeats
the point of containers and the lease, so the conf sets `1`.
**What is left, and it is a real limitation.** `follow_mouse = 1` moves
keyboard focus too — which is what makes typing possible at all, since a
virtual keyboard is seat-global and has no output to aim. But **one warp
does not move it.** Measured directly against the live compositor
(`tests/README-keyboard-probe.md`): an idle `motion_absolute` onto an
unfocused window delivers `wl_pointer.enter` and no `wl_keyboard.enter`,
because `mouseMoveUnified` zeroes `m_mousePosDelta` when the previous
movement was over 0.5 s ago and keyboard focus is that delta compared
against `input:follow_mouse_threshold`.
So `pointer acquire` sends **two** warps, a real pixel apart, and takes the
keyboard as well as the cursor. The conf now sets
`follow_mouse_threshold = 0` explicitly rather than inheriting the default,
because that is what the second warp depends on; raise it and acquire stops
taking keyboard focus. `dispatch focuswindow` is the fallback if the nudge
cannot be sent, and the acquire reply's `focus` field says which ran.
4. **A container's window rule only binds for an application that reads the
environment.** The broker's only lever on an application's class is
`$HHSTREAM_APP_ID` and the three toolkit variables beside it
(`hhstreamd/launcher.py`), so a GTK or Qt application — and `foot`, and
`wev` — keeps its own class, matches no per-session rule, and is swept into
the quarantine workspace. That is reported by the read-back rather than
papered over, and it is why `vm-containers` and `vm-pointer` use a
cooperating client (`hhs-pointer-target`) for the matched case and `foot`
for the unmatched one. Closing it needs a per-app `--app-id` in the
allowlist, which is a policy change.