Files
hyprland-headless-stream-pl…/docs/TODO
HermenixandClaude Opus 5 887ed17be2 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
2026-10-11 22:54:26 +00:00
..

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
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.