diff --git a/docs/CONTRACT-sessions.md b/docs/CONTRACT-sessions.md new file mode 100644 index 0000000..336f591 --- /dev/null +++ b/docs/CONTRACT-sessions.md @@ -0,0 +1,300 @@ +# CONTRACT — sessions build (sessions-v1) + +This file is the interface for the **session** work: the broker, containers, +compositor IPC and pointer input. It is the sibling of `docs/CONTRACT.md`, which +freezes the *frame-socket* wire format; that one is untouched by this build. + +**Immutable without a version bump.** Every slice codes against this and nothing +else. If something here is wrong or missing, **stop and report it in your final +message** — the parent edits this file, not you. Do not widen your slice to work +around a gap. + +Version: sessions-v1 (2026-10-01). + +--- + +## 1. What is being built, in one paragraph + +A headless Hyprland desktop is driven by an agent. A broker (`hhstreamd`) starts +allowlisted applications as **sessions** and tracks them. This build gives each +session its **own output and workspace** (a spatial container), teaches the +broker to **talk to the compositor** (IPC), and adds **serialised pointer input** +aimed at one session, under a **lease** whose bookmark is stored with the +session. + +Read `docs/PLAN-workspaces-and-pointer.md` only if your brief tells you to. It +describes the whole system; you are building one part. + +--- + +## 2. File ownership — the rule that makes four sessions possible + +| Slice | Owns (only these) | +| --- | --- | +| **A — stage0-rename** | `nix/module.nix`, `src/hhstream/cli.py` (the two socket-path defaults only), `examples/agent-eyes` | +| **B — ipc-client** | `src/hhstreamd/ipc.py`, `tests/ipc/**` | +| **C — containers** | `src/hhstreamd/containers.py`, `tests/containers/**` | +| **D — pointer** | `src/hhstreamd/pointer.py`, `src/hhstream_pointer/**`, `tests/pointer/**`, `pyproject.toml`, `nix/package.nix` | +| **parent (integration)** | `src/hhstreamd/{protocol,registry,manager,launcher,compositor,procmon}.py`, `checks/**`, `docs/**`, `src/hhstream/cli.py` (everything but the path defaults), `nix/module.nix` (after A merges) | + +Two slices never edit the same file. A shared-file change you believe you need is +a **report**, not an edit. + +**Never touch:** `/etc/nixos` (outside this repo), anything under +`/var/lib/hermes/nixos`, any systemd unit, any running service. Never run +`nixos-rebuild`, `nixosTest`, `nix build .#checks.*`, or launch a GUI +application. The parent serialises all of that on a 2-core machine. + +--- + +## 3. Python seams (exact signatures — code to these) + +### 3.1 `hhstreamd/ipc.py` (B) + +```python +class CompositorUnavailable(Exception): + """No request socket, or the compositor refused. Callers degrade, never guess.""" + +@dataclass(frozen=True) +class Monitor: + name: str; x: int; y: int; width: int; height: int; scale: float + active_workspace_id: int | None + +@dataclass(frozen=True) +class Workspace: + id: int; name: str; monitor: str | None; windows: int; is_special: bool + +@dataclass(frozen=True) +class Client: + address: str; pid: int; workspace_id: int | None; monitor: str | None + class_: str; initial_class: str; title: str; stable_id: str; visible: bool + +@dataclass(frozen=True) +class CursorPos: + x: int; y: int + +@dataclass(frozen=True) +class Event: + name: str # "openwindow", "workspace", "monitorremoved", ... + data: dict # parsed payload; keys are whatever the event carried + +class HyprlandIPC: + @classmethod + def discover(cls, runtime_dir: Path, signature: str | None = None) -> "HyprlandIPC": ... + # raises CompositorUnavailable. Signature from the argument, else + # $HYPRLAND_INSTANCE_SIGNATURE, else the single directory under + # /hypr/. More than one and no signature = CompositorUnavailable. + + def __init__(self, request_socket: Path, event_socket: Path | None = None) -> None: ... + + def version(self) -> str: ... + def monitors(self) -> list[Monitor]: ... + def workspaces(self) -> list[Workspace]: ... + def clients(self) -> list[Client]: ... + def cursorpos(self) -> CursorPos: ... + def query(self, command: str) -> str: ... # raw request socket, for anything not wrapped + def events(self) -> Iterator[Event]: ... # blocking; raises CompositorUnavailable on EOF + def close(self) -> None: ... + +def parse_event(line: str) -> Event: ... # "name>>a,b,c" -> Event +``` + +Rules: every method raises `CompositorUnavailable` rather than returning a +guess. `clients()` parses `clients -j`; `monitors()` parses `monitors -j`; +`workspaces()` parses `workspaces -j`. Stdlib only. + +### 3.2 `hhstreamd/containers.py` (C) + +**Pure logic. No I/O, no subprocess, no socket, no import of `ipc.py`.** It +computes command lines and parses nothing. Seams are primitives so this module +stands alone. + +```python +@dataclass(frozen=True) +class ContainerPlan: + output: str # hh- + workspace: int + mode: tuple[int, int] # width, height + create: list[list[str]] # full argv lists, in order, each ["hyprctl", ...] + teardown: list[list[str]] + +def output_name(session_id: str) -> str: ... + # "hh-" + session_id. Ids are already [a-z0-9-]; assert and raise ValueError otherwise. + +def contains_output(name: str) -> bool: ... + # True for names this broker creates (prefix "hh-"), so a start-up scan can + # find orphans. + +def container_plan(session_id: str, workspace: int, width: int, height: int, + app_id: str) -> ContainerPlan: ... + # create: output create headless ["hyprctl","output","create","headless",name] + # workspace rule ["hyprctl","keyword","workspace", + # f"{workspace}, monitor:{name}, default:true, persistent:true"] + # window rule ["hyprctl","keyword","windowrule", + # f"match:initial_class ^{app_id}$, workspace {workspace}, monitor {name}"] + # output mode ["hyprctl","keyword","monitor", f"{name},{width}x{height},auto,1"] + # teardown: output remove ["hyprctl","output","remove",name] + +def app_id_for(session_id: str) -> str: ... + # the bare "hh-" the launcher sets on the app; "^hh-$" + # is built in container_plan. + +def quarantine_plan(quarantine_workspace: str) -> ContainerPlan | None: ... + # the backstop: every window matching no container goes to + # special:quarantine. Returns the keyword argv, or None if disabled. + +class WorkspaceAllocator: + def __init__(self, base: int, count: int) -> None: ... + def allocate(self) -> int: ... # lowest free slot in [base, base+count); raises NoSlots + def release(self, workspace: int) -> None: ... # unknown id -> KeyError (a bug, not a no-op) + def in_use(self) -> list[int]: ... + +class NoSlots(Exception): ... +``` + +### 3.3 `hhstreamd/pointer.py` (D) + +Lease state machine + coordinate maths. **No Wayland, no socket, no I/O.** The +clock is injected so expiry is testable without sleeping. + +```python +class LeaseBusy(Exception): # another session holds it + def __init__(self, holder: str) -> None: ... +class LeaseInvalid(Exception): # not held, or held by someone else / stale lease_id + +@dataclass(frozen=True) +class Bookmark: + x: float; y: float # 0..1, output-local, normalised + output: str + at: str # ISO-8601 UTC + +@dataclass(frozen=True) +class LeaseInfo: + session_id: str; lease_id: str; acquired_at: float; expires_at: float + hard_deadline: float + +@dataclass(frozen=True) +class LeaseOutcome: + bookmark: Bookmark | None; reason: str; buttons_lifted: list[str] + +class PointerLease: + def __init__(self, ttl_s: float = 30.0, max_s: float = 300.0, + clock: Callable[[], float] = time.monotonic) -> None: ... + def acquire(self, session_id: str) -> str: ... # -> lease_id; raises LeaseBusy + def refresh(self, session_id: str, lease_id: str) -> None: ... # raises LeaseInvalid + def release(self, session_id: str, lease_id: str, reason: str) -> LeaseOutcome: ... + def state(self) -> dict: ... # {"holder": str|None, "since": float|None, + # "lease_id": str|None, "expires_at": float|None} + def expire(self) -> LeaseInfo | None: ... + # force-release if past ttl or hard cap; returns what was released. + # The caller (broker) lifts buttons on the driver side. + def press(self, session_id: str, button: str) -> None: ... + def unpress(self, session_id: str, button: str) -> list[str]: ... + def pressed(self) -> list[str]: ... + +def window_to_absolute(point: tuple[int, int], window: tuple[int, int, int, int], + monitor: tuple[int, int, int, int]) -> tuple[float, float]: + # point is window-local pixels; window is (x, y, w, h) global; monitor is + # (x, y, w, h) global. Returns normalised 0..1 in the MONITOR's frame, + # clamped to [0, 1]. Raises ValueError if the point is outside the window. +``` + +### 3.4 `src/hhstream_pointer/**` (D) — the driver process + +A separate process, because a Wayland client needs its own connection and a +blocked driver must not stall the broker. + +- Entry point `hhstream-pointer` (add to `pyproject.toml`: + `hhstream-pointer = "hhstream_pointer.__main__:main"`). +- Command line the module will pass, exactly: + `hhstream-pointer --socket /run/hhstream/pointer.sock --compositor-runtime-dir /run/hypr-stream` +- Uses **pywayland** (packaged as `python3Packages.pywayland`) and the **wlr + virtual pointer XML** from `pkgs.wlr-protocols` + (`share/wayland-protocols/wlr-unstable/zwlr-virtual-pointer-unstable-v1.xml`). + Compile the protocol at build time or vendor the generated module under your + directory — your choice, stated in your report. `pyproject.toml` and + `nix/package.nix` are yours precisely so this is possible. +- Binds `zwlr_virtual_pointer_manager_v1` **version 2** and uses + `create_virtual_pointer_with_output(seat, output, id)` so coordinates are + output-local. If only version 1 is offered, **report it — never silently fall + back** to a global pointer, which would break aiming. +- Private socket protocol with the broker, newline-delimited JSON: + +```json +{"op": "warp", "output": "hh-x", "x": 0.42, "y": 0.61} -> {"ok": true} +{"op": "button", "button": "left", "state": "down"} -> {"ok": true} +{"op": "frame"} -> {"ok": true} +{"op": "pressed"} -> {"ok": true, "buttons": ["left"]} +{"op": "release_all"} -> {"ok": true, "lifted": ["left"]} +``` + +`{"ok": false, "error": ""}` for anything rejected. The driver holds **no +lease state** — the broker owns the lease; the driver is an executor that must +never be trusted to serialise anything. + +--- + +## 4. Wire format (broker control socket) — B, C and D do not implement this + +Newline-delimited JSON over `/run/hhstream/control.sock`. Existing verbs are +unchanged. New verbs (integration implements; listed so slices know what their +code will be called with): + +| Verb | Request (beyond `verb`, `request_id`) | Response | +| --- | --- | --- | +| `container.list` | — | `containers[]`, `orphans[]` | +| `container.reconcile` | `id?` | `container`, `diff` | +| `pointer.acquire` | `id`, `ttl_s?`, `restore?` | `lease_id`, `bookmark` | +| `pointer.move` | `id`, `lease_id`, `x`, `y` \| `dx`, `dy` | `bookmark` | +| `pointer.button` | `id`, `lease_id`, `button`, `state` | `buttons[]` | +| `pointer.click` | `id`, `lease_id`, `button?`, `count?` | `bookmark` | +| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by` | +| `pointer.state` | — | `holder`, `since`, `lease_id` | + +### Error codes (extend `ExitCode`, do not renumber) + +| 0 OK | 2 USAGE | 3 NO_SUCH_SESSION | 4 BAD_STATE | 5 DAEMON_UNREACHABLE | +| 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** | + +Activity accounting is unchanged and load-bearing: **`touch` is the only mark of +activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` verb do **not** +reset the idle clock. + +--- + +## 5. Names and paths (frozen) + +| Thing | Value | +| --- | --- | +| Compositor runtime dir | `/run/hypr-stream` — **must be ≤ 25 chars** (socket paths must stay under `sun_path`'s 108-byte limit) | +| Compositor request socket | `/hypr//.socket.sock` | +| Compositor event socket | `/hypr//.socket2.sock` | +| Broker control socket | `/run/hhstream/control.sock` | +| Broker↔driver socket | `/run/hhstream/pointer.sock` | +| Broker state dir | `/var/lib/hermes/hhstream-sessions` | +| Session runtime dir | `/run/hhstream/sessions/` | +| Container output name | `hh-` | +| Container workspace band | `1000 + slot`, allocated from the registry's free list | +| Container mode | `1280x720` | +| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` | +| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` | +| Service account | `hermes`, supplementary group `hhstream` | + +--- + +## 6. Rules of engagement + +1. **Only your files** (§2). A shared-file change you need is a report. +2. **Unit tests only.** `nix develop -c python -m pytest tests/ -q`. + Nothing that builds a VM, rebuilds the system, or touches a live service. +3. **Stdlib only**, except slice D which may add `pywayland`. +4. **Machine style:** module docstrings that say *why*, not what; comments carry + reasoning; no TODO placeholders; no speculative generality. +5. **Definition of done:** a commit on your branch; your tests pass; your final + message states (a) what you built, (b) the exact test command and its result, + (c) what you could **not** verify, (d) any contract gap you hit. A slice that + "finishes" without (b) is not done. +6. **Do not open by reading the whole repo.** Your brief plus this contract is + your context. Read the two or three files you actually touch. +7. If the contract is wrong, say so and stop. If your slice turns out to need + another slice's file, say so and stop. Both are successful outcomes. diff --git a/docs/PLAN-workspaces-and-pointer.md b/docs/PLAN-workspaces-and-pointer.md new file mode 100644 index 0000000..b4b166e --- /dev/null +++ b/docs/PLAN-workspaces-and-pointer.md @@ -0,0 +1,662 @@ +# 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.