Commit Graph
24 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 b1f2744cf0 Stage 0 review: correct what the log does not say, and edit the plan
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
2026-10-04 03:46:53 +00:00
HermenixandClaude Opus 5 f931858f30 Stage 1: the driver learns to type
`zwp_virtual_keyboard_v1`, spoken by the process that already speaks
`zwlr_virtual_pointer_v1`. One device for the seat, one keymap uploaded
once, keysym names on our socket and evdev codes only on the Wayland
request -- the division buttons.py already draws.

keymap.py is the new seam, and it holds the three decisions that have a
wrong version which looks right:

  * A capital is the MASK, not a synthetic Shift keycode. Hyprland's
    virtual keyboard never runs updateXkbStateWithKey, so a virtual
    KEY_LEFTSHIFT changes no modifier state at all -- and sending both
    is how a toolkit applies Shift twice.
  * A modifier is whatever the keymap says is one, measured by pressing
    each key in a throwaway xkb state. Not a name list: `@` on `de` is a
    level-three symbol, and a Shift-only special case types the wrong
    character. (The measured set is also smaller than the canonical one,
    because no keycode on us/pc105 carries Meta or Hyper.)
  * A lock is not a modifier. Caps_Lock reports a *locked* mask, so
    `type` refuses while it is held rather than guessing the case.

The whole string resolves before anything is emitted, and every refusal
names the scalar INDEX, never the character: these messages reach the
driver's log and the string is a password as often as not.

Folding in the review's changes 1, 2, 3 and 6:

  1 a Rejected now carries a `kind`. A bad keysym or an unmappable
    character is `invalid_argument`; a missing keyboard global is
    `refused`. Without the token the broker would have to tell exit 2
    from exit 10 by reading English, and _drive maps every `ok: false`
    to driver_refused today.
  2 the keymap `size` on the wire includes the trailing NUL, and the fd
    outlives a roundtrip rather than a flush. Hyprland mmaps exactly
    that many bytes and hands the pointer to xkb_keymap_new_from_string.
  3 release_all lifts buttons, then keys in press order, then zeroes the
    mask -- and the mask only if something set it, so a compositor with
    no keyboard global still gets its buttons lifted. One release_all is
    the whole of expiry; an exception in the key half would abandon it.
  6 `key` and `type` never call _aimed(). A keyboard has no output, and
    one test deliberately never warps so that stays true.

Also: `--xkb-layout/-model/-variant/-options`, compiled BEFORE any
Wayland call so a bad layout is exit 2 rather than exit 10; a comma in
the layout refused outright, because v1 always sends group 0 and
xkbcommon would hand back a second group nothing could reach; the
keymap uploaded after connect and before listen, with one
modifiers(0,0,0,0) after it; and xkbcommon as a hard, non-optional
dependency -- an optional one would let test_keymap.py skip, and the
unmappable-character path is the one that must not rot.

  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
  549 passed in 25.70s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:39:00 +00:00
HermenixandClaude Opus 5 19e484b388 Stage 0: measure the compositor instead of reading its source
A throwaway client against the live /run/hypr-stream that answers the
four open questions. It touches no broker, no lease and no session; it
opens two windows of its own and moves the one cursor, because keyboard
focus cannot be measured without doing both, and it refuses to send a
key until it sees wl_keyboard.enter on a surface it owns.

What it found, with the transcript beside it:

  1  zwp_virtual_keyboard_manager_v1 is present at version 1. The gate
     the plan hangs on holds against the running binary, not just
     against §6.7's [RAN] claim.

  a  ONE IDLE WARP DOES NOT MOVE KEYBOARD FOCUS. A second warp
     immediately after does. Measured with an unfocused fullscreen
     window under a focused floating one, warping into the margin that
     belongs to the first alone -- and `pointer acquire` is one warp, so
     the first key of a lease can land in the previously focused
     window. Neither plan permits building the fallback here, so this
     branch does not; it is the objection in the final report.

  b  destroy with a key down releases nothing and clears no mask
     (release_pressed_on_close is 0 and unset). An earlier run proved it
     by accident: it exited with Shift_L down and the NEXT run's first
     enter carried keys=[42, 0, 0, 0].

  c  one held key is one wl_keyboard.key, with repeat_info 25/600. The
     flood is the client's repeat, not ours -- which is why `down` warns
     unconditionally rather than only if the probe saw repeats.

The XML both plans name does not exist in this nixpkgs: not in
wayland-protocols 1.49, not in wlr-protocols, not in wlroots. Hyprland's
own copy is the only one, so that is what is used -- and because it
names keymap_format and key_state without defining them, both are
written down as cited constants instead of read off an enum.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:21:14 +00:00
Hermenix acdfb2801e the default capture command now asks for the cursor
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.
2026-10-03 19:42:13 +00:00
Hermenix 352cfdcb24 claim windows by pid, and find the compositor after a restart
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.
2026-10-03 19:39:33 +00:00
HermenixandClaude Opus 5 6b395305e0 scroll: one verb, two axes, and the sign carries the direction
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>
2026-10-03 19:05:39 +00:00
Hermenix 8f3f000783 read the config the module writes: containers can be turned off
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.
2026-10-03 12:10:19 +00:00
HermenixandClaude Opus 5 de408e4b7f the surface: CLI verbs, the module's options, and three checks the compositor votes in
Everything below the CLI was merged and green against fakes; none of it was
reachable and none of it had ever met a compositor. This wires it up and then
puts the compositor in a position to disagree.

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

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

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

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

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

Module (nix/module.nix)

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

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

Checks (checks/**)

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

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

  vm-pointer: a version-2 virtual pointer, a warp and a click whose
  coordinates the *application* reports, BUSY naming the holder, an expired
  lease swept with its held button lifted, and a broker restart that leaves
  the lock free, the bookmark intact and the driver reachable.

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

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

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WQy29x9AfHWyzNd1f7XPGK
2026-10-03 06:58:44 +00:00
Hermenix 57fdd4f636 ipc: Monitor gains the id that CONTRACT-sessions v2 promised
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.
2026-10-03 04:51:07 +00:00
HermenixandClaude Opus 5 129430bffd wire the broker to the compositor, containers and pointer
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
2026-10-02 19:47:33 +00:00
Hermenix 20b2aee109 unit check: run the whole tests/ tree, not just tests/unit
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).
2026-10-02 18:14:48 +00:00
Hermenix e8b3855a05 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.
2026-10-02 18:11:46 +00:00
Hermenix d45219994e tests: make the test basenames unique so the whole tree collects
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.
2026-10-02 18:07:48 +00:00
Hermenix 8c180ec938 merge slice/pointer into main
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.
2026-10-02 18:05:48 +00:00
Hermenix 28b4b4b2cd merge slice/containers into main
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.
2026-10-02 18:05:48 +00:00
HermenixandClaude Opus 5 0d414d76bc pointer: the lease, and a driver process that only executes
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
2026-10-02 00:15:50 +00:00
HermenixandClaude Opus 5 9b77c77ee8 ipc: a client that asks the compositor instead of guessing
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
2026-10-02 00:12:44 +00:00
HermenixandClaude Opus 5 01460016e7 containers: a headless output and a persistent workspace per session
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
2026-10-02 00:02:40 +00:00
Hermenix 30f456c07e integrate the session broker: one CLI, a module unit, and a VM check
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.
2026-10-01 12:23:16 +00:00
HermenixandClaude Opus 5 a37b3dd485 checks: give both VM machines a virtio GPU, and say why when it is not enough
`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
2026-09-28 12:28:01 +00:00
Hermenix 578e14286d tests: merge the two unit-test conftests into one fixture set 2026-09-28 11:52:32 +00:00
Hermenix 72f359932a Merge branch 'slice/tests'
# Conflicts:
#	tests/unit/conftest.py
#	tests/unit/test_capture.py
#	tests/unit/test_client.py
#	tests/unit/test_protocol.py
#	tests/unit/test_server.py
2026-09-28 11:51:07 +00:00
HermenixandClaude Opus 5 4af6f7072a server, client: implement the v1 frame protocol end to end
Fill in the bodies the skeleton left as NotImplementedError, to docs/CONTRACT.md:

- protocol: the `\n`-terminated JSON Hello and the `<ascii length>\n<payload>`
  frame, both directions. Malformed input raises (ValueError for a bad length
  prefix, EOFError for a truncated payload), never hangs on endless garbage and
  never silently truncates; a huge length prefix is not pre-allocated.
- capture: CommandCapture runs the configured command and reports a missing
  binary, a non-zero exit, a timeout and empty output as CaptureError, with the
  helper's stderr folded into the message so nothing leaks to the server's own
  stdio. The Hello's pixel size is read from the frame's PNG/JPEG header, so no
  compositor query is needed and an injected fake command behaves the same.
- server: one capture thread holding only the newest frame plus one thread per
  client, which is what drops frames for a slow client instead of queueing
  them. Survives a client dying mid-write, keeps the socket up across capture
  failures, withholds the Hello until a size is known, replaces a stale socket
  file (but never a non-socket one) and publishes it mode 0660.
- client: fetch()/read_stream() and the CLI, with --out suffixing per frame.

--capture-command folds its separated form into `--flag=value` before argparse
sees it, so the contract's default `grim -t png -` can actually be passed: its
tokens start with a dash.

Unit tests under tests/unit cover framing round-trips (including a payload
containing `\n` and a zero-length frame), truncated and garbage prefixes, a
stalled client not blocking a second one, a client dying mid-frame, frames being
dropped rather than queued, and every capture failure mode. A fake capture
command stands in for grim, so nothing needs a compositor or a GPU. They are
deliberately not wired into flake.nix: `checks` belongs to another workstream.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FYJ8ZQ5AZaDErYTwXZe7N9
2026-09-28 05:35:17 +00:00
HermenixandClaude Opus 5 75a05cd72f tests: checks.{unit,vm-basic,vm-hyprland} + the harness behind them
Wires a `checks` output into the flake, one file per check under checks/,
all three asserting docs/CONTRACT.md rather than the implementation:

- unit: pytest over tests/unit/ in the build sandbox, against the
  nix/package.nix build. Refuses an empty suite -- pytest exits 0 when
  every test was skipped or deselected, so checks/lib/check_report.py
  parses the JUnit report and fails on zero collected or zero executed.
- vm-basic: nixosTest with captureCommand pointed at tests/fake_capture.py,
  which emits one fixed deterministic PNG. Because the image never changes,
  "two frames arrived and they are the same bytes" is an assertion about
  the framing rather than a coincidence.
- vm-hyprland: the same machine with no captureCommand override, so grim
  captures the real compositor. Deliberately impatient -- bounded timeouts,
  no retry loops, and a full diagnostics dump (compositor log, hyprctl
  monitors, both journals) before any failure propagates.

tests/assert_stream.py is a second, independent reader of the contract: it
shares no code with hhstream.client, so a framing bug present in both the
server's writer and the shipped client's reader still fails. The unit
suite's negative tests use a `rejects` fixture instead of
pytest.raises(Exception), which an unimplemented stub's
NotImplementedError would otherwise satisfy.

Three defects found in code this branch does not own, recorded in
README.dev.md rather than worked around:
- nix/module.nix has no config side, so neither unit exists and both VM
  checks fail at their first wait;
- services.hyprland-headless-stream.package is declared with no default,
  against docs/CONTRACT.md;
- src/hhstream/*.py is all stubs, so 66 of 70 unit tests fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017YXMoCNxzScTaKNr43GQNz
2026-09-28 05:25:37 +00:00