move every live default to /run/hypr-stream, and resolve the slices' contract gaps

Slice A renamed the runtime directory in the module, but the old path was still
live in the code and checks it does not own, so the VM gates pointed at a
directory the module no longer creates. This moves the 21 remaining live
occurrences (client/server defaults, the unit tests that pin them, all three VM
checks, the diagnostics script, both READMEs) and deliberately leaves the three
mentions that are history rather than configuration: the plan's problem
statement, module.nix's note about the previous name, and cli.py's explanation
for spelling its default out.

Also here: docs/CONTRACT-sessions.md is now v2 with every gap the four slices
reported resolved as a decision (Monitor.id, stable_id, pid -1, Event.data,
mark(), the quarantine argv type, the corrected wlr XML path, and the state
dir/frame socket rows), and docs/CONTRACT.md is v2 because its documented socket
default moved -- wire format unchanged.

Two comments that stated the old, wrong diagnosis (a 'misnamed' IPC socket) now
state the measured one: the event socket did not fit in sun_path.
This commit is contained in:
Hermenix committed 2026-10-02 18:11:46 +00:00
1 parent d45219994e
commit e8b3855a05
15 files changed
+102 -35

No files matched your search

+1 -1
View File
@@ -152,7 +152,7 @@ What the dump contains, and where it comes from in the guest:
|---|---|
| `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/hyprland-headless-stream`, `/run/user/*` |
| `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` |
+1 -1
View File
@@ -29,7 +29,7 @@ Two parts:
Then any consumer:
```bash
hhstream-client --socket /run/hyprland-headless-stream/stream.sock --count 1 --out frame.png
hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
```
The socket is a plain file descriptor: the server serves every client that
+1 -1
View File
@@ -13,7 +13,7 @@
width ? 1280,
height ? 720,
fps ? 30,
socketPath ? "/run/hyprland-headless-stream/stream.sock",
socketPath ? "/run/hypr-stream/stream.sock",
}:
testers.runNixOSTest {
name = "hhstream-vm-basic";
+5 -5
View File
@@ -20,7 +20,7 @@
width ? 1280,
height ? 720,
fps ? 30,
socketPath ? "/run/hyprland-headless-stream/stream.sock",
socketPath ? "/run/hypr-stream/stream.sock",
}:
testers.runNixOSTest {
name = "hhstream-vm-hyprland";
@@ -111,8 +111,8 @@ testers.runNixOSTest {
# compositor's IPC socket even though it belongs to `hhstream`.
HYPRCTL_MONITORS = (
"set -eu; "
"sig=$(ls -1 /run/hyprland-headless-stream/hypr | head -n1); "
"XDG_RUNTIME_DIR=/run/hyprland-headless-stream"
"sig=$(ls -1 /run/hypr-stream/hypr | head -n1); "
"XDG_RUNTIME_DIR=/run/hypr-stream"
" HYPRLAND_INSTANCE_SIGNATURE=$sig hyprctl -j monitors"
)
@@ -177,8 +177,8 @@ testers.runNixOSTest {
# minimal PATH, not the guest's environment.systemPackages.
status, out = machine.execute(
"systemd-run --pipe --wait --uid=hhstream"
" --setenv=XDG_RUNTIME_DIR=/run/hyprland-headless-stream"
" --setenv=WAYLAND_DISPLAY=$(cd /run/hyprland-headless-stream"
" --setenv=XDG_RUNTIME_DIR=/run/hypr-stream"
" --setenv=WAYLAND_DISPLAY=$(cd /run/hypr-stream"
" && ls -1 wayland-* | grep -v '\.lock$' | head -n1)"
" sh -c '${grim}/bin/grim -t png - > /tmp/direct.png' 2>&1",
timeout=120,
+1 -1
View File
@@ -214,7 +214,7 @@ testers.runNixOSTest {
CONTROL = "${controlSocket}"
CONTROL_DIR = "/run/hhstream"
IDLE_TIMEOUT = ${toString idleTimeout}.0
COMPOSITOR_RUNTIME = "/run/hyprland-headless-stream"
COMPOSITOR_RUNTIME = "/run/hypr-stream"
# The module pins the compositor's XDG_RUNTIME_DIR; the instance signature
# under it is the only part not known ahead of time. Root may connect to
+66 -10
View File
@@ -9,7 +9,20 @@ else. If something here is wrong or missing, **stop and report it in your final
message** — the parent edits this file, not you. Do not widen your slice to work
around a gap.
Version: sessions-v1 (2026-10-01).
Version: sessions-v2 (2026-10-02). v1 was the freeze the four slices built against;
v2 records the decisions their reports asked for. Every v2 change is either a
clarification or an addition — **no v1 signature changed meaning** — so v1 code
stays valid except where noted. Changes:
| § | Change | Why |
| --- | --- | --- |
| §3.1 | `Monitor` gains `id: int` | `clients -j` reports a client's monitor as a numeric **index**, `Workspace.monitor` as a **name**, so without an id there is no way to join a client to its output. Slice D's aiming is output-local. |
| §3.1 | `Client.stable_id` defined as `"<initial_class>:<pid>"` (fallback `address`); absent `pid` becomes `-1`; `Event.data` is a per-event field table plus always-present `raw`/`args`; `request_timeout_s` is an overridable class attribute (2 s); `version()` returns the compositor's banner verbatim | What slice B had to decide, now written down instead of re-derived. |
| §3.2 | `quarantine_argv()` replaces `quarantine_plan()`, returning `list[list[str]] \| None` | A quarantine rule is not a container: no output, no numbered workspace, no mode, and `container_plan` refuses a zero size. **Integration updates `containers.py` and its tests to this shape.** |
| §3.3 | `mark()` added; `expire()` precedence documented | §3.3 gave no way to record a position, so `LeaseOutcome.bookmark` could only ever be `None` and `pointer.acquire … restore?` had nothing to restore. |
| §3.4 | Vendored protocol is permitted, and the XML path is corrected | The v1 path was wrong (`share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml`). |
| §5 | The broker state dir is stated as an *option default* with this machine's override; the frame socket is named | §5's value was the deployed one, not the default, and the frame socket was missing while `docs/CONTRACT.md` still documents the old one. |
---
@@ -57,7 +70,7 @@ class CompositorUnavailable(Exception):
@dataclass(frozen=True)
class Monitor:
name: str; x: int; y: int; width: int; height: int; scale: float
id: int; name: str; x: int; y: int; width: int; height: int; scale: float
active_workspace_id: int | None
@dataclass(frozen=True)
@@ -103,6 +116,24 @@ Rules: every method raises `CompositorUnavailable` rather than returning a
guess. `clients()` parses `clients -j`; `monitors()` parses `monitors -j`;
`workspaces()` parses `workspaces -j`. Stdlib only.
Decisions, so they are not re-derived per caller:
- **A client's monitor is an index, an output's name is a name.** `Client.monitor`
is the numeric index rendered as text (or `None` when the reply said nothing);
join it to a `Monitor` through `Monitor.id`. `Workspace.monitor` is a name.
- **`Client.stable_id`** is `"<initial_class>:<pid>"`, falling back to
`address`. Hyprland publishes no such key; this is the identity that survives a
remap, and the launcher sets the class per session.
- **An absent `pid` becomes `-1`**, not `0` — no process has pid `-1`.
- **Events are positional on the wire** (`name>>a,b,c`). `Event.data` is built
from a per-event field table, with the last named field absorbing the remaining
commas (titles contain them); `raw` and `args` are always present so an unknown
event is still usable. An event that carries fewer fields than the table names
only what arrived — never invented empties.
- **`request_timeout_s`** is a class attribute (2 s) on `HyprlandIPC` because
`__init__` is frozen.
- **`version()` returns the compositor's banner verbatim**, not a parsed number.
### 3.2 `hhstreamd/containers.py` (C)
**Pure logic. No I/O, no subprocess, no socket, no import of `ipc.py`.** It
@@ -139,9 +170,18 @@ def app_id_for(session_id: str) -> str: ...
# the bare "hh-<session-id>" the launcher sets on the app; "^hh-<session-id>$"
# is built in container_plan.
def quarantine_plan(quarantine_workspace: str) -> ContainerPlan | None: ...
def quarantine_argv(quarantine_workspace: str) -> list[list[str]] | None: ...
# the backstop: every window matching no container goes to
# special:quarantine. Returns the keyword argv, or None if disabled.
# special:quarantine. Returns the keyword argv, or None when the target is
# blank/whitespace (which is how "disabled" is spelled).
#
# Deliberately NOT a ContainerPlan: a quarantine rule has no output, no
# numbered workspace and no mode. The argv shape mirrors the per-session
# rule, with a catch-all class:
# ["hyprctl","keyword","windowrule",
# f"match:initial_class .*, workspace {target}"]
# It must be installed BEFORE any per-session rule, or the catch-all wins.
# That ordering is the caller's, and this module cannot enforce it.
class WorkspaceAllocator:
def __init__(self, base: int, count: int) -> None: ...
@@ -183,6 +223,11 @@ class PointerLease:
def acquire(self, session_id: str) -> str: ... # -> lease_id; raises LeaseBusy
def refresh(self, session_id: str, lease_id: str) -> None: ... # raises LeaseInvalid
def release(self, session_id: str, lease_id: str, reason: str) -> LeaseOutcome: ...
def mark(self, session_id: str, lease_id: str, bookmark: Bookmark) -> None: ...
# records where the cursor was left, called on every move and before
# release. Added in v2: without it LeaseOutcome.bookmark could only ever
# be None, so `pointer.acquire --restore` had nothing to restore.
# raises LeaseInvalid for a non-holder.
def state(self) -> dict: ... # {"holder": str|None, "since": float|None,
# "lease_id": str|None, "expires_at": float|None}
def expire(self) -> LeaseInfo | None: ...
@@ -192,6 +237,13 @@ class PointerLease:
def unpress(self, session_id: str, button: str) -> list[str]: ...
def pressed(self) -> list[str]: ...
**`expire()` carries no bookmark and no lifted buttons** — it returns the lease
that was released, nothing more. The broker therefore has two duties on expiry:
read `pressed()` *before* calling `expire()` if it wants the lease's view of what
was down, and lift those buttons on the driver (`release_all`), because the lease
cannot lift them itself. The bookmark is not `expire()`'s to keep: the broker
already stores it with the session (§1), which is where it belongs.
def window_to_absolute(point: tuple[int, int], window: tuple[int, int, int, int],
monitor: tuple[int, int, int, int]) -> tuple[float, float]:
# point is window-local pixels; window is (x, y, w, h) global; monitor is
@@ -209,11 +261,14 @@ blocked driver must not stall the broker.
- Command line the module will pass, exactly:
`hhstream-pointer --socket /run/hhstream/pointer.sock --compositor-runtime-dir /run/hypr-stream`
- Uses **pywayland** (packaged as `python3Packages.pywayland`) and the **wlr
virtual pointer XML** from `pkgs.wlr-protocols`
(`share/wayland-protocols/wlr-unstable/zwlr-virtual-pointer-unstable-v1.xml`).
Compile the protocol at build time or vendor the generated module under your
directory — your choice, stated in your report. `pyproject.toml` and
`nix/package.nix` are yours precisely so this is possible.
virtual pointer XML** from `pkgs.wlr-protocols`, which lives at
`share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml` (the v1
contract had this path wrong: different middle directory, and no `z` prefix on
the filename). **Vendoring the generated module is explicitly permitted** (v2):
generating at build time puts a code generator between a checkout and a runnable
driver, and the dev shell has neither the XML nor a scanner. State which you
did. `pyproject.toml` and `nix/package.nix` are yours precisely so this is
possible.
- Binds `zwlr_virtual_pointer_manager_v1` **version 2** and uses
`create_virtual_pointer_with_output(seat, output, id)` so coordinates are
output-local. If only version 1 is offered, **report it — never silently fall
@@ -269,9 +324,10 @@ reset the idle clock.
| Compositor runtime dir | `/run/hypr-stream` — **must be ≤ 25 chars** (socket paths must stay under `sun_path`'s 108-byte limit) |
| Compositor request socket | `<runtime dir>/hypr/<signature>/.socket.sock` |
| Compositor event socket | `<runtime dir>/hypr/<signature>/.socket2.sock` |
| Frame socket (published) | `<runtime dir>/stream.sock` — default `/run/hypr-stream/stream.sock`. Also frozen in `docs/CONTRACT.md`, which v1 of this file left disagreeing with it. |
| Broker control socket | `/run/hhstream/control.sock` |
| Broker↔driver socket | `/run/hhstream/pointer.sock` |
| Broker state dir | `/var/lib/hermes/hhstream-sessions` |
| Broker state dir | **option default** `/var/lib/hhstream`; this machine sets `/var/lib/hermes/hhstream-sessions` (`sessions.stateDir`). v1 listed the deployed value, which read as a contradiction of the module. |
| Session runtime dir | `/run/hhstream/sessions/<session-id>` |
| Container output name | `hh-<session-id>` |
| Container workspace band | `1000 + slot`, allocated from the registry's free list |
+10 -3
View File
@@ -1,4 +1,11 @@
# Wire contract (v1)
# Wire contract (v2)
**v2 changes nothing on the wire.** The published socket's documented *default*
moved from `/run/hyprland-headless-stream/stream.sock` to
`/run/hypr-stream/stream.sock`: the old runtime directory pushed the compositor's
own IPC *event* socket past `sun_path`'s 108-byte limit, so it never bound (see
`docs/CONTRACT-sessions.md` §5). Message sequence, framing and failure semantics
are unchanged, so a v1 reader is still a correct reader.
This file is the interface. Code on either side may change freely; **this
document may not**, without bumping the version.
@@ -7,7 +14,7 @@ document may not**, without bumping the version.
- Transport: `AF_UNIX`, `SOCK_STREAM`.
- Path: whatever `services.hyprland-headless-stream.socketPath` says.
Default `/run/hyprland-headless-stream/stream.sock`.
Default `/run/hypr-stream/stream.sock`.
- Ownership: the service user (`user` option, default `hhstream`), mode `0660`.
- The server accepts **any number of concurrent clients**. Each client gets its
own copy of the header and of every subsequent frame. A client disconnecting
@@ -78,7 +85,7 @@ Namespace: `services.hyprland-headless-stream`
| Option | Type | Default | Meaning |
|---|---|---|---|
| `enable` | bool | `false` | turn everything on |
| `socketPath` | str | `/run/hyprland-headless-stream/stream.sock` | published socket |
| `socketPath` | str | `/run/hypr-stream/stream.sock` | published socket |
| `user` / `group` | str | `hhstream` | owner of the session and the socket |
| `frameRate` | int | `30` | capture target, becomes `fps` in Hello |
| `format` | enum `png`/`jpeg` | `png` | frame encoding |
+8 -4
View File
@@ -93,10 +93,14 @@ Two notes for anyone editing that file:
Hyprland draws the error *across the screen*, which lands in the recording.
Always check an edit with `Hyprland --verify-config --config <file>` — it does
not need a display, so it costs seconds instead of a rebuild.
- `hyprctl` **cannot connect** to this session: the compositor names its IPC
socket `.socket.so`/`.socket.s` instead of `.socket.sock`, so nothing using the
documented path works. Do not plan on `hyprctl` for window control — measure
what you need from the frames instead.
- `hyprctl` **works** against this session; an older note here claimed the
compositor misnames its IPC socket, which was wrong. The real defect was path
length: `$XDG_RUNTIME_DIR` was `/run/hyprland-headless-stream` (29 chars) and
the event socket `hypr/<signature>/.socket2.sock` did not fit in `sun_path`, so
the compositor logged `ERR ]: Socket2 path is too long. (2) IPC will not work.`
while the request socket kept answering — which is why the wrong diagnosis
survived. The runtime directory is now `/run/hypr-stream`, and `nix/module.nix`
asserts it stays ≤ 25 characters.
### Posting the result to a chat
+2 -2
View File
@@ -50,8 +50,8 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "src"))
from hhstream import protocol # noqa: E402 (path set above)
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
DEFAULT_RUNTIME_DIR = "/run/hyprland-headless-stream"
DEFAULT_SOCKET = "/run/hypr-stream/stream.sock"
DEFAULT_RUNTIME_DIR = "/run/hypr-stream"
def log(message: str) -> None:
+1 -1
View File
@@ -11,7 +11,7 @@ from typing import Iterable
from . import protocol
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
DEFAULT_SOCKET = "/run/hypr-stream/stream.sock"
def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]:
+1 -1
View File
@@ -23,7 +23,7 @@ from typing import Iterable
from . import protocol
from .capture import CaptureBackend, CommandCapture
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
DEFAULT_SOCKET = "/run/hypr-stream/stream.sock"
#: Contract: the published socket is mode 0660 (ownership is the unit's job).
SOCKET_MODE = 0o660
#: Contract default for `services.hyprland-headless-stream.captureCommand`.
+2 -2
View File
@@ -42,7 +42,7 @@ ls -l /dev/dri 2>&1 || echo "[no /dev/dri: this machine has no DRM device at all
run cat /proc/fb
say "socket and runtime directories"
ls -la /run/hyprland-headless-stream 2>&1 || echo "[no /run/hyprland-headless-stream]"
ls -la /run/hypr-stream 2>&1 || echo "[no /run/hypr-stream]"
ls -la /run/user 2>&1 || echo "[no /run/user]"
for d in /run/user/*; do
[ -d "$d" ] && ls -la "$d" 2>&1
@@ -56,7 +56,7 @@ say "wayland socket vs WAYLAND_DISPLAY"
systemctl show -p Environment --value "$SERVICE_UNIT" 2>&1 \
| tr ' ' '\n' | grep -E '^(WAYLAND_DISPLAY|XDG_RUNTIME_DIR)=' \
|| echo "[no WAYLAND_DISPLAY/XDG_RUNTIME_DIR in the unit environment]"
for d in /run/hyprland-headless-stream /run/user/*; do
for d in /run/hypr-stream /run/user/*; do
[ -d "$d" ] || continue
found_sock=$(find "$d" -xdev -maxdepth 1 -name 'wayland-*' ! -name '*.lock' 2>/dev/null)
if [ -n "$found_sock" ]; then
+1 -1
View File
@@ -31,7 +31,7 @@ for _path in (str(_HERE), str(_SRC)):
from hhstream.server import FrameServer # noqa: E402 (needs sys.path above)
#: The path named in docs/CONTRACT.md and in the module's option default.
CONTRACT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
CONTRACT_SOCKET = "/run/hypr-stream/stream.sock"
# AF_UNIX addresses are capped near 108 bytes; a long tmp_path would fail with a
# confusing OSError instead of the assertion the test is about.
+1 -1
View File
@@ -54,7 +54,7 @@ def wait_for_socket(path: str, proc: subprocess.Popen, timeout: float = 10.0) ->
def test_server_defaults_match_the_contract():
args = server.build_parser().parse_args([])
assert args.socket == "/run/hyprland-headless-stream/stream.sock"
assert args.socket == "/run/hypr-stream/stream.sock"
assert (args.fps, args.format, args.capture_command) == (30, "png", None)
assert server.DEFAULT_CAPTURE_COMMAND == ["grim", "-t", "png", "-"]
+1 -1
View File
@@ -134,7 +134,7 @@ def test_main_rejects_a_negative_count(sock_path, capsys):
def test_default_socket_matches_the_contract():
assert client.DEFAULT_SOCKET == "/run/hyprland-headless-stream/stream.sock"
assert client.DEFAULT_SOCKET == "/run/hypr-stream/stream.sock"
assert client.build_parser().parse_args([]).socket == client.DEFAULT_SOCKET