Files
HermenixandClaude Opus 5 de408e4b7f the surface: CLI verbs, the module's options, and three checks the compositor votes in
Everything below the CLI was merged and green against fakes; none of it was
reachable and none of it had ever met a compositor. This wires it up and then
puts the compositor in a position to disagree.

CLI (src/hhstream/cli.py, src/hhstream_session/**)

  session container [ID], session reconcile [ID], and the seven pointer verbs
  from PLAN §9. `start` still prints the bare session id and nothing else.
  `list` gains WS / OUTPUT / POINTER, with the gap marker where a value is
  genuinely unknown rather than a blank that reads as zero -- the POINTER
  column needs a second, read-only `pointer.state` call because the `list`
  reply carries no lease state.

  The lease id is cached in `hhstream_session.lease` (under
  $XDG_RUNTIME_DIR), because PLAN §9's gesture verbs take no --lease and the
  wire requires a lease_id on every one of them; --lease and $HHSTREAM_LEASE
  override it, and a `no_lease` refusal drops the stale entry.

  Exit codes are the contract's: a gesture with no lease is 9 and never
  reaches the broker, and a compositor failure is 10 with a message that says
  the session is still running. `kill` now warns about
  `session.container_survivors` -- windows the compositor still shows -- and
  distinguishes `null` ("could not ask") from `[]`.

  `shot`/`record --output NAME` capture one container through `grim -o`; the
  frame socket publishes the main output only, so it cannot do it.

Module (nix/module.nix)

  sessions.containers.{enable,max,mode,workspaceBase},
  sessions.pointer.{enable,leaseTtl,leaseMax}, rendered into the generated
  TOML with §10's key names. hhstream-pointer.service: the operator's account,
  supplementary group hhstream, After=/BindsTo= the compositor,
  Restart=on-failure, KillMode=process, and the command line §3.4 freezes.
  tmpfiles for /run/hhstream plus RuntimeDirectoryPreserve on the broker,
  without which restarting the broker deletes the driver's socket out from
  under it. The runtime-directory length assertion is untouched.

  And ExecStartPost on the compositor, opening its IPC directory to its own
  group: Hyprland creates <runtime>/hypr with S_IRWXU, so the broker -- a
  different account by design -- could not reach the request or event socket
  at all, and degraded silently exactly as it is built to.

Checks (checks/**)

  vm-ipc: both sockets at their frozen names, measured against sun_path's 108
  bytes, and a socket2 subscriber that receives an openwindow for a window the
  test creates. The subscriber is the shipped HyprlandIPC, not a second
  implementation: this check exists to prove that this client hears this
  compositor.

  vm-containers: one hh-* output per session at the container mode, the window
  on it, a second window of the same application beside it, an unmatched
  window quarantined, grim -o isolating one container, teardown removing the
  output and freeing the slot. PLAN experiment 3 is answered: `hyprctl output
  create headless` works.

  vm-pointer: a version-2 virtual pointer, a warp and a click whose
  coordinates the *application* reports, BUSY naming the holder, 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.

  checks/lib gains the guest the three share, their test-script helpers (no
  assertions live there), an event-socket subscriber and a Wayland client that
  says where it was clicked -- nothing in nixpkgs both honours
  $HHSTREAM_APP_ID and reports pointer events.

Reported, not worked around: the broker reads none of the container or
pointer config (policy.py takes [defaults] and [apps] only), `start` has no
no_container field so --no-container is refused rather than silently ignored,
and nix/hyprland-conf.nix sets input:follow_mouse = 0, which sends pointer
events to the focused window only -- measured, with the cursor at the aimed
pixel and no client told. README.dev.md has the evidence for each.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WQy29x9AfHWyzNd1f7XPGK
2026-10-03 06:58:44 +00:00

356 lines
16 KiB
Nix

# checks.<system>.vm-containers -- one output and one workspace per session,
# proved against the compositor that has to create them.
#
# Everything under this has so far been proved against fakes. `hyprctl output
# create headless` is marked **[UNVERIFIED -- experiment 3]** in PLAN §5.1: it
# is *implied* by Hyprland requesting the headless backend as
# AQ_BACKEND_REQUEST_MANDATORY, and nobody had run it. If it does not work,
# this is where that is found out, and the right outcome is a red check that
# quotes the compositor rather than a softer assertion.
#
# ─── THE VICTIM, AND WHY IT IS NOT `foot` ────────────────────────────────────
# A session's window rule is `match:initial_class ^hh-<id>$`, and the broker's
# only lever on an application's class is the environment (`$HHSTREAM_APP_ID`,
# see `hhstreamd/launcher.py`): a per-app `--app-id` flag would have to come
# out of the allowlist. `foot` and `wev` ignore the environment and keep their
# own class, so their windows match no per-session rule -- which makes them
# excellent *unmatched* windows and useless as matched ones.
#
# So this check uses both, for the two different jobs:
#
# * `target`, a wrapper around `hhs-pointer-target` (checks/lib), reads
# $HHSTREAM_APP_ID and calls `xdg_toplevel.set_app_id` with it. Its windows
# are the ones that must land in their container.
# * `foot`, launched *outside* any session, is the window that matches
# nothing and must end up quarantined.
#
# The launcher's own docstring says a GTK or Qt application ignores all four
# variables and its rule will not bind. That is a real limitation of the
# design, and this check is deliberately written so it is visible: the matched
# case needs a cooperating client, and nothing here pretends otherwise.
# ─────────────────────────────────────────────────────────────────────────────
{
testers,
hhstream,
hhsModule,
testTools,
hyprland,
foot,
jq,
grim,
procps,
coreutils,
dejavu_fonts,
width ? 1280,
height ? 720,
sessionUser ? "hermes",
}:
testers.runNixOSTest (
{ pkgs, ... }:
let
tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; };
guest = import ./lib/session-machine.nix {
inherit
hhsModule
hhstream
hyprland
testTools
foot
jq
procps
grim
coreutils
dejavu_fonts
;
sessionTools = tools;
};
prelude = import ./lib/session-prelude.nix {
inherit hhstream coreutils sessionUser;
};
# The wrapper the launcher's docstring describes: "HHSTREAM_APP_ID for a
# wrapper script that knows what to do with it". `exec`, so the session's
# pid is the client's and the broker's kill handle stays correct -- the
# cmdline change that causes is explicitly tolerated (procmon, BUG-02).
target = pkgs.writeShellScript "hhs-target-wrapper" ''
exec ${tools}/bin/hhs-pointer-target --app-id "$HHSTREAM_APP_ID" "$@"
'';
in
{
name = "hhstream-vm-containers";
globalTimeout = 1800;
nodes.machine = guest {
inherit width height sessionUser;
apps = {
target = {
exec = "${target}";
# One caller-supplied argument, so the two-window subtest can ask for
# a second toplevel without a second allowlist entry.
argsAllow = [ "--windows=*" ];
};
};
};
testScript =
prelude
+ ''
MODE = (${toString width}, ${toString height})
start_all()
bring_up("the compositor and broker")
with subtest("the as-user wrapper propagates exit status"):
machine.succeed(as_user(TRUE), timeout=120)
machine.fail(as_user(FALSE), timeout=120)
with subtest("a fresh machine has one output and no containers"):
# The baseline every assertion below is a difference from. An
# `hh-*` output here would mean the compositor kept one from a
# previous boot, which it cannot -- so this also proves the
# start-up scan found nothing to clean up.
try:
before = [m["name"] for m in compositor("monitors")]
print(f"outputs before: {before}")
assert not [n for n in before if n.startswith("hh-")], before
listing = cli_json("container --json")
assert listing["containers"] == [], listing
assert listing["orphans"] == [], listing
except Exception:
dump("the machine did not start clean")
raise
with subtest("starting a session creates one output named hh-<id>"):
# PLAN §5.1 experiment 3: does `hyprctl output create headless`
# actually work on this instance? Everything else depends on it.
try:
session_id = machine.succeed(cli("start target"), timeout=180).strip()
print(f"session: {session_id}")
expected = f"hh-{session_id}"
record = cli_json(f"status --json {session_id}")["session"]
print(json.dumps(record["container"], indent=2, sort_keys=True))
container = record["container"]
assert container["state"] == "owned", (
f"the broker did not create a container: {container}. "
"If `state` is 'degraded' the compositor refused `output "
"create headless` -- read the journal above for its words."
)
assert container["output"] == expected, container
monitor = monitor_named(expected)
assert monitor is not None, (
f"the broker recorded {expected} but the compositor has "
f"{[m['name'] for m in compositor('monitors')]}"
)
print(json.dumps(monitor, indent=2, sort_keys=True))
assert (monitor["width"], monitor["height"]) == MODE, (
f"{expected} is {monitor['width']}x{monitor['height']}, not "
f"the container mode {MODE[0]}x{MODE[1]}"
)
workspace = container["workspace"]
assert workspace >= 1000, (
f"workspace {workspace} is outside the reserved band (1000+)"
)
except Exception:
dump("no container output was created", locals().get("session_id"))
raise
with subtest("the application's window is on that output, not elsewhere"):
# The compositor is the authority: the record saying `owned` only
# means the broker asked for an output, not that the window rule
# bound and the window went there.
try:
machine.wait_until_succeeds(
f"{HYPRCTL} clients | jq -e --arg m {expected}"
" 'any(.initialClass == $m)' >/dev/null",
timeout=120,
)
ours = [
c for c in compositor("clients") if c.get("initialClass") == expected
]
print(json.dumps(ours, indent=2, sort_keys=True))
assert len(ours) == 1, f"expected one window of ours, got {len(ours)}"
client = ours[0]
assert client["workspace"]["id"] == workspace, (
f"the window is on workspace {client['workspace']} and the "
f"container is {workspace}"
)
except Exception:
dump("the window did not land in its container", session_id)
raise
with subtest("a second window of the same application lands in the same one"):
# Same session, same app id, second toplevel. The rule matches on
# `initial_class`, so this is the case the rule is written for --
# and the one that would silently break if the rule were per-window
# rather than per-class.
try:
second = machine.succeed(
cli("start target -- --windows=2"), timeout=180
).strip()
second_expected = f"hh-{second}"
second_ws = cli_json(f"status --json {second}")["session"]["container"][
"workspace"
]
print(f"second session {second} on workspace {second_ws}")
machine.wait_until_succeeds(
f"{HYPRCTL} clients | jq -e --arg m {second_expected}"
" '[.[] | select(.initialClass == $m)] | length == 2' >/dev/null",
timeout=120,
)
windows = [
c
for c in compositor("clients")
if c.get("initialClass") == second_expected
]
print(json.dumps(windows, indent=2, sort_keys=True))
assert len(windows) == 2, windows
on = {w["workspace"]["id"] for w in windows}
assert on == {second_ws}, (
f"the two windows of one application are on workspaces {on}, "
f"not both on the container's {second_ws}"
)
# And they are in a different container from the first session:
# one output per session is the other half of the claim.
assert second_ws != workspace, (second_ws, workspace)
except Exception:
dump("the second window did not join its container", locals().get("second"))
raise
with subtest("a window matching no container is quarantined"):
# `foot` is launched outside any session, so it carries its own
# class and matches no per-session rule. Without the backstop it
# would appear on whatever output happened to be focused -- which
# is one of the two sessions' containers, i.e. in someone's screen
# capture. PLAN §5.2.
try:
machine.succeed(
background(
"stray",
"${foot}/bin/foot",
env=compositor_env(),
user=USER,
),
timeout=120,
)
machine.wait_until_succeeds(
f"{HYPRCTL} clients | jq -e 'any(.initialClass == \"foot\")' >/dev/null",
timeout=120,
)
stray = [c for c in compositor("clients") if c.get("initialClass") == "foot"]
print(json.dumps(stray, indent=2, sort_keys=True))
assert len(stray) == 1, stray
landed = stray[0]["workspace"]["name"]
assert landed == "special:quarantine", (
f"an unmatched window landed on workspace {landed!r}; the "
"quarantine backstop did not catch it, so it is sitting on "
"whatever output was focused"
)
except Exception:
dump("an unmatched window was not quarantined")
raise
with subtest("grim -o captures that container and only that container"):
# The reason a container is an *output* and not just a workspace
# (PLAN §5.4). Two captures of two different containers must differ
# -- and both must differ from a capture of the main output, which
# has the stray window on it.
try:
shots = {}
for name in (expected, second_expected):
path = f"/tmp/{name}.png"
# No compositor environment passed in: the CLI discovers
# the session itself, which is the part under test. It runs
# as the operator account, through grim, like a person.
machine.succeed(
as_user(f"{HHSTREAM} shot --output {name} --out {path}"),
timeout=180,
)
# PNG IHDR: width and height are two big-endian uint32 at
# byte 16. Read with od so no interpreter is involved.
geometry = machine.succeed(
f"od -An -tu4 -j16 -N8 --endian=big {path}"
).split()
shots[name] = (
geometry,
machine.succeed(f"sha256sum {path}").split()[0],
)
print(f"{name}: {geometry} sha {shots[name][1]}")
for name, (geometry, _) in shots.items():
assert geometry == [str(MODE[0]), str(MODE[1])], (
f"{name} captured at {geometry}, not the container mode "
f"{MODE[0]}x{MODE[1]}"
)
assert shots[expected][1] != shots[second_expected][1], (
"two different containers captured byte-identical images; "
"grim -o is not selecting an output"
)
except Exception:
dump("per-container capture did not isolate the containers")
raise
with subtest("an output that does not exist is refused, not invented"):
try:
code, out = machine.execute(
as_user(f"{HHSTREAM} shot --output hh-nothing --out /tmp/no.png")
+ " 2>&1",
timeout=120,
)
print(f"exit {code}: {out}")
assert code != 0, "capturing a non-existent output succeeded"
# grim's own words, passed through rather than replaced by a
# guess at what went wrong.
assert "hh-nothing" in out, out
machine.fail("test -e /tmp/no.png")
except Exception:
dump("a bad output name did not fail")
raise
with subtest("teardown removes the output and the compositor agrees"):
try:
reply = cli_json(f"kill --json {session_id}", timeout=180)
print(json.dumps(reply["session"]["container"], indent=2, sort_keys=True))
assert reply["ok"] is True, reply
assert reply["session"]["container_removed"] is True, reply["session"]
assert reply["session"]["container_survivors"] == [], (
"the compositor still shows windows for a session whose "
f"output was removed: {reply['session']['container_survivors']}"
)
machine.wait_until_succeeds(
f"{HYPRCTL} monitors | jq -e --arg m {expected}"
" 'all(.name != $m)' >/dev/null",
timeout=60,
)
assert monitor_named(expected) is None, (
f"{expected} is still an output after teardown"
)
except Exception:
dump("the container outlived its session", session_id)
raise
with subtest("the workspace slot comes back and a new session reuses the band"):
# Releasing the slot is what stops the band leaking: without it the
# fourth session on a 4-slot band would be refused for no reason.
try:
listing = cli_json("container --json")
print(json.dumps(listing, indent=2, sort_keys=True))
assert workspace not in listing["workspaces_in_use"], listing
assert listing["orphans"] == [], (
f"teardown left an orphan output behind: {listing['orphans']}"
)
third = machine.succeed(cli("start target"), timeout=180).strip()
third_ws = cli_json(f"status --json {third}")["session"]["container"][
"workspace"
]
print(f"third session {third} took workspace {third_ws}")
assert third_ws == workspace, (
f"the freed slot {workspace} was not reused; got {third_ws}"
)
except Exception:
dump("the workspace slot was not released", locals().get("third"))
raise
'';
}
)