From 561e0c28f50ca0d603c29e59617772506830b971 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Mon, 5 Oct 2026 04:43:56 +0000 Subject: [PATCH] Stage 2 fixes: the two tests the review named, and the docs drift MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From docs/reviews/2026-10-04-stage2-3-review.md (Stage 3 done; Stage 2 done-with-fixes). Its findings 1, 2, 3 and 5, which it called the only things standing before merge. (A) REPLAY, THROUGH THE SINK. What existed was `test_every_keyboard_verb_is_cached_for_the_same_reason`, which asserts the two verbs are in MUTATING_VERBS -- and the verification doc had already named that as the false pass: "asserting `deduplicated` and not the sink. A handler that types and then sets the flag stays green." Two integration tests now, modelled on `test_a_retried_click_with_the_same_request_id_clicks_once`: test_a_retried_type_with_the_same_request_id_types_once `keyboard.type` of "ab" twice with request_id="retry-me". Asserts `deduplicated`, chars == 2 on both, and that the sink still has exactly 4 key events -- two characters, a down and an up each -- so a replay that typed again is caught by the count and not by the flag. test_a_retried_unmappable_type_stays_refused_and_types_nothing `café` twice with one id. Both refusals are `invalid_argument`, the second carries `deduplicated` (a recorded failure is replayed as the failure it was), and the sink is empty after both -- there is no partial type on either call. Mutation-checked rather than assumed: removing `keyboard.key` and `keyboard.type` from MUTATING_VERBS fails both. (B) KILL, THROUGH kill(). `test_killing_the_holder_lifts_its_keys` calls `_drop_lease_for` directly, so it proves that helper lifts keys and says nothing about whether `kill` still calls it. The integration kill test now holds `Shift_L` before the kill and asserts the SINK saw `("key", 42, 0)` and `("modifiers", 0, 0, 0, 0)` -- the lease forgetting a key is not the compositor being told it came up, and only the second matters to the application. Code 42 because `type` never emits it, so the release cannot be a leftover. Mutation-checked: stubbing out the `_drop_lease_for` call in `kill()` fails it. Before this it stayed green. (C) DOCS. The plan's stage table and risk paragraph still said acquire is one warp and that `focuswindow` was unbuilt Stage 4 work. The contract (v3 §4) describes what shipped; the plan did not. Rewritten so they agree, and the plan now says outright that the contract wins where they differ: * risk 1 marked RESOLVED, describing the two warps, the pinned `follow_mouse_threshold`, and `focuswindow` as the nudge-failure fallback selecting on `address:` (not `stable_id`, which is not a Hyprland selector) * Stage 3 marked Done; Stage 4 struck as not existing -- the answer to Stage 0 was the second warp, not a focus dispatch * the top banner, the §5 VM assertion list and open question 2 no longer say "one warp" * verification §B3 subtest 1 amended: it is a live assertion rather than an expected red, and the check additionally requires `focus == "warp"` so the fallback is not accepted as success Also amended one sentence the review did not list, because leaving it would contradict the edit above inside the same document: verification §"Warp does not guarantee wl_keyboard.enter" predicted `focuswindow` was "likely mandatory". It was not; the second warp was. Written down rather than smoothed over: the `focuswindow` branch itself has no test, and if both mechanisms fail acquire still returns ok with `focus="none"` -- a lease whose first key may go to the previously focused window. (D) The tap docstring claimed the `up` is sent even if the `down` was refused after sending. The next lines return early on `not ok`, and that early return is right: a refusal means the key was never pressed, so an `up` would ask the compositor to release something it never had. Sentence replaced with why the early return is correct and what actually covers a lost reply (the broker's `release_all`, not the CLI, which cannot know whether the request arrived). Not done, and not claimed: findings 4, 6 and 7 (the broker chord test checking first/last mask rather than the key; the at-cap test not looking at the sink; the module-defaults test being a substring match). The review rates all three as not holes in the claim, and the driver tests are the locks for the first two. nix develop -c python -m pytest tests -q 907 passed in 67.71s nix develop -c python -m pytest tests/pointer tests/sessions/unit -q 605 passed in 27.16s Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM --- docs/plans/2026-10-03-keyboard-input.md | 37 ++-- .../plans/2026-10-04-keyboard-verification.md | 6 +- docs/reviews/2026-10-04-stage2-3-review.md | 178 ++++++++++++++++++ src/hhstream_session/__init__.py | 12 +- tests/sessions/integration/test_containers.py | 103 ++++++++++ 5 files changed, 321 insertions(+), 15 deletions(-) create mode 100644 docs/reviews/2026-10-04-stage2-3-review.md diff --git a/docs/plans/2026-10-03-keyboard-input.md b/docs/plans/2026-10-03-keyboard-input.md index 7ca8c98..7baab59 100644 --- a/docs/plans/2026-10-03-keyboard-input.md +++ b/docs/plans/2026-10-03-keyboard-input.md @@ -21,12 +21,18 @@ > | 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). -> The three open behavioural questions are answered, and one answer is worse -> than this document assumes: **a single idle warp does not move keyboard -> focus**, so `pointer acquire` — which is one warp — can leave the first key -> of a lease going to whatever was already focused. §6 risk 1 still holds and -> the fallback is still not built in Stages 1–2. +> **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. @@ -279,7 +285,7 @@ Match the split already in the tree: the dispatcher is tested against a recordin - 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. If it fails, the check is red and Stage 4 is in play — do not weaken the assertion. + 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. @@ -294,7 +300,16 @@ Match the split already in the tree: the dispatcher is tested against a recordin - **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`. - **`pointer acquire` is one warp**, so the first key of a lease can land in whatever was already focused. The fallback is the one named below — `dispatch focuswindow` on the session's `window.stable_id`, immediately before the first key of a lease — and **it is still not built in Stages 1–2.** Two things that are *not* the fix: warping twice to the same bookmark (the same floored pixel returns early), and waiting longer after the warp (the first warp's settle window was 0.4 s and contained the pointer enter alone). Stage 3's enter subtest must not be written against acquire's single warp. + **[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`). @@ -307,7 +322,7 @@ Match the split already in the tree: the dispatcher is tested against a recordin 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`?~~ **No — not from a single idle warp.** See risk 1 above; this is the one answer worse than the plan assumed. +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. @@ -320,7 +335,7 @@ Questions 1–4 are **closed by Stage 0** (`tests/README-keyboard-probe.md` and | 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 | `vm-keyboard.nix` and the keyboard target client. **Do not design its enter subtest from acquire's single warp** — Stage 0 says that does not focus. | M, about 2–3 days | Characters on A, silence on B, key-up after a real TTL, second acquire is 8. Red if the keymap was not uploaded. | -| 4 | **No longer contingent: Stage 0 showed no `enter` after a single idle warp.** `focuswindow` via the broker's existing compositor IPC, immediately before a lease's first key, then re-run Stage 3. Still not to be built in Stages 1–2. | S, about a day | The Stage 3 enter assertion goes green without loosening it. | +| 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. \ No newline at end of file diff --git a/docs/plans/2026-10-04-keyboard-verification.md b/docs/plans/2026-10-04-keyboard-verification.md index b15b9aa..4a86450 100644 --- a/docs/plans/2026-10-04-keyboard-verification.md +++ b/docs/plans/2026-10-04-keyboard-verification.md @@ -161,6 +161,8 @@ Pointer focus is updated later in the same function with no threshold. That is w 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. @@ -315,7 +317,9 @@ Victim: a sibling of `checks/lib/pointer_target.py`, not foot and not Chromium. 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, one warp. A's log shows `enter` for A's app id **after** the acquire, and B's log shows `leave`. If (a1) of Stage 0 was "no enter", this subtest is expected red until the double-warp or `focuswindow` fallback is in, and the assertion is not weakened to "cursor coordinates look right". +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`. diff --git a/docs/reviews/2026-10-04-stage2-3-review.md b/docs/reviews/2026-10-04-stage2-3-review.md new file mode 100644 index 0000000..81573f2 --- /dev/null +++ b/docs/reviews/2026-10-04-stage2-3-review.md @@ -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. diff --git a/src/hhstream_session/__init__.py b/src/hhstream_session/__init__.py index ec7f3b0..db35def 100644 --- a/src/hhstream_session/__init__.py +++ b/src/hhstream_session/__init__.py @@ -1255,9 +1255,15 @@ def _cmd_keyboard_key(args: argparse.Namespace) -> int: """A tap: down then up, as two wire calls. Two calls and not a `count`-style loop in the broker, because a tap is the - only thing anyone wants and the pair is what `down`/`up` already are. The - `up` is sent even if the `down` was refused-after-sending, for the same - reason the broker lifts on expiry: a key left down is worse than stuck. + only thing anyone wants and the pair is what `down`/`up` already are. + + A refused `down` returns without sending the `up`, and that is deliberate: + a refusal is the broker saying the key was never pressed -- a bad keysym, + no lease -- so an `up` would ask the compositor to release something it + never had. A reply *lost* after a successful down is a connection error + rather than ``ok: false``, and the broker's own `release_all` on expiry is + what covers that; the CLI cannot, because it does not know whether the + request arrived. """ lease_id = _lease_of(args, args.id) diff --git a/tests/sessions/integration/test_containers.py b/tests/sessions/integration/test_containers.py index 25e224a..b7eb962 100644 --- a/tests/sessions/integration/test_containers.py +++ b/tests/sessions/integration/test_containers.py @@ -517,14 +517,42 @@ def test_a_button_left_down_is_lifted_when_the_lease_is_released(rig: Rig): def test_killing_a_session_that_holds_the_cursor_gives_it_back(rig: Rig): + """Through `kill`, with a button AND a key down. + + The key half is here rather than in a unit test on purpose. The unit test + calls `_drop_lease_for` directly, so it proves that helper lifts keys and + says nothing about whether `kill` still calls it -- removing the call would + leave that test green. This goes through the verb, and it asserts on the + SINK rather than on `pointer.state`: the lease forgetting a key is not the + same as the compositor being told it came up, and only the second one + matters to the application. + """ + first = start(rig.daemon, "sleeper") second = start(rig.daemon, "sleeper") lease = rig.daemon.call("pointer.acquire", id=first)["lease_id"] rig.daemon.call("pointer.button", id=first, lease_id=lease, button="right", state="down") + held = rig.daemon.call( + "keyboard.key", id=first, lease_id=lease, key="Shift_L", state="down" + ) + assert held["keys"] == ["Shift_L"], held + rig.driver.sink.calls.clear() rig.daemon.call("kill", id=first, grace_s=0) + # KEY_LEFTSHIFT, and `state=0`. Shift is the key to use because `type` + # never emits code 42, so a release of it cannot be a leftover from + # anything else this rig did. + assert ("key", 42, 0) in rig.driver.sink.calls, ( + f"kill did not lift the held key: {rig.driver.sink.calls}. On this " + "compositor a code left in the seat's m_pressed makes the NEXT press " + "of it a no-op, so the key is dead rather than merely stuck." + ) + # And the mask with it: a virtual key-up clears no modifier state, so + # without this the next holder inherits Shift. + assert ("modifiers", 0, 0, 0, 0) in rig.driver.sink.calls, rig.driver.sink.calls assert rig.driver.dispatcher._pressed == {} + assert rig.driver.dispatcher._keys == {} assert rig.daemon.call("pointer.state")["holder"] is None assert rig.daemon.call("pointer.acquire", id=second)["ok"] @@ -561,6 +589,81 @@ def test_a_retried_click_with_the_same_request_id_clicks_once(rig: Rig): assert len(rig.driver.sink.of("button")) == 2, "one press and one release, not two" +def test_a_retried_type_with_the_same_request_id_types_once(rig: Rig): + """A retried `type` is the keyboard's version of a second click. + + Asserted on the SINK and not on the `deduplicated` flag, because the flag + alone is the false pass the verification doc names: a handler that typed + the string and *then* set the flag would satisfy it. The thing that must + not happen twice is the key events, so those are what is counted. + + The cache is not keyboard-specific -- `_dispatch` looks the `request_id` up + before the handler and remembers it after, keyed on the id alone -- so what + this locks is that `keyboard.type` is in the mutating set and therefore + reaches that path at all. + """ + + session_id = start(rig.daemon, "sleeper") + lease = rig.daemon.call("pointer.acquire", id=session_id)["lease_id"] + rig.driver.sink.calls.clear() + + first = rig.daemon.call( + "keyboard.type", id=session_id, lease_id=lease, text="ab", request_id="retry-me" + ) + second = rig.daemon.call( + "keyboard.type", id=session_id, lease_id=lease, text="ab", request_id="retry-me" + ) + + assert first["ok"] and second["ok"] + assert second.get("deduplicated") is True + assert first["chars"] == 2 and second["chars"] == 2 + # Two characters, a down and an up each: four key events for one `type`, + # and the replay must not add a fifth. + assert len(rig.driver.sink.of("key")) == 4, ( + f"a replayed type sent {rig.driver.sink.of('key')}; the recorded answer " + "must be returned without typing again" + ) + + +def test_a_retried_unmappable_type_stays_refused_and_types_nothing(rig: Rig): + """The recorded answer includes a recorded refusal. + + An agent that retries a `type` which was refused must see the refusal + again, not a second attempt -- and the sink must still be untouched after + both calls, because validation happens before the first event either time. + """ + + session_id = start(rig.daemon, "sleeper") + lease = rig.daemon.call("pointer.acquire", id=session_id)["lease_id"] + rig.driver.sink.calls.clear() + + first = rig.daemon.call( + "keyboard.type", + id=session_id, + lease_id=lease, + text="caf\u00e9", + request_id="refuse-me", + ) + second = rig.daemon.call( + "keyboard.type", + id=session_id, + lease_id=lease, + text="caf\u00e9", + request_id="refuse-me", + ) + + assert first["ok"] is False and second["ok"] is False + assert first["error"] == "invalid_argument", first + assert second["error"] == "invalid_argument", second + assert second.get("deduplicated") is True, ( + "a recorded failure must be replayed as the failure it was" + ) + assert rig.driver.sink.of("key") == [], ( + f"an unmappable string typed something: {rig.driver.sink.calls}. There is " + "no partial type, on the first call or the replay." + ) + + def test_a_restored_bookmark_survives_a_daemon_restart(short_tmpdir: Path): """That is what putting it in the record, and not only in the lease, is for."""