The QEMU path now distinguishes between two related but different concepts:
bridge_status— coarse provider-bridge lifecycle used for high-level API honestyreadiness_state— stricter readiness ladder used to explain why a session is or is not actionable yet
| Field | Values | Meaning |
|---|---|---|
bridge_status |
viewer_only, bridge_waiting, runtime_ready, failed |
High-level provider bridge state |
readiness_state |
booting, desktop_ready, bridge_listening, bridge_attached, runtime_ready, failed |
Detailed readiness progression |
- Ubuntu 24.04 + GNOME
- full desktop dogfood path
- intended for the Taskers proof
- lighter internal fixture
- same guest-runtime protocol and readiness semantics
- intended for package/file regression checks such as
jq --version
The host prepares or reuses qcow2 assets and then boots them under qemux/qemu.
Practical pieces:
- product/regression image preparation:
scripts/qemu_guest_assets.py - guest disk booted through
BOOT=/boot.qcow2 - optional seed ISO attached via
ARGUMENTS=-drive file=/seed.iso,format=raw,media=cdrom,readonly=on - optional shared host content exposed through
/shared/hostshare
The canonical live_desktop_view contract is for:
- operator visibility
- session/task/action context
- pause/resume/stop
Provider truthfulness matters:
qemuproductexposes a canonical live stream through the control planeqemuregressionkeeps the VM viewer as debug-only because the action plane runs in guest-sidexvfbxvfbis screenshot fallback only in this phase
The live view is not the primary control plane for claiming product success.
A QEMU session should not be treated as actionable until:
- the guest runtime answers
/health - the host can attach a remote runtime session inside the guest
- the resulting runtime exposes actions