diff --git a/docs/TODO/README.md b/docs/TODO/README.md index d12410f..e371bbe 100644 --- a/docs/TODO/README.md +++ b/docs/TODO/README.md @@ -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. diff --git a/docs/TODO/containers-do-not-bind.md b/docs/TODO/containers-do-not-bind.md deleted file mode 100644 index b2ac21b..0000000 --- a/docs/TODO/containers-do-not-bind.md +++ /dev/null @@ -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-`, 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. diff --git a/docs/TODO/cursor-visibility-in-captures.md b/docs/TODO/cursor-visibility-in-captures.md index 675167a..bdb9ded 100644 --- a/docs/TODO/cursor-visibility-in-captures.md +++ b/docs/TODO/cursor-visibility-in-captures.md @@ -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. diff --git a/docs/TODO/kill-can-leave-the-app-alive.md b/docs/TODO/kill-can-leave-the-app-alive.md new file mode 100644 index 0000000..0bb3dfa --- /dev/null +++ b/docs/TODO/kill-can-leave-the-app-alive.md @@ -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. diff --git a/docs/TODO/pointer-needs-a-container-or-a-screen.md b/docs/TODO/pointer-needs-a-container-or-a-screen.md deleted file mode 100644 index 477a085..0000000 --- a/docs/TODO/pointer-needs-a-container-or-a-screen.md +++ /dev/null @@ -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.