Found on the deployment machine on 2026-10-11, the first time `hhstream-live` was run **as a unit** rather than from a login shell: a systemd unit's PATH has no system profile, so the capture command `grim` is not found, ten times, and the stream gives up. It answers on its port, serves the landing page and reports `"stopped": true, "failures": 10` while showing nothing -- the quiet half of the failure is what makes it worth a file. The module already solves this for `sessions.apps` by requiring an absolute store path; the stream's unit has to do the same (or set PATH, which is what made the deployment run work). Recorded in `docs/TODO/` with the two fixes, and named as a risk on stage 3 of the plan, which is the stage that turns this from an experiment into the only path.
2.9 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.
Ideas
- An absolute binary, as the module already does elsewhere (recommended).
sessions.appsrequires an absolute store path for exactly this reason — "a unit's defaultPATHdoes not include the system profile", which is why the allowlist spellsfootas${pkgs.foot}/bin/foot. The stream's unit should not inheritgrimby name either: pass${pkgs.grim}/bin/grimas the capture command from the module (or setPATHon 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 whateverPATHresolves to at the moment the unit starts. - 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. - 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.