---
name: progress-report
description: Use whenever a long VM job runs for the user (vminstall.sh, vmbootloadertest.sh, vmsuite.sh, vmtest.sh, an ISO build), locally or on the WSL PC, and the user wants to follow it - how to report progress (a table with a bar per VM and a total, only when something changes), show the log in the user's terminal and the VM's screen on their desktop, and look into a job that seems stuck.
---

# Progress report for VM jobs

What the user asked for (2026-09-29): see what is going on, without noise.

## The rules

- **Report only on a change**: an install stage, a test step, a job finishing, a FAIL. Never a
  timed "no change" message. One monitor, not polling from the conversation.
- **Every report is the same table**, one row per VM/job plus a total row:

  | VM | Step | Checks | Progress |
  |---|---|---|---|
  | grub | ✅ done | 40 / 40, 0 failed | `████████████████████` 100% |
  | systemd-boot | test: kernel update | 27 / 40, 0 failed | `█████████████░░░░░░░` 68% |
  | limine | install: desktop environment (40%) | 0 / 41 | `░░░░░░░░░░░░░░░░░░░░` 0% |
  | **Total** | | **67 / 121**, 0 failed | `███████████░░░░░░░░░` 55% |

  Bar: 20 cells, `█` per 5% of checks passed out of the expected count. Step in plain words
  ("install: base system (9%)", "test: reboot into the other kernel"), ✅ when done, ❌ with the
  failed check's name when something fails. Under the table at most two lines: what is odd or next.
- **A FAIL or a job that stops moving is reported at once**, with the cause looked up first (below),
  not only the numbers.

## The monitor

`scripts/vmprogress.sh [job...]` (jobs: limine systemd-boot grub cli menu hw installer toggles)
prints one line only when something changes and `ALLDONE` at the end; it reads the latest run in
`~/vms/bl-<loader>.test.log` / `~/vms/run-<suite>.log` and the install percentage from
`$VM_DIR/install-www/install.log`. Expected check counts live at its top: update them when a
suite gains checks. `--once` prints the current state.

On the WSL PC, from the laptop:

```
Monitor(command: "ssh wsl '~/projects/steamify-cachyos-dev/scripts/vmprogress.sh grub systemd-boot limine'",
        description: "boot loader tests: only on change", timeout_ms: 1800000)
```

Re-arm it when it expires while jobs still run. Turn each event into the table above.

## What the user sees on the PC

- **Their terminal**: stream the running job's log into it (the `showlog` unit, `wsl-build-host`
  skill); switch it when the job changes (install log, then the test log, then `~/vms/test.log`).
- **The VM's screen**: automated runs are headless. To show one: `scripts/vmview.py ~/vms/<vm>` in
  a unit with the WSLg env (a window refreshed every 2 s, view only). When the user wants to watch
  or step in, restart the job with a real window (`--window`, WSLg env) instead.
- One screenshot for yourself (`scripts/qmpshot.py <qmp.sock> out.png`, copied back and Read) only
  to diagnose a stuck boot, not as a test.

## A job that seems stuck

1. `--once` and the log's last `#####` step: how long has it been there, compared with the others?
2. Is the VM up: `pgrep -af '[q]emu'` (its `hostfwd` port), ssh to it with the test's own options
   (`. scripts/common.sh` with its `VM_DIR`/`VM_PORT`): a known_hosts mismatch or "Permission
   denied" is a test setup problem, not the guest.
3. No ssh banner: take one screenshot. Firmware PXE/HTTP boot means no usable boot entry: read the
   UEFI variables from a copy of `vars.fd` (`virt-fw-vars -i <copy> --print`, package
   virt-firmware) and compare with a loader that works.