Files
hyprland-headless-stream-pl…/docs/PLAN-workspaces-and-pointer.md
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

33 KiB
Raw Permalink Blame History

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

"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 nulls meaningful:

{
  "schema": 3,
  "id": "foot-v7r4li",
  "app": "foot",
  "argv": ["…"],

  "pid": 1288, "pgid": 1288, "sid": 1288,
  "pid_starttime": 8100, "boot_id": "…",
  "exit_detected_by": "pidfd",

  "state": "ready",            // spawned|ready|exited|killed|reaped|failed
  "created_at": "…", "created_boottime": 81.0,
  "ready_signal": "spawned",
  "idle_timeout_s": 10800.0, "last_activity_at": "…", "last_activity_boottime": 106.5,
  "tombstoned_boottime": null,

  "home": "/var/lib/hermes", "ephemeral_home": false,
  "runtime_dir": "/run/hhstream/sessions/foot-v7r4li",
  "log_path": "/var/lib/hermes/hhstream-sessions/logs/foot-v7r4li.log",

  "container": {                          // NEW — null until Stage 2
    "output": "hh-foot-v7r4li",
    "workspace": 1003,
    "mode": {"width": 1280, "height": 720},
    "created_by": "broker",
    "state": "owned"                      // owned|degraded|removed|orphan
  },

  "window": {"stable_id": "…", "class": "foot", "title": "…"},   // Stage 1
  "workspace": 1003,                                              // Stage 1
  "foreground": false,                                            // Stage 1 (monitor-active join)

  "pointer": {                            // NEW — Stage 3, per-session bookmark
    "bookmark": {"x": 0.42, "y": 0.61, "output": "hh-foot-v7r4li", "at": "…"},
    "last_released_at": "…", "released_by": "lease|timeout|crash|kill"
  },

  "command_count": 8, "adopted": false, "last_error": null,
  "signature": "efb5…"                    // NEW — HYPRLAND_INSTANCE_SIGNATURE
}

Invariants:

  • container: 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

[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.

  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.