`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
69 lines
3.8 KiB
Markdown
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. |