Merge feat/mcp-server (9708154) into feat/mcp-auth

The base branch moved twelve commits while this work was in flight --
including the per-session live stream and its own contract bump -- so this
integrates rather than leaving a PR nobody can merge.  Six files
conflicted; the interesting resolutions are the two that were not
textual.

**The contract is mcp-v3.1, not v2.1.**  This branch bumped v2 -> v2.1 for
an additive change; `feat/mcp-server` bumped v2 -> v3 for the live stream,
also additive.  Both point releases, both correct, and they cannot both be
the same document.  So v3 stands as written and the HTTP transport is the
point release on top of it, by the same rule each of us applied
independently: v2 is still the only major bump, because it is still the
only one that removed anything.

**The counts are no longer literals.**  This branch asserted `21 tools` and
`5 resources` in `checks/vm-mcp-http.nix` and `5` in `test_mcp_http.py`;
the stream added two tools and one fixed resource, so the surface is 23
and 6.  Rather than re-hardcode numbers that will go stale again, the
check now counts against `--list-tools` and `--list-resources` -- the
server's own table -- and the unit test against `resources.FIXED`.  That
is the lesson 9708154 ("count the unnarrowed resources against the
listing, not a literal") had already learned on the other side of this
merge, arrived at twice.  A stale number here would have failed in a way
indistinguishable from the HTTP transport dropping tools, which is the
one thing those subtests exist to catch.

The rest were additive on both sides and both halves are kept: the TODO
table, the checks wiring, the README check rows, the architecture diagram
(their 23/10 counts with this branch's two-transport annotation).
`nix/module.nix` needed reconstructing -- git interleaved the bodies of
`hhstream-live` and `hhstream-mcp` because both units land between the
same surrounding lines -- so the live unit is taken verbatim and the MCP
unit placed after it, with this branch's options, tmpfiles entry,
firewall rule, two assertions and two warnings re-applied on top.

One thing deliberately NOT touched: the v3 change table cites `§6` for the
idle-clock exception, but the rule it means is `§8`. That is the other
branch's prose and its author's call, not something to quietly rewrite in
a merge.

Verified after resolution: 394 unit tests pass, and the module evaluates
with both units, the right ExecStart, one firewall port and both
warnings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-12 00:47:14 +00:00
commit f83717ba71
37 files changed
+4241 -101

No files matched your search

+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` |
| [mcp-http-auth-is-not-oauth](mcp-http-auth-is-not-oauth.md) | medium | a static bearer token, not OAuth 2.1 + RFC 9728: the cost is which clients can connect, not how exposed the desktop is |
| [mcp-tokens-do-not-scope-resources](mcp-tokens-do-not-scope-resources.md) | medium | `token mint --toolsets frames` narrows the tools and not the eight resources; nothing until a second token is minted for someone else |
@@ -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.