`docs/CONTRACT-mcp.md` goes to mcp-v3 with a change table: two tools, two resources, three `session_start` arguments, and the one rule that is not a name at all -- a connected viewer is the single exception to the idle-clock rule, and it cannot be invoked, so it is documented in §6 rather than offered in §3. v3 is additive; every v2 name still means what it meant. README.md leads the stream with the shape of it rather than the options: one port for the machine, a phrase per session, a browser `<img>` as the entire client, and the four things worth knowing before switching one on -- that it is per session and off by default, that the phrase survives a restart, that capture runs only while somebody is connected, and that watching counts as activity. The phrase is called what it is: the only protection, with no TLS and no second factor. ARCHITECTURE.md gains the fourth unit as a seventh box -- `hhstream-live`, hanging off the broker by `live.sock` with one port and a browser at the end of it -- and the counts move to 23 and 10. Two TODOs, both written by `checks/vm-stream.nix`: * `a-stream-that-gave-up-still-reports-attached.md`. The publisher stops a stream after ten consecutive capture failures and the stop is sticky on purpose, but `Control._describe` does not pass `stopped` on, so `_stream_public` reports `attached: true` for a capture that has permanently given up. That is the second place `attached` answers "is a capture running right now" wrongly, and a field that is right only when nothing is wrong is not worth reading. * `capture-binary-and-the-unit-path.md` is now half fixed, and says so. The module passes grim's store path and this check reads real frames -- which immediately found the sibling fault, the unit's missing `XDG_RUNTIME_DIR`. What is still open is the other half: the app resolves its capture command by name and never checks it, so any deployment that is not this module still discovers a broken capture ten failures later. The plan's status section records Stage 2 and Stage 3 as built, the two decisions §5 left open (that `start` takes `--stream`, and that the default rate is the daemon's), and what Stage 2 deliberately did not do -- §6's restart re-attachment, which has its own TODO. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
3.1 KiB
A stream whose capture gave up still reports attached: true
The issue
hhstream_live.publisher stops a stream after FAILURE_LIMIT (10) consecutive
capture failures, and the stop is sticky on purpose — the case it guards is an
output that was removed, and that does not come back. The stream object stays in
StreamRegistry with stopped = True; the HTTP handler returns as soon as it
notices, so viewers are dropped and new ones get a page that ends immediately.
Nothing on the broker side can see that. Control._describe returns
spec.public() plus url and viewers — not stopped, captured,
failures or last_frame_age_s, all of which Stream.status() already
computes. So LiveStreams.list() reports the phrase, _attachments() finds it
and _stream_public sets attached = True. hhstream session stream status
says LIVE: YES for a capture that has permanently given up.
MEASURED, in checks/vm-stream.nix, by the bug that check found: the
hhstream-live unit had the compositor's group but not its environment, so
every grim exited 1 with
error: XDG_RUNTIME_DIR is invalid or not set in the environment.
The unit was active (running), the broker's record was intact, stream status
said attached: true with a URL, and the only place the truth appeared was a
single WARNING in the daemon's journal. The environment bug is fixed
(execLive in nix/module.nix); the reporting gap it exposed is not.
Ideas
- Carry the publisher's health through
list. (recommended) Addstoppedandlast_frame_age_stoControl._describe— both already exist onStream.status()— parse them inhhstreamd.live.Attachment, and have_stream_publicreportattached: false(or a third state) when the daemon says the capture is dead. The cost is one more field pair in CONTRACT-sessions.md §3.5 and arender_streamline; the gain is thatattachedmeans what it was added to mean. - Drop a stopped stream from the registry. Then
liststops naming it andattachedgoes false for free, with no new fields. Rejected as the first move because it destroys the evidence:failuresand the phrase are what an operator needs in order to understand what happened, and a 404 on the URL reads as "wrong phrase". - Leave it. What ships.
stream disablethenstream enablerevives it (a freshStream, same phrase, same URL), which is what an operator reaches for anyway, and the daemon's journal does say what happened.
Why it matters
Low severity because the capture only gives up for a reason that is itself a
failure — a removed output, a compositor that went away, a misconfigured unit —
and in two of those three the session is in trouble in ways status does show.
It matters because attached exists specifically to separate "the operator
asked for this" from "a capture is running right now" (CONTRACT-sessions.md
§3.5), and this is the second case where it answers the second question wrongly;
see stream-does-not-reattach-after-a-broker-restart
for the first. A field that is right only when nothing is wrong is not worth
reading.