`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
37 lines
2.2 KiB
Markdown
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.
|