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

+263 -10
View File
@@ -13,6 +13,11 @@ from typing import Any
from hhstreamd.clock import format_duration
#: The honest gap. Printed wherever a value is genuinely unknown, because the
#: alternative — a blank cell — reads as zero or as "no", and the three columns
#: added in this milestone (``WS``, ``OUTPUT``, ``POINTER``) are unknown exactly
#: when the compositor could not be asked. That is the case a reader most needs
#: to be able to see.
DASH = "—"
@@ -35,19 +40,48 @@ def render_table(rows: list[list[str]], headers: list[str]) -> str:
return "\n".join(out)
def render_list(sessions: list[dict[str, Any]]) -> str:
def pointer_cell(session_id: str, holder: Any, *, known: bool) -> str:
"""The ``POINTER`` column for one row (PLAN §9).
Three facts, told apart on purpose: this session holds the one cursor
(``held``), somebody else does and the row says who (``held:<id>``), or
nobody does (``free``). ``known=False`` is the fourth case and prints the
gap marker — the broker could not be asked who holds it, which is not the
same as nobody holding it.
"""
if not known:
return DASH
if holder is None:
return "free"
return "held" if holder == session_id else f"held:{holder}"
def render_list(
sessions: list[dict[str, Any]],
*,
pointer_holder: Any = None,
pointer_known: bool = False,
) -> str:
"""The default view.
``EXPIRES IN`` is on it rather than behind a flag because it is the number
an agent actually needs.
There is **no ``FG`` column** (DESIGN.md §1.4, amended): foreground-ness
needs compositor IPC, which this milestone does not have, so the column was
``?`` on every row of every listing — a header and six columns of width
paying for no information, and a reader who has to learn that ``?`` means
*unknown* rather than *no*. ``foreground`` stays in the record and in
``status``, where it is one line among many and can become real without
changing the shape of this table.
``WS`` / ``OUTPUT`` / ``POINTER`` are the columns PLAN §9 asks for, and they
are *after* ``PID`` rather than before it: the position of the existing
columns is something callers already read (and a VM check asserts on), so
the new ones are appended where nothing has to shift.
There is still **no ``FG`` column** (DESIGN.md §1.4, amended): it would be
a sixth narrow column carrying a tri-state almost nobody branches on, and
``status`` reports foreground in a line of its own. ``WS`` and ``OUTPUT``
earn their width differently — they are how a caller finds the container to
point ``grim -o`` or a pointer verb at.
``pointer_known`` exists because the ``list`` reply carries no lease state:
the holder comes from a second, read-only ``pointer.state`` call, and when
that call fails the column must say *unknown* rather than *free*.
"""
if not sessions:
@@ -64,17 +98,193 @@ def render_list(sessions: list[dict[str, Any]]) -> str:
idle = DASH
left = s.get("tombstone_expires_in_s")
expires = f"(tombstone, {format_duration(left)} left)" if left is not None else DASH
container = s.get("container") or {}
rows.append(
[
_cell(s.get("id")),
_cell(s.get("app")),
_cell(s.get("state")),
_cell(s.get("pid")) if live else DASH,
_cell(s.get("workspace")),
_cell(container.get("output")),
pointer_cell(str(s.get("id")), pointer_holder, known=pointer_known)
if live
else DASH,
idle,
expires,
]
)
return render_table(rows, ["ID", "APP", "STATE", "PID", "IDLE", "EXPIRES IN"])
return render_table(
rows,
["ID", "APP", "STATE", "PID", "WS", "OUTPUT", "POINTER", "IDLE", "EXPIRES IN"],
)
def render_containers(reply: dict[str, Any]) -> str:
"""``session container`` with no id: every container, and every orphan.
The orphan list is the reason this view exists at all. ``hh-*`` outputs with
no live session are the thing a start-up scan removes, and until they are
printed somewhere an operator has no way to see that the compositor is
carrying render targets nobody owns.
"""
rows = []
for row in reply.get("containers") or []:
rows.append(
[
_cell(row.get("id")),
_cell(row.get("app")),
_cell(row.get("output")),
_cell(row.get("workspace")),
render_mode(row.get("mode")),
_cell(row.get("state")),
_cell(row.get("window")),
]
)
lines = [
render_table(rows, ["ID", "APP", "OUTPUT", "WS", "MODE", "STATE", "WINDOW"])
if rows
else "no containers"
]
lines.append(f"compositor: {_cell(reply.get('compositor'))}")
if reply.get("error"):
lines.append(f" {reply['error']}")
in_use = reply.get("workspaces_in_use")
lines.append(
"workspaces: " + (", ".join(str(w) for w in in_use) if in_use else "none in use")
)
orphans = reply.get("orphans")
if orphans is None:
# Not `[]`: "could not look" and "looked, found none" are different
# claims and only one of them is reassuring.
lines.append(f"orphans: {DASH} (the compositor could not be asked)")
elif orphans:
lines.append(
f"orphans: {len(orphans)} hh-* output(s) no live session claims: "
+ ", ".join(orphans)
)
else:
lines.append("orphans: none")
return "\n".join(lines)
def render_container(reply: dict[str, Any]) -> str:
"""``session container ID``: one session's container, and its drift."""
container = reply.get("container")
lines = [f"{_cell(reply.get('id'))}"]
if not container:
lines.append(f" container {DASH} (this session has none)")
else:
lines.append(
f" output {_cell(container.get('output'))}"
f" workspace {_cell(container.get('workspace'))}"
f" mode {render_mode(container.get('mode'))}"
)
lines.append(
f" state {_cell(container.get('state'))}"
f" created by {_cell(container.get('created_by'))}"
)
lines.extend(render_diff(reply.get("diff") or []))
return "\n".join(lines)
def render_diff(diff: list[dict[str, Any]]) -> list[str]:
"""Where the record and the compositor disagreed, with both values.
An empty diff is printed, not omitted: "the record matches the compositor"
is the useful answer to ``reconcile``, and silence would be read as a verb
that did nothing.
"""
if not diff:
return [" drift none (the record matches the compositor)"]
lines = [" drift"]
for item in diff:
if item.get("error"):
lines.append(f" {item.get('id')}: {item['field']} — {item['error']}")
continue
lines.append(
f" {item.get('id')}: {item.get('field')} "
f"recorded {item.get('recorded')!r}, compositor says {item.get('observed')!r}"
)
return lines
def render_reconcile(reply: dict[str, Any]) -> str:
"""``session reconcile``, with or without an id."""
if reply.get("id"):
return render_container(reply)
scan = reply.get("scan") or {}
lines = [
f"compositor: {'reachable' if scan.get('available') else 'unreachable'}"
+ (f" (signature {scan['signature']})" if scan.get("signature") else ""),
]
if scan.get("error"):
lines.append(f" {scan['error']}")
lines.append(f"quarantine: {_cell(scan.get('quarantine'))}")
# The scan's four lists carry different shapes -- `removed` is a list of
# output names, the others are records -- so each is rendered rather than
# printed, and `failed` is last and loudest because it is the only one that
# means the compositor and the registry are still out of step.
for item in scan.get("adopted") or []:
lines.append(f" adopted {_scan_item(item)}")
for output in scan.get("removed") or []:
lines.append(f" removed {output} (no live session claimed it)")
for item in scan.get("orphaned") or []:
lines.append(f" orphan {_scan_item(item)}")
for item in scan.get("failed") or []:
lines.append(f" FAILED {_scan_item(item)}")
lines.extend(render_diff(reply.get("diff") or []))
return "\n".join(lines)
def _scan_item(item: Any) -> str:
"""One entry of a reconcile scan list, whatever shape it has."""
if not isinstance(item, dict):
return str(item)
return " ".join(f"{key} {value}" for key, value in item.items())
def render_mode(mode: dict[str, Any] | None) -> str:
"""``WIDTHxHEIGHT``, or the gap marker for a container that has no mode.
A degraded container records ``None`` here rather than a size it never set,
so this has to be able to say so.
"""
if not mode:
return DASH
return f"{mode.get('width')}x{mode.get('height')}"
def render_bookmark(bookmark: dict[str, Any] | None) -> str:
"""Where the cursor is, in the words the wire uses (PLAN §6.3)."""
if not isinstance(bookmark, dict):
return DASH
x, y = bookmark.get("x"), bookmark.get("y")
if not isinstance(x, (int, float)) or not isinstance(y, (int, float)):
return DASH
return f"{x:.4f},{y:.4f} on {bookmark.get('output')} at {bookmark.get('at')}"
def render_pointer_state(reply: dict[str, Any]) -> str:
holder = reply.get("holder")
buttons = reply.get("buttons") or []
lines = [
f"holder {holder if holder else 'free'}",
f"lease {_cell(reply.get('lease_id'))}",
# Loud, because a button left down is the one pointer failure that keeps
# hurting after the lease is gone.
f"buttons {', '.join(buttons) if buttons else 'none down'}",
f"bookmark {render_bookmark(reply.get('bookmark'))}",
f"driver {_cell(reply.get('driver'))}",
]
return "\n".join(lines)
def render_status(session: dict[str, Any]) -> str:
@@ -148,8 +358,51 @@ def render_gc(result: dict[str, Any]) -> str:
return "\n".join(lines)
#: Error names whose failure is on the *compositor* side (exit 10), annotated
#: with what that means for the session. CONTRACT-sessions.md §4 makes the
#: distinction load-bearing — "the session is not lost, it keeps running in
#: degraded mode" — and a message that only said "error" would leave a caller
#: deciding whether to restart an application that is perfectly alive.
COMPOSITOR_ERRORS = {
"compositor": "the compositor or the output operation failed",
"compositor_unavailable": "the compositor's IPC socket could not be reached",
"no_container": "this session has no container output to aim at",
"driver_unavailable": "the pointer driver is not reachable",
"driver_refused": "the pointer driver refused the operation",
}
def render_error(reply: dict[str, Any]) -> str:
parts = [f"error: {reply.get('reason') or reply.get('error')}"]
"""The human error, saying which side of the system failed.
Three classes get a named prefix because an agent (and a person) acts
differently on each: a compositor failure leaves the application running, a
missing lease is fixed by acquiring one, and anything else is about the
session itself.
"""
error = reply.get("error") or ""
reason = reply.get("reason") or error
if error in COMPOSITOR_ERRORS:
parts = [
f"compositor error: {reason}",
f" {COMPOSITOR_ERRORS[error]}; the session itself is unaffected "
"and keeps running (exit 10, not a session failure)",
]
elif error == "no_lease":
parts = [
f"no pointer lease: {reason}",
" this session does not hold the one cursor (exit 9); acquire it "
"first with 'pointer acquire'",
]
elif error == "pointer_busy":
parts = [
f"pointer busy: {reason}",
" another session holds the one cursor (exit 8); wait for it to "
"release or for its lease to time out",
]
else:
parts = [f"error: {reason}"]
if reply.get("hint"):
parts.append(f"hint: {reply['hint']}")
return "\n".join(parts)