Merge keyboard input (feat/keyboard-input @561e0c2) for a live trial on this machine

The merge request stays open for review; this is a local trial only.
Undo: git reset --hard 02d5006, then rebuild.
This commit is contained in:
Hermenix committed 2026-10-05 12:31:41 +00:00
commit edbf15f259
51 files changed
+8995 -233

No files matched your search

+119 -20
View File
@@ -1,7 +1,7 @@
# CONTRACT — sessions build (sessions-v1)
# CONTRACT — sessions build (sessions-v3)
This file is the interface for the **session** work: the broker, containers,
compositor IPC and pointer input. It is the sibling of `docs/CONTRACT.md`, which
compositor IPC and pointer **and keyboard** input. It is the sibling of `docs/CONTRACT.md`, which
freezes the *frame-socket* wire format; that one is untouched by this build.
**Immutable without a version bump.** Every slice codes against this and nothing
@@ -9,10 +9,23 @@ else. If something here is wrong or missing, **stop and report it in your final
message** — the parent edits this file, not you. Do not widen your slice to work
around a gap.
Version: sessions-v2 (2026-10-02). v1 was the freeze the four slices built against;
v2 records the decisions their reports asked for. Every v2 change is either a
clarification or an addition — **no v1 signature changed meaning** — so v1 code
stays valid except where noted. Changes:
Version: sessions-v3 (2026-10-04). v1 was the freeze the four slices built
against; v2 recorded the decisions their reports asked for; v3 adds the
keyboard. Every change in both has been an addition or a clarification — **no
v1 or v2 signature changed meaning** — so earlier code stays valid except where
noted.
v3 changes, all of them keyboard (`docs/plans/2026-10-03-keyboard-input.md` as
amended by `docs/plans/2026-10-04-keyboard-verification.md`):
| § | Change | Why |
| --- | --- | --- |
| §3.3 | `PointerLease` gains `press_key` / `unpress_key` / `keys_pressed`; `LeaseOutcome` gains `keys_lifted`. **`expire()` still returns `LeaseInfo` and nothing else.** | One `wl_seat` means one keyboard focus, so the keyboard shares the pointer's lease. §6.7's "the lease gains a `keyboard` flag" is the wrong shape: a boolean cannot say to lift `Control_L` and not `a`, and order matters for the same reason it does for buttons. |
| §3.4 | Driver ops `key` and `type`; `pressed` gains `keys[]`; `release_all` gains `lifted_keys[]`; the frozen command line gains four `--xkb-*` flags. A rejected request may carry a `kind`. | There is no keyboard `frame` and no `release_all_keys`: the protocol has no frame, and expiry has one call site. The flags are the **only** path a layout has to the uploaded keymap — the broker's TOML is read by `hhstreamd`, and the driver is a different unit that never opens it. |
| §4 | Verbs `keyboard.key` and `keyboard.type`, both in the mutation set; `pointer.state` gains `keys[]`; `pointer.release` gains `keys_lifted[]`. | A retried `type` must not type twice, for the reason a retried click must not click twice. |
| §4 | **`pointer.acquire` takes keyboard focus as well as the cursor**, and is two `warp`s on the driver socket rather than one. | Measured (`tests/README-keyboard-probe.md`): one warp onto an idle cursor delivers `wl_pointer.enter` and no `wl_keyboard.enter`, so a one-warp acquire aims the cursor at the session and leaves the keys with whatever was focused before. |
v2 changes:
| § | Change | Why |
| --- | --- | --- |
@@ -236,13 +249,27 @@ class PointerLease:
def press(self, session_id: str, button: str) -> None: ...
def unpress(self, session_id: str, button: str) -> list[str]: ...
def pressed(self) -> list[str]: ...
# v3: the same three for keysym names. A `keys` dict beside `buttons` on
# the held record, not a `keyboard` boolean: `release_all` has to know
# *which* keys went down and in what order.
def press_key(self, session_id: str, key: str) -> None: ...
def unpress_key(self, session_id: str, key: str) -> list[str]: ...
def keys_pressed(self) -> list[str]: ...
**`expire()` carries no bookmark and no lifted buttons** — it returns the lease
that was released, nothing more. The broker therefore has two duties on expiry:
read `pressed()` *before* calling `expire()` if it wants the lease's view of what
was down, and lift those buttons on the driver (`release_all`), because the lease
cannot lift them itself. The bookmark is not `expire()`'s to keep: the broker
already stores it with the session (§1), which is where it belongs.
**`expire()` carries no bookmark, no lifted buttons and no lifted keys** — it
returns the lease that was released, nothing more. The broker therefore has two
duties on expiry: read `pressed()` **and `keys_pressed()`** *before* calling
`expire()` if it wants the lease's view of what was down, and lift them on the
driver (one `release_all`), because the lease cannot lift anything itself. The
bookmark is not `expire()`'s to keep: the broker already stores it with the
session (§1), which is where it belongs.
v3 deliberately did **not** widen this return. The ordering it forces — read,
then expire — is the only thing stopping a key from being forgotten before the
driver has been told to lift it, and on this compositor a forgotten key is
worse than a forgotten button: `InputManager::onKeyboardKey` drops the *next*
press of a code it still believes is down, so the key is dead rather than
merely stuck.
def window_to_absolute(point: tuple[int, int], window: tuple[int, int, int, int],
monitor: tuple[int, int, int, int]) -> tuple[float, float]:
@@ -258,8 +285,27 @@ blocked driver must not stall the broker.
- Entry point `hhstream-pointer` (add to `pyproject.toml`:
`hhstream-pointer = "hhstream_pointer.__main__:main"`).
- Command line the module will pass, exactly:
`hhstream-pointer --socket /run/hhstream/pointer.sock --compositor-runtime-dir /run/hypr-stream`
- Command line the module will pass, exactly (**amended in v3**: the four
`--xkb-*` flags, whose defaults are the values below):
```
hhstream-pointer --socket /run/hhstream/pointer.sock \
--compositor-runtime-dir /run/hypr-stream \
--xkb-layout us --xkb-model pc105 \
--xkb-variant '' --xkb-options ''
```
These flags are the **only** path a layout has to the uploaded keymap. There
is deliberately no `[keyboard]` table in the broker's TOML: that file is read
by `hhstreamd`, and this is a different unit that never opens it, so such a
table would be a setting an operator could change while every injected key
stayed on `us`.
A layout `xkb_keymap_new_from_names` rejects — and a comma-separated one,
and an empty one — is exit **2**, raised *before* the compositor is
contacted. A keymap the compositor refuses is exit **10**, and the socket is
never listened on: `key` before `keymap` is the protocol error `no_keymap`,
which kills the connection rather than returning anything reportable.
- Uses **pywayland** (packaged as `python3Packages.pywayland`) and the **wlr
virtual pointer XML** from `pkgs.wlr-protocols`, which lives at
`share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml` (the v1
@@ -280,10 +326,39 @@ blocked driver must not stall the broker.
{"op": "button", "button": "left", "state": "down"} -> {"ok": true}
{"op": "axis", "axis": "vertical", "value": 3.0} -> {"ok": true}
{"op": "frame"} -> {"ok": true}
{"op": "pressed"} -> {"ok": true, "buttons": ["left"]}
{"op": "release_all"} -> {"ok": true, "lifted": ["left"]}
{"op": "pressed"} -> {"ok": true, "buttons": ["left"], "keys": ["Control_L"]}
{"op": "release_all"} -> {"ok": true, "lifted": ["left"], "lifted_keys": ["Control_L"]}
{"op": "key", "key": "Return", "state": "down"} -> {"ok": true, "keys": ["Return"], "lifted": []}
{"op": "type", "text": "Hello"} -> {"ok": true, "keys": []}
```
**Amended in v3 — `key` and `type`, for the keyboard.** Names on this socket,
evdev codes only on the Wayland request: the driver owns the keymap, so it is
the only thing that can say which keycode `z` is on the uploaded layout. Four
rules that are not interchangeable:
- **No output and no frame.** A virtual keyboard is seat-global, so `key` and
`type` take no output and must not require a prior `warp`. And
`zwp_virtual_keyboard_v1` has no `frame` request — a key queued until one
would never arrive — so each request is flushed the way `button` already is.
- **`pressed` and `release_all` grow key fields** rather than gaining a
parallel `release_all_keys`. Expiry has one call site, and a second op would
be a second thing to forget in the path that runs when nobody is watching.
`release_all` lifts buttons, then keys in press order, then sends
`modifiers(0, 0, 0, 0)` if a mask was ever set — a virtual key-up clears no
modifier state, so without that a lease that ended under Shift hands the
next holder a keyboard where every letter is a capital.
- **`type` is one request for the whole string.** The driver resolves every
character before emitting anything, so an unmappable one types no prefix.
Capped at 4096 Unicode **scalars** (not bytes) in the driver and in the
broker.
- **A rejection may carry `kind`.** `{"ok": false, "error": "…", "kind":
"invalid_argument"}` is the caller's mistake — a keysym the layout does not
have, an unmappable character, a bad `state`, a string over the cap — and the
broker maps it to exit 2. Any other value, and an older driver's absent
field, stay `driver_refused` (exit 10), which is what the button and axis
paths already do.
**Amended after the freeze — `axis`, for scrolling.** Added to the op set above
and to the broker's verbs as `pointer.scroll`. Positive vertical is *down* and
positive horizontal is *right*: the protocol's direction, not a choice of ours,
@@ -316,8 +391,26 @@ code will be called with):
| `pointer.move` | `id`, `lease_id`, `x`, `y` \| `dx`, `dy` | `bookmark` |
| `pointer.button` | `id`, `lease_id`, `button`, `state` | `buttons[]` |
| `pointer.click` | `id`, `lease_id`, `button?`, `count?` | `bookmark` |
| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by` |
| `pointer.state` | — | `holder`, `since`, `lease_id` |
| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by`, `buttons_lifted[]`, `keys_lifted[]` |
| `pointer.state` | — | `holder`, `since`, `lease_id`, `buttons[]`, `keys[]` |
| `keyboard.key` (v3) | `id`, `lease_id`, `key`, `state` | `keys[]` |
| `keyboard.type` (v3) | `id`, `lease_id`, `text` | `chars`, `keys[]` |
**v3, the keyboard.** `keyboard.*` verbs take the **pointer** lease: there is
no `keyboard.acquire` and no second lease id. One `wl_seat` means one keyboard
focus, and the shipped `input:follow_mouse = 1` means another session's warp
retargets the keys, so two leases would let session B move the pointer while
session A believed it was typing into its own window. Both verbs are in the
`request_id` mutation set, for the reason `pointer.click` is: a retried `type`
that typed twice is the one failure an agent cannot undo.
**v3, acquire takes the keyboard too.** `pointer.acquire` sends **two** warps
to the driver — a neighbouring pixel, then the real target — because one warp
onto an idle cursor moves the cursor and not keyboard focus. Measured; see
`tests/README-keyboard-probe.md`. The reply gains `focus`, naming which
mechanism took it (`warp`, `focuswindow`, or `none`). This depends on
`input:follow_mouse_threshold` being 0, which `nix/hyprland-conf.nix` now sets
explicitly rather than inheriting.
### Error codes (extend `ExitCode`, do not renumber)
@@ -325,8 +418,13 @@ code will be called with):
| 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** |
Activity accounting is unchanged and load-bearing: **`touch` is the only mark of
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` verb do **not**
reset the idle clock.
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` **and
`keyboard.*`** verb do **not** reset the idle clock. A session being typed into
is still a session nobody has said they want kept.
The *lease* clock is a different one, and v3 widens it: every `pointer.*` and
`keyboard.*` gesture verb refreshes the lease's idle deadline, because they all
go through the same gate. `pointer acquire`'s own stderr says so.
---
@@ -346,6 +444,7 @@ reset the idle clock.
| Container workspace band | `1000 + slot`, allocated from the registry's free list |
| Container mode | `1280x720` |
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` |
| Keyboard layout | **option default** `us` (`sessions.keyboard.layout`), reaching the driver as `--xkb-layout`. One group: a comma is refused. Hyprland's `input:kb_layout` is not read. |
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` |
| Service account | `hermes`, supplementary group `hhstream` |
+341
View File
@@ -0,0 +1,341 @@
# Keyboard input for sessions
> **Superseded in eight places. Read this first.**
>
> `docs/plans/2026-10-04-keyboard-verification.md` is an adversarial review of
> this file against the tree and against Hyprland v0.56.2. Its verdict is "safe
> to build on, not safe to implement as written", and the eight rows of its
> **"Changes required before code"** table **override this document wherever
> they differ**. Each one is also folded into the text below, marked
> `[SUPERSEDED]`, so nobody following a single paragraph gets the contradicted
> version:
>
> | # | What changed |
> | --- | --- |
> | 1 | Exit 2 vs `driver_refused` — §2's exit-code paragraph was wrong about what `_drive` does |
> | 2 | The keymap `size` includes the trailing NUL; `format = 1`; `time` is `_now_ms()` |
> | 3 | `release_all` no-ops its key half with no keyboard, and ends with `modifiers(0,0,0,0)` |
> | 4 | `input:virtualkeyboard:release_pressed_on_close = true` — destroy-while-held is no longer an open question |
> | 5 | The layout reaches the keymap **only** as `--xkb-layout` on the driver unit; no `[keyboard]` TOML table |
> | 6 | The modifier-keysym set is measured from the keymap; no Shift special case |
> | 7 | Stage 0's expectations, and `keyboard down` warns unconditionally |
> | 8 | Acquire's stderr mentions keyboard verbs; refusals carry a scalar index, never the string |
>
> **Stage 0 has run** (`tests/README-keyboard-probe.md`, with its transcript),
> and Stages 1–3 are built. The three open behavioural questions are answered,
> and one answer was worse than this document assumed: **a single idle warp
> does not move keyboard focus.** That is resolved rather than outstanding —
> `pointer acquire` now sends **two** warps a real pixel apart, and
> `nix/hyprland-conf.nix` pins the `follow_mouse_threshold` the second one
> depends on. See §6 risk 1, which is rewritten, and the Stage 3/4 rows, which
> are not pending work.
>
> **Where this file and `docs/CONTRACT-sessions.md` v3 disagree, the contract
> wins.** It describes what shipped; several paragraphs here describe what was
> planned before Stage 0 measured the compositor.
Typing stops being a non-goal. `docs/PLAN-workspaces-and-pointer.md` §1 defers it, and §6.7 already specifies the shape: same seat, same serialisation, `zwp_virtual_keyboard_manager_v1`, and the existing pointer lease rather than a new lock. Stages 0–3 of that plan are what the tree implements today (broker lease in `src/hhstreamd/pointer.py`, driver in `src/hhstream_pointer/`, CLI in `src/hhstream_session/__init__.py`). This plan is §6.7, with one correction noted under lease semantics.
The Chrome path in `examples/agent-eyes-demo.py` (`Input.insertText`) is not this feature. It never touches the seat. This plan is for whatever window is focused on the compositor's one seat.
---
## 1. Protocol
**Decision: `zwp_virtual_keyboard_v1`, spoken by the existing `hhstream-pointer` process. Not `wp_virtual_keyboard_v1`, not uinput/`ydotool`, not `wtype`.**
| Option | Verdict |
| --- | --- |
| `zwp_virtual_keyboard_v1` | Use it. Unstable wayland-protocols interface (`virtual-keyboard-unstable-v1.xml`). Manager global `zwp_virtual_keyboard_manager_v1`. Requests are `keymap(format, fd, size)`, `key(time, keycode, state)`, `modifiers(depressed, latched, locked, group)`. Version 1 only. |
| `wp_virtual_keyboard_v1` | Do not bind it. Nothing in this repo claims that global. A stable `wp_` rename is not what §6.7 measured. |
| uinput / `ydotool` | Reject. Needs `/dev/uinput` and a seat that actually reads that device. The headless compositor is driven as a Wayland client today (`WaylandSink` in `src/hhstream_pointer/backend.py`); the driver runs as `hermes` with group `hhstream` so it can open the Wayland socket (`nix/module.nix`). A kernel device is a second privilege and a second focus story, and it cannot be unit-tested as a recording sink. |
| `wtype` | Reject as the mechanism. It is a short-lived client of the same `zwp_` protocol: new virtual keyboard per invocation, its own keymap, no `release_all` across calls, no lease. Useful only as a reference for how text becomes keycodes. |
**What the running compositor exposes.** Not re-checked in this session (no registry dump). The only evidence in-tree is §6.7's **[RAN]** claim, against the Hyprland it measured (plan header: tag `v0.56.2`): `zwp_virtual_keyboard_manager_v1` is a live global. `wp_virtual_keyboard_v1` is not mentioned. Treat that as unverified until Stage 0 dumps the globals on `/run/hypr-stream`. If the dump shows a different name, stop. Do not probe uinput as a fallback.
**Tradeoffs, as they apply here:**
- **Keycode, not keysym, on the wire to the compositor.** `key` takes a Linux evdev code (the same value `wl_keyboard.key` carries; clients add 8 to reach an XKB keycode). Keysym names stay on our socket, the way button names stay on ours and evdev codes cross into `zwlr_virtual_pointer_v1` (`src/hhstream_pointer/buttons.py`).
- **Keymap upload is mandatory.** Until `keymap` is sent (format `xkb_v1`, memfd of an XKB text keymap), clients cannot decode a key to a character. Upload **once**, after connect and before `listen`, matching `__main__.py`'s rule that a listening socket is a promise the device works. Do not upload again per string: a second `keymap` resets client state under held keys.
**[SUPERSEDED — change 2.]** Three values this bullet left unstated, each of which fails silently:
- the `size` argument **includes the trailing NUL**. Hyprland `mmap`s exactly `size` bytes and hands the pointer to `xkb_keymap_new_from_string`, which wants a C string, so `size = len(text)` reads off the end of the mapping. The symptom is a keymap that will not compile, which from our side is indistinguishable from a compositor with no keyboard at all;
- the fd must outlive a **round trip**, not a flush: the compositor has to have received and mapped it before we close our end;
- `format` is the integer **1** (`XKB_KEYMAP_FORMAT_TEXT_V1`). Hyprland ignores it and parses as `TEXT_V2`, which accepts a V1 string; do not send 2;
- `time` on every `key` is `backend._now_ms()`, the same monotonic source the pointer requests use. The protocol requires one clock per object.
Also, a *second* upload is worse than "resets client state": Hyprland replaces its XKB state without walking the keys it believes are down, so re-uploading under a held modifier strands it.
- **No unicode request.** A codepoint is typeable only when the uploaded layout has a keysym for it. No `Ctrl+Shift+u`, no per-string custom keymap, no compose sequences in v1.
- **Modifiers are a separate request.** The compositor does not derive the modifier mask from `key`. Shifted text needs `modifiers` as well as the letter key. Details in §4.
- **No per-output target.** Unlike `create_virtual_pointer_with_output` (`backend.py`), a virtual keyboard is seat-global. Keys hit whichever surface has keyboard focus. There is no output argument to add.
**Missing global is not fatal to the cursor.** `ManagerTooOld` aborts process start because a version-1 pointer aims at the wrong output (`backend.py`). A missing keyboard global must not do that. Pointer ops keep working. Keyboard ops return `{"ok": false, "error": ...}` and the broker surfaces that as exit **10 COMPOSITOR**. No silent no-op.
---
## 2. Surface
**Decision: new CLI group `session keyboard`, new broker verbs `keyboard.*`, new ops on the existing broker↔driver socket. No new process, unit, binary, or socket.**
`CONTRACT-sessions.md` §5 freezes the binary `hhstream-pointer` and the socket `/run/hhstream/pointer.sock`. Renaming the package to "input" is churn with no behavioural gain. `server.py` already frames newline-delimited JSON at `MAX_LINE_BYTES` (1 MiB) and is unchanged.
### CLI
`pointer acquire` remains the only acquire. Keyboard verbs are gestures on that lease. They reuse `_lease_of`, `--lease`, and `$HHSTREAM_LEASE` (`src/hhstream_session/lease.py`). There is no `keyboard acquire` and no second cache file.
```
hhstream session pointer acquire ID # unchanged; also authorises typing
hhstream session pointer release ID # lifts buttons and keys
hhstream session pointer state # JSON gains "keys"
hhstream session keyboard type ID TEXT # one argument, raw UTF-8, no backslash escapes
hhstream session keyboard key ID NAME # tap: down then up
hhstream session keyboard down ID NAME
hhstream session keyboard up ID NAME
```
`NAME` is an XKB keysym name (`a`, `A`, `Return`, `BackSpace`, `Left`, `Control_L`, `Shift_L`), not an evdev number. Help text on both groups must say keyboard commands refuse with exit 9 until `pointer acquire`. `pointer --help` stays about the cursor.
`type` does not interpret `\n`. A newline is a real newline in the argument. The shell quotes it. The wire value is that string.
### Broker control socket
Extend `src/hhstreamd/protocol.py` (do not renumber `ExitCode`). Same codes as pointer: **8 BUSY** only on a second acquire, **9 NO_LEASE** when this session does not hold the lease, **2 USAGE** for a bad keysym or an unmappable character, **10 COMPOSITOR** when the driver has no keyboard global or the connection dies.
**[SUPERSEDED — change 1.]** "Exit 2 for a bad keysym" and "`Rejected`, same as a bad button" are not the same code, and this paragraph asserted both. `SessionManager._drive` turns *every* driver `ok: false` into `ManagerError("driver_refused")`, which is exit **10** — that is why `test_an_unknown_button_is_refused_by_the_driver_not_invented` asserts `driver_refused` and not usage. Exit 2 happens only for an `invalid_argument` the broker raises *before* `_drive`. So:
- the **broker** checks shape before it calls the driver: `text` must be a string, `state` must be `down`/`up`, `key` must be a non-empty string, and `text` must be within the 4096-scalar cap. Those are `invalid_argument`, exit 2;
- the **driver** tags a rejection it caused the caller to earn with a stable token, `kind: "invalid_argument"` (`hhstream_pointer.ops.KIND_INVALID`) — a bad keysym, an unmappable character, a dead key, a `type` under a held non-modifier. `_drive` maps that token to `invalid_argument`, exit 2;
- everything else keeps `kind: "refused"` and stays `driver_refused`, exit **10**: no keyboard global, no aimed output, a dead connection.
The token exists because the alternative is the broker telling "no such keysym on your layout" from "this compositor has no keyboard" by matching on English.
| Verb | Request beyond `verb`, `request_id` | Response |
| --- | --- | --- |
| `keyboard.key` | `id`, `lease_id`, `key`, `state` (`down`/`up`) | `keys[]` |
| `keyboard.type` | `id`, `lease_id`, `text` | `keys[]` (explicit holds still down; a `type` itself leaves none) |
| `pointer.state` | — | existing fields plus `keys[]` |
| `pointer.release` | unchanged | report lifted keys in the same place buttons are already reported (audit if that is where `buttons_lifted` lives today — do not invent a richer release body than buttons have) |
`keyboard.key` and `keyboard.type` join the mutation set beside `pointer.click` (`protocol.py`): a replayed `request_id` returns the recorded answer and must not type twice. A new `request_id` types again.
Neither verb calls `touch`. Same rule as every `pointer.*` verb (`CONTRACT-sessions.md` §4, module docstring of `src/hhstream_session/__init__.py`, `src/hhstreamd/manager.py`).
Cap `text` at **4096** Unicode scalars in both broker and driver. Over the cap is `invalid_argument`, not a truncated type.
**Audit:** `keyboard_key` records the keysym name and state. `keyboard_type` records `chars` (an integer) and **not the text**. Typed strings will include passwords; the audit log is the wrong place for them.
**[SUPERSEDED — change 8.]** `events.jsonl` is not the only place a string leaks, and the plan secured only that one. Two more:
- **Refusal messages and driver logs carry the scalar *index*, never the character and never the string.** "unmappable at scalar 3" is the whole of what a reader needs, and the alternative ends up in the journal. `AuditLog.emit` will happily write a `text` field if a caller passes one, so the rule is about every message, not only the audit event.
- **`pointer acquire`'s stderr is wrong once this lands.** It says "expires in … with no further **pointer** verb". A `keyboard.*` verb goes through `_refresh` and *does* move `expires_at`, so the sentence has to name both — otherwise an operator releases during a `type` that would have kept the lease, and the TTL test looks flaky against the help text.
(What the shell and `ps` show of the CLI argument is outside this rule: the text is an argv word by the time anything here sees it.)
### Driver socket (`CONTRACT-sessions.md` §3.4)
The driver stays an executor with no lease (`ops.py` docstring, `driver.py` docstring). New ops:
```json
{"op":"key","key":"Return","state":"down"} -> {"ok":true}
{"op":"key","key":"a","state":"up"} -> {"ok":true}
{"op":"type","text":"Hello"} -> {"ok":true}
{"op":"pressed"} -> {"ok":true,"buttons":["left"],"keys":["Control_L"]}
{"op":"release_all"} -> {"ok":true,"lifted":["left"],"lifted_keys":["Control_L"]}
```
There is no keyboard `frame`. `zwp_virtual_keyboard_v1` has none. Do not reuse the pointer's end-of-gesture `frame`; a key flushed only on `frame` would never arrive. `backend.py` already flushes every pointer request; keyboard requests flush the same way.
`pressed` and `release_all` grow key fields. Do not add a parallel `release_all_keys` op. Expiry has one call site (`SessionManager._expire_pointer`).
**[SUPERSEDED — change 3.]** Two things follow from there being exactly one call site, and this plan stated neither:
- `release_all` must **no-op its key half when no virtual keyboard exists**. If the key half raised, the one `release_all` would abandon the buttons it had just been asked to lift — and a lease that expired with a mouse button down is the failure the whole TTL exists to prevent.
- `release_all` ends with `modifiers(0, 0, 0, 0)` **whenever a mask was set**, because a virtual key-up clears no modifier state on this compositor. Without it a lease that ended under Shift hands the next holder a keyboard where every letter is a capital. One `modifiers(0, 0, 0, 0)` also goes out immediately after the initial keymap upload, so a previous driver's mask is not inherited.
Unknown keysym, non-finite or over-long text, and `type` while a non-modifier key is held are `Rejected` (answered, connection kept), same as a bad button.
### File-by-file
| File | Change |
| --- | --- |
| `src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/` | Vendor pywayland output, same method as `_protocol/regenerate.py` (seed the import map with core `wl_*`, do not use `python -m pywayland.scanner` alone). XML is wayland-protocols `unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml`, not the wlr pointer XML. |
| `src/hhstream_pointer/_protocol/regenerate.py` | Second XML argument. State the path in the module docstring the way the pointer generator does. |
| `src/hhstream_pointer/keymap.py` | **New.** xkbcommon only here. Builds one keymap from rules (`evdev`, model, layout, variant, options). Resolves a keysym name or a string to a list of actions `(evdev_code, mods_depressed)` or raises. Resolves the **whole** string before returning, so a bad character emits nothing. |
| `src/hhstream_pointer/ops.py` | Extend `Dispatcher`. A small `Keymap` protocol (same idea as `PointerSink`) does the resolving, so this file still imports neither pywayland nor xkbcommon. New ops `key` and `type`. `_pressed` stays buttons. New insertion-ordered `_keys`. `release_all` lifts keys after buttons: key-up each held key in press order, then `modifiers(0, 0, 0, group)`. |
| `src/hhstream_pointer/backend.py` | Still the only pywayland importer. Bind the manager at version 1, `create_virtual_keyboard(seat)` **once** (not per output). `keymap` upload from a memfd. Sink methods `key(code, state)` and `modifiers(dep, latch, lock, group)` only — no names, no UTF-8. |
| `src/hhstream_pointer/__main__.py` | Flags below. Build the keymap and upload it before `listen`. `_lift_everything` already calls `release_all`; once that op lifts keys, shutdown covers them. Update the comment that today only mentions buttons. |
| `src/hhstream_pointer/server.py` | No change. |
| `src/hhstreamd/driver.py` | `key()`, `type_text()` on `PointerDriver`. `release_all` / `pressed` read the new fields. Same socket, same "do not retry a request that was written" rule. A failed `release_all` is still `DriverUnavailable`: a dropped lift leaves a key down. |
| `src/hhstreamd/pointer.py` | Not a new class. On `_Held`, a `keys` dict beside `buttons`. `press_key` / `unpress_key` / `keys_pressed`, mirroring `press` / `unpress` / `pressed`. `expire()` still returns `LeaseInfo` only — no keys. Callers read `keys_pressed()` first, as they must read `pressed()` first (`CONTRACT-sessions.md` §3.3). |
| `src/hhstreamd/manager.py` | `keyboard_key` and `keyboard_type` go through `_refresh` (live session, holder, not expired, container output required). Driver first, then the lease mirror — the `pointer_button` order, so a refused key is not recorded as down. `_expire_pointer` reads keys before `expire()` and uses the one `release_all`. Same on `pointer_release`, kill, reap, and driver loss. |
| `src/hhstreamd/protocol.py` | Verb allowlist plus the mutation set. |
| `src/hhstreamd/policy.py` | **[SUPERSEDED — change 5.] No change.** A `[keyboard]` table here would be read by nothing: `settings_from_dict` is read by `hhstreamd`, and the driver is a *different unit* that never opens that file. An operator could change the layout and every injected key would stay on `us`. The layout travels as `--xkb-layout` on the driver's argv, and nowhere else. |
| `src/hhstream_session/__init__.py` | `_build_keyboard` beside `_build_pointer`. |
| `src/hhstream_session/format.py` | `render_pointer_state` shows held keys. |
| `src/hhstream_session/lease.py` | No new store. `pointer-leases.json` remains the cache. |
| `nix/module.nix` | No new unit. Extend `hhstream-pointer.service` argv — **and nothing else**: **[SUPERSEDED — change 5]** the `[keyboard]` TOML emission is dropped, see `policy.py` above. Options under `sessions.keyboard`: `layout` (`lib.types.strMatching "[A-Za-z0-9_-]+"`, default `"us"` — the type is what refuses a comma-separated list), `variant` (default `""`), `options` (default `""`), `model` (default `"pc105"`). The driver also refuses a comma itself, before `xkb_keymap_new_from_names`, because the NixOS type cannot reach a binary run by hand. §3.4's "command line the module will pass, exactly" and the unit comment quoting it are amended in the same change. |
| `nix/package.nix`, `flake.nix` devshell, `pyproject.toml` | `xkbcommon` for the driver and for unit tests. No new console script. |
| `nix/hyprland-conf.nix` | Keep `input:follow_mouse = 1`. Extend the comment: keyboard events have no output, so the warp is what moves keyboard focus — but see §6 risk 1 and Stage 0, because **one** warp does not — and the lease is what stops another session stealing it mid-string. **[SUPERSEDED — change 4]** Also set `input:virtualkeyboard:release_pressed_on_close = true`, with the note that it releases keys and still does not clear the modifier mask. |
| `docs/CONTRACT-sessions.md` | Amend §3.3 (key mirror, `expire()` still carries no keys), §3.4 (ops above), §4 (verbs, idle rule). |
| `README.dev.md` item 3, `checks/vm-pointer.nix` header | Stale relative to the conf file as read: they still say `hyprland-conf.nix` ships `follow_mouse = 0` and that the keyboard task will choose. The conf file sets `1`. Fix the prose when implementing; do not set the conf back to `0`. |
Flags the unit passes, defaults matching §5's style of frozen defaults:
```
hhstream-pointer --socket /run/hhstream/pointer.sock \
--compositor-runtime-dir /run/hypr-stream \
--xkb-layout us --xkb-model pc105 \
--xkb-variant '' --xkb-options ''
```
A layout xkbcommon rejects, before any Wayland connect, exits **2**. Compositor failures stay **10**.
---
## 3. Lease
**Decision: one lease. Keyboard verbs require the pointer lease. Do not add a keyboard lease, a `keyboard` boolean, or a second sweeper.**
§6.7 says the lease "gains a `keyboard` flag" and that no new mechanism is needed. The flag is the wrong reading of the code that shipped. `_Held.buttons` exists because `release_all` must know **which** buttons went down and in what order (`src/hhstreamd/pointer.py`, `ops.py`). A boolean cannot lift `Control_L` and not `a`. The key set is that pattern, not a new state machine.
Why sharing is required by the seat, not just by the plan: there is one `wl_seat` and one keyboard focus. `follow_mouse = 1` (`nix/hyprland-conf.nix`) means another session's warp retargets the keys. Two leases would let session B move the pointer while session A believes it is typing into its own window. `LeaseBusy` on acquire is already the mutex (`PointerLease.acquire` refuses even the current holder a second id, so a drag — or a half-typed chord — cannot have its id silently replaced).
Rules that keyboard inherits unchanged:
- Acquire / refresh / hard cap (`ttl` 30 s, `max` 300 s, refresh moves only the idle deadline).
- `expire()` does not lift anything. The broker reads the mirror, drops the lease, then `release_all` on the driver (`_expire_pointer`).
- Driver death force-releases (`driver_gone`). The driver is not asked to remember who held the lease.
- Kill and reap of the holder drop the lease with the existing reasons (`kill` / `crash`).
- CLI cache is re-checked by the broker; a stale id is exit 9 and then forgotten.
- Gesture verbs do not mark activity.
**TTL expiry with keys held down.** Same as buttons (`PLAN` §6.2 "Never leave a button down", implemented in `_expire_pointer` and in `_lift_everything`):
1. Sweeper (or the next verb's `_refresh`) sees the deadline.
2. Broker reads `keys_pressed()` and `pressed()` **before** `expire()`.
3. `expire()` drops the lease. It is not kept open to finish the word.
4. Driver `release_all`: button-ups, then key-ups in press order, then `modifiers(0, 0, 0, group)`, then the pointer `frame`s it already sends for buttons. No keyboard frame.
5. Audit `pointer_lease_timeout` gains `keys_lifted`. The session's pointer bookmark is stamped `released_by: timeout` as today.
6. The next `acquire` is free. Nothing is replayed. A held Shift does not leak into the next holder.
If `release_all` fails, do what the button path does: log it, still drop the lease, do not retry a request whose outcome is unknown (`driver.py`). The stuck-key case is a risk in §6, not a second expiry protocol.
`type` refreshes **once per broker verb**, inside `_refresh`, not once per character. Explicit `down` of a modifier stays in the lease mirror across later `type` calls. `type` itself must not leave letters down.
A warp while a key is held stays legal, same as a drag. Focus can follow that warp. That is another reason both devices share the lease: the holder is the only session allowed to move focus until release or TTL.
---
## 4. Keymap and text
**Decision: one seat-wide XKB layout, chosen in config, default `us` / `pc105` / empty variant / empty options. The virtual keyboard's keymap is the one we upload. Hyprland's `input:kb_layout` is not read and does not affect injected keys.**
Do not query `hyprctl getoption` to fill a default. The broker's rule is that unverified fields stay null (`PLAN` §7); a layout guessed from the compositor would drift on reload. Operators who are not on `us` set `sessions.keyboard.layout`.
**Decision: v1 is a single group.** A comma-separated layout (`us,ru`) is rejected at config load. Group in every `modifiers` request is **0**. No group-switch keysym.
**Where it lives.** `[keyboard]` in the broker TOML (`policy.py`), rendered by `nix/module.nix`, passed as the flags in §2. The driver compiles it at startup and uploads that byte string. The session record does not gain a layout field. Per-session layouts would mean re-uploading `keymap` on every acquire, which drops held state; not in v1.
**How text is expressed.**
- `keyboard type` takes a Python `str` of Unicode scalars. The keymap maps each scalar to one keysym, then to one `(evdev code, modifier mask)`.
- Newline → keysym `Return`. Tab → `Tab`. Other C0 controls are rejected with the rest of the string, not skipped.
- `A` is Shift+`a` via the **mask**, not via a typed Shift key, unless the user also has Shift explicitly held.
- Explicit modifier holds are a baseline. `type` ORs each character's mask with that baseline, sends the letter, and restores the mask to the baseline afterwards. So `down Control_L` then `type c` is Ctrl+C, and Control is still down when `type` returns.
- If any **non-modifier** key is already held, `type` is rejected and emits nothing.
- Validation is complete before the first sink call. Unmappable character → the whole request fails, no prefix typed. This includes `é` on `us`.
- Dead keys (`dead_acute` and the like) are a rejection even if the layout names them. v1 does not emit a two-event compose. `us(intl)` is therefore a poor choice until a later stage; default `us` does not need it.
- No auto-repeat timer in our process. **[SUPERSEDED — change 7, and Stage 0 has measured it.]** Hyprland does not repeat on the wire: a key held 1.5 s produced exactly one `wl_keyboard.key`, and it publishes `repeat_info rate=25 delay=600` so the *client* repeats. That is not good news — a focused text field will insert characters from that one press until the key-up or the TTL — so the `down` help text warns **unconditionally** rather than only if a probe saw repeats, and v1 has no rate to offer because we do not generate them.
**Modifier decision:** for a shifted character, send `modifiers(shift_mask, 0, 0, 0)` and the letter's `key` down/up, then restore the previous mask. Do **not** also synthesize `Shift_L` down/up for that character. For an explicit `keyboard down Shift_L`, send the Shift **key** and a matching `modifiers` update, and remember both in the held-key record so `release_all` undoes both. Sending both a synthetic Shift key and a mask for an ordinary capital is how toolkits apply Shift twice or not at all; the VM check in §5 is what proves the letter path against a real `wl_keyboard` client.
Named non-character keysyms used by `key`/`down`/`up` go through the same resolver, not a second table that can disagree with the layout. `buttons.py` can stay a hand-written evdev table because the protocol takes those codes directly; keysyms cannot.
**[SUPERSEDED — change 6.]** This section never defined "modifier", and a Shift-only reading of it is wrong: `@` on `de` is a **level-three** symbol, so a resolver that only knew about Shift would type the wrong character. The definition is *measured from the keymap*, not listed — press each keycode in a throwaway XKB state and read the serialised masks back:
- a non-zero **depressed** mask and no locked mask makes it a **modifier**: on `us`/`pc105` that is exactly `Shift_L/R`, `Control_L/R`, `Alt_L/R`, `Super_L/R`, `ISO_Level3_Shift`, `ISO_Level5_Shift`. (`Meta_L/R` and `Hyper_L/R` are canonical modifier keysyms that **no keycode on this layout carries** — which is the argument for measuring rather than listing.)
- a non-zero **locked** mask makes it a **lock**: `Caps_Lock`, `Num_Lock`. A lock is not a modifier, and `type` refuses while one is held rather than producing a case nobody asked for.
The resolver returns `(evdev code, mask)` for a keysym at *any* level, so one code path serves `us` and `de`. And `key`/`type` never call `_aimed()`: a keyboard has no output, so demanding a prior warp would refuse a caller who only ever wanted to type.
---
## 5. Tests
Match the split already in the tree: the dispatcher is tested against a recording sink and is not tested for authority (`tests/pointer/test_ops.py`); the lease is pure with `FakeClock` and no sleep (`tests/pointer/conftest.py`); the broker is tested with a real UNIX socket and `FakeDriver`, Wayland substituted (`tests/sessions/unit/test_pointer_verbs.py`). No integration test grows a fake compositor. `tests/sessions/integration/` does not gain Wayland.
### Unit
| Test | Asserts |
| --- | --- |
| `tests/pointer/test_keymap.py` | Real xkbcommon, layout `us`: `a` → evdev 30, mask 0; `A` → 30 plus Shift; `Return` and `\n` → `KEY_ENTER`; empty string → `[]`; `é` and a C0 control other than `\n`/`\t` raise; the raise happens with zero sink calls when driven through the dispatcher. Dead keysym raises. |
| `tests/pointer/test_ops.py` | Extend `RecordingSink` with `key(code, state)` and `modifiers(...)`. `key down` then `pressed` lists the name. `up` of a key that was not down reports it not lifted (same as `unpress`). `release_all` lifts keys in press order and ends with a zeroed `modifiers`, even if the last `warp` was to another output (keys are not per output). `type` emits down/up pairs and leaves `keys` empty. `type` with `Control_L` held ORs the mask and leaves Control down. `type` with `a` held emits nothing and returns `ok: false`. A keymap that raises on the third character emits nothing. |
| `tests/pointer/test_lease.py` | `press_key` / `keys_pressed` order. `expire()` still returns no key list; the test reads `keys_pressed()` first, then `expire()`, then sees an empty lease. Existing busy/stale/`lease_id` cases stay as they are. |
| `tests/pointer/test_vendored_protocol.py` | Interface name `zwp_virtual_keyboard_manager_v1` and requests `keymap`, `key`, `modifiers`. No display. |
| `tests/sessions/unit/test_keyboard_verbs.py` | New, harness copied from `test_pointer_verbs.py`. No lease → 9. Other session holds the lease → 9 (not 8). Second `pointer.acquire` while typing → 8. `type` refreshes TTL: advance the `ManualClock` by less than `ttl` after a type and the lease survives; advance past it and `release_all` runs with the held key. Driver rejection does not stick the key in the lease. `type` does not move `last_activity_boottime`. `pointer.release` and kill both lift keys. `pointer.state` includes `keys`. |
| ~~`tests/sessions/unit/test_settings.py`~~ | **[SUPERSEDED — change 5.] Dropped.** A TOML default of `us` that nothing uploads is precisely the false pass that file's own docstring warns about. Replaced by `tests/pointer/test_driver_flags.py`: an omitted `--xkb-layout` is `us`, `de` is `de`, and `us,ru` exits 2 **with an injected sink proving the compositor was never touched**. |
| CLI surface test (`tests/sessions/unit/test_cli_surface.py`) and broker verb list (`test_broker_protocol.py`) | `keyboard` in help; help says the pointer lease is required; `keyboard.type` / `keyboard.key` are known verbs and are in the mutation set. |
`nix develop -c python -m pytest tests/pointer tests/sessions/unit -q` is the gate. Not run for this plan.
### Integration / VM
**Decision: a new `checks/vm-keyboard.nix`, same shape as `checks/vm-pointer.nix`. Do not call the feature done on unit tests alone.** `docs/TODO/scroll-has-no-compositor-proof.md` is the precedent: scroll shipped on the driver socket with no compositor proof. Keyboard's only purpose is that the client receives symbols.
- Victim: a small Wayland client beside `checks/lib/pointer_target.py` (or an extension of it) that sets `xdg_toplevel` app id from `$HHSTREAM_APP_ID` and prints `wl_keyboard.enter`, each `key` (evdev code, state), each `modifiers` mask, and the keysym it decodes from the keymap the compositor forwarded. Read-back is `hhstream session logs`, as in `vm-pointer`.
- Assertions, real time, no injected clock (the unit clock already covers the arithmetic; `vm-pointer`'s expiry subtest states why):
1. After `pointer acquire` on session A, A's log shows `wl_keyboard.enter`. This is the focus measurement, and it is asserted against acquire itself: acquire is two warps (§6 risk 1), so this is a live assertion rather than one expected red. `checks/vm-keyboard.nix` also requires the reply's `focus == "warp"`, so the nudge-failure fallback is not accepted as success, and it asserts `wl_pointer.enter` separately — a check that saw only the cursor arrive would pass while the first keystroke went elsewhere. Do not weaken it.
2. `keyboard type A hello` decodes to the characters `hello` on A and to nothing on session B.
3. `keyboard down A Shift_L`, wait out a short `--ttl`, A's log shows the key-up and a cleared mask, and `pointer state` shows no holder.
4. A second acquire during the hold exits 8.
- Mutation, per `PLAN` §14: the character assertion must fail if `keymap` was never uploaded (keycodes without a decoded `hello` are a failure, not a pass).
- `globalTimeout` on the order of `vm-pointer` (1800). This check is slow; that is not a reason to fold it into a unit test.
---
## 6. Risks, open questions, stages
### Risks
- **Focus does not follow a single virtual-pointer warp. [MEASURED — Stage 0, and this is the headline risk of the feature.]** One `motion_absolute` onto an unfocused window, after the cursor had been still for 0.8 s, delivered `wl_pointer.enter` and **no** `wl_keyboard.enter`; the focus change arrived only after a *later* motion that changed the floored pixel. The mechanism is `InputManager::onMouseWarp` → `mouseMoveUnified(refocus=false)`: the delta is set to 0 when the previous movement was over 0.5 s ago, `mouseMoveUnified` returns early when the floored pixel did not change at all, and keyboard focus is that delta compared against `input:follow_mouse_threshold` (measured 0.0, unset). Transcript in `tests/README-keyboard-probe.md`.
**[RESOLVED in Stage 2 — `pointer acquire` is now two warps.]** This paragraph used to end "acquire is one warp, so the first key of a lease can land in whatever was already focused; the fallback is not built in Stages 1–2". Both halves are out of date, and `docs/CONTRACT-sessions.md` v3 §4 is the text that describes what shipped:
- `pointer_acquire` calls `_warp_taking_focus`, which warps to a neighbouring pixel and *then* to the target. The second motion carries a non-zero `m_mousePosDelta`, so it moves keyboard focus; the cursor finishes on the target, so the bookmark is unchanged. `FOCUS_NUDGE` is 0.004, about 2.88 px at the frozen 1280×720 mode, which is what makes the *floored* pixel differ.
- This depends on `input:follow_mouse_threshold` being 0, so `nix/hyprland-conf.nix` now sets it **explicitly** rather than inheriting the default. Raise it and acquire stops taking the keyboard.
- `dispatch focuswindow` **is** built, and it is not what this risk needed: it runs only when the *nudge* warp could not be sent, and it selects on `address:` from the read-back (falling back to `pid:`), never on `stable_id`, which is not a Hyprland selector. The target warp is still attempted afterwards and its failure still drops the lease. The acquire reply and the audit event carry `focus`: `warp`, `focuswindow`, or `none`.
- Still *not* the fix, and worth keeping written down: warping twice to the same bookmark (the same floored pixel returns early, before the delta is touched) and waiting longer after one warp (the measured settle window was 0.4 s and contained the pointer enter alone).
Measured end to end by `checks/vm-keyboard.nix` on both layouts: with session B holding keyboard focus, acquire on A delivers `wl_pointer.enter` **and** `wl_keyboard.enter` to A and `wl_keyboard.leave` to B. That subtest requires `focus == "warp"`, so it does not accept the fallback as success.
What is **not** covered by a test: the `focuswindow` branch itself. A driver that is down fails the target warp too and the acquire aborts, so the branch is the narrow one where the nudge fails and the target warp succeeds. If both mechanisms fail, acquire still returns `ok` with `focus="none"` — a lease whose first key may go to the previously focused window.
- **Destroy of the virtual keyboard leaves a key down inside Hyprland. [MEASURED — Stage 0.]** `destroy` with a key held, with a second virtual keyboard keeping the seat's capability up, delivered no key-up; `input:virtualkeyboard:release_pressed_on_close` is `0` and unset. Worse than "stuck": `InputManager::onKeyboardKey` drops a *press* whose code is already in the seat's `m_pressed`, so the next driver's press of that code is ignored and the key is **dead** until something sends a matching up. Our shutdown path sends key-ups first (`_lift_everything`); a `-9` skips it, which is why **[change 4]** `nix/hyprland-conf.nix` now sets `release_pressed_on_close = true`. That setting emits key-ups only and still never clears the modifier mask, so `release_all` keeps sending `modifiers(0, 0, 0, 0)` regardless. Still no retry loop the button path does not have.
- **Auto-repeat is the client's, which does not make it harmless. [MEASURED — Stage 0.]** `press_count=1` over a 1.5 s hold, with `repeat_info rate=25 delay=600` published at bind time. So the flood is real and it is foot/GTK/Qt producing it from our one press, for as long as the key is down — up to the TTL (default 30 s). **[SUPERSEDED — change 7]** the help text for `down` therefore warns unconditionally; the old "if it does, the help text says so" is the false pass the review named. v1 has no repeat-rate control, and `zwp_virtual_keyboard_v1` has no `repeated` state to ask the compositor about. Chords (`Control_L` held across a `type`) remain the justified use of `down`.
- **Mask versus Shift keycode.** §4's letter path can still be wrong for a toolkit that ignores `modifiers` and only shifts when it sees `KEY_LEFTSHIFT`. The VM victim must print both the mask and the decoded sym. Chromium is not the first victim (`vm-pointer` avoided it; it is expensive and the app-id rule in `README.dev.md` item 4 only binds clients that honour `$HHSTREAM_APP_ID`).
- **The lease is not a security boundary.** `PLAN` §6.6: any client may bind the pointer global. The keyboard global is the same. Stage 4 sandboxing is unchanged and out of this work.
- **Concurrent typing is impossible** on one compositor, for the same reason concurrent pointers are (`PLAN` §1). A second seat is Stage 5 and still CPU-gated. This work does not pretend otherwise.
- **`xkbcommon` in the devshell** is a new dependency. Tests that import `keymap.py` cannot skip when it is absent; an optional dependency would let the unmappable-character path rot.
### Open questions
Questions 1–4 are **closed by Stage 0** (`tests/README-keyboard-probe.md` and its transcript). Question 5 is answered by the operator.
1. ~~Stage 0 global name and version on the actual `/run/hypr-stream` socket.~~ **`zwp_virtual_keyboard_manager_v1` at version 1.** No `wp_virtual_keyboard_v1`. The gate holds.
2. ~~Does acquire's warp produce `wl_keyboard.enter`?~~ **Not from a single idle warp — so acquire stopped being a single warp.** See risk 1 above. Measured again end to end by `vm-keyboard` on both layouts, where the two-warp acquire does deliver `enter` to the aimed window and `leave` to the one that held focus.
3. ~~On destroy, does Hyprland release keys that were down?~~ **No.** See risk 2.
4. ~~Does Hyprland auto-repeat those keys?~~ **Not on the wire; the client does.** See the auto-repeat risk.
5. **Answered: `us`, and configurable.** The operator's decision is a NixOS option in the `hhstream` namespace, string, default `"us"`, documented in `README.dev.md` — reaching the keymap as `--xkb-layout` on the driver unit, per change 5.
6. A later stage, only if agents must type arbitrary UTF-8: a throwaway keymap that maps spare keycodes to `0x01000000 + codepoint` for the duration of one `type`, then restores the layout keymap. Not v1. It reintroduces the "upload resets held modifiers" problem, so it has to refuse to run while any key is held.
### Stages
| Stage | Work | Rough size | Gate |
| --- | --- | --- | --- |
| 0 | **Done.** `tests/keyboard_probe.py`, its README and its transcript. Two windows, not one; read-only `hyprctl` for the boxes; `(a1)` and `(a2)` measured separately; no `hyprctl dispatch`. | S | **Passed.** Named global is `zwp_virtual_keyboard_manager_v1` v1. |
| 1 | Driver: vendor, `keymap.py`, ops, backend upload, `__main__` flags, pointer unit tests. Pointer still runs if the global is missing. | M, about 3–5 days | `pytest tests/pointer` green. `type` of an unmappable character emits no events. |
| 2 | Broker mirror, verbs, CLI, module argv, session unit tests, contract doc amendments, stale `follow_mouse` comments. **No `policy.py` and no TOML table** (change 5). | M, about 2–4 days | `pytest tests/pointer tests/sessions/unit` green. Expiry test shows `release_all` lifting a held key. No new unit under `nix/module.nix`, and nothing there beyond argv. |
| 3 | **Done.** `checks/vm-keyboard.nix` and `checks/lib/keyboard_target.py`, exposed twice (`vm-keyboard`, `vm-keyboard-de`) because the layout reaches the keymap only through the driver unit's argv. Its enter subtest **is** written against acquire, because acquire is two warps now — see the risk paragraph above and the file's own header. | M | **Passed**, both layouts: characters on A, silence on B, key-up after a real TTL, second acquire is 8, red if the keymap was not uploaded. |
| ~~4~~ | **Does not exist as pending work.** It was "build `focuswindow` before the first key of a lease, if Stage 0 shows no enter". Stage 0 did show no enter after a *single* warp, and the answer was the second warp in `_warp_taking_focus`, not a focus dispatch — so the Stage 3 enter assertion is green without loosening it. `focuswindow` shipped in Stage 2 as the nudge-failure fallback *inside* acquire, which is a different mechanism for a different failure. Nothing here is outstanding. | — | — |
Rollback of Stages 1–2 is reverting the commit: old brokers never send `key`/`type`, and an old driver rejects unknown ops with `ok: false` (`ops.py` already answers unknown `op` instead of dropping the connection). No registry schema bump. Bookmarks stay as they are.
@@ -0,0 +1,351 @@
# Keyboard plan — verification and tests
Adversarial check of `docs/plans/2026-10-03-keyboard-input.md` (commit `14b3f69` on `feat/keyboard-input`; that file is not in this checkout). Source citations are from this tree. `git diff 14b3f69 HEAD -- src nix tests checks docs/CONTRACT-sessions.md docs/PLAN-workspaces-and-pointer.md` is empty, so the pointer/broker code the plan describes is the code reviewed here.
Compositor claims below are from the Hyprland **v0.56.2** tree `PLAN-workspaces-and-pointer.md` says it measured (not from a registry dump on `/run/hypr-stream`). Stage 0 still has to confirm the running binary. Until it does, treat the source as the prior, not as a pass.
**Bet, up front:** do not implement the plan as written. The shape is right (same driver, same lease, `zwp_virtual_keyboard_v1`, names on our JSON, evdev only on the Wayland `key` request, mask rather than a synthetic Shift key). Five plan edits are load-bearing and cheap only before Stage 1: the exit-2 vs `driver_refused` contradiction, NUL included in the keymap `size`, `release_pressed_on_close` (default is off, and destroy does not clear the modifier mask), focus is not a coin-flip, and the layout option reaches the keymap only via the pointer unit's argv. Detail below.
---
## Layout option (operator decision, not re-litigated)
The layout is a NixOS option on the pointer unit's command line. It is not a broker TOML key. `[pointer]` is read by `hhstreamd` (`policy.py` `settings_from_dict`, `__main__.py` around the `load_settings` call) for lease numbers only. The driver is a different unit (`nix/module.nix` `systemd.services.hhstream-pointer`) and never sees that file. Emitting `[keyboard]` "the way `[pointer]` is emitted" (plan §2 file table) does not upload a keymap.
| | |
| --- | --- |
| Attribute | `services.hyprland-headless-stream.sessions.keyboard.layout` |
| Type | `lib.types.strMatching "[A-Za-z0-9_-]+"` |
| Default | `"us"` |
| Description | XKB layout the `hhstream-pointer` unit uploads once as the virtual keyboard keymap (`rules` `evdev`, model `pc105`). Injected keys are decoded with this keymap. Hyprland `input:kb_layout` is not read. One group: a comma-separated list does not match the type. `de` is the value the VM check uses for a non-`us` proof. |
`variant` / `options` / `model` stay as the plan wrote them (`""`, `""`, `"pc105"`). They are not required for the `de` y/z proof. Do not add a `rules` option; the driver hardcodes `evdev`.
Path to the upload, in order:
1. `nix/module.nix` `hhstream-pointer` `ExecStart` (today the frozen two-flag line at the `ExecStart = lib.escapeShellArgs` block, ~986–992) gains `--xkb-layout ${cfg.sessions.keyboard.layout}` plus the plan's `--xkb-model`, `--xkb-variant`, `--xkb-options`.
2. `hhstream_pointer/__main__.py` parses them. A comma in `layout`, or a layout `xkb_keymap_new_from_names` rejects, returns `EXIT_USAGE` (2) **before** `WaylandSink.connect`. xkbcommon accepts `us,ru`; the driver must reject `,` itself. The Nix type does not cover a hand-run binary.
3. `keymap.py` compiles `rules=evdev`, `model`, `layout`, `variant`, `options` and returns one text keymap. Same object for every later `type`.
4. `backend.py` `create_virtual_keyboard(seat)` once, then one `keymap` request, then `listen`. Not on acquire, not per string.
`CONTRACT-sessions.md` §3.4's "command line the module will pass, exactly" and the unit comment that quotes it (`module.nix` ~981–985) have to be amended in the same change. §5's binary and socket names do not change.
---
## A. What the plan gets right
Do not reopen these.
- **Not a new service.** `CONTRACT-sessions.md` §5 freezes binary `hhstream-pointer` and socket `/run/hhstream/pointer.sock`. A CLI group on `hhstream session` is not a new binary. No second socket, no second unit.
- **No `touch`.** §4: `touch` is the only activity mark; every `pointer.*` verb leaves the idle clock alone. `pointer_click` never calls `registry.touch` (`manager.py` `pointer_click`). Routing `keyboard.*` through `_refresh` and not through `touch` is the same rule, and it is testable the way `test_pointer_verbs_do_not_reset_the_idle_clock` already is (`command_count`).
- **One lease, no `keyboard` flag.** `PLAN` §6.7's flag cannot name which keys to lift. `_Held.buttons` is an insertion-ordered dict because `release_all` must (`pointer.py` `_Held`, `ops.py` `_pressed`). A `keys` dict beside it is the same pattern. `acquire` already raises `LeaseBusy` for the current holder (`pointer.py` `acquire`), so a second id cannot replace a half-typed chord. Two leases would let session B warp while A types: one `wl_seat`, and `follow_mouse = 1` (`nix/hyprland-conf.nix`).
- **Exit 9 is implementable where the plan says.** Gesture verbs go through `_refresh` (`manager.py`): live session, `_expire_pointer`, then `PointerLease.refresh`, and `LeaseInvalid` becomes `no_lease`. The CLI already refuses with exit 9 before the broker when the cache is empty (`hhstream_session/__init__.py` `_lease_of` / `_no_lease`), using `lease.py`'s `pointer-leases.json`. There is no second cache to add. Another session's hold is 9, not 8; 8 is only `LeaseBusy` on a second `pointer.acquire` (`pointer_busy` → `ExitCode.BUSY`).
- **`expire()` stays `LeaseInfo` only.** §3.3. `_expire_pointer` already reads `pressed()` before `expire()` and then calls one `release_all`. Reading `keys_pressed()` on that same line is the whole of the lease-side change. Do not add `release_all_keys`.
- **Replay mechanism is the click mechanism.** `server.py` `_dispatch` looks up `request_id` before the handler and `remember`s after, success or failure. Membership is `MUTATING_VERBS` (`protocol.py`). `pointer.state` is not in that set. Putting `keyboard.key` and `keyboard.type` in it, and not `pointer.state`, matches `test_a_retried_click_with_the_same_request_id_clicks_once` (`tests/sessions/integration/test_containers.py`).
- **Names on our JSON, evdev only on the Wayland request.** This is what the plan's own driver examples say (`{"op":"key","key":"Return"}`), and it is what `buttons.py` does: names on the broker and driver sockets, `code_for` inside `ops.py`, integers only in `PointerSink.button`. The shorthand "evdev codes on the driver wire" is not the plan and would force a keymap into the broker. Do not "correct" the plan toward that.
- **No keyboard `frame`.** `zwp_virtual_keyboard_v1` v1 requests are `keymap`, `key`, `modifiers`, `destroy`. `backend.py` `display.flush()` on every pointer method is a socket flush, not a `wl_pointer.frame`. `ops.py` `frame` is a separate op because the pointer protocol delivers on `frame` (`PointerSink.frame` docstring; `driver.py` `frame` docstring). A key queued until `frame` would never be sent. Keyboard requests must flush inside the sink the way `button` does, and must not call `_aimed()` — keys are not per output (`ops.py` `_aimed` raises when nothing has been warped).
- **Missing keyboard global must not `ManagerTooOld`.** That exception is the pointer manager below version 2 (`backend.py`, `__main__.py` `connect`), because a v1 pointer aims at the desktop. A missing `zwp_virtual_keyboard_manager_v1` is a different failure. Pointer ops have to keep working.
- **Mask, not a synthetic Shift, for a capital.** Confirmed against v0.56.2 below. VM must print mask and keycode, not only the character.
- **Validate the whole string before the first sink call.** Same reason a bad axis emits nothing (`test_an_unknown_axis_is_refused_by_the_driver_not_invented`).
- **Audit stores a count.** `AuditLog.emit` writes every field it is given (`audit.py`). The generic `request` line in `server.py` stores the error **name**, not the body. A dedicated `keyboard_type` event is the leak. `chars` and not `text` is the right shape; click stores `button` and `count` (`pointer_click`).
- **VM proof is required.** `docs/TODO/scroll-has-no-compositor-proof.md` is the precedent the plan cites. Unit tests do not show a client decode a symbol.
- **Rollback.** Unknown `op` is `Rejected` and the connection stays (`ops.py` `_handle`). Old brokers never send `key` / `type`.
---
## A. Protocol
`zwp_virtual_keyboard_manager_v1` version 1 is what Hyprland v0.56.2 binds (`ProtocolManager.cpp` constructs `CVirtualKeyboardProtocol` with version 1). There is no `wp_virtual_keyboard_v1` in that tree. uinput is a second privilege the pointer path does not have (`WaylandSink` is a client; the unit's only extra privilege is group `hhstream` so it can open the Wayland socket, `module.nix` `SupplementaryGroups`). Rejecting `wtype` as the mechanism is right: one process, one keymap, one `release_all`.
v1 requests and the values the plan never writes down:
| Request | Arguments | Values that matter |
| --- | --- | --- |
| `keymap` | `format: uint`, `fd: fd`, `size: uint` | Protocol `keymap_format.xkb_v1 = 1`. That format is a **null-terminated** libxkbcommon text keymap. The `key` event's code is an evdev code; clients add 8. |
| `key` | `time: uint`, `key: uint`, `state: uint` | `key_state.released = 0`, `pressed = 1`. Same integers as `buttons.STATES`. `time` is milliseconds, undefined base, **one clock for the object**. |
| `modifiers` | four `uint`s | depressed, latched, locked, group. Not derived by this protocol from `key`. |
| `destroy` | destructor | See held keys below. |
`key` or `modifiers` before `keymap` is protocol error `no_keymap` (0). Hyprland posts it and the client connection dies (`VirtualKeyboard.cpp` `setKey` / `setModifiers`). That is not `{"ok": false}` and not a retry. "Upload once, after connect, before `listen`" is the right order (`__main__.py` already treats a listening socket as a promise). A second `keymap` is not a refresh: Hyprland replaces the xkb state and does **not** walk `m_pressed` (`setKeymap` in the same file).
What the plan gets wrong or leaves out:
1. **`size` must include the trailing NUL.** Hyprland `mmap`s exactly `len` bytes and passes the pointer to `xkb_keymap_new_from_string` (`VirtualKeyboard.cpp` keymap handler). No NUL inside that map reads off the end. The plan says "memfd of an XKB text keymap" and never says `size == strlen + 1`.
2. **`time` is unspecified.** Pointer methods pass `_now_ms()` (`backend.py`, monotonic ms, low 32 bits). The keyboard sink has to use that same function. A constant 0 is one clock and therefore legal, but it is a second clock the moment anything else on the object uses monotonic time.
3. **Hyprland ignores `format` and parses as `XKB_KEYMAP_FORMAT_TEXT_V2`.** Send `format = 1` anyway. A `TEXT_V1` string from `xkb_keymap_get_as_string` is what V2 accepts. Do not pass `XKB_KEYMAP_FORMAT_TEXT_V2` (the integer 2) as the Wayland format.
4. **Do not vendor Hyprland's `protocols/virtual-keyboard-unstable-v1.xml`.** That v0.56.2 copy mentions `keymap_format` and `key_state` and does not define them. The plan's wayland-protocols path is the right file (`share/wayland-protocols/unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml`). `regenerate.py` must seed the import map from core `wl_*` the way it already does; scanning this XML alone `KeyError`s on `wl_seat`.
5. **`release_all` with no keyboard object must still lift buttons.** The plan says a missing global is not fatal, and also says `release_all` grows key-ups and a `modifiers(0,…)`. If the key half throws, `_expire_pointer`'s one `release_all` stops lifting buttons. Key-ups and `modifiers` run only when `create_virtual_keyboard` succeeded.
6. **Upload failure is exit 10 and must not `listen`.** A keymap Hyprland rejects is `noMemory` on that resource, i.e. a dead connection. Layout rejection before connect stays exit 2. The plan specifies only the second.
`ManagerTooOld` wording in the plan matches the code. "No per-output target" matches the XML (`create_virtual_keyboard(seat)` only) and is why `key` must not go through `_aimed()`.
---
## A. Surface and lease
§4 and §5 hold, with one contract edit the plan already schedules (§3.3 key mirror, §3.4 ops and argv, §4 verb rows). Do not renumber `ExitCode`. New verbs do not call `touch`.
**Exit codes do not match the pointer path the plan says it copies.**
`_drive` turns every driver `ok: false` into `ManagerError("driver_refused")` (`manager.py`), and `driver_refused` is exit **10** (`protocol.py` `EXIT_CODE_FOR_ERROR`). An unknown button is not exit 2: `_button_name` only checks "non-empty string", and `test_an_unknown_button_is_refused_by_the_driver_not_invented` asserts `driver_refused`. The plan says both "Rejected, same as a bad button" and "exit 2 for a bad keysym or an unmappable character". Those are different codes. Exit 2 happens only for `invalid_argument` raised in the broker **before** `_drive` (`_checked_count`, a non-string button).
So, as written:
| Case | What the plan says | What the current mapping does if resolution stays in the driver |
| --- | --- | --- |
| text longer than 4096 scalars | `invalid_argument` (2) | 2, **if** the broker checks `len` before `_drive`. The driver check alone is 10. |
| bad keysym, `é` on `us`, C0 other than `\n`/`\t`, dead key, `type` while a non-modifier is held | 2 | **10** `driver_refused` |
| no keyboard global, or the Wayland connection died | 10 | 10. Right. |
| no lease / other holder | 9 | 9 via `_refresh`. Right. |
| second `pointer.acquire` | 8 | 8. Right. `keyboard.*` must not call `acquire`. |
Pick one before Stage 1. Recommended, because a bad character is not a dead compositor: broker rejects non-string text, the 4096 cap, and a bad `state` as `invalid_argument`. Driver rejections that are caller errors carry a stable token (not only a sentence), and `_drive` maps that token to `invalid_argument`. `driver_refused` stays "the keyboard global is missing". Copying the button path and then asserting exit 2 in the tests will fail.
**Acquire's own stderr contradicts the lease story.** `__init__.py` prints "expires in … with no further **pointer** verb". A `keyboard.*` verb that goes through `_refresh` moves `expires_at`. That sentence has to say any pointer or keyboard verb. Otherwise the TTL test looks "flaky" against the help text.
`type` refreshes once per broker verb because `_refresh` is once per verb. It must not call `refresh` per character. Explicit modifier holds live in `_Held.keys` across later `type`s; `release()` drops the whole `_Held`, so the mirror does not leak into the next holder. `pointer_release` already calls `_release_all_buttons` before `PointerLease.release`. One extended `release_all` covers keys. Audit for release already has `buttons_lifted` from the **driver** list, not from `LeaseOutcome` (`pointer_release`). `keys_lifted` goes next to that field, not into a new release body. `pointer_lease_timeout` already records `pressed` and `buttons_lifted`; add `keys_lifted` there.
`_refresh` still requires a container output (`_pointer_output`). Typing has no output argument, but the lease gate does. A session with no container gets `no_container` (exit 10) the same way a click does. That is existing behaviour, not a new keyboard rule. Do not special-case it.
---
## A. Idempotency and audit
A completed `keyboard.type` with a given `request_id` does not type twice, **for the same reason a completed click does not click twice**: lookup hits, the handler is not called, the reply is the stored object plus `deduplicated: true`. A stored failure is replayed too (`test_a_recorded_failure_is_replayed_as_the_failure_it_was`), so a retried unmappable `type` must not touch the sink either.
The plan does not get a stronger guarantee than click, and it should not claim one:
- The cache key is `request_id` alone (`IdempotencyCache.lookup`). A `keyboard.type` that reuses a `pointer.click` id returns the click reply and does not type.
- `remember` runs after the handler returns. Two connections in flight with the same id both miss the cache. The driver lock serialises the Wayland writes; it does not collapse them. Both strings are typed.
- Capacity is `DEDUP_ENTRIES` (64). An older id is forgotten and will type again.
- A driver death **mid-string** is not the unmappable case. Validation-before-emit stops a bad character from typing a prefix. A connection drop after character 2 of 5 still typed 2, the error is then cached, and the replay does not finish the word or undo it. Click has the same hole between down and up. Say so; do not let the "no prefix" sentence cover it.
Audit: `keyboard_key` may store the keysym name and `down`/`up`. `keyboard_type` stores `chars` (scalar count) and nothing else from the string. Driver logs and `Rejected` messages must use an index ("unmappable at scalar 3"), not the character and not the string. `emit` will happily write a `text` field if a caller passes one. The shell and `ps` still show the CLI argument; that is outside this audit rule.
---
## A. Correctness traps
### Typing `A` (nothing else held, layout `us`, model `pc105`)
Evdev `KEY_A` is **30**. The XKB keycode is 38. The Wayland `key` request and `wl_keyboard.key` both carry **30**. Shift's modifier index on the evdev `us` map is 0, so the depressed mask is `1 << 0` = **1**. Do not hardcode 1 in the resolver; ask xkbcommon (`xkb_keymap_key_get_mods_for_level` or the equivalent level lookup). On `us` the lookup returns 1.
`devices/Keyboard.cpp` (libinput keyboards) calls `updateXkbStateWithKey`. `devices/VirtualKeyboard.cpp` does not: `updatePressed` only edits `m_pressed` (`IKeyboard.cpp`). A virtual `key(KEY_LEFTSHIFT)` does **not** change Hyprland's modifier mask and does **not** cause `wl_keyboard.modifiers`. The `modifiers` request is required. The plan is right.
Sequence on `zwp_virtual_keyboard_v1`, one object, `time` from `_now_ms()`:
```
modifiers(mods_depressed=1, mods_latched=0, mods_locked=0, group=0)
key(time, key=30, state=1) # pressed
key(time, key=30, state=0) # released
modifiers(0, 0, 0, 0)
```
Not in that sequence: evdev 42 (`KEY_LEFTSHIFT`), XKB code 38, a pointer `frame`. `modifiers` goes **before** the key. A client that decodes with the mask from the last `wl_keyboard.modifiers` (foot, GTK) emits `a` if the key comes first.
`keyboard down Shift_L` is the other path, and the plan is right to keep it different: send `key(42, pressed)` **and** `modifiers(1, 0, 0, 0)`, and remember both. `release_all` key-ups in press order, then `modifiers(0, 0, 0, group)`. The `modifiers(0)` is not optional. Virtual key-ups do not clear the mask, because `updateXkbStateWithKey` never runs for this device. A `release_all` that only key-ups leaves Shift latched in every client that trusts the mask.
`type` while `Shift_L` is already held ORs the character mask with that baseline (still 1 for `a`) and must not emit a second Shift key. `type` while a non-modifier is held emits nothing. The plan never defines "modifier". Define it as the keysyms that contribute to the depressed mask on this keymap: `Shift_L/R`, `Control_L/R`, `Alt_L/R`, `Meta_L/R`, `Super_L/R`, `Hyper_L/R`, `ISO_Level3_Shift`, `ISO_Level5_Shift`. `Caps_Lock` and `Num_Lock` are locks, not that set; v1 rejects `type` while they are held. A Shift-only special case fails the `de` VM check (`@` is a level-3 mask, not Shift).
Ctrl is index 2, mask 4, on the same map. `down Control_L` then `type c` is `modifiers(4)`, `key(KEY_C)`, `modifiers(4)`, and `Control_L` still in `keys`.
### Warp does not guarantee `wl_keyboard.enter`
The plan's risk is right, and understated. v0.56.2 already answers it for the shipped config.
`onMouseWarp` calls `mouseMoveUnified(time)` with `refocus=false` (`InputManager.cpp`). With `follow_mouse == 1`, the distance added to `m_mousePosDelta` is the distance of **this** warp only when the previous cursor movement was **under 0.5 s** ago; otherwise the delta is set to 0. Keyboard focus then requires `m_mousePosDelta > follow_mouse_threshold` or `refocus`. The threshold option defaults to **0**, so the test is `> 0`. One warp after the cursor has been still does not pass it.
Pointer focus is updated later in the same function with no threshold. That is why `vm-pointer` saw clicks land, and why `follow_mouse = 0` delivered clicks to nobody (`hyprland-conf.nix` comment, `checks/vm-pointer.nix` header). Those measurements are not `wl_keyboard.enter`.
`rawWindowFocus` still runs if `keyboardFocus == nullptr`. A single mapped window is usually focused at map time, so a one-window probe prints `enter` and proves nothing about the warp. `cursor.no_warps = true` in our conf blocks `PointerController::warpTo`, not a virtual pointer's `warpAbsolute`. The cursor does move. Focus still does not.
A second warp inside 0.5 s adds a non-zero delta and can focus. Stage 0 has to measure **one idle warp** and **a second warp inside the window** separately. `dispatch focuswindow` stays the fallback the plan names, and it is likely mandatory, not a surprise Stage 4. Do not build it in Stage 1. Do not write Stage 3's enter assertion against one window.
**[AMENDED after Stage 2 — "likely mandatory" was the wrong prediction.]** Stage 0 measured exactly what this paragraph predicted, and the fix that shipped is the **second warp**, not the focus dispatch: `pointer_acquire` sends a nudge and then the target, which is the "second warp inside 0.5 s" above. `focuswindow` did ship, but as the narrow fallback for a nudge that could not be *sent*, inside acquire — not as the mechanism that moves focus. So Stage 4 is not pending work of any kind. See `docs/CONTRACT-sessions.md` v3 §4 and §B3 subtest 1 below.
### Destroy, expiry, `kill -9`
Three different paths.
| Path | What runs | v0.56.2 result |
| --- | --- | --- |
| TTL, `pointer release`, kill/reap of the **holder** | Broker `release_all`: button-ups, key-ups, `modifiers(0,0,0,0)`. Object stays. | Keys and mask clear **if we send them**. `input:virtualkeyboard:release_pressed_on_close` is irrelevant. |
| Driver `SIGTERM` | `__main__.py` `finally` → `_lift_everything` → `release_all`, then `sink.close`. | Same, once `release_all` lifts keys. The comment today says buttons only. |
| `destroy` of the resource, client disconnect, `kill -9` | `CVirtualKeyboardV1Resource::destroy`. `releasePressed()` runs only when `input:virtualkeyboard:release_pressed_on_close` is true. | Default is **false** (`ConfigValues.cpp`; device default `INT{0}` in `ConfigManager.cpp`). No key-ups. `releasePressed` emits key-ups only, never `modifiers`. The destructor emits `destroy` and does not release. |
Stuck keys are worse than "a key stays down". `InputManager::onKeyboardKey` drops a press whose code is already in the seat's `m_pressed`, and drops a release that is not (`if (CONTAINS && pressed) return`). After `kill -9` with the default config, that code stays in `m_pressed`. The next driver's `key down` for it is ignored. The seat looks dead for that key until some client sends a matching `key up`.
Required plan change, one line in `nix/hyprland-conf.nix`: `input:virtualkeyboard:release_pressed_on_close = true`. Still send explicit ups on the clean path. Still send `modifiers(0, 0, 0, 0)` once after the initial keymap upload, because even the true setting does not clear a mask, and a client keeps the last `wl_keyboard.modifiers` until the next one. Stage 0 confirms the running binary; the default in this tree is not an open question with even odds.
`share_states` defaults to 2 (`only_non_ime`). Our client is not an IME grab, so the mask Hyprland forwards is the OR of every sharing keyboard (`shareModsFromAllKBs`). Headless config sets `WLR_LIBINPUT_NO_DEVICES=1` (`module.nix`). With no second keyboard the OR is a no-op. A second virtual keyboard with Shift held will keep Shift in the forwarded mask after our `modifiers(0)`. Not v1's problem; do not paper over it with a retry loop.
### Auto-repeat
Hyprland does not re-send `wl_keyboard.key` for a held key. It stores `input:repeat_rate` (default **25**) and `input:repeat_delay` (default **600**) on the keyboard and sends `wl_keyboard.repeat_info` (`Seat.cpp`). The client repeats. `KeybindManager`'s timer repeats **binds**, and virtual keys go through `onKeyEvent` unless the client is the IME (`shouldIgnoreVirtualKeyboard`). A bound key may never reach the window, and the bind may repeat.
The plan's "if Stage 0 shows no repeat, the help text stays quiet" is the wrong gate. A raw client that counts `wl_keyboard.key` will see one press. foot/GTK/Qt will insert characters until key-up or TTL (default 30 s) from that one press plus `repeat_info`. `keyboard down` of a non-modifier must say so in the help text regardless of the probe. `type` and `keyboard key` are taps (down then up) and stay under the delay if the pair is immediate. The justified hold is a modifier chord, which clients do not repeat as text.
There is no `repeated` state on `zwp_virtual_keyboard_v1.key` (Wayland's `wl_keyboard.key_state.repeated = 2` is client-facing, since version 10). We cannot ask the compositor for a repeat rate.
---
## A. Changes required before code, cheapest first
| # | Change | If it waits until after Stage 1 |
| --- | --- | --- |
| 1 | Resolve exit 2 vs `driver_refused`. Broker-side checks for shape and the 4096 cap. A distinct driver token for "your keysym/character", mapped to `invalid_argument`. Missing global stays 10. | Help text, `test_exit_codes.py`, and every verb test encode the wrong code. |
| 2 | Keymap `size` includes the NUL; fd stays alive across `flush`. `format = 1`. `time` is `_now_ms()`. | First real `type` kills the driver or types nothing. Looks like "Hyprland has no global". |
| 3 | `release_all` no-ops the key half when no virtual keyboard exists. `modifiers(0,…)` after upload, and at the end of every `release_all` that touched a mask. | A missing global breaks button expiry. A crash mid-`A` leaves Shift on for the next holder. |
| 4 | Set `input:virtualkeyboard:release_pressed_on_close = true` in `hyprland-conf.nix`. Document that this still does not clear the mask. | First `kill -9` during Stage 1 poisons `m_pressed`. Later downs of that key vanish. |
| 5 | Layout option as specified above, on the unit argv. Driver rejects `,` before `xkb_keymap_new_from_names`. Do not treat `[keyboard]` in the TOML as the upload path. | VM "non-us" checks the broker file, the driver stays on `us`, test is a false pass or a surprise. |
| 6 | Write down the modifier-keysym set. Resolver returns `(evdev, mask)` for any level, not a Shift special case. `key`/`type` do not call `_aimed()`. | `de` and Ctrl+C get a second code path that disagrees with `us`. `type` without a prior warp fails only in a test that forgot to acquire. |
| 7 | Stage 0 expectations: one idle warp does not `enter`; destroy with the default config does not release; one held key is one `wl_keyboard.key`, while `repeat_info` is still sent. Help text for `down` warns unconditionally. Two-window probe, or the enter result is a false pass. | Stage 3 goes red, or goes green because the only window was focused at map time. Stage 4 arrives as a surprise. |
| 8 | Acquire stderr says keyboard verbs refresh the TTL. `Rejected` text and driver logs carry an index, not the string. | Operators release during a `type` that would have kept the lease. A password lands in the journal even though `events.jsonl` is clean. |
Not required to change: the protocol choice, the process boundary, the single lease, names-vs-evdev, no `frame`, no `touch`, `expire()`'s return type, one `release_all`, mutation-set replay, `chars` not `text`, single group, xkbcommon as a hard test dependency, a real VM check.
---
## B. Tests
Gate for Stages 1–2 stays `nix develop -c python -m pytest tests/pointer tests/sessions/unit -q`. No test sleeps except the VM and the Stage 0 probe. No test in `tests/sessions/integration/` grows a fake compositor.
### B1. Stage 0 probe
One throwaway client, not committed, not run via the broker. It is not `hhstream`. It does not open `/run/hhstream/control.sock` or `pointer.sock`.
Run it as the broker account (supplementary group `hhstream`, `module.nix` `sessions.user` description — that group is what makes `wayland-*` openable; the directory is `0750`):
```
sudo -u hermes -g hhstream env \
XDG_RUNTIME_DIR=/run/hypr-stream \
WAYLAND_DISPLAY="$(sudo -u hermes -g hhstream \
find /run/hypr-stream -maxdepth 1 -name 'wayland-*' ! -name '*.lock' -printf '%f\n')" \
python3 /tmp/kb-probe.py
```
Refuse to start if `find` prints more than one name (`backend.py` `find_wayland_display` does). Read-only `hyprctl` (`clients -j`, `monitors -j`, `getoption`) is allowed so the warp hits a known box. `hyprctl dispatch` is not allowed: `dispatch focuswindow` answers question (a) by cheating.
The script uses pywayland. It binds `wl_compositor`, `wl_shm`, `xdg_wm_base`, `wl_seat`, `wl_output`, `zwlr_virtual_pointer_manager_v1`, `zwp_virtual_keyboard_manager_v1`. It prints every global as `global <name> v<version>` and exits 2 if the keyboard manager is missing or not version 1. Two `xdg_toplevel`s, app ids `kb-probe-a` and `kb-probe-b`, both mapped and acknowledged. `wl_keyboard` listener prints, flushed:
```
enter surface=<app-id> serial=<n> keys=[...]
leave surface=<app-id>
repeat_info rate=<n> delay=<n>
keymap bytes=<n> symbols=<snippet>
modifiers depressed=<n> latched=<n> locked=<n> group=<n>
key code=<evdev> state=<0|1|2> sym=<name>
```
`sym` comes from `xkb_state` built from the **keymap fd the compositor sent**, updated with `xkb_state_update_mask` on `modifiers` and `xkb_state_key_get_one_sym(key+8)` on `key`. Not from a table inside the script.
Sequence, printing a banner line before each step:
1. Map A, map B. Sleep 0.6 s so the cursor has been still longer than Hyprland's 0.5 s window.
2. **(a1)** One `motion_absolute` of a virtual pointer bound to B's output, into A's box (normalised, from `hyprctl clients`). Sleep 0.3 s. Assert-by-printing: no new `enter` for A. An `enter` here means this binary does not match the v0.56.2 threshold logic; say so and continue.
3. **(a2)** A second warp, still inside A, immediately. Print whether A then gets `enter` and B gets `leave`. This is the double-warp question, separate from (a1).
4. Upload an `us` / `pc105` keymap (`format=1`, `size` includes NUL) on a virtual keyboard. Print `uploaded`.
5. **(c)** `key(KEY_A=30, pressed)` once. Sleep 1.5 s (longer than the 600 ms default delay). Print `press_count=<n>` of `state=1` or `state=2` events for code 30. Do not key-up yet.
6. **(b)** `destroy` the virtual keyboard. Roundtrip. Sleep 0.2 s. Print `release_on_destroy=<yes|no>` and `mask_cleared=<yes|no>`. Do not send `key up` or `modifiers` before this.
7. Cleanup, required: a **new** virtual keyboard, keymap again, `key(30, released)`, `modifiers(0,0,0,0)`, destroy. Print `cleanup=sent`. This undoes a poisoned `m_pressed` if step 6 released nothing.
**(a) passes** only if the log shows, in order: B entered at map; after (a1) A has no new `enter`; the line says which warp, if any, produced A's `enter`. A pass that is a lie: only one window, or `enter` counted with no check that it happened after the warp rather than at map, or a `hyprctl dispatch focuswindow` before the warp.
**(b) passes** as a measurement, not as a green feature: print the `getoption` value of `input:virtualkeyboard:release_pressed_on_close` next to `release_on_destroy`. On v0.56.2 with the default, expect `release_on_destroy=no` and `mask_cleared=no`. A pass that is a lie: the script sent `key up` before `destroy`, or it counted a release from step 7.
**(c) passes** as a measurement: `press_count` and the `repeat_info` line are both printed. Expect `press_count=1` and a non-zero rate on this source. Interpreting `press_count=1` as "`keyboard down` will not flood a text field" is the false pass. The flood is the client's repeat, which this probe does not implement on purpose.
### B2. Unit tests (Stages 1 and 2)
Match existing files. Dispatcher tests use a recording sink and do not grant authority (`tests/pointer/test_ops.py` module docstring). Lease tests use the injected clock (`tests/pointer/conftest.py`). Broker tests use the real UNIX socket and `FakeDriver` (`tests/sessions/unit/test_pointer_verbs.py`).
`tests/pointer/test_keymap.py` — real xkbcommon, not a stub.
| Case | Pass | False pass |
| --- | --- | --- |
| `us`: `a` → `(30, 0)`; `A` → `(30, mask)` with mask equal to `1 << xkb_keymap_mod_get_index(..., "Shift")`; `Return` and `"\n"` → `KEY_ENTER` (28); `Tab` and `"\t"` → 15 | Those tuples | Asserting xkb code 38, or hardcoding mask `1` without reading the index (breaks the day the resolver is used for `de`) |
| `""` → `[]` | Empty, no error | |
| `"é"`, `"\x01"`, keysym `dead_acute` raise | Exception type the dispatcher already maps to `Rejected` | Asserting the message contains `é` (that string would be logged) |
| `"abé"` through the dispatcher | `ok: false` and **zero** sink calls | Asserting only that no event carried `é`, while `a` and `b` were emitted |
| 4096 scalars of `a` accepted; 4097 rejected with zero sink calls; one case is 4096 scalars of `😀` (`len == 4096`) | Boundary as scalars | ASCII only: a byte cap and a scalar cap agree, so a `len(utf8)` check stays green |
| Two `type`s | The keymap **object** is built once, and the sink's `keymap` method is called once | Asserting only that `keymap.py` returns equal strings. A backend that uploads on every `type` stays green |
`tests/pointer/test_ops.py` — extend `RecordingSink` with `key(code, state)` and `modifiers(dep, latch, lock, group)`.
| Case | Pass | False pass |
| --- | --- | --- |
| `key` `down` then `pressed` | `keys == ["Return"]` (name, not 28) | |
| `up` of a key that was not down | `ok: true`, not listed as lifted. Same as `unpress` | |
| `release_all` after `Control_L` then `a` | key-ups in that order, then one `modifiers(0,0,0,0)`, even if the last warp was a different output. No `frame` added for the keys | A sink that ignores the output argument. Warp to output B and assert the key calls were not tagged with B |
| `type "A"` with nothing held | `modifiers(shift), key(30,1), key(30,0), modifiers(0,…)` and `keys == []`. No code 42 | Asserting the sink was called at all, or that some event's code was 30, without the mask before the press and without the absence of 42 |
| `type` with `Control_L` held | Mask ORed, `Control_L` still in `keys`, no Control key-up | |
| `type` with `a` held | `ok: false`, zero new sink calls, `a` still held | |
| `type "Hi"` with **no prior warp** | Keys emitted. Must not return the `_aimed()` error | Every test warps first because it copied `test_ops` helpers. Delete the warp in this one test |
| `release_all` when the sink has no keyboard | Buttons still lift; no exception | Only running it when the keyboard exists |
`tests/pointer/test_lease.py` — `press_key` order matches `press`. `expire()`'s return has no key list. The test reads `keys_pressed()`, then `expire()`, then sees no holder. Existing busy / stale / `lease_id` tests stay.
`tests/pointer/test_vendored_protocol.py` — interface `zwp_virtual_keyboard_manager_v1`; requests `keymap`, `key`, `modifiers` on `zwp_virtual_keyboard_v1`; enum values `xkb_v1 == 1`, `pressed == 1`, `released == 0`. No display.
`tests/sessions/unit/test_keyboard_verbs.py` — copy the `test_pointer_verbs.py` harness.
| Case | Pass | False pass |
| --- | --- | --- |
| No lease, and another session holds it | `no_lease` (exit 9), not `pointer_busy` | |
| Second `pointer.acquire` while a key is held | `pointer_busy` (8). The held key is still the first holder's | Acquiring from the holder and treating 8 as success |
| `type` and the clock | Advance less than `ttl` after `type`: holder remains. Advance past it: one `release_all`, and that reply's `lifted_keys` contains the key that was down | Advancing the clock without running `_expire_pointer` / the sweep. The unit test must call the sweep or the next verb, the way the pointer expiry test does |
| Driver `ok: false` on `key` | Lease `keys` unchanged | Asserting the error only |
| `type` | `last_activity_boottime` and `command_count` unchanged | `command_count` alone if a future change updates the timestamp without counting a command. Assert the timestamp |
| `pointer.release` and `kill` | Driver `lifted_keys` contains what was down; `pointer.state` holder is null; `keys` is `[]` | `kill` of a session that does not hold the lease (green, lifted nothing) |
| `pointer.state` | `keys` present, names not codes | |
| Replay | Same shape as `test_a_retried_click_…`: second reply `deduplicated: true`, sink `key` count unchanged. Also replay an **unmappable** `type`: still zero sink calls | Asserting `deduplicated` and not the sink. A handler that types and then sets the flag stays green |
| Unmappable / over cap at the broker | Exit 2 `invalid_argument` for the cap and for a non-string. Exit 2 for an unmappable character **only after change 1**; until that mapping exists this assertion fails, which is the point | Treating `driver_refused` as 2 because the CLI printed "usage" somewhere in the hint |
`tests/sessions/unit/test_settings.py` — only if `[keyboard]` is actually read. If the option lives solely on the unit argv, this test does not belong here; a TOML default of `us` that nothing uploads is the false pass `test_settings.py`'s own docstring warns about. Prefer asserting the driver's flag parser: omitted `--xkb-layout` is `us`, `--xkb-layout de` is `de`, `--xkb-layout us,ru` exits 2 and does not connect (inject a connect function and assert it was not called).
`test_cli_surface.py` — `keyboard` in `hhstream session --help`; the keyboard help says exit 9 until `pointer acquire`; `pointer --help` does not grow a keyboard tutorial. False pass: the word `keyboard` appears in the pointer help because of the acquire-stderr fix, and the test greps the whole binary help.
`test_broker_protocol.py` — `keyboard.type` and `keyboard.key` in `VERBS` and `MUTATING_VERBS`; `pointer.state` still absent from the mutating set. `test_every_verb_the_protocol_names_is_one_the_daemon_answers` already fails if only one of the lists is updated. Keep it.
`test_exit_codes.py` — no new integer. If a new error **name** is added for the driver token, map it in `EXIT_CODE_FOR_ERROR` and add a row. A name that is not in the table becomes exit 4 `BAD_STATE` (`exit_code_for`). That is the false pass for "we return 2": the CLI exits 4 and the test only checked `ok: false`.
### B3. VM proof (Stage 3)
New `checks/vm-keyboard.nix`, same shape as `checks/vm-pointer.nix` (`testers.runNixOSTest`, `session-machine.nix`, `session-prelude.nix`, `globalTimeout` on the order of `vm-pointer`'s 1800). Do not fold it into `vm-pointer`. Real time, no injected clock; the expiry subtest in `vm-pointer` says why.
Victim: a sibling of `checks/lib/pointer_target.py`, not foot and not Chromium. It sets `xdg_toplevel` app id from `$HHSTREAM_APP_ID` (the reason `pointer_target.py` exists: foot ignores the variable and is quarantined). It prints the same keyboard lines as the Stage 0 probe, from the keymap fd. Read-back is `hhstream session logs`, as in `vm-pointer`.
Subtests:
1. **Enter.** Two sessions, A and B, B started last so B is focused (the `vm-pointer` measurement that already bit them). `pointer acquire` on A. A's log shows `enter` for A's app id **after** the acquire, and B's log shows `leave`. The assertion is not weakened to "cursor coordinates look right".
**[AMENDED after Stage 0 and Stage 2 — this said "one warp", and "expected red until the double-warp or `focuswindow` fallback is in".]** Stage 0's (a1) did measure "no enter", and the answer shipped in Stage 2: **acquire is two warps**, a real pixel apart, which is the double-warp this sentence anticipated. So this subtest is a live assertion, not an expected red. `focuswindow` also shipped, but it is *not* what makes this pass — it runs only when the nudge warp cannot be sent — so the check additionally requires the reply's `focus == "warp"` and treats `focuswindow` or `none` as failure. And it asserts `wl_pointer.enter` on A separately from `wl_keyboard.enter`: a check that saw only the cursor arrive would go green while A had the cursor, B had the keys, and the first keystroke of the lease went to B. `docs/CONTRACT-sessions.md` v3 §4 is the authority on the mechanism.
2. **`keyboard type` of `A` then of `hello`.** A's log contains, in order, `modifiers depressed=1`, `key code=30 state=1 sym=A`, `key code=30 state=0`, `modifiers depressed=0`, and **no** `code=42` on that span; then five key downs decoding to `h,e,l,l,o`. B's log has no `key ` line from this span.
3. **TTL.** `keyboard down Shift_L`, `--ttl` of a few seconds, wait it out in real time. A's log shows code 42 released and `modifiers depressed=0`. `pointer state` has `holder` null and `keys` empty. A second `pointer acquire` from B during the hold, before the wait, exits 8.
4. **Layout.** Same VM expression with `sessions.keyboard.layout = "de"` (module argument, so the unit argv changes). Do **not** set Hyprland `input:kb_layout` (leave it unset / `us`). `keyboard type y` decodes to sym `z`; `keyboard type z` decodes to sym `y`. The keymap line from the fd contains the symbols name `de`.
False passes:
| Assertion | Looks green while broken |
| --- | --- |
| Characters on A | The log is searched for the substring `hello`, and the session log also contains the broker command or the test script echoing the argument. Match `sym=h` lines from the victim only. `pointer_target.py` prints what the **client** received for this reason |
| Silence on B | B never bound `wl_keyboard`, or B's window was never mapped, so B is silent even when focus is still on B and A also received nothing. (1) and (2) are one assertion: A positive and B negative |
| Keymap was uploaded | A decodes `hello` with a keymap compiled inside the victim. Require the sym to come from the fd, and fail the subtest if no `keymap bytes=` line precedes the keys. The plan's mutation rule (`PLAN` §14): keycodes without a decoded `hello` are a failure |
| Non-`us` | The test greps the guest's systemd unit for `--xkb-layout de` and never types `y`. Or Hyprland `kb_layout` was also set to `de`, so a client that ignored our keymap still decodes `z` |
| TTL key-up | The waiter matches a `state=0` from the earlier `hello` taps. Use code 42, which `type` must not emit |
| Second acquire exits 8 | A leftover holder from a previous subtest. This subtest acquires, holds, and only then has the other session acquire |
| Enter | One session. Map-time `enter` satisfies "A saw enter" |
Stage 0's script is the wrong place to prove the broker lease. The VM is the wrong place to prove replay. Keep them apart.
---
## If I had to bet
The plan is safe to **build on** and not safe to **implement as written**.
I would not reopen `zwp_virtual_keyboard_v1`, the pointer process, the single lease, keysym names on the broker and driver sockets, or "Shift for `A` is a mask". Those match the code and, for the mask, match Hyprland v0.56.2 (`updateXkbStateWithKey` is only on the libinput keyboard).
I would refuse a Stage 1 that starts from the plan text unchanged. The exit-code paragraph disagrees with `_drive` and with `test_an_unknown_button_is_refused_by_the_driver_not_invented`. The keymap upload omits the NUL that Hyprland's `mmap` requires. Destroy-while-held is not an open question in this tree: `release_pressed_on_close` defaults to false, and the true setting still does not clear modifiers, so `kill -9` poisons `m_pressed`. A single idle warp does not send `wl_keyboard.enter` under `follow_mouse = 1` with the default threshold; a one-window VM check will say it did. The layout option the operator asked for reaches the keymap only as `--xkb-layout` on `hhstream-pointer`, not as a `[keyboard]` table copied from `[pointer]`.
Those are plan edits, all cheaper than the first driver commit. After them, Stage 0 is a measurement against `/run/hypr-stream` with the expectations above, not a research project, and Stage 1 has a test that goes red for a prefix-typed `é`, a second keymap upload, a replay that types twice, and an `A` that was a Shift keycode instead of a mask.
+128
View File
@@ -0,0 +1,128 @@
# Stage 0 review — keyboard probe
Reviewed `d07a1fd` (the plan fold-in) and `19e484b` (the probe, its README, and `tests/keyboard-probe-2026-10-04.txt`) against §B1 of `docs/plans/2026-10-04-keyboard-verification.md`. The three probe files are that commit, not an untracked add-on. Dirty Stage 1 files in the worktree were not reviewed and were not touched. The probe was not re-run: this environment has no `HYPRLAND_INSTANCE_SIGNATURE`, so the judgement is the committed transcript read against the script that prints those answer strings.
## Verdict
**Yes-with-fixes.** The run measured the gate and questions (a1), (b)'s key, and (c). The write-up then says things the log does not say, and `d07a1fd` did not edit the plan. Do not design Stage 3 from the README's (a) excerpt or from its mask sentence. The raw log, read with the script, is usable.
## What the evidence actually shows
The script is the B1 sequence with three real deviations and one hole. It is not a one-window probe, it does not call `hyprctl dispatch`, it refuses a runtime directory that does not contain exactly one `wayland-*` (`tests/keyboard_probe.py:378-389`), it dumps every global as `global <name> v<version>` (`:759-760`) and returns 2 when `zwp_virtual_keyboard_manager_v1` is missing or not version 1 (`:761-770`). `sym` is `xkb_state_key_get_one_sym(code+8)` on a state built from the keymap fd, updated with `update_mask` (`:575-609`, `:627-632`). Cleanup sends `key(30, released)` and `modifiers(0,…)` on a new virtual keyboard and prints `cleanup=sent` (`:940-945`). Deviations, all visible in the log: the keymap is uploaded before the windows rather than after (a); the idle wait is 0.8 s not 0.6 s; (a2) is 0.4 s after (a1), not immediate.
### Gate
Log lines 6–75 are the registry. Line 71 is `global zwp_virtual_keyboard_manager_v1 v1`. No `wp_virtual_keyboard_v1` line. Line 76: `ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1.` Line 59: `zwlr_virtual_pointer_manager_v1 v2`. That is the gate. The project continues.
### (a)
**The log does not prove "a warp onto an unfocused window delivered `wl_keyboard.enter`."** That sentence is the natural reading of the README's annotation "focus, one warp late" (`tests/README-keyboard-probe.md:129`) and of the commit message, which hangs both results on "warping into the margin that belongs to the first alone." The warp into that margin is (a1). It did not deliver keyboard enter.
What the log actually contains, in order:
```
108| (a1) one warp after 0.8s of stillness
109| (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7
110| (a2) a second warp, immediately, still inside the same window
111| (a2) -> modifiers depressed=0 latched=0 locked=0 group=0
112| (a2) -> leave surface=kb-probe-b
113| (a2) -> enter surface=kb-probe-a serial=371 keys=[]
117| a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes
```
(a1) is the warp onto unfocused `kb-probe-a`. The only event in its bucket is `wl_pointer.enter` at 13,7, which is the chosen point: target `0.0100,0.0100` (log 107) on a 1280×720 output is about (12.8, 7.2), and B's box starts at 120,80 (log 105), so the point is inside A only. No `enter surface=kb-probe-a` keyboard line in that bucket. `a1_enter=no` is true, and the `startswith` test (`keyboard_probe.py:820-825`) is what keeps `wl_pointer.enter` from counting. Map-time focus was B (log 89–90 and 106), so this is not the one-window false pass.
The keyboard `leave`/`enter` are the next bucket. That bucket is the second `motion_absolute` (`keyboard_probe.py:816`: same x, y plus 0.004), sent while the pointer was already on A. There is no second `wl_pointer.enter`, because the probe does not listen for `wl_pointer.motion` and pointer focus did not change. So the leave/enter arrived on the motion *after* the warp onto the window, not on the warp onto the window.
The sentence the log supports is: an idle `motion_absolute` onto unfocused `kb-probe-a` delivered `wl_pointer.enter` and no `wl_keyboard.enter`; `wl_keyboard.leave` of B and `wl_keyboard.enter` of A (serial 371, `keys=[]`) were observed only in the settle window after a later `motion_absolute` that stayed inside A.
Line 118's narrower claim — "one idle warp did NOT deliver enter; the SECOND warp did" — matches the buckets, with two caveats the file does not write down. The second request is not "immediate": `question_focus` pumps `SETTLE_S` (0.4 s, `keyboard_probe.py:124` and `:812`) and prints the (a1) lines before sending it, and the banner hardcodes the word (`:815`). And it is not a repeat of the same point. In the v0.56.2 `InputManager.cpp` on this machine, `mouseMoveUnified` returns immediately when the floored pixel did not change (`:239-240`), *before* it adds to `m_mousePosDelta` (`:253-256`). Keyboard focus is that delta compared with `follow_mouse_threshold` (`:711-715`). Log 98 says the threshold is 0 and unset, so any non-zero floored distance inside 0.5 s focuses, and a second warp to the same floored pixel does nothing. 0.004 of 720 px is about 3 px, so this nudge cleared that bar. The log never prints the second point, so a reader cannot see that it moved.
`pointer acquire` is one `_warp` (`src/hhstreamd/manager.py:1620`). The consequence that the first key of a lease can hit whatever was already focused follows from (a1) alone, and (a1) supports it. It does not follow from "the landing warp delivered enter, one warp late."
The README excerpt is not the log. It claims a verbatim transcript (`README-keyboard-probe.md:90-91`) and then prints `serial=336` (`:129`). This run's (a2) enter is serial 371 (log 113). Setup enters are 357 and 365 (log 84, 90), so 336 cannot be this run's focus change. The excerpt also drops log 111 (a `modifiers` line *before* `leave`) and the two `configured` lines that follow the enter (log 115–116). "Reproduced across six runs" (`README:89`) has one transcript.
### (b)
**No release: the log shows it. Mask not cleared: the log does not show what that sentence means.**
```
127| spare -> uploaded keymap format=1 size=35572
128| release_on_destroy=no mask_cleared=no
131| cleanup -> uploaded keymap format=1 size=35572
132| cleanup -> key code=30 state=0 sym=a
133| cleanup -> modifiers depressed=0 latched=0 locked=0 group=0
```
There is no `after destroy ->` line. The post-destroy pump is 1.0 s (`keyboard_probe.py:915-916`) and it recorded nothing: no `key code=30 state=0`, no `modifiers`. The script did not send a key-up or a `modifiers` before `destroy` (`:912`). The release it did send is after the verdict, labeled `cleanup ->`. B1's named false pass (counting step 7, or releasing before destroy) is not this log.
The spare keyboard does not weaken the "no release" half. It is created so the seat still has a keyboard (`:904-910`). Log 78–79 show why that matters: capabilities go `1` (pointer) then `3` (pointer|keyboard) only once a virtual keyboard exists, and the seat has no libinput keyboard. The spare never pressed code 30 — its only line is the local `uploaded keymap`. `shareKeyFromAllKBs` swallows a release only when some *other* sharing keyboard still has that code down (`InputManager.cpp:1891-1911`). The spare did not. Silence here is not "the release was delivered to a keyboard we stopped listening on."
The stronger evidence is log 132, which the ANSWER paragraph does not cite. `onKeyboardKey` drops a release whose code is not in the seat `m_pressed` (`InputManager.cpp:1669-1670`). A `state=0` for code 30 from a *new* keyboard means 30 was still in that set after `destroy`. If destroy had released it, the cleanup up would have been dropped and the client would not have seen `state=0`.
`mask_cleared=no` is a different predicate than the README's sentence. The code sets it when the post-destroy bucket contains `modifiers depressed=0` (`keyboard_probe.py:918-919`). The bucket is empty, so the flag is `no`. The depressed mask was already 0: the last modifiers lines are log 111 and 114, and the probe never sent `modifiers` with a non-zero mask. The held key is `KEY_A` (30), not Shift. "Destroy did not emit a modifiers event" is what was measured. "A non-zero mask survived destroy" was not. `releasePressed` emits key-ups only (`VirtualKeyboard.cpp:125-135`), so the source still says a mask would survive, but this run is not that measurement. Log 99 supports the option half only: `input:virtualkeyboard:release_pressed_on_close` is `{"int": 0, … "set": false}`.
The Shift story (`README:156-161`, `keys=[42, 0, 0, 0]`) is not in this transcript. Every `enter` here has `keys=[]` (log 84, 90, 113). Do not treat the zeros, or the claim that a key outlived the process, as data from this file.
The ANSWER's `kill -9` sentence is an inference. The transcript is an explicit `destroy` request. In this tree both that request and client disconnect call the same `CVirtualKeyboardV1Resource::destroy` (`VirtualKeyboard.cpp:38-39`, `:137-140`), which consults the option. Fair inference, not a second experiment.
### (c)
**The log shows exactly one press, and neither the spare, the window, nor `repeat_info` weakens that count.**
```
82| setup -> repeat_info rate=25 delay=600
121| key code=30 state=1 sym=a
122| press_count=1 repeat_info=(25, 600)
```
`press_count` counts `state=1` or `state=2` for code 30 inside the hold pump (`keyboard_probe.py:875-879`). One line, state 1, no state 2. The hold is `REPEAT_HOLD_S = 1.5` (`:120`), which is longer than the 600 ms delay on log 101, not shorter. A compositor that repeated at 25 Hz after 600 ms would have put on the order of twenty more `key` lines in the remaining 0.9 s. It put none. `repeat_info` was delivered at bind time (log 82), before the hold, which is when Hyprland sends it; printing the stored tuple next to the count is what B1 asked. It does not mean the compositor also repeated. The spare keyboard is created in `question_destroy`, after this section, so it is not in the (c) setup. The ANSWER text (log 123) already refuses the false pass: `press_count=1` is not "a text field will not flood." That part of the file is right, and it is the reading Stage 1 should keep.
`sym=a` is from the forwarded keymap, not a table. Log 80–81: uploaded `format=1 size=35572`, and `wl_keyboard.keymap format=1 bytes=35572 symbols=xkb_symbols "pc_us_inet(evdev)"`. The sizes match, which is consistent with the NUL-inclusive memfd (`keyboard_probe.py:312-326`) being what the compositor mapped. The symbols snippet is not the layout string `us`.
## Defects
1. **High. The (a) write-up states a causality the log does not have.** README `:114` and `:129`, and the `19e484b` message, read as "warping onto the unfocused window delivered keyboard enter, one warp late." Log 108–113 say the landing warp delivered `wl_pointer.enter` only, and leave/enter came on the next motion. "One warp late" is the wrong mechanism: the first warp's delta is set to 0 (`InputManager.cpp:255-256`); the enter belongs to the second motion's non-zero delta, not to a delayed effect of the first. Cheapest fix: replace the README excerpt with log 108–117 unchanged, and replace the annotation with the sentence in the (a) section above. Do not leave `serial=336` in the file.
2. **High. `d07a1fd` did not fold the eight changes into the plan.** `git diff 14b3f69 HEAD -- docs/plans/2026-10-03-keyboard-input.md` is empty. The commit adds `docs/plans/2026-10-04-keyboard-verification.md` and nothing else. The commit message is an accurate list of what that review says, and the review text itself is not softened. The plan text is unchanged, so anyone told to follow the plan (the untracked brief says that, and it repeats exit codes 8/9/2/10) still has the contradicted text. Cheapest fix: a banner at the top of `2026-10-03-keyboard-input.md` stating that the eight rows in the verification doc's "Changes required before code" table supersede the plan where they differ. Not done here.
3. **Medium. `mask_cleared=no` is reported as a measurement of a held mask.** README `:150-154`. The mask was 0 the whole time (log 111, 114; no `modifiers` request before destroy). Cheapest fix: one sentence in the README — destroy emitted no key-up and no modifiers event; a non-zero mask was not held, so this run does not show one surviving. Do not re-run unless Stage 2 wants a transcript of Shift specifically. Do not cite the unlogged `keys=[42, 0, 0, 0]` run.
4. **Medium. "A second warp" is underspecified in a way Stage 3 will copy.** The report never says the second point differed, and the same floored pixel returns before the focus test (`InputManager.cpp:239-240`). Cheapest fix: in the README, say (a2) moved about 3 px and that a second `motion_absolute` of the same point is not this result. Printing the second normalised point from `question_focus` would make the next transcript show it.
5. **Low. "Immediately" is hardcoded, and the gap is not logged.** 0.4 s plus the time to print (a1) is still under Hyprland's 0.5 s window, and the fact that (a2) focused is consistent with that. The word in log 110 is not a measurement. Cheapest fix: print the monotonic gap between the two `motion_absolute` calls. Not worth a re-run by itself.
6. **Low. Claims with no transcript.** "Six runs" (README `:89`) and the Shift enter (README `:156-161`). Cheapest fix: delete both, or attach the log. The committed transcript does not contain them.
Not defects: committing the probe (B1 said not to; the commissioning brief said to; the README says so); uploading the keymap before (a) (log 78–80: no keyboard capability until a virtual keyboard exists, so the listener could not have seen enter otherwise); idle 0.8 s instead of 0.6 s; fullscreen A so the two boxes are not the same 1040×560 (log 104–105 shows they were not); the spare keyboard, for the reason under (b).
## What Stage 1 must not build on
- **Do not assert `wl_keyboard.enter` on `pointer acquire`.** Acquire is one warp. (a1) did not enter. Stage 3's enter subtest stays red until a later motion that changes the floored pixel, or `focuswindow`. Do not "fix" it by warping twice to the same bookmark.
- **Do not read "one warp late" as "the enter is delayed, so wait longer."** The (a1) bucket was 0.4 s and contained the pointer enter. The keyboard enter was a different request.
- **Do not gate the `keyboard down` warning on this probe having seen repeats.** It saw one `wl_keyboard.key` and a `repeat_info` of 25/600. The warning stays unconditional. Log 123 already says this; the plan at `2026-10-03-keyboard-input.md:234` still says the opposite ("if it does, the help text says so").
- **Do not cite `mask_cleared=no` as proof a held Shift survives `destroy`.** Keep sending `modifiers(0,0,0,0)` because `releasePressed` never emits modifiers, not because this log held a mask.
- **Do not treat `keys=[42, 0, 0, 0]` as a measured poison.** This transcript's enters are `keys=[]`. The cleanup `state=0` (log 132) is the poison evidence, and it is for code 30 after an explicit `destroy`.
- **Do not expect the scanner to emit `keymap_format` or `key_state`.** The Hyprland XML this probe used names both and defines neither (`protocols/virtual-keyboard-unstable-v1.xml` in the v0.56.2 tree: the request text says "keymap_format enumeration" / "key_state enumeration"; the only enums in the file are `error`). The constants in `keyboard_probe.py:89-95` are the right workaround. The symbols line to match later is `xkb_symbols "pc_us_inet(evdev)"`, not the bare layout name.
- **Do not implement exit 2, the NUL, or the layout path from the 2026-10-03 plan text.** Those paragraphs were not updated. See carried objections.
## Carried objections
`d07a1fd` preserved the eight pre-code changes intact inside the verification doc and dropped them from the plan. Nothing in the eight was rewritten into something unimplementable. Where the plan still disagrees:
| # | Still binding, from the verification doc `:192-201` | Plan text that was not changed |
| --- | --- | --- |
| 1 | Broker checks shape and the 4096 cap. A driver token for a bad keysym or character maps to `invalid_argument` (exit 2). Missing global stays `driver_refused` (exit 10). | `:61` still says exit 2 for a bad keysym, which `_drive` turns into 10. |
| 2 | Keymap `size` includes the trailing NUL. `format = 1`. `time` is `_now_ms()`. | `:25` still says "memfd of an XKB text keymap" and never says `size == strlen + 1`. |
| 3 | `release_all` no-ops its key half when no virtual keyboard exists, and ends with `modifiers(0,0,0,0)` when a mask was touched. Also one `modifiers(0,…)` after the initial upload. | Not stated. |
| 4 | `input:virtualkeyboard:release_pressed_on_close = true` in `nix/hyprland-conf.nix`. The true setting still does not clear the mask. | `:233` still calls destroy-while-held unverified and does not set the option. This run confirms the default is 0 and that explicit destroy releases nothing. |
| 5 | Layout is `--xkb-layout` on the pointer unit. The driver rejects `,` before `xkb_keymap_new_from_names`. A `[keyboard]` table in the broker TOML is not the upload. | `:111`, `:115`, `:176`, `:208` still emit and test `[keyboard]` the way `[pointer]` is emitted. |
| 6 | The modifier-keysym set is written down. The resolver returns `(evdev, mask)` for any level. `key` / `type` do not call `_aimed()`. | `:189` still has the mask-vs-Shift decision and no keysym set. |
| 7 | Stage 0 expectations as B1 wrote them. `keyboard down` warns unconditionally. Two windows, or the enter result is a false pass. | `:234` and `:253` are still the vague originals. The probe did use two windows; the unconditional warning is the right reading of (c). |
| 8 | Acquire's stderr says keyboard verbs refresh the TTL. `Rejected` text and driver logs carry an index, not the string. | Not stated. |
Objection 4 of the verification doc (do not vendor Hyprland's XML; use wayland-protocols `unstable/virtual-keyboard/…`) is the one item this stage showed is not implementable on this nixpkgs. The protocol's wayland-protocols MR never landed; the file the review names is not where the README looked, and the Hyprland copy is the one the probe compiled. Carry the review's actual reason — the copy does not define the enums — not the path. Switching later, if a nixpkgs grows the file, is a one-line change and does not move the integers.
Unchanged and confirmed, so Stage 1 should not reopen them: `zwp_virtual_keyboard_v1` version 1 on the running compositor; no `wp_virtual_keyboard_v1`; one idle warp does not move keyboard focus under `follow_mouse = 1` and threshold 0; do not build `dispatch focuswindow` in Stage 1.
Stage 1: implement from the eight rows in `docs/plans/2026-10-04-keyboard-verification.md`, not from the unedited 2026-10-03 plan; do not assert `wl_keyboard.enter` on acquire's single warp, do not treat a second warp to the same point as the fix, and do not cite `mask_cleared=no` as a held-mask result.
+178
View File
@@ -0,0 +1,178 @@
# Stage 1 review — the driver learns to type
Reviewed `f931858` only (keymap, vendored `zwp_virtual_keyboard_v1`, ops, backend upload, `__main__` flags, the pointer-side lease mirror, and `tests/pointer/`). Uncommitted edits under `src/hhstreamd/`, `src/hhstream_session/`, `nix/module.nix` and `nix/hyprland-conf.nix` are not this commit and were not reviewed. `b1f2744`, which lands after `f931858` and only edits the plan and the Stage 0 write-up, was not reviewed either.
The suite was not re-run. The resolver and the dispatcher were executed against the installed libxkbcommon 1.13.2 (python-xkbcommon 1.5.1) for `us` and `de`. Line numbers below are `f931858`.
## Verdict
**Yes-with-fixes.** `type` of `A` on `us` is the worked example, and it is not a Shift special case: the same path sends level 3 for `de` `@`. The uploaded text is a real XKB keymap (`xkb_symbols "pc_us_inet(evdev)"`, TEXT_V1), and its NUL-inclusive size for `us`/`pc105` is 35572, the same number Stage 0 logged. The layout is `--xkb-layout` (default `us`), not a hardcoded string. Nothing in this commit treats `pointer acquire`'s one warp as keyboard focus.
Two things are wrong enough that Stage 2 will encode them if it starts from this tree. `key` throws away the mask the resolver just computed, so `keyboard key A` types `a`. And the shutdown comment says `nix/hyprland-conf.nix` sets `input:virtualkeyboard:release_pressed_on_close`, which this commit does not do.
## Findings
1. **High. `key` drops `action.mask`, so any keysym above level 0 is sent as the bare key.** `keymap.py` `resolve_name("A")` returns `(code=30, mask=1)` and `resolve_text("@")` on `de` returns `(code=16, mask=128)`, which is `ISO_Level3_Shift`'s bit, not Shift. `_op_type` uses that mask (`ops.py:315`, mask before the down/up, restored after). `_op_key` does not. On down it sends `action.code` and then, only if `is_modifier(name)`, `modifier_mask` (`ops.py:261-266`). `A` and `at` are not modifiers, so the calls are `key(30, pressed)` and `key(16, pressed)` with no `modifiers` at all. Confirmed by running the dispatcher: `{"op":"key","key":"A"}` produces `[("key", 30, 1)]`; `{"op":"key","key":"at"}` on `de` produces `[("key", 16, 1)]`. The plan's `NAME` list includes `A` (`2026-10-03-keyboard-input.md` CLI block). Stage 2's `keyboard key` / `down` / `up` as a thin wrapper of this op will type the level-0 character. Stage 3's `keyboard type` assertion stays green while that is true, because `type` is the path that was tested (`tests/pointer/test_ops.py:513-527`).
The same hole aliases two names onto one evdev code. `down A` then `down a` records both names and sends `key(30, pressed)` twice. Hyprland drops the second press (`m_pressed` already contains 30). `release_all` then emits two ups of 30 (`ops.py:351-352`); the second is dropped because the code is already up. The seat survives. The held set lied the whole time.
Cheapest fix: in `_op_key`, if `action.mask` is non-zero, send `modifiers(baseline | action.mask)` *before* the down and restore the baseline on the matching up — the one-character `type` sequence — and refuse a second held name whose evdev code is already down, `kind=invalid_argument`. Do not store `action.mask` in `_keys` as the contribution: that field means "what this key adds", and `type` treats a zero contribution as "non-modifier, refuse". `Shift_L` must stay key-then-mask; the tests at `test_ops.py:481-486` lock that order, and it is the other path on purpose.
2. **High. The comment says Hyprland releases keys on destroy. The conf file does not.** `__main__.py:186-193` says SIGKILL is safe because `nix/hyprland-conf.nix` sets `input:virtualkeyboard:release_pressed_on_close`. In `f931858` that file's `input` block is `follow_mouse = 1` and nothing else (`nix/hyprland-conf.nix:81-94`). The verification's change 4 was "required before code" because the default is 0 and `releasePressed` emits key-ups only when the option is true: a `kill -9` leaves the code in the seat's `m_pressed`, and the next driver's down of that code is ignored. The clean path is fine — `_lift_everything` calls `release_all`, and `release_all` does send the ups and, when a mask was touched, `modifiers(0,0,0,0)`. The comment describes the path the option exists for, and the option is not there.
Cheapest fix: one line in `nix/hyprland-conf.nix`, `input:virtualkeyboard:release_pressed_on_close = true`, plus the sentence the verification asked for (the true setting still does not clear a mask, which is why `modifiers(0,…)` stays). Delete the claim from `__main__.py` until the line exists. This is not optional follow-up: it is the difference between a killed driver and a key that stays dead.
3. **Medium. The upload is right, and no test would notice if it stopped being right.** `WaylandSink.upload_keymap` (`backend.py:209-253`) creates one keyboard, writes `text.encode("utf-8") + b"\0"`, passes `format=XKB_V1` (1) and `len(payload)`, `_sync()`s, and only then `os.close`s the fd. python-xkbcommon 1.5.1's `get_as_bytes` defaults to `XKB_KEYMAP_FORMAT_TEXT_V1` and `ffi.string` strips the NUL, so the extra byte is exactly one terminator, not two. For `us`/`pc105` that size is 35572. `__main__.py:155-173` calls it once, after `connect`, and returns exit 10 on `CompositorUnavailable` *before* `listen`. `type` never calls it.
Nothing asserts any of that. `test_the_keymap_object_is_built_once_and_reused_across_types` (`test_keymap.py:279-293`) checks `dispatcher._keymap is us`. The sink has no `keymap` method. The verification named this false pass: a backend that uploads on every `type` stays green. `test_a_usable_layout_gets_as_far_as_the_compositor` (`test_driver_flags.py:128-138`) raises at `connect`, so upload, the NUL, format 1, and "before listen" are never reached. A `main` that connects and listens without uploading passes every test in the tree. `test_the_backend_binds_the_keyboard_manager_at_version_1_and_survives_its_absence` (`test_vendored_protocol.py:179-187`) constructs an unconnected `WaylandSink` and checks the flag is false. A `connect` that `ManagerTooOld`s when the keyboard global is missing stays green.
Cheapest fix: one test with a sink whose `connect` succeeds and whose `upload_keymap` records `(text, caller)`. Assert `main` calls it once, with a payload whose last byte is NUL and whose length is `len(text.encode()) + 1`, and that `serve` is what runs next — inject `listen` so it does not need a socket. A second test calls `upload_keymap` on a fake keyboard object and asserts `keymap(1, fd, size)` sees `size == len(payload)` while `fd` still reads back the bytes. Do not assert only that `keymap.py` returns equal strings.
4. **Low. `key` up forgets the name before the send, unlike `button`.** `_op_key` pops `_keys` and then calls `sink.key` (`ops.py:275-276`). `_op_button` updates `_pressed` only after the send (`ops.py:198-203`). A raise from the up — `KeyboardUnavailable` is caught in `__main__.py:211-214` and the process stays up — leaves `_keys` empty while the compositor still has the code down. `release_all` will not repeat the up. Confirmed with a sink that raises on `state=0`: after a failed `Shift_L` up the held set is `[]` and `_mask_touched` is still true, so the next `release_all` sends `modifiers(0,…)` and no key-up. Not reachable today unless the keyboard object disappears between down and up (`close` is the only thing that clears it, and it runs after the lift). Cheapest fix: pop after a successful send, same order as the button.
5. **Low. Two layouts xkbcommon accepts are not the layout the caller named.** `CONTROL_KEYSYMS` maps `\r` to `Return` (`keymap.py:67`). The plan's C0 rule exempts `\n` and `\t` only; `\r` is a `Return` and not a refusal. And `build(layout="")` does not raise: xkbcommon compiles it as `xkb_symbols "pc_us_inet(evdev)"`, the same keymap as `us`. A hand-run `--xkb-layout ''` looks configured. The comma check (`keymap.py:144-153`) is the right idea and does not cover this. Cheapest fix: drop `\r` from `CONTROL_KEYSYMS`, and reject an empty layout in `build()` next to the comma check.
Not defects, checked because they look like them:
- **Shift is not hardcoded.** `A` on `us` is evdev 30 and mask `1 << mod_get_index("Shift")` (index 0, so 1). `de` `@` is evdev 16 and mask 128, equal to `modifier_mask("ISO_Level3_Shift")`, not equal to Shift. `type "@"` emits `modifiers(128), key(16, down), key(16, up), modifiers(0,…)` and no code 42. Control's contribution is 4 (index 2). The measured modifier set on `us`/`pc105` is exactly `EXPECTED_MODIFIERS`; Meta and Hyper are absent because no key produces them. Locks are `Caps_Lock` and `Num_Lock`, and `type` while either is held emits nothing.
- **Unmappable means no events.** `resolve_text("xéy")` raises `UnknownKey` with `scalar 1 (U+00E9)` and neither the character nor the string. The dispatcher calls `resolve_text` before any sink call (`ops.py:310-311`). `é`, a C0 other than the two (and `\r`) exemptions, a dead keysym, and 4097 scalars are the same shape.
- **The 4096 cap counts scalars.** `len(str)` is what `resolve_text` compares (`keymap.py:335-338`). 4096 copies of `😀` miss the cap and fail on scalar 0; a byte cap would have said "limit".
- **Degraded mode is the reachable one.** A missing manager makes `upload_keymap` return before `create_virtual_keyboard` (`backend.py:221-226`). `has_keyboard()` stays false. `key` / `type` answer `kind: refused` (`ops.py:391-396`). `release_all` sends key-ups only when `_keys` is non-empty and `modifiers(0,…)` only when `_mask_touched` (`ops.py:347-361`). Both stay empty if no keyboard op ever succeeded, so the button half still runs. The test uses a real `us` keymap plus a sink with no keyboard (`test_ops.py:703-723`), which is how the process actually starts: the keymap is compiled before connect (`__main__.py:132-138`) even when the global is absent.
- **No keyboard `frame`, no `_aimed()` on `key` or `type`, no `touch`.** `frame` remains the pointer op. `release_all` still frames pointer outputs and does not add one for keys (`ops.py:343-344`, locked by `test_ops.py:667-683`). There is no `touch` in the driver. This commit does not add broker verbs, so it does not add any to the mutation set either.
- **The driver token exists, on the driver reply only.** A bad keysym, an unmappable scalar, a bad `state`, and a string over the cap are `{"ok": false, "kind": "invalid_argument"}` (`ops.py:112-117`, `159-160`, `413-425`). A missing keyboard is `kind: "refused"`. A bad layout is process exit 2 *before* `WaylandSink` is constructed (`__main__.py:132-141`, `keymap.py:144-153`). Upload failure is exit 10 and does not `listen` (`__main__.py:155-164`). The committed broker does not read `kind`. That is the next section, not a second copy of this one.
- **Focus.** No Stage 1 path warps to deliver `wl_keyboard.enter`, warps twice, or calls `dispatch focuswindow`. `type` with no prior warp emits keys (`test_ops.py:420-432`). `pointer acquire` is still one `_warp`. The Stage 0 misreading was not built on.
## Tests
Dispatcher tests record tuples. They cannot see Wayland `time`, the keymap fd, or `format`. That seam is fine for ops and blind for the upload. Per test, what a pass requires, and where a pass is a lie:
`tests/pointer/test_keymap.py` (real xkbcommon, not a stub):
| Test | Passes only if | False pass |
| --- | --- | --- |
| `test_a_lower_case_letter_…` | `resolve_name("a")` is `(30, 0)` | Asserting the XKB code 38 would be the lie; this one asserts 30 |
| `test_a_capital_is_the_same_code_with_shift_in_the_mask` | code 30 and mask `== 1 << mod_get_index("Shift")`, and the code is not 42 | Hardcoding mask `1` is what this test refuses. It does not run `type` |
| `test_shift_is_a_key_in_its_own_right_…` | `Shift_L` is `(42, 0)` and `modifier_mask` equals that Shift bit | |
| `test_a_named_keysym_resolves_…` | `Return` 28, `Tab` 15, `BackSpace` 14, `Left` 105 | The mask is not checked. All four are level 0 on `us`, so a resolver that always returns mask 0 passes |
| `test_the_two_allowed_control_characters_…` | `\n` and `\t` are `Return` / `Tab`, mask 0 | Does not notice that `\r` is also `Return` |
| `test_an_empty_string_…` | `resolve_text("") == []` | |
| `test_a_character_this_layout_cannot_produce_…` | `UnknownKey`, message contains `scalar 0`, and the character is not in the message | A message that quoted `é` fails this. Logging the string elsewhere would not |
| `test_the_refusal_names_the_index_…` | `"abcé"` says `scalar 3` and not `é` | |
| `test_a_dead_keysym_is_refused_by_name` | `dead_acute` raises and the message contains `dead key` | The prefix check refuses the name even when it is not on the layout. The test does not prove a layout that *has* the key still refuses it; `us` does not have it |
| `test_an_unknown_keysym_name_…` | `NoSuchKeysymAtAll` raises `UnknownKey` | |
| `test_a_comma_separated_layout_…` | `build("us,ru")` raises `KeymapError` and the message contains `group` | Compiling the two-group keymap and *then* raising still passes. The user-visible failure (nothing uploaded) is the same |
| `test_a_layout_xkbcommon_rejects_…` | `zzz-no-such-layout` raises and the name is in the message | xkbcommon does reject it (NULL, not a silent `us`). Empty string is the case this does not cover: it compiles as `us` |
| `test_the_cap_is_exactly_at_the_limit` | 4096 `a`s resolve | |
| `test_one_scalar_over_the_cap_…` | 4097 raises and the message names 4096 | No sink. The dispatcher twin covers "zero calls" |
| `test_the_cap_counts_scalars_and_not_bytes` | 4096 emoji (`len == 4096`, UTF-8 longer) raises `scalar 0` and the message does not contain `limit` | An ASCII-only cap test would not tell a byte cap from a scalar cap. This one does |
| `test_the_modifier_set_is_measured_…` | `modifier_names() == EXPECTED_MODIFIERS` | An empty set fails. It does not fail a set that matches the constant and was then hardcoded — the constant is what `us`/`pc105` measures, which is the point of the constant |
| `test_a_lock_is_not_a_modifier` | locks are exactly `{Caps_Lock, Num_Lock}`, none of them modifiers | |
| `test_control_contributes_a_mask_that_is_not_shifts` | Control's mask is neither 0 nor Shift | **Alt's bit passes.** Nothing asks `mod_get_index("Control")`. The wire tests compare against `modifier_mask(...)`, so a consistently wrong bit stays green. Measured here: index 2, mask 4. The test does not lock that |
| `test_de_swaps_y_and_z_…` | `us` y/z are 21/44, `de` is 44/21 | A table beside the keymap that always returns the `us` codes fails |
| `test_on_de_the_at_sign_…` | `us` `@` has Shift's mask; `de` `@` is neither 0 nor Shift, and equals `modifier_mask("ISO_Level3_Shift")` | The two sides use different xkbcommon calls (level lookup vs a pressed key). Both are 128. A Shift special case for letters only would still pass, which is why the `de` case exists |
| `test_a_character_us_cannot_type_is_ordinary_on_de` | `ü` raises on `us`; on `de` it is `udiaeresis`, mask 0 | |
| `test_the_keymap_text_is_an_xkb_keymap_naming_its_layout` | text starts with `xkb_keymap {`; the `xkb_symbols` line contains `us` or `de` | `"us" in "pc_us_inet(evdev)"` is true of every `us`-family map. The `de` line is what fails if the layout argument is ignored. It does not require the symbols name `pc_de_inet(evdev)`, which is what the VM grep should match. Actual lines: `xkb_symbols "pc_us_inet(evdev)"` and `xkb_symbols "pc_de_inet(evdev)"` |
| `test_an_unmappable_character_emits_nothing_through_the_dispatcher` | `type "abcé"` is `ok: false`, `kind == invalid_argument`, `sink.calls == []` | "No event carried `é`" would pass with `a` and `b` typed. This assertion would not |
| `test_a_string_over_the_cap_emits_nothing_…` | 4097 `a`s, same three checks | |
| `test_the_keymap_object_is_built_once_…` | two `type`s leave `dispatcher._keymap` as the same object | **The false pass the verification named.** Re-uploading per string never calls this object twice and stays green |
`tests/pointer/test_ops.py`, new cases. All of them talk to `RecordingSink`, which writes down whatever it was told. A pass means the dispatcher passed those tuples, not that `zwp_virtual_keyboard_v1.key` was marshalled.
| Test | Passes only if | False pass |
| --- | --- | --- |
| `test_the_contracts_ops_are_exactly_what_is_implemented` | `Dispatcher._ops` equals a set literal that includes `key` and `type` and not `release_all_keys` | The docstring says the contract. The test never opens `CONTRACT-sessions.md`. §3.4 still lists neither op, and this stays green |
| `test_key_down_sends_the_code_and_lists_the_name` | `key down Return` → `[("key", 28, 1)]` and `pressed` says `["Return"]` | |
| `test_key_needs_no_warp` | `type "Hi"` and `key a` both `ok` on a dispatcher that never warped, and some call is `key(30, down)` | The `in sink.calls` check is weak (`H` is not code 30; the explicit `key a` supplies it). `ok is True` on `type "Hi"` is the real assertion, and a call to `_aimed()` fails it. Not a false pass of the aim rule |
| `test_a_key_is_not_tagged_with_an_output_…` | after a warp, `key a` is exactly `[("key", 30, 1)]` | A sink that accepted an output argument and ignored it would still look like this, because the dispatcher never passes one. That is what the arity assertion is for |
| `test_key_up_forgets_the_key` | down then up is down, up, and `lifted == ["a"]` | |
| `test_up_of_a_key_that_was_never_down_…` | `ok`, `lifted == []`, no sink calls | |
| `test_keys_are_reported_oldest_first` | `pressed` names are `Control_L`, `Shift_L`, `a` | Does not look at the sink, so a modifier down that forgot the mask still passes |
| `test_a_modifier_down_sends_the_key_and_the_mask` | `Shift_L` down is key 42 then `modifiers(mask, 0, 0, 0)` | |
| `test_a_modifier_up_restores_the_mask_…` | releasing Shift while Control is held sends key-up 42 then Control's mask, not zero | |
| `test_an_ordinary_key_down_sends_no_mask` | `key a` is exactly one key call | This is also why `key A` has no test. The ordinary-key assertion is what a capital would satisfy, wrongly |
| `test_type_of_a_capital_is_the_mask_and_not_a_shift_keycode` | exactly `modifiers(shift), key(30,1), key(30,0), modifiers(0,0,0,0)`, and no code 42 | "Some call had code 30" would be the lie. This list is the worked example. It uses `modifier_mask("Shift_L")`, which on this keymap is 1 |
| `test_type_leaves_no_key_held` | `type "Hello"` leaves `pressed` keys empty | Does not look at the sink |
| `test_type_emits_a_down_up_pair_per_character` | the key calls for `"ab"` are 30 and 48, down/up each | **Filters to `key` calls.** Omitting every `modifiers` stays green. The capital test is what locks the mask |
| `test_type_of_an_empty_string_…` | `ok`, no calls | |
| `test_type_ors_an_explicitly_held_modifier_…` | `down Control_L` then `type c` is `modifiers(control)`, key down/up of `c`'s code, `modifiers(control)` again; `pressed` is still `["Control_L"]`; no key 29 | Full sequence. Not a false pass |
| `test_type_of_a_capital_under_a_held_control_…` | first call is `modifiers(control\|shift)`, last is `modifiers(control)` | **`modifiers(both)` then `modifiers(control)` with no key events passes.** The key, and "no second Control down", are not in the assertion |
| `test_type_while_a_non_modifier_is_held_…` | `ok: false`, `kind` invalid, no new calls, `a` still held | |
| `test_type_while_a_lock_is_held_…` | `Caps_Lock` held, `type a` is `ok: false`, no new calls | Does not check `kind`. A `refused` (exit 10) passes |
| `test_a_string_that_fails_on_its_third_character_…` | `"abé"` is `ok: false` and `calls == []` | Same strength as the keymap twin. Does not check `kind` |
| `test_a_bad_character_is_a_usage_error_and_a_missing_keyboard_is_not` | `é`, `Nope`, and `state=sideways` are `invalid_argument`; the same `type a` on `KeyboardlessSink` is `refused` | This is the token. It does not check that anything maps the token to exit 2. Nothing in `f931858` does |
| `test_without_a_keymap_at_all_…` | `Dispatcher(sink, None)` still warps and buttons; `type` is `refused` | |
| `test_release_all_lifts_keys_in_press_order_then_zeroes_the_mask` | `Control_L` then `a` lifts 29, then 30, then `modifiers(0,0,0,0)` | |
| `test_release_all_lifts_keys_after_buttons_and_adds_no_keyboard_frame` | button up, one pointer `frame`, key up 42, `modifiers(0,…)` | Locks the frame *before* the key-up. The plan's step list puts the pointer frames last. Buttons and keys are different objects; the frame does not gate the key. Not a false pass, and not worth reordering unless a client is shown to care |
| `test_release_all_lifts_keys_even_after_a_warp_to_another_output` | after a warp to another output, the only call is `key(30, up)` | A plain `a` never touched the mask, so the absent `modifiers` is correct (`_mask_touched` is false). A sink that ignored an output argument cannot fake this: the call has no output slot |
| `test_release_all_without_a_keyboard_still_lifts_buttons` | keymap present, `has_keyboard` false, a held button: `lifted == ["left"]`, `lifted_keys == []`, and the calls are button up plus frame | `KeyboardlessSink.key` raises. If the key half ran, the test errors rather than passes. It does not hold a key, which is the only degraded state the process can reach |
| `test_release_all_after_a_type_zeroes_the_mask_once_more` | after `type A`, `release_all` is exactly one `modifiers(0,0,0,0)` | `_mask_touched` stays true after `type` restores the baseline. A `type` that never sent a non-zero mask would not take this branch; `type a` is not this test |
`tests/pointer/test_driver_flags.py`:
| Test | Passes only if | False pass |
| --- | --- | --- |
| `test_the_xkb_flags_default_to_the_frozen_values` | `parse_args([])` is `us` / `pc105` / empty variant / empty options | Parsing only. `main` could ignore them; the refusal tests below are what catch that for a *bad* value |
| `test_the_defaults_are_the_ones_the_module_option_defaults_to` | the two Python constants equal `("us", "pc105")` | **Does not read `nix/module.nix`.** In `f931858` the unit's `ExecStart` is still the two-flag line (`nix/module.nix:986-992`) and there is no `sessions.keyboard` option. The docstring says the module and the binary cannot drift. They are not compared |
| `test_a_layout_is_taken_from_the_flag` | `parse_args(["--xkb-layout", "de"]).xkb_layout == "de"` | Parsing only |
| `test_the_contract_command_line_still_parses` | the §3.4 line plus the four XKB flags parses | The contract text is not read, and it does not yet contain those flags |
| `test_a_comma_separated_layout_exits_2_without_connecting` | `main(["--xkb-layout", "us,ru"])` is exit 2 and `WaylandSink` was never constructed | The injected sink raises if constructed. A connect that happened would fail the test, not pass it |
| `test_a_layout_xkbcommon_rejects_exits_2_without_connecting` | `zzz-no-such-layout` is exit 2, same injection | Ignoring the flag and always compiling `us` would reach `connect` and fail this. The flag is actually wired |
| `test_a_usable_layout_gets_as_far_as_the_compositor` | `main(["--xkb-layout", "us"])` raises `_Unreached("connect")` | Stops at connect. See finding 3 |
| `test_the_exit_codes_match_the_brokers_table` | the three constants are 0, 2, 10 | Does not import `hhstreamd.protocol`. Two copies can diverge and this still passes |
`tests/pointer/test_lease.py`, the new key cases. They call `press_key` on the lease directly. None of them opens a socket. A pass does not mean a verb updates the mirror; no verb in `f931858` does (`manager.py` never calls `press_key`).
| Test | Passes only if | False pass |
| --- | --- | --- |
| `test_press_and_lift_one_key` | `press_key` / `keys_pressed` / `unpress_key`, and a later `release` has `keys_lifted == []` | |
| `test_lifting_a_key_that_is_not_down_…` | `unpress_key` of a key not held is `[]` | |
| `test_keys_are_kept_in_press_order` | order is press order, including after one is removed; `release().keys_lifted` is what remained | |
| `test_pressing_a_key_twice_leaves_one_down` | a dict, so the second `press_key` does not duplicate | The driver does not share this dict. A double `key down` still sends two presses; this test cannot see that |
| `test_keys_and_buttons_are_tracked_separately` | `release` reports buttons and keys independently | |
| `test_a_non_holder_cannot_press_a_key` | `LeaseInvalid` for the other session | |
| `test_expire_still_returns_no_key_list_…` | read `keys_pressed()`, then `expire()`; the return has no `keys_lifted` and no `buttons_lifted`; the lease is then empty | `hasattr` fails if someone adds the field to `LeaseInfo`. Widening the return is what this is for |
| `test_expiry_does_not_leak_keys_to_the_next_holder` | after `expire`, the next `acquire` sees no keys | |
`tests/pointer/test_vendored_protocol.py`, the keyboard cases. The source-text tests pass if the generated file contains the substring, including in a comment. The two `skipif` tests import pywayland and check `hasattr` and `version == 1`, which is a real bind of the generated class, still with no display.
| Test | Passes only if | False pass |
| --- | --- | --- |
| `test_the_keyboard_protocol_is_vendored_beside_the_pointer_one` | the package exists and every `.py` starts with the scanner banner | |
| `test_the_keyboard_manager_is_version_1_with_the_seat_only_request` | the source contains the interface name, `version = 1`, `create_virtual_keyboard(self, seat: WlSeat)`, and not `WlOutput` | A comment with that signature passes |
| `test_the_keyboard_carries_keymap_key_and_modifiers` | source contains the three signatures, `ArgumentType.FileDescriptor`, and no `def frame(` | Same |
| `test_the_integers_the_xml_names_but_does_not_define_live_in_our_code` | the generated file mentions `keymap_format` and does not define the enum; `XKB_V1 == 1`; `STATES` is 0 and 1 | Does not check that `upload_keymap` passes 1. A call with format 2 stays green |
| `test_the_shim_resolves_the_keyboard_relative_import` | the manager module imports `WlSeat` from `..wayland` | |
| `test_the_keyboard_protocol_binds_against_the_installed_pywayland` | import, name, version 1, and the four requests exist on the proxy | Skipped when pywayland is absent. The package check is what runs in the build |
| `test_the_backend_binds_…_and_survives_its_absence` | `KEYBOARD_MANAGER_VERSION == 1` and an unconnected sink reports no keyboard | See finding 3. It never runs `_on_global` |
| `test_the_backend_refuses_a_version_1_manager` | `ManagerTooOld(1)` mentions version 1 and `create_virtual_pointer_with_output` | This is the *pointer* manager. It says nothing about a keyboard global at the wrong version. `_on_global` binds `KEYBOARD_MANAGER_VERSION` whenever the name matches (`backend.py:362-366`) and does not reject a compositor that advertised something else |
`tests/pointer/test_pointer_server.py` only grew `keys` / `lifted_keys` in two assertions. A pass means the JSON reply gained those fields. It does not send `key` or `type`.
## What Stage 2 must not assume
Three of these, left alone, make Stage 2 wrong. The rest are the same class of mistake at lower cost.
1. **`{"op":"key","key":"A"}` does not type `A`.** Neither does `at` on `de`, or any other keysym whose producing mask is non-zero. `type` does, and it ORs that mask with the baseline of keys that are actually modifiers. `keyboard key` / `down` / `up` must not be "send the name through unchanged" until finding 1 is fixed, and a VM check that only runs `keyboard type` will not catch it. `a` and `A` are two held names for evdev 30. `Caps_Lock` down sends the key and never a locked mask; `type` then refuses. Do not document Caps as capitalization.
2. **`kind` does not survive the broker client, and every refusal is exit 10.** `PointerDriver._exchange` raises `DriverRejected` from `reply["error"]` and drops everything else (`src/hhstreamd/driver.py:158-159` at `f931858`). `_drive` maps every `DriverRejected` to `driver_refused` (`manager.py:2047`). A Stage 2 test that asserts exit 2 for `é` fails, or it passes by reading the English. Read `kind` off the JSON *before* that conversion and map `invalid_argument` to exit 2. Leave `refused` as exit 10. The 4096 check lives only in `resolve_text`. A broker check of `len(text.encode())` disagrees with it on the emoji case the driver already got right. `Rejected` text carries an index; do not log `text`, and do not put it on `keyboard_type`.
3. **Do not design the enter subtest, the unit argv, or `kill -9` from the comments in `__main__.py`.** `pointer acquire` is still one warp (`manager.py` `_warp`, unchanged in this commit) and Stage 0's (a1) did not deliver `wl_keyboard.enter`. A second warp to the same floored pixel is not the fix. `nix/module.nix` does not pass `--xkb-layout`; the flag defaults to `us`, so the running unit types `us` until Stage 2 adds the argv. A `[keyboard]` table in the broker TOML is still not the upload — the driver never opens that file. `input:virtualkeyboard:release_pressed_on_close` is not set, whatever `__main__.py:191-193` says. `upload_keymap` is not idempotent: a second call creates a second virtual keyboard and orphans the first (`backend.py:227`). Do not call it on acquire or per string.
Also, because the mirror landed here and nothing uses it:
- `expire()` still returns `LeaseInfo` with no keys (`pointer.py:178-196`). `_expire_pointer` reads `pressed()` and not `keys_pressed()` (`manager.py:1857`). Read the keys first. The driver's one `release_all` is what lifts them; do not add `release_all_keys`.
- The committed `PointerDriver.release_all` returns the button list only (`driver.py` `release_all`), and `_release_all_buttons` does `list(lifted)` (`manager.py:2058-2061`). The new reply field is `lifted_keys` beside `lifted`. Changing the client method to return a tuple without updating that `list()` turns the button names into the two lists.
- `pressed()` on the client still returns buttons only. The reply now also has `keys`. Do not widen the return of `pressed()` in place.
- `keyboard.key` and `keyboard.type` are not in `MUTATING_VERBS`. `pointer.state` must stay out of it. No keyboard verb calls `touch`. Acquire's stderr still says "pointer" only; a `keyboard.*` verb that goes through `_refresh` moves the deadline, and the help text has to say so.
- `CONTRACT-sessions.md` §3.4 is still the two-flag command line and a `pressed` / `release_all` with no key fields (`:262`, `:283-284`). Amend it in the same change as the unit argv. `test_the_contracts_ops_…` will not notice if you forget.
## Carried objections
From the Stage 0 review, still true of `f931858`, with one correction for where the branch tip is:
- **The plan banner is not in this commit.** `git grep` of `f931858` for the supersession banner is empty, so anyone who builds Stage 1 from that commit alone still has the unedited exit-code paragraph, the `[keyboard]` TOML rows, and "if it repeats, the help text says so". `b1f2744` (after this commit, not reviewed here) adds the banner and folds the eight rows. Do not treat that as something Stage 1 did, and do not do it again.
- **Stage 0's (a) mechanism, as `f931858` inherited it.** This commit does not cite it. The parent commit's README did. `b1f2744` rewrites that README; it was not re-checked for this review. Stage 2 still must not read "one warp late" as "wait longer" or as "warp twice to the same point".
- **`mask_cleared=no` is not a held Shift.** `backend.py:246-250` cites `tests/README-keyboard-probe.md` for "destroy does not clear the modifier mask". The send of `modifiers(0,0,0,0)` after upload is right anyway — `releasePressed` never emits modifiers — but the citation is the sentence Stage 0 said the log does not support. The cleanup `state=0` for code 30 is the poison evidence, and it is why finding 2 is not theoretical.
- **The Hyprland XML, kept on purpose.** `regenerate.py` says wayland-protocols has no `virtual-keyboard` directory in this nixpkgs and vendors Hyprland's copy, which names `keymap_format` and `key_state` and defines neither. `XKB_V1 = 1` and `buttons.STATES` are the right workaround. Switching later, if a nixpkgs grows the file, does not move the integers. Do not vendor a second copy to get an enum.
- **Changes 5 and 8, the halves this stage did not take.** The driver half of 5 is done (flag, comma rejected before `xkb_keymap_new_from_names`, no `rules` flag, `evdev` hardcoded). The unit argv is not. The driver half of 8 is done (index and `U+` codepoint, and the server does not log the request line). Acquire's stderr is untouched. Change 7 (the probe's expectations, the unconditional `keyboard down` warning) is not this stage; the warning has nowhere to live until the CLI exists, and it is still unconditional when it does.
- **`xkbcommon` is a hard dependency** (`pyproject.toml`, `nix/package.nix`). Leave it that way. An optional one lets `test_keymap.py` skip, and the unmappable path is the one that rots.
+178
View File
@@ -0,0 +1,178 @@
# Stage 2 and Stage 3 review — the broker learns to type, and the VM has to show it
Reviewed `e6f4c3b` (Stage 1 review fixes plus the broker, CLI and module), `7890315` (xkbcommon in the unit check, and the two-warp acquire tests), `a6a4094` (`checks/vm-keyboard.nix`, the keyboard victim, the helper derivation) and `54dd109` (the change to `checks/vm-pointer.nix`). Tip is `54dd109` on `feat/keyboard-input`. Line numbers below are that tip, not the individual commits.
Nothing was rebuilt. Pytest was not run. The VM checks were not run — they are slow and are being run elsewhere. What follows is a reading of the code and of what each assertion would and would not catch. A green VM log from another machine is not evidence this review produced.
The Stage 1 fixes that `e6f4c3b` claimed are in the tree and are not re-opened here. `key` of a capital sends the mask before the key (`tests/pointer/test_ops.py:510-528`). `type` under a held Control asserts the whole sequence, including the key, and the comment says why a first-and-last check would pass while typing nothing (`test_ops.py:653-688`). `release_pressed_on_close = true` is set (`nix/hyprland-conf.nix:134-136`). The keymap upload is ordered connect, upload, listen, serve (`tests/pointer/test_driver_flags.py:254-272`) and the payload test counts the NUL (`test_driver_flags.py:286`). A key-up forgets the name only after the sink accepts (`test_ops.py:589`). `checks/unit.nix:27` puts `xkbcommon` next to `pywayland`, so the resolver tests cannot skip.
---
## Stage 2 — broker, CLI, module
### Verdict
**done-with-fixes.** The verbs, the exit codes, the driver token, the two warps, the layout argv and the audit count are implemented and the tests that exist mostly look at the bytes the driver would send. Two tests the verification named as false passes were not written. The behaviour they would lock is the shared cache and a call that is already in `kill()`. Fixing them is two tests, not a redesign.
### What is in the tree
**Verbs.** `keyboard.key` and `keyboard.type` are in `VERBS` and in `MUTATING_VERBS` (`src/hhstreamd/protocol.py:157-188`). There is no `keyboard.acquire`. Both go through `_refresh` (`manager.py:1882`, `1913`), so they refresh the lease and do not mark activity. `test_typing_does_not_count_as_activity` (`tests/sessions/unit/test_keyboard_verbs.py:523-543`) asserts the timestamp **and** `command_count`. `pointer.state` reports `keys` as names (`manager.py:1849-1851`). `pointer.release` reports `keys_lifted` beside `buttons_lifted` (`manager.py:1822-1837`). Expiry reads `keys_pressed()` before `expire()` and then one `release_all` (`manager.py:1962-1975`).
**Exit codes, and they are the ones the plan names.**
| Code | Name | How it is reached |
| --- | --- | --- |
| 2 | `invalid_argument` | Bad state, non-string text, over the scalar cap, at the broker before the driver (`manager.py:1884-1922`). A bad keysym or an unmappable character, after the driver says `kind`. |
| 8 | `pointer_busy` | A second `pointer.acquire` only (`manager.py:1628-1635`). Holding a key does not change that. `test_a_second_acquire_while_a_key_is_held_is_busy_and_leaves_the_key` (`test_keyboard_verbs.py:171-185`) checks the holder and the key both survive. |
| 9 | `no_lease` | No lease, or another session's lease id (`test_keyboard_verbs.py:144-168`). Not 8. The CLI prints the exit-9 sentence (`src/hhstream_session/format.py:399-404`, `KEYBOARD_LEASE_NOTE` at `__init__.py:491-498`). |
| 10 | `driver_refused` | Anything the driver refuses without `kind == "invalid_argument"`, including a missing keyboard global (`manager.py:2168-2177`, `test_keyboard_verbs.py:387-407`). Pointer move still works in that test. |
**The token mapping landed.** The driver sets `kind` to `invalid_argument` for a bad keysym, a bad state, an unmappable character and an over-cap string (`src/hhstream_pointer/ops.py:107-117`, `457-466`). The client copies `reply["kind"]` onto `DriverRejected` (`src/hhstreamd/driver.py:218-221`). `_drive` maps that one token to `ManagerError("invalid_argument")` and leaves every other refusal, including a missing `kind`, as `driver_refused` (`manager.py:2168-2177`). `test_an_unmappable_character_is_exit_2_and_types_nothing` (`test_keyboard_verbs.py:288-304`) goes through the real manager, the real UNIX socket and the real dispatcher on a compiled `us` keymap (`tests/sessions/fakes.py:477-493`). It asserts the error name, `exit_code_for == USAGE`, and `sink.calls == []`. A driver that refused `é` as `driver_refused` fails it. A driver that typed `caf` and then refused fails it. This is not a fake that returns the error name by agreement.
**Two warps, and the threshold is pinned.** `pointer_acquire` always calls `_warp_taking_focus` (`manager.py:1638-1639`). That sends a warp to `(x, _nudged(y))` and then a warp to `(x, y)` (`manager.py:2220-2234`). `FOCUS_NUDGE` is `0.004` (`manager.py:2392`), about 2.88 px at the frozen 1280×720 mode, so the floored pixels differ. The unit test asserts two warps, the second equal to the bookmark, the rounded pixels different, and `focus == "warp"` (`test_keyboard_verbs.py:624-651`). The integration test pins the nudge itself: after a restore to `(0.8, 0.2)` the sink saw `(0.8, 0.204)` then `(0.8, 0.2)` (`tests/sessions/integration/test_containers.py:580-585`). `follow_mouse = 1` and `follow_mouse_threshold = 0` are written out in `nix/hyprland-conf.nix:99-115`, not inherited. The comment says why raising the threshold stops acquire taking the keyboard.
**The fallback is not where the plan's stage table puts it.** See finding 3. The second motion is real. The `focuswindow` call exists, on nudge failure only, and the contract describes that. The plan's stage table still says it is Stage 4.
**CLI and module.** `hhstream session keyboard type|key|down|up` is built in `_build_keyboard` (`src/hhstream_session/__init__.py:501-627`). Each verb takes `--lease` and otherwise reuses the cached pointer lease, and refuses with `_no_lease` (exit 9) when there is none (`__init__.py:1232-1296`). `type` renders a character count, never the text (`__init__.py:1241-1248`). `sessions.keyboard.layout` is `strMatching "[A-Za-z0-9_-]+"`, default `"us"` (`nix/module.nix:630-638`). The only consumer is `hhstream-pointer`'s `ExecStart`, as `--xkb-layout` and the three sibling flags (`nix/module.nix:1060-1080`). There is no `[keyboard]` TOML table. The audit event is `chars=len(text)` (`manager.py:1927`). The generic `request` audit stores the verb, the error name and the request id, not the body (`server.py:233-242`). Driver refusals name a scalar index and a `U+` codepoint (`test_keyboard_verbs.py:307-317`). A non-string `text` can put `text!r` into an error reason (`manager.py:1915`); that is a shape check, not a typed string. Nothing in the broker, the CLI render or the audit line logs the text. The shell's own argv is out of scope, and the plan says so.
### Findings
Ordered by what they cost to fix. None of them is a missing verb.
1. **The replay test asserts set membership, not the sink.** The verification's own false pass (`docs/plans/2026-10-04-keyboard-verification.md` §B2): "Asserting `deduplicated` and not the sink. A handler that types and then sets the flag stays green." What landed is `test_every_keyboard_verb_is_cached_for_the_same_reason` (`tests/sessions/unit/test_broker_protocol.py:175-184`), which checks that the two names are in `MUTATING_VERBS`. The cache itself is real and is not keyboard-specific: `_dispatch` looks up `request_id` before the handler and `remember`s after (`server.py:196-231`), and the key is the request id alone (`protocol.py:196-222`). `test_a_retried_click_with_the_same_request_id_clicks_once` (`test_containers.py:545-561`) is the shape the spec asked to copy, and it counts `sink.of("button")`. Nothing replays `keyboard.type`, and nothing replays an unmappable `type` and asserts the sink stayed empty. The CLI does not send a `request_id` on keyboard verbs (same as the pointer gestures; `--request-id` is on start/kill/gc/adopt/reconcile). Dedup only fires when a caller of the broker socket supplies one. A regression that removed the two names from the set fails the membership test. A regression that typed and then cached would not, because that test never calls the handler.
Cheapest fix: copy the click integration test. One `keyboard.type` of `"ab"` with `request_id="retry-me"`, a second call with the same id, assert `deduplicated` and that the sink's `key` count did not grow. A second case, an unmappable string, same id twice, sink still empty.
2. **Key-lift on kill is tested by calling the helper, not `kill()`.** `test_killing_the_holder_lifts_its_keys` (`test_keyboard_verbs.py:563-574`) calls `manager._drop_lease_for(..., "kill")` and then looks for the key-up on the sink. `SessionManager.kill` does call `_drop_lease_for(session, reason="kill")` (`manager.py:1232-1237`), so the production path is there. The spec named the false pass: a `kill` of a session that does not hold the lease, or a `kill` that no longer calls the helper, stays green. The existing integration kill test (`test_containers.py:520-529`) asserts `dispatcher._pressed == {}` and a null holder. It never holds a key, so removing the call from `kill()` while leaving `_drop_lease_for` itself correct stays green.
Cheapest fix: in that integration test, `keyboard.key` down of `Shift_L` before `kill`, then assert the sink lifted it (or `pointer.state` `keys == []` after, which is weaker — prefer the sink).
3. **`focuswindow` is inside acquire, on nudge failure, and the plan still says it is Stage 4.** The code matches `docs/CONTRACT-sessions.md` v3 (`:407-413`): two warps, reply field `focus` of `warp` / `focuswindow` / `none`, depending on a threshold the conf file sets. It does not match the plan. The risk paragraph still says acquire is one warp and the fallback "is still not built in Stages 1–2", on `window.stable_id`, immediately before the first key (`docs/plans/2026-10-03-keyboard-input.md:297`, stage table at `:324`).
What the code actually does (`manager.py:2220-2260`): if the nudge warp raises, log it, call `hyprctl dispatch focuswindow` with `address:` from `session.container.window.address` or else `pid:{session.pid}`, then **still send the target warp**. The target warp's failure still drops the lease (`manager.py:1640-1644`). `address:` is the selector `vm-pointer` itself uses and treats as working (`checks/vm-pointer.nix:493-494`). `pid:` is the branch when no address has been read back, and nothing tests it. `stable_id` would be the wrong selector; the code is more correct than the plan's wording.
The fallback does not cover the failure Stage 0 measured. That failure is "both warps were sent and the keyboard did not move", which is what the second warp is for, and only when the threshold is 0. The fallback covers a driver error on the nudge. A driver that is down fails the target warp too and the acquire aborts, so the path that returns `focuswindow` is the narrow one where the nudge fails and the target warp succeeds. Nothing tests it. `test_acquire_sends_two_motions_so_keyboard_focus_moves` requires `focus == "warp"`. The VM does the same (`checks/vm-keyboard.nix:511-515`), so a broken fallback stays green everywhere. If both mechanisms fail, acquire still succeeds and reports `focus="none"` (`manager.py:2233`). That is a lease whose first key goes to the previously focused window. The VM would catch it. No unit test does.
Cheapest fix: edit the plan. Strike stage 4's "build `focuswindow` before the first key", and rewrite the risk paragraph so it describes the two warps and the nudge-failure fallback the contract already describes. Do not move the call to match the stale paragraph. A test that forces the nudge to raise and asserts one `focuswindow` plus the target warp is worth having; it is not what makes the two-warp true.
4. **The broker chord test checks the first and last mask, not the key.** `test_a_held_modifier_survives_a_type_and_ors_into_it` (`test_keyboard_verbs.py:231-245`) asserts `calls[0]` and `calls[-1]` are the Control mask and that the lease still holds `Control_L`. It does not assert a `key` event for `c` between them. The comment on the driver test (`test_ops.py:680-682`) says that shape types nothing and stays green. The driver test is the real lock: the whole sequence, including the key (`test_ops.py:662-668`). The broker test is a weaker copy. Not a functional bug.
Cheapest fix: assert the four-tuple the driver test already asserts, against `harness.fake.sink.calls`.
5. **The tap's comment describes a behaviour the code does not have.** `_cmd_keyboard_key` says the up is sent even if the down was refused after sending (`src/hhstream_session/__init__.py:1257-1260`). The next lines return immediately when `down` is not `ok` (`:1269-1270`). A broker refusal (bad keysym, never pressed) should not send the up, and the early return is right for that. A reply lost after a successful down is a connection error, not `ok: false`, so the sentence is not implemented and should not be. Cheapest fix: delete the sentence.
6. **`test_exactly_the_cap_is_accepted` does not look at the sink** (`test_keyboard_verbs.py:366-373`). It asserts `reply["chars"]`. A handler that returned the count and never called the driver stays green. The over-cap test does assert `sink.calls == []`. Cheapest fix: assert the sink is non-empty, or at least that its length is `2 * MAX_TYPE_SCALARS` key events. Low; the dispatcher has its own cap tests.
7. **`test_the_module_passes_the_same_defaults_this_binary_has` is a substring of `nix/module.nix`** (`test_driver_flags.py:160-174`). `default = "us"` in a comment, or `"--xkb-layout"` anywhere in the file, satisfies it. The VM's `ExecStart` assertion is the one that would notice (`checks/vm-keyboard.nix:386-392`). Not worth a new unit test if Stage 3 stays.
### What the merge request must not claim
- That a replayed `keyboard.type` was shown not to type twice. Membership in `MUTATING_VERBS` was shown. The click replay test covers the cache for clicks.
- That `kill()` was shown to lift keys. `_drop_lease_for` was shown to. `kill()` contains the call; no test goes through it with a key down.
- That `focuswindow` is tested, or that it is the Stage 0 fix. The Stage 0 fix is the second warp. The fallback runs when the nudge cannot be sent, returns `focus="none"` without failing the acquire when the compositor call also fails, and no test enters that branch.
- That the plan's stage table was followed. The contract was. The plan still says Stage 4.
- That Wayland bytes were inspected. Broker tests see `RecordingSink` tuples from the real dispatcher. One test calls the real `upload_keymap` for the NUL size. That is the right layer for a unit test and it is not a compositor.
### Carried objections
- The plan's stage table and risk paragraph disagree with `CONTRACT-sessions.md` v3 and with the code. Fix the plan, or say in the merge request that the contract wins. Do not treat it as unfinished Stage 4 work.
- Keyboard CLI verbs do not generate `request_id`. Same as pointer gestures. Dedup is for a caller of the control socket.
- `ps` of the CLI's `type` argument shows the string. The plan excludes it. `events.jsonl` does not contain it, on the path the unit test checks (the `keyboard_type` event only; the VM greps the whole file).
- Every acquire moves the cursor by about 3 px and back. Clients see both warps. That is the mechanism, not an accident. `vm-pointer`'s repaired subtest prints the jiggle.
- No `[keyboard]` table. Layout is argv only. Hyprland `input:kb_layout` is not read. Both are what change 5 of the verification asked for.
- The unit pixel check uses `round(y * 720)` (`test_keyboard_verbs.py:650`). Hyprland floors. At `0.004` both differ (2.88 px). A future nudge under one pixel could pass `round` and fail `floor`, or the reverse. The integration assertion of `0.204` is the one that pins the constant.
---
## Stage 3 — the VM check
### Verdict
**done.** Read as a check, not as a log this review produced: two windows, characters on one and silence on the other, a key-up after a real TTL, a second acquire refused, and the symbol taken from the keymap the compositor forwarded. `vm-keyboard-de` is a second run of the same script with `sessions.keyboard.layout = "de"`, and a hardcoded `us` fails it in more than one place. The `vm-pointer` edit repairs a premise the two-warp broke. The helper is on the path the check executes, and a missing binary fails the check rather than falling back. `vm-keyboard` and `vm-keyboard-de` would not pass on `main`. This review did not run them.
### Does the check prove the claim?
The victim compiles the fd from `wl_keyboard.keymap` with xkbcommon and decodes with that state (`checks/lib/keyboard_target.py:177-215`). No keymap, or one that will not compile, is printed as `UNREADABLE` / `WILL-NOT-COMPILE` / `sym=?`, not as a guessed character. The wrapper is `exec ${tools}/bin/hhs-keyboard-target` with no other program (`checks/vm-keyboard.nix:146-148`). Hyprland `input:kb_layout` is left at its default in both runs (`extraConfig` is empty on this machine; `session-machine.nix:55-57` only appends what the check passes). The header of `vm-keyboard.nix` (`:52-80`) records the two places the written spec is now wrong, and the assertions match that header rather than the stale sentences.
What a false green would look like, and what the check does instead:
| Claim | A false green | What is asserted |
| --- | --- | --- |
| Two windows, B focused first | One session, or A's map-time `keyboard enter` counted as the acquire. | `beta` is started second. `focusHistoryID == 0` must be beta's output **before** acquire (`vm-keyboard.nix:457-475`), and beta must already have `keyboard enter` (`:478-482`). The acquire subtest snapshots pointer-enter, keyboard-enter on alpha and keyboard-leave on beta **before** the acquire (`:504-506`) and waits for new ones (`:517-535`). |
| Acquire took the keyboard, not only the cursor | `pointer enter` on alpha, beta still has the keys, `focus` unchecked. That is what one warp does. | `reply["focus"] == "warp"` (`:511-515`). New pointer enter **and** keyboard enter on alpha, keyboard leave on beta (`:517-535`). `focuswindow` or `none` fails the reply assert, so this check does not accept the fallback as success. |
| `hello` on the holder | The log is searched for the substring `hello`, which a script that echoes its argv would satisfy. Or keycodes with no symbol, counted as success. | `typed()` is `sym=` from `keyboard key` lines only (`:241-249`, `:288`). The holder must decode `["h","e","l","l","o"]` (`:627-631`). Any `sym=?` fails (`:632-634`). |
| Silence on the other | Beta never bound a keyboard, so it is silent even when focus never moved. Or beta's key lines scrolled out of the log window (below). | The same subtest requires beta's new key lines to be `[]` (`:619-626`) **and** the positive decode above. Beta bound a keyboard in the focus subtest. The two are one subtest on purpose (`:603-606`). |
| Capital A is a mask | Some non-zero mask anywhere in the log, or a Shift keycode the client ignored. | Press and release are both `sym=A` (`:568-572`), no keycode 42 in the pair (`:573-575`), some mask in the span is non-zero, and the span ends at 0 (`:590-598`). `sym=A` is the ordering proof: the client decodes with the mask it had been given when the key arrived. The comment explains why `span[0]` would flake on the focus-change `modifiers depressed=0`. |
| Key-up after a real TTL | A `state=0` left over from `hello` (those are code 30 and others, not 42). Or an injected clock, which the unit suite already has. | `--ttl` of 8 seconds, `keyboard down Shift_L`, then `wait_until_succeeds` until `pointer state` has a null holder (`:862-889`). The client must report code 42 down then up (`:897-915`) and the mask span must end at 0 (`:916-923`). `type` is not allowed to emit 42, which is why Shift is the key. |
| Second acquire refused | A leftover holder from an earlier subtest, so any acquire of beta exits 8. | This subtest holds `Shift_L` on alpha, **then** has beta acquire (`:807-827`). Exit 8, the holder is still alpha, and `keys` is still `["Shift_L"]`. |
| Symbol from the compositor's keymap | The victim compiled its own `us` table and decoded `hello` from either layout. | `keymap_new_from_string` on the forwarded text (`keyboard_target.py:198`). Exactly one `keyboard keymap` line, not `UNREADABLE`, not `WILL-NOT-COMPILE`, `symbols=` matching the layout (`vm-keyboard.nix:415-438`), and that line's position is before any `keyboard key` line (`:445-452`). |
Residual, not a false green of the happy path: `target_log` asks for `--lines 800` (`vm-keyboard.nix:229`). `keys(beta)[before:]` is a slice of that tail. If beta's older key lines scroll out of the window, the saved index lands past the new tail and the silence slice is `[]` while beta did receive keys. The `hello` subtest is early, and beta has almost no key lines yet, so this is unlikely there. It is a real hole in the negative assertion if a later edit moves the silence check down the script. A false **red** of the same shape (the positive slice starts in the middle of the new events) is the more likely failure if the window is hit.
`format=1` (`vm-keyboard.nix:431-433`) is the format the **client** was given. Hyprland can ignore the format on the virtual-keyboard request and always forward format 1. The check does not prove we uploaded format 1. The unit test of `upload_keymap` is the one that sees the request we sent.
### Does `vm-keyboard-de` exercise a non-`us` layout end to end?
Yes, as written. `checks/default.nix:66-68` calls the same file with `keyboardLayout = "de"`. `session-machine.nix:87-91` sets `sessions.keyboard.layout` from that argument, which is the option the module puts on `ExecStart`. The `de` run then requires all of:
- `--xkb-layout de` on the unit (`vm-keyboard.nix:390-392`);
- forwarded symbols `pc_de_inet(evdev)` (`:161-167`, `:434-438`);
- `type y` arriving as evdev 44 and `type z` as 21, with the sym still `y` and `z` (`:662-692`);
- `type cafü` succeeding, `chars == 4`, decoded as `c,a,f,udiaeresis` (`:710-727`).
A hardcoded `us` fails the symbols line, fails y's code (21 ≠ 44), fails `ü` (exit 2, and the refusal must name `scalar 3` and `U+00FC` without quoting the string, `:728-761`), and fails the argv check. The argv check alone is the false pass the spec named ("greps the unit for `--xkb-layout de` and never types `y`"). It is not the only assertion. Leaving `input:kb_layout` at `us` is what makes a client that ignored our keymap decode the `us` answer on the `de` run.
The spec's "`type y` on `de` decodes to sym `z`" (`docs/plans/2026-10-04-keyboard-verification.md` §B3 subtest 4) contradicts the same section's rule that the victim decodes the forwarded keymap. A correct driver sends `de`'s code for keysym `y`; the client, using that keymap, reads `y` back. The check documents this (`vm-keyboard.nix:52-69`) and asserts the code, the symbols name and whether `ü` is typeable. That is the right reading. Do not "fix" the check to expect `z`.
### Was `vm-pointer` repaired or weakened?
**Repaired.** `54dd109` does not drop the property. It changes how the situation is arranged.
The property is: a warp is delivered to the session it was aimed at, and the window that holds keyboard focus is told nothing (`checks/vm-pointer.nix:449-462`). That is `input:follow_mouse`, not keyboard focus. It used to be free, because one warp did not move keyboard focus, so after acquire the other session was still focused. Two-warp acquire focuses the holder, so the old precondition ("the other window is focused") stopped arranging itself. The new code acquires, asserts the bookmark is still `(0.25, 0.75)` (`:482-485`), then `hyprctl dispatch focuswindow address:…` on the **other** session as setup (`:493-506`), asserts that window is the focused one, then `pointer move` to `(0.6, 0.4)`. The focused client's events since that setup must be empty (`:529-534`). The aimed client's last reported position must be near the aim (`:535-537`).
`before` is taken before the acquire (`:479`), so `mine` includes the two acquire warps. `mine[-1]` against `(0.6, 0.4)` still requires the later move: the acquire restores `(0.25, 0.75)`, which is not close to the aim. `before_other` is taken after the focus command and before the move (`:511`), so the focused client's slice does not include anything from the acquire.
The commit message says `nix build .#checks.x86_64-linux.vm-pointer` passed, 12/12. This review did not reproduce that.
One residual flake, and it is a false **red**, not a false green. `wait_for` returns when **either** client has new events (`:519-523`). The aimed client already has the acquire warps in `positions(session_id)[before:]`, so the wait can return before the move is logged. `mine[-1]` is then the bookmark, the closeness assert fails, and the check goes red. It does not go green.
This check would still pass on `main`. On `main`, acquire does not take keyboard focus, the other session is already focused, and the extra `focuswindow` is a no-op setup of a situation that already holds. The routing property predates the keyboard. That is correct. It is not a keyboard check, and a green `vm-pointer` on `main` says nothing about this feature.
### The helper
`checks/lib/session-tools.nix` builds `hhs-ipc-watch`, `hhs-pointer-target` and `hhs-keyboard-target`. The keyboard one is installed from `keyboard_target.py` and its shebang is rewritten to a Python with pywayland and xkbcommon (`:76-78`). The builder then `test -x`s all three and runs `--help` (`:84-89`), and compiles a real `us` keymap in that interpreter (`:95`). The comment at the top (`:14-35`) describes the old failure: an indented heredoc terminator swallowed the rest of the builder, the derivation still built, and `$out/bin` contained only `hhs-ipc-watch`. The self-tests had become text inside the shim, so they never ran. `writeTextFile` plus those `test -x` lines is what makes that failure a build failure now.
The check uses that binary. `tools` is `session-tools.nix` (`vm-keyboard.nix:127`), the guest wrapper execs `${tools}/bin/hhs-keyboard-target` (`:146-148`), and the first subtest that needs a window fails if the target exits 127 (`:397-413`). There is no `||` and no foot fallback. Nix interpolation of the path depends on the derivation; it does not by itself notice a missing file inside `$out`. The derivation's own `test -x` does, and the check depends on the derivation, so a helper that was not installed fails the check's build. A runtime absence (self-test removed, file deleted after the build) fails in the guest as exit 127, which the "victim never got a window" subtest turns red. Same `tools` output supplies `hhs-pointer-target` to `vm-pointer` and `vm-containers`; those checks fail the same way if the pointer target is absent. The keyboard target is not optional on the keyboard check.
### Would any of this pass on `main`?
`vm-keyboard` and `vm-keyboard-de` would not. `main` has no `keyboard` CLI, no virtual keyboard on the seat (the headless seat has no keyboard capability, and "target: keyboard bound" is the subtest that requires one), no keymap upload, and an acquire that is one warp, so the keyboard-enter half of the acquire subtest fails. `vm-pointer` would. See above. That split is what "load-bearing" means here: the new checks go red without the feature, and the old check still measures the property it measured before.
### Findings
None that change the verdict. Two are worth fixing if the file is touched, and neither is a hole in the claim above.
1. **The chord subtest does not look at the character.** `vm-keyboard.nix:766-805` holds `Control_L`, types `c`, waits until two key events have arrived, and asserts `pointer state` still lists `Control_L`. It never asserts the sym or the code. Two key events of anything, with Control still held, pass. The driver test is the lock (`test_ops.py:653-668`). Cheapest fix: assert the pair decodes to `c`, `c`. The spec's B3 list does not include this subtest; it is extra. Not a reason to call the stage open.
2. **`wait_for` in the repaired `vm-pointer` subtest can return on the acquire warps.** False red, described above (`vm-pointer.nix:479`, `:519-523`). Cheapest fix: take `before` after the acquire, or wait until `mine[-1]` is near the aim. Do not "fix" it by dropping the closeness assert.
### What the merge request must not claim
- That §B3's "`type y` on `de` decodes to sym `z`" was implemented. It was not, correctly. The proof is the evdev code, the symbols name `pc_de_inet(evdev)`, and that `ü` is typeable on `de` and exit 2 on `us`.
- That this review ran `vm-keyboard` or `vm-keyboard-de`. It did not. The `vm-pointer` re-run claimed in `54dd109` was not reproduced here either.
- That `format=1` in the client log proves the driver uploaded format 1.
- That the `focuswindow` fallback was exercised. The check requires `focus == "warp"` and treats the other two values as failure.
- That `vm-pointer` going green is evidence of the keyboard. It is evidence the cursor still goes to the window under it. It would go green on `main`.
- That a silence assertion is safe at any point in a long script. It is a slice of an 800-line tail.
### Carried objections
- The plan's Stage 3 gate still says "do not design the enter subtest from acquire's single warp" (`2026-10-03-keyboard-input.md:323`) and the verification still says one warp (`2026-10-04-keyboard-verification.md` §B3 subtest 1). The check's header is the text that matches the code. Same docs drift as Stage 2 finding 3; one edit covers both.
- The chord subtest, as finding 1. Leaving it does not weaken `hello`, the capital, or the layout run.
- The 800-line tail, as above. Fine for this script's early silence check. Do not copy the pattern into a later subtest without counting lines.
---
## One line
After the two tests in Stage 2 findings 1 and 2, this branch is safe to merge; update the plan's stage table so it matches the contract (or say in the merge request that the contract wins), and nothing else has to happen first.