HermenixandClaude Opus 5 a6a4094e6a Stage 3: vm-keyboard, and the helper derivation that never built
The keyboard's only purpose is that a client receives symbols, so a unit
suite alone was testing the shape of a request nobody answered --
docs/TODO/scroll-has-no-compositor-proof.md is the precedent. This is
the compositor proof: two nixosTests, 16 subtests each, real time, no
injected clock.

  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard
    test script finished in 281.06s   (16/16, exit 0)
  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard-de
    test script finished in 278.15s   (16/16, exit 0)

The victim, checks/lib/keyboard_target.py, decodes every keysym from the
keymap the COMPOSITOR forwarded rather than from a table of its own.
That is the mutation rule PLAN §14 asks for: a driver that stopped
uploading leaves the client with nothing to decode with, every key
arrives as `sym=?`, and the character assertions go red. A victim with
its own keymap would decode `hello` either way and the check would be
asserting that the check can spell.

What the client actually reported, which is the point of reading back
the application's state rather than the broker's intention:

  type A        [(30, 1, 'A'), (30, 0, 'A')]   masks [1, 1, 0, 0]
                -- evdev 30 decoded as A, so the mask arrived BEFORE the
                   key, and no code 42 anywhere
  key Return    [(28, 1, 'Return'), (28, 0, 'Return')]
  TTL expiry    [(42, 1, 'Shift_L'), (42, 0, 'Shift_L')] masks [1,1,0,0]
                -- lifted by the sweeper alone, mask cleared with it
  chord         depressed mask [4, 4] while Control held, still held
                   after the type returned

It runs TWICE because `sessions.keyboard.layout` reaches the uploaded
keymap through exactly one path -- `--xkb-layout` on the driver unit's
argv -- and one layout cannot tell that path from a hardcoded `us`:

  us:  symbols=pc_us_inet(evdev)  bytes=35572
       type y -> [(21, 1, 'y')]   type z -> [(44, 1, 'z')]
       type cafü -> exit 2, "scalar 3 (U+00FC) is not typeable", and the
                    client reported [] -- no prefix typed
  de:  symbols=pc_de_inet(evdev)  bytes=37532
       type y -> [(44, 1, 'y')]   type z -> [(21, 1, 'z')]   (swapped)
       type cafü -> {'chars': 4, 'ok': True}
                    client decoded ['c', 'a', 'f', 'udiaeresis']

Hyprland's own input:kb_layout is left at `us` in BOTH runs, so a client
that ignored our keymap would decode the us answer on the de machine.

The decisive subtest is "acquire takes the KEYBOARD as well as the
cursor". With session B holding keyboard focus because its window mapped
last, acquire on A delivered wl_pointer.enter AND wl_keyboard.enter to A
and wl_keyboard.leave to B, with focus == "warp". A check that asserted
only pointer delivery would have gone green while A had the cursor, B
had the keys, and the first keystroke of the lease went to B -- which is
exactly what one warp does. §B3's "one warp" and the Stage 0 review's
"do not assert enter on acquire" are superseded by the two-warp acquire,
and the header says so.

One deviation from §B3, with reasons in the header: its subtest 4 says
`type y` decodes to sym `z`, which is wrong for a victim that decodes
from the forwarded keymap -- the same paragraph requires that. `type y`
resolves keysym y against the uploaded layout and sends that layout's
code; the client decodes it back to `y`. The sym is `y` on both layouts
by construction. What differs is the CODE, the symbols name, and whether
ü is typeable at all, and those are what this asserts.

── AND A PRE-EXISTING BUG THE FIRST RUN EXPOSED ──────────────────────

checks/lib/session-tools.nix opened a heredoc with `<<EOF` and closed it
with an INDENTED `  EOF`. A delimiter has to be at column zero, so it
never closed: it swallowed the rest of the builder -- both `install`
lines and every self-test -- into the shim's own text. The derivation
built anyway, with `hhs-ipc-watch` alone in $out/bin:

  $ ls /nix/store/wy3lp3...-hhstream-session-tools/bin/
  hhs-ipc-watch

So hhs-pointer-target has NEVER existed in that derivation either.
vm-pointer execs that absolute path, and vm-keyboard failed the same
way: the broker reported `target exited immediately (exit code 127)`,
which is true about a path that was never created and says nothing about
why. hhs-ipc-watch's own first line was `  #!...`, indented, which is
not a shebang, so vm-ipc is affected too. The build-time self-tests that
exist to catch exactly this had themselves become heredoc text. The
unquoted delimiter also expanded the swallowed text, so the builder ran
`hhstreamd.ipc` as a command.

The shim is a writeTextFile now -- no delimiter to indent wrong -- and
`test -x` on all three programs is the guard that would have caught it.

NOT DONE, and it needs doing: vm-pointer and vm-ipc have not been
re-run. checks/default.nix says one VM at a time on this two-core box
and I did not want to perturb the keyboard runs. That they WOULD have
failed is read off the store listing above, not off a run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 20:23:14 +00:00
2026-09-28 05:01:41 +00:00
2026-09-28 05:01:41 +00:00
2026-10-04 03:39:00 +00:00

hyprland-headless-stream-plugin

A Nix flake that runs a headless Hyprland session and publishes its frames on a persistent Unix socket, so any process that can open a socket can see the screen without owning a display.

Two parts:

  • NixOS module — services.hyprland-headless-stream: starts Hyprland with no physical monitor, and a small frame server beside it.
  • Package — hhstream — the frame server (publishes frames) and its client (reads them). Pure Python standard library.
{
  inputs.hhstream.url = "git+https://<host>/git/<owner>/hyprland-headless-stream-plugin.git";

  # in your host config
  imports = [ inputs.hhstream.nixosModules.default ];
  services.hyprland-headless-stream = {
    enable = true;
    # Optional: the default is one 1280x720@30 rule with an empty name, which
    # is Hyprland's wildcard and applies to whatever outputs the GPU has.
    outputs = [ { width = 1920; height = 1080; refresh = 60; } ];
  };
}

Then any consumer:

hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png

The socket is a plain file descriptor: the server serves every client that connects, and keeps running when one disconnects.

Document What it is
docs/CONTRACT.md the wire protocol and the module surface — the interface other people build against
docs/ARCHITECTURE.md how the pieces fit: compositor, capture, server, client
README.dev.md how to build, test and hack on it
examples/README.md the demo that films the screen: agent-eyes-demo.py

Status: work in progress — the module and the test suite are being built.

S
Description
No description provided
Readme
2.8 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 81.7%
Nix 18.1%
Shell 0.2%