Files
komorebi/e2e/platforms/qemu_windows/W1.md
T
LGUG2Z ff3711dcb5 docs(e2e): document the Windows guest and what it found
README.md: building the image, running scenarios, the variables, the known
failures. W1.md: the measurements and findings behind them.
2026-10-30 18:59:32 -07:00

22 KiB

W1: pointer and second display

Measured 2026-10-28 on the same machine and guest as W0, with w1_probe.py, on a golden image built from scratch.

Pointer: works

QMP input-send-event through usb-tablet (absolute axes, 0 to 32767 over the 1280x800 display) drove a drag of a komorebi-testwin title bar: asked for a move of (200, 100) pixels in ten steps of 50 ms, the DWM frame moved by exactly (200, 100). Qmp.pointer_move and pointer_button are enough for the drag and focus-follows-mouse scenarios; not tried yet with komorebi running (live resize, drag-swap).

Second display: a second QXL device and Red Hat's driver works

-device secondary-vga gives QEMU a second head, but Windows' basic display driver does not use it: the agent's displays verb still reports one monitor. A second QXL device does, once the signed qxldod display driver is installed (from virtio-win 0.1.285-1, its qxldod/w10/amd64 files, on a CD; Windows 11 build 26100 took the w10 driver, no reboot):

-device qxl,id=qxl2,ram_size_mb=64,vram_size_mb=64,vgamem_mb=16
pnputil /add-driver D:\qxldod.inf /install ; pnputil /scan-devices

Afterwards the agent reported two displays, 1280x800 at (0, 0) and 1024x768 at (1280, 0), and kfw's own komorebic state listed two monitors with distinct ids (65610 and 131073). The sizing follows the SPICE docs and a Proxmox report that 64 MB avoided error 12 on extra QXL heads on Windows 11; other sizes were not tried. The driver is Red Hat's, signed, from the nix package the repo can pin, so the third-party IddCx driver is not needed for this.

Still to do: put the driver in the golden image (setup.ps1, from the answer ISO) so a run can add the second head without installing it, a screendump per head (device=qxl2), hotplug of the second device, and setting a resolution.

Not verified

  • Multi-monitor behaviour of kfw beyond the monitor list: the move-to-monitor scenarios and hotplug.
  • Pointer input while komorebi is running.

Where a drag-resize falls short

kfde's resize scenario drags the edge two tiles share by 60 px. On kfw the edge moves 53 px (dx 30: 27, dx 60: 53, dx 120: 96). w1_drag.py drags the right border of a plain komorebi-testwin that no daemon manages, by the same distances, and reads the cursor with Cursor.Position:

dx cursor after release window's right edge moved
30 exactly the asked x 30
60 exactly the asked x 60
120 exactly the asked x 120

The frame also follows the pointer during the glide at a constant 4 px offset. So the input path (QMP tablet, Windows' cursor, the resize loop) is exact, and the loss is in what kfw does with the drag. Where to look: MoveResizeEnd handling in komorebi/src/process_event.rs and the resize code that commit a3fac99a changed. Not investigated further.

Retest against kfw 0c9acdf4

komorebi.exe and komorebic.exe built from 0c9acdf4 (the animation branch, which contains a3fac99a), with this tree's flake fixes copied in so that it builds; same golden image, same scenario:

dx master (21a821ac) 0c9acdf4
30 +27, passes +27, passes
60 +53, fails +51, fails
120 +96, fails +106, fails

Not fixed by the scenario's measure (the left tile 60 +/- 6 wider). The shortfall differs in size (9 and 14 px at dx 60 and 120) but is still there.

Hotplug of the second display (w1_hotplug.py)

The guest boots with one display, a PCIe root port (pcie-root-port,id=rp1) and the driver CD; the driver is put in the store with pnputil /add-driver, then QMP device_add driver=qxl bus=rp1 ... adds the head and device_del removes it, with kfw running. Two runs, same results:

Step Windows kfw monitors
before 1 display 1
after device_add (3.6 s and 6.8 s to a second display) 2 displays 2
after device_del (1.0 s) 1 display 1 after 3 s in one run, 2 in the other

So a display can be added and removed at runtime, and kfw follows both ways; its monitor list lags the removal by a few seconds, so a scenario has to wait for it rather than read it at once. Seen in both runs: the agent's first displays call during device_add came back empty (the connection was dropped) and a reconnect worked; the agent process survived. Not investigated (a windows subsystem program shows no panic message).

What komorebi-recorder saw (kfw master, dx = 60)

The runner's record step (KOMOREBI_E2E_RECORDER=<dir of komorebi-recorder.exe>) ran the scenario with komorebi at trace level and the recorder in the guest (record --window-track; screen capture works in the headless guest). From the session:

  • windows.jsonl (window rects at about 30 ms): win1 is 596 px wide when the drag starts and grows steadily to 656, so the window itself grew by exactly the 60 px dragged. The input and the Windows resize loop are exact, as w1_drag.py showed.
  • komorebi.log, at MoveResizeEnd: resizing with mouse, then resize_window{direction=Right sizing=Increase delta=106 update=false}. kfw works out a delta of 106 from a 60 px drag.
  • Afterwards win1 is 649 wide and the right column starts at 710: the edge moved 53, which is 106 / 2. So the number to look at is the 106: a 60 px drag should give 120 if the delta is split between the two tiles (60 x 2), and kfw gave 14 less. For dx 30 and 120 the shortfalls were 6 and 48 (deltas 54 and 192), which is not a constant like twice an invisible border.

The cause, read off the same session: the delta is 2 * (end_right - start_right) (komorebi/src/process_event.rs, the resizing with mouse branch), and start_right comes from started_from, the window's rect that the MoveResizeStart handler reads when the event is processed (kfw master process_event.rs, near let started_from = WindowsApi::window_rect(...)). The recorder puts that moment, mapped through timeline.jsonl, at 1.79 s into the video, and at 1.77 to 1.80 s win1 was already 603 to 608 px wide: the drag had begun about 100 ms before and the window had grown 7 to 12 px. So the measured drag is 656 - 603 = 53, and 2 x 53 = 106, the delta in the log. A longer drag moves further before the event is processed, which is why the loss grows with the distance (3, 7 and 24 px for 30, 60 and 120). The fix to try is reading the start rect before the drag has moved the window, for example from the container's tile (latest_layout) or in the WinEvent callback that queues the event. Not tried. The session is in ~/e2e-w0/rec1/resize/session/rec on the machine that ran it.

A window sent to a monitor that does not exist (w1_sendmon.py)

With one display and three tiled windows, komorebic send-to-monitor 1 exits 0 and prints nothing, and afterwards the daemon manages two windows while the OS still has all three. So kfw stops managing a window it was asked to send to a monitor that is not there; the window stays on screen, untiled. Seen on kfw master (21a821ac) in a fresh guest, once. kfde's commands sweep used to assume two monitors, so its 20 failures after this command were this effect (the sweep now adds a display first).

The commands sweep and unknown_monitor on kfw

On the golden image with the logging agent (golden6), kfw master:

  • unknown_monitor: fails 2 of 12 checks, as it does on KDE: after send-to-monitor 7 and after move-to-monitor 7 the daemon no longer manages every window. kfw's move_container_to_monitor removes the focused container before it looks up the target monitor (komorebi/src/window_manager.rs, around remove_focused_container).
  • commands with two displays: 245 passed, 2 failed at first, both komorebic toggle-focus-follows-mouse exiting 2 with the subcommand's help text, because kfw's subcommand needs an argument; kfde's sweep now passes --implementation windows, and the sweep passes 247/0.
  • Four repeats of that sweep: runs 1 and 2 failed (komorebic state timed out with os error 10060; the daemon stopped answering after replace-configuration and eager-focus), runs 3 and 4 passed 247/0. Runs 1 and 2 overlapped a KDE VM suite on the same machine and a nix build of mine, and the daemon log showed state replies going from milliseconds to about a second before the timeout, so this is taken as host load, not shown to be. An earlier run died with QEMU aborting in SPICE's handle_dev_oom, before -spice was added.
  • lifecycle (stop, start again): 17 of 17, with the tiled windows only. rules with the old-rule extension: 9 of 9. unknown_monitor is a known failure with a reason string; the runner prints known failures: 2.
  • resize at komorebi 0ffc502c ("measure a drag from where the tile was"): 18 of 18, a 60 px drag widens the left tile by exactly 60.

The pointer with two displays

w1_pointer2.py adds the second display (1024x768 at (1280, 0) next to the 1280x800 first one) and moves QMP's absolute tablet to five fractions of its range. Windows put the cursor at x = 0, 319, 639, 959 and 1279 for 0, 0.25, 0.5, 0.75 and 1.0: the whole tablet range lands on the first display, and the second one cannot be reached with it. So WindowsPointer is a pointer on the first display only, which is what it was built for; resize and the drags use nothing else.

Not tried: a second, relative device (usb-mouse, rel events), whose motion Windows would scale by its pointer speed, and a tablet whose descriptor asks for the virtual desktop. Neither is worth doing until a scenario needs the pointer on the second display.

komorebic stop with windows put away

w1_stop_hidden.py: three tiled windows, win3 sent to workspace 1 (cloaked), win1 minimized, then komorebic stop and a fresh komorebi.exe --clean-state.

  • After the stop win3 is uncloaked and where its tile was; win1 stays minimized. So kfw gives back the windows it had cloaked.
  • After the start the daemon has win2 and win3 on workspace 0, tiled (596 wide each, win3 back from workspace 1), and does not manage win1: a minimized window is not taken up. The workspace assignment is not kept (--clean-state), which lifecycle does not ask for either.
  • The probe itself ended in an IndexError asking for workspace 1 after the start, which no longer exists; fixed to ask for workspace 0 only.

placement: a number as initial_window_placement_rules

placement (kfde's, with Platform.restart_with) on kfw: "no rules" gives a, b, c and "Primary" gives c, b, a, as kfde expects. The case with the rules 2 as a JSON number does not run: komorebi.exe --config exits at start with data did not match any variant of untagged enum InitialWindowPlacementRules (w1_placement_int.py, with stderr captured). The string "2" starts. The type's docs (komorebi/src/core/mod.rs) say an integer is accepted, but PlacementTarget deserializes with String::deserialize, which takes a string only. The runner records that case as a known failure and runs the others.

Restoring a saved guest

The runner can restore every guest from a state saved after one boot (KOMOREBI_E2E_STATE, state.py, Guest(state=...)). A separate investigation measured, with the load noted in its own log: cold boot to the agent answering 50 to 86 s, restore 1.5 to 3 s; a whole tiling run 106 s cold against about 7 s restored. Through the runner: saving the state took 130 s once, then placement, tiling and lifecycle ran in 81 s together and passed (4, 10 and 17 checks, one known failure). Notes:

  • QEMU 10.2.2 refuses to migrate a guest with an NVMe disk (State blocked by non-migratable device .../nvme), so a guest that is saved or restored has its disk on an AHCI controller (ich9-ahci, ide-hd); the golden image boots on it unchanged. A cold guest keeps NVMe.
  • The saved memory belongs to the disk as it was: the state has its own overlay, which is the read-only base of every run's overlay, and copies of vars.fd and the TPM state. Restores do not modify it (checked by md5).
  • The guest's clock is the instant of the save. The state is about 2.7 GB for 6 GB of RAM and fits the golden image, the QEMU version and the command line, so state.py keys it on those and makes a new one when they change.
  • Not tried: internal snapshots (snapshot-save), saving with a hotplugged display, and scenarios beyond tiling, lifecycle, placement and hotplug.

The mutation check, and five runs in a row

Mutation (Phase 2 exit): in a scratch worktree of 0ffc502c, never committed, every tile got right += 200 right after the layout is calculated (komorebi/src/workspace.rs). All 14 scenarios, restored guests, scale 1.5: 65 checks failed and every one is a geometry check ("inside the work area", "do not overlap", "and they tile, not on each other", "two tiles share a vertical edge", the display-tiling checks of hotplug and commands, and each of the eight change-layout lines). rules and placement check only the order of windows and stayed green. Nothing that is not about geometry went red.

Five green runs on 0ffc502c: run 1 green (all 14 scenarios); runs 2 and 3 each failed one check, hotplug's "after a display is unplugged the daemon has one monitor fewer"; stopped after run 3. So the exit item is not met with hotplug in the set.

A monitor that is unplugged stays in kfw's list

w1_hotplug_lag.py (plug and unplug a QXL display, debug log, no windows): Windows has one display 0.1 to 0.9 s after device_del, and komorebic state lists two monitors for the whole 90 s, in every round, on master (21a821ac) and, in an earlier probe, on 0ffc502c. The daemon log loops: "potential monitor removal detected (2 vs 1), verifying in 3s", "verified monitor removal (2 vs 1), removing disconnected monitors", "removing disconnected monitors", and again, every 3 s; the removal never takes effect.

A reading, not shown: in komorebi/src/monitor_reconciliator/mod.rs (about line 601) a monitor stays when attached.serial_number_id.eq(&m.serial_number_id) || attached.device_id.eq(&m.device_id); with no EDID serial, None == None is true, so the unplugged QXL monitor (named "UNKNOWN" in the log) matches the primary and is never found missing. The loop at about line 561 guards with if let (Some, Some); this one does not. Why the check passes in some runs is not known (it passed 19 of 19 several times). It is not a known failure in the runner, because a known failure that holds fails the suite and this one holds only sometimes.

What went wrong on the machine, so it is not repeated

  • Every finished guest left its run directory (overlay, firmware variables, TPM state, several hundred MB) in the output directory: 135 of them, 62 GB, and with old golden images and scratch the drive filled and WSL2 crashed. Guest now deletes its run directory at exit (KOMOREBI_E2E_KEEP_GUEST=1 keeps it).
  • A unix socket path is limited to about 108 bytes. A run directory under a long $TMPDIR made swtpm and QEMU fail ("Path for UnixIO socket is too long"), and the guest then looked like one that never answers. Guest now refuses a run directory that is too long; the state build uses a directory next to the state.
  • After a WSL restart the page cache is empty and the golden image reads at about 105 MB/s; a second guest or a build doing heavy I/O at the same time starves a cold boot past the agent's 180 s. One guest at a time, and read the image through once (cat disk.qcow2 > /dev/null) after a restart.

Focus follows mouse (2026-10-29, w1_ffm*.py, komorebi 0ffc502c)

kfw's setting is Windows' own active window tracking (SPI_SETACTIVEWINDOWTRACKING): a QMP tablet move over a window gives it the focus in 0.2 to 0.4 s, and nothing moves it while the setting is off. It is a hover delay: a pointer that leaves a window again within milliseconds, as in a move to the already focused window followed at once by a move to the other, is not an entry into the other one. The scenario's last check failed five of five runs for that reason (a wait that returned at once, after which the pointer moved on), and passed 3 of 3 once kfde's scenario rested the pointer over the focused window. The probes' pass or fail followed that timing, not the parking spot, the enable/toggle way of turning it on, or the scenario's state call.

Exe rules, config reload, locking (2026-10-29)

  • kfw names the exe of a window with its extension (e2e-exe-sent.exe), so workspace-rule exe e2e-exe-sent and ignore-rule exe e2e-exe-left match nothing, and the rules_exe scenario fails 3 of 5. With .exe in the ids it passes 5 of 5 (w1_rules_exe.py). ignore-rule drops a rule whose id an earlier ignore rule has, whatever its kind, as on KDE (it compares ids only, process_command.rs).
  • The daemon watches the configuration file it was started with, as the hotwatch in static_config.rs says: rewrite_config only writes the file and config_reload passes 8 of 8; the windows_config_file extra checks it. (An earlier note here said it did not watch the file: wrong, the scenario had been run with replace-configuration after each write, which hid the reload.)
  • The image forbids locking (DisableLockWorkstation, NoLockScreen), so lock() sets the policy to 0 first, runs LockWorkStation and waits for LogonUI.exe; unlock() presses a key and types the account's password with QMP keys. While locked the agent still lists the user's windows (42) and can move one: SetWindowPos works, and kfw puts the window back in its tile within a second of the unlock (w1_lock.py). A frame is the visible bounds, 7 px in from the window rect on the left, so move_window corrects for that to put the frame's corner where it is asked.

Extras, extras/*.py (2026-10-30)

Run as windows_padding, windows_cloaking, windows_config_file, windows_tracking and windows_second_display: the tiling windows, then the extra, its checks labelled [windows].

  • Windows are padding + container padding + 7 px from every edge and 2 * (container padding + 7) apart (27 and 34 px by default). The 7 is kfw's border: BORDER_WIDTH 8 plus BORDER_OFFSET -1, taken off the layout when borders are on (monitor.rs). It answers the 7 px that the state does not name.
  • A window on another workspace is cloaked and not minimized; a minimized one is minimized and not cloaked; komorebic stop uncloaks the first and leaves the second minimized.
  • focus-follows-mouse enable and disable set SPI_SETACTIVEWINDOWTRACKING.
  • With a second display the monitor has the display's size, move-to-monitor 1 takes a window there, and the daemon's focus is the OS's.

Changing the mode of a display (2026-10-30)

w1_display_modes.py, w1_display_change.py, display.ps1.

  • The first display of the guest is the Microsoft Basic Display Adapter with one mode, 1280x800: it cannot change. The second is the QXL device (Red Hat's driver) and lists about 30 modes, 640x480 to 2560x1600. ChangeDisplaySettingsEx on \\.\DISPLAY2 returns 0 and the display has the mode at once. (PowerShell's own calls to EnumDisplayDevices failed with the struct passed by reference; the same calls from C# compiled by Add-Type work, so display.ps1 has the logic in C#.)
  • With two windows on the second monitor, kfw follows every change within the first second: the monitor size and work area are the new ones, and the windows are inside the work area and clear of each other at 1280x720, 800x600 and back at 1024x768. The windows_display_change extra checks that, and that the windows are where they were when the mode is back.
  • A change of the Windows scale (DPI) is not tried: it needs a sign-out.

kfde's new scenarios, first run (2026-10-30, next 6d862a11, scale 3)

One guest beside a KDE batch (load average about 5.6; the binary upload took 8.6 s against about 1 s). Results, all marked load-suspect until rerun alone:

  • queries 5/0 (one skip: fewer than two containers), layout_flip 62/0, handover 15/0, display_change 14/0 (the shared one, on the QXL display).
  • title_rule 2 of 4: kfw never manages the window once it renames itself, because TitleUpdate is an empty arm in process_event.rs: a window an ignore rule matched when it opened stays unmanaged for good. (The first failing check is an artifact of scale 3: the 2 s it waits for the window to stay unmanaged is 6 s, the same as the window's after=6.)
  • fullscreen 14/2: with a window fullscreen (a borderless popup over the display, as a program's own key does it), opening another window makes kfw retile the fullscreen one back into its tile, and when it leaves fullscreen it can lie over the others (it goes back to the rectangle it had before).
  • monitors.run 79 checks, none failed; then monitors.at_cursor plugged a second display and QEMU aborted (SIGABRT in the kernel log, 13:31): the same kind of death as in one of six hotplug repeats on next. The runner now keeps QEMU's stderr, names a dead guest, and runs the scenario once more.

The extended steps, run alone (2026-10-30, next 6d862a11, scale 1.5)

title_rule 5/0 (an ignored window that renames itself stays unmanaged, a managed one stays managed), handover 15/0, monitors.at_cursor 3/0, monocle.focus_behaviour 14/0. Four steps fail, and the output was kept:

  • lifecycle_hidden.crash 12/5: the daemon is killed during a monocle, which has cloaked win1 and win2. The next daemon manages only win3. win1 and win2 are "workspace None, hidden True" for good: cloaked, unmanaged, invisible, at their old positions; nothing brings them back. A clean stop uncloaks them, a kill does not, and a new daemon does not look for windows that are cloaked.
  • maximizing.user 11/7: a window maximized with its title bar button (SC_MAXIMIZE) fills the work area, but the daemon never has it as its maximized window; nothing in process_event.rs turns a maximize by the user into maximized_window (only toggle-maximize does). Every later check follows from that.
  • hotplug.user_move 11/1: a window moved to the other display with SetWindowPos is not taken to the other monitor by the daemon in 45 s. kfw relocates a window when a drag ends (MoveResizeEnd); a move by anything else raises no such event. The pointer cannot make that drag here: the tablet reaches the first display only.
  • resize.edge_cases 17/1: dragging the top edge of the lower right tile (win3) up by 72 moves nothing, while dragging the bottom edge of the tile above (win2) down by 72 moves the same shared edge by 72. The other seven drags built from the layout move the edge as the pointer did.