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.
663 lines
33 KiB
Markdown
663 lines
33 KiB
Markdown
# 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.
|