The broker reported `workspace: null` and `window: null` for every session
because nothing in it could talk to Hyprland. This is that voice, and the
only place that knows the compositor's wire format: one connection per
request on `.socket.sock` (leading `/` so an argument containing a slash is
never read as output flags, `j/` where JSON is wanted), and a held, blocking
stream on `.socket2.sock`.
Every failure is CompositorUnavailable -- no instance directory, two of them
and no signature, a socket that is gone, a peer that refuses or closes
mid-reply, a reply that is not the JSON it promised, an event stream that
ends. Nothing returns an empty list or a None to stand in for "I could not
ask", because a caller that cannot tell those apart writes a guess into a
session record. Inside the defined shape the parse is forgiving instead:
Hyprland's JSON has changed keys across releases, so a missing key is a
defined value and never a KeyError reaching the broker.
Tests bind real AF_UNIX sockets in a temporary directory laid out the way
Hyprland lays one out and serve canned bytes, so they drive the actual
connect, half-close, read-to-EOF and timeout paths rather than a mock that
would pass while the sockets broke.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MLiQAZCmJf66CEcLx8siYF
M0 of the sessions design, wired into the flake and gated by a real check.
What is here now:
- `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group
teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME.
- `src/hhstream_session/` — the CLI handlers, registered into the one front door.
- `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the
frame verbs and the session namespace are one binary.
- `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service`
unit: the operator's own account (never a service account, because launched
applications should see that account's home), the compositor's group as a
supplementary group (without it a launched GUI client cannot open the Wayland
socket), the generated app allowlist, and `--compositor-runtime-dir` so
applications are handed the compositor's session rather than the broker's.
- `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM.
Two bugs found by driving it, both fixed:
- BUG-01: launched applications could not reach the compositor at all — the
broker spawned them with its own inherited environment, which names the login
session. `hhstreamd/compositor.py` discovers the socket and builds the child
environment; a directory with no usable socket is a startup refusal, not a
warning.
- BUG-02: `kill` refused to signal a live application and said nothing was
wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve`
replaces — and on NixOS applications are reached through wrapper scripts that
do exactly that. The gate now rests on `starttime` (+ boot id, + session id
where it is immutable) and records command-line drift as evidence of nothing.
KillMode=process is set on the unit on purpose: the default control-group kill
would take the applications down with the broker, which would make adoption and
a broker restart pointless.
Fill in the bodies the skeleton left as NotImplementedError, to docs/CONTRACT.md:
- protocol: the `\n`-terminated JSON Hello and the `<ascii length>\n<payload>`
frame, both directions. Malformed input raises (ValueError for a bad length
prefix, EOFError for a truncated payload), never hangs on endless garbage and
never silently truncates; a huge length prefix is not pre-allocated.
- capture: CommandCapture runs the configured command and reports a missing
binary, a non-zero exit, a timeout and empty output as CaptureError, with the
helper's stderr folded into the message so nothing leaks to the server's own
stdio. The Hello's pixel size is read from the frame's PNG/JPEG header, so no
compositor query is needed and an injected fake command behaves the same.
- server: one capture thread holding only the newest frame plus one thread per
client, which is what drops frames for a slow client instead of queueing
them. Survives a client dying mid-write, keeps the socket up across capture
failures, withholds the Hello until a size is known, replaces a stale socket
file (but never a non-socket one) and publishes it mode 0660.
- client: fetch()/read_stream() and the CLI, with --out suffixing per frame.
--capture-command folds its separated form into `--flag=value` before argparse
sees it, so the contract's default `grim -t png -` can actually be passed: its
tokens start with a dash.
Unit tests under tests/unit cover framing round-trips (including a payload
containing `\n` and a zero-length frame), truncated and garbage prefixes, a
stalled client not blocking a second one, a client dying mid-frame, frames being
dropped rather than queued, and every capture failure mode. A fake capture
command stands in for grim, so nothing needs a compositor or a GPU. They are
deliberately not wired into flake.nix: `checks` belongs to another workstream.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FYJ8ZQ5AZaDErYTwXZe7N9