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.
This commit is contained in:
LGUG2Z committed 2026-10-30 18:59:32 -07:00
1 parent 0aec364345
commit ff3711dcb5
4 files changed
+673

No files matched your search

+141
View File
@@ -0,0 +1,141 @@
# The Windows guest for the neutral e2e scenarios
The scenarios in `e2e/lib/komorebi_vm/core` (vendored from the KDE port with
`scripts/sync-e2e-core` there) run against a throwaway Windows 11 guest under
QEMU. Findings and measurements are in `W0.md` and `W1.md`.
## Needs
- Linux with KVM (nested is enough: WSL2 with `nestedVirtualization=true`).
- The Windows 11 Enterprise Evaluation ISO (`go.microsoft.com/fwlink/?linkid=2289031`).
- Nix. `nix run .#e2e-windows` brings QEMU, swtpm, an OVMF with TPM support
and the binaries under test.
## Build the golden image, in two layers
Windows Setup is about 97% of building an image (measured: 18 minutes of a
18.2 minute build), so the image is two layers, a qcow2 chain.
The **base** is the unattended install, up to a desktop with auto-login, the
Visual C++ runtime and the guest agent. Build it once, and again for a new ISO,
when the agent needs more in the image, or when the 90-day evaluation runs
out (about 20 minutes, more under load):
```sh
nix build .#komorebi-e2e-agent -o agent
build-base.sh win11.iso agent/bin/komorebi-e2e-agent.exe base
```
The **golden** layer goes on top of it in about 2.5 minutes, most of it the
boot: policies, Defender, the display driver and the like, provisioned
through the agent (`provision.ps1`), so a change to those costs minutes, not
a reinstall. Run it from `e2e/` with the nix app's environment (`PYTHONPATH=lib:.`,
`OVMF_FD`, qemu and swtpm on PATH):
```sh
build-golden.sh base golden QXLDOD_DIR
```
The build script needs `python` on PATH as well (`nix shell nixpkgs#python3`).
Measured from these scripts: 127 s on a loaded host.
`QXLDOD_DIR` is virtio-win's `qxldod/w10/amd64` (Red Hat's signed QXL display
driver). Without it the guest has one display and `hotplug` and the
two-display `commands` sweep cannot run. `golden/disk.qcow2` is backed by
`../base/disk.qcow2` through a relative path: move the two together, or
`qemu-img rebase -u` the golden one. Both builds need the guest to have
internet (the Visual C++ runtime is downloaded in it).
## Run scenarios
```sh
E2E_GOLDEN=golden nix run .#e2e-windows -- OUT SCENARIO...
```
Shared scenarios (from `e2e/lib`, vendored from kfde; their checks print as
`[shared]`):
- tiling and focus: `tiling`, `focus`, `moving`, `stacks`, `workspaces`,
`monocle`, `closing`, `layouts`, `floating`, `minimizing`, `maximizing`,
`workspace_moves`, `promoting`, `flipping`, `pausing`, `tiling_off`,
`scrolling`, `padding`
- resizing: `resize` (a pointer drag), `resize_commands`
- rules and config: `rules`, `rules_class`, `rules_exe`, `manage_rules`,
`state_fidelity`, `placement`, `startup_rules`, `config_reload`
- lifecycle: `lifecycle`, `lifecycle_hidden`, `locking`
- displays: `hotplug`, `commands` (also the sweep of every command; with
`SWEEP_TWO_DISPLAYS=1` it adds a second display), `unknown_monitor`
- `focus_follows_mouse` (needs the pointer, on the first display only)
What only Windows checks, run after the tiling windows with `[windows]`
labels, from `extras/`: `windows_padding` (the border's 7 px),
`windows_cloaking`, `windows_config_file`, `windows_tracking`,
`windows_second_display` and `windows_display_change` (the mode of the QXL
display changes while windows are on it).
Every scenario gets its own guest on a fresh overlay of the golden
image; each needs about 4 vCPU and 6 GB. `OUT/<scenario>/result.json` names the
scenario, the commit under test (`KOMOREBI_E2E_COMMIT`), every check (with its
scope), and the seconds each phase took.
| Variable | Effect |
|---|---|
| `KOMOREBI_E2E_STATE=DIR` | restore every guest from a state saved in DIR (made on the first run, and again when the golden image, QEMU or `guest.py` changed): about 3 s instead of 50 to 90 s; the state is about 2.7 GB and the guest then has an AHCI disk |
| `KOMOREBI_E2E_SCALE=1.5` | every wait of a scenario is that many times as long, for a busy host |
| `KOMOREBI_E2E_BINS=DIR` | (the nix app) test the binaries in DIR, made by `build-ref.sh REF DIR`, instead of this checkout's |
| `KOMOREBI_E2E_KEEP_GUEST=1` | keep each guest's run directory (overlay, TPM state), which is deleted at exit by default |
| `SWEEP_TWO_DISPLAYS=1` | `commands` adds a second display first |
| `KOMOREBI_E2E_LOG_LEVEL` | the daemon's log level (`debug`, `trace`) |
| `KOMOREBI_E2E_RECORDER=DIR` | record the run with komorebi-recorder (folder with `komorebi-recorder.exe`); the session comes back as `recording.zip` |
| `KOMOREBI_E2E_CAPTURE=DIR` | save raw `komorebic state` fixtures |
| `E2E_ONLY=word,word` | run only the steps of a scenario whose printed name (`module.function`) contains one of the words, for a rerun of one step: `E2E_ONLY=at_cursor` with `monitors`; a step the runner needs to open the windows always runs (`KFDE_ONLY` is the older name) |
| `RESIZE_DX` | the drag of `resize`, in pixels |
Keep the output and run directories on a short path: the guest's sockets are
in them and a unix socket path is limited to about 108 bytes.
## Testing another commit or branch
```sh
build-ref.sh origin/next bins # komorebi, komorebic and testwin of that ref
KOMOREBI_E2E_BINS=bins E2E_GOLDEN=golden nix run .#e2e-windows -- OUT SCENARIO...
```
`bins/commit` has the full hash, which the runner puts in every `result.json`.
A known-failure marker of the runner applies only when that commit does not
contain the fix of the bug it is for (`git merge-base --is-ancestor`, in
`run.py`): `unknown_monitor` (fixed by `837ca257`) and the integer case of
`placement` (`3b424dd7`) are known failures on `0ffc502c` and plain passes on
komorebi's `next` (there, a marker that still applied would fail the suite, to
say it can go).
## Known failures and limits
- On a commit without the fix, `unknown_monitor` (kfw drops the focused window
when the target monitor does not exist) and the integer case of `placement`
(the daemon exits at start) are known failures: the suite prints
`known failures: N`, and fails once the bug is fixed and the marker holds.
- One step is a known difference of kfw, kept for now (`KNOWN_STEPS` in
`run.py`; its failing checks print as `known failure` and a step that stops
failing says the marker can go): `hotplug.user_move` (kfw relocates a window
to another monitor only when a drag ends, `MoveResizeEnd`).
`maximizing.user` is a known failure only on a build without `3fa3d429`
(kfw did not track a user's maximize); master passes it.
- `hotplug` failed about two runs in three on `0ffc502c` (an unplugged
monitor stayed in the list); `next` has the fix (`5c8e4770`).
- By design, not bugs: a minimized window is not taken up when the daemon
starts, and a rule's exe id has the extension (`exe_id` spells it).
- Under heavy host load the daemon can answer `komorebic state` slowly enough
to time out; a run that overlaps other VM suites is suspect.
- The QMP tablet reaches the first display only, so `platform.pointer`
cannot act on a second one.
- Only the second (QXL) display lists modes, so only it can change mode; the
first is the basic display adapter, with one. A change of the Windows scale
(DPI) needs a sign-out and is not tried.
## Pieces
`guest.py` (QEMU, swtpm, the overlay), `qmp.py` (keys, pointer, screenshots),
`agent.py` and `../../guest/agent` (windows, processes and files in the guest
over TCP), `windows_platform.py` (the shared `Platform` protocol), `run.py`
(the runner), `extras/` (what only Windows checks), `display.ps1` (changes the
mode of a display), `w1_*.py` (probes, each prints what it saw).
+414
View File
@@ -0,0 +1,414 @@
# 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):
```text
-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.
@@ -0,0 +1,67 @@
"""W1: which command undoes a maximize that the user made?
usage: python -m platforms.qemu_windows.w1_maximize_cmds GOLDEN BIN_DIR OUT STATE
Tiles three windows, has the user maximize the second, and for each command
the maximizing scenario says the daemon ignores in that state: sends it,
waits, and prints what the daemon has (the maximized window, how many
containers, what floats, the monocle) and whether the window still fills the
work area; if the command undid the maximize, the user maximizes again. A
probe: it prints what it saw.
"""
import importlib
import sys
from pathlib import Path
from komorebi_vm.core.checks import Checks
from .guest import Guest
from .run import BINARIES
from .windows_platform import WindowsPlatform
def main(argv: list[str]) -> int:
golden, bin_dir, out, state = (Path(a) for a in argv[:4])
out.mkdir(parents=True, exist_ok=True)
tiling = importlib.import_module("komorebi_vm.core.scenarios.tiling")
maximizing = importlib.import_module("komorebi_vm.core.scenarios.maximizing")
with Guest(golden, out / "guest", state=state) as guest:
guest.upload(bin_dir, BINARIES)
platform = WindowsPlatform(guest.qmp, guest.agent, out, scale=1.5)
platform.start_komorebi()
clients = tiling.run(platform, Checks())
target = clients[1]
area = platform.work_area()
def describe() -> str:
workspace = platform.state().workspace()
window = platform.os_window(target)
fills = window is not None and window.frame.w >= area.w - 4
return (f"maximized {workspace.maximized.title if workspace.maximized else None}, "
f"containers {len(workspace.containers)}, floating "
f"{len(workspace.floating)}, monocle "
f"{workspace.monocle is not None}, fills {fills}")
platform.user_maximize(target)
platform.wait_for(lambda: platform.state().workspace().maximized is not None, 10)
print(f"PASTE after the user maximized: {describe()}")
for command in maximizing.IGNORED:
status, text = platform.komorebic_status(*command.split())
platform.wait_for(lambda: False, 2)
print(f"PASTE {command!r} (exit {status}): {describe()}")
if platform.state().workspace().maximized is None:
# put it back, to look at the next command alone
platform.komorebic("focus-workspace", "0")
try:
platform.user_maximize(target, on=False)
except RuntimeError:
pass
platform.user_maximize(target)
platform.wait_for(
lambda: platform.state().workspace().maximized is not None, 10)
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,51 @@
"""W1: what is the ring of a window when the wallpaper scenario says it is not warm?
usage: python -m platforms.qemu_windows.w1_wallpaper_ring GOLDEN BIN_DIR OUT STATE
Runs `wallpaper.run` with `ring_hue` wrapped to print, for every call, the
frame, the hue and the colors of the pixels it looked at, and keeps the screen
of each call. A probe: it prints what it saw.
"""
import importlib
import sys
from pathlib import Path
from komorebi_vm.core import pixels
from .guest import Guest
from .run import BINARIES, RecordedChecks
from .windows_platform import WindowsPlatform
def main(argv: list[str]) -> int:
golden, bin_dir, out, state = (Path(a) for a in argv[:4])
out.mkdir(parents=True, exist_ok=True)
wallpaper = importlib.import_module("komorebi_vm.core.scenarios.wallpaper")
original = wallpaper.ring_hue
calls = []
def ring_hue(frame, image, reach=12):
hue = original(frame, image, reach)
y = frame.y + frame.h // 2
row = [pixels.pixel(image, x, y) for x in range(
max(0, frame.x - reach), min(image.size[0], frame.x + reach), 2)]
calls.append((frame, hue))
image.save(out / f"ring-{len(calls)}.png")
print(f"PASTE ring call {len(calls)}: frame {frame} hue {hue}")
print(f"PASTE pixels at y={y} from x={frame.x - reach}: {row}")
return hue
wallpaper.ring_hue = ring_hue
with Guest(golden, out / "guest", state=state) as guest:
guest.upload(bin_dir, BINARIES)
platform = WindowsPlatform(guest.qmp, guest.agent, out, scale=1.5)
platform.start_komorebi()
checks = RecordedChecks()
wallpaper.run(platform, checks)
print(f"PASTE passed {checks.passed} failed {checks.failed}")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))