Files
hyprland-headless-stream-pl…/README.dev.md
T
HermenixandClaude Opus 5 10176356b6 docs(mcp)!: mcp-v4, a second transport, and what its token is not
The contract said "stdio, and only stdio" and now describes two
transports, so it gets a version -- **v4**, because v3 (the live stream)
was published to main while this branch was in review.  Nothing here
breaks: no tool renamed, no argument reshaped, no resource moved, so a
client written against v2 over stdio still works unchanged.  v2 is the
only bump that took something away, and it took away five tools; v3 and
v4 are additive.

§1 is rewritten around the asymmetry rather than around the feature,
because the asymmetry is the part that is easy to get wrong later: stdio
is unauthenticated **on purpose** and that is now written down with its
argument, so the next reader does not "fix" it.  A stdio client spawns
the server, so it has already passed a filesystem permission check and
holds the broker's 0660 control socket either way -- unix permissions are
the gate, exactly as `mcp.enable`'s own option text has always said.  A
port is the first time the caller passed neither, which is the entire
reason the token exists.

§2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`:
that directory is 0700 owned by the broker's user and holds the audit
trail), the `serve --http` flags, and the `token` verbs with the three
decisions behind them -- digests not tokens, wall-clock expiry where
every broker deadline is BOOTTIME, and a flock because two processes
write the table.  §3 records that a token's toolsets intersect the
server's and cannot widen them.

§10 is new and is the part worth having: **what this is not.**  Not OAuth
2.1, not RFC 9728, no metadata discovery -- so a client that can only
*discover* an authorization server will not connect, and one that lets
you set a header will.  And a token narrows tools but not resources, so a
`frames` token can still read `hhstream://sessions`.  Both are now TODO
files with their own evidence and recommended routes, beside the two
limits the SDK imposes:

* `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about
  interoperability rather than exposure.  Nothing is weaker than it
  claims; what is missing is the part that lets a client somebody else
  configured connect without a human pasting a header.  It records that
  `ssh host hhstream-mcp` is genuinely the better answer for one operator
  with one machine, because that is what this competes with.
* `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all
  until a second token is minted for someone else, at which point the
  restriction is narrower than it reads.

README gains the HTTP section with the three things to know before
enabling it (the unit's refusal and self-heal, no TLS, not OAuth);
README.dev gains the token commands in the dev-shell walkthrough and the
new check's row; ARCHITECTURE gains the two transports in its diagram and
the reason the shim has a state directory while owning no state about the
desktop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 18:00:05 +00:00

29 KiB

Developing and testing hyprland-headless-stream-plugin

The interface everything here asserts is docs/CONTRACT.md. That document is authoritative: if a test and the code disagree, the document decides, and if the document is wrong it gets a version bump, not an edit.

Prerequisites

  • Nix with flakes enabled.
  • /dev/kvm readable, for the VM checks. They are nixosTests; without KVM they still run, just slowly enough that the timeouts below get tight.
  • No GPU. Nothing in the test suite needs one — the compositor runs on Hyprland's headless backend over software rendering.

Nothing in the checks touches the host: no /etc/nixos, no network, and no socket outside the build sandbox or the test VM.

The dev shell

nix develop

Puts python3, pytest, hyprland, grim, ffmpeg, jq and tmux on PATH, plus both packages (hhstream and hhstream-mcp) and the mcp SDK, and sets PYTHONPATH=$PWD/src, so import hhstream and import hhstream_mcp both pick up the working tree rather than an installed copy.

Build

nix build .#hhstream          # the package
ls result/bin                 # hhstream-server, hhstream-client, hhstream,
                              # hhstreamd, hhstream-pointer, hhstream-live

nix build .#hhstream-mcp      # the MCP server, a SEPARATE derivation
ls result/bin                 # hhstream-mcp

The first package's entry points: the frame server and a reference reader for it, the hhstream front-door CLI (frames, run, and the session namespace), the session broker, the pointer driver and the session-stream web app.

hhstream-mcp is its own derivation on purpose. It is the CLI as Model Context Protocol tools (docs/CONTRACT-mcp.md), it depends on the third-party mcp SDK, and packages.hhstream is stdlib-only by policy — see the header of nix/mcp.nix. It depends on the hhstream package as a library: the tools call hhstream.cli's handlers in process rather than spawning the CLI. The dev shell has both, plus python3.pkgs.mcp so tests/unit/test_mcp_server.py can import the SDK:

nix develop
hhstream-mcp --list-tools      # the 23 acting verbs
hhstream-mcp --list-resources  # the 10 read-only URIs

# the HTTP transport, which is the only part that needs a credential
export HHSTREAM_MCP_STATE_DIR=$PWD/.mcp-state
hhstream-mcp token mint --label dev   # the token, once, on stdout
hhstream-mcp serve --http             # 127.0.0.1:9989/mcp

stdio is unauthenticated on purpose and the HTTP transport is not: a stdio client spawns the server and so already holds the broker's socket, while a port is reachable by someone who passed no permission check. docs/CONTRACT-mcp.md §1 has the argument; token mint prints the secret once and the table on disk keeps only its digest.

The checks

Check What it proves Needs a VM
unit the framing, the capture backend, the server's client handling, the broker, the CLI, the containers, the lease and the pointer driver — in-process, against the nix/package.nix build no
vm-basic the NixOS module brings up both units and publishes a contract-conformant socket, with a fake capture backend yes
vm-hyprland the same, capturing the real headless compositor through grim yes
vm-sessions the session broker: a real GUI application launched into the compositor as a tracked session, seen by the compositor's own IPC, killed as a tree, reaped on its idle deadline (and not reaped when touched), and adopted back after the broker restarts yes
vm-ipc the compositor's IPC: both sockets exist at the names docs/CONTRACT-sessions.md §5 freezes and fit inside sun_path, hyprctl answers, the broker's own HyprlandIPC reaches it, and a subscriber on the event socket receives an openwindow for a window the test creates yes
vm-containers one hh-* output per session at the container mode, the application's window on it, a second window of the same application beside it, an unmatched window quarantined, grim -o capturing that container alone, and teardown removing the output and freeing its workspace slot yes
vm-pointer the lease and the driver: a version-2 virtual pointer, a warp that lands where it was aimed as the application reports it, a click delivered as one press and one release, a contended acquire refused with BUSY, an expired lease swept with its held button lifted, and a broker restart that leaves the lock free, the bookmark intact and the driver reachable yes
vm-keyboard the keymap, the focus and a decoded symbol: the keymap the driver uploads reaching a real compositor, pointer acquire leaving the aimed window holding the keyboard and not merely the cursor, and hhs-keyboard-target decoding hello from the keymap it was forwarded — so a driver that stopped uploading one arrives as sym=? and goes red yes
vm-keyboard-de the same file with sessions.keyboard.layout = "de", because that option reaches the uploaded keymap through exactly one path — --xkb-layout on the driver unit — and a single-layout check cannot tell that path from a hardcoded us: keysym y's evdev code swaps (21 against 44), the forwarded symbols= name with it, and ü goes from exit 2 to udiaeresis yes
vm-stream the live stream end to end: stream enable on a live session mints a phrase the daemon accepts, a real HTTP viewer reads JPEGs off /<phrase>/stream.mjpg from inside the guest, stream list reports that viewer, the broker's idle-clock sweep stamps touch for it (and does not when nobody is watching), a wrong phrase 404s, and kill detaches the stream before the output is removed yes
vm-stream-firewall the stream's port: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened yes
vm-mcp the MCP server over stdio: mcp.enable puts the binary on PATH and starts no unit, the initialize handshake completes over a real pipe, all 23 tools and 10 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do not move its idle deadline while session_touch does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, --toolsets narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code yes

| vm-mcp-http | the HTTP transport, its token and its unit: the unit refusing to start while the authorization table is empty and saying so in the journal, then coming up by itself within one retry interval of the first token mint with no systemctl start — the half that nothing in Python can test; the state directory 0700 and owned by the account that mints tokens, the table 0600 and holding no token; the port on loopback only and not in the firewall; an unauthenticated and a wrong-token request both 401 with an empty body and no echo; a good token completing the handshake, reading a resource and calling a tool against the live broker; two tokens served by one process with different tool budgets; and a revocation taking effect on the next request with no restart | yes |

All of them at once:

nix flake check -L

nix flake check stops at the first failing check, which makes it a poor way to see the whole picture while the tree is still red. Run the VM checks one at a time anyway — each boots a guest with a software-rendered compositor, and two at once on a two-core machine make the timing-sensitive assertions flake. A flaky green is worth less than a slow one.

nix build -L .#checks.x86_64-linux.unit
nix build -L .#checks.x86_64-linux.vm-basic
nix build -L .#checks.x86_64-linux.vm-hyprland
nix build -L .#checks.x86_64-linux.vm-sessions
nix build -L .#checks.x86_64-linux.vm-ipc
nix build -L .#checks.x86_64-linux.vm-containers
nix build -L .#checks.x86_64-linux.vm-pointer
nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
nix build -L .#checks.x86_64-linux.vm-mcp
nix build -L .#checks.x86_64-linux.vm-mcp-http
nix build -L .#checks.x86_64-linux.vm-stream

-L is not optional in practice: without it, Nix hides the build log, and the build log is the test report. Do not pipe a check into tail or grep: the pipeline's exit status is the last command's, so a build that cannot fail is not a test. Redirect to a file instead.

Each VM check's test script is type-checked before the guest boots, which is much cheaper than finding a typo after a five-minute boot:

nix build -L .#checks.x86_64-linux.vm-pointer.driver --no-link

Watch for names the driver already defines — log is an AbstractLogger in that namespace, and assigning a string to it is a type error, not a shadowing warning.

unit

pytest over tests/unit/, run in the build sandbox with PYTHONPATH pointing at what nix/package.nix installed (nix/package.nix sets doCheck = false on purpose, so this is the only place the suite runs in a build). nix/mcp.nix's output is on that path beside it, and mcp is in the test environment, because tests/unit/test_mcp_*.py import hhstream_mcp and one of them imports the SDK — not optionally: a file that skipped when the SDK was absent would be green in exactly the build where a malformed tool schema mattered.

The MCP suite is six files, split along what each can be tested without: test_mcp_invoke.py (the in-process CLI call and the exit-code mapping), test_mcp_tools.py (the argv each tool builds, and the toolsets), test_mcp_resources.py (URI routing, query parameters, and that a read never writes), test_mcp_authorizations.py (the token store and the token verbs -- standard library, no SDK), test_mcp_server.py (the SDK wiring, over its memory transport, plus the command line now that it has subcommands) and test_mcp_http.py (the bearer check and the per-token toolsets, over a real ASGI stack).

The check fails if the suite is empty, not just if it is red. pytest exits 5 on "collected nothing", but it exits 0 when every test was skipped or deselected, so checks/lib/check_report.py parses the JUnit report and refuses a run with zero collected or zero executed tests. A green check that tested nothing is worse than no check. On success the report is copied to result/junit.xml.

To run the same tests directly, without Nix:

nix develop
pytest tests/unit -v                      # PYTHONPATH=$PWD/src comes from the shell
pytest tests/unit/test_protocol.py -v     # one file
pytest tests/unit -k "hello or frame" -v  # one theme
pytest tests/unit -x --ff                 # stop at the first failure, failures first

Note that the unit suite's negative tests use the rejects fixture from tests/unit/conftest.py rather than pytest.raises(Exception). rejects treats NotImplementedError as a failure, because a plain raises(Exception) is satisfied by an unimplemented stub — the test would then be green precisely because nothing had been written.

vm-basic

Boots one machine with services.hyprland-headless-stream.enable = true and captureCommand pointed at tests/fake_capture.py, which writes one fixed, deterministic PNG of the configured size to stdout. Because the image never changes, "two frames arrived and they are the same bytes" is a real assertion about the framing rather than a coincidence.

It checks, in order: both units start; the socket exists and is hhstream:hhstream mode 0660; the Hello parses with magic = "HHS1" and non-zero width/height matching the configured output; two frames arrive with length > 0, identical bytes, and an IHDR matching the Hello; two clients are served concurrently; and a client that dies mid-frame leaves the server serving.

The reader is tests/assert_stream.py, a second, independent implementation of the contract that shares no code with hhstream.client — so a framing bug present in both the server's writer and the shipped client's reader still fails the test. It validates the length prefix strictly (0|[1-9][0-9]*: no leading zeros, no sign, no spaces), never reads past a newline, and prints the Hello, every frame's size and SHA-256, and the parsed IHDR before it decides anything.

vm-hyprland

The same machine with no captureCommand override, so the module's default (grim) captures the real compositor.

This is the check expected to be flaky, so it is deliberately impatient: every wait has a bounded timeout, nothing is retried in a loop, and any failure dumps diagnostics before it propagates. It asserts a frame is a valid PNG whose IHDR dimensions match the configured output, and that it is more than a blank buffer:

  • the IDAT must decompress;
  • the decompressed scanlines must contain a non-zero byte and at least two distinct byte values — a zero-filled framebuffer fails both;
  • the payload must be larger than a best-case blank PNG of the same geometry (blank_png_size() in tests/assert_stream.py: an all-zero raster at zlib level 9, i.e. the smallest a blank frame of that size can be encoded).

It also runs grim directly against the session as a separate subtest, which separates "grim cannot see the compositor" from "the server is wrong" — the two failures that look identical from the socket.

When vm-hyprland fails: where the logs are

Every failing subtest in both VM checks runs hhs-hyprland-diagnostics (tests/hyprland_diagnostics.sh) in the guest first and prints its output to the build log. So the answer to "where are the logs" is usually in the build log you already have, above the traceback, between ########## diagnostics: ... ########## markers. Re-read it with:

nix log .#checks.x86_64-linux.vm-hyprland

What the dump contains, and where it comes from in the guest:

Section Source
units systemctl list-units --all 'hyprland*'
per-unit status / journalctl hyprland-headless.service and hyprland-headless-stream.service, 200 lines each
socket and runtime directories /run/hypr-stream, /run/user/*
hyprland logs every hyprland*.log found under /run, /var/log, /tmp, /home
hyprctl monitors run once per instance found, with the right XDG_RUNTIME_DIR and HYPRLAND_INSTANCE_SIGNATURE
processes ps aux filtered to hypr, hhstream, grim

Hyprland writes its log to $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log, and the compositor runs on a private XDG_RUNTIME_DIR, so the path is not knowable in advance — that is why the script searches for it rather than naming it. The instance signature is the directory name under <runtime>/hypr, which is also what hyprctl needs in the environment:

XDG_RUNTIME_DIR=/run/user/$(id -u hhstream) \
HYPRLAND_INSTANCE_SIGNATURE=$(ls /run/user/$(id -u hhstream)/hypr | head -1) \
  hyprctl monitors

Poking at a live VM

The nicest way to debug a VM failure is to keep the machine:

nix build .#checks.x86_64-linux.vm-hyprland.driverInteractive
./result/bin/nixos-test-driver

That drops you in a Python REPL with machine bound. start_all(), then machine.shell_interact() for a root shell in the guest, or run the test script a line at a time. machine.succeed("hhs-hyprland-diagnostics") works there too.

Layout

checks/
  default.nix            wiring only: the checks the flake exposes
  unit.nix               pytest in the sandbox, against the nix/package.nix build
  vm-basic.nix           nixosTest, fake capture backend
  vm-hyprland.nix        nixosTest, real compositor + grim
  vm-sessions.nix        nixosTest, the broker's lifecycle against the compositor
  vm-ipc.nix             nixosTest, the compositor's request and event sockets
  vm-containers.nix      nixosTest, one output and one workspace per session
  vm-pointer.nix         nixosTest, the lease, the driver and a click that lands
  vm-keyboard.nix        nixosTest, the uploaded keymap, keyboard focus, and a
                         symbol a client decoded. Exposed TWICE -- `vm-keyboard`
                         (layout us) and `vm-keyboard-de` -- because the layout
                         reaches the keymap only through the driver unit's argv
  vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
  vm-mcp.nix             nixosTest, hhstream-mcp driven over stdio by a raw
                         JSON-RPC client against the live broker
  vm-mcp-http.nix        nixosTest, the HTTP transport: the unit's refusal while
                         no token exists and its self-heal after the first mint,
                         the 0700 state dir, the refusals, and two tokens with
                         different tool budgets served by one process
  vm-stream.nix          nixosTest, `session stream enable` and a real HTTP
                         viewer reading MJPEG from inside the guest
  lib/mcp_client.py      that client: hhs-mcp-call, stdlib only and deliberately
                         NOT the MCP SDK's -- the SDK on both ends would agree
                         with itself about a framing neither side had to get right
  lib/mcp_http_client.py the same choice over HTTP: hhs-mcp-http, urllib only,
                         with a distinct exit status for an HTTP refusal so a
                         401 cannot be mistaken for a server that died
  lib/test-tools.nix     packages the tests/ helpers for the guest
  lib/session-tools.nix  packages the two guest programs below
  lib/session-machine.nix  the guest the three session checks share
  lib/session-prelude.nix  their test-script helpers (no assertions live here)
  lib/gpu-session.nix    the hardware a bare test machine does not have
  lib/check_report.py    JUnit report -> build verdict (and the empty-suite guard)
  lib/ipc_watch.py       subscribes to the event socket: hhs-ipc-watch
  lib/pointer_target.py  a Wayland window that reports pointer events it receives:
                         hhs-pointer-target
  lib/keyboard_target.py a Wayland window that reports KEY events, decoded with
                         the keymap the compositor forwarded: hhs-keyboard-target
tests/
  fake_capture.py        writes one fixed PNG to stdout: hhs-fake-capture
  assert_stream.py       independent contract reader/asserter: hhs-assert-stream
  hyprland_diagnostics.sh  the failure dump: hhs-hyprland-diagnostics
  keyboard_probe.py      THROWAWAY: measures the compositor's keyboard behaviour
                         against the live socket. See README-keyboard-probe.md
                         and the transcript beside it; delete both once
                         checks/vm-keyboard.nix asserts the same properties.
  unit/ ipc/ containers/ pointer/ sessions/   the pytest suite

checks/lib/test-tools.nix and checks/lib/session-tools.nix self-test their programs at build time (the fake emits a PNG of the size it was asked for; the asserter starts; the event subscriber can import the broker's IPC client; the pointer target refuses to start without an app id), because a broken helper otherwise surfaces as a baffling failure three layers away.

hhs-ipc-watch deliberately runs the shipped hhstreamd.ipc.HyprlandIPC rather than a second implementation — the opposite choice from tests/assert_stream.py. The difference is what each proves: assert_stream asserts a wire format two programs must agree on, so a shared bug must still fail it; vm-ipc asserts that this client receives events from this compositor, which a reimplementation could not say anything about.

hhs-pointer-target exists because no application in nixpkgs does both of the things the session checks need: set its xdg_toplevel app id from $HHSTREAM_APP_ID (so its window matches its session's container rule) and print the pointer events it receives with the coordinates it was given. foot and wev do neither and ignore the environment entirely, which makes them good unmatched windows and useless as matched ones.

hhs-keyboard-target is its sibling, and the thing that makes it a separate program rather than a flag is where its symbols come from: it compiles the keymap the compositor forwarded over wl_keyboard.keymap and decodes every key through that. A client with its own keymap would decode hello whether or not the driver ever uploaded one, so the check would be asserting that the check can spell. It is also why session-tools.nix builds it against a python with xkbcommon while the pointer target gets one with only pywayland.

Adding a unit test: drop a test_*.py under tests/. Nothing needs registering, but the basename must be unique across the tree. Adding a check: one file in checks/, one line in checks/default.nix.

Typing into a session: the keyboard layout

Keys reach whichever surface the compositor's one seat has focused. A virtual keyboard is seat-global and has no output argument, so unlike the pointer there is nothing to aim — what aims it is the pointer, and pointer acquire takes both (see item 3 under the known gaps for why that is two warps and not one).

hhstream session pointer acquire <id>              # also authorises typing
hhstream session keyboard type <id> 'hello world'  # one argument, raw UTF-8
hhstream session keyboard key <id> Return          # a tap: down then up
hhstream session keyboard down <id> Control_L      # a chord, held
hhstream session keyboard type <id> c              #   ...is Ctrl+C
hhstream session keyboard up <id> Control_L
hhstream session pointer release <id>              # lifts buttons AND keys

hhstream session pointer state reports held keys beside held buttons.

The layout is an operator setting

The driver compiles one XKB keymap at start-up and uploads it once. That keymap is the only thing that decides what an injected key means. Every verb names an XKB keysym — a, A, Return, BackSpace, Left, Control_L — and the driver resolves that name against the keymap to get the evdev code and the modifier mask the compositor is sent.

Option Default Notes
services.hyprland-headless-stream.sessions.keyboard.layout "us" One group only: the option's type refuses us,ru, and so does the driver
…sessions.keyboard.model "pc105"
…sessions.keyboard.variant "" A variant whose characters are dead keys (us(intl)) cannot be typed by v1
…sessions.keyboard.options "" Passed to xkb_keymap_new_from_names; a value it rejects stops the driver with exit 2
services.hyprland-headless-stream.sessions.keyboard.layout = "de";

Three things worth knowing before an agent types anything:

  1. Hyprland's own input:kb_layout is not read and has no effect on injected keys. It describes the layout for physical keyboards, of which a headless session has none, and reading it would mean a hyprctl reload could silently change what every agent types. The two can therefore disagree, and only the option above matters.

  2. A character the layout cannot produce fails the whole string. There is no partial type: keyboard type <id> 'café' on us is exit 2 and emits nothing, rather than typing caf and stopping. The refusal names the scalar index, never the character and never the string, because a typed string is a password as often as not and these messages are logged. The audit log records a character count and nothing else.

  3. keyboard down of a non-modifier floods the window. The compositor sends one key event and publishes a repeat rate; the application repeats, so a held a inserts characters until the key-up or the lease TTL (default 30 s). Measured on this build at 25/s after 600 ms. It is not ours to rate-limit — we do not generate the repeats — so the only safe hold is a modifier, which is what chords are for.

The layout reaches the driver as --xkb-layout on hhstream-pointer's command line, and only there. It is deliberately not a key in the broker's TOML: that file is read by hhstreamd, and the driver is a different unit that never opens it, so a [keyboard] table there would be a setting an operator could change while every injected key stayed on us.

Known gaps in the interface (as of this branch)

Every item the previous revision of this section listed is closed: the module has a config side, package has a default, src/hhstream/*.py is written, and the frame server's command line is the one the module passes. What is open is below. These are defects in code this branch does not own; they are recorded here because the checks are written against the contract and therefore trip over them.

The deep versions of these — the issue, more than one idea, and why each one matters — live in docs/TODO/. Update the file there when one closes, so this list stays a description of what is still true.

  1. The container host can be switched off, and the broker now honours it. (This item previously read "the broker reads none of the container or pointer configuration." That is fixed: policy.py parses those settings beside Policy, read in __main__, and a host that is switched off reports itself unavailable with the reason naming the key — so a disabled machine cannot be mistaken for one whose compositor is down. The reason it matters is what follows.) Containers are consequently off on the deployment machine: no window can be put in one yet, and enabling them quarantines every allowlisted app. That join is the first item in docs/TODO/.

  2. session start --no-container is refused, not honoured. PLAN §9 lists the flag; docs/CONTRACT-sessions.md §4 leaves start unchanged, and SessionManager.start takes no such argument. A request carrying a no_container field would be accepted and ignored, and the session would get a container anyway — so the CLI exits 2 and names the disagreement instead of lying about what it did.

  3. Fixed: nix/hyprland-conf.nix sets input:follow_mouse = 1. (This item previously said it ships 0, that pointer input therefore reaches nothing but the focused window, and that whether to change it was a decision for the keyboard work. The conf file sets 1, and the keyboard work has made that decision; what follows is why, and what is left.)

    The original measurement, by vm-pointer, with two sessions and the second holding focus because its window opened last:

    aimed at target-le22h7: it reports []     <- the session the warp named
    focused is  target-s76taj: it reports []  <- the session with focus
    cursor now at {'x': 2048, 'y': 288}       <- exactly where it was aimed
    

    With 0, the compositor moved the cursor to the right pixel, inside the right window, on the right output, and told no client at all. That defeats the point of containers and the lease, so the conf sets 1.

    What is left, and it is a real limitation. follow_mouse = 1 moves keyboard focus too — which is what makes typing possible at all, since a virtual keyboard is seat-global and has no output to aim. But one warp does not move it. Measured directly against the live compositor (tests/README-keyboard-probe.md): an idle motion_absolute onto an unfocused window delivers wl_pointer.enter and no wl_keyboard.enter, because mouseMoveUnified zeroes m_mousePosDelta when the previous movement was over 0.5 s ago and keyboard focus is that delta compared against input:follow_mouse_threshold.

    So pointer acquire sends two warps, a real pixel apart, and takes the keyboard as well as the cursor. The conf now sets follow_mouse_threshold = 0 explicitly rather than inheriting the default, because that is what the second warp depends on; raise it and acquire stops taking keyboard focus. dispatch focuswindow is the fallback if the nudge cannot be sent, and the acquire reply's focus field says which ran.

  4. A container's window rule only binds for an application that reads the environment. The broker's only lever on an application's class is $HHSTREAM_APP_ID and the three toolkit variables beside it (hhstreamd/launcher.py), so a GTK or Qt application — and foot, and wev — keeps its own class, matches no per-session rule, and is swept into the quarantine workspace. That is reported by the read-back rather than papered over, and it is why vm-containers and vm-pointer use a cooperating client (hhs-pointer-target) for the matched case and foot for the unmatched one. Closing it needs a per-app --app-id in the allowlist, which is a policy change.