`docs/CONTRACT-sessions.md` goes to sessions-v4 with a change table at the top,
for the reason mcp-v2 got one: everything in it is an addition, and a reader who
learned v3 should be told what moved rather than diff it.
The new §3.5 is the interface that needed freezing most, because it is the only
one in this build that two *processes* have to agree on: `/run/hhstream/live.sock`,
`LiveStreams.attach/detach/list/viewers`, the four JSON ops on the wire, and the
`Attachment` the broker gets back. Its shape is §3.4's deliberately -- the broker
holds the decision (which session streams, under which phrase), the daemon holds
the capture -- so a reader who knows the pointer driver already knows this.
Four rules in §3.5 are written out because each one is a thing a reasonable
implementation would get wrong:
* the daemon holds no session state and no idle clock; `viewers` is a reading,
and what the broker does with it is the broker's;
* `fps` is optional and omitting it is normal -- the default is the daemon's,
from its own unit's argv, for the same reason the port is. A broker that sent
its own default on every attach would turn `sessions.stream.fps` into a
setting that changed nothing, which is the failure `--xkb-layout` exists to
avoid;
* `attach` is idempotent on the phrase, so a re-`enable` after a broker restart
does not double the `grim` rate on one output;
* the phrase is never logged by either side. It is the stream's only credential.
§4 gains four verbs, the three `start` arguments, and the one genuinely new rule
in this version: **a connected viewer is activity**. That is the first exception
to "`touch` is the only mark of activity" since that rule was written, and it is
there for one failure -- an operator watching a long job on his phone, saying
nothing to the broker, and losing the session at three hours *because* watching
was all he was doing. It cannot hold a session open by itself: an enabled stream
with no viewer runs no `grim` and stamps nothing.
No new exit numbers. The three error names map onto codes the frozen table
already has (`stream_unavailable` -> 10, `stream_busy` -> 8, `stream_budget` ->
6), because no new *kind* of failure appeared: no container output is a
compositor-side failure, a phrase collision is a busy, a viewer cap is a budget.
§6 records schema 3 -> 4 (the record gains `stream`, older records migrate to
`null`), and §5 names the socket, the unit and port 9988 beside the other frozen
paths.
What v4 deliberately withholds from the broker is the port, the bind address and
the capture command. The broker learns the URL prefix *from* the daemon, in the
`attach` reply -- a URL it assembled itself from a port it was told about once
is a URL that lies the first time an operator moves the listener.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE