Files
hyprland-headless-stream-pl…/docs/TODO/README.md
T
HermenixandClaude Opus 5 6a40c7e2e4 docs(mcp): freeze the tool surface, and record what the in-process seam costs
`docs/CONTRACT-mcp.md` (mcp-v1) is the new interface, written the way this
repository writes interfaces: the tool names, the arguments each takes, the
flag form, what is deliberately absent and why, and a row per exit code saying
what it arrives as and what an agent should do about it. An agent that has
learned these names is a consumer like any other, so renaming one needs a
version bump.

README.md gains the section an operator reads: the `mcp.enable` option, the
`mcpServers` block to register it with, why both environment variables are
shown at their defaults, and what to do when `shot` cannot read the frame
socket. README.dev.md gains the `nix build .#hhstream-mcp` half of the build
section, the `vm-mcp` row, the new files in the layout, and the reason `mcp` is
in the unit check's environment. ARCHITECTURE.md gains the sixth box, drawn
above the CLI rather than beside the broker, because that is where it sits.

`docs/TODO/mcp-in-process-has-no-call-deadline.md` records the two things the
in-process seam costs, rather than leaving them to be rediscovered. A thread
cannot be interrupted, so there is no per-call deadline and a wedged call
queues every later one behind it; and `cli.main`'s `sg` re-exec is an `exec`
this server cannot perform, so a frame verb that cannot read the socket fails
where the CLI would have recovered. The second is the one an operator meets
first -- the CLI works from their shell and the tool does not -- which is why
the failure says what the CLI would have done and how to not need it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:33:07 +00:00

37 lines
2.2 KiB
Markdown

# 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](cursor-visibility-in-captures.md) | high | answered: the compositor draws no cursor for a virtual pointer. Needs a decision on an overlay marker |
| [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` |
| [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 |
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.