docs: two TODO items closed, and the cursor question answered

Closed: containers-do-not-bind and pointer-needs-a-container-or-a-screen. Both
were the same defect seen from two sides, and both are fixed by assigning
windows by pid -- two sessions now hold two outputs with a real browser on each,
and the pointer aims at a desk that has something in it.

The cursor item is rewritten with the answer rather than the speculation: the
compositor draws no cursor image for a virtual pointer, so no capture setting
can make one appear. The evidence is in the file, including the three wrong
answers that came before it and the boring measurement that settled it.

New item: killing a session left two browsers alive, found by counting windows
rather than sessions.
This commit is contained in:
Hermenix committed 2026-10-03 19:45:42 +00:00
1 parent acdfb2801e
commit cbf58f6443
5 files changed
+103 -175

No files matched your search

+18 -9
View File
@@ -10,16 +10,25 @@ 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 |
| [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 |
Severity here means "how much of the feature is actually delivered", not
"how loud the failure is". The high one is high because a working feature is
turned off; the others are medium because they are gaps in proof, where the
symptom of a real fault and the symptom of a working thing look identical.
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.
-60
View File
@@ -1,60 +0,0 @@
# Containers are built, tested, and switched off
## The issue
A session can be given its own container — its own headless output and a
numbered workspace — but **no window can be assigned to it**.
The broker stamps an identity on each session's app and matches a windowrule on
`match:initial_class`, on the assumption that an allowlisted app will carry that
stamp. None of them does: chromium reaches the compositor through a wrapper
script whose flags do not set a per-session class, and `foot` has no such
option. Every allowlisted app therefore lands in the *base* class set, the
broker judges it foreign to every container, and quarantines it.
The consequence is that enabling containers makes sessions unusable — which is
how this was found: not in tests, but live, immediately after the first switch
that enabled them. Containers are now off
(`containers_enabled = false`), and every session reports
`container: {state: "degraded", output: null}`, deliberately, so a disabled
machine cannot be mistaken for one whose compositor is down.
## Ideas
0. **This is already recorded from the other side**, in `README.dev.md` item 4:
a window rule only binds for an application that reads the environment, and
the fix proposed there is a per-app `--app-id` in the allowlist — a policy
change. Idea 1 below sidesteps the question instead of answering it, because
it needs nothing from the application at all.
1. **Adopt windows by the pid the compositor already reports.** *(recommended)*
`hyprctl clients -j` gives each client's pid, and the broker already knows each
session's pid — so the join is a lookup, and **no app has to take part**. No
stamp, no per-app flags, and it works for programs that will never co-operate.
It must use `(pid, starttime)` rather than pid alone, because the wrapper
replaces its own argv and that is exactly the pid-reuse confusion already
fixed once in `procmon`.
2. **Per-app identity argument, where one exists.** chromium accepts
`--class=hh-<id>`, so the wrapper could pass the session's value. Cheap for
chromium, and dead weight for every other app: it makes the allowlist a list of
apps that cooperate.
3. **Keep the stamp, set it in each wrapper.** Same shape as (2), more moving
parts, same ceiling.
4. **Hybrid: pid first, stamp as a fallback.** Only worth it if some app reports
no pid at all; the compositor's `-1` sentinel for "absent pid" already covers
the reporting side.
## Why it matters
The isolation milestone does not deliver while this is open. Sessions still
share one output and tile over each other on the same screen — two concurrent
sessions are both `ready` and both visible at once. Per-session ownership today
is bookkeeping only: a runtime directory, an idle clock, captured output, an
audit trail.
So the difference between what the design claims ("a session owns a workspace")
and what the machine does ("a session is an app on a shared screen") is entirely
this one join. And note which failure mode to expect on the way: the *first*
half of the feature — creating outputs and workspaces — worked on the first
attempt and looked fine right up until an app was put in one. A green container
test proves the compositor accepted the commands, not that anything arrived.
+43 -42
View File
@@ -1,53 +1,54 @@
# The cursor may not appear in captures at all
# The compositor draws no cursor for a virtual pointer
## The issue
## The issue — answered, and it is not a capture setting
The acceptance video shows the browser searching, opening listings in separate
tabs, and a terminal running cowsay — and **no cursor anywhere**. Two candidate
causes, and they are not exclusive:
The pointer moves exactly where it is told, and **nothing is drawn**. Every
plausible cause was eliminated by test rather than by argument:
1. **The demo never moved it.** The browser beats were driven over Chromium's
CDP HTTP endpoints (`/json/new`, `/json/activate`, navigation), which inject
no pointer input at all. Nothing moved the cursor because nothing was asked
to. This part is a gap in the demo, not in the machine, and it is now
fixable: `pointer.move` warps the real cursor.
2. **A headless capture may not include the cursor image.** The compositor
normally draws the cursor as its own plane, on top of the scene, so a buffer
read back from the output can legitimately contain everything except the
pointer. Whether that is what happens here has **not been checked**.
| candidate | test | result |
| --- | --- | --- |
| `grim` not asking for the cursor | Hyprland's `Screencopy.cpp` takes an `overlayCursor` argument, so `-c` was added to the capture command | no change at the pointer |
| hardware cursor plane | `cursor:no_hardware_cursors` | already `true` |
| no cursor theme installed | installed `adwaita-icon-theme`, present at `/run/current-system/sw/share/icons/Adwaita` (63 cursor files) | no change |
| theme not reaching the cursor manager | `hyprctl setcursor Adwaita 24` at runtime | no change — and note `env = XCURSOR_THEME` in the compositor's own config sets variables for **launched programs**, not for the compositor, which is where my first attempt put it |
| hyprcursor rather than X11 themes | `cursor:enable_hyprcursor` | already `false`: the X11 path |
Which one it is decides the fix, so the first step is to find out rather than
pick.
The decisive measurement: park the pointer at two points that both miss the
browser's toolbar, capture each, diff them — **zero differing pixels**. The only
differences that ever appear are in the URL bar, which is a blinking text caret.
The cause is the protocol. `zwlr_virtual_pointer_v1` has no request to set a
cursor image, and Hyprland renders a cursor only for a pointer that has an image
to draw. A virtual pointer warps the position and has no surface behind it, so
the compositor has nothing to composite: every capture is faithful, and the
cursor is simply not in it.
## Ideas
1. **Check before changing anything.** *(recommended)* Start a session, warp the
pointer to a known point with `pointer.move`, take a `shot`, and look —
once with the pointer parked in a corner and once beside it. One comparison
separates the two causes.
2. **If the cursor is missing from the buffer, force software cursors** in the
compositor configuration (`cursor { no_hardware_cursors = true }`). That draws
the cursor into the scene, so it lands in the capture, at the cost of a redraw
per frame — the same cost this box already pays, since there is no GPU and
rendering is software anyway. Worth measuring rather than assuming.
3. **Verify motion without pixels, for tests.** `hyprctl cursorpos` answers on
this build, so a test can assert *where* the cursor is without any image at
all. That belongs in the gates; (2) is only for the human eye.
4. **Last resort: a synthetic marker** drawn by the driver. Honest only if it is
labelled as an overlay — it proves the driver thinks the cursor is at (x, y),
which is not the same claim as the compositor putting it there.
1. **Stamp the position into the frames, labelled as an overlay.** *(recommended)*
The frame server can ask `hyprctl cursorpos` — this machine answers it exactly
— map it into the stitched frame, and draw a marker there. It is not fiction:
it is the compositor's own answer, drawn where the compositor says the pointer
is, precisely because the compositor draws nothing. It has to be *named* as an
overlay in the code and in anything published from it.
2. **Leave the pixels alone and prove motion by readout.** `hyprctl cursorpos` is
exact: 0.8 across a 1280-wide desk came back as 3584 with the desk starting at
2560. Gates can assert position with no image at all — cheaper and stronger
than a pixel check.
3. **Ask upstream, or try a newer compositor.** Whatever makes a cursor appear
for a virtual pointer is the real fix. Not attempted.
4. **A synthetic pointer client.** Impossible for a plain client (it cannot draw
over another window); it would need a layer-shell surface, which is more
machinery than (1) for the same result.
## Why it matters
The point of moving a pointer is to act somewhere visible. If the cursor cannot
be seen in the artifact the operator is shown, then the acceptance proof for all
input work is missing, and the failure it hides is specifically the one that
matters: **a click on the wrong element looks exactly like a click on the right
one.** Both produce a screen that changed; neither shows where it happened.
Everything about the pointer is verifiable except the part a person can see. That
a click landed *here* is provable by readout and by what changed, but a viewer
cannot tell **where** it happened — and a click on the wrong element and a click
on the right one both produce a screen that changed.
There is a second-order cost too. Everything learned about the cursor — that the
compositor remembers no position per-device, that `motion_absolute` speaks
output-normalised coordinates, that a bookmark has to live in the session
record — was hard-won and is all invisible in a video with no cursor in it. The
operator cannot check any of it. That is a documentation problem the video was
supposed to solve.
Worth recording: this took three wrong answers (`-c`, the theme, the compositor
setting) before the right one, and two of those came from reasoning rather than
measurement. What settled it was boring — capture the same screen twice with the
pointer in two places and diff them. That should have been the first move.
+42
View File
@@ -0,0 +1,42 @@
# Killing a session does not always kill the browser it started
## The issue
Three chromium processes outlived the sessions that had launched them, while the
broker reported those sessions as ended. Found by counting windows on the
compositor after a probe run: two windows left on the main screen whose sessions
no longer existed, with pids older than the session that had replaced them.
The kill path does signal the process group — the audit line says
`sent SIGTERM to process group 2966561` and that session's process *did* die —
so this is not "the kill does nothing". It is narrower: two of three killings
left a live browser behind, and the two that leaked were started while the
compositor was unreachable from the broker, so they had no container recorded at
all. That correlation is the only clue so far and it is not proof.
## Ideas
1. **Check whether the leak tracks the container record.** *(recommended first)*
Kill a session whose container is `owned` and one whose container is `null`,
several times, and count survivors. If the leak is limited to containerless
sessions, the fix is in the kill path's cleanup of a session that never got a
desk, not in the signal path.
2. **Re-read the survivors from the compositor after every kill.** The teardown
already has `container_survivors` for windows; the same shape applies to
processes, and `procmon` already knows how to identify them by
`(pid, starttime)`. A kill that leaves anything alive should say so in its
reply rather than returning a clean record.
3. **Make the idle reaper the backstop it already is.** A session that was
reaped instead of killed goes through the same teardown; if the leak is in
the exit path, the reaper may be leaking too — worth measuring once (1).
4. **A test that counts processes, not sessions.** Every existing assertion is
about the broker's view. One that counts the app's processes after a kill
would have caught this the first time it happened.
## Why it matters
Processes that outlive their sessions are exactly what the registry's whole
identity design (boot id, start time) exists to prevent, and the ones found were
still holding windows on the compositor — invisible to `session list`, visible
on screen. A machine that accumulates them slowly fills up with browsers nobody
owns, each holding a desk slot if the band is what limits sessions.
@@ -1,64 +0,0 @@
# 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.