Files
hyprland-headless-stream-pl…/docs/PLAN-workspaces-and-pointer.md
T
Hermenix 98374b8457 docs: the plan for workspaces and pointer input, and the frozen sessions contract
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.
2026-10-01 23:58:09 +00:00

663 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <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`: `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/<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:
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-<session-id>` **[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 = <n>, monitor:hh-<id>, default:true, persistent:true`
- `windowrule = match:initial_class ^hh-<id>$, workspace <n>, monitor hh-<id>`
- 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-<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 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-<id>` — 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-<id> out.jpg` captures 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, 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 <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
`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-<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:
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.<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 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 <stableId>`) — 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.