exec-sandbox 0.21.0__tar.gz → 0.22.0__tar.gz

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exec-sandbox
-Version: 0.21.0
+Version: 0.22.0
 Summary: Secure code execution in microVMs with QEMU
 Project-URL: Homepage, https://github.com/dualeai/exec-sandbox
 Project-URL: Documentation, https://github.com/dualeai/exec-sandbox#readme

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "exec-sandbox"
-version = "0.21.0"
+version = "0.22.0"
 description = "Secure code execution in microVMs with QEMU"
 readme = "README.md"
 license = "Apache-2.0"

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/scripts/build-qemu.sh

@@ -101,8 +101,12 @@ cd "qemu-${QEMU_VERSION}"
 # --enable-fdt: device tree support, required for aarch64-softmmu (virt machine),
 #   harmless for x86_64. Needs libfdt-dev.
 # --enable-kvm: KVM acceleration support.
-# --enable-linux-io-uring: io_uring async I/O backend for block drives (aio=io_uring).
-#   Needs liburing-dev (>= 0.3). Falls back to aio=threads if unavailable at runtime.
+# --enable-linux-io-uring: io_uring async I/O backend. Needs liburing-dev (>= 0.3).
+#   Two benefits: (1) block drives use aio=io_uring (falls back to aio=threads if
+#   unavailable at runtime), and (2) since QEMU 10.2 the main event loop itself is
+#   io_uring-based when liburing is linked — lower syscall/wakeup overhead on fd
+#   monitoring. Keeping this flag ensures BOTH; without it the main loop silently
+#   falls back to ppoll. (probe_io_uring_support() only gates the drive aio= mode.)
 # --enable-seccomp: seccomp sandbox for QEMU process (-sandbox on).
 #   Needs libseccomp-dev (>= 2.3.0).
 # --enable-slirp: user-mode networking backend. Needs libslirp-dev.

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/src/exec_sandbox/constants.py

@@ -402,17 +402,31 @@ Only used when socket activation is unavailable (sudo wraps QEMU, closing
 inherited fds). With socket activation, the socket is pre-created and no
 polling is needed."""
 
-MEMORY_SNAPSHOT_MIN_QEMU_VERSION: Final[tuple[int, int, int]] = (9, 0, 0)
+MEMORY_SNAPSHOT_MIN_QEMU_VERSION: Final[tuple[int, int, int]] = (11, 0, 0)
 """Minimum QEMU version for mapped-ram + multifd migration capabilities.
-Changing capabilities requires bumping MEMORY_SNAPSHOT_FORMAT_VERSION."""
 
-MEMORY_SNAPSHOT_FORMAT_VERSION: Final[int] = 3
+Floor is 11.0: it is the first release where mapped-ram coexists with
+x-ignore-shared without a null-deref ("Bad address") crash, letting the template
+and full-RAM paths share ONE unified capability list (no version fork). The
+project pins QEMU 11.0.2, so this floor is free; older local installs fall back
+to plain streaming migration. Changing capabilities requires bumping
+MEMORY_SNAPSHOT_FORMAT_VERSION."""
+
+MEMORY_SNAPSHOT_FORMAT_VERSION: Final[int] = 4
 """Migration format version. Bump when changing QMP capabilities or migration
 protocol to invalidate stale L1 cache entries. History:
   v1: Plain streaming format (no mapped-ram)
   v2: mapped-ram + multifd (QEMU >= 9.0)
   v3: x-ignore-shared VM templating — device-state-only vmstate + separate
       RAM file for COW sharing across VMs (QEMU >= 9.0)
+  v4: unified capability list — template path now also enables mapped-ram +
+      multifd alongside x-ignore-shared (QEMU >= 11.0 fixes the coexistence
+      crash), removing the version-forked branch.
+
+NOTE: the migration stream layout is QEMU-version- AND parameter-specific — a
+QEMU upgrade or a change to multifd-channels / direct-io (both baked into the
+mapped-ram file layout) requires restore-QEMU == save-QEMU. Any such change must
+bump this version so stale, incompatible snapshots are not restored.
 """
 
 # ============================================================================

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/src/exec_sandbox/migration_client.py

@@ -197,28 +197,37 @@ class MigrationClient:
 
         Both sender (save) and receiver (restore) MUST set the same
         capabilities, otherwise QEMU rejects with "received capability is off".
+
+        NOTE (design constraints, verified QEMU 11.0):
+        - mapped-ram is INCOMPATIBLE with multifd-compression (seekable-fd
+          requirement) AND with migration TLS. Any snapshot compression or
+          encryption for a future S3 freeze/thaw path must therefore be done
+          EXTERNALLY (client-side zstd + AEAD), not via QEMU capabilities. The
+          sanctioned in-QEMU perf recovery is the `direct-io` migration parameter
+          (O_DIRECT), gated to the full-RAM path when that lands.
+        - CPR (cpr-reboot/transfer/exec) is NOT a resume-anywhere primitive: all
+          modes are same-host only (fd/RAM handoff to a peer QEMU), so they cannot
+          back S3 freeze/thaw. Their only use here would be in-place QEMU upgrades.
+        - The migration stream format is QEMU-version-specific; a QEMU bump
+          invalidates saved snapshots (see MEMORY_SNAPSHOT_FORMAT_VERSION).
         """
         if qemu_version is None or qemu_version < constants.MEMORY_SNAPSHOT_MIN_QEMU_VERSION:
             return
 
+        # Unified capability list (QEMU >= 11.0). Base is mapped-ram + multifd for
+        # seekable, parallel page I/O. Template mode adds x-ignore-shared to skip
+        # RAM pages backed by the shared memory-backend-file (device-state-only
+        # vmstate). mapped-ram + x-ignore-shared coexist safely only since 11.0
+        # (earlier releases null-deref on ignored blocks — the reason the floor is
+        # 11.0), so both paths share one branch-free list.
+        # Ref: QEMU commit "migration/mapped-ram: Fix x-ignore-shared snapshots"
+        #      (Pawel Zmarzly, Nov 2025; reviewed by Peter Xu, Dec 2025)
+        capabilities = [
+            {"capability": "multifd", "state": True},
+            {"capability": "mapped-ram", "state": True},
+        ]
         if use_template:
-            # VM Templating: x-ignore-shared skips RAM pages backed by shared
-            # memory-backend-file.  mapped-ram is INCOMPATIBLE with x-ignore-shared
-            # in QEMU <= 10.x: mapped-ram's bitmap code dereferences null pointers
-            # for ignored blocks, crashing with "Bad address".  Fix merged for 11.0.
-            # Ref: QEMU commit "migration/mapped-ram: Fix x-ignore-shared snapshots"
-            #      (Pawel Zmarzly, Nov 2025; reviewed by Peter Xu, Dec 2025)
-            # TODO(qemu-11): Re-enable mapped-ram + multifd alongside x-ignore-shared
-            # once QEMU >= 11.0 is the minimum version.  This will give parallel I/O
-            # for the device-state portion of the vmstate.
-            capabilities = [
-                {"capability": "x-ignore-shared", "state": True},
-            ]
-        else:
-            capabilities = [
-                {"capability": "multifd", "state": True},
-                {"capability": "mapped-ram", "state": True},
-            ]
+            capabilities.append({"capability": "x-ignore-shared", "state": True})
         resp = await self._execute(
             "migrate-set-capabilities",
             {"capabilities": capabilities},
@@ -263,6 +272,11 @@ class MigrationClient:
         # Valid = false). QEMU's hvf_handle_exception asserts isv==true, causing
         # SIGABRT. Stopping the vCPU first eliminates the race.
         # See: https://github.com/qemu/qemu/blob/master/target/arm/hvf/hvf.c
+        #
+        # NOTE (non-adoption): the background-snapshot capability (live snapshot
+        # without pausing the vCPU) is not used. It is KVM-only (needs userfaultfd
+        # write-protect) so excluded on HVF, and we snapshot idle sessions where a
+        # brief stop is cheap and full-fidelity capture wants a quiescent VM anyway.
         resp = await self._execute("stop")
         if "error" in resp:
             raise MigrationTransientError(f"stop command failed: {resp['error']}")
@@ -346,7 +360,11 @@ class MigrationClient:
                 status = resp.get("return", {}).get("status", "")
                 if status == "completed":
                     return
-                if status in ("failed", "cancelled"):
+                # "failing" (QEMU 11.0+): an error occurred and cleanup is underway;
+                # the status will transition to "failed" shortly. Treat it as terminal
+                # here so a mid-stream failure surfaces immediately instead of burning
+                # another poll interval waiting for the "failed" transition.
+                if status in ("failed", "cancelled", "failing"):
                     error_desc = resp.get("return", {}).get("error-desc", "unknown")
                     raise MigrationTransientError(f"Migration {status}: {error_desc}")
 

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/src/exec_sandbox/qemu_cmd.py

@@ -89,6 +89,10 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
 
     # Detect hardware acceleration type (centralized in detect_accel_type)
     accel_type = await detect_accel_type(force_emulation=settings.force_emulation)
+
+    # QEMU version gates several flags below (machine props, netdev reconnect,
+    # -run-with). Probe once up front; the result is cached in system_probes.
+    qemu_version = await probe_qemu_version()
     logger.info(
         "Hardware acceleration detection",
         extra={"vm_id": vm_id, "accel_type": accel_type.value, "is_macos": is_macos},
@@ -102,6 +106,14 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
     else:
         # TCG software emulation fallback (~5-8x slower than KVM/HVF)
         #
+        # NOTE (security envelope): QEMU's security policy grants the
+        # "virtualization use case" isolation guarantee only to microvm (x86) /
+        # virt (aarch64) *with* a hardware accelerator (KVM/HVF). The TCG path is
+        # explicitly NOT security-supported ("must not rely on QEMU for
+        # isolation"). It is a functional fallback for CI / trusted workloads
+        # only; prod isolation always runs on KVM or HVF.
+        # See: https://qemu-project.gitlab.io/qemu/system/security.html
+        #
         # thread=single: Disable MTTCG to reduce thread count per VM. Without this,
         # each VM creates multiple threads for parallel translation, exhausting
         # system thread limits when running parallel tests (qemu_thread_create:
@@ -149,10 +161,19 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
         #   random.trust_cpu=on in kernel cmdline
         # mem-merge: KSM page dedup (Linux only; macOS HVF does not support it)
         mem_merge = "off" if is_macos else "on"
+        # virtio-mmio-transports=8: cap the number of virtio-mmio transport slots
+        #   (QEMU virt board default is 32). We instantiate at most 6 virtio-mmio
+        #   devices (blk-base + optional blk-snap + serial + balloon + rng +
+        #   optional net); 8 leaves headroom. Fewer empty slots means the guest's
+        #   virtio_mmio driver skips ~24 spurious MMIO magic/device-id probes at
+        #   boot and the DTB is smaller. Keep >= the live device count or QEMU aborts.
+        #   Machine property added in QEMU 11.0 — gated to avoid aborting older
+        #   local installs. See docs/system/arm/virt.rst.
+        mmio_transports = ",virtio-mmio-transports=8" if qemu_version is not None and qemu_version >= (11, 0, 0) else ""
         machine_type = (
-            f"virt,virtualization=off,highmem=off,gic-version=3,its=off,dtb-randomness=off,mem-merge={mem_merge}"
+            f"virt,virtualization=off,highmem=off,gic-version=3,its=off,dtb-randomness=off,mem-merge={mem_merge}{mmio_transports}"
             if is_macos
-            else f"virt,virtualization=off,highmem=off,gic-version=3,its=off,dtb-randomness=off,mem-merge={mem_merge},dump-guest-core=off"
+            else f"virt,virtualization=off,highmem=off,gic-version=3,its=off,dtb-randomness=off,mem-merge={mem_merge}{mmio_transports},dump-guest-core=off"
         )
     else:
         arch_suffix = "x86_64"
@@ -294,6 +315,9 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
             # also lacks 256-bit vector ops (TCG_TARGET_HAS_v256=0), so AVX2
             # is unavailable — effective ceiling is SSE4.2. On x86 hosts the
             # effective ceiling is x86_64-v3 (AVX2/FMA).
+            # NOTE (non-adoption): ARM `max,sve=off,sme=off` (individually maskable
+            # on `max` since QEMU 11.0) is not set — boot never exercises SVE/SME,
+            # so the win is ~zero (only trims per-vCPU vector-state struct size).
             # See: https://www.qemu.org/docs/master/system/i386/cpu.html
             # See: https://gitlab.com/qemu-project/qemu/-/issues/844
             (
@@ -339,6 +363,9 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
             # (16-64KB per fault instead of 4KB), but transparent_hugepage=never
             # disables anonymous 2MB hugepages (no khugepaged, no compaction stalls).
             # File-backed large folios work regardless of this sysfs setting.
+            # NOTE (non-adoption): keeping anon THP off is deliberate for density —
+            # 2MB hugepages defeat free-page-reporting and KSM (both 4KB-granular)
+            # and add compaction stalls; enabling them would hurt host-RAM-per-VM.
             + " transparent_hugepage=never"
             # Boot verbosity: debug_boot enables full kernel/init logging for diagnostics
             # Note: loglevel=7 overrides loglevel=1 set in console_params (kernel uses last occurrence)
@@ -471,9 +498,8 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
             ]
         )
 
-    # Determine AIO mode and QEMU version based on cached startup probes
+    # Determine AIO mode based on cached startup probes (qemu_version probed above)
     io_uring_available = await probe_io_uring_support()
-    qemu_version = await probe_qemu_version()
     aio_mode = "io_uring" if io_uring_available else "threads"
     if not io_uring_available:
         logger.debug(
@@ -503,6 +529,13 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
 
     # Disk configuration (EROFS base drive, serial=base)
     # Uses qcow2 overlay backed by the EROFS base image
+    #
+    # NOTE (non-adoption): RWF_DSYNC FUA (QEMU 10.0 file-posix) is deliberately
+    # unused. It only helps cache=writethrough/directsync; cache=unsafe drops all
+    # flushes/FUA outright, which strictly dominates for discard-on-exit overlays
+    # (a host crash loses in-flight overlay writes, but the overlay is thrown away
+    # on VM exit). Switching to a flushing cache mode to gain FUA would be a large
+    # regression here.
     qemu_args.extend(
         [
             "-drive",
@@ -534,6 +567,13 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
     # rootfs drive, regardless of /dev/vdX assignment. ARM virt (MMIO) enumerates
     # virtio devices in reverse declaration order, so /dev/vda != first -device on ARM.
     # D2: event_idx=off reduces interrupt coalescing overhead during boot.
+    #
+    # NOTE (non-adoption): num-queues=1 is deliberate. virtio-blk multiqueue /
+    # iothread-vq-mapping (QEMU 9.0) only pays off with many vCPUs and an
+    # I/O-bound guest saturating a single iothread. Our VMs have 1-2 vCPUs, a
+    # read-only page-cache-hot EROFS base and a tiny cache=unsafe overlay — never
+    # iothread-CPU-bound. HVF has no ioeventfd (block already routed to main-loop
+    # above) and TCG is thread=single, so extra queues buy nothing here.
     qs = constants.VIRTIO_QUEUE_SIZE
     qemu_args.extend(
         [
@@ -622,6 +662,10 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
     # See: https://bugs.launchpad.net/qemu/+bug/1639791 (early virtio console lost)
     # See: https://gist.github.com/mcastelino/aa118275991d4f561ee22dc915b9345f
     # =============================================================
+    # NOTE (non-adoption): guest-agent transport stays on virtio-serial. vhost-vsock
+    # was evaluated as an alternative; no QEMU 10.1→11.0 reliability/perf change
+    # shifts the tradeoff, and virtio-serial's named ports (cmd/event) map cleanly
+    # onto the existing guest-agent protocol.
     qemu_args.extend(
         [
             "-device",
@@ -637,6 +681,13 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
     )
 
     # virtio-balloon for host memory efficiency (deflate/inflate for warm pool).
+    #
+    # NOTE (non-adoption): virtio-mem is deliberately not used in place of the
+    # balloon. It targets long-lived, resizable VMs; unplug is guest-cooperative,
+    # slow, and can partially fail, and its block size must be a power-of-two
+    # >= 2 MiB — coarse for our small -m VMs. It has no HVF support and yields no
+    # net RSS win over free-page-reporting + template-COW page sharing.
+    #
     # Disabled for ALL template VMs (save AND restore):
     #   1. Device topology must match between save and restore — QEMU migration
     #      fails with "Unknown section" if one side has balloon and the other doesn't.
@@ -697,6 +748,9 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
     #
     # =============================================================
 
+    # NOTE (non-adoption): the in-tree passt netdev (QEMU 10.1) is not used. It
+    # lacks gvproxy's API-driven outbound-filtering and dynamic port-forward model
+    # that Modes 1-3 below depend on, so it is not a drop-in replacement.
     needs_network = allow_network or bool(expose_ports)
     if needs_network:
         # All modes use socket networking to gvproxy (fast ~300ms boot)
@@ -783,8 +837,21 @@ async def build_qemu_cmd(  # noqa: PLR0912, PLR0915
 
     # Orphan protection: kill QEMU if parent process dies (QEMU 10.2+)
     # Uses PR_SET_PDEATHSIG on Linux, kqueue on macOS/FreeBSD
+    #
+    # async-teardown=on (Linux only): fork a teardown clone that unmaps guest RAM
+    # so the main QEMU can exit without blocking on munmap. Trims destroy_vm()
+    # tail latency under mass pool recycle. macOS QEMU rejects this sub-option
+    # (only chroot/exit-with-parent/user exist there), so it is Linux-gated.
+    #
+    # NOTE (non-adoption): -run-with chroot=/user= are not used. Both require a
+    # privileged launcher (QEMU starts root, then drops), which conflicts with our
+    # unprivileged model — sudo -u qemu-vm + fd-passing (socket-activated QMP).
+    # Filesystem confinement is already provided by `unshare --mount` on Linux.
     if qemu_version is not None and qemu_version >= (10, 2, 0):
-        qemu_args.extend(["-run-with", "exit-with-parent=on"])
+        run_with_opts = "exit-with-parent=on"
+        if not is_macos:
+            run_with_opts += ",async-teardown=on"
+        qemu_args.extend(["-run-with", run_with_opts])
 
     # Run QEMU as unprivileged user if qemu-vm user is available (optional hardening)
     # Falls back to current user if qemu-vm doesn't exist - VM still provides isolation

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/src/exec_sandbox/scheduler.py

@@ -217,6 +217,13 @@ class Scheduler:
 
             # Initialize WarmVMPool (optional)
             if self.config.warm_pool_size > 0:
+                # The pool pre-boots one VM per language, and its startup hashes
+                # each base image (check_cache -> compute_cache_key -> get_base_image).
+                # On a fresh cache ensure_assets() fetched only kernel/initramfs, so
+                # download every pooled base image first, else start() raises
+                # VmDependencyError. Mirrors the per-run fetch in _prepare_vm.
+                if self.config.auto_download_assets:
+                    await asyncio.gather(*(fetch_base_image(language.value) for language in Language))
                 self._warm_pool = WarmVMPool(
                     self._vm_manager,
                     self.config,
@@ -701,6 +708,12 @@ class Scheduler:
         if vm is None:
             is_cold_boot = True
 
+            # Base image must be on disk before the L1 cache key hashes it
+            # (check_cache -> compute_cache_key -> get_base_image) and before
+            # cold create_vm. Skip when snapshot_path already fetched it.
+            if self.config.auto_download_assets and not snapshot_path:
+                await fetch_base_image(language)
+
             admission_start = asyncio.get_running_loop().time()
             async with self._vm_manager.reservation_context(
                 vm_id=f"{constants.SCHEDULER_TENANT_ID}-{task_id}",
@@ -747,11 +760,6 @@ class Scheduler:
 
                 # Cold boot fallback: L1 miss (or L1 skipped for network/boot-log)
                 if vm is None:
-                    # Auto-download base image if needed (skip when snapshot_path
-                    # is set — _get_or_create_snapshot already fetched it)
-                    if self.config.auto_download_assets and not snapshot_path:
-                        await fetch_base_image(language)
-
                     vm = await self._vm_manager.create_vm(
                         language=language,
                         tenant_id=constants.SCHEDULER_TENANT_ID,

{exec_sandbox-0.21.0 → exec_sandbox-0.22.0}/tests/test_migration_client.py

@@ -287,11 +287,11 @@ class TestMigrationClientExecuteEdgeCases:
 class TestMigrationClientSetCapabilities:
     """Tests for _set_capabilities (mapped-ram + multifd on QEMU >= 9.0)."""
 
-    async def test_enables_mapped_ram_for_qemu_9(self) -> None:
-        """QEMU >= 9.0 should enable mapped-ram + multifd."""
+    async def test_enables_mapped_ram_for_qemu_11(self) -> None:
+        """QEMU >= 11.0 should enable mapped-ram + multifd."""
         client, _reader, writer = _make_connected([{"return": {}}])
 
-        await client._set_capabilities((9, 2, 0))
+        await client._set_capabilities((11, 2, 0))
 
         cmds = writer.commands
         assert len(cmds) == 1
@@ -299,12 +299,25 @@ class TestMigrationClientSetCapabilities:
         cap_names = {c["capability"] for c in cmds[0]["arguments"]["capabilities"]}
         assert "multifd" in cap_names
         assert "mapped-ram" in cap_names
+        # Non-template save: no x-ignore-shared (full RAM captured).
+        assert "x-ignore-shared" not in cap_names
+
+    async def test_template_adds_x_ignore_shared(self) -> None:
+        """Template mode appends x-ignore-shared to the unified mapped-ram list."""
+        client, _reader, writer = _make_connected([{"return": {}}])
+
+        await client._set_capabilities((11, 2, 0), use_template=True)
+
+        cmds = writer.commands
+        assert len(cmds) == 1
+        cap_names = {c["capability"] for c in cmds[0]["arguments"]["capabilities"]}
+        assert cap_names == {"multifd", "mapped-ram", "x-ignore-shared"}
 
     async def test_no_capabilities_for_old_qemu(self) -> None:
-        """QEMU < 9.0 should not set capabilities."""
+        """QEMU < 11.0 should not set capabilities (falls back to plain streaming)."""
         client, _reader, writer = _make_connected()
 
-        await client._set_capabilities((8, 2, 0))
+        await client._set_capabilities((10, 2, 0))
 
         assert len(writer.commands) == 0
 
@@ -325,25 +338,25 @@ class TestMigrationClientSetCapabilities:
         )
 
         # Should not raise
-        await client._set_capabilities((9, 2, 0))
+        await client._set_capabilities((11, 2, 0))
 
 
 class TestMigrationClientSetCapabilitiesEdgeCases:
     """Edge cases for capability negotiation."""
 
-    async def test_boundary_qemu_version_9_0_0(self) -> None:
-        """Exactly QEMU 9.0.0 should enable capabilities (>= check)."""
+    async def test_boundary_qemu_version_11_0_0(self) -> None:
+        """Exactly QEMU 11.0.0 should enable capabilities (>= check)."""
         client, _reader, writer = _make_connected([{"return": {}}])
 
-        await client._set_capabilities((9, 0, 0))
+        await client._set_capabilities((11, 0, 0))
 
         assert any(c["execute"] == "migrate-set-capabilities" for c in writer.commands)
 
-    async def test_boundary_qemu_version_8_99_99(self) -> None:
-        """QEMU 8.99.99 should NOT enable capabilities (< 9.0.0)."""
+    async def test_boundary_qemu_version_10_99_99(self) -> None:
+        """QEMU 10.99.99 should NOT enable capabilities (< 11.0.0)."""
         client, _reader, writer = _make_connected()
 
-        await client._set_capabilities((8, 99, 99))
+        await client._set_capabilities((10, 99, 99))
 
         assert len(writer.commands) == 0
 
@@ -406,6 +419,26 @@ class TestMigrationClientPollMigration:
         ):
             await client._poll_migration(timeout=5.0)
 
+    async def test_poll_raises_on_failing(self) -> None:
+        """Poll should raise on 'failing' status (QEMU 11.0+ error-cleanup state).
+
+        'failing' means an error occurred and cleanup is underway (it transitions
+        to 'failed' shortly). We treat it as terminal so the failure surfaces one
+        poll interval sooner instead of waiting for the 'failed' transition.
+        """
+        client, _reader, _writer = _make_connected(
+            [
+                {"return": {"status": "active"}},
+                {"return": {"status": "failing", "error-desc": "write error"}},
+            ]
+        )
+
+        with (
+            patch.object(constants, "MEMORY_SNAPSHOT_POLL_INTERVAL_SECONDS", 0.001),
+            pytest.raises(MigrationTransientError, match="failing"),
+        ):
+            await client._poll_migration(timeout=5.0)
+
     async def test_poll_raises_on_query_error(self) -> None:
         """Poll should raise MigrationTransientError on query-migrate error response."""
         client, _reader, _writer = _make_connected(
@@ -494,13 +527,13 @@ class TestMigrationClientSaveSnapshot:
         )
 
         with patch.object(constants, "MEMORY_SNAPSHOT_POLL_INTERVAL_SECONDS", 0.001):
-            await client.save_snapshot(Path("/tmp/test.vmstate"), qemu_version=(9, 2, 0))
+            await client.save_snapshot(Path("/tmp/test.vmstate"), qemu_version=(11, 2, 0))
 
         cmds = [c["execute"] for c in writer.commands]
         assert cmds == ["migrate-set-capabilities", "stop", "migrate", "query-migrate", "quit"]
 
     async def test_save_command_sequence_old_qemu(self) -> None:
-        """Save with QEMU < 9.0 should: stop → migrate → poll → quit (no capabilities)."""
+        """Save with QEMU < 11.0 should: stop → migrate → poll → quit (no capabilities)."""
         client, _reader, writer = _make_connected(
             [
                 {"return": {}},  # stop
@@ -638,7 +671,7 @@ class TestMigrationClientRestoreSnapshot:
         )
 
         with patch.object(constants, "MEMORY_SNAPSHOT_POLL_INTERVAL_SECONDS", 0.001):
-            await client.restore_snapshot(Path("/tmp/test.vmstate"), qemu_version=(9, 2, 0))
+            await client.restore_snapshot(Path("/tmp/test.vmstate"), qemu_version=(11, 2, 0))
 
         cmds = [c["execute"] for c in writer.commands]
         assert cmds == ["migrate-set-capabilities", "migrate-incoming", "query-migrate", "cont"]
@@ -655,7 +688,7 @@ class TestMigrationClientRestoreSnapshot:
         )
 
         with patch.object(constants, "MEMORY_SNAPSHOT_POLL_INTERVAL_SECONDS", 0.001):
-            await client.restore_snapshot(Path("/tmp/test.vmstate"), qemu_version=(9, 2, 0))
+            await client.restore_snapshot(Path("/tmp/test.vmstate"), qemu_version=(11, 2, 0))
 
         cmds = [c["execute"] for c in writer.commands]
         assert "quit" not in cmds