pixie-lab 0.3.1__tar.gz → 0.3.2__tar.gz

{pixie_lab-0.3.1 → pixie_lab-0.3.2}/.github/workflows/cicd.yaml

@@ -10,6 +10,11 @@ name: cicd
 #   * ``build-media``: build the live-env media (netboot-pc + usbboot-pc
 #     variants) via the cijoe pipelines under cijoe/tasks/. Requires
 #     live-build + passwordless sudo; the runner has both.
+#   * ``verify-usbboot``: structurally verify the usbboot-pc .iso
+#     (hybrid ISO + El Torito BIOS & UEFI entries + sha256), then boot
+#     it via a real Ventoy stick in QEMU and assert the pixie live env
+#     comes up. Gates the publish jobs so a broken / non-Ventoy .iso
+#     never ships.
 #   * ``build-wheel``: sdist + wheel for PyPI. Runs on every push +
 #     PR so the packaging story is exercised regardless of tag state.
 #   * ``publish-pypi``: trusted publishing of the wheel + sdist,
@@ -556,6 +561,66 @@ jobs:
           path: cijoe/_build/test-pxe
           if-no-files-found: warn
 
+  verify-usbboot:
+    name: Verify usbboot .iso (structural + Ventoy boot in QEMU)
+    # Downloads the usbboot-pc bake, structurally verifies the hybrid
+    # ISO (ISO 9660 + isohybrid MBR + El Torito BIOS & UEFI entries +
+    # sha256), then boots it via a real Ventoy stick in QEMU and asserts
+    # the pixie live env comes up: pixie-usb-grow skips (no PIXIE_IMGS
+    # under a loop-mounted ISO), pixie-images-discover bind-mounts the
+    # operator drop, pixie-on-tty1 renders the CLI wizard. Gates the
+    # release -- a broken / non-bootable / non-Ventoy-compatible ISO
+    # must not ship.
+    needs: build-media
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install host tools (qemu, ovmf, exfat, xorriso)
+        run: |
+          set -eu
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            qemu-system-x86 \
+            qemu-utils \
+            ovmf \
+            exfat-fuse \
+            exfatprogs \
+            xorriso \
+            file
+          sudo chmod a+rw /dev/kvm
+          ls -la /dev/kvm
+
+      - name: Install cijoe
+        run: pipx install --force cijoe
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Download usbboot-pc artifact
+        uses: actions/download-artifact@v7
+        with:
+          name: pixie-usbboot-pc-x86_64
+          path: ~/system_imaging/disk/
+
+      - name: Show downloaded artifact contents
+        run: |
+          set -eu
+          echo "--- ~/system_imaging/disk (recursive) ---"
+          find ~/system_imaging/disk -maxdepth 5 -print
+
+      - name: Verify + Ventoy-boot the usbboot .iso
+        run: make test-usb-ventoy
+
+      - name: Upload cijoe output
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: cijoe-output-test-usb-ventoy
+          path: cijoe/cijoe-output
+          if-no-files-found: warn
+
   build-wheel:
     name: Build wheel + sdist
     needs: test
@@ -591,6 +656,7 @@ jobs:
       - test-pxe-tui
       - test-pxe-flash
       - test-pxe-flash-always
+      - verify-usbboot
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/v')
     environment:
@@ -632,6 +698,7 @@ jobs:
       - test-pxe-tui
       - test-pxe-flash
       - test-pxe-flash-always
+      - verify-usbboot
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/v')
     permissions:
@@ -676,6 +743,7 @@ jobs:
       - test-pxe-tui
       - test-pxe-flash
       - test-pxe-flash-always
+      - verify-usbboot
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/v')
     permissions:

{pixie_lab-0.3.1 → pixie_lab-0.3.2}/CHANGELOG.md

@@ -11,6 +11,22 @@ operator-facing summary.
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-07-24
+
+### Added
+
+**CI verifies the usbboot `.iso` boots via Ventoy.** A new
+`verify-usbboot` job structurally checks the bake (valid ISO 9660 +
+isohybrid MBR + El Torito BIOS *and* UEFI boot entries + sha256), then
+installs Ventoy onto a QEMU disk, drops the `.iso` + a sentinel image
+catalog onto it, and boots it -- asserting the pixie live env comes up
+correctly on the Ventoy loop-boot path (`pixie-usb-grow` skips with no
+`PIXIE_IMGS` partition, `pixie-images-discover` bind-mounts the
+operator drop at `/var/lib/pixie/images`, and `pixie-on-tty1` renders
+the CLI wizard). The job gates the publish jobs, so a broken,
+non-bootable, or non-Ventoy-compatible ISO can never ship. Ported from
+bty's `test-usb-ventoy`.
+
 ## [0.3.1] - 2026-07-24
 
 ### Fixed

{pixie_lab-0.3.1 → pixie_lab-0.3.2}/Makefile

@@ -23,7 +23,7 @@ endif
 
 .PHONY: help \
         deps test lint format format-check typecheck ci wheel \
-        media-deps build ipxe test-pxe \
+        media-deps build ipxe test-pxe test-usb-ventoy \
         clean
 
 help:
@@ -56,6 +56,8 @@ help:
 	@echo "                  (same deps as test-pxe-flash; asserts no /done flip)"
 	@echo "  test-pxe-tui  end-to-end PXE pixie-tui chain test"
 	@echo "                  (same deps as test-pxe-flash; asserts wizard entry)"
+	@echo "  test-usb-ventoy  structural + Ventoy-boot verify of the usbboot .iso"
+	@echo "                  (needs a prior VARIANT=usbboot-pc bake + qemu/KVM/OVMF + ventoy deps)"
 	@echo ""
 	@echo "Variant: $(VARIANT)  (override with VARIANT=netboot-pc, ...)"
 	@echo "  usbboot-pc    - bootable USB live ISO via live-build (.iso, x86_64)"
@@ -166,6 +168,13 @@ test-pxe-flash-always:
 test-pxe-tui:
 	cd cijoe && cijoe tasks/test-pxe-tui.yaml --monitor -c configs/test-pxe-tui.toml
 
+# Structural + Ventoy-boot verification of the usbboot .iso. Needs a
+# prior VARIANT=usbboot-pc bake staged under ~/system_imaging/disk/ (or
+# a downloaded pixie-usbboot-pc-x86_64 CI artifact) + qemu/KVM/OVMF +
+# ventoy tooling deps (losetup, exfat-fuse, passwordless sudo).
+test-usb-ventoy:
+	cd cijoe && cijoe tasks/test-usb-ventoy.yaml --monitor -c configs/test-usb-ventoy.toml
+
 # ---------- Cleanup ------------------------------------------------------
 
 clean:

{pixie_lab-0.3.1 → pixie_lab-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixie-lab
-Version: 0.3.1
+Version: 0.3.2
 Summary: Bare-metal netboot appliance: catalog + fetch + NBD + PXE + TFTP + operator TUI in one container
 Project-URL: Homepage, https://github.com/safl/pixie
 Project-URL: Repository, https://github.com/safl/pixie

pixie_lab-0.3.2/cijoe/configs/test-usb-ventoy.toml

@@ -0,0 +1,48 @@
+# pixie USB Ventoy-boot test - cijoe config
+#
+# Verifies an operator's realistic Ventoy workflow:
+#   1. Install Ventoy onto a USB stick.
+#   2. Drop pixie-usbboot-pc-x86_64-v*.iso + image files + a catalog.toml
+#      onto the Ventoy data partition (under pixie-images/).
+#   3. Boot the stick; Ventoy menu auto-selects the only ISO + chains
+#      into the pixie live env.
+#   4. ``pixie-usb-grow.service`` skips correctly (no PIXIE_IMGS
+#      partition on the booted device -- the .iso is loop-mounted, not
+#      dd'd).
+#   5. ``pixie-images-discover.service`` finds the operator's drop on the
+#      Ventoy data partition and bind-mounts ``pixie-images/`` at
+#      ``/var/lib/pixie/images``.
+#   6. ``pixie-on-tty1.service`` renders the pixie CLI wizard on tty1.
+
+[cijoe.task]
+fail_fast = true
+
+[qemu]
+img_bin = "qemu-img"
+
+[qemu.systems.x86_64]
+bin = "qemu-system-x86_64"
+
+[qemu.guests.usb-ventoy]
+path = "{{ local.env.HOME }}/system_imaging/usb-ventoy"
+system_label = "x86_64"
+system_args.kwa = { cpu = "host", smp = 2, m = "1G", accel = "kvm" }
+# IDE-hd: Ventoy's bootloader (a chainloaded GRUB) reads via BIOS
+# INT13 -- virtio-blk is invisible to it. Present the Ventoy stick as
+# an IDE hard disk so the BIOS sees a bootable disk. ``-no-reboot`` so
+# a failed boot exits instead of looping.
+system_args.raw = "-drive file={{ local.env.HOME }}/system_imaging/usb-ventoy/disk.img,format=raw,if=ide -no-reboot"
+system_args.tcp_forward = { host = 12223, guest = 22 }
+
+[cijoe.transport.usb_ventoy_guest]
+username = "root"
+password = "pixie"
+hostname = "localhost"
+port = 12223
+
+[test.usb_ventoy]
+iso_dir = "{{ local.env.HOME }}/system_imaging/disk"
+# Pinned Ventoy version so the test is reproducible. Bump deliberately
+# when validating a newer release; this is the Ventoy2Disk.sh version
+# the test installs with, not what an operator must use in production.
+ventoy_version = "1.1.05"

pixie_lab-0.3.2/cijoe/scripts/usb_iso_verify.py

@@ -0,0 +1,92 @@
+"""
+Structurally verify the pixie usbboot .iso
+===========================================
+
+Fast, no-boot sanity checks on ``pixie-usbboot-pc-x86_64-v*.iso`` before
+the Ventoy boot test spends ~10 min proving it actually boots. Catches a
+broken / non-hybrid / single-firmware bake immediately:
+
+  1. ``file`` reports an ISO 9660 filesystem with a DOS/MBR boot sector
+     (the isohybrid MBR that makes ``dd`` to a USB stick BIOS-bootable).
+  2. The El Torito catalog carries BOTH a BIOS and a UEFI/EFI boot
+     image -- i.e. the ISO boots on legacy BIOS AND UEFI firmware.
+  3. The published ``.iso.sha256`` sidecar matches the image.
+
+Retargetable: False (host-side; needs ``file`` + ``xorriso`` +
+``sha256sum`` on the initiator, which the workflow installs).
+"""
+
+from __future__ import annotations
+
+import errno
+import logging as log
+from argparse import ArgumentParser
+from pathlib import Path
+
+ISO_BASENAME_GLOB = "pixie-usbboot-pc-x86_64-v*.iso"
+
+
+def add_args(parser: ArgumentParser):
+    del parser
+
+
+def _out(res) -> str:
+    return res.output() if hasattr(res, "output") else str(res)
+
+
+def main(args, cijoe):
+    del args
+    cfg = cijoe.getconf("test.usb_ventoy", {})
+    iso_dir = Path(cfg.get("iso_dir") or (Path.home() / "system_imaging" / "disk"))
+    candidates = sorted(iso_dir.glob(ISO_BASENAME_GLOB))
+    if not candidates:
+        log.error(f"no {ISO_BASENAME_GLOB} found in {iso_dir} (did usbboot-pc build run?)")
+        return errno.ENOENT
+    iso = candidates[-1]
+    log.info(f"verifying {iso.name} ({iso.stat().st_size} bytes)")
+
+    # 1. Valid ISO 9660 + isohybrid MBR (BIOS-bootable when dd'd).
+    err, res = cijoe.run_local(f"file -- {iso}")
+    if err:
+        log.error("`file` failed")
+        return errno.EIO
+    file_out = _out(res)
+    if "ISO 9660" not in file_out:
+        log.error(f"not an ISO 9660 image: {file_out}")
+        return errno.EINVAL
+    if "DOS/MBR boot sector" not in file_out and "bootable" not in file_out.lower():
+        log.error(f"no isohybrid MBR boot sector (not USB-dd bootable?): {file_out}")
+        return errno.EINVAL
+    log.info("OK: ISO 9660 + DOS/MBR boot sector")
+
+    # 2. El Torito catalog has both a BIOS and a UEFI/EFI boot image.
+    err, res = cijoe.run_local(f"xorriso -indev {iso} -report_el_torito plain 2>&1")
+    if err:
+        log.error("`xorriso -report_el_torito` failed")
+        return errno.EIO
+    et = _out(res)
+    log.info(f"El Torito report:\n{et}")
+    boot_lines = [ln for ln in et.splitlines() if "boot img" in ln.lower()]
+    has_bios = any("BIOS" in ln for ln in boot_lines)
+    has_uefi = any(("UEFI" in ln) or ("EFI" in ln) for ln in boot_lines)
+    if not has_bios:
+        log.error("El Torito catalog has no BIOS boot image")
+        return errno.EINVAL
+    if not has_uefi:
+        log.error("El Torito catalog has no UEFI/EFI boot image")
+        return errno.EINVAL
+    log.info("OK: El Torito has both BIOS and UEFI boot images")
+
+    # 3. sha256 sidecar matches.
+    sha = iso.with_name(iso.name + ".sha256")
+    if not sha.is_file():
+        log.error(f"missing sha256 sidecar: {sha}")
+        return errno.ENOENT
+    err, _ = cijoe.run_local(f"sh -c 'cd {iso_dir} && sha256sum -c {sha.name}'")
+    if err:
+        log.error("sha256 mismatch")
+        return errno.EIO
+    log.info("OK: sha256 sidecar matches")
+
+    log.info(f"{iso.name}: structural verification passed")
+    return 0

pixie_lab-0.3.2/cijoe/scripts/usb_ventoy_guest_start.py

@@ -0,0 +1,48 @@
+"""
+Start the Ventoy QEMU guest WITHOUT the is_up wait
+==================================================
+
+Thin wrapper around ``cijoe.qemu.wrapper.Guest.start()`` that returns
+immediately after the guest is daemonised, skipping the upstream
+``qemu.guest_start`` step's hardcoded 180-second ``is_up`` check
+(which waits for the literal string ``login:`` on the serial console).
+
+Why a local copy: Ventoy adds a chainload phase (menu -> grub ->
+.iso -> initrd -> squashfs) on top of the pixie live env's normal
+boot, which routinely pushes the time-to-login past the 180-second
+ceiling baked into the upstream script. The YAML's
+``core.wait_for_transport`` step already polls SSH readiness with
+its own (configurable) timeout, so this script intentionally splits
+"start the guest" from "wait for it to be reachable" -- the latter
+is the only concern that needs a tunable timeout.
+
+Retargetable: False (host-side; same constraints as the upstream
+script).
+"""
+
+from __future__ import annotations
+
+import logging as log
+from argparse import ArgumentParser
+
+from cijoe.qemu.wrapper import Guest
+
+
+def add_args(parser: ArgumentParser):
+    parser.add_argument("--guest_name", type=str, help="Name of the qemu guest.")
+
+
+def main(args, cijoe):
+    if "guest_name" not in args:
+        log.error("missing argument: guest_name")
+        return 1
+
+    guest = Guest(cijoe, cijoe.config, args.guest_name)
+
+    err = guest.start()
+    if err:
+        log.error(f"guest.start() : err({err})")
+        return err
+
+    log.info(f"guest '{args.guest_name}' started; readiness handled by wait_for_transport")
+    return 0

pixie_lab-0.3.2/cijoe/scripts/usb_ventoy_stage.py

@@ -0,0 +1,231 @@
+"""
+Stage a Ventoy disk for the pixie Ventoy-boot test
+===================================================
+
+Mirrors what an operator does in practice:
+
+  1. Download Ventoy.
+  2. Install Ventoy onto a USB stick (here: a 4 GiB sparse file
+     loop-attached so ``Ventoy2Disk.sh`` sees a block device).
+  3. Drop ``pixie-usbboot-pc-x86_64-v*.iso`` onto the Ventoy data
+     partition so the Ventoy menu offers it.
+  4. Drop a ``pixie-images/`` subdir with one sentinel image + a
+     ``catalog.toml`` -- the operator's image catalog the live env
+     should discover via ``pixie-images-discover.service``.
+  5. Write a ``ventoy/ventoy.json`` with BOTH ``VTOY_MENU_TIMEOUT`` and
+     ``VTOY_SECONDARY_TIMEOUT`` = 1 so the two Ventoy menus auto-boot
+     the only ISO without keyboard input (bty proved both are needed).
+
+The catalog carries a single ``oras://`` entry (rolling nosi tag);
+it exercises pixie's catalog parser as the realistic source operators
+drop next to their images.
+
+Retargetable: False (host-side staging on the cijoe initiator;
+sudo needed for losetup + Ventoy2Disk.sh).
+"""
+
+from __future__ import annotations
+
+import errno
+import logging as log
+import urllib.request
+from argparse import ArgumentParser
+from pathlib import Path
+
+ISO_BASENAME_GLOB = "pixie-usbboot-pc-x86_64-v*.iso"
+DISK_BYTES = 4 * 1024 * 1024 * 1024  # 4 GiB
+
+# ``pixie-images-discover`` bind-mounts the first vfat/exfat partition
+# whose ``pixie-images/`` subdir holds a usable image (``*.img*`` /
+# ``*.qcow2``). A 1 MiB sparse ``.img.gz`` is enough to trip that; it is
+# never flashed.
+IMAGES_SUBDIR = "pixie-images"
+SENTINEL_IMAGE_NAME = "demo-pixie-ventoy-test.img.gz"
+SENTINEL_IMAGE_BYTES = 1 * 1024 * 1024
+
+# Single-entry catalog an operator would realistically drop alongside
+# their images: a remote ``oras://`` ref pixie's catalog parser reads.
+CATALOG_TOML = """\
+version = 1
+
+[[images]]
+name = "ventoy-test-fedora-44-headless"
+src = "oras://ghcr.io/safl/nosi/fedora-44-headless:latest"
+format = "img.gz"
+arch = "x86_64"
+description = "Sentinel remote entry for the Ventoy-boot test"
+"""
+
+
+def add_args(parser: ArgumentParser):
+    del parser
+
+
+def main(args, cijoe):
+    del args
+    cfg = cijoe.getconf("test.usb_ventoy", {})
+    iso_dir = Path(cfg.get("iso_dir") or (Path.home() / "system_imaging" / "disk"))
+    candidates = sorted(iso_dir.glob(ISO_BASENAME_GLOB))
+    if not candidates:
+        log.error(f"no {ISO_BASENAME_GLOB} found in {iso_dir} (did usbboot-pc build run?)")
+        return errno.ENOENT
+    src_iso = candidates[-1]
+    log.info(f"using {src_iso.name} ({src_iso.stat().st_size} bytes)")
+
+    ventoy_version = cfg.get("ventoy_version", "1.1.05")
+    ventoy_url = (
+        f"https://github.com/ventoy/Ventoy/releases/download/"
+        f"v{ventoy_version}/ventoy-{ventoy_version}-linux.tar.gz"
+    )
+
+    guest_path_raw = cijoe.getconf("qemu.guests.usb-ventoy.path")
+    if not guest_path_raw:
+        log.error("missing qemu.guests.usb-ventoy.path in cijoe config")
+        return errno.EINVAL
+    guest_path = Path(guest_path_raw)
+    guest_path.mkdir(parents=True, exist_ok=True)
+
+    disk = guest_path / "disk.img"
+    ventoy_tarball = guest_path / f"ventoy-{ventoy_version}-linux.tar.gz"
+    ventoy_dir = guest_path / f"ventoy-{ventoy_version}"
+
+    # 1. Download Ventoy (cached across runs).
+    if not ventoy_tarball.is_file():
+        log.info(f"downloading {ventoy_url}")
+        urllib.request.urlretrieve(ventoy_url, ventoy_tarball)
+    if not ventoy_dir.is_dir():
+        log.info(f"extracting {ventoy_tarball.name}")
+        err, _ = cijoe.run_local(f"tar -xzf {ventoy_tarball} -C {guest_path}")
+        if err:
+            log.error("tar -xzf failed")
+            return errno.EIO
+
+    # 2. Create the sparse 4 GiB disk (Ventoy will format it).
+    log.info(f"creating sparse disk: {disk} ({DISK_BYTES} bytes)")
+    with disk.open("wb") as fh:
+        fh.truncate(DISK_BYTES)
+
+    # 3. losetup + Ventoy2Disk.sh -I (force install).
+    log.info("losetup -fP --show <disk>")
+    err, out = cijoe.run_local(f"sudo losetup -fP --show {disk}")
+    if err:
+        log.error("losetup failed")
+        return errno.EIO
+    loop_dev = out.output().strip().splitlines()[-1].strip() if hasattr(out, "output") else ""
+    if not loop_dev.startswith("/dev/loop"):
+        log.error(f"unexpected losetup output: {out!r}")
+        return errno.EIO
+    log.info(f"loop device: {loop_dev}")
+
+    mount_dir = guest_path / "ventoy-mount"
+    mount_dir.mkdir(exist_ok=True)
+    sentinel_tmp = guest_path / "demo.tmp"
+    catalog_tmp = guest_path / "catalog.toml.tmp"
+    ventoy_json_tmp = guest_path / "ventoy.json.tmp"
+
+    try:
+        # ``yes | Ventoy2Disk.sh -I <dev>``: force install over any
+        # existing partition table; ``yes`` answers the confirmation
+        # prompts (the disk is about to be erased).
+        log.info(f"Ventoy2Disk.sh -I {loop_dev}")
+        err, _ = cijoe.run_local(f"sudo sh -c 'yes | {ventoy_dir}/Ventoy2Disk.sh -I {loop_dev}'")
+        if err:
+            log.error("Ventoy2Disk.sh failed")
+            return errno.EIO
+
+        # Ventoy creates two partitions: p1 is the exFAT data partition
+        # (ISOs + operator files), p2 is the small VTOYEFI partition.
+        cijoe.run_local("sudo udevadm settle --timeout=10")
+        cijoe.run_local(f"sudo partprobe {loop_dev} || true")
+        cijoe.run_local("sudo udevadm settle --timeout=10")
+        cijoe.run_local(f"sudo lsblk -bno NAME,SIZE,TYPE,LABEL,FSTYPE {loop_dev}")
+
+        ventoy_data = f"{loop_dev}p1"
+        # Kernel exfat first (fast), fall back to mount.exfat-fuse.
+        # Ubuntu's ``mount -t exfat`` does NOT auto-fall-back to FUSE
+        # when the kernel module is missing; GHA's ubuntu-latest ships
+        # a stripped kernel without exfat, so the workflow installs
+        # ``exfat-fuse`` for the ``/sbin/mount.exfat-fuse`` userspace
+        # path.
+        log.info(f"mounting {ventoy_data}")
+        err, _ = cijoe.run_local(f"sudo mount -t exfat {ventoy_data} {mount_dir}")
+        if err:
+            log.info("kernel exfat unavailable; falling back to mount.exfat-fuse")
+            err, _ = cijoe.run_local(f"sudo mount.exfat-fuse {ventoy_data} {mount_dir}")
+            if err:
+                log.error(
+                    f"both kernel and FUSE exfat mounts failed on {ventoy_data} "
+                    f"(install ``exfat-fuse`` or ``linux-modules-extra-$(uname -r)``)"
+                )
+                return errno.EIO
+
+        try:
+            # 4. Drop the .iso at the root of the Ventoy data partition.
+            log.info(f"copying {src_iso.name} -> Ventoy data partition")
+            err, _ = cijoe.run_local(f"sudo cp {src_iso} {mount_dir}/")
+            if err:
+                log.error("cp .iso failed")
+                return errno.EIO
+
+            # 5. pixie-images/ subdir with sentinel image + catalog.toml.
+            cijoe.run_local(f"sudo mkdir -p {mount_dir}/{IMAGES_SUBDIR}")
+
+            log.info(f"staging sentinel image ({SENTINEL_IMAGE_BYTES} bytes)")
+            with sentinel_tmp.open("wb") as fh:
+                fh.truncate(SENTINEL_IMAGE_BYTES)
+            err, _ = cijoe.run_local(
+                f"sudo cp {sentinel_tmp} {mount_dir}/{IMAGES_SUBDIR}/{SENTINEL_IMAGE_NAME}"
+            )
+            if err:
+                log.error("cp sentinel image failed")
+                return errno.EIO
+
+            log.info("staging catalog.toml")
+            catalog_tmp.write_text(CATALOG_TOML, encoding="utf-8")
+            err, _ = cijoe.run_local(
+                f"sudo cp {catalog_tmp} {mount_dir}/{IMAGES_SUBDIR}/catalog.toml"
+            )
+            if err:
+                log.error("cp catalog.toml failed")
+                return errno.EIO
+
+            # 6. ventoy/ventoy.json: fully-headless auto-boot. Ventoy
+            # shows TWO menus that BOTH need a timeout (bty verified via
+            # a stuck-guest screendump): the primary ISO list
+            # (VTOY_MENU_TIMEOUT) and the secondary boot-mode menu
+            # (VTOY_SECONDARY_TIMEOUT). The primary timeout does not
+            # cascade; without the secondary knob the guest sits at the
+            # boot-mode menu forever and no kernel ever boots.
+            cijoe.run_local(f"sudo mkdir -p {mount_dir}/ventoy")
+            ventoy_json_tmp.write_text(
+                "{\n"
+                '  "control": [\n'
+                '    {"VTOY_MENU_TIMEOUT": "1"},\n'
+                '    {"VTOY_SECONDARY_TIMEOUT": "1"}\n'
+                "  ]\n"
+                "}\n",
+                encoding="utf-8",
+            )
+            err, _ = cijoe.run_local(f"sudo cp {ventoy_json_tmp} {mount_dir}/ventoy/ventoy.json")
+            if err:
+                log.error("cp ventoy.json failed")
+                return errno.EIO
+
+            # Record what landed for the cijoe report.
+            cijoe.run_local(f"sudo ls -la {mount_dir}/")
+            cijoe.run_local(f"sudo ls -la {mount_dir}/{IMAGES_SUBDIR}/")
+            cijoe.run_local(f"sudo cat {mount_dir}/{IMAGES_SUBDIR}/catalog.toml")
+            cijoe.run_local(f"sudo cat {mount_dir}/ventoy/ventoy.json")
+            cijoe.run_local(f"sudo sync {mount_dir}")
+        finally:
+            cijoe.run_local(f"sudo umount {mount_dir}")
+    finally:
+        cijoe.run_local(f"sudo losetup -d {loop_dev}")
+        sentinel_tmp.unlink(missing_ok=True)
+        catalog_tmp.unlink(missing_ok=True)
+        ventoy_json_tmp.unlink(missing_ok=True)
+        if mount_dir.is_dir() and not any(mount_dir.iterdir()):
+            mount_dir.rmdir()
+
+    log.info(f"Ventoy disk ready at {disk}")
+    return 0