The contract said "stdio, and only stdio" and now describes two transports, so it gets a version -- **v4**, because v3 (the live stream) was published to main while this branch was in review. Nothing here breaks: no tool renamed, no argument reshaped, no resource moved, so a client written against v2 over stdio still works unchanged. v2 is the only bump that took something away, and it took away five tools; v3 and v4 are additive. §1 is rewritten around the asymmetry rather than around the feature, because the asymmetry is the part that is easy to get wrong later: stdio is unauthenticated **on purpose** and that is now written down with its argument, so the next reader does not "fix" it. A stdio client spawns the server, so it has already passed a filesystem permission check and holds the broker's 0660 control socket either way -- unix permissions are the gate, exactly as `mcp.enable`'s own option text has always said. A port is the first time the caller passed neither, which is the entire reason the token exists. §2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`: that directory is 0700 owned by the broker's user and holds the audit trail), the `serve --http` flags, and the `token` verbs with the three decisions behind them -- digests not tokens, wall-clock expiry where every broker deadline is BOOTTIME, and a flock because two processes write the table. §3 records that a token's toolsets intersect the server's and cannot widen them. §10 is new and is the part worth having: **what this is not.** Not OAuth 2.1, not RFC 9728, no metadata discovery -- so a client that can only *discover* an authorization server will not connect, and one that lets you set a header will. And a token narrows tools but not resources, so a `frames` token can still read `hhstream://sessions`. Both are now TODO files with their own evidence and recommended routes, beside the two limits the SDK imposes: * `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about interoperability rather than exposure. Nothing is weaker than it claims; what is missing is the part that lets a client somebody else configured connect without a human pasting a header. It records that `ssh host hhstream-mcp` is genuinely the better answer for one operator with one machine, because that is what this competes with. * `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all until a second token is minted for someone else, at which point the restriction is narrower than it reads. README gains the HTTP section with the three things to know before enabling it (the unit's refusal and self-heal, no TLS, not OAuth); README.dev gains the token commands in the dev-shell walkthrough and the new check's row; ARCHITECTURE gains the two transports in its diagram and the reason the shim has a state directory while owning no state about the desktop. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
TODO
Known, unfixed problems — each one real, none of them guessed at.
Each file answers three questions and stops:
- The issue — what is actually wrong, with the evidence for it.
- Ideas — more than one, and which one is the recommended route.
- Why it matters — the impact, not the principle.
| item | severity | state |
|---|---|---|
| cursor-visibility-in-captures | high | answered: the compositor draws no cursor for a virtual pointer. Needs a decision on an overlay marker |
| scroll-has-no-compositor-proof | medium | works live; unproven in a gate |
| reconcile-while-containers-are-off | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature |
| kill-can-leave-the-app-alive | medium | found by counting windows, not sessions |
| capture-binary-and-the-unit-path | 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 | medium | two costs of running the CLI in process: no killable deadline, and no sg recovery |
| mcp-resources-cannot-be-subscribed-to | medium | the SDK hardcodes subscribe=False, so a log resource can only be re-read |
| mcp-http-auth-is-not-oauth | 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 | medium | token mint --toolsets frames narrows the tools and not the ten resources; nothing until a second token is minted for someone else |
| stream-does-not-reattach-after-a-broker-restart | low | the phrase survives and the sweep works; attached reports false until re-enabled |
| a-stream-that-gave-up-still-reports-attached | low | the other direction: a capture that permanently gave up still reads LIVE: YES |
Closed since this folder was written:
- "Containers do not bind" — fixed. Windows are assigned by the pid the compositor reports, moved onto their desk's workspace and read back. Two sessions now hold two outputs with a real browser on each.
- "The pointer is unusable while containers are off" — fixed with it. The pointer aims at the session's desk, and desks hold applications.
- "Discovery refuses when two compositor instances exist" — fixed. Each candidate is asked for its version and the one that answers is used.
Severity here means "how much of the feature is actually delivered", not "how loud the failure is". The highest is highest because a whole class of work is blocked on it: the pointer is exact and invisible, so nothing can show where anything happened.
When one of these is fixed, delete its file and the row — this folder is a list of what is still true, not a history of what was thought.