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())
+9
View File
@@ -0,0 +1,9 @@
"""``python -m hhstream_session`` — drive the handlers without a host CLI.
The real integration is :func:`hhstream_session.register`; this exists so the
verbs can be exercised (and tested) standalone.
"""
from . import main
raise SystemExit(main())
+109
View File
@@ -0,0 +1,109 @@
"""The control-socket client (DESIGN.md §1.6, §10).
Blocking, stdlib sockets, one request per connection. **One connect attempt,
then exit 5** — a CLI that silently retries hides a down daemon, and the hint
tells the operator where to look.
"""
from __future__ import annotations
import os
import socket
from typing import Any
from hhstreamd import protocol
from hhstreamd.protocol import ExitCode, exit_code_for
DEFAULT_SOCKET = "/run/hhstream/control.sock"
ENV_SOCKET = "HHSTREAM_SOCKET"
#: How long to wait for the daemon to answer. The daemon's own per-request
#: deadline is shorter for every verb except `kill` and `start`, which are
#: allowed their grace and readiness budgets, so this is a backstop.
DEFAULT_TIMEOUT_S = 60.0
class ClientError(Exception):
"""A failure that never reached the daemon's dispatch."""
def __init__(self, error: str, reason: str, hint: str | None = None) -> None:
super().__init__(reason)
self.error = error
self.reason = reason
self.hint = hint
@property
def exit_code(self) -> ExitCode:
return exit_code_for(self.error)
def default_socket_path() -> str:
return os.environ.get(ENV_SOCKET, DEFAULT_SOCKET)
def call(
op: str,
*,
socket_path: str | None = None,
timeout: float = DEFAULT_TIMEOUT_S,
**fields: Any,
) -> dict[str, Any]:
"""Send one request, return the decoded reply.
Raises :class:`ClientError` with ``daemon_unreachable`` (exit 5) if the
socket cannot be reached, and ``timeout`` (exit 7) if the daemon accepts the
request but never answers.
"""
path = socket_path or default_socket_path()
message = protocol.request(op, **fields)
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.settimeout(timeout)
try:
try:
sock.connect(path)
except (FileNotFoundError, ConnectionRefusedError, PermissionError, OSError) as exc:
raise ClientError(
"daemon_unreachable",
f"cannot reach the hhstream session daemon at {path}: {exc}",
hint="is hhstreamd running? (it is an ordinary process; check "
"however you supervise it)",
) from exc
try:
sock.sendall(protocol.encode(message))
buffer = bytearray()
while b"\n" not in buffer:
chunk = sock.recv(65536)
if not chunk:
break
buffer.extend(chunk)
if len(buffer) > protocol.MAX_LINE_BYTES:
raise ClientError("bad_request", "reply exceeds the frame limit")
except TimeoutError as exc:
raise ClientError(
"timeout", f"the daemon did not answer {op!r} within {timeout:g}s"
) from exc
except OSError as exc:
raise ClientError("daemon_unreachable", f"control socket error: {exc}") from exc
finally:
sock.close()
if not buffer.strip():
raise ClientError("daemon_unreachable", "the daemon closed the connection without replying")
try:
return protocol.decode(bytes(buffer))
except protocol.ProtocolError as exc:
raise ClientError(exc.error, f"malformed reply from the daemon: {exc.reason}") from exc
def reply_exit_code(reply: dict[str, Any]) -> ExitCode:
"""The frozen exit code for a decoded reply.
A reply that is not ``ok`` never yields 0, even if it carries no error name
the table knows: reporting success for an unexplained failure is the one
mistake an agent cannot recover from.
"""
if reply.get("ok"):
return ExitCode.OK
return exit_code_for(reply.get("error") or "bad_state")
+155
View File
@@ -0,0 +1,155 @@
"""Rendering for the human views.
``--json`` output is the protocol's own objects, unmodified: a flag that
reshapes the data would mean two contracts to keep in step. The tables below
are for people.
"""
from __future__ import annotations
import json
import sys
from typing import Any
from hhstreamd.clock import format_duration
DASH = "—"
def dump_json(obj: Any, stream=None) -> None:
print(json.dumps(obj, indent=2, sort_keys=True), file=stream or sys.stdout)
def _cell(value: Any) -> str:
return DASH if value is None else str(value)
def render_table(rows: list[list[str]], headers: list[str]) -> str:
widths = [len(h) for h in headers]
for row in rows:
for i, cell in enumerate(row):
widths[i] = max(widths[i], len(cell))
out = [" ".join(h.ljust(widths[i]) for i, h in enumerate(headers)).rstrip()]
for row in rows:
out.append(" ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
return "\n".join(out)
def render_list(sessions: list[dict[str, Any]]) -> 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.
"""
if not sessions:
return "no sessions"
rows = []
for s in sessions:
live = s.get("live")
if live:
idle = format_duration(s.get("idle_s"))
expires = format_duration(s.get("expires_in_s"))
if s.get("expires_in_s") is None:
expires = "never"
else:
idle = DASH
left = s.get("tombstone_expires_in_s")
expires = f"(tombstone, {format_duration(left)} left)" if left is not None else DASH
rows.append(
[
_cell(s.get("id")),
_cell(s.get("app")),
_cell(s.get("state")),
_cell(s.get("pid")) if live else DASH,
idle,
expires,
]
)
return render_table(rows, ["ID", "APP", "STATE", "PID", "IDLE", "EXPIRES IN"])
def render_status(session: dict[str, Any]) -> str:
live = session.get("live")
lines = [
f"{session.get('id')} ({session.get('app')})",
f" state {session.get('state')}"
+ (f" [{session.get('last_error')}]" if session.get("last_error") else ""),
f" pid {_cell(session.get('pid'))} pgid {_cell(session.get('pgid'))}"
f" sid {_cell(session.get('sid'))}",
f" argv {' '.join(session.get('argv') or []) or DASH}",
f" home {_cell(session.get('home'))}",
f" created {_cell(session.get('created_at'))}",
f" last activity {_cell(session.get('last_activity_at'))}"
f" ({session.get('command_count', 0)} command(s) counted)",
f" idle {format_duration(session.get('idle_s'))}"
f" of {format_duration(session.get('idle_timeout_s'))}",
f" expires in {format_duration(session.get('expires_in_s'))}"
if session.get("expires_in_s") is not None
else " expires in never (idle timeout disabled)",
f" ready signal {_cell(session.get('ready_signal'))}",
f" adopted {session.get('adopted')}",
]
if not live:
lines.append(
f" exit code {_cell(session.get('exit_code'))}"
f" detected by {_cell(session.get('exit_detected_by'))}"
)
if session.get("exit_detected_by") in ("pidfd", "proc_poll", "proc_check"):
lines.append(" exit code unavailable (adopted process)")
compositor = session.get("compositor") or {}
lines.append(
f" window {_cell(compositor.get('window'))}"
f" workspace {_cell(compositor.get('workspace'))}"
f" foreground {_cell(compositor.get('foreground'))}"
)
if compositor.get("note"):
lines.append(f" {compositor['note']}")
events = session.get("events") or []
if events:
lines.append(" recent events")
for event in events[-20:]:
lines.append(f" {event.get('ts')} {event.get('event')}")
return "\n".join(lines)
def render_gc(result: dict[str, Any]) -> str:
lines = [
f"pruned {result.get('pruned', 0)} tombstone(s), "
f"reconciled {len(result.get('reconciled') or [])} session(s)",
f"{result.get('live', 0)} live, {result.get('tombstones', 0)} tombstone(s) remain",
]
for item in result.get("reconciled") or []:
lines.append(f" {item['id']}: {item['why']}")
unresolved = result.get("unresolved") or []
if unresolved:
# Not a routine exit: the daemon could not establish whether these pids
# are still their sessions', so it signalled nothing. Said loudly
# because the application may well still be running (BUG-02 item 5).
lines.append(
"UNRESOLVED — identity could not be established, nothing was signalled:"
)
for item in unresolved:
mismatched = ", ".join(item.get("mismatched") or []) or "no usable evidence"
lines.append(f" {item['id']}: {item['why']} ({mismatched})")
orphans = result.get("orphans") or []
if orphans:
lines.append("orphaned processes (escaped the process group AND the session id):")
for item in orphans:
lines.append(f" {item['id']} sid {item['sid']}: pids {item['pids']}")
return "\n".join(lines)
def render_error(reply: dict[str, Any]) -> str:
parts = [f"error: {reply.get('reason') or reply.get('error')}"]
if reply.get("hint"):
parts.append(f"hint: {reply['hint']}")
return "\n".join(parts)