Files
hyprland-headless-stream-pl…/docs/TODO/a-stream-that-gave-up-still-reports-attached.md
T
HermenixandClaude Opus 5 887ed17be2 docs(stream): mcp-v3, the seventh box, and two TODOs the check wrote
`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
2026-10-11 22:54:26 +00:00

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

  1. Carry the publisher's health through list. (recommended) Add stopped and last_frame_age_s to Control._describe — both already exist on Stream.status() — parse them in hhstreamd.live.Attachment, and have _stream_public report attached: 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 a render_stream line; the gain is that attached means what it was added to mean.
  2. Drop a stopped stream from the registry. Then list stops naming it and attached goes false for free, with no new fields. Rejected as the first move because it destroys the evidence: failures and the phrase are what an operator needs in order to understand what happened, and a 404 on the URL reads as "wrong phrase".
  3. Leave it. What ships. stream disable then stream enable revives it (a fresh Stream, 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.