the surface: CLI verbs, the module's options, and three checks the compositor votes in

Everything below the CLI was merged and green against fakes; none of it was
reachable and none of it had ever met a compositor. This wires it up and then
puts the compositor in a position to disagree.

CLI (src/hhstream/cli.py, src/hhstream_session/**)

  session container [ID], session reconcile [ID], and the seven pointer verbs
  from PLAN §9. `start` still prints the bare session id and nothing else.
  `list` gains WS / OUTPUT / POINTER, with the gap marker where a value is
  genuinely unknown rather than a blank that reads as zero -- the POINTER
  column needs a second, read-only `pointer.state` call because the `list`
  reply carries no lease state.

  The lease id is cached in `hhstream_session.lease` (under
  $XDG_RUNTIME_DIR), because PLAN §9's gesture verbs take no --lease and the
  wire requires a lease_id on every one of them; --lease and $HHSTREAM_LEASE
  override it, and a `no_lease` refusal drops the stale entry.

  Exit codes are the contract's: a gesture with no lease is 9 and never
  reaches the broker, and a compositor failure is 10 with a message that says
  the session is still running. `kill` now warns about
  `session.container_survivors` -- windows the compositor still shows -- and
  distinguishes `null` ("could not ask") from `[]`.

  `shot`/`record --output NAME` capture one container through `grim -o`; the
  frame socket publishes the main output only, so it cannot do it.

Module (nix/module.nix)

  sessions.containers.{enable,max,mode,workspaceBase},
  sessions.pointer.{enable,leaseTtl,leaseMax}, rendered into the generated
  TOML with §10's key names. hhstream-pointer.service: the operator's account,
  supplementary group hhstream, After=/BindsTo= the compositor,
  Restart=on-failure, KillMode=process, and the command line §3.4 freezes.
  tmpfiles for /run/hhstream plus RuntimeDirectoryPreserve on the broker,
  without which restarting the broker deletes the driver's socket out from
  under it. The runtime-directory length assertion is untouched.

  And ExecStartPost on the compositor, opening its IPC directory to its own
  group: Hyprland creates <runtime>/hypr with S_IRWXU, so the broker -- a
  different account by design -- could not reach the request or event socket
  at all, and degraded silently exactly as it is built to.

Checks (checks/**)

  vm-ipc: both sockets at their frozen names, measured against sun_path's 108
  bytes, and a socket2 subscriber that receives an openwindow for a window the
  test creates. The subscriber is the shipped HyprlandIPC, not a second
  implementation: this check exists to prove that this client hears this
  compositor.

  vm-containers: one hh-* output per session at the container mode, the window
  on it, a second window of the same application beside it, an unmatched
  window quarantined, grim -o isolating one container, teardown removing the
  output and freeing the slot. PLAN experiment 3 is answered: `hyprctl output
  create headless` works.

  vm-pointer: a version-2 virtual pointer, a warp and a click whose
  coordinates the *application* reports, BUSY naming the holder, 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.

  checks/lib gains the guest the three share, their test-script helpers (no
  assertions live there), an event-socket subscriber and a Wayland client that
  says where it was clicked -- nothing in nixpkgs both honours
  $HHSTREAM_APP_ID and reports pointer events.

Reported, not worked around: the broker reads none of the container or
pointer config (policy.py takes [defaults] and [apps] only), `start` has no
no_container field so --no-container is refused rather than silently ignored,
and nix/hyprland-conf.nix sets input:follow_mouse = 0, which sends pointer
events to the focused window only -- measured, with the cursor at the aimed
pixel and no client told. README.dev.md has the evidence for each.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WQy29x9AfHWyzNd1f7XPGK
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-03 06:58:44 +00:00
1 parent 57fdd4f636
commit de408e4b7f
19 files changed
+4304 -98

No files matched your search

+131 -42
View File
@@ -7,7 +7,7 @@ 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 two VM checks. They are `nixosTest`s; without
- `/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.
@@ -28,21 +28,26 @@ rather than an installed copy.
## Build
```bash
nix build .#hhstream # the package (server + client)
ls result/bin # hhstream-server, hhstream-client
nix build .#hhstream # the package
ls result/bin # hhstream-server, hhstream-client, hhstream,
# hhstreamd, hhstream-pointer
```
Both entry points currently exit with `NotImplementedError` — see "Known gaps"
at the bottom. The package builds; it does not yet run.
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 client — in-process, against the `nix/package.nix` build | no |
| `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:
@@ -51,17 +56,36 @@ 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. Prefer running them
individually — they are independent:
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.
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`
@@ -187,56 +211,121 @@ a line at a time. `machine.succeed("hhs-hyprland-diagnostics")` works there too.
```
checks/
default.nix wiring only: the three checks the flake exposes
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
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
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
unit/ the pytest suite
unit/ ipc/ containers/ pointer/ sessions/ the pytest suite
```
`checks/lib/test-tools.nix` self-tests the two Python helpers at build time
(the fake emits a PNG of the size it was asked for; the asserter starts), because
a broken helper otherwise surfaces as a baffling failure three layers away.
`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.
Adding a unit test: drop a `test_*.py` in `tests/unit/`. Nothing needs
registering. Adding a check: one file in `checks/`, one line in
`checks/default.nix`.
`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.
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`.
## Known gaps in the interface (as of this branch)
These are defects in code this branch does not own; they are recorded here
because the tests are written against the contract and therefore trip over them.
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.
1. **`nix/module.nix` has no `config` side yet.** Neither
`hyprland-headless.service` nor `hyprland-headless-stream.service` exists, so
both VM checks fail at their first wait with
`Unit hyprland-headless.service could not be found.` Nothing in `checks/`
works around this.
2. **`services.hyprland-headless-stream.package` is declared with no default.**
`docs/CONTRACT.md` says the default is "the flake's own build", but the option
has no `default`, so reading it fails with
1. **The broker reads none of the container or pointer configuration.**
`nix/module.nix` renders `sessions.containers.{max,mode,workspaceBase}` and
`sessions.pointer.{leaseTtl,leaseMax}` into the generated TOML as PLAN §10
names them, and `hhstreamd/policy.py:policy_from_dict` reads only
`[defaults]` and `[apps]`. `hhstreamd/__main__.py:serve` builds its
`ManagerConfig` from command-line flags that have no counterpart for any of
those numbers either, so the broker runs on its own defaults (band 1000,
4 slots, 1280x720, lease 30 s / 300 s).
Those defaults agree with the module's, so a deployment that leaves the
options alone behaves as documented; one that changes them is ignored.
`vm-pointer` prints the module's `leaseTtl` beside the TTL the broker
reports, so the discrepancy is visible in the build log rather than
inferred. The fix is in `policy.py` and `__main__.py`, not here.
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. **`nix/hyprland-conf.nix` sets `input:follow_mouse = 0`, and that stops
pointer input reaching anything but the focused window.** The comment
justifying it — "No pointer will ever exist; do not let focus depend on
one" — was true before this build and is false now.
Measured by `vm-pointer`, with two sessions and the second holding focus
because its window opened last:
```
error: The option `services.hyprland-headless-stream.package' was accessed but
has no value defined. Try setting the option.
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
```
Today that only bites code that reads `cfg.package`, which the unwritten
`config` side does not yet do; it will bite every consumer that sets only
`enable = true` the moment it does. Both VM checks set `package` explicitly.
3. **`src/hhstream/*.py` is stubs.** Every function raises
`NotImplementedError`, so 66 of the 70 unit tests fail. The 4 that pass are
`tests/unit/test_package.py`, which only reads constants — they are the
canary for the `unit` check's own wiring.
4. **The frame server's command line is unspecified.** `docs/CONTRACT.md` fixes
the module's option surface and the wire format but never says how the module
invokes `hhstream-server`. `tests/unit/test_server.py::test_build_parser_exposes_the_options_the_module_needs`
currently assumes `--socket PATH --fps N --format png -- <captureCommand...>`.
That is a guess; if the module ends up passing something else, that one test
is the thing to change, not the server.
The compositor moved the cursor to the right pixel, inside the right
window, on the right output, and told no client at all. Every warp and
click in the subtests before that one is delivered perfectly, because there
the aimed-at session is also the focused one — which is why nothing noticed
until a check put two sessions on the screen at once.
It defeats the point of containers and the lease: an agent could only drive
whichever session the compositor last focused. `vm-pointer` overrides the
single line through the module's `extraConfig` and asserts the property
that fails without it, so the check is green and the defect is still
visible. The fix is one line in `nix/hyprland-conf.nix`; whether it should
be `1` (Hyprland's own default, keyboard focus follows the cursor too) or a
looser setting that leaves keyboard focus alone is a decision for the
keyboard work in PLAN §6.7.
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.