Files
hyprland-headless-stream-pl…/docs/TODO/capture-binary-and-the-unit-path.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.8 KiB

The capture command needs an absolute path under a unit

The issue

hhstream-live runs its capture command (grim -c -t jpeg -q 80 -o <output> -) by name, from the PATH it inherits. Under systemd that path is /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin — the system profile is deliberately not on it — so the capture fails, ten times, and the stream gives up:

WARNING hhstream.live: stream on hh-chromium-yhvpms: giving up after 10
consecutive capture failures: capture command ['grim', '-c', '-t', 'jpeg',
'-q', '80', '-o', 'hh-chromium-yhvpms', '-'] could not be run:
[Errno 2] No such file or directory: 'grim'

Measured on 2026-10-11 on the deployment machine, the first time the app was run as a unit rather than from a login shell. A login shell has /run/current-system/sw/bin on its PATH, which is why every run before this one — the stage-1 work, the standalone serve --stream runs, the whole test suite — never saw it.

What makes it worth a file rather than a line: the failure is quiet in the worst way. The unit starts, the port opens, the landing page answers, and status.json reports a stream that is simply "stopped": true with "failures": 10. A viewer sees an empty frame area and nothing else says why. Only the unit's log names the reason, one line above the giving-up entry.

Half of this is now fixed. The module passes grim's absolute store path (idea 1), checks/vm-stream.nix starts the unit and reads real JPEGs off the stream — the check this file asked for — and that check immediately found the sibling fault: the unit had the compositor's group but not its environment, so grim exited 1 with "XDG_RUNTIME_DIR is invalid or not set", ten times, with the same silence. Fixed too (execLive). What is still open is idea 2: the app resolves its capture command by name and never checks it, so a standalone hhstream-live serve and any deployment shape that is not this module still discover a missing or unusable capture binary ten failures later. The quiet half — a stream that gave up while the broker still reports it attached — has its own file now: a-stream-that-gave-up-still-reports-attached.

Ideas

  1. An absolute binary, as the module already does elsewhere (recommended). sessions.apps requires an absolute store path for exactly this reason — "a unit's default PATH does not include the system profile", which is why the allowlist spells foot as ${pkgs.foot}/bin/foot. The stream's unit should not inherit grim by name either: pass ${pkgs.grim}/bin/grim as the capture command from the module (or set PATH on the unit, which is what made it work on the deployment machine). The absolute path is also the stronger control: it names one exact binary instead of whatever PATH resolves to at the moment the unit starts.
  2. Resolve early and fail loudly. Have the app resolve the binary itself at start-up and refuse to serve with a named error (capture_binary_missing) if it is not there. A unit that dies at start is a five-second diagnosis; a unit that serves an empty frame is an afternoon.
  3. Both. The module passes the absolute path and the app checks it once at start-up: the first is the fix, the second is what catches the next deployment shape nobody has thought of yet.

Why it matters

Stage 3's unit is the point at which running under systemd stops being an experiment and becomes the only path every deployment takes — and a stream that answers, reports a healthy port, and shows nothing is a worse failure than one that does not start. Whichever idea is taken, the check for it belongs in the same stage as the unit: a vm-* check that starts the unit and reads one frame would have caught this on the day it was written.