# 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`, one `m_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 = false` with 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 ┌──────────────────────────────┴──────────────────────────────┐ │ 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`: `RuntimeDirectory` for both units, the published socket `default`, and the broker's `--compositor-runtime-dir`. - `/etc/nixos/hyprland-stream.nix`: `socketPath`, `sessions.stateDir` is unaffected. - The frame server's `HOME`/`WorkingDirectory`. - The `hhstream` CLI'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/` 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: 1. Every mutation the broker performs is followed by a **read-back** of the affected fact (`clients -j` filtered to the session's container). 2. On socket2 reconnect, a full reconcile runs: for each live session, compare the record against `clients -j` and repair or report. 3. Reconciliation is the *only* writer of `window`/`workspace`/`output` fields 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`) 1. `hyprctl output create headless hh-` **[UNVERIFIED — experiment 3]** (strongly implied: Hyprland requests the headless backend as `AQ_BACKEND_REQUEST_MANDATORY`; `dispatchOutput` checks `getImplementations()` for `AQ_BACKEND_HEADLESS`). 2. Generate a synthetic config for that output via `hyprctl keyword` (immediate, instance-scoped, no reload): - `workspace = , monitor:hh-, default:true, persistent:true` - `windowrule = match:initial_class ^hh-$, workspace , monitor hh-` - the output's mode, taken from the container's size (default 1280×720). 3. Launch the app with a matching identity so the rule binds: the app is started in a **`systemd-run --user` scope? No** — see §5.4 — the app is launched as today (plain `Popen`), with `--class`/`--app-id` set per app in the policy where the app supports it, and `XDPP_APP_ID`-style environment where it does not. 4. Read back: the client's `workspace`, `monitor` and `stableId`; 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-$`), and - a **quarantine backstop**: `match:class .*, workspace special:quarantine`. A window that matches no container lands in a hidden special workspace and is reported by `session list --unmatched`, instead of appearing on whatever output happened to be focused. ### 5.3 Teardown (on `kill`, reap, or gc) 1. Send the configured signal to the process group; wait `grace`; escalate. 2. `hyprctl output remove hh-` — removes the output, and with it the container. Windows on it are destroyed by the compositor when their surface is destroyed. 3. Release the workspace number and the pointer bookmark. 4. 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- out.jpg` captures one container in isolation. - The frame server keeps publishing the **main** output for backwards compatibility (`hhstream shot`), and gains `--output hh-` to publish or capture a specific container. - `grim -T ` (a window on a non-visible workspace) is **unverified** (experiment 1). The design does not depend on it: containers are outputs, so `grim -o` is always available. `-T` is 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_sessions` gains a **container budget** (`max_containers`, default 2 on this machine, to be re-derived from the measurement). - The measurement decides whether `vfr = true` is adopted (screencopy may drive rendering on demand, making it free performance). If `vfr` stays 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_v1` **version 2** is a live global **[RAN]**. - `create_virtual_pointer_with_output(seat, output, id)` — Hyprland stores `m_boundOutput` on 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`: only `m_boundOutput`, `m_connected`, flip flags, scroll factor) and **no query** for the cursor position. Position is one global `m_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 ` | take lock; warp from bookmark (or output centre); start TTL | | refresh | any gesture verb with a valid lease | extend TTL | | release | `session pointer release ` | 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 `acquire` returns `BUSY` (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 move` for 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 ```json "bookmark": {"x": 0.42, "y": 0.61, "output": "hh-", "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: 1. Get the client's box from `clients -j` (or the container's rect if aiming at the output). 2. Map box-local `(px, py)` → global → subtract the output's `(x, y)` from `monitors` → divide by the output's width/height. 3. Emit `motion_absolute(t, X, Y, X_extent, Y_extent)` then `frame()`. 4. Settle: `animations = false` is 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 `null`s meaningful: ```json { "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: null` means "no spatial container" (degraded or pre-Stage-2), never "unknown but probably something". - `pointer` is written on release and on every move; a missing `pointer` is "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 ```toml [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.] exec = "…" args_allow = [ … ] # unchanged: per-argument fnmatch, no shell app_id = "hh-" # 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 user `hermes`, supplementary group `hhstream` (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: `runtimeDirectory` length ≤ 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 1. **Window capture off-screen** (`grim -T `) — unverified; the design does not depend on it (containers are outputs). 2. **Container cost at `vfr = false`** — gates `max_containers` and Stage 5. Procedure: create one headless output, measure the compositor's CPU for a minute, remove it; repeat with `vfr = true` and check the frame server still receives frames. Both mutate a live desktop, which is why they were not run. 3. **Does `hyprctl output create headless` succeed on this instance?** Implied by source, unverified. 4. **Decision, operator:** is serialised pointer input acceptable, or is concurrent input a hard requirement? Only the latter forces Stage 5. 5. **Decision, operator:** the container budget (`max_containers`) if experiment 2 shows a per-output cost that matters. 6. **Decision, operator:** whether `hhstream pointer` verbs 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 1. **Stage 0** — rename, measured reason in the comment. Hours, unblocks everything, worth doing alone. 2. **Stage 1** — IPC client + reconciler + record fields. Small. 3. **Experiment 2** (cost) — because it sets `max_containers` and whether Stage 5 is ever reachable. 4. **Stage 2** — containers. Small-to-medium. 5. **Stage 3** — pointer lease + driver. Small, given the lease is specified here. 6. **Stage 4** — sandboxing, when adversarial isolation is wanted. 7. **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.