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.
33 KiB
Plan — per-session workspaces, outputs, and pointer input
Technical specification for the next milestone of the headless-Hyprland session
broker. Every claim about the compositor in here is either [RAN] on this
machine or read from the running build's source at tag v0.56.2; the evidence
markers and citations are in REPORT.md (same directory as the brief that
produced it).
Status: proposal — not approved, nothing built. Stage 0 is a prerequisite for all of it and is nearly free.
1. Goals and non-goals
Goals
| ID | Goal | Verified possible? |
|---|---|---|
| G1 | A session owns a spatial container: listable, capturable in isolation, and torn down as a container — not just a process group | Yes — one headless output + one persistent workspace per session |
| G2 | A session's identifier is returned at start and is sufficient later to observe, keep alive, kill, and now target input at | Yes — session start already prints the bare id; the record gains container fields |
| G3 | Mouse input aimed at one session, without disturbing another session's contents | Yes — output-bound virtual pointer, serialised by a broker-wide lease |
| G4 | Several sessions coexist, isolated enough that one cannot disturb another's container | Partly — spatial isolation yes; adversarial isolation needs Stage 4; crash isolation needs Stage 5 and this machine cannot afford it |
Non-goals (deliberate, for now)
- Concurrent pointer input in one compositor. Structurally impossible: one
wl_seat, onem_pointerPos. A second cursor requires a second compositor. - Per-tenant compositors on this machine. Hyprland consumes 96.6% of a core
continuously at
debug:vfr = falsewith software rendering on a 2-core box. Stage 5 is specified but gated on the CPU question. - Typing. Keyboard injection uses the same seat and the same serialisation question; it is specified as an extension of the pointer lease (§6.7) but not in the first three stages.
- A general window-management API (move/resize/stack). The session owns a container; it does not manage windows inside it.
2. Architecture
┌──────────────────────────────┐
frame clients ──▶│ hyprland-headless-stream │ JPEG frames of ONE output
│ (frame server, stream.sock) │
└──────────────┬───────────────┘
│ grim -o <output>
┌──────────────────────────────┴──────────────────────────────┐
│ hyprland-headless.service — ONE compositor, N outputs │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ output hh-A │ │ output hh-B │ │ output main │ │
│ │ ws 101 │ │ ws 102 │ │ ws 1 │ │
│ │ [app A] │ │ [app B] │ │ wallpaper │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└───────▲──────────────────▲───────────────────▲──────────────┘
│ request socket │ socket2 (events) │ virtual pointer
│ hyprctl / IPC │ │ (output-bound)
┌───────┴──────────────────┴───────────────────┴──────────────┐
│ hhstream-sessions.service — the broker (as `hermes`) │
│ registry │ launcher │ ipc client │ pointer service │ reaper │
└───────▲─────────────────────────────────────────────────────┘
│ control socket (JSON request/response)
┌───────┴─────────────────────────────────────────────────────┐
│ hhstream CLI — status│shot│run│record│session … │
└─────────────────────────────────────────────────────────────┘
Four moving parts change; the frame server is untouched except for which output it captures.
2.1 Component responsibilities
| Component | Owns | Must not |
|---|---|---|
hyprland-headless (compositor) |
seats, outputs, workspaces, windows, the one cursor | know about sessions |
hhstreamd (broker) |
the registry, session lifetime, containers, the pointer lease, the audit log | guess compositor state; act on a container it did not create without verifying |
hhstream (CLI) |
argument parsing, exit codes, human formatting | hold state; talk to the compositor directly |
| frame server | encoding and publishing frames of a nominated output | know which output belongs to whom |
3. Stage 0 — rename the runtime directory (prerequisite)
Problem. $XDG_RUNTIME_DIR is /run/hyprland-headless-stream (29 chars).
Hyprland's IPC sockets are $XDG_RUNTIME_DIR/hypr/$HIS/.socket.sock and
…/.socket2.sock, and the instance signature alone is ~30 chars, so the path
exceeds sun_path's 108-byte limit. The compositor logs
ERR ]: Socket2 path is too long. (2) IPC will not work. [RAN]
Consequence today. The request socket works by luck of residual truncation
(it is silently a different, shorter path both sides agree on); the event
socket does not work at all. A generated comment in the Hyprland config asserts
the IPC is misnamed and that hyprctl clients cannot connect — that is wrong in
cause and conclusion; hyprctl version|monitors|workspaces|clients|devices| layers|instances|cursorpos|status all answer correctly against the live
compositor [RAN].
Change. Rename to /run/hypr-stream (15 chars) everywhere:
nix/module.nix:RuntimeDirectoryfor both units, the published socketdefault, and the broker's--compositor-runtime-dir./etc/nixos/hyprland-stream.nix:socketPath,sessions.stateDiris unaffected.- The frame server's
HOME/WorkingDirectory. - The
hhstreamCLI's default frame socket. - Remove the incorrect comment claiming IPC is broken, and replace it with the
measured reason for the name length (hard requirement: ≤ 25 chars, so
socket paths stay under
sun_path).
Gate. In a VM: both sockets exist at their real names; hyprctl answers;
a socket2 client receives openwindow/workspace events for a window it
created. Rollback: the rename is config-only; reverting restores today's
behaviour exactly (including the broken event socket).
Risk. Anything holding the old path. Enumerated above; there is nothing else on this machine.
4. Stage 1 — the broker speaks IPC
4.1 IPC client (src/hhstreamd/ipc.py)
One client, two sockets:
| Socket | Use | Failure behaviour |
|---|---|---|
hypr/$HIS/.socket.sock |
request/response queries | retry once, then degrade (§4.4) |
hypr/$HIS/.socket2.sock |
event stream | subscribe; on loss, reconcile by re-querying |
Instance discovery: HYPRLAND_INSTANCE_SIGNATURE if set, else the single
$XDG_RUNTIME_DIR/hypr/<sig> directory. Store the signature in the session
record so a restart re-attaches to the same instance rather than guessing.
Commands used (all [RAN] as available on this build):
| Purpose | Command |
|---|---|
| liveness / version | version |
| outputs and their rects | monitors (with per-output x,y,width,height,scale) |
| workspaces and their monitors | workspaces |
windows with class, title, workspace, monitor, stableId |
clients -j |
| cursor position (diagnostics only) | cursorpos |
Events consumed from socket2: openwindow, closewindow, movewindow,
movewindowv2, activewindow, activewindowv2, workspace, workspacev2,
focusedmon, monitoradded, monitorremoved, urgent.
4.2 Reconciler
An event stream that can break is not a source of truth. So:
- Every mutation the broker performs is followed by a read-back of the
affected fact (
clients -jfiltered to the session's container). - On socket2 reconnect, a full reconcile runs: for each live session, compare
the record against
clients -jand repair or report. - Reconciliation is the only writer of
window/workspace/outputfields from events; events merely schedule a reconcile of one session.
4.3 Record fields this fills
workspace, window, foreground, plus new container (§7). foreground is
defined as the monitor-active-workspace join, not the client's visible
field, so it means "a human or the frame server is actually looking at this".
4.4 Degraded mode
If no IPC is reachable: sessions still start, stop, reap and are tracked by
process identity — exactly today's behaviour. workspace/window stay null
(never guessed), container: "none", and one line is logged at startup and
reported in status. Lifecycle verbs never depend on IPC.
4.5 Teardown cross-check
Today teardown is process-group only. From here: after killing, verify from the
compositor (no client with this session's app-id remains) and report a
discrepancy as survivors: [...] rather than declaring success. Two independent
sources — pidfd//proc and the compositor — must agree.
5. Stage 2 — one output and one workspace per session
5.1 Container creation (on start)
hyprctl output create headless hh-<session-id>[UNVERIFIED — experiment 3] (strongly implied: Hyprland requests the headless backend asAQ_BACKEND_REQUEST_MANDATORY;dispatchOutputchecksgetImplementations()forAQ_BACKEND_HEADLESS).- Generate a synthetic config for that output via
hyprctl keyword(immediate, instance-scoped, no reload):workspace = <n>, monitor:hh-<id>, default:true, persistent:truewindowrule = match:initial_class ^hh-<id>$, workspace <n>, monitor hh-<id>- the output's mode, taken from the container's size (default 1280×720).
- Launch the app with a matching identity so the rule binds: the app is
started in a
systemd-run --userscope? No — see §5.4 — the app is launched as today (plainPopen), with--class/--app-idset per app in the policy where the app supports it, andXDPP_APP_ID-style environment where it does not. - Read back: the client's
workspace,monitorandstableId; write them to the record.
Workspace numbering: containers get workspaces from a reserved band (1000 + slot) so nothing collides with the operator's own workspaces; the slot is allocated from a free list held in the registry and released on teardown.
5.2 The catch-all window rule
The current config has windowrule = match:class .*, float on, size 1040 560, center on — justified by the belief that IPC could not be queried. With Stage 1
that belief is gone, so it is replaced by:
- per-container rules (
match:initial_class ^hh-<id>$), and - a quarantine backstop:
match:class .*, workspace special:quarantine. A window that matches no container lands in a hidden special workspace and is reported bysession list --unmatched, instead of appearing on whatever output happened to be focused.
5.3 Teardown (on kill, reap, or gc)
- Send the configured signal to the process group; wait
grace; escalate. hyprctl output remove hh-<id>— removes the output, and with it the container. Windows on it are destroyed by the compositor when their surface is destroyed.- Release the workspace number and the pointer bookmark.
- Record a tombstone with
container: "removed"and the reason.
Reversible in one step: output remove is the container's deletion, and it is
also the recovery path — a broker that has lost its registry can enumerate
outputs named hh-* and converge (an orphan hh-* output with no session is
either re-adopted or removed, never left behind).
5.4 Per-session capture
grim -o hh-<id> out.jpgcaptures one container in isolation.- The frame server keeps publishing the main output for backwards
compatibility (
hhstream shot), and gains--output hh-<id>to publish or capture a specific container. grim -T <stableId>(a window on a non-visible workspace) is unverified (experiment 1). The design does not depend on it: containers are outputs, sogrim -ois always available.-Tis a convenience if it works.
5.5 Container sizing and cost
Each output is a real render target. At vfr = false the compositor renders
every output every frame [UNVERIFIED — experiment 2]. Therefore:
max_sessionsgains a container budget (max_containers, default 2 on this machine, to be re-derived from the measurement).- The measurement decides whether
vfr = trueis adopted (screencopy may drive rendering on demand, making it free performance). Ifvfrstays false, the container budget is a hard CPU decision, not a preference.
6. Stage 3 — the pointer lease and driver
6.1 What the compositor provides
zwlr_virtual_pointer_manager_v1version 2 is a live global [RAN].create_virtual_pointer_with_output(seat, output, id)— Hyprland storesm_boundOutputon the device and maps normalised absolute motion into that output's rectangle (CPointerManager::warpAbsolute,PointerManager.cpp:905-920) [SRC].motion_absolute(time, x, y, w, h),button(time, btn, state),frame().- No per-device position exists (
IPointer.hpp: onlym_boundOutput,m_connected, flip flags, scroll factor) and no query for the cursor position. Position is one globalm_pointerPos.
6.2 The lease — state machine
acquire (free) release / ttl / crash
FREE ───────────────▶ HELD(lease) ─────────────────────────▶ FREE
▲ │ ▲
│ force-release │ │ events (move/click) refresh TTL
└───────────────────────┘ │
└── any verb without the lease → BUSY (8)
| Transition | Trigger | Side effects |
|---|---|---|
| acquire | session pointer acquire <id> |
take lock; warp from bookmark (or output centre); start TTL |
| refresh | any gesture verb with a valid lease | extend TTL |
| release | session pointer release <id> |
write bookmark; lift any pressed buttons; free lock; stamp reason |
| timeout | TTL (default 30 s) with no verb, or hard cap (default 300 s) | force-release; lift buttons; event pointer_lease_timeout |
| crash | broker restart | leases are stale by definition → free; bookmarks intact |
Rules:
- One holder. The lock is broker-wide because the cursor is one. A second
acquirereturnsBUSY(8) with the current holder's id. - Gesture atomicity. The lease must span warp → press → move → release. The
broker will not interleave another session's events, and it refuses
pointer movefor a session that does not hold the lease. - Never leave a button down. On release/timeout with any button pressed, the
broker sends the button-up and records
buttons_lifted: [BTN_LEFT]. - Bookmark written on every move and on release, so a crash leaves the last real position.
6.3 Bookmark representation
"bookmark": {"x": 0.42, "y": 0.61, "output": "hh-<id>", "at": "2026-10-01T…Z"}
Output-local normalised coordinates, because that is the frame
motion_absolute already speaks: the value survives output resizes, layout
changes and container renumbering, and needs no conversion on the way in.
6.4 Aiming
Converting a window-local pixel target to motion_absolute inputs:
- Get the client's box from
clients -j(or the container's rect if aiming at the output). - Map box-local
(px, py)→ global → subtract the output's(x, y)frommonitors→ divide by the output's width/height. - Emit
motion_absolute(t, X, Y, X_extent, Y_extent)thenframe(). - Settle:
animations = falseis already set and is now a correctness requirement — a composition animation between warp and click moves the target under the cursor.
6.5 Driver placement
The driver is a separate small process, hhstream-pointer, not part of the
broker's event loop: a Wayland client needs a connection of its own, and a
blocked driver must not stall session lifecycle. The broker owns the lease and
speaks to the driver over a private socket; the driver owns the Wayland
connection and the per-session zwlr_virtual_pointer_v1 objects. If the driver
dies, the broker force-releases the lease.
6.6 What the lease does not protect
Nothing in the compositor stops any client from creating its own virtual pointer and moving the shared cursor — the global is advertised to everyone. The lease disciplines our sessions; it does not enforce against a hostile one. Stage 4 is what makes it enforceable (the compositor's own global filter can deny input injection to a sandboxed session).
6.7 Keyboard (specified, later)
Same seat, same serialisation. zwp_virtual_keyboard_manager_v1 exists [RAN].
The lease gains a keyboard flag so a typing burst is atomic; no new mechanism
is needed. Not in Stages 0–3.
7. Data model — the session record (schema 3)
Today (schema: 2) the record has identity, lifecycle, and reserved-but-empty
spatial fields. Schema 3 adds the container and the pointer, and makes the
existing nulls meaningful:
{
"schema": 3,
"id": "foot-v7r4li",
"app": "foot",
"argv": ["…"],
"pid": 1288, "pgid": 1288, "sid": 1288,
"pid_starttime": 8100, "boot_id": "…",
"exit_detected_by": "pidfd",
"state": "ready", // spawned|ready|exited|killed|reaped|failed
"created_at": "…", "created_boottime": 81.0,
"ready_signal": "spawned",
"idle_timeout_s": 10800.0, "last_activity_at": "…", "last_activity_boottime": 106.5,
"tombstoned_boottime": null,
"home": "/var/lib/hermes", "ephemeral_home": false,
"runtime_dir": "/run/hhstream/sessions/foot-v7r4li",
"log_path": "/var/lib/hermes/hhstream-sessions/logs/foot-v7r4li.log",
"container": { // NEW — null until Stage 2
"output": "hh-foot-v7r4li",
"workspace": 1003,
"mode": {"width": 1280, "height": 720},
"created_by": "broker",
"state": "owned" // owned|degraded|removed|orphan
},
"window": {"stable_id": "…", "class": "foot", "title": "…"}, // Stage 1
"workspace": 1003, // Stage 1
"foreground": false, // Stage 1 (monitor-active join)
"pointer": { // NEW — Stage 3, per-session bookmark
"bookmark": {"x": 0.42, "y": 0.61, "output": "hh-foot-v7r4li", "at": "…"},
"last_released_at": "…", "released_by": "lease|timeout|crash|kill"
},
"command_count": 8, "adopted": false, "last_error": null,
"signature": "efb5…" // NEW — HYPRLAND_INSTANCE_SIGNATURE
}
Invariants:
container: nullmeans "no spatial container" (degraded or pre-Stage-2), never "unknown but probably something".pointeris written on release and on every move; a missingpointeris "never used", not "position unknown".- Every field the broker cannot verify stays
null. No field is ever guessed.
8. Wire protocol (broker control socket)
Newline-delimited JSON request/response over the existing control socket. Every
request gains a request_id (client-supplied) for idempotency; the broker keeps
the last N completed ids per session and returns the recorded answer rather than
repeating a mutation.
8.1 Verbs
| Verb | Request | Response | Stage |
|---|---|---|---|
session.start |
app, argv[], idle_timeout_s?, home?, ephemeral_home?, container? |
session (record) |
existing (+container) |
session.list |
all? |
sessions[] |
existing |
session.status |
id, events? |
session, events[] |
existing |
session.touch |
id |
session |
existing |
session.kill |
id, grace?, signal? |
session, survivors[] |
existing (+cross-check) |
session.gc |
— | removed[], orphans[] |
existing |
session.adopt |
pid, app?, idle_timeout_s? |
session |
existing |
session.logs |
id, lines? |
text |
existing |
container.list |
— | containers[] (incl. orphans) |
2 |
container.reconcile |
id? |
container, diff |
2 |
pointer.acquire |
id, ttl_s?, restore? |
lease_id, bookmark |
3 |
pointer.move |
id, lease_id, x, y | dx, dy |
bookmark |
3 |
pointer.button |
id, lease_id, button, state |
buttons[] |
3 |
pointer.click |
id, lease_id, button?, count? |
bookmark |
3 |
pointer.release |
id, lease_id |
bookmark, released_by |
3 |
pointer.state |
— | held_by, since, bookmark |
3 |
8.2 Error model
Existing exit/status codes are kept and extended:
| Code | Name | Meaning | New? |
|---|---|---|---|
| 0 | OK | ||
| 2 | USAGE | malformed request | |
| 3 | NO_SUCH_SESSION | unknown id | |
| 4 | BAD_STATE | e.g. kill on a reaped session | |
| 5 | DAEMON_UNREACHABLE | socket missing/refused | |
| 6 | POLICY | app or argument not allowlisted; container budget exhausted | |
| 7 | TIMEOUT | wait_ready/grace expired | |
| 8 | BUSY | pointer lease held by another session | |
| 9 | NO_LEASE | verb requires the lease and this session does not hold it | new |
| 10 | COMPOSITOR | IPC or output operation failed; session survives in degraded mode | new |
COMPOSITOR is distinct from a session failure on purpose: losing the
compositor must not look like losing the session.
8.3 Activity accounting (unchanged, restated because it is load-bearing)
touch is the only mark of activity. list, status, logs, gc, and all
pointer.* verbs do not reset the idle clock — a session that is being
clicked in must still be kept alive explicitly, or a driven-but-idle session
would never be reaped.
9. CLI surface
hhstream status
hhstream shot [--out FILE] [--output NAME] # --output NEW
hhstream run [--] CMD… # unmanaged
hhstream record [--seconds N] [--out FILE] [--output NAME]
hhstream session start APP [-- ARGV…] [--json]
[--idle-timeout D] [--wait-ready D] [--home P | --ephemeral-home]
[--no-container] # NEW: skip the container
hhstream session list [--all] [--json]
hhstream session status ID [--events N] [--json]
hhstream session touch ID
hhstream session kill ID [--grace D] [--signal S]
hhstream session logs ID [--lines N] [--follow]
hhstream session gc
hhstream session adopt --pid PID [--app A] [--idle-timeout D]
hhstream session container ID [--json] # NEW
hhstream session reconcile [ID] # NEW
hhstream session pointer acquire ID [--ttl D] [--no-restore] # NEW
hhstream session pointer move ID --to X,Y | --by DX,DY # NEW
hhstream session pointer click ID [--button left|right|middle] # NEW
hhstream session pointer down ID [--button B] # NEW
hhstream session pointer up ID [--button B] # NEW
hhstream session pointer release ID # NEW
hhstream session pointer state [--json] # NEW
Human output keeps the current conventions: the bare identifier on stdout for
start, detail on stderr, --json for the protocol object. Machine-facing
consumers always use --json; human text is never parsed.
list gains two columns and one honest gap marker:
ID APP STATE WS OUTPUT POINTER IDLE EXPIRES
foot-v7r4li foot ready 1003 hh-foot-v7r4li free 0:12 2:59:48
chromium-abc chromium ready 1004 hh-chromium-abc held:foot 0:03 2:59:57
10. Policy (TOML) — new keys
[broker]
max_sessions = 4
max_containers = 2 # NEW — CPU-bounded, from experiment 2
degraded_ok = true # NEW — allow sessions with no container/ IPC
[compositor]
signature = "auto" # NEW — or a pinned HYPRLAND_INSTANCE_SIGNATURE
runtime_dir = "/run/hypr-stream" # NEW — must be ≤25 chars
workspace_base = 1000 # NEW — reserved band for containers
container_mode = "1280x720" # NEW
quarantine_enabled = true # NEW
[pointer]
lease_ttl_s = 30 # NEW — idle TTL before force-release
lease_max_s = 300 # NEW — hard cap for a single lease
settle_ms = 60 # NEW — wait after warp before pressing
button_default = "left"
restore_on_acquire = true # NEW — warp from bookmark
[apps.<name>]
exec = "…"
args_allow = [ … ] # unchanged: per-argument fnmatch, no shell
app_id = "hh-<session>" # NEW — identity the window rule matches
11. NixOS module changes
Options added to services.hyprland-headless-stream:
| Option | Type | Default | Purpose |
|---|---|---|---|
sessions.containers.enable |
bool | true |
per-session output+workspace |
sessions.containers.max |
int | 2 |
CPU budget (measure first) |
sessions.containers.mode |
str | "1280x720" |
container size |
sessions.containers.workspaceBase |
int | 1000 |
reserved band |
sessions.pointer.enable |
bool | false |
start hhstream-pointer |
sessions.pointer.leaseTtl |
int (s) | 30 |
|
sessions.pointer.leaseMax |
int (s) | 300 |
Unit changes:
hyprland-headless.service,hyprland-headless-stream.service,hhstream-sessions.service:RuntimeDirectory→hypr-stream(Stage 0).- New
hhstream-pointer.service: same userhermes, supplementary grouphhstream(it needs the compositor's Wayland socket),After=the compositor,Restart=on-failure,KillMode=process(same reasoning as the broker: it must not take sessions down when it restarts). - tmpfiles: the pointer service's private runtime dir; the state dir already exists.
- Assertion:
runtimeDirectorylength ≤ 25, failing evaluation rather than producing a compositor with a broken event socket.
12. Isolation (Stage 4) and per-tenant compositors (Stage 5)
Stage 4 — sandbox a session's application. Launch it through a
wp_security_context_manager_v1 listener with sandbox_engine and
app_id/instance_id set per session, and hand it the restricted socket instead
of the compositor's. The compositor's global filter then denies it: screen
capture, input injection, enumerating other sessions' windows, layer-shell
overlays, clipboard reads. This is what gives the pointer lease teeth (§6.6).
Still not achievable: protection from a compositor crash, xdg_activation
focus-stealing, and a stray window landing on another container.
Stage 5 — per-tenant compositors. hyprland-session@.service template;
headless backend (never nested, never DRM); per-instance RuntimeDirectory
≤25 chars; ideally a per-tenant user; per-session socket resolution in the broker
instead of one global --compositor-runtime-dir. Gives truly concurrent
pointers, crash isolation, kernel-level separation. Gated on the CPU
measurement — at 96.6% of a core for one compositor on a 2-core box, this is
not affordable today.
13. Failure modes
| Failure | Detection | Behaviour |
|---|---|---|
| Compositor restarts | socket2 EOF; version fails |
sessions are dead (their clients died with it) → mark container: orphan, reaper reports; broker re-attaches, does not pretend |
| Broker restarts | unit restart | sessions live on (KillMode=process, plain Popen); adoption re-reads clients -j and re-binds containers by output name |
| Output creation fails | hyprctl output create error |
session starts without a container, container: "degraded", exit code 10 from container verbs, lifecycle unaffected |
| socket2 path too long | compositor log line | refuse to start in container mode; assert in the module (Stage 0 prevents it) |
| A window matches no container | openwindow + no rule match |
quarantined to a hidden workspace; reported by container.list as orphan |
| Pointer driver dies | socket EOF | force-release the lease with reason driver_gone; sessions unaffected |
| Lease holder goes silent | TTL | force-release after lease_ttl_s; buttons lifted; audit event |
| Stuck button | button state in the lease | lifted on release/timeout; buttons_lifted recorded |
| Registry lost, containers present | start-up scan | enumerate hh-* outputs and adopt or remove; never leave a container unattended |
grim -o fails on a container |
capture error | frame server falls back to the main output and reports degraded, rather than publishing a black frame |
14. Testing and acceptance gates
Same discipline as today: unit tests plus a real NixOS VM check per stage, all green before any switch, and each check must be shown to fail when its mechanism is broken (mutation test), because twice now a check passed for the wrong reason.
| Stage | Unit | VM check | Key assertions |
|---|---|---|---|
| 0 | socket-path length is derived, not hardcoded | extend vm-hyprland |
both sockets exist at real names; a socket2 subscriber receives openwindow for a window the test creates; hyprctl answers |
| 1 | IPC parse/format against recorded fixtures; reconciler diff logic | vm-ipc |
workspace/window/foreground are filled and match clients -j; teardown cross-check reports a deliberately-orphaned window as a survivor |
| 2 | workspace-slot allocator; rule generation | vm-containers |
one output per session, named hh-*; a second window of the same app lands in the same container; an unmatched window is quarantined; grim -o captures only that container; teardown removes the output |
| 3 | lease state machine (TTL, hard cap, force-release, button lift); coordinate conversion | vm-pointer |
acquire warps from the bookmark; a click lands where aimed (verified by reading back the app's state, not pixels); a second acquire returns BUSY; timeout releases and lifts buttons; a broker restart leaves the lock free and the bookmark intact |
| 4 | policy filter expectations | vm-sandbox |
a sandboxed app cannot bind a virtual pointer or capture the screen (both fail with a protocol error) |
Every check runs with an injected clock for the TTL logic, and with real time
for at least one reap/expiry assertion — the existing vm-sessions does exactly
this and it is why the race in the negative control was found.
15. Open questions and experiments
- Window capture off-screen (
grim -T <stableId>) — unverified; the design does not depend on it (containers are outputs). - Container cost at
vfr = false— gatesmax_containersand Stage 5. Procedure: create one headless output, measure the compositor's CPU for a minute, remove it; repeat withvfr = trueand check the frame server still receives frames. Both mutate a live desktop, which is why they were not run. - Does
hyprctl output create headlesssucceed on this instance? Implied by source, unverified. - Decision, operator: is serialised pointer input acceptable, or is concurrent input a hard requirement? Only the latter forces Stage 5.
- Decision, operator: the container budget (
max_containers) if experiment 2 shows a per-output cost that matters. - Decision, operator: whether
hhstream pointerverbs are part of the session-lease API now, or the lease is internal until input injection is proven useful end-to-end.
16. Recommended sequencing
- Stage 0 — rename, measured reason in the comment. Hours, unblocks everything, worth doing alone.
- Stage 1 — IPC client + reconciler + record fields. Small.
- Experiment 2 (cost) — because it sets
max_containersand whether Stage 5 is ever reachable. - Stage 2 — containers. Small-to-medium.
- Stage 3 — pointer lease + driver. Small, given the lease is specified here.
- Stage 4 — sandboxing, when adversarial isolation is wanted.
- Stage 5 — only on evidence.
Each stage ships with its check, its rollback (revert the commit; containers and
outputs are removed by gc), and an entry in the audit trail.