Compare commits

...
+126
View File
@@ -0,0 +1,126 @@
# Make the Hyprland session look like a normal Linux desktop
Plan only. Nothing here was edited, rebuilt, or measured live. The diagnostic shell (`hyprctl monitors`, `systemctl cat`, `/dev/dri`, portals, audio) was cancelled before it ran. Every live fact below is either from files that were read or from older Chromium logs already on disk. Anything not in those sources is marked unverified.
## What was read
- `/etc/nixos/hyprland-stream.nix` — outputs, capture, session allowlist, fonts, cursor theme, window rule
- `/etc/nixos/common.nix` — QEMU guest, `chromium` on `systemPackages`, `hermes` groups, no audio/portal/timezone block
- `nix/module.nix` — compositor environment, `WLR_*`, `SEATD_VTBOUND`, session broker, what apps inherit
- `nix/hyprland-conf.nix` — generated `hyprland.conf` (cursor, input, `disable_xdg_env_checks`)
- `src/hhstream/capture.py` — `grim` to stdout; capture does not name an output
- `src/hhstreamd/containers.py` — `hyprctl output create headless hh-<session-id>`
- `src/hhstreamd/launcher.py`, `src/hhstreamd/compositor.py` — app environment
- `examples/agent-eyes` — `run` only sets `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`, `XDG_SESSION_TYPE`
- `docs/ARCHITECTURE.md` (full). `docs/CONTRACT.md` and `docs/CONTRACT-sessions.md` were searched, not read end to end. Container output name `hh-<session-id>` is frozen in the sessions contract.
- `/var/lib/hermes/.hermes/skills/devops/agent-eyes/SKILL.md` and `headless-wayland-compositor/references/browser-fetch-and-cdp.md`
The SwiftShader flags are **not** in that skill, the allowlist, or `examples/agent-eyes`. They appear in one recorded command (`~/.hermes/logs/process-results/proc_a2b2e2384799.json`): `agent-eyes run -- chromium … --use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader … https://discord.com/register`. Older Chromium logs (`proc_53cbb1c64842.json`, `proc_ecc7dddf484a.json`, `proc_3edb9a456ba3.json`) show `virtio_gpu_drv_video.so` init failure, `WebGL1 blocklisted`, and UPower `DisplayDevice` `ServiceUnknown`. Those logs still mention `XDG_RUNTIME_DIR=/run/hyprland-headless-stream` (the old path). The runtime dir in the current module is `/run/hypr-stream`.
## 1. Signal inventory
A page cannot see Hyprland output names, kernel input names, or `XDG_*`. Those matter only when they change something the page *can* read (WebGL, `screen`, media devices, `Intl`).
| Signal | Evidence | What a page actually sees | Live check |
|---|---|---|---|
| SwiftShader forced on | Ad-hoc `agent-eyes run` argv above. Not in the Nix allowlist, so `hhstream session start chromium` would reject those args. `agent-eyes run` execs them as-is. | `WEBGL_debug_renderer_info` / WebGPU adapter info. Stock SwiftShader strings are `Google SwiftShader` and device id `0x0000C0DE`. **The exact string on this box was not read back.** | Unverified |
| WebGL context dies without those flags | Same logs: `ContextResult::kFatalFailure: WebGL1 blocklisted` and a failed GPU command buffer | `getContext('webgl')` is null. That is its own automation signal. | From old logs, not a new probe |
| Virtio GPU present, video init fails | `libva error: …/virtio_gpu_drv_video.so init failed`, `vaInitialize failed`. `hardware.graphics.enable = true`. This is a QEMU guest (`common.nix` imports `qemu-guest.nix`). | Hardware decode missing (`mediaCapabilities`). The GL renderer string without SwiftShader flags was **not** captured. Likely Mesa virgl or llvmpipe, not NVIDIA/AMD/Intel. | Renderer string unverified |
| `/dev/dri` missing | **Not supported.** Architecture says the compositor will not start without a render node, and the VAAPI path found a virtio-gpu driver. | Nothing, if the node exists. | `ls /dev/dri` was not run |
| `hermes` cannot open the render node | `hermes.extraGroups` is `wheel`, `systemd-journal`, and `hhstream`. The compositor user gets `video` and `render`. Chromium runs as `hermes`. | Browser falls back to software GL or a blocklisted WebGL context. This is the likely reason SwiftShader was added by hand. | Groups were not read from the running session |
| Main output name | Module does **not** create the main output. The monitor rule uses an empty name (wildcard). Comments say `Virtual-1` on virtio, `eDP-1` on a laptop. `WLR_BACKENDS=headless` is set and documented as ignored by current Hyprland (aquamarine). | Not visible on `window.screen`. `getScreenDetails().label` might echo the wl_output name, and only after a permission prompt. **Not verified in this Chromium.** | `hyprctl monitors` was not run. Do not assume the name is `HEADLESS-1`. |
| Per-session output | `containers.enable = true` (trial, dated 2026-10-03). `containers.py` runs `hyprctl output create headless hh-<id>`. Contract freezes that name. | Same as above, and only if the window is actually on that output. The Nix comment says Chromium ignores the app-id stamp, so the window may miss the container. | Unverified whether any `hh-*` output exists now |
| Screen 1280×720 @ 30 Hz, scale 1 | `outputs` in `hyprland-stream.nix`; container default `1280x720`. Window rule `size 1040 560`. Launch recipe `--window-size=1040,560`. | `screen.width/height`, `devicePixelRatio` 1. Refresh rate is not on `window.screen`. 720p is a weak signal, not a headless label. | Mode unverified live |
| No real input devices | `WLR_LIBINPUT_NO_DEVICES=1`. Pointer is `zwlr_virtual_pointer_v1` (`hhstream-pointer`). Generated config sets `cursor.invisible = true`. | A page does **not** see kernel or libinput names. Compositor-delivered clicks are real Wayland events; `isTrusted` was not measured. CDP input (`Input.insertText` in the skill) is a separate, stronger tell. No keyboard injector exists (`wtype` / `ydotool` are called out as not installed). | Device list unverified |
| `navigator.webdriver` / headless UA | Allowlist and the skill do **not** pass `--enable-automation` or `--headless`. They do pass `--remote-debugging-port` and `--remote-debugging-address=127.0.0.1`. | `navigator.webdriver` should be false and the UA should not contain `HeadlessChrome`. **Not evaluated in a page.** The open DevTools port is not visible to the origin. Attaching CDP and typing through it is. | Unverified |
| Runtime dir not owned by the app | Compositor `XDG_RUNTIME_DIR=/run/hypr-stream`, owned by `hhstream`. Broker and `agent-eyes run` point the app at that same directory. Old log: `XDG_RUNTIME_DIR (…) is not owned by us (uid 1000), but by uid 994`. | Not visible as a string. Chromium then skips Pulse, portals, and dconf. That shows up as empty media devices and failed permission UIs. | Old path only; current path not re-checked |
| Desktop env not set | App env from `CompositorSession.env()` is only `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`, `XDG_SESSION_TYPE=wayland`. Compositor also sets `HYPRLAND_NO_SD_VARS=1`, so it does not publish a desktop session. `HOME` for the compositor unit is `/run/hypr-stream`; for broker apps it is the hermes home. | Pages do not read `XDG_*`. GTK/Qt and Chromium's own desktop integration do. | Unverified in `/proc/<pid>/environ` |
| No portal | `disable_xdg_env_checks = true` because "the XDG portal environment" is not there. Neither Nix file enables `xdg.portal`. | No direct JS API. Clipboard, file choosers, and screencast fail. Not the Discord signup check. | Service state unverified |
| No audio server | No PipeWire, Pulse, or WirePlumber in either Nix file. | `enumerateDevices()` has no `audioinput` / `audiooutput` (kinds can leak before permission). | Unverified |
| No UPower | Chromium log: `org.freedesktop.UPower` `ServiceUnknown`. No upower module in the files read. | `navigator.getBattery()` fails. A tower desktop also has no battery, so this is a weak "VM" tell and a bad thing to fake as a laptop. | From old logs |
| Fonts | `fonts.packages = [ pkgs.dejavu_fonts ]` only, added so `foot` has a monospace. | Canvas / `document.fonts` look like a minimal Linux install, not specifically headless. Emoji and metric-compatible faces are absent. | `fc-list` was not run |
| Locale and timezone | Neither file sets `i18n.defaultLocale` or `time.timeZone`. The session unit does not set `LANG` or `TZ`. | `Intl.DateTimeFormat().resolvedOptions().timeZone` and `navigator.languages`. A VM left on UTC is a datacenter tell if the operator is not in UTC. **The live zone was not read.** | Unverified |
| Fresh profile every launch | Skill and the Discord command use `--user-data-dir=/tmp/eyes-profile-$$` (or a one-off `/tmp` dir). | Empty cookies, storage, and history. Behavioral, not a renderer string. | n/a |
Not listed, because nothing read supports them: a kernel input device whose name contains "headless"; `navigator.webdriver === true`; a UA containing `HeadlessChrome`; a missing `/dev/dri`.
## 2. What we can change
**Stop forcing SwiftShader.** Do not add those three flags to `sessions.apps.chromium.argsAllow`. `agent-eyes run` bypasses the allowlist, so a wrapper has to be the binary both paths exec. Wrapper lives in the NixOS module (`sessions.apps.chromium.exec`) and the skill's launch recipe points at it. Flags to keep: `--ozone-platform=wayland`. Flags to refuse: `--use-angle=swiftshader`, `--enable-unsafe-swiftshader`, `--enable-automation`, `--headless`. Do not spoof `UNMASKED_RENDERER`. Overriding `getParameter` in the page is itself detectable.
**Let Chromium open the same render node the compositor uses.** Add `video` and `render` to `users.users.hermes.extraGroups` in `hyprland-stream.nix`, and restart `hhstream-sessions` so the broker picks up the groups. An already-open SSH session will not see them until a new login. `agent-eyes run` from that SSH session still needs a new login or `sg`. This is the best chance of a real Mesa renderer (virgl) instead of SwiftShader or a null WebGL context.
**Give apps a runtime dir they own.** `CompositorSession.env()` and `examples/agent-eyes` `cmd_run` should set `XDG_RUNTIME_DIR` to hermes' `/run/user/<uid>` (linger is already on) and put a symlink to the compositor's `wayland-N` socket there. Toolkits resolve `WAYLAND_DISPLAY` against `XDG_RUNTIME_DIR`, so the symlink is required. Also set `XDG_CURRENT_DESKTOP=Hyprland` and `XDG_SESSION_DESKTOP=Hyprland` on the app, not by clearing `HYPRLAND_NO_SD_VARS` on the compositor unit. The frame server and `grim` stay on `/run/hypr-stream`.
**Desktop services, after that runtime-dir fix.** In `hyprland-stream.nix` (session-specific, not the whole guest image):
- PipeWire + WirePlumber. No sound card was verified; a null sink is the honest stand-in.
- `xdg.portal` with the GTK portal. The Hyprland portal only after it can see this compositor's IPC, which is not the user session's.
- `upower` so the D-Bus name exists. Do not invent a charge percentage.
- Fonts next to DejaVu: a sans/serif metric set (Liberation or Noto), plus Noto Color Emoji.
**Timezone and locale** belong in `common.nix` (`time.timeZone`, `i18n.defaultLocale`), set to the operator's real zone. The files do not say what that zone is. Do not guess.
**Resolution, only if capture still fits.** 1920×1080@60, scale 1, in `outputs` and `sessions.containers.mode`. Keep the window smaller than the output (the wallpaper is intentional). JPEG q80 at 1280×720 was measured at ~46 ms in the Nix comments; 1080p is about 2.25× the pixels. If `grim` goes much past that, stay at 720p. Do not set `outputs[].name` to `DP-1` or `HDMI-A-1`: a monitor rule whose name matches nothing is silently ignored and the mode never applies.
**Do not rename `hh-*` outputs.** The sessions contract, `grim -o`, pointer binding, and reconcile all use that name. A page almost certainly never reads it.
**One durable Chromium profile** for the signup browser, under `/var/lib/hermes/hhstream-sessions/`, not `/tmp/eyes-profile-$$`. Keep per-run profiles only when two browsers must run at once (Chromium exits if the profile is locked).
**Leave the cursor config alone** in this work. `invisible = true` is in the generated conf and the extraConfig does not turn it off. That affects captures, not fingerprinting.
## 3. What cannot be faked
There is no physical GPU on this guest. The GL string will be Mesa on virtio-gpu, or llvmpipe if virgl does not come up. Both are software-ish VM strings. SwiftShader is worse because `0x0000C0DE` is a known headless-Chrome id. Claiming Intel, AMD, or NVIDIA from stock Chromium is not possible, and a patched Chromium or a JS lie is a louder signal than llvmpipe.
There is no monitor EDID and no physical seat. Renaming an output `DP-1` does not create one. Websites do not read EDID.
`navigator.getBattery()` failing is normal for a desktop tower. A fake laptop battery would disagree with the rest of the machine.
WebRTC can still expose the guest address `10.77.0.2` and the hostname `hermes` (`common.nix`). That is a VM tell, not a "headless Linux" string. Confirm with a page before adding a WebRTC policy flag; do not add it speculatively.
Typing still goes through CDP unless a keyboard injector is added later. Pointer events from `zwlr_virtual_pointer_v1` are the less detectable input. This plan does not add a keyboard.
Discord's phone wall was not reproduced here. The Google signup note (`web-account-signup/references/google-signup.md`) records the same class of wall on this desktop, and it does not say which signal Google used. Fixing the rows above removes the signals we can point at. It does not guarantee the wall goes away.
## 4. Staged plan
**Stage 0 — baseline, no changes.** Small. Run, and save the output:
```bash
sg hhstream -c 'XDG_RUNTIME_DIR=/run/hypr-stream HYPRLAND_INSTANCE_SIGNATURE=$(basename /run/hypr-stream/hypr/*) hyprctl -j monitors'
sg hhstream -c 'XDG_RUNTIME_DIR=/run/hypr-stream HYPRLAND_INSTANCE_SIGNATURE=$(basename /run/hypr-stream/hypr/*) hyprctl -j devices'
ls -l /dev/dri
id hermes
systemctl is-active hyprland-headless hyprland-headless-stream hhstream-sessions hhstream-pointer
```
Then one windowed Chromium **without** SwiftShader flags, and one CDP `Runtime.evaluate` of: WebGL vendor/renderer (or null context), `navigator.webdriver`, `navigator.userAgent`, `screen.width/height/devicePixelRatio`, `Intl.DateTimeFormat().resolvedOptions()`, `navigator.languages`, `enumerateDevices()` kinds, and `getBattery()`'s rejection. That sheet is the only acceptance test that matters.
**Stage 1 — wrapper, stop SwiftShader.** Small. Nix wrapper as `chromium`'s `exec`; skill recipe updated; allowlist does not grow those flags. Proof: `/proc/<pid>/cmdline` has no `swiftshader`; the Stage 0 WebGL expression no longer returns SwiftShader. If the context is null, Stage 1 is incomplete and Stage 2 is the fix, not turning SwiftShader back on.
**Stage 2 — `render`/`video` for `hermes`.** Small config, needs a new login and a broker restart. Proof: same WebGL expression returns a Mesa/virgl (or llvmpipe) string, and the log has no `WebGL1 blocklisted`.
**Stage 3 — user-owned `XDG_RUNTIME_DIR` plus desktop variables.** Medium. `compositor.py` and `agent-eyes` `cmd_run`. Proof: Chromium's stderr does not contain `not owned by us`; a launched `foot` prints `/run/user/<uid>`. Run `checks.vm-sessions` and `checks.vm-pointer` (one at a time; they are timing-sensitive). Failure mode to watch: `Failed to connect to Wayland display`.
**Stage 4 — PipeWire null sink, GTK portal, upower, fonts, real timezone.** Medium, NixOS only, after Stage 3. Proof: `wpctl status` shows a sink; `busctl status org.freedesktop.portal.Desktop` and `org.freedesktop.UPower` are active; `fc-match sans` and `fc-match emoji` hit the new faces; the page's `enumerateDevices()` includes `audiooutput`; Chromium's log no longer says UPower `ServiceUnknown`; `Intl` timezone matches `timedatectl`.
**Stage 5 — 1080p@60, gated.** Small, only if Stage 0's page probe and a `grim` timing say 720p@30 is worth the CPU. Proof: `hyprctl monitors` shows the new mode, and one timed `grim -c -t jpeg -q 80` stays near the old ~46 ms budget. If it does not, revert the mode and keep 720p.
**Stage 6 — durable profile.** Small, convention plus the wrapper's `--user-data-dir`. Proof: second launch reuses the same directory and still starts; cmdline has no `/tmp/eyes-profile`.
Land 0 → 1 → 2 → 3 → 4 → 6. Stage 5 is optional and independent. Do not combine Stage 3 with a resolution change; a dead Wayland socket and a slow `grim` would be one undifferentiated failure.
## 5. Risks
- **Wayland socket.** Stage 3 is the BUG-01 area. The frame server must keep `XDG_RUNTIME_DIR=/run/hypr-stream`. Moving the compositor's own runtime directory re-breaks the 25-character `sun_path` limit on the event socket.
- **`hh-*` names.** Renaming them breaks capture-by-output, the pointer's per-output device, and reconcile. Leave the contract alone.
- **Monitor-rule names.** A non-empty `outputs[].name` that is not the real connector is ignored. The session would come up at the connector's preferred mode and the 1280×720 assumption in capture, the window rule, and the tests would be wrong.
- **Containers trial.** `containers.enable = true` today can park Chromium on the quarantine workspace, so the published frame is an empty desktop. A fingerprint change that assumes the window is on the main output will be "verified" against the wrong screen.
- **CPU.** `debug:vfr = false` renders every output every frame, and each container is another output. 1080p plus two containers is the capture-budget failure.
- **Groups.** `extraGroups` does nothing for a broker that is already running, and nothing for an SSH session started before the rebuild.
- **Allowlist vs `agent-eyes run`.** Fixing only `argsAllow` does not stop the helper from passing SwiftShader. The wrapper has to be on both paths.
- **Cursor and `grim -c`.** Do not flip `cursor.invisible` in the same change. Capture tests do not own that behavior.
- **VM checks.** Run `vm-sessions`, `vm-pointer`, and `vm-hyprland` one at a time after Stages 3 and 5. Two guests at once on this machine flake.
The defensible outcome is a windowed Chromium on virtio-gpu Mesa, with a normal runtime dir, a sink, fonts, and the operator's timezone. It will still be a QEMU guest. It will not be SwiftShader, and it will not be named like a headless Chrome.