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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
30 KiB
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.
-
The replay test asserts set membership, not the sink. The verification's own false pass (
docs/plans/2026-10-04-keyboard-verification.md§B2): "Assertingdeduplicatedand not the sink. A handler that types and then sets the flag stays green." What landed istest_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 inMUTATING_VERBS. The cache itself is real and is not keyboard-specific:_dispatchlooks uprequest_idbefore the handler andremembers 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 countssink.of("button"). Nothing replayskeyboard.type, and nothing replays an unmappabletypeand asserts the sink stayed empty. The CLI does not send arequest_idon keyboard verbs (same as the pointer gestures;--request-idis 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.typeof"ab"withrequest_id="retry-me", a second call with the same id, assertdeduplicatedand that the sink'skeycount did not grow. A second case, an unmappable string, same id twice, sink still empty. -
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) callsmanager._drop_lease_for(..., "kill")and then looks for the key-up on the sink.SessionManager.killdoes call_drop_lease_for(session, reason="kill")(manager.py:1232-1237), so the production path is there. The spec named the false pass: akillof a session that does not hold the lease, or akillthat no longer calls the helper, stays green. The existing integration kill test (test_containers.py:520-529) assertsdispatcher._pressed == {}and a null holder. It never holds a key, so removing the call fromkill()while leaving_drop_lease_foritself correct stays green.Cheapest fix: in that integration test,
keyboard.keydown ofShift_Lbeforekill, then assert the sink lifted it (orpointer.statekeys == []after, which is weaker — prefer the sink). -
focuswindowis inside acquire, on nudge failure, and the plan still says it is Stage 4. The code matchesdocs/CONTRACT-sessions.mdv3 (:407-413): two warps, reply fieldfocusofwarp/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", onwindow.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, callhyprctl dispatch focuswindowwithaddress:fromsession.container.window.addressor elsepid:{session.pid}, then still send the target warp. The target warp's failure still drops the lease (manager.py:1640-1644).address:is the selectorvm-pointeritself 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_idwould 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
focuswindowis the narrow one where the nudge fails and the target warp succeeds. Nothing tests it.test_acquire_sends_two_motions_so_keyboard_focus_movesrequiresfocus == "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 reportsfocus="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
focuswindowbefore 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 onefocuswindowplus the target warp is worth having; it is not what makes the two-warp true. -
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) assertscalls[0]andcalls[-1]are the Control mask and that the lease still holdsControl_L. It does not assert akeyevent forcbetween 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. -
The tap's comment describes a behaviour the code does not have.
_cmd_keyboard_keysays the up is sent even if the down was refused after sending (src/hhstream_session/__init__.py:1257-1260). The next lines return immediately whendownis notok(: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, notok: false, so the sentence is not implemented and should not be. Cheapest fix: delete the sentence. -
test_exactly_the_cap_is_accepteddoes not look at the sink (test_keyboard_verbs.py:366-373). It assertsreply["chars"]. A handler that returned the count and never called the driver stays green. The over-cap test does assertsink.calls == []. Cheapest fix: assert the sink is non-empty, or at least that its length is2 * MAX_TYPE_SCALARSkey events. Low; the dispatcher has its own cap tests. -
test_the_module_passes_the_same_defaults_this_binary_hasis a substring ofnix/module.nix(test_driver_flags.py:160-174).default = "us"in a comment, or"--xkb-layout"anywhere in the file, satisfies it. The VM'sExecStartassertion 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.typewas shown not to type twice. Membership inMUTATING_VERBSwas shown. The click replay test covers the cache for clicks. - That
kill()was shown to lift keys._drop_lease_forwas shown to.kill()contains the call; no test goes through it with a key down. - That
focuswindowis 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, returnsfocus="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
RecordingSinktuples from the real dispatcher. One test calls the realupload_keymapfor 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.mdv3 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. psof the CLI'stypeargument shows the string. The plan excludes it.events.jsonldoes not contain it, on the path the unit test checks (thekeyboard_typeevent 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. Hyprlandinput:kb_layoutis 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. At0.004both differ (2.88 px). A future nudge under one pixel could passroundand failfloor, or the reverse. The integration assertion of0.204is 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 deon the unit (vm-keyboard.nix:390-392);- forwarded symbols
pc_de_inet(evdev)(:161-167,:434-438); type yarriving as evdev 44 andtype zas 21, with the sym stillyandz(:662-692);type cafüsucceeding,chars == 4, decoded asc,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 -xs 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.
-
The chord subtest does not look at the character.
vm-keyboard.nix:766-805holdsControl_L, typesc, waits until two key events have arrived, and assertspointer statestill listsControl_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 toc,c. The spec's B3 list does not include this subtest; it is extra. Not a reason to call the stage open. -
wait_forin the repairedvm-pointersubtest can return on the acquire warps. False red, described above (vm-pointer.nix:479,:519-523). Cheapest fix: takebeforeafter the acquire, or wait untilmine[-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 yondedecodes to symz" was implemented. It was not, correctly. The proof is the evdev code, the symbols namepc_de_inet(evdev), and thatüis typeable ondeand exit 2 onus. - That this review ran
vm-keyboardorvm-keyboard-de. It did not. Thevm-pointerre-run claimed in54dd109was not reproduced here either. - That
format=1in the client log proves the driver uploaded format 1. - That the
focuswindowfallback was exercised. The check requiresfocus == "warp"and treats the other two values as failure. - That
vm-pointergoing green is evidence of the keyboard. It is evidence the cursor still goes to the window under it. It would go green onmain. - 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.