`cmd_serve` read `args.capture_command`, which only exists on the `serve`
subparser, so a bare `hhstream-live` died with an `AttributeError`. The word
`serve` is now inserted before parsing rather than defaulted afterwards: the
top-level parser would otherwise reject `hhstream-live --port 9999` for an
unknown option before anything could be filled in. `--help` is left alone so
it still shows the program's own help. `--log-level` gained a copy on each
subparser, defaulting to `SUPPRESS` so that naming the subcommand does not
reset it.
SIGTERM had no handler, so the default action killed the process and
`server.stop()` never ran -- the exit status was a signal, not a 0. The
handler is installed before the listener is bound, so a supervisor's first
signal is never the fatal one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
Four things the HTTP side owed.
A connection had no read timeout, so a client that connected and sent
nothing held a handler thread in `readline` for ever -- and on the MJPEG
route it also held a viewer slot, which keeps grim running for nobody.
Handlers now carry a 15 s header timeout, cleared once the MJPEG headers
are out because from there the wait is on frames, not on the client. TCP
keepalive covers the other half: a black-holed viewer that never closes.
The MJPEG response had no `Content-Length`, no chunked encoding and no
`Connection: close` -- `close_connection = True` was set after
`end_headers()`, so it never became a header. An intermediary was entitled
to buffer the whole thing waiting for an EOF that never comes.
`log_message` formatted the request line, which is the phrase, at debug
level; so did the client-error line. Both now log the method, the status
and the peer, never the path.
`RateLimiter` pruned only the key it was asked about, so every source
address that ever missed stayed in the table for the life of the process --
a leak any LAN host could drive. The sweep now covers the table.
Finally, `LiveServer` says where it is really bound: `address` still
returns something dialable, and `describe_bind` is what names `0.0.0.0` as
all interfaces.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
Two holes in the one credential a stream has.
The wordlist has four hyphenated entries (`drop-down`, `felt-tip`,
`t-shirt`, `yo-yo`). A phrase drawn from one is six tokens --
`abacus-drop-down-lantern-harbor-7k2qp` -- and a listener cannot hear where
the tail starts. `words()` now keeps only `^[a-z]+$`; 7772 words costs
0.003 bits, so the ~77.5-bit figure is unchanged. The shape test asserted
over 50 draws, which caught this about a tenth of the time; the property is
now asserted over the whole list.
`validate` accepted `a-b-c`. It is what an operator-supplied `--phrase` is
checked against, so everything it accepts is a password someone can choose
for a LAN-facing stream. The floor is now exactly what `generate` produces:
four `[a-z]{3,}` words and a five-character `[a-z0-9]` tail. The router
still looks phrases up without validating, so an unknown phrase is the same
empty 404 it was.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
The failure cap read `consecutive_failures >= FAILURE_LIMIT and captured ==
0`, so it could only ever fire on a cold start. An output removed while
someone was watching -- grim answering "unknown output" to every grab from
then on -- kept the loop retrying twice a second for as long as the viewer
held the page open. That is the busy loop the cap exists to stop, so the
count is now of failures in a row and nothing else. Giving up stays sticky:
a removed output does not come back, and re-enabling the session is how it
returns.
While here, the capture thread is named for its output and the give-up is
logged by output. The phrase is the stream's only credential, and
faulthandler, `threading.excepthook` and any sampling profiler all print
thread names.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase. Off by default, so a stream
exists only for the sessions it was enabled on.
src/hhstream_live/phrase.py four EFF-large words + a 5-char base-36 tail
(~77.5 bits); the phrase is the password
src/hhstream_live/publisher.py one capture thread + one frame slot per
output; one slot/no queue; capture paused at
zero viewers
src/hhstream_live/server.py the router: /, /<phrase>/, /stream.mjpg,
/frame.jpg, /status.json; unknown phrase is
an empty 404, rate-limited
src/hhstream_live/pages.py the built-in dark pages (no CDN, no build)
src/hhstream_live/__main__.py hhstream-live serve|phrase, standalone
The root page is a form, never a list: the phrase is known only by whoever
enabled the stream. Transport is MJPEG (multipart/x-mixed-replace), reusing
the JPEG grim already produces. Not yet wired to the broker -- that is
stage 2. Tests: tests/live (51).
The marker is now written up as the *open* item rather than a research note: it
is not implemented, the video went out without it, and everything else about the
pointer is exact and readable.
proof-video.py is rewritten for desks, one command, no arguments. It films the
session's own output with `record --output` instead of the published socket --
with desks, the socket carries every output stitched together, so a viewer would
watch two thirds wallpaper. The scrolling beats are real pointer axis events,
down twice and back up once, so the movement cannot be mistaken for a page that
merely loaded a different part of itself.
Closed: containers-do-not-bind and pointer-needs-a-container-or-a-screen. Both
were the same defect seen from two sides, and both are fixed by assigning
windows by pid -- two sessions now hold two outputs with a real browser on each,
and the pointer aims at a desk that has something in it.
The cursor item is rewritten with the answer rather than the speculation: the
compositor draws no cursor image for a virtual pointer, so no capture setting
can make one appear. The evidence is in the file, including the three wrong
answers that came before it and the boring measurement that settled it.
New item: killing a session left two browsers alive, found by counting windows
rather than sessions.
grim's `-c` ("include cursors in the screenshot") exists because the screencopy
protocol takes the decision from the client: Hyprland's capture_output carries
an overlayCursor argument and the frame is only composited with the cursor when
it is set. Without it a frame shows that *something* changed and never where it
was clicked -- and a click on the wrong element looks exactly like a click on
the right one, which is the whole reason the pointer work is verifiable at all.
Found by reading Hyprland's Screencopy.cpp rather than guessing at a compositor
setting: `no_hardware_cursors` was already on, and the cursor was invisible
because nobody had asked for it.
Two things stood between "containers enabled" and an application actually
sitting on its own output, and neither was where I said it was.
ipc: discovery refused whenever two instance directories existed, which every
compositor restart leaves behind (a log file where a live compositor used to
be). After two rebuilds the broker could not reach any compositor at all, so no
container could be created and the pointer had nothing to aim at. It now asks
each candidate for its version and uses the one that answers, preferring the
newest only when two answer, and still refusing when none do.
container_host.claim: windows are assigned by the pid the compositor already
reports, not by the class stamp the per-session rule matches -- foot, GTK, Qt
and the chromium wrapper all ignore that stamp, so the desk was created and
left empty while the window sat in special:quarantine. The claim moves the
window to its desk's workspace, makes that workspace the one the desk is
showing, and reads back: the record says where the window is, never where it
was sent. Called from both places a window can appear -- the read-back at start
and container.reconcile -- and skipped in the steady state, because a move is a
real change on screen and should not be dispatched for its own sake.
Found live while trying to demonstrate the scroll verb that was just deployed:
every cursor verb resolves its target through _pointer_output, which requires a
container output, and no session has one -- because containers are off. So the
verb exists and cannot be used, and the acceptance video's missing cursor was
never a capture artefact: nothing could have moved it.
Recorded with the routes out (aim at the shared output when a session owns no
container; or fix the binding first and leave this alone), the cost of the
quick one, and the misleading hint that blames the compositor for a switched-off
feature.
Item 1 said the broker reads none of the container or pointer configuration.
That was true and is not: the settings are parsed beside Policy and a switched-off
container host reports itself unavailable with the key named. The item now
records what actually matters about it -- that containers are off on the
deployment machine because no window can be put in one -- and the section links
docs/TODO/, where each open problem has its impact written down.
The TODO folder itself landed in the previous commit by accident (a `git add -A
docs` swept it in with the scroll work); this commit only makes it findable.
A session could move a cursor and press it, but not scroll. The protocol
already had the request -- zwlr_virtual_pointer_v1.axis(time, axis, value) --
it had simply never been implemented, in the driver or the broker.
hhstream session pointer scroll <id> --axis vertical --amount 3
Positive is down (vertical) or right (horizontal): the protocol's direction,
not a choice of ours, which is why direction travels in the sign and there is
deliberately no up/down vocabulary layered over it. The output is whatever the
last warp aimed at, exactly like a button, so scrolling somewhere else is a
warp first -- and the lease is what keeps the whole gesture atomic. Bounded at
100 wheel clicks per request on both sides, because a decimal-point slip should
be a refusal rather than a session scrolled somewhere unrecoverable.
The resume point is re-stamped, not moved: the cursor did not go anywhere, so
the coordinates are re-affirmed and only the stamp advances. Recorded in the
contract as an amendment to the frozen op set, because adding an op to a frozen
interface should be visible rather than implied.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Driving the session's browser over CDP, then a terminal with cowsay, was a
scratch script twice and got pruned from scratch once -- which produced an
80-second video of an idle browser and no error. It is asked for repeatedly, so it
belongs with the rest of the agent-eyes tooling, takes a session id, and says in
its docstring that the URLs are real (the search uses key= singular, the bug that
once silently cost every Gunpost search its filtering).
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The module rendered containers_enabled, workspace_base, container_mode,
max_containers and the pointer lease keys into the TOML, and policy.py read only
[defaults] and [apps] -- so the settings were inert. The defaults coincided,
which made it look honoured, until a deployment tried to turn containers off and
found it could not.
Settings now come from the same file: parsed beside Policy (read by __main__, so
the manager keeps taking a plain ManagerConfig its tests build directly) and
carried into ContainerHost, which reports itself unavailable when switched off.
That is the whole mechanism -- the manager already treats an unavailable host as
'sessions without containers', which is what turning them off means -- and the
reason names the key, so a disabled machine cannot be mistaken for one whose
compositor is down.
This is what made the rollback on the host possible; the machine had containers
built, tested, and impossible to disable.
vm-pointer measured what this setting actually does: with follow_mouse=0 Hyprland
delivers pointer events only to the keyboard-focused window, so a click aimed at
0.25,0.75 of a session's container put the cursor at x=299 y=519 -- inside that
window -- and both clients reported nothing. The click was aimed correctly and
delivered nowhere.
The comment here said 'no pointer will ever exist; do not let focus depend on
one', which was true when written and is false now that the broker injects a
virtual pointer. The cursor lease already serialises input, so focus following
the pointer cannot make two sessions fight over the keyboard.
The surface the plan described, and the first composer of real compositor
evidence: seven checks green one at a time, including three new ones. They proved
`hyprctl output create headless` works (PLAN experiment 3, until now
unverified), that a click lands where it was aimed read from the application
itself, and that an unmatched window is quarantined.
They also found three defects no fake could: Hyprland's IPC directory is mode
0700 so the broker could not reach either socket and degraded silently, a broker
restart deleted the driver's socket out from under it, and input:follow_mouse=0
sends pointer events only to the keyboard-focused window, so an aimed click
reaches a client that reports nothing.
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
The contract bump added Monitor.id and nobody implemented it: slice B predates
v2, so the integration slice had to join a client to its output through
Workspace.monitor instead. Field added, parsed from `monitors -j`, and -1 when a
reply omits it -- a missing id must not default to 0, which would silently bind
every such client to the first output.
Two tests: the id is parsed, and omitting it yields -1.
The four modules built against the frozen contract finally have a caller. Record
schema 3 with migration, container lifecycle (create on start, teardown on kill,
reap, gc and unprompted exit, reconcile at start-up), the pointer verbs over the
lease with a 1s expiry sweep, quarantine_argv, and the new wire verbs and error
codes.
Its own report is explicit that the fake compositor proves the broker's half
only; whether Hyprland accepts these commands is the VM checks' question.
The four slices existed and nothing called them. Now the broker builds a
spatial container per session, reads back what the compositor actually did,
and aims the cursor into one container under a broker-wide lease.
Record schema 3 (registry.py): `container` {output, workspace, mode,
created_by, state}, `pointer` {bookmark, last_released_at, released_by} and
the compositor's `signature`. A v2 record is migrated on load, not refused —
its application is still running. Every field that could not be verified is
null; `container: null` means "no container", never "probably something".
Containers (new container_host.py, manager.py, launcher.py): `start`
allocates a slot from `WorkspaceAllocator`, runs `container_plan()`'s argv,
launches the app with the container stamp in its environment, then reads the
workspace, output and window back out of `clients -j`. Teardown removes the
output, releases the slot and reports survivors rather than claiming success
— and runs for an unprompted exit and for `gc` too, so no container is ever
left unattended. Broker start-up reconciles: adopt `hh-*` outputs a live
session claims, remove the rest, `contains_output()` being the only filter.
No IPC means `container: degraded` and lifecycle verbs unchanged.
The plans' argv are dispatched over the compositor's request socket rather
than by executing `hyprctl`, which is what hyprctl does with the same words;
the reply is checked, so a refused command is not recorded as a container.
Pointer (new driver.py, manager.py): a client for the driver's private
socket, and `pointer.acquire|move|button|click|release|state` on top of
`PointerLease`. The broker owns the lease, the driver executes. The bookmark
is marked on every move and before release and stored in the record, so it
survives a restart. On expiry `pressed()` is read before `expire()` and
`release_all` goes to the driver, because the lease cannot lift a button
itself; a sweep runs unprompted so the TTL is a promise.
containers.py to v2: `quarantine_plan()` -> `quarantine_argv()`, with the
before-any-per-session-rule ordering stated where the caller could get it
wrong. protocol.py: 9 NO_LEASE, 10 COMPOSITOR, the verb table, and the
`request_id` cache moved out of the server so the CLI agrees with it.
Tests: real AF_UNIX everywhere — a stateful fake compositor and the shipped
pointer driver behind a recording sink. No mocked sockets, no compositor, no
VM. 551 -> 693.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017mUq7QvQ9EZb2Wi35xj4cs
The check took ../tests/unit alone, so the broker's, the pointer driver's and the
sessions suites were collected by no check at all -- 432 of 551 tests ran only
when someone happened to enter the dev shell. It now takes ../tests, which
surfaced two real defects in the harness rather than in the code:
- tests/sessions/integration/test_lifecycle.py locates the repository by looking
upward for a pyproject.toml, which a build has no reason to contain; it raised
at import and took the whole run down as a collection error. The check now
copies the marker in, which is what the test documents it needs.
- That file also REPLACED PYTHONPATH for the daemon it spawns instead of
prepending to it. In a checkout src/ is the package, so it worked; under a
build it discarded the package under test, and 'python -m hhstreamd' died at
startup with an ImportError -- reported as a daemon failure on every test in
the file. Prepending is the fix, and the right behaviour anywhere.
pywayland joins the test environment because the pointer driver imports it.
unit: 551 collected, 550 passed, 1 skipped (a deliberate skip).
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.
The union of main and the four slices cannot be collected by pytest: an
import-file-mismatch on test_protocol.py (the frame wire's, the broker's) and
test_server.py (the frame server's, the pointer driver's). Per-directory runs
never hit it, so this is what the union run is for.
The tempting fix is --import-mode=importlib, and it is wrong: importlib does not
put a test file's directory on sys.path, which the slices' tests rely on for
sibling imports (from conftest import HANG, from test_ops import RecordingSink).
That trades a collection error for an ImportError. Renaming the two colliding
modules keeps the import behaviour and fixes the actual problem:
tests/pointer/test_server.py -> test_pointer_server.py
tests/sessions/unit/test_protocol.py -> test_broker_protocol.py
tests: 551 passed.
Built in an independent worktree against docs/CONTRACT-sessions.md. Reports its
own slice's verification in its final message; the parent re-runs the union.
Built in an independent worktree against docs/CONTRACT-sessions.md. Reports its
own slice's verification in its final message; the parent re-runs the union.
Built in an independent worktree against docs/CONTRACT-sessions.md. Reports its
own slice's verification in its final message; the parent re-runs the union.
Built in an independent worktree against docs/CONTRACT-sessions.md. Reports its
own slice's verification in its final message; the parent re-runs the union.
There is one cursor on this compositor build and every virtual pointer
writes to it, so aiming at a session is a matter of serialising input, not
of binding harder. Two pieces, and the split between them is the point.
`hhstreamd/pointer.py` is the lease: one holder, an idle TTL and a hard cap
on an injected clock, tracked buttons, and the window-local-to-normalised
arithmetic that makes "click 40px into this window" mean something on an
output that is not at the layout origin. Pure, so the expiry tests move
time instead of sleeping.
`hhstream_pointer/` is the driver: its own process because a Wayland client
needs its own connection and a blocked one must not stall the broker. It
holds no lease state -- it is told what to do and does it. The manager is
bound at version 2 and pointers are created with
`create_virtual_pointer_with_output`; a version-1-only manager is reported
and refused rather than quietly aiming at the global layout.
The wlr protocol module is vendored scanner output under `_protocol/`, so a
checkout builds without a code generator; `_protocol/regenerate.py` says how
to refresh it and why pywayland's own scanner entry point cannot be used.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011txKimbdkqPFpq6m8KDELu
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
`/run/hyprland-headless-stream` is 29 characters, and the compositor's IPC
sockets live under it at `hypr/<instance signature>/.socket2.sock`. With a
~30-character signature the *event* socket does not fit in `sun_path` and the
compositor refuses to bind it:
ERR ]: Socket2 path is too long. (2) IPC will not work.
The *request* socket kept answering `hyprctl` (both ends agree on a residual
truncated path), which is why this looked healthy while every observation
feature that needs events had nothing to read.
`/run/hypr-stream` is 16 characters. The rename reaches both units'
`RuntimeDirectory`, `WorkingDirectory`, `XDG_RUNTIME_DIR` and `HOME`, the
broker's `--compositor-runtime-dir`, the `socketPath` option default, the
`hhstream` CLI's frame-socket default and the `agent-eyes` helper.
An assertion now holds the name at <= 25 characters, the ceiling frozen in
docs/CONTRACT-sessions.md §5, so this cannot regress silently -- the failure
mode is a working request socket and a dead event stream, which looks like
nothing is wrong. Its message says what breaks and why the limit exists.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018YqpJb5aZvZQKb49QDnV7P
A session was a process group, so every application landed on whichever
workspace the compositor happened to show: one session's capture caught
another's windows, and a pointer aimed at one could land in the other.
This is the pure half of the fix. containers.py computes the argv lists
that create a session's container (headless output, numbered workspace
bound to it as default and persistent, an anchored window rule pinning
the session's class there, then the mode) and the one that tears it down,
plus the lowest-free allocator for the 1000+slot band and the
quarantine backstop for windows that match no container. It runs
nothing: no subprocess, no socket, no file, no clock, and no import of
ipc.py, so every decision that can be tested without a compositor is
asserted in a unit test.
Validation is a control, not style: these strings reach a compositor
that acts on them, and a rule body is comma-separated, so a session id
outside [a-z0-9-], a class outside [A-Za-z0-9._+-], a non-positive or
fractional size and a blank quarantine name all raise ValueError naming
the value. Releasing a workspace the allocator never handed out raises
rather than no-opping, because the quiet version hands the same
workspace to two sessions minutes later.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QS2JvrgmvXmimKFcqqDVoa
The plan is the researched design (one compositor, one output+workspace per
session, serialised output-bound pointer input under a lease). The contract is
the freeze point for a parallel build: file ownership per slice, the exact
Python seams, the wire format, and the names and paths nobody may invent.
Kept separate from docs/CONTRACT.md, which governs the frame socket and is
untouched by this work.
`a session touched inside the window is not reaped` was racing itself. The
idle window restarts at the *last* touch, so everything the subtest does
after the loop -- the `status --json` round trip, `kill -0`, and the `kill`
that clears the session away -- has to finish inside one whole window. With
`--idle-timeout 6s` and a `systemd-run --wait` round trip costing several
seconds in this guest, it did not: the session was reaped 6.3 s after the
last touch, legitimately, and the cleanup `kill` arrived ~13.5 s after it
and returned 4 ("not in a usable state"). The daemon was right and the test
was wrong.
The window is now 45 s, which is the margin the cleanup gets. The assertion
is unchanged in meaning and stricter in degree: nine touches 15 s apart --
a third of a window -- keep the session alive for 135 s, three whole
windows of real time, so a `touch` that did not reset the deadline would
have let the reaper fire two windows before the loop ended. Nothing in the
cleanup stamps activity (`registry.touch` has exactly one caller,
`manager.touch`), so the margin is slack and not a hidden touch.
Two details keep it honest rather than lucky: the loop ends with a touch
instead of a trailing sleep, so the cleanup gets a whole window and not a
window less one gap; and it runs under `set -e`, so a `touch` that fails --
exit 4 against an already-reaped session -- fails the loop where it happens
instead of being swallowed by the sleep that used to end each iteration.
Verified both ways: the check passes (258 s; cleanup finished 4.1 s after
the last touch, against the 45 s window), and with `manager.touch`
temporarily not calling `registry.touch` it goes red here, on the touch
that follows the reap, with the diagnostics dump naming the failure mode.
That break is reverted.
The positive control (`the idle reaper fires for real`, 5 s) needs no such
margin and is unchanged: it waits for `reaped`, which is terminal and held
for the tombstone TTL, so time passing only confirms it, and it runs no
cleanup that needs a usable session.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F8R9yNgHeHMnY4nDQwaLtu
Adding the broker's state directory as a second assignment to
systemd.tmpfiles.settings does not evaluate at all (the option takes one
definition), which broke every check that enables sessions. Both reasons to
write a tmpfiles entry now live in one lib.mkMerge.
The unit used systemd's StateDirectory=, which can only ever mean
/var/lib/<name> — on this kind of machine that is the disposable root. The
records the broker adopts and events.jsonl, the audit trail of every accepted
command, are precisely the things that should outlive a reinstall, so they are
now an option (`sessions.stateDir`) and the directory is declared with tmpfiles
so its owner and mode are still declarative.
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.
There are two `sg` on this box: the setuid wrapper in /run/wrappers/bin and a
plain symlink to shadow's sg in the system profile. A login shell has the
wrapper first and works; a cron job's PATH reaches the plain one, which cannot
switch groups and dies with "setgroups: Operation not permitted" — which reads
as "chromium exited immediately" once a consumer discards its stderr. The
helper now looks for a setuid `sg` explicitly and says so if there is none.
One front door to the headless session, for reuse by any consumer: it
discovers whichever wayland-N socket exists, re-execs itself under
sg hhstream when the login predates the group membership, and encodes
recordings at the measured frame rate so clips play at true speed.
A machine running this module has a GPU. aquamarine's headless backend has
no allocator of its own -- `CHeadlessBackend::drmFD()` returns -1 and
`CBackend::start()` takes the allocator from the first backend with a drm fd
-- so the session always rides on the DRM backend and always has the host's
own connectors. `HEADLESS-1` is a name no connector will ever have, which
made the shipped default a monitor rule Hyprland silently ignored, and made
`vm-hyprland`'s assertion on that name unsatisfiable.
`outputs` now means "monitor rules applied to whatever outputs the machine
has". `name` is a regex against the real connector names and defaults to the
empty string -- Hyprland's own wildcard form, as in its shipped
`monitor=,preferred,auto,1` -- so `enable = true` alone gives a session at a
known size on any host. Nothing else about the option changed.
SEATD_VTBOUND=0 moves from checks/lib/gpu-session.nix into the compositor
unit, where it belongs: libseat finds no seatd socket and no logind session
for a system service, falls back to its embedded seatd, and that seat is
VT-bound by default -- so it opens /dev/tty0, which the service user cannot,
and every device open is refused. That is true on any host, not just in the
test. gpu-session.nix keeps only the two things that really are the test
machine's business: a render node and Mesa.
vm-hyprland now asserts over `hyprctl -j monitors` that at least one monitor
exists at the configured mode, with no monitor name anywhere in the check.
It also gains a wallpaper, because `--reject-blank` could not otherwise mean
anything: the session the module configures by default is a flat black
field, which grim captures as an all-zero 1280x720 RGBA PNG of exactly 3653
bytes -- `blank_png_size()` to the byte. Runs that passed that assertion were
reading Hyprland's startup notification overlay, which expires after about
fifteen seconds. With `misc:force_default_wallpaper` on, the frame is 85267
bytes with all 921600 pixels non-zero and is byte-identical at +15s, +30s and
+60s.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M5GEju6XhoRXDWvEiaAX2r
`nix build .#checks.x86_64-linux.vm-basic` failed because Hyprland 0.56.2
aborted with `CBackend::create() failed!` on every start. Reading aquamarine
0.15.1 rather than guessing at it, that abort had three independent causes on a
NixOS test machine, and none of them is visible in the journal until
`debug:disable_logs = false` is set -- Hyprland mutes aquamarine, so the abort
is all that survives. checks/lib/gpu-session.nix now supplies all three and
records the evidence for each:
* `-vga virtio`, for a DRM render node. `virtualisation.graphics = false`
still leaves QEMU's default bochs-drm adapter, which gives card0 and no
renderD*. Measured in the guest: `-vga virtio` -> card0 + renderD128;
`-device virtio-gpu-pci` only *adds* a card next to bochs-drm, so it would
need `-vga none` beside it.
* `hardware.graphics.enable`, so Mesa's GBM backends exist at all. Without it
gbm_create_device() fails with "MESA-LOADER: failed to open dri:
/run/opengl-driver/lib/gbm/dri_gbm.so" and aquamarine reports "Cannot open
backend: no allocator available".
* `SEATD_VTBOUND=0`, so libseat's embedded seatd hands out a seat with no VT.
`CHeadlessBackend::drmFD()` returns -1 unconditionally, so the *only*
source of an allocator is the DRM backend, which opens /dev/dri/card0
through libseat -- and the default VT-bound seat needs /dev/tty0, which the
unprivileged service user cannot open.
The diagnostics dump grows a "graphics devices" section (`ls -l /dev/dri`,
`cat /proc/fb`) and a "wayland socket vs WAYLAND_DISPLAY" section, so the next
machine that is missing a render node, or that binds a socket the frame server
is not waiting on, says so in three lines instead of timing out mutely.
vm-basic's `dump()` is now vm-hyprland's, which reports the exit status too.
vm-basic also gained `python3` in the guest: its last subtest shells out to a
python one-liner and had been dying on exit code 127 -- invisible until the
compositor got far enough to reach that subtest.
Neither check passes yet, and the two remaining blockers both live in
nix/module.nix, which this slice may not edit, so they are reported rather
than patched:
* vm-basic stops at "the module's two units come up". The compositor is up
and healthy; the frame server sits in ExecStartPre forever. The module
hardcodes `waylandDisplay = "wayland-0"`, but Hyprland's socket loop is
`// get socket, avoid using 0` over candidates 1..32 (src/Compositor.cpp),
so the session binds wayland-1. Forcing WAYLAND_DISPLAY=wayland-1 in the
guest was verified to carry vm-basic through every other subtest.
* vm-hyprland stops at "the compositor reports the configured headless
output" with "hyprctl never reported a HEADLESS-1 monitor". hyprctl reports
`Monitor Virtual-1` at 1280x800 -- the virtio-gpu output. A HEADLESS-N
output only exists after `hyprctl output create headless`, which the module
never issues; Hyprland's own fallback output is named FALLBACK. The
`monitor = HEADLESS-1, ...` line in hyprland.conf is a rule for a monitor
that is never created.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018fJZYyS4pqxt2FC37JsFYd