Found on the deployment machine on 2026-10-11, the first time `hhstream-live`
was run **as a unit** rather than from a login shell: a systemd unit's PATH has
no system profile, so the capture command `grim` is not found, ten times, and
the stream gives up. It answers on its port, serves the landing page and
reports `"stopped": true, "failures": 10` while showing nothing -- the quiet
half of the failure is what makes it worth a file.
The module already solves this for `sessions.apps` by requiring an absolute
store path; the stream's unit has to do the same (or set PATH, which is what
made the deployment run work). Recorded in `docs/TODO/` with the two fixes, and
named as a risk on stage 3 of the plan, which is the stage that turns this from
an experiment into the only path.
The same shape as the merge that branch got on 2026-10-05 (edbf15f on
feat/session-live-stream): this machine's own config sets
`sessions.keyboard.layout`, so a ref without the keyboard work does not
evaluate -- and the point of this branch is to be consumed here.
The stream branch's own commit is the first parent, so PR #2 stays based on
main and carries none of this merge. Conflicts were additive on both sides
(new option blocks, new checks, new README rows) and are resolved by keeping
both.
`sessions.stream { port, bind, openFirewall }` -- the piece of stage 3 that
does not need the broker. It exists because a machine had to be able to *reach*
a stream before the rest of the app is settled: the operator asked for the port
to be open on the deployment machine, where the app still runs by hand, and a
bare `networking.firewall.allowedTCPPorts` line in one machine's config is the
wrong place for a fact about this flake.
- `openFirewall` defaults false and is deliberately not implied by
`sessions.enable`: a live view of the desktop is readable by anyone who can
reach the port, the phrase in the URL is its only credential, and there is no
TLS. It opens exactly one port -- the one the option names.
- `bind` defaults to loopback and is *checked*: `openFirewall = true` beside a
loopback bind is refused, because that is a hole with no service behind it.
- `checks/vm-stream-firewall.nix` boots the module with a configured port that
is not the module's default, puts listeners on that port and on a neighbour,
and asserts from a second machine on the same VLAN that the peer reaches the
configured port and is refused on the other -- while both answer on loopback
inside the guest, so the refusal is the firewall's doing and not an empty
socket. The peer is a second machine because a probe from the test driver
proves nothing: the driver is not on the test VLAN.
Nothing here turns a stream on -- no unit, no phrases, no `session stream`
verbs, which stay stage 2+3 -- and docs/plans/2026-10-04-session-stream-webapp.md
now records which part of its stage 3 landed and why out of order.
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 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).
From docs/reviews/2026-10-04-stage2-3-review.md (Stage 3 done; Stage 2
done-with-fixes). Its findings 1, 2, 3 and 5, which it called the only
things standing before merge.
(A) REPLAY, THROUGH THE SINK. What existed was
`test_every_keyboard_verb_is_cached_for_the_same_reason`, which
asserts the two verbs are in MUTATING_VERBS -- and the verification
doc had already named that as the false pass: "asserting
`deduplicated` and not the sink. A handler that types and then sets
the flag stays green." Two integration tests now, modelled on
`test_a_retried_click_with_the_same_request_id_clicks_once`:
test_a_retried_type_with_the_same_request_id_types_once
`keyboard.type` of "ab" twice with request_id="retry-me".
Asserts `deduplicated`, chars == 2 on both, and that the sink
still has exactly 4 key events -- two characters, a down and an
up each -- so a replay that typed again is caught by the count
and not by the flag.
test_a_retried_unmappable_type_stays_refused_and_types_nothing
`café` twice with one id. Both refusals are `invalid_argument`,
the second carries `deduplicated` (a recorded failure is
replayed as the failure it was), and the sink is empty after
both -- there is no partial type on either call.
Mutation-checked rather than assumed: removing `keyboard.key` and
`keyboard.type` from MUTATING_VERBS fails both.
(B) KILL, THROUGH kill(). `test_killing_the_holder_lifts_its_keys` calls
`_drop_lease_for` directly, so it proves that helper lifts keys and
says nothing about whether `kill` still calls it. The integration
kill test now holds `Shift_L` before the kill and asserts the SINK
saw `("key", 42, 0)` and `("modifiers", 0, 0, 0, 0)` -- the lease
forgetting a key is not the compositor being told it came up, and
only the second matters to the application. Code 42 because `type`
never emits it, so the release cannot be a leftover.
Mutation-checked: stubbing out the `_drop_lease_for` call in
`kill()` fails it. Before this it stayed green.
(C) DOCS. The plan's stage table and risk paragraph still said acquire
is one warp and that `focuswindow` was unbuilt Stage 4 work. The
contract (v3 §4) describes what shipped; the plan did not. Rewritten
so they agree, and the plan now says outright that the contract wins
where they differ:
* risk 1 marked RESOLVED, describing the two warps, the pinned
`follow_mouse_threshold`, and `focuswindow` as the
nudge-failure fallback selecting on `address:` (not
`stable_id`, which is not a Hyprland selector)
* Stage 3 marked Done; Stage 4 struck as not existing -- the
answer to Stage 0 was the second warp, not a focus dispatch
* the top banner, the §5 VM assertion list and open question 2
no longer say "one warp"
* verification §B3 subtest 1 amended: it is a live assertion
rather than an expected red, and the check additionally requires
`focus == "warp"` so the fallback is not accepted as success
Also amended one sentence the review did not list, because leaving
it would contradict the edit above inside the same document:
verification §"Warp does not guarantee wl_keyboard.enter" predicted
`focuswindow` was "likely mandatory". It was not; the second warp
was.
Written down rather than smoothed over: the `focuswindow` branch
itself has no test, and if both mechanisms fail acquire still
returns ok with `focus="none"` -- a lease whose first key may go to
the previously focused window.
(D) The tap docstring claimed the `up` is sent even if the `down` was
refused after sending. The next lines return early on `not ok`, and
that early return is right: a refusal means the key was never
pressed, so an `up` would ask the compositor to release something it
never had. Sentence replaced with why the early return is correct
and what actually covers a lost reply (the broker's `release_all`,
not the CLI, which cannot know whether the request arrived).
Not done, and not claimed: findings 4, 6 and 7 (the broker chord test
checking first/last mask rather than the key; the at-cap test not
looking at the sink; the module-defaults test being a substring match).
The review rates all three as not holes in the claim, and the driver
tests are the locks for the first two.
nix develop -c python -m pytest tests -q
907 passed in 67.71s
nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
605 passed in 27.16s
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
The Stage 1 review (docs/reviews/2026-10-04-stage1-review.md, verdict
yes-with-fixes) found a real bug, and it was the kind Stage 2 would have
cemented. All five findings:
(1) HIGH, and reproduced before fixing: `key` resolved the action and
then used only its `code`. So `keyboard key A` sent a bare code 30
and the window received `a`; on `de`, `at` lost its level-three mask
and typed `q`. `type` was the only path that used the mask, which is
why every `type` test stayed green. `key` now sends
modifiers(baseline | mask) before the down and restores the baseline
on the up -- the one-character `type` sequence -- and `Shift_L`
keeps its key-then-mask order, which is the other path on purpose.
The same hole aliased two names onto one keycode: `down A` then
`down a` recorded both and pressed 30 twice, Hyprland dropped the
second, and the held set lied until the lease ended. A second name
for a code already down is now refused.
(2) HIGH: the shutdown comment claimed hyprland-conf.nix sets
input:virtualkeyboard:release_pressed_on_close. It did not. The line
is there now, with the note that it releases keys and still never
clears a mask -- which is why release_all zeroes the mask on every
path we control rather than relying on it.
(3) MEDIUM: nothing would have noticed the keymap upload stopping. A
`main` that connected and listened without uploading passed every
test in the tree. Now asserted on the real sink: uploaded once,
before `listen` (one shared ordering log across both stand-ins), the
payload NUL-terminated with `size == len(utf8) + 1` read back
through the fd, format 1, one terminator not two, and modifiers(0)
straight after.
(4) LOW: `key` up now forgets the name only after a successful send,
like `button` -- otherwise a raise between the two leaves us
believing a key is up that the compositor still has down, and
release_all will not try again.
(5) LOW: `\r` no longer aliases to Return (CRLF would have become two
newlines silently), and an empty layout is refused -- xkbcommon
compiles "" as the same keymap as `us`, so `--xkb-layout ''` looked
configured and typed `us`.
Several of the review's named false passes are closed too: Control's
mask is compared against mod_get_index("Control") rather than merely
"not Shift's"; the keymap text assertion names pc_us_inet/pc_de_inet
instead of substring-matching "us"; the capital-under-Control case
asserts the whole sequence; the exit-code mirror is compared against
hhstreamd.protocol; and the module's defaults are read out of
nix/module.nix rather than asserted against themselves.
Stage 2 proper:
* broker verbs keyboard.key / keyboard.type, both in the mutation set,
both through _refresh (so they refresh the lease and, like every
pointer verb, do NOT count as activity)
* the driver's `kind` token mapped: a bad keysym or character is
invalid_argument (exit 2), a missing keyboard global stays
driver_refused (exit 10). The 4096-scalar cap and the shape checks
are broker-side, because only a broker-side invalid_argument is 2
* keys[] on pointer.state, keys_lifted[] on pointer.release and on
pointer_lease_timeout, one release_all for both halves
* CLI `session keyboard type|key|down|up`, reusing the pointer lease
and its cache; `type` takes one raw argument and interprets nothing;
the audit records a character count and never the text
* sessions.keyboard.{layout,model,variant,options} on the unit's argv,
layout defaulting to "us" with a type that refuses a comma. NO
[keyboard] TOML table: hhstreamd reads that file and the driver is a
different unit, so it would be a setting with no effect
* CONTRACT-sessions.md bumped to v3; README.dev.md item 3 and
vm-pointer.nix's header corrected (both still said the conf ships
follow_mouse = 0 and that the keyboard work would choose)
And the operator decision that acquire grabs both devices: it now sends
two warps a real pixel apart, because one warp onto an idle cursor moves
the cursor and not keyboard focus. follow_mouse_threshold = 0 is set
explicitly in hyprland-conf.nix since the second warp depends on it,
`dispatch focuswindow` is the fallback when the nudge cannot be sent,
and the reply and audit carry which mechanism ran. The acquire test
asserts the pair and that they floor to different pixels -- a test that
only saw wl_pointer.enter would pass while the first keystroke went to
the wrong window.
nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
605 passed in 27.11s
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
The Stage 0 review (docs/reviews/2026-10-04-stage0-review.md, verdict
yes-with-fixes) found that the measurements were sound and the write-up
was not. All four of its high and medium defects, verified against the
committed transcript before fixing:
(1) 19e484b's README claimed a verbatim excerpt and printed serial=336
while the run's (a2) enter was serial 371. It also claimed six
reproductions with one transcript, and cited a `keys=[42, 0, 0, 0]`
enter from a run whose log was never kept -- every enter in the
committed file is `keys=[]`. The excerpt is now copied from the log
with line numbers to check it against, the reproduction claim is
gone, and the Shift observation is named as not-in-this-log.
(2) THE (a) CONCLUSION WAS WRONG, and it is the one that matters. The
first idle warp onto the unfocused window gave wl_pointer.enter and
NO keyboard enter; the leave/enter arrived on the LATER motion. So
it is not "enter, one warp late" -- the first warp's delta is set to
0, the threshold is 0.0, and the second motion's own non-zero delta
is what focused. Two corollaries the old text got backwards: a
second warp to the SAME point returns before mouseMoveUnified
touches the delta and proves nothing, and waiting longer does not
help. The probe now prints both targets and the measured gap
(0.401s) instead of hardcoding the word "immediately", and its
ANSWER string says the mechanism.
Consequence, now stated everywhere it belongs: `pointer acquire` is
one warp, so the first key of a lease can land on whatever was
already focused. Stage 3's enter subtest must not be designed from
acquire's single warp, and must not be made to pass by warping twice
to the same bookmark.
(3) d07a1fd did not edit the plan -- `git diff 14b3f69 HEAD --
docs/plans/2026-10-03-keyboard-input.md` was empty, so anyone told
to follow the plan still had the contradicted text. All eight
pre-code changes are now folded into that file, each marked
[SUPERSEDED], plus a banner at the top. Changes 5 and 7 were the
ones that had survived intact in four places: the [keyboard] TOML
table (dropped -- the broker reads that file and the driver is a
different unit, so it would have been a setting with no effect) and
"if it repeats, the help text says so" (now unconditional). The four
closed open questions and the stage table are updated with what
Stage 0 measured, including that Stage 4 is no longer contingent.
(4) mask_cleared=no was reported as a held mask surviving destroy. The
held key was a letter, so the mask was 0 throughout; the README now
says destroy emitted no key-up and no modifiers event, and that the
reason release_all still sends modifiers(0,0,0,0) is
VirtualKeyboard.cpp's releasePressed, not this line. The real
poison evidence is promoted: onKeyboardKey drops a release whose
code is not in m_pressed, so the cleanup's `key code=30 state=0`
arriving from a brand-new keyboard proves 30 was still in that set.
The transcript is a fresh run of the corrected probe, so the file and
the claims about it agree line for line.
19e484b's message carries defect (2)'s wrong causality. It is corrected
here rather than by rewriting that commit, so the hashes the reviewer
cites keep resolving.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
An adversarial read of 2026-10-03-keyboard-input.md against this tree and
against Hyprland v0.56.2. Its verdict is "safe to build on, not safe to
implement as written", and its §"Changes required before code" is the list
Stages 0-2 are built to rather than the original plan where the two differ:
1 exit 2 vs driver_refused -- _drive maps every `ok: false` to
driver_refused (exit 10), so the plan's "exit 2 for a bad keysym"
needs a token the broker can map to invalid_argument
2 the keymap `size` must include the trailing NUL
3 release_all must no-op its key half with no keyboard object, and
must end with modifiers(0, 0, 0, 0)
4 input:virtualkeyboard:release_pressed_on_close defaults to false
5 the layout reaches the keymap only as --xkb-layout on the driver
unit; a [keyboard] table in the broker TOML would be a false pass
6 the modifier-keysym set has to be written down; no Shift special case
7 Stage 0 expectations, including a two-window probe
8 acquire's stderr, and an index rather than the string in logs
It also writes the test specs for Stages 1-3, including the false pass
beside each assertion, which is the part the unit tests are written from.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
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.
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>
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
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 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.
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.
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