From 336474793ff519e3b01790fb4fd65b98acd9c5d9 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sat, 3 Oct 2026 19:19:24 +0000 Subject: [PATCH] docs: the pointer is unusable while containers are off Found live while trying to demonstrate the scroll verb that was just deployed: every cursor verb resolves its target through _pointer_output, which requires a container output, and no session has one -- because containers are off. So the verb exists and cannot be used, and the acceptance video's missing cursor was never a capture artefact: nothing could have moved it. Recorded with the routes out (aim at the shared output when a session owns no container; or fix the binding first and leave this alone), the cost of the quick one, and the misleading hint that blames the compositor for a switched-off feature. --- docs/TODO/README.md | 1 + .../pointer-needs-a-container-or-a-screen.md | 64 +++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/TODO/pointer-needs-a-container-or-a-screen.md diff --git a/docs/TODO/README.md b/docs/TODO/README.md index 233a7c4..d12410f 100644 --- a/docs/TODO/README.md +++ b/docs/TODO/README.md @@ -11,6 +11,7 @@ Each file answers three questions and stops: | item | severity | state | | --- | --- | --- | | [containers-do-not-bind](containers-do-not-bind.md) | high | containers built, tested, **switched off** in production | +| [pointer-needs-a-container-or-a-screen](pointer-needs-a-container-or-a-screen.md) | high | every cursor verb refuses while containers are off — nothing can be moved | | [scroll-has-no-compositor-proof](scroll-has-no-compositor-proof.md) | medium | implemented; unit-tested; unproven against a real compositor | | [cursor-visibility-in-captures](cursor-visibility-in-captures.md) | medium | unverified — the acceptance video shows no cursor | | [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | worked around by restarting the compositor | diff --git a/docs/TODO/pointer-needs-a-container-or-a-screen.md b/docs/TODO/pointer-needs-a-container-or-a-screen.md new file mode 100644 index 0000000..477a085 --- /dev/null +++ b/docs/TODO/pointer-needs-a-container-or-a-screen.md @@ -0,0 +1,64 @@ +# The pointer is unusable whenever containers are off + +## The issue + +Every pointer verb — `acquire`, `move`, `click`, `scroll` — resolves its target +through `SessionManager._pointer_output`, which returns the session's **container +output** and refuses with `no_container` if there is none. Containers are off on +the deployment machine (see [containers-do-not-bind](containers-do-not-bind.md)), +so **no session has a container output, so no cursor can be moved at all**. + +That is why the acceptance video showed no cursor: not a capture artefact, not a +missing beat — nothing could have moved it. Verified live: + +``` +$ hhstream session pointer acquire foot-7xrsyi --json +{"ok": false, "error": "no_container", "id": "foot-7xrsyi", + "container": {"state": "degraded", "output": null, ...}, + "reason": "session foot-7xrsyi has no container output to aim at", + "hint": "the compositor was unreachable when this session started; ..."} +``` + +The refusal itself is deliberate and worth keeping: as the code says, aiming at +"wherever the cursor is" is how a click lands in another session's window. The +defect is that the refusal is **the only behaviour available in the configuration +we actually run**, and that its `hint` blames the compositor when the cause is a +switched-off feature — the same confusion the container host was fixed to avoid +at its own layer. + +## Ideas + +1. **Aim at the shared output when a session owns no container.** *(recommended)* + With containers off there is one screen, so "the session's output" is that + screen; the broker can ask the compositor which output is primary (it already + has an IPC client and a `CompositorTarget` independent of the container host) + and aim the lease at it. Small, and it restores the pre-container semantics + without weakening the refusal for the case where the compositor genuinely + cannot be reached. +2. **Fix the container binding first, then leave this alone.** The pid-join route + in `containers-do-not-bind` gives each session a real output, and the pointer's + per-session isolation comes back with it — but it is the larger change, and + until it lands the pointer stays dead. +3. **Both, in that order** — (1) to unblock the current machine, (2) as the real + fix. What (1) costs: with one shared output, the lease still serialises + *order* between sessions but can no longer prevent one session's click landing + over another's window. That is already the documented advisory state; it would + need saying out loud rather than being implied. +4. **Correct the `hint` regardless of which route is chosen.** It should name the + reason it can actually see ("this session has no container output — containers + are switched off"), because a wrong cause in an error message is worse than no + hint: it sends the reader to a compositor that was never broken. + +## Why it matters + +This is the difference between a feature that exists and one that can be used. +`scroll` was implemented, unit-tested, merged and deployed to this machine — and +it still cannot scroll anything, because the layer underneath refuses to aim. A +whole class of work (cursor movement, clicks, scrolling, the acceptance video that +depends on them) is blocked by a configuration choice made for an unrelated +reason, and the error message points at the wrong suspect. + +It is also a reminder about the shape of this system: the pointer, the +containers and the compositor are one dependency chain, and the part that was +switched off is upstream of the part being demonstrated. Anything verified only +in the enabled configuration says nothing about the one that runs.