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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-03 06:58:44 +00:00
1 parent 57fdd4f636
commit de408e4b7f
19 files changed
+4304 -98

No files matched your search

+535 -4
View File
@@ -21,9 +21,24 @@ standard library, so a host CLI pays no startup cost and gains no new failure
mode by registering it.
**The one thing to read before using this:** ``touch`` is the only mark of
activity that exists. ``list``, ``status``, ``logs`` and ``gc`` deliberately do
not reset a session's idle clock, so an agent watching a long-running app must
call ``touch`` or the session will be reaped on schedule.
activity that exists. ``list``, ``status``, ``logs``, ``gc``, ``container``,
``reconcile`` and every ``pointer`` verb deliberately do not reset a session's
idle clock, so an agent watching or driving a long-running app must call
``touch`` or the session will be reaped on schedule. Being driven is not the
same as being wanted.
The verb tree, beyond the original eight:
session container [ID] the output and workspace a session was given
session reconcile [ID] re-read them from the compositor, report drift
session pointer acquire ID take the one cursor, aimed into ID's container
session pointer move ID ... warp, --to X,Y or --by DX,DY (0..1, per output)
session pointer click/down/up/release ID
session pointer state who holds the cursor and what is pressed
The pointer verbs share one precondition — the lease — and the lease id lives
in :mod:`hhstream_session.lease` between invocations, because the wire requires
it on every gesture and the CLI is one process per verb.
"""
from __future__ import annotations
@@ -37,6 +52,7 @@ from hhstreamd.clock import format_duration, parse_duration
from hhstreamd.protocol import ExitCode
from . import format as fmt
from . import lease
from .client import DEFAULT_SOCKET, ENV_SOCKET, ClientError, call, reply_exit_code
__all__ = ["register", "build_parser", "dispatch", "main", "ExitCode"]
@@ -164,6 +180,12 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
help="deduplication token: retrying a start with the same id returns the "
"original reply instead of launching a second application",
)
start.add_argument(
"--no-container",
action="store_true",
help="start without a container (NOT IMPLEMENTED: the broker's 'start' "
"verb carries no such field — see the message it refuses with)",
)
# ---- list --------------------------------------------------------
lst = add("list", _cmd_list, help="list sessions (does NOT count as activity)")
@@ -232,6 +254,219 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
"--follow", "-f", action="store_true", help="keep printing new output until interrupted"
)
# ---- container ---------------------------------------------------
container = add(
"container",
_cmd_container,
help="the output and workspace a session was given "
"(does NOT count as activity)",
description=(
"Show one session's container -- the output, workspace and mode the "
"broker created for it -- or, with no id, every container plus the "
"'hh-*' outputs no live session claims (orphans)."
),
)
container.add_argument(
"id",
nargs="?",
help="session id; omit for every container and the orphan list",
)
# ---- reconcile ---------------------------------------------------
reconcile = add(
"reconcile",
_cmd_reconcile,
help="re-read containers from the compositor and report the drift "
"(does NOT count as activity)",
description=(
"Ask the compositor where a session's window actually is and bring "
"the record up to that answer; the compositor is the authority and "
"the record is a cache of it. With no id, every live session is "
"reconciled and the start-up scan is re-run: the quarantine rule is "
"re-installed, adopted containers re-take their workspace slots, and "
"'hh-*' outputs with no live session are removed."
),
)
reconcile.add_argument("id", nargs="?", help="session id; omit for all of them")
reconcile.add_argument("--request-id", metavar="ID", help="deduplication token")
# ---- pointer -----------------------------------------------------
_build_pointer(verbs, common)
#: Button names the driver knows (``hhstream_pointer.buttons.CODES``), mirrored
#: here rather than imported: this module's whole integration promise is that it
#: imports ``hhstreamd.protocol`` and the standard library and nothing else, so
#: registering it cannot drag in the driver's Wayland dependencies. The driver
#: is still the authority -- it answers an unknown name with the set it knows --
#: and this list only buys a typo an exit 2 instead of an exit 10.
BUTTONS = ("left", "right", "middle", "side", "extra", "forward", "back", "task")
def _build_pointer(verbs: Any, common: argparse.ArgumentParser) -> None:
"""``session pointer <verb>`` — the one cursor, under a lease (PLAN §6).
A nested namespace rather than seven top-level verbs because they share one
precondition that nothing else here has: the lease. Grouping them is what
makes ``pointer --help`` able to say that once.
"""
namespace = verbs.add_parser(
"pointer",
parents=[common],
help="aim and click the one cursor at a session, under a lease",
description=(
"The cursor is singular, so it is leased. 'acquire' takes it and "
"prints the lease id on stdout; the gesture verbs reuse that lease "
"and refuse (exit 9) without it; 'release' gives it back, lifting "
"anything still pressed. A lease left idle past its TTL is "
"force-released by the broker, which also lifts its buttons.\n\n"
"Coordinates are OUTPUT-NORMALISED, 0..1, within the session's own "
"container: (0,0) is its top-left corner and (1,1) its "
"bottom-right. Window-local pixel aiming is deliberately absent -- "
"the broker's IPC client carries no window geometry, so there is "
"nothing honest to convert from.\n\n"
"No pointer verb counts as activity: a session being driven is "
"still a session nobody has said they want kept. Call 'touch'."
),
epilog=ACTIVITY_NOTE,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
gestures = namespace.add_subparsers(dest="pointer_verb", metavar="VERB")
namespace.set_defaults(
func=_cmd_pointer_state, hhstream_session_handler=_cmd_pointer_state, json=False
)
def add_gesture(name: str, handler, **kwargs: Any):
sub = gestures.add_parser(name, parents=[common], **kwargs)
sub.set_defaults(func=handler, hhstream_session_handler=handler)
sub.add_argument("--json", action="store_true", help="emit the protocol object on stdout")
return sub
def with_lease(sub: argparse.ArgumentParser) -> argparse.ArgumentParser:
sub.add_argument(
"--lease",
metavar="ID",
help="the lease id from 'pointer acquire'. Omitted, the one that "
f"acquire cached is used (${lease.ENV_LEASE} overrides that).",
)
return sub
acquire = add_gesture(
"acquire",
_cmd_pointer_acquire,
help="take the cursor for a session and aim it into its container",
description=(
"Take the one cursor and warp it into this session's own output. "
"Prints the bare lease id on stdout, so $(hhstream session pointer "
"acquire ID) is the lease and nothing else, and caches it so the "
"gesture verbs below need no flag. A second acquire while someone "
"else holds it exits 8 (BUSY) naming the holder."
),
)
acquire.add_argument("id", help="session id")
acquire.add_argument(
"--ttl",
type=_duration,
metavar="DURATION",
help="idle lifetime for this lease before the broker force-releases it "
"(default: the broker's; capped by its hard maximum)",
)
acquire.add_argument(
"--no-restore",
action="store_true",
help="start at the centre of the container instead of the position this "
"session's cursor was last left at",
)
move = with_lease(add_gesture(
"move",
_cmd_pointer_move,
help="warp within the session's own output (normalised 0..1)",
description=(
"Warp the cursor inside this session's container. --to is absolute "
"and refused outside 0..1, because a caller that computed 1.4 has a "
"bug and clamping would hide it; --by is relative and IS clamped, "
"because running into the edge of the screen is what a mouse does."
),
))
move.add_argument("id", help="session id")
target = move.add_mutually_exclusive_group(required=True)
target.add_argument(
"--to", type=_point, metavar="X,Y", help="absolute, output-normalised 0..1"
)
target.add_argument(
"--by", type=_point, metavar="DX,DY", help="relative to the current bookmark"
)
click = with_lease(add_gesture(
"click",
_cmd_pointer_click,
help="press and release a button where the cursor is",
))
click.add_argument("id", help="session id")
click.add_argument(
"--button", default="left", choices=BUTTONS, metavar="B", help=_button_help()
)
for name, state in (("down", "down"), ("up", "up")):
sub = with_lease(add_gesture(
name,
_cmd_pointer_button,
help=f"hold a button {state} without releasing it"
if state == "down"
else "release a button that was held down",
description=(
"Half a click. Together with 'move' this is a drag, and the "
"lease is what makes the three calls atomic -- no other "
"session's events are interleaved. The broker lifts whatever "
"is still down on release or on a lease timeout, so a crashed "
"agent cannot leave a button pressed."
),
))
sub.set_defaults(button_state=state)
sub.add_argument("id", help="session id")
sub.add_argument(
"--button", default="left", choices=BUTTONS, metavar="B", help=_button_help()
)
release = with_lease(add_gesture(
"release",
_cmd_pointer_release,
help="give the cursor back, lifting anything still pressed",
))
release.add_argument("id", help="session id")
add_gesture(
"state",
_cmd_pointer_state,
help="who holds the cursor, and what is pressed (does NOT count as activity)",
)
def _button_help() -> str:
return f"one of: {', '.join(BUTTONS)} (default: left)"
def _point(text: str) -> tuple[float, float]:
"""``X,Y`` as two floats.
Parsed here so a malformed pair is a usage error from argparse (exit 2)
before anything reaches the broker, and so the error names the form.
"""
parts = text.split(",")
if len(parts) != 2:
raise argparse.ArgumentTypeError(
f"expected two numbers separated by a comma, e.g. 0.5,0.5 — got {text!r}"
)
try:
return (float(parts[0]), float(parts[1]))
except ValueError:
raise argparse.ArgumentTypeError(
f"{text!r} is not a pair of numbers (coordinates are output-normalised, 0..1)"
) from None
def _duration(text: str) -> float:
try:
@@ -300,6 +535,27 @@ def _cmd_start(args: argparse.Namespace) -> int:
# argparse has already removed the separating `--`, so what is left is the
# application's own argv, as a list. It is never joined into a string.
argv = list(args.argv or [])
if args.no_container:
# Refused rather than sent. The flag is in PLAN §9's surface, but the
# wire's `start` (CONTRACT-sessions.md §4: "existing verbs are
# unchanged") carries no `no_container` field and `SessionManager.start`
# takes no such argument, so a request carrying it would be silently
# ignored and the session would get a container anyway. A flag that
# lies about what it did is worse than one that says it cannot.
return _finish(
args,
{
"ok": False,
"error": "invalid_argument",
"reason": "--no-container is not implemented by this broker: the "
"'start' verb has no no_container field, so the request would be "
"accepted and a container created anyway",
"hint": "start without it and tear the container down with "
"'session kill', or report the gap against "
"docs/CONTRACT-sessions.md §4",
},
lambda r: "",
)
reply = _request(
args,
"start",
@@ -349,7 +605,40 @@ def _fmt_timeout(seconds: Any) -> str:
@_guard
def _cmd_list(args: argparse.Namespace) -> int:
reply = _request(args, "list", all=bool(getattr(args, "all", False)) or None)
return _finish(args, reply, lambda r: fmt.render_list(r.get("sessions") or []))
if getattr(args, "json", False) or not reply.get("ok"):
# `--json` is the protocol's own object, unmodified: splicing the lease
# holder into it would invent a field no other caller can rely on.
return _finish(args, reply, lambda r: "")
holder, known = _pointer_holder(args)
return _finish(
args,
reply,
lambda r: fmt.render_list(
r.get("sessions") or [], pointer_holder=holder, pointer_known=known
),
)
def _pointer_holder(args: argparse.Namespace) -> tuple[Any, bool]:
"""Who holds the one cursor, for the ``POINTER`` column.
A second request, because the ``list`` reply carries no lease state and the
broker is not this slice's file to change. It is read-only and does not
count as activity (CONTRACT-sessions.md §4), so the only cost is a round
trip on a human listing — ``--json`` never makes it.
Returns ``(holder, known)``. ``known=False`` is not a failure worth exiting
over: the sessions have been listed, and the honest thing is to print the
gap marker in that one column rather than lose the whole table.
"""
try:
reply = _request(args, "pointer.state")
except ClientError:
return None, False
if not reply.get("ok") or "holder" not in reply:
return None, False
return reply.get("holder"), True
@_guard
@@ -372,6 +661,43 @@ def _cmd_touch(args: argparse.Namespace) -> int:
return _finish(args, reply, render)
def _container_teardown(session: dict[str, Any]) -> list[str]:
"""What the compositor side of a teardown left behind.
``survivors`` (processes) was already reported and ``container_survivors``
(windows the compositor still shows) was not, so a teardown that removed
the output and left a window on the screen read as a clean kill. They are
two independent sources and PLAN §4.5 requires both to agree before a
teardown is called a success.
``None`` is its own case and is *not* folded into "none": it means the
compositor could not be asked, so "no windows survived" is a claim nobody
is in a position to make.
"""
bits = []
if session.get("container_removed"):
bits.append("container removed")
if session.get("container_error"):
bits.append(f"container error: {session['container_error']}")
survivors = session.get("container_survivors")
if survivors is None:
bits.append(
"WARNING: the compositor could not be asked whether any window "
"survived the teardown"
)
elif survivors:
named = ", ".join(
f"{w.get('class') or w.get('initial_class')}@{w.get('address')} (pid {w.get('pid')})"
for w in survivors
)
bits.append(
f"WARNING: the compositor still shows {len(survivors)} window(s) "
f"after the output was removed ({named})"
)
return bits
@_guard
def _cmd_kill(args: argparse.Namespace) -> int:
reply = _request(
@@ -413,6 +739,7 @@ def _cmd_kill(args: argparse.Namespace) -> int:
f"WARNING: {len(survivors)} process(es) SURVIVED "
f"({', '.join(str(p) for p in survivors)})"
)
bits.extend(_container_teardown(session))
return "; ".join(bits)
return _finish(args, reply, render)
@@ -472,6 +799,210 @@ def _cmd_logs(args: argparse.Namespace) -> int:
return int(ExitCode.OK)
# --------------------------------------------------------------------------
# containers
# --------------------------------------------------------------------------
@_guard
def _cmd_container(args: argparse.Namespace) -> int:
"""One session's container, or the whole picture including orphans.
With an id this is ``container.reconcile`` and not ``container.list``, and
that is deliberate: asking "what container does this session have" is
almost always asking "where is this window *now*", and the list verb can
only report what the record remembers.
"""
if args.id is None:
reply = _request(args, "container.list")
return _finish(args, reply, fmt.render_containers)
reply = _request(args, "container.reconcile", id=args.id)
return _finish(args, reply, fmt.render_container)
@_guard
def _cmd_reconcile(args: argparse.Namespace) -> int:
reply = _request(
args, "container.reconcile", id=args.id, request_id=args.request_id
)
return _finish(args, reply, fmt.render_reconcile)
# --------------------------------------------------------------------------
# the pointer lease
# --------------------------------------------------------------------------
def _lease_of(args: argparse.Namespace, session_id: str) -> str | None:
"""The lease id for this verb: the flag, the environment, then the cache."""
explicit = getattr(args, "lease", None)
if explicit:
return explicit
return lease.recall(session_id, socket=_socket_of(args))
def _no_lease(args: argparse.Namespace, session_id: str) -> int:
"""Refuse a gesture with no lease, without troubling the broker.
Exit 9 and not 2: the caller's command line is fine, what is missing is the
lease — and 9 is precisely the code that says "acquire one and try again"
(CONTRACT-sessions.md §4). The broker would answer the same way; refusing
here means the message can name the cache, which the broker knows nothing
about.
"""
reply = {
"ok": False,
"error": "no_lease",
"reason": f"no pointer lease for {session_id} on this socket",
"hint": f"run 'pointer acquire {session_id}' first, or pass --lease "
"with the id it printed",
}
return _finish(args, reply, lambda r: "")
def _finish_gesture(
args: argparse.Namespace, reply: dict[str, Any], render, session_id: str
) -> int:
"""Print a gesture's reply, dropping a lease the broker has just disowned.
A cached lease that is refused is stale by definition — expired, released
by the sweeper, or taken over — and keeping it would make every subsequent
verb fail the same way while the fix (``acquire``) looks unnecessary.
"""
if reply.get("error") in ("no_lease", "no_such_session"):
lease.forget(session_id)
return _finish(args, reply, render)
@_guard
def _cmd_pointer_acquire(args: argparse.Namespace) -> int:
reply = _request(
args,
"pointer.acquire",
id=args.id,
ttl_s=args.ttl,
# `False` and not `None`: the wire default is to restore, so the only
# way to ask for the centre is to say so explicitly.
restore=False if args.no_restore else None,
)
if not reply.get("ok"):
return _finish(args, reply, lambda r: "")
lease_id = reply.get("lease_id") or ""
lease.remember(args.id, lease_id, socket=_socket_of(args))
if args.json:
fmt.dump_json(reply)
return int(ExitCode.OK)
# Same shape as `start`: stdout is the one token a caller needs to pass
# back, detail goes to stderr.
print(lease_id)
bookmark = reply.get("bookmark") or {}
print(
f"acquired the cursor for {reply.get('id')} on {bookmark.get('output')} "
f"at {fmt.render_bookmark(bookmark)}",
file=sys.stderr,
)
print(
f"expires in {_fmt_timeout(reply.get('expires_in_s'))} with no further "
f"pointer verb; release it with: hhstream session pointer release {args.id}",
file=sys.stderr,
)
return int(ExitCode.OK)
@_guard
def _cmd_pointer_move(args: argparse.Namespace) -> int:
lease_id = _lease_of(args, args.id)
if not lease_id:
return _no_lease(args, args.id)
absolute = getattr(args, "to", None)
relative = getattr(args, "by", None)
coordinates = (
{"x": absolute[0], "y": absolute[1]}
if absolute is not None
else {"dx": relative[0], "dy": relative[1]}
)
reply = _request(args, "pointer.move", id=args.id, lease_id=lease_id, **coordinates)
def render(r: dict[str, Any]) -> str:
return f"{r.get('id')}: cursor at {fmt.render_bookmark(r.get('bookmark'))}"
return _finish_gesture(args, reply, render, args.id)
@_guard
def _cmd_pointer_click(args: argparse.Namespace) -> int:
lease_id = _lease_of(args, args.id)
if not lease_id:
return _no_lease(args, args.id)
reply = _request(
args, "pointer.click", id=args.id, lease_id=lease_id, button=args.button
)
def render(r: dict[str, Any]) -> str:
return (
f"{r.get('id')}: clicked {r.get('button')} "
f"at {fmt.render_bookmark(r.get('bookmark'))}"
)
return _finish_gesture(args, reply, render, args.id)
@_guard
def _cmd_pointer_button(args: argparse.Namespace) -> int:
lease_id = _lease_of(args, args.id)
if not lease_id:
return _no_lease(args, args.id)
reply = _request(
args,
"pointer.button",
id=args.id,
lease_id=lease_id,
button=args.button,
state=args.button_state,
)
def render(r: dict[str, Any]) -> str:
down = r.get("buttons") or []
return (
f"{r.get('id')}: {args.button} {args.button_state}; "
f"held: {', '.join(down) if down else 'nothing'}"
)
return _finish_gesture(args, reply, render, args.id)
@_guard
def _cmd_pointer_release(args: argparse.Namespace) -> int:
lease_id = _lease_of(args, args.id)
if not lease_id:
return _no_lease(args, args.id)
reply = _request(args, "pointer.release", id=args.id, lease_id=lease_id)
if reply.get("ok"):
lease.forget(args.id)
def render(r: dict[str, Any]) -> str:
lifted = r.get("buttons_lifted") or []
bits = [
f"{r.get('id')}: cursor released by {r.get('released_by')}",
f"bookmark {fmt.render_bookmark(r.get('bookmark'))}",
]
if lifted:
bits.append(f"lifted {', '.join(lifted)}")
return "; ".join(bits)
return _finish_gesture(args, reply, render, args.id)
@_guard
def _cmd_pointer_state(args: argparse.Namespace) -> int:
reply = _request(args, "pointer.state")
return _finish(args, reply, fmt.render_pointer_state)
# --------------------------------------------------------------------------
# standalone use
# --------------------------------------------------------------------------