integrate the session broker: one CLI, a module unit, and a VM check

M0 of the sessions design, wired into the flake and gated by a real check.

What is here now:

- `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group
  teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME.
- `src/hhstream_session/` — the CLI handlers, registered into the one front door.
- `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the
  frame verbs and the session namespace are one binary.
- `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service`
  unit: the operator's own account (never a service account, because launched
  applications should see that account's home), the compositor's group as a
  supplementary group (without it a launched GUI client cannot open the Wayland
  socket), the generated app allowlist, and `--compositor-runtime-dir` so
  applications are handed the compositor's session rather than the broker's.
- `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM.

Two bugs found by driving it, both fixed:

- BUG-01: launched applications could not reach the compositor at all — the
  broker spawned them with its own inherited environment, which names the login
  session. `hhstreamd/compositor.py` discovers the socket and builds the child
  environment; a directory with no usable socket is a startup refusal, not a
  warning.
- BUG-02: `kill` refused to signal a live application and said nothing was
  wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve`
  replaces — and on NixOS applications are reached through wrapper scripts that
  do exactly that. The gate now rests on `starttime` (+ boot id, + session id
  where it is immutable) and records command-line drift as evidence of nothing.

KillMode=process is set on the unit on purpose: the default control-group kill
would take the applications down with the broker, which would make adoption and
a broker restart pointless.
This commit is contained in:
Hermenix committed 2026-10-01 12:23:16 +00:00
1 parent 9dc9e0da9a
commit 30f456c07e
37 files changed
+9118 -1

No files matched your search

+508
View File
@@ -0,0 +1,508 @@
"""``hhstream session …`` — the CLI handlers, as a drop-in for someone else's CLI.
The integration contract is one function::
from hhstream_session import register
register(subparsers) # subparsers from argparse's add_subparsers()
...
args = parser.parse_args()
raise SystemExit(args.func(args))
``register`` adds a single ``session`` subcommand with its own verb tree, sets
``func`` (and ``hhstream_session_handler``, for hosts that dispatch on their own
attribute) to a callable taking the parsed namespace and returning an **exit
code from the frozen table** in ``DESIGN.md`` §1.6. The registrant needs to
know nothing about the daemon beyond the socket path, which comes from
``--socket`` or ``$HHSTREAM_SOCKET``.
Nothing here is imported until a ``session`` verb actually runs: the module
imports only :mod:`hhstreamd.protocol` (framing and exit codes) and the
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.
"""
from __future__ import annotations
import argparse
import sys
import time
from typing import Any, Callable
from hhstreamd.clock import format_duration, parse_duration
from hhstreamd.protocol import ExitCode
from . import format as fmt
from .client import DEFAULT_SOCKET, ENV_SOCKET, ClientError, call, reply_exit_code
__all__ = ["register", "build_parser", "dispatch", "main", "ExitCode"]
#: Printed under `session --help` and under `start --help`. It is here, in two
#: places, because it is the single fact an agent gets wrong.
ACTIVITY_NOTE = (
"ACTIVITY: 'touch' is the ONLY thing that resets a session's idle clock. "
"'list', 'status', 'logs' and 'gc' do NOT count — if polling kept sessions "
"alive, an abandoned session would never be reaped. An agent that leaves an "
"app running must call 'hhstream session touch <id>' before the idle timeout "
"expires."
)
_FOLLOW_INTERVAL_S = 0.5
# --------------------------------------------------------------------------
# registration
# --------------------------------------------------------------------------
def register(subparsers: Any, *, name: str = "session") -> argparse.ArgumentParser:
"""Add the ``session`` namespace to an existing argparse subparser set.
Returns the namespace's parser, so a host that wants to add to it can.
"""
parser = subparsers.add_parser(
name,
help="manage tracked application sessions (needs the hhstream session daemon)",
description="Start, inspect, keep alive and kill tracked application sessions.",
epilog=ACTIVITY_NOTE,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
_build_namespace(parser)
return parser
def _socket_parent() -> argparse.ArgumentParser:
"""Shared ``--socket`` so it may be given before *or* after the verb.
``SUPPRESS`` matters: without it the verb-level default would overwrite a
value given at the namespace level.
"""
common = argparse.ArgumentParser(add_help=False)
common.add_argument(
"--socket",
default=argparse.SUPPRESS,
metavar="PATH",
help=f"control socket (default: ${ENV_SOCKET} or {DEFAULT_SOCKET})",
)
return common
def _build_namespace(parser: argparse.ArgumentParser) -> None:
common = _socket_parent()
parser.add_argument(
"--socket",
default=None,
metavar="PATH",
help=f"control socket (default: ${ENV_SOCKET} or {DEFAULT_SOCKET})",
)
# `hhstream session` with no verb lists, because that is what everyone
# types first.
parser.set_defaults(func=_cmd_list, hhstream_session_handler=_cmd_list, all=False, json=False)
verbs = parser.add_subparsers(dest="session_verb", metavar="VERB")
def add(name: str, handler: Callable[[argparse.Namespace], int], **kwargs: Any):
sub = verbs.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
# ---- start -------------------------------------------------------
start = add(
"start",
_cmd_start,
help="launch an allowlisted application as a tracked session",
description=(
"Launch an allowlisted application. Prints the bare session id on "
"stdout and human-readable detail on stderr, so $(hhstream session "
"start foo) is the id and nothing else.\n\n"
"Everything after a literal -- is passed to the application as an "
"argv list: 'session start chromium -- --new-window URL'."
),
epilog=ACTIVITY_NOTE,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
start.add_argument("app", help="an app name from the daemon's allowlist, never a path")
start.add_argument(
"argv",
nargs="*",
metavar="-- ARGV...",
help="arguments for the application, after a literal --. Passed as an "
"argv list; there is never a shell.",
)
start.add_argument(
"--idle-timeout",
type=_duration,
metavar="DURATION",
help="reap the session after this long with no 'touch' (e.g. 30s, 5m, 3h)",
)
start.add_argument(
"--wait-ready",
type=_duration,
metavar="DURATION",
help="how long to wait for the app to signal readiness",
)
home = start.add_mutually_exclusive_group()
home.add_argument(
"--home", metavar="PATH", help="run the app with this HOME instead of the inherited one"
)
home.add_argument(
"--ephemeral-home",
action="store_true",
help="give the session a private HOME and delete it when the session ends "
"(opt-in; by default the app inherits the real home directory)",
)
start.add_argument(
"--request-id",
metavar="ID",
help="deduplication token: retrying a start with the same id returns the "
"original reply instead of launching a second application",
)
# ---- list --------------------------------------------------------
lst = add("list", _cmd_list, help="list sessions (does NOT count as activity)")
lst.add_argument("--all", action="store_true", help="include tombstones of ended sessions")
# ---- status ------------------------------------------------------
status = add("status", _cmd_status, help="show one session (does NOT count as activity)")
status.add_argument("id", help="session id")
status.add_argument(
"--events", type=int, default=20, metavar="N", help="recent audit events to include"
)
# ---- touch -------------------------------------------------------
add(
"touch",
_cmd_touch,
help="reset the idle clock — THE ONLY MARK OF ACTIVITY",
description=(
"Reset the session's idle clock. Injects nothing, changes nothing "
"else, and is the only verb that counts as activity: an agent "
"observing a long-running application has no other way to say "
"'still working'."
),
epilog=ACTIVITY_NOTE,
formatter_class=argparse.RawDescriptionHelpFormatter,
).add_argument("id", help="session id")
# ---- kill --------------------------------------------------------
kill = add("kill", _cmd_kill, help="terminate a session and everything it spawned")
kill.add_argument("id", help="session id")
kill.add_argument(
"--grace",
type=_duration,
metavar="DURATION",
help="how long to wait after the first signal before SIGKILL (default: the daemon's)",
)
kill.add_argument(
"--signal", default="TERM", metavar="SIG", help="first signal to send (default: TERM)"
)
kill.add_argument("--request-id", metavar="ID", help="deduplication token")
# ---- gc ----------------------------------------------------------
add(
"gc",
_cmd_gc,
help="prune tombstones and reconcile the registry with /proc "
"(does NOT count as activity)",
).add_argument("--request-id", metavar="ID", help="deduplication token")
# ---- adopt -------------------------------------------------------
adopt = add("adopt", _cmd_adopt, help="bring an already-running process under management")
adopt.add_argument("--pid", type=int, required=True, help="pid to adopt")
adopt.add_argument("--app", help="name to record (default: the executable's basename)")
adopt.add_argument("--idle-timeout", type=_duration, metavar="DURATION")
adopt.add_argument("--request-id", metavar="ID", help="deduplication token")
# ---- logs --------------------------------------------------------
logs = add(
"logs",
_cmd_logs,
help="the application's captured stdout/stderr (does NOT count as activity)",
)
logs.add_argument("id", help="session id")
logs.add_argument("--lines", type=int, default=100, metavar="N", help="tail this many lines")
logs.add_argument(
"--follow", "-f", action="store_true", help="keep printing new output until interrupted"
)
def _duration(text: str) -> float:
try:
return parse_duration(text)
except ValueError as exc:
raise argparse.ArgumentTypeError(str(exc)) from exc
# --------------------------------------------------------------------------
# handlers
# --------------------------------------------------------------------------
def _socket_of(args: argparse.Namespace) -> str | None:
return getattr(args, "socket", None)
def _request(args: argparse.Namespace, op: str, **fields: Any) -> dict[str, Any]:
return call(op, socket_path=_socket_of(args), **fields)
def _finish(args: argparse.Namespace, reply: dict[str, Any], render) -> int:
"""Print a reply and return its exit code.
Errors always go to stderr and always carry the machine field, whatever the
output mode, because that is what an agent branches on.
"""
code = reply_exit_code(reply)
if getattr(args, "json", False):
fmt.dump_json(reply, stream=sys.stdout if reply.get("ok") else sys.stderr)
elif reply.get("ok"):
text = render(reply)
if text:
print(text)
else:
print(fmt.render_error(reply), file=sys.stderr)
return int(code)
def _guard(handler: Callable[[argparse.Namespace], int]) -> Callable[[argparse.Namespace], int]:
def wrapper(args: argparse.Namespace) -> int:
try:
return handler(args)
except ClientError as exc:
if getattr(args, "json", False):
fmt.dump_json(
{"ok": False, "error": exc.error, "reason": exc.reason, "hint": exc.hint},
stream=sys.stderr,
)
else:
print(f"error: {exc.reason}", file=sys.stderr)
if exc.hint:
print(f"hint: {exc.hint}", file=sys.stderr)
return int(exc.exit_code)
except KeyboardInterrupt:
return int(ExitCode.USAGE)
wrapper.__name__ = handler.__name__
wrapper.__doc__ = handler.__doc__
return wrapper
@_guard
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 [])
reply = _request(
args,
"start",
app=args.app,
argv=argv,
idle_timeout_s=args.idle_timeout,
wait_ready_s=args.wait_ready,
home=args.home,
ephemeral_home=args.ephemeral_home or None,
request_id=args.request_id,
)
if not reply.get("ok"):
# A failed start may still have created a session (it exited at once, or
# it is slow to become ready). Print the id so it can be inspected.
if reply.get("id") and not args.json:
print(reply["id"])
return _finish(args, reply, lambda r: "")
session = reply.get("session") or {}
if args.json:
fmt.dump_json(session)
return int(ExitCode.OK)
session_id = reply.get("id") or session.get("id") or ""
# stdout is the bare id and nothing else; detail goes to stderr.
print(session_id)
print(
f"started {session.get('app')} → {session_id} "
f"(pid {session.get('pid')}, pgid {session.get('pgid')}, sid {session.get('sid')})",
file=sys.stderr,
)
print(
f"state {session.get('state')} via {session.get('ready_signal')}; "
f"idle timeout {_fmt_timeout(session.get('idle_timeout_s'))}",
file=sys.stderr,
)
print(
f"keep it alive with: hhstream session touch {session_id} "
"(the only mark of activity; list/status/logs/gc do not count)",
file=sys.stderr,
)
return int(ExitCode.OK)
def _fmt_timeout(seconds: Any) -> str:
return "disabled" if not seconds else format_duration(seconds)
@_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 []))
@_guard
def _cmd_status(args: argparse.Namespace) -> int:
reply = _request(args, "status", id=args.id, events=args.events)
return _finish(args, reply, lambda r: fmt.render_status(r.get("session") or {}))
@_guard
def _cmd_touch(args: argparse.Namespace) -> int:
reply = _request(args, "touch", id=args.id)
def render(r: dict[str, Any]) -> str:
session = r.get("session") or {}
return (
f"{session.get('id')}: idle clock reset; "
f"expires in {format_duration(session.get('expires_in_s'))}"
)
return _finish(args, reply, render)
@_guard
def _cmd_kill(args: argparse.Namespace) -> int:
reply = _request(
args,
"kill",
id=args.id,
grace_s=args.grace,
signal=args.signal,
request_id=args.request_id,
)
def render(r: dict[str, Any]) -> str:
"""Say what the daemon actually did, not merely that it finished.
The old rendering could only distinguish "signalled" from "not
signalled", and printed *the process was already gone* for both the
routine case and the case where the daemon refused to signal a live
application (BUG-02). A refusal is now an error reply and never reaches
here; what is left is reported with the signal and the process group it
went to, so "killed" cannot be read as more than it says.
"""
session = r.get("session") or {}
bits = [f"{session.get('id')}: {session.get('state')}"]
sent = session.get("signal_sent")
if sent:
bits.append(f"sent {sent} to process group {session.get('pgid')}")
if session.get("escalated_to_sigkill"):
bits.append("escalated to SIGKILL")
stragglers = session.get("stragglers") or 0
if stragglers:
bits.append(f"{stragglers} straggler(s) swept by session id")
if session.get("signalled") is False and not sent:
bits.append("nothing signalled (the process was already gone)")
survivors = session.get("survivors") or []
if survivors:
# The loudest thing this command can say: the kill did not work.
bits.append(
f"WARNING: {len(survivors)} process(es) SURVIVED "
f"({', '.join(str(p) for p in survivors)})"
)
return "; ".join(bits)
return _finish(args, reply, render)
@_guard
def _cmd_gc(args: argparse.Namespace) -> int:
reply = _request(args, "gc", request_id=args.request_id)
return _finish(args, reply, fmt.render_gc)
@_guard
def _cmd_adopt(args: argparse.Namespace) -> int:
reply = _request(
args,
"adopt",
pid=args.pid,
app=args.app,
idle_timeout_s=args.idle_timeout,
request_id=args.request_id,
)
if reply.get("ok") and not args.json:
print(reply.get("id", ""))
session = reply.get("session") or {}
print(
f"adopted pid {session.get('pid')} as {reply['id']}; "
"exit code will be unavailable (not a child of the daemon)",
file=sys.stderr,
)
return int(ExitCode.OK)
return _finish(args, reply, lambda r: "")
@_guard
def _cmd_logs(args: argparse.Namespace) -> int:
reply = _request(args, "logs", id=args.id, lines=args.lines)
if not reply.get("ok") or not args.follow:
return _finish(args, reply, lambda r: "\n".join(r.get("lines") or []))
# --follow polls from the returned offset. The daemon holds no streaming
# connection open, so a follower that dies costs the daemon nothing.
for line in reply.get("lines") or []:
print(line)
offset = reply.get("offset", 0)
try:
while True:
if reply.get("eof"):
break
time.sleep(_FOLLOW_INTERVAL_S)
reply = _request(args, "logs", id=args.id, offset=offset)
if not reply.get("ok"):
return _finish(args, reply, lambda r: "")
for line in reply.get("lines") or []:
print(line)
offset = reply.get("offset", offset)
except KeyboardInterrupt:
pass
return int(ExitCode.OK)
# --------------------------------------------------------------------------
# standalone use
# --------------------------------------------------------------------------
def build_parser(prog: str = "hhstream") -> argparse.ArgumentParser:
"""A host CLI stand-in, so the handlers can be driven without one."""
parser = argparse.ArgumentParser(prog=prog)
subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
register(subparsers)
return parser
def dispatch(args: argparse.Namespace) -> int:
"""Run the handler argparse selected. The host may call this or ``args.func``."""
handler = getattr(args, "func", None)
if handler is None:
return int(ExitCode.USAGE)
return int(handler(args))
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
if getattr(args, "command", None) is None:
parser.print_help(sys.stderr)
return int(ExitCode.USAGE)
return dispatch(args)
if __name__ == "__main__": # pragma: no cover
raise SystemExit(main())