qemu: display + touch scenario, ADR-0006, docs

Phase 4+5 of the device sim: - Display + touch verified end-to-end: virtio-gpu at 720x720 (fbdev emulation) renders the real WardenOS dashboard from the static LVGL fbdev+evdev UI build (flare-edge qemu-vm-support tools/build-ui-vm.sh); QMP input-send-event taps the Metrics tab and qemu/tests/ui-shot.sh asserts the repaint from screendumps. Two load-bearing QEMU flags found and documented: -global virtio-mmio.force-legacy=false (gpu/input are VERSION_1-only) and the 200ms press hold (an instantaneous press+release lands inside one LVGL indev poll and never clicks). - qemu/tests/qmp.py: minimal QMP client (screendump, tap, quit). - stage-2 init starts warden-ui when present and fb0 exists. - docs/decisions/0006-qemu-device-sim.md: virt-not-custom-board, the enters-at-kernel boundary, fragment policy, naming, consequences. - docs/architecture.md: new section 7 (device emulation), order-of-work item 7; modbus cross-reference to the bridge. - qemu/README.md: emulated-vs-not table, scenarios, gotchas, host/runner requirements. docs/ci-cd.md: runner needs one-time qemu-system-arm install (fail-closed smoke until then, [maintainer]-gated). Repo README updated. Final sweep on this commit: shellcheck clean, bridge 7/7 tests, boot smoke PASS, portal scenario PASS (check-in + fw pull + signed .wfw download), ui-shot PASS (touch navigates to Metrics) — all under the final flags. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018HUayid7W5w7jBdb9Rrj1K
2026-08-29 20:16:36 -06:00
parent c7e06514ad
commit 13b7d063a2
9 changed files with 347 additions and 29 deletions
@@ -12,12 +12,14 @@ the rest of the firmware: tested, benchmarked, reproducible, and honest about
 what runs on real silicon versus what we simulate.

 > Status: **bringup.** The hardware **simulator** and its tests, the RV1106 kernel
-> forward-port as a reviewable `patches/` series, the hermetic kernel build, and two
-> Tier-1 drivers at 100% MC/DC are all in and CI-green on `main`. What
-> remains before this is on the production build path: installing the self-hosted
-> kernel-build runner (see `docs/ci-cd.md`) and having flare-edge consume warden-sdk
-> as a dependency — both [maintainer]-gated. Until then, flare-edge still builds firmware from
-> the vendored SDK + `sdk-patches/`.
+> forward-port as a reviewable `patches/` series, the hermetic kernel build, two
+> Tier-1 drivers at 100% MC/DC, and the **QEMU device sim** (`qemu/`, ADR-0006:
+> boots the real kernel + real userspace on `-M virt` — check-in/OTA against the
+> mock portal, watchdog, RS485-to-sim bridge, 720x720 display + touch, all
+> emulation-verified) are in. What remains before this is on the production build
+> path: qemu-system-arm on the kernel-build runner (see `docs/ci-cd.md` §5) and
+> having flare-edge consume warden-sdk as a dependency — both [maintainer]-gated. Until
+> then, flare-edge still builds firmware from the vendored SDK + `sdk-patches/`.

 ## Why a new SDK

@@ -90,6 +92,8 @@ than duplicate each other.

 ```
 sim/        the hardware simulator (Rust): membus/devmem, HPMCU, CRU, Modbus, RGA, NPU.
+qemu/       the device simulator (ADR-0006): QEMU -M virt boots the real kernel and
+            real userspace; A/B disk layout, RS485 bridge into sim/, scenario tests.
 drivers/    our own hardened drivers + their seams (relays, freshness; more migrate in).
 patches/    the RV1106 kernel forward-port delta onto pristine linux-6.18.46 (subsystem-split).
 kernel/     forward-port docs + provenance (rv1106-enablement/, PROVENANCE.md).
@@ -71,7 +71,9 @@ supervisor logic runs in CI with no panel.
  (CRC16 byte-identical to the master, FC 0x01–0x06/0x0F/0x10/0x11, exception replies,
  and fault injection — silent-drop and forced-NAK) so `warden-modbus`'s master can be
  hardened to MC/DC against realistic device behaviour with no serial hardware. MEI
-  (0x2B/0x0E) identification is the documented follow-up.
+  (0x2B/0x0E) identification is the documented follow-up. The same slave also serves
+  as the QEMU device sim's field bus: `qemu/rs485-bridge/` feeds it from a serial
+  chardev so the guest's real master polls it over what it believes is /dev/ttyS4 (§7).
 - **`npu` — NPU load model.** Done. `NpuSim` models `/proc/rknpu/load` (the exact
  "NPU load:  N%" text the sysmon reads) behind the path seam, so the load-readout UI
  is host-testable. NPU *compute* is explicitly out of scope — no inference runs here.
@@ -152,7 +154,31 @@ kernel move as one matched boot+oem image, never a partial reflash.
 series honest against pristine 6.18.46; provenance is in `patches/README.md` and
 `kernel/rv1106-enablement/`.

-## 7. Order of work
+## 7. Device emulation (`qemu/`) — see ADR-0006
+
+The third simulator, deliberately not named "sim": a QEMU VM (`-M virt,highmem=off`,
+one Cortex-A7, 256M — the RV1106G3's shape) that boots the real forward-ported
+kernel and real userspace, entering at `-kernel zImage` because everything below
+(BootROM, idblock/DDR-init, U-Boot, the BCB A/B machinery) is closed blobs plus
+mask ROM. The canonical RV1106 zImage boots virt unmodified; an additive kconfig
+fragment (`qemu/configs/virt.fragment` via `WARDEN_KCONFIG_FRAGMENT`) adds the
+scenario devices (PCI serial for RS485, i6300esb watchdog, WireGuard,
+virtio-gpu/input for the 720x720 UI). The virtio disk carries the device's exact
+12-partition `blkdevparts=` A/B layout and the `/dev/block/by-name/` contract.
+
+Where the seams meet: the guest runs the *real* binaries (static musl flared,
+the LVGL fbdev UI); the RS485 bridge (`qemu/rs485-bridge/`) connects a QEMU
+serial chardev to `sim/`'s `ModbusSlave`, so the register-level models serve as
+the VM's field bus — behavior lives in one place, `sim/`, and the VM consumes
+it. Scenario tests: `qemu/tests/boot-smoke.sh` (CI, in kernel-build),
+`portal-scenario.sh` (check-in + OTA offer download against flare-edge's mock
+portal), `ui-shot.sh` (QMP screendump + touch injection). Division of labour
+with the other sims: NPU/RGA/HPMCU *behavior* stays `sim/`; UI *rendering
+development* stays `lvglsim`; the VM is where processes, the kernel, and the
+network meet. §5 still applies — no behavioural sim, this one included, catches
+memory-map faults; and "boots under emulation" is never on-silicon evidence.
+
+## 8. Order of work

 1. **Simulator core** — `membus`, `hpmcu`, the `cru` reset ladder, `modbus`, plus the
   `rga`/`npu` models. **Done.**
@@ -163,3 +189,6 @@ series honest against pristine 6.18.46; provenance is in `patches/README.md` and
 4. **Config-lint CI gates** (§5) — the brick-class of bug. **Done.**
 5. **Hermetic kernel build** (`build/build-kernel.sh` + the `patches-apply` gate). **Done.**
 6. **Kernel 5.10→6.18.46 forward-port** (§6, ADR-0001). **Done** (hardware-verified).
+7. **QEMU device sim** (§7, ADR-0006) — boot smoke, A/B disk harness, RS485 bridge,
+   portal/watchdog/clock scenarios, display+touch. **Done** (emulation-verified;
+   booting the real flare-edge rootfs+oem image pair is a documented later milestone).
@@ -45,6 +45,14 @@ A **third** repo-scoped runner instance on `bfe-mpc-0640` (alongside `flare` and

 Host build deps: `dtc bc flex bison libssl-dev` — already present on 0640.

+5. **`qemu-system-arm`** (for the boot-smoke step inside `kernel-build`, added
+   with the `qemu/` device sim — ADR-0006): one-time
+   `sudo apt-get install qemu-system-arm cpio` on 0640. The step is
+   **fail-closed** — a missing qemu binary fails the job with a message
+   pointing here; it never silently skips. NOT YET PROVISIONED (2026-08-29):
+   the first dispatched `kernel-build` after this lands will fail its smoke
+   step until the install is done ([maintainer]-gated sudo on 0640).
+
 ## Badges

 Static shields SVGs are committed by the `badges` job (private repo can't use
@@ -0,0 +1,58 @@
+# ADR 0006 — QEMU device sim: generic `-M virt`, entered at the kernel
+
+**Status:** Accepted (2026-08-29).
+
+## Context
+The two existing simulators cannot test the *device*: `lvglsim` (flare-edge)
+is an SDL rendering harness, and `sim/` models registers behind driver seams.
+Init ordering, the daemons as real processes, networking/enrollment against
+FLARE, OTA, and the watchdog were testable only on a bench panel — flare-edge's
+fault suite marks five scenarios "HIL, human prompts", its Playwright e2e needs
+a live panel on the LAN, and its OTA desk test stops at "reached APPLYING".
+
+Two ways to emulate the panel were considered:
+
+1. **A custom RV1106 QEMU board model.** Nothing exists upstream or in the
+   community, so this means writing VOP/CRU/GRF/eMMC/HPMCU device models from
+   scratch and maintaining them against QEMU — months of work that duplicates
+   what `sim/` already models in Rust. It still could not run the boot chain:
+   BootROM is mask ROM and the DDR-init/idblock stages are closed rkbin blobs.
+2. **The generic `-M virt` machine, entering at `-kernel zImage`.** The
+   forward-ported 6.18.46 config is multi_v7-derived and already carries
+   `ARCH_VIRT` plus the full virtio set — the canonical RV1106 zImage boots
+   virt **unmodified** (verified 2026-08-29). Peripherals become virtio
+   substitutes; SoC-block behavior stays in `sim/`, bridged in (the RS485
+   chardev bridge) rather than re-modeled.
+
+## Decision
+Option 2. `qemu/` holds the harness: `qemu-system-arm -M virt,highmem=off
+-cpu cortex-a7 -smp 1 -m 256M` (the RV1106G3's shape), one canonical kernel
+image plus an optional additive config fragment (`qemu/configs/virt.fragment`
+via the `WARDEN_KCONFIG_FRAGMENT` hook — PCI/pci-serial/i6300esb/WireGuard/
+virtio-gpu/virtio-input; the RV1106 build is byte-identical with the variable
+unset). The VM carries the device's real 12-partition `blkdevparts=` A/B
+layout on a virtio disk and populates the `/dev/block/by-name/` contract.
+The name is `qemu/`, not any variant of "sim" — the wikis already warn that
+"sim" is two different things.
+
+Notable mechanics: `highmem=off` because the non-LPAE 32-bit kernel cannot
+reach virt's default 40-bit PCIe ECAM; `-global virtio-mmio.force-legacy=false`
+because virtio-gpu/input are VERSION_1-only devices.
+
+## Consequences
+- Everything below the kernel is **out of scope**: BootROM, idblock, U-Boot,
+  the real BCB-driven A/B selection and bootcount auto-revert. The initramfs
+  `warden.slot=` switch emulates U-Boot's *choice*, not the mechanism. The
+  untested A/B rollback chain stays bench territory.
+- Display, input, network, and storage are **substitutes** (virtio), not
+  models. "Boots/works under emulation" is never evidence of "works on
+  silicon"; the VM narrows which claims need a panel.
+- The VM is the first environment that runs production userspace binaries on
+  a non-RV1106 physical memory map, which makes it a canary for baked-in
+  hardware assumptions (it immediately found flare-edge #106, a fatal SIGBUS
+  in flared's HPMCU probe, and #107, a Y2038 time_t truncation in the UI).
+- The guest deliberately deviates from production in documented ways
+  (`WARDEN_FLARE_INSECURE=1` for the desk mock portal, `WARDEN_HPMCU=0`);
+  qemu/README.md carries the emulated-vs-not table.
+- The kernel-build CI job gains a fail-closed qemu boot smoke; hosted runners
+  build (but cannot boot) the initramfs and disk image.
@@ -2,46 +2,100 @@

 A QEMU virtual machine that boots the real forward-ported kernel (`build/` +
 `patches/`) and real userspace, so the *device* — init, daemons, networking,
-OTA, watchdog — can be tested off-hardware. The third simulator in the stack,
-deliberately not named "sim":
+OTA, watchdog, display — can be tested off-hardware. The third simulator in
+the stack, deliberately not named "sim":

 - `lvglsim` (flare-edge) — SDL desktop build of the UI. Rendering only.
 - `sim/` (this repo) — register-level Rust models of RV1106 blocks behind
  driver seams.
- `qemu/` (this) — the whole machine above the kernel entry point.
+- `qemu/` (this) — the whole machine above the kernel entry point, running
+  the real binaries.
+
+Decision record: `docs/decisions/0006-qemu-device-sim.md`.

 ## The boundary (read this before trusting a green run)

 There is no RV1106 machine model in QEMU and everything below the kernel is
 closed rkbin blobs plus mask ROM, so the VM **enters at `-kernel zImage`** on
-`-M virt` (generic ARMv7 machine, virtio peripherals). That means:
+`-M virt,highmem=off` (single Cortex-A7, 256M — the RV1106G3's shape).

- **Not emulated, not tested here:** BootROM, idblock/DDR-init, SPL, U-Boot,
-  the real BCB-driven A/B slot selection, bootcount auto-revert. The untested
-  A/B rollback chain stays untested by this tool.
- **Substituted, not modeled:** display (virtio-gpu, not VOP), input
-  (virtio-tablet, not GT911), network (virtio-net, not GMAC), storage
-  (virtio-blk, not eMMC). NPU/RGA/HPMCU behavior stays `sim/` territory.
- "Boots under emulation" is **not** "works on silicon". On-device claims
-  still need on-device evidence; the VM narrows which claims need a panel.
+| Emulated / substituted | Not emulated (stays bench / `sim/` territory) |
+|---|---|
+| Kernel boot, init ordering, switch_root | BootROM, idblock/DDR-init, SPL, U-Boot |
+| A/B *outcome* (`warden.slot=` cmdline) | Real BCB A/B selection, bootcount auto-revert |
+| Storage: virtio-blk with the device's exact `blkdevparts=` layout + `/dev/block/by-name/` contract | eMMC controller itself |
+| Network: virtio-net (slirp, hostfwd 22/80/28443) | GMAC, AIC8800 wifi, usb0 gadget |
+| Display: virtio-gpu 720x720 via fbdev emulation | VOP/RGB666 pipeline, CH32V003 panel init, RGA blits |
+| Touch: virtio-tablet (QMP `input-send-event`) | GT911 on I2C3 |
+| Watchdog: i6300esb (PCI), `-action watchdog=reset` | DW watchdog @0xff5a0000, HPMCU supervisor |
+| RS485: pci-serial chardev bridged to `sim/`'s `ModbusSlave` | Real UART4 timing/electrical behavior |
+| RTC: PL031 (`--rtc` reproduces the no-RTC 2021-clock incident class) | The unpopulated backup-cell reality |
+
+**"Boots/works under emulation" is never evidence of "works on silicon."**
+The VM narrows which claims need a panel; on-device claims still need
+on-device evidence. Conversely, the VM is the first environment that runs
+production binaries on a non-RV1106 memory map — it found flare-edge #106
+(fatal SIGBUS in flared's HPMCU probe) and #107 (Y2038 time_t truncation)
+on its first two boots of real userspace.
+
+Documented guest deviations from production, set by stage-2 init:
+`WARDEN_FLARE_INSECURE=1` (the desk mock portal is plain HTTP) and
+`WARDEN_HPMCU=0` (no mailbox SRAM on virt; flared >= flare-edge#106 fix
+required, or the daemon dies of SIGBUS).

 ## Quick start

 ```sh
-# 1. build the QEMU kernel variant (canonical RV1106 build + virt fragment)
+# 1. kernel: canonical build boots the VM as-is; the fragment variant adds
+#    the scenario devices (PCI serial, watchdog, WireGuard, virtio-gpu/input)
 WORK=$HOME/kbuild-out CROSS_COMPILE=arm-linux-gnueabihf- \
  WARDEN_KCONFIG_FRAGMENT=qemu/configs/virt.fragment bash build/build-kernel.sh

-# 2. build the initramfs (sha256-pinned static busybox + qemu/rootfs/)
+# 2. initramfs (sha256-pinned static busybox + qemu/rootfs/) and A/B disk
 bash qemu/mkinitramfs.sh
+bash qemu/mkimage.sh                  # options: --portal-url --state K=V --fw-version

-# 3. smoke it
-bash qemu/tests/boot-smoke.sh $HOME/kbuild-out/linux-6.18.46/arch/arm/boot/zImage
+# 3. run (see run.sh header for all flags)
+bash qemu/run.sh --kernel $HOME/kbuild-out/linux-6.18.46/arch/arm/boot/zImage --shell
 ```

-Host requirements: `qemu-system-arm` (Debian 13 ships QEMU 10), `curl`, `cpio`,
-`gcc-arm-linux-gnueabihf` for the kernel build.
+Payload: drop static musl armv7 binaries into `qemu/payload/` (see its
+README) — `warden-flared`, `warden-modbus`, and `warden-ui` (the LVGL
+fbdev+evdev build from flare-edge `tools/build-ui-vm.sh`) are started by
+stage-2 init when present.

-Status: bringup — boot smoke only. Disk/network harness, RS485 bridge to
-`sim/`, portal scenarios, and display/touch land in later phases (see
-`docs/decisions/0006-qemu-device-sim.md` once written).
+## Scenario tests (`qemu/tests/`)
+
+- `boot-smoke.sh <zImage>` — sentinel-asserting boot; runs in CI inside the
+  kernel-build job.
+- `portal-scenario.sh <zImage>` (needs `FLARE_EDGE=<checkout>`) — the real
+  flared in the VM against the desk mock portal: authenticated check-in,
+  firmware desired-state pull, and download of a real signed tier-1 `.wfw`
+  offer. Verify/stage/APPLYING run as a dry run (no `WARDEN_FW_ALLOW_APPLY`);
+  flipping it on inside the VM is the documented stretch — apply writes
+  `/dev/block/by-name/rootfs_b` inside disk.img, then `--slot _b` boots it.
+- `ui-shot.sh <zImage>` — display+touch: boots headless with virtio-gpu,
+  QMP-screendumps the 720x720 UI, taps the Metrics tab via `input-send-event`
+  (a 200 ms hold — an instantaneous press+release lands inside one LVGL poll
+  and never clicks), and asserts the frame changed. `qmp.py` is the tiny QMP
+  client.
+- Watchdog: `run.sh --watchdog`, arm `/dev/watchdog` in the guest, don't pet —
+  the VM resets ~30 s later (verified). Do NOT combine with a flared payload
+  expecting survival: flared pets only while the UI heartbeat is fresh.
+
+## Gotchas that cost time (so they cost it once)
+
+- AF_UNIX socket paths cap at ~108 chars — keep `--rs485`/`--qmp` paths short.
+- A serial port that is closed discards incoming bytes: hold ONE fd open
+  across write and read when scripting the guest side of the RS485 bridge.
+- `highmem=off` and `-global virtio-mmio.force-legacy=false` are load-bearing
+  (32-bit ECAM reach; virtio-1-only gpu/input) — both live in run.sh.
+- Never pass `earlyprintk`: DEBUG_UART_PHYS is the RV1106's 0xff4c0000.
+
+## Host requirements
+
+`qemu-system-arm` (Debian 13 ships QEMU 10), `curl`, `cpio`, `mkfs.ext4`,
+`gcc-arm-linux-gnueabihf` (kernel build), `python3` (+`cryptography` for the
+portal scenario's `.wfw` signing). CI: the hosted `qemu-tools` job builds the
+tooling; the boot smoke runs on the self-hosted kernel-build runner, which
+needs a one-time `apt-get install qemu-system-arm` (see docs/ci-cd.md).
@@ -77,6 +77,14 @@ for d in /usr/bin/warden-flared /usr/bin/warden-modbus; do
    fi
 done

+# The UI (LVGL fbdev+evdev build from flare-edge tools/build-ui-vm.sh) needs
+# virtio-gpu's fbdev: present only with run.sh --display on|headless AND the
+# virt.fragment kernel.
+if [ -x /usr/bin/warden-ui ] && [ -c /dev/fb0 ]; then
+    echo "init: starting warden-ui (fbdev)"
+    /usr/bin/warden-ui > /tmp/warden-ui.log 2>&1 &
+fi
+
 if grep -qw warden.shell /proc/cmdline; then
    echo "warden.shell: interactive shell (exit powers off)"
    setsid cttyhack sh
@@ -78,6 +78,9 @@ fi
 APPEND="console=ttyAMA0 rdinit=/init"
 ARGS=(
  -M "virt,highmem=off" -cpu cortex-a7 -smp 1 -m 256M
+  # virtio-mmio defaults to the legacy (0.9) transport; virtio-gpu and
+  # virtio-input are VERSION_1-only devices and never bind without this.
+  -global "virtio-mmio.force-legacy=false"
  -kernel "$KERNEL" -initrd "$INITRD"
  -netdev "user,id=n0,hostfwd=tcp:127.0.0.1:${SSH_PORT}-:22,hostfwd=tcp:127.0.0.1:${HTTP_PORT}-:80,hostfwd=tcp:127.0.0.1:${API_PORT}-:28443"
  -device "virtio-net-device,netdev=n0"
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Tiny QMP client for the qemu/ device-sim tests.
+
+    qmp.py <socket> screendump <out.ppm>
+    qmp.py <socket> tap <x> <y>      # absolute 0..32767 (virtio-tablet)
+    qmp.py <socket> quit
+"""
+import json
+import socket
+import sys
+import time
+
+
+def rpc(sock, obj):
+    sock.sendall((json.dumps(obj) + "\n").encode())
+    while True:
+        line = sock_file.readline()
+        if not line:
+            raise RuntimeError("QMP connection closed")
+        msg = json.loads(line)
+        if "return" in msg:
+            return msg["return"]
+        if "error" in msg:
+            raise RuntimeError(f"QMP error: {msg['error']}")
+        # asynchronous events are interleaved; skip them
+
+
+def main():
+    if len(sys.argv) < 3:
+        sys.exit(__doc__)
+    path, cmd = sys.argv[1], sys.argv[2]
+    global sock_file
+    s = socket.socket(socket.AF_UNIX)
+    s.connect(path)
+    sock_file = s.makefile("r")
+    sock_file.readline()  # greeting banner
+    rpc(s, {"execute": "qmp_capabilities"})
+
+    if cmd == "screendump":
+        rpc(s, {"execute": "screendump", "arguments": {"filename": sys.argv[3]}})
+    elif cmd == "tap":
+        x, y = int(sys.argv[3]), int(sys.argv[4])
+        press = [
+            {"type": "abs", "data": {"axis": "x", "value": x}},
+            {"type": "abs", "data": {"axis": "y", "value": y}},
+            {"type": "btn", "data": {"down": True, "button": "left"}},
+        ]
+        release = [{"type": "btn", "data": {"down": False, "button": "left"}}]
+        rpc(s, {"execute": "input-send-event", "arguments": {"events": press}})
+        # Hold the press across several LVGL indev poll periods (33 ms each):
+        # an instantaneous press+release lands inside one poll and no click
+        # is ever registered.
+        time.sleep(0.2)
+        rpc(s, {"execute": "input-send-event", "arguments": {"events": release}})
+    elif cmd == "quit":
+        s.sendall(b'{"execute":"quit"}\n')
+    else:
+        sys.exit(f"unknown command {cmd}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Display + touch scenario: boot the VM headless with virtio-gpu, wait for the
+# LVGL UI (fbdev build) to start, screendump over QMP, inject an absolute
+# touch tap (virtio-tablet), screendump again. Asserts the first frame is
+# non-blank; reports (does not assert) whether the tap changed pixels — the
+# device-level analogue of flare-edge's Xvfb/xdotool sim-test.sh.
+#
+# FAILS CLOSED on missing prerequisites.
+#
+# Usage: ui-shot.sh <zImage-virt> [out-dir]
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"     # qemu/tests/
+QDIR="$(cd "$HERE/.." && pwd)"                           # qemu/
+
+ZIMAGE="${1:-}"
+OUTDIR="${2:-$QDIR/out}"
+if [ -z "$ZIMAGE" ] || [ ! -f "$ZIMAGE" ]; then
+  echo "FATAL: usage: $0 <zImage> [out-dir] — the virt.fragment kernel variant" >&2
+  exit 1
+fi
+[ -x "$QDIR/payload/warden-ui" ] || {
+  echo "FATAL: no qemu/payload/warden-ui — build it with flare-edge tools/build-ui-vm.sh" >&2
+  exit 1
+}
+command -v qemu-system-arm >/dev/null || {
+  echo "FATAL: qemu-system-arm not on PATH — see qemu/README.md" >&2
+  exit 1
+}
+
+# Short-named scratch: AF_UNIX socket paths are capped at ~108 chars.
+WORK="$(mktemp -d /tmp/wqu.XXXXXX)"
+QEMU_PID=""
+cleanup() {
+  if [ -n "$QEMU_PID" ]; then kill "$QEMU_PID" 2>/dev/null || true; fi
+  rm -rf "$WORK"
+}
+trap cleanup EXIT
+
+bash "$QDIR/mkinitramfs.sh"
+bash "$QDIR/mkimage.sh"
+
+PORT=$((21000 + RANDOM % 20000))
+bash "$QDIR/run.sh" --kernel "$ZIMAGE" --display headless --qmp "$WORK/qmp.sock" \
+  --ssh-port "$PORT" --http-port $((PORT + 1)) --api-port $((PORT + 2)) \
+  > "$WORK/console.log" 2>&1 &
+QEMU_PID=$!
+
+deadline=$((SECONDS + 120))
+while [ $SECONDS -lt $deadline ]; do
+  grep -aq 'init: starting warden-ui' "$WORK/console.log" && break
+  kill -0 "$QEMU_PID" 2>/dev/null || { echo "FATAL: VM exited early" >&2; tail -25 "$WORK/console.log" >&2; exit 1; }
+  sleep 2
+done
+grep -aq 'init: starting warden-ui' "$WORK/console.log" || {
+  echo "FATAL: warden-ui never started (no fb0? wrong kernel?)" >&2
+  tail -25 "$WORK/console.log" >&2
+  exit 1
+}
+sleep 8   # let LVGL render the first frames
+
+qmp() { python3 "$HERE/qmp.py" "$WORK/qmp.sock" "$@"; }
+
+qmp screendump "$WORK/shot1.ppm"
+# Tap the "Metrics" tab: pixel (373,40) of 720x720 scaled to the QMP absolute
+# range 0..32767 — switching tabs must repaint the content area.
+qmp tap 16975 1820
+sleep 3
+qmp screendump "$WORK/shot2.ppm"
+
+mkdir -p "$OUTDIR"
+cp "$WORK/shot1.ppm" "$OUTDIR/ui-shot1.ppm"
+cp "$WORK/shot2.ppm" "$OUTDIR/ui-shot2.ppm"
+
+# Non-blank: more than one distinct pixel value in the raw PPM payload.
+python3 - "$WORK/shot1.ppm" <<'EOF'
+import sys
+data = open(sys.argv[1], "rb").read()
+# P6 header: magic, dims, maxval, then raw RGB
+parts = data.split(b"\n", 3)
+pixels = parts[3] if len(parts) == 4 else b""
+distinct = len(set(pixels[i:i+3] for i in range(0, min(len(pixels), 3*720*720), 3)))
+print(f"shot1: {len(pixels)} bytes of pixels, {distinct} distinct colors")
+sys.exit(0 if distinct > 1 else 1)
+EOF
+
+if cmp -s "$WORK/shot1.ppm" "$WORK/shot2.ppm"; then
+  echo "FATAL: tapping the Metrics tab did not change the frame — touch is not reaching the UI" >&2
+  exit 1
+fi
+echo "tap on the Metrics tab repainted the frame (touch reached the UI)"
+echo "UI-SHOT-PASS (screenshots in $OUTDIR/ui-shot{1,2}.ppm)"