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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 22:54:26 +00:00
1 parent 9d33639c04
commit 887ed17be2
9 files changed
+341 -33

No files matched your search

+6 -2
View File
@@ -52,7 +52,7 @@ import the SDK:
```bash
nix develop
hhstream-mcp --list-tools # the 21 acting verbs
hhstream-mcp --list-resources # the 8 read-only URIs
hhstream-mcp --list-resources # the 10 read-only URIs
```
## The checks
@@ -68,8 +68,9 @@ hhstream-mcp --list-resources # the 8 read-only URIs
| `vm-pointer` | the **lease and the driver**: a version-2 virtual pointer, a warp that lands where it was aimed *as the application reports it*, a click delivered as one press and one release, a contended acquire refused with BUSY, an expired lease swept with its held button lifted, and a broker restart that leaves the lock free, the bookmark intact and the driver reachable | yes |
| `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads reaching a real compositor, `pointer acquire` leaving the aimed window holding the *keyboard* and not merely the cursor, and `hhs-keyboard-target` decoding `hello` from the keymap it was **forwarded** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes |
| `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes |
| `vm-stream` | the **live stream end to end**: `stream enable` on a live session mints a phrase the daemon accepts, a real HTTP viewer reads JPEGs off `/<phrase>/stream.mjpg` from *inside* the guest, `stream list` reports that viewer, the broker's idle-clock sweep stamps `touch` for it (and does not when nobody is watching), a wrong phrase 404s, and `kill` detaches the stream before the output is removed | yes |
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 21 tools and 8 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 23 tools and 10 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
All of them at once:
@@ -95,6 +96,7 @@ nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
nix build -L .#checks.x86_64-linux.vm-mcp
nix build -L .#checks.x86_64-linux.vm-stream
```
`-L` is not optional in practice: without it, Nix hides the build log, and the
@@ -262,6 +264,8 @@ checks/
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw
JSON-RPC client against the live broker
vm-stream.nix nixosTest, `session stream enable` and a real HTTP
viewer reading MJPEG from inside the guest
lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately
NOT the MCP SDK's -- the SDK on both ends would agree
with itself about a framing neither side had to get right
+53 -5
View File
@@ -35,6 +35,52 @@ hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
The socket is a plain file descriptor: the server serves every client that
connects, and keeps running when one disconnects.
## Watching a session: one port, a phrase per session
A session can publish its own screen on a web page, so a person can watch what
an agent is doing from a phone. One port for the whole machine, and a path that
is four words and a short tail:
```bash
hhstream session stream enable chromium-k3f9d2
# http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/
```
That URL is the whole interface — a browser `<img>` is the entire client, over
MJPEG — and the phrase in it is its **only** protection. No TLS, no second
factor: anyone who can reach the port and guess four words can watch. It is
never written to the audit log, and `stream list` does not print it.
Four things worth knowing before switching one on:
- **It is per session and off by default.** A session does not stream because
it exists; it streams because somebody enabled it. What is published is that
session's own container output, never the main one — the main output carries
every other session, and putting it behind one session's phrase is the
mistake this refuses to make.
- **The phrase survives a restart.** It lives in the session's record, so
somebody you read it out to keeps the URL you gave them. `disable` then
`enable` rotates it.
- **Capture runs only while somebody is connected.** An enabled stream nobody
is watching costs no `grim` and no CPU.
- **Watching counts as activity.** This is the one exception to "`touch` is the
only mark of activity": about once a minute the broker notices a connected
viewer and resets that session's idle clock, so a long job you are watching
on a phone is not reaped at three hours. An enabled stream with nobody
watching keeps nothing alive.
```nix
services.hyprland-headless-stream.sessions.stream = {
enable = true; # runs hhstream-live; turns no stream on
# bind = "0.0.0.0"; # and openFirewall, to reach it from another device
# openFirewall = true;
};
```
Loopback by default, where the path to a phone is `ssh -L 9988:127.0.0.1:9988`.
`hhstream session start <app> --stream` starts an application and prints its
URL in one go, which is the usual way an agent sets one up.
## Driving it from an agent: the MCP server
`hhstream-mcp` is the `hhstream` CLI behind a [Model Context
@@ -45,14 +91,16 @@ application without writing command lines. The interface is frozen in
It is split the way the protocol splits things:
- **Resources are the state** — eight of them, read by URI, and reading one
- **Resources are the state** — ten of them, read by URI, and reading one
changes nothing. `hhstream://status` is whether the desktop is up,
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
an application's own output, `hhstream://pointer` is who holds the input
lease, `hhstream://screen` is a frame of the screen.
- **Tools are the acts** — twenty-one, one per CLI verb that does something.
lease, `hhstream://screen` is a frame of the screen, `hhstream://streams` is
what is being published and who is watching.
- **Tools are the acts** — twenty-three, one per CLI verb that does something.
`session_start` puts an application on the screen, `pointer_acquire` takes the
input lease, `keyboard_type` types, `session_kill` ends a session.
input lease, `keyboard_type` types, `session_stream_enable` publishes the
screen for a person to watch, `session_kill` ends a session.
A host decides what state to put in front of its model; the model decides what
to do. That is the whole of the split, and it is why `shot` is still a tool
@@ -104,7 +152,7 @@ account in the group.
`hhstream-mcp --list-tools` and `--list-resources` print the two tables and
exit, which is the quickest way to check an install.
If twenty-one tools is more than a client has room for, `--toolsets` narrows
If twenty-three tools is more than a client has room for, `--toolsets` narrows
what is offered to whichever families are wanted — `frames`, `sessions`,
`pointer`, `keyboard`:
+27 -8
View File
@@ -26,9 +26,17 @@
│ hhstream-sessions.service │─────▶│ hhstream-pointer.service │
│ hhstreamd │ │ one Wayland connection │
│ registry, containers, │ JSON │ one virtual pointer │
│ the pointer lease │ over │ per output │
└────────────┬──────────────┘ a └──────────────────────────┘
│ private socket
│ the pointer lease, │ over │ per output │
│ the stream phrases │ a └──────────────────────────┘
└────────────┬────────┬─────┘ private socket
│ │ ┌──────────────────────────┐
│ └─────────────▶│ hhstream-live.service │
│ live.sock │ one port (9988) │
│ │ grim ─▶ MJPEG per │
│ │ phrase, while watched │
│ └───────────┬──────────────┘
│ │ HTTP
│ a browser ┘ /<phrase>/
│ AF_UNIX control.sock, mode 0660
▼
hhstream session ... (the CLI an agent drives)
@@ -37,12 +45,12 @@
│
┌────────────┴──────────────┐
│ hhstream-mcp │ spawned per client, stdio only
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 8 resources (the state)│
│ 23 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 10 resources (the state)│
└───────────────────────────┘
```
Five pieces, deliberately separate, and a sixth that is deliberately not a
Six pieces, deliberately separate, and a seventh that is deliberately not a
piece at all:
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
@@ -62,9 +70,20 @@ piece at all:
a separate process because a Wayland client needs its own connection and a
driver blocked on the compositor must not stall session lifecycle.
And the sixth, which is a *shim* and not a layer:
6. **The stream daemon** (`hhstream-live`) publishes one session's output as
MJPEG on one port, behind a four-word phrase, while somebody is connected.
A third executor on the pointer driver's pattern and for its reasons: `grim`
blocks tens to hundreds of milliseconds so it must not run where `touch` and
`kill` are answered, and a LAN-facing HTTP parser must not run in the frame
server whose one-socket contract cannot grow one. The broker owns the
*decision* (which session, under which phrase, in the record); the daemon
owns the port, the capture and the URL. It knows nothing about sessions or
idle clocks — it publishes what it is told to publish, and reports a viewer
count the broker chooses to read as activity.
6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
And the seventh, which is a *shim* and not a layer:
7. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
Model Context Protocol surface on it, so an agent reads state by URI and
acts by calling tools instead of writing command lines. It is drawn above
the CLI rather than beside the broker because that is where it sits: every
+59 -8
View File
@@ -1,4 +1,4 @@
# CONTRACT — the MCP server (mcp-v2)
# CONTRACT — the MCP server (mcp-v3)
This file is the interface of `hhstream-mcp`: the resource URIs, the tool names,
the arguments each takes, what comes back, and which of the CLI's exit codes
@@ -10,7 +10,19 @@ containers and the input lease).
these argument shapes is a consumer like any other, and renaming a tool breaks
it exactly as renaming a wire verb would.
Version: mcp-v2 (2026-10-11). v1 was the first freeze and lasted one day.
Version: mcp-v3 (2026-10-11). v1 was the first freeze and lasted one day; v2
split state out into resources; v3 adds the live stream. v3 is **additive** —
every v2 name still means what it meant.
v3 changes, all of them the per-session live stream
(`docs/CONTRACT-sessions.md` §4, v4):
| § | Change | Why |
| --- | --- | --- |
| §3 | Tools `session_stream_enable` and `session_stream_disable`. 21 tools became 23. | Switching a stream on is an *act*, and a consequential one: it publishes a desktop on the LAN behind a phrase. Nothing about it is a read. |
| §3 | `session_start` gains `stream`, `stream_phrase` and `stream_fps`, and its reply carries the URL. | A stream needs the container output that starting creates, so sequencing start-then-enable in the caller means every caller repeats the ordering and the half-done case. One call, one answer, and the phrase comes back with the session. |
| §4 | Resources `hhstream://streams` and `hhstream://sessions/{id}/stream`. 8 resources became 10. | What is being published, and who is watching, is state — so it is read, not called. |
| §6 | A connected viewer is the **one exception** to the idle-clock rule. | About once a minute the broker stamps `touch` on any session somebody is watching. It is not a verb and cannot be invoked; it is the broker noticing that a person is looking. |
**v2 is a breaking change, and the only one: the verbs that merely read are
resources now, not tools.**
@@ -120,7 +132,7 @@ to an argv list.
| family | tools |
| --- | --- |
| `frames` | `shot`, `record`, `run` |
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile` |
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile`, `session_stream_enable`, `session_stream_disable` |
| `pointer` | `pointer_acquire`, `pointer_move`, `pointer_click`, `pointer_scroll`, `pointer_down`, `pointer_up`, `pointer_release` |
| `keyboard` | `keyboard_type`, `keyboard_key`, `keyboard_down`, `keyboard_up` |
@@ -154,13 +166,15 @@ running.
| Tool | Arguments |
| --- | --- |
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `request_id?` |
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `stream?`, `stream_phrase?`, `stream_fps?`, `request_id?` |
| `session_touch` | `id` |
| `session_kill` | `id`, `grace?`, `signal?`, `request_id?` |
| `session_gc` | `request_id?` |
| `session_adopt` | `pid`, `app?`, `idle_timeout?`, `request_id?` |
| `session_container` | `id` |
| `session_reconcile` | `id?`, `request_id?` |
| `session_stream_enable` | `id`, `phrase?`, `fps?` |
| `session_stream_disable` | `id` |
Every one of these runs with `--json`, so what comes back is the broker's own
protocol object: in the text part verbatim, and in `structuredContent` parsed.
@@ -170,6 +184,21 @@ second wire format.
`home` and `ephemeral_home` are mutually exclusive, and the schema says so —
the CLI's argparse group, moved forward to where the refusal is free.
`session_stream_enable` returns the **URL** on the first line of its text part,
because that is the whole point of the call: it is what gets handed to a person.
It publishes the session's own container output and never the main one — that
output carries every other session, and putting it behind one session's phrase
is the mistake the broker refuses to make (exit 10 with no container). Re-enabling
returns the same URL; a different `phrase` is exit 8, not a silent rotation,
because rotating under somebody holding the old URL is the one outcome neither
answer can be mistaken for. `session_stream_disable` is marked **destructive**:
it forgets the phrase, so anyone holding that URL loses it.
`session_start` with `stream: true` is one call rather than two, and a stream
that cannot be opened **does not fail the start** — the application is on the
screen, and killing it over a web page would be the wrong trade. The reply
carries `stream_error` whenever `stream` was asked for, `null` when it worked.
`session_container` is **not** marked read-only, and that is not an oversight:
with an `id` the CLI runs `container.reconcile`, which writes the record back.
That is also why it is a tool rather than a resource. The no-id listing, which
@@ -232,6 +261,13 @@ verb a tool would have, with `--json` where the verb has it.
| `hhstream://sessions/{id}` | `application/json` — one session with its recent audit events | `?events=N` |
| `hhstream://sessions/{id}/logs` | `application/json` — the application's own captured output | `?lines=N` |
| `hhstream://outputs/{name}` | one output captured alone, as an image blob. Exactly that output's configured size, which is the coordinate space the pointer tools aim in. | — |
| `hhstream://streams` | `application/json` — every session a stream was enabled on, with its URL, rate and connected viewer count, plus `available` (whether the stream daemon answered) | — |
| `hhstream://sessions/{id}/stream` | `application/json` — one session's stream, or `null`. `attached` is separate from `enabled`, and the URL is absent rather than stale when it is false. | — |
**The URLs in those two bodies contain their phrases**, which are the only thing
protecting those streams. Both descriptions say so, because a host that puts
`hhstream://streams` into a model's context has put a credential there — and
the one place it must never go is anywhere the streamed session can see.
Rules this surface keeps:
@@ -349,13 +385,22 @@ in terms of this surface. They are on the individual tools and resources and
not only in the server instructions, because a client shows a thing's own
description at the point of use:
1. **`session_touch` is the only thing that resets a session's idle clock.**
Reading `hhstream://sessions`, `hhstream://sessions/{id}` or its logs does
not, `session_gc` does not, and neither does any pointer or keyboard tool. A
1. **`session_touch` is the only thing a *caller* can do that resets a
session's idle clock.** Reading `hhstream://sessions`,
`hhstream://sessions/{id}` or its logs does not, `session_gc` does not, the
stream tools do not, and neither does any pointer or keyboard tool. A
session being driven is still a session nobody has said they want kept. The
three resources it applies to say so in their own descriptions, because a
resources it applies to say so in their own descriptions, because a
description is what a host shows beside the thing it describes.
**The one exception is a connected viewer** (`docs/CONTRACT-sessions.md` §4,
v4): about once a minute the broker stamps `touch` on any session somebody
is watching through its live stream. It is not a tool and cannot be
invoked — it is the broker noticing that a person is looking, which is the
one form of "still wanted" that does not come down the control socket. It
cannot hold a session open by itself: an enabled stream with no viewer
captures nothing and stamps nothing.
2. **Every keyboard tool needs the pointer lease, and holds only while it
holds.** There is no keyboard lease: one compositor seat means one keyboard
focus. A held non-modifier key floods the window until it is lifted or the
@@ -376,6 +421,12 @@ socket, the CLI and the broker are stdlib-only by policy. `packages.hhstream`
must not grow that dependency; the root `pyproject.toml` excludes
`hhstream_mcp*` from its package discovery so it cannot acquire it by accident.
The stream tools and the two stream resources additionally need
`services.hyprland-headless-stream.sessions.stream.enable`, which runs the
`hhstream-live` unit and gives the broker the socket it switches streams on
over. Without it they answer exit 10 (`stream_unavailable`) — the session is
unaffected, which is what that code means.
`services.hyprland-headless-stream.mcp.enable` (default `false`) puts the
binary on the system PATH. That is the whole of the option: there is no unit, no
socket and no state directory, because the server is spawned per client over
+3 -1
View File
@@ -14,9 +14,11 @@ Each file answers three questions and stops:
| [scroll-has-no-compositor-proof](scroll-has-no-compositor-proof.md) | medium | works live; unproven in a gate |
| [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature |
| [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions |
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` |
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | partly fixed: the module passes grim's store path and a check reads real frames; the app still never checks its capture binary |
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
| [stream-does-not-reattach-after-a-broker-restart](stream-does-not-reattach-after-a-broker-restart.md) | low | the phrase survives and the sweep works; `attached` reports false until re-enabled |
| [a-stream-that-gave-up-still-reports-attached](a-stream-that-gave-up-still-reports-attached.md) | low | the other direction: a capture that permanently gave up still reads `LIVE: YES` |
Closed since this folder was written:
@@ -0,0 +1,58 @@
# 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](stream-does-not-reattach-after-a-broker-restart.md)
for the first. A field that is right only when nothing is wrong is not worth
reading.
@@ -27,6 +27,19 @@ worst way. The unit starts, the port opens, the landing page answers, and
`"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)*.
@@ -0,0 +1,66 @@
# A broker restart leaves an enabled stream recorded but not attached
## The issue
`docs/plans/2026-10-04-session-stream-webapp.md` §6 says what a restart should
do:
> If `hhstream-live` is still up, the broker asks it for the list and
> re-attaches them to the session records, so `status` and teardown still see
> them.
Stage 2 did not build that half. What happens today, measured in
`tests/sessions/unit/test_stream_verbs.py`
(`test_a_down_daemon_turns_attached_false_rather_than_failing_the_read`) and by
reading `SessionManager.startup`:
* the record keeps its phrase, so nothing is lost and a later `enable` restores
the *same* URL — which is the property §4 exists for, and it works;
* but `startup` does not call `LiveStreams.list()`, so the broker does not
learn about streams the daemon is still publishing;
* so `stream list` and `stream status` report `attached: false` for a stream
that is, in fact, up and serving. The viewer sweep then skips it, because it
only touches sessions whose phrase the daemon reports a viewer for — and it
asks `viewers`, which *would* name it. So the sweep actually still works;
what is wrong is the reporting.
The symptom is therefore narrow and confusing rather than broad: after
`systemctl restart hhstream-sessions`, somebody watching a stream keeps
watching it, the session keeps being touched, and `hhstream session stream
list` says `LIVE: NO`. An operator reading that would reasonably `enable`
again — which is harmless (`attach` is idempotent on the phrase) but should not
be necessary.
The other half of §6 *is* implemented: if the daemon restarted too, the records
keep their phrases and the streams stay off until re-enabled, because an open
port and a running capture are explicit acts.
## Ideas
1. **Ask the daemon in `startup` and merge.** *(recommended)* One
`LiveStreams.list()` where `reconcile_containers()` already runs, matching
attachments to records by phrase. Small and local: `_stream_public` already
merges an attachment into a record, so this is about *having* the
attachments at start-up rather than only at read time. The one thing to get
right is a phrase the daemon is publishing that no live record claims —
which is the stream equivalent of an orphan `hh-*` output, and should
probably be detached rather than adopted.
2. **Ask on every read instead.** `_attachments()` already does, which is why
the *reads* are nearly right. The reason it is not enough: there is no
record-side state to update, so a restart's first `stream list` is correct
and `attached` is still computed per call — this is really just (1) done
lazily, and it hides the orphan case entirely.
3. **Leave it.** What ships. The phrase survives, re-enabling is idempotent and
costs one record write, and the sweep keeps working. The cost is a status
field that lies after a restart.
## Why it matters
Low severity because nothing breaks and nothing is lost: the stream keeps
serving, the viewer keeps being counted, and the fix an operator will reach for
by instinct (`enable` again) is exactly the right one and is idempotent.
It matters at all because `attached` was added specifically so that "the
operator asked for this" and "a capture is running right now" could be told
apart — and after a restart it reports the second one wrongly, which is the one
job that field has.
+56 -9
View File
@@ -175,12 +175,54 @@ one at a time; no browser in a VM check.
3. **Port 9988**, fixed and single, no range fallback.
4. **Capture pauses at zero viewers** (v1's choice, kept).
**Stage 1 is built** (`src/hhstream_live/`, `tests/live/`, 51 unit tests): the
router, the pages, the phrase and the publisher, runnable standalone via
`hhstream-live serve --stream PHRASE=OUTPUT`. The broker verbs and
`/run/hhstream/live.sock` are Stage 2.
**Stage 1 is built** (`src/hhstream_live/`, `tests/live/`): the router, the
pages, the phrase and the publisher, runnable standalone via `hhstream-live
serve --stream PHRASE=OUTPUT`.
**Stage 3 has started, out of order and on purpose** (2026-10-11). A machine
**Stage 2 is built** (2026-10-11), and §5's surface is what shipped:
`stream.enable|disable|list|status` on the control socket, `hhstream session
stream …` on the CLI, the record field at **registry schema 4**,
`/run/hhstream/live.sock` with `hhstreamd/live.py` on the broker's end and
`hhstream_live/control.py` on the daemon's, the teardown order, and the viewer
heartbeat. `docs/CONTRACT-sessions.md` went to **sessions-v4** for it.
Two decisions §5 left open, settled in the building:
1. **`start` takes `--stream`.** A stream needs the container output that
starting creates, so "start, then enable" made every caller repeat the
ordering and the half-done case in between. One call, and the URL comes
back with the session id. A stream that cannot be opened does **not** fail
the start — the application is on the screen, and `stream_error` says what
went wrong.
2. **The default rate is the daemon's, not the broker's.** §5 did not say who
owns it, and the first cut had the broker send its own default on every
attach — which would have made `sessions.stream.fps` a setting that changed
nothing, the exact failure `--xkb-layout` exists to avoid. `fps` is now
omitted from `attach` unless a caller named one.
What Stage 2 did **not** do: `stream.enable` carries no `--port`, and §6's
restart re-attachment is not implemented. A broker restart leaves the records'
phrases intact and their streams off until re-enabled, which is §6's own
fallback ("an open port and a running capture are explicit acts") — but it does
*not* ask a surviving daemon for its list and re-attach, so `attached` reads
false until somebody enables again. Recorded in `docs/TODO/`.
**Stage 3 is built** (2026-10-11), the unit included — `hhstream-live.service`
runs the app with `--control-socket`, the module's own capture command (`grim`
is not on a unit's PATH), and `sessions.stream.{enable,fps,port,bind,openFirewall}`.
What follows is why the firewall half landed first.
The unit has to be handed two things, and both were found by
`checks/vm-stream.nix` rather than reasoned about: the capture command with
grim's store path, because a unit's `PATH` has no `grim`; and the compositor's
session — `XDG_RUNTIME_DIR` plus the `wayland-N` the compositor actually bound,
discovered at start by `execLive`. Without the second the unit was
`active (running)`, the broker attached, `stream status` said `attached: true`,
and every capture exited 1 with "XDG_RUNTIME_DIR is invalid or not set" until
the publisher gave up. Both failures are silent in the same way, which is why
the check reads JPEG bytes instead of asserting a 200.
**Stage 3 started out of order and on purpose.** A machine
had to be able to *reach* a stream before the rest of the app is settled: the
operator asked for the port to be open on the deployment machine, where the app
runs by hand, and a hand-written firewall line in one machine's config is the
@@ -189,7 +231,12 @@ openFirewall }` and the single rule it stands for are in `nix/module.nix`, with
`checks/vm-stream-firewall.nix` asking the *running* firewall — and a peer
outside the guest — whether the configured port is the one that opened.
What that does **not** do: no unit, no phrases, no `session stream
enable|disable|list|status`, and nothing in the module turns a stream on. The
app is still started by hand, and the option's whole job is to describe where a
stream will be reachable from.
At the time that did **not** include a unit, phrases or the verbs; those are
above. What is still true of it is the last sentence: nothing in the module
turns a stream *on*. `sessions.stream.enable` runs a listener serving one form,
and a stream exists only for the sessions somebody enabled it on.
**Stage 4 — the host pass — has not been done.** Nothing here has had a real
browser pointed at it; `checks/vm-stream.nix` reads the MJPEG with a
hand-rolled client inside the guest, which proves the framing and the capture
but not that a phone paints it.