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

69 lines
3.8 KiB
Markdown

# 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](a-stream-that-gave-up-still-reports-attached.md).
## 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.