[Enrique Saurez (esaurez)]

nvx-rs sandbox keeps its own runtime records, lock, and spawn, wait, and kill code, which #772, stacked on this PR, replaces with the host layers that every host of a sandbox shares: host::store, host::supervisor, and host::session. This PR prepares that move, and changes no behavior. Its earlier pushes held the whole move, which was split out into #772 to keep each review small.

What changes

• Runtime identity. ArtifactDir::runtime_identity reads the identities of OpenVMM, the kernel, and the Alpine initramfs from install metadata, and never hashes an artifact; RuntimeIdentity::new adds this build's boot and control contract versions:

  • a release lists their SHA-256 digests in its SHA256SUMS, under bin/openvmm[.exe], guest/vmlinux, and guest/initramfs.cpio.gz;
  • a repository checkout has them in the build provenance that nvx.py writes to build/ with each artifact that it builds, and that nvx.py download installs: executable_sha256 of openvmm.provenance.json, kernel_sha256 of vmlinux.provenance.json, and initramfs_sha256 of initramfs.provenance.json.

  Nothing calls it yet: the CLI's managed start records the identity that it reads in nvx-rs: move the CLI's sandbox lifecycle onto the store and supervisor #772, and host::instance in nvx-rs: move host::instance onto the store and supervisor #721.

• The CLI's start. start builds the OpenVMM command from the arguments before and after its control endpoint, and checks that the guest is ready in a function of its own, check_ready, so that nvx-rs: move the CLI's sandbox lifecycle onto the store and supervisor #772 can launch OpenVMM with supervisor::launch, which chooses the endpoint itself. The command and the order of the checks stay as they were.

• Tests. The CLI's tests share the helpers that provision a sandbox with a command line for the fake OpenVMM and that list a state directory, which the tests of nvx-rs: move the CLI's sandbox lifecycle onto the store and supervisor #772 use too.

Behavior

Nothing changes. The golden fixture nvx-rs/tests/fixtures/cli.json is unchanged, and the existing tests check what they checked before.

Tests

• host::artifacts unit tests: the identity of each layout, and the errors for missing, malformed, and duplicated metadata.

Part of #620. Refs #535.

Validation

Run at this head (f5cff887), on dev at ed6a603f, on Windows 11 (MSVC, WHP) and on an Azure Linux 3 host with MSHV. Real VMs ran with nvx-rs built from this branch and the artifacts of v0.1.0-dev.ed6a603f1e53, the release of ed6a603f, from nvx.py download. The MSHV host cannot present the built-in profile of its CPU (amd.genoa.v1), so OpenVMM ran there through a wrapper that adds --cpu-profile host.

• python scripts/nvx.py verify.
• nvx-rs, with NVX_BUNDLE=skip, on Windows and Linux: cargo fmt --all --check; cargo clippy --locked --all-targets --all-features -- -D warnings; cargo clippy --locked --lib --no-default-features -- -D warnings; cargo test --locked --all-features, then cargo test --locked; cargo doc --locked --no-deps --all-features with RUSTDOCFLAGS=-D warnings. On Linux, the other steps of check-nvx-rs: the 1.89 check, the macOS check, the artifact-bundling test, and the three configurations of tests/runtime-adapter.
• aci_edge_sandboxes: the steps of check-aci-edge-sandboxes on Linux (fmt, clippy, tests, nvx.py test-agent-bundling, docs, the 1.89 check, the macOS check), and its fmt, clippy, tests, and docs on Windows.
• On Linux, the tests of validate-nvx, the nvx.py --help smoke commands, the Specula tests, and the pinned shellcheck and shfmt on the scripts that check-quality lists.
• WHP, and MSHV under sudo for /dev/mshv: python scripts/nvx.py test-microvm --scenario managed-lifecycle --scenario sandbox-lifecycle --scenario managed-exec-config.

Left to CI: the full matrix on KVM, MSHV, and WHP.

[Copilot]

🟡 Changes recommended

Unjournaled legacy state can be overwritten, FIFO locks can hang transitions, and Windows guest bundles omit required provenance.

3 open issues

• Guest bundle omits required provenance files · New
• Unjournaled control files permit duplicate VM starts · New
• FIFO lock open can block indefinitely on Linux · New

What changed in this PR

Moves the CLI’s managed sandbox lifecycle onto the shared host store and supervisor, while retaining CLI configuration and policy.

Changes:

• Adopts shared locking, launch recovery, runtime records, and process supervision.
• Reads runtime identities from artifact metadata without hashing artifacts.
• Updates lifecycle tests and documents the format switch.

File	Description
scripts/​test_microvm_tests.py	Updates simulated lifecycle behavior and regression checks.
scripts/​nvx_tools/​sandbox_lifecycle_tests.py	Adapts acceptance checks to shared-store state.
nvx-rs/​tests/​cli.rs	Adds identity, timeout, and crash-recovery coverage.
nvx-rs/​src/​testing/​fake_openvmm.rs	Adds delayed exit after stop.
nvx-rs/​src/​host/​supervisor/​mod.rs	Exposes the child for failed-start cleanup.
nvx-rs/​src/​host/​store/​mod.rs	Clarifies record-format documentation.
nvx-rs/​src/​host/​python/​windows.rs	Removes unused file-status helpers.
nvx-rs/​src/​host/​python/​mod.rs	Updates filesystem helper documentation.
nvx-rs/​src/​host/​python/​fs.rs	Removes unused fstat support.
nvx-rs/​src/​host/​process.rs	Updates remaining-caller documentation.
nvx-rs/​src/​host/​platform/​windows.rs	Removes obsolete byte-range lock helpers.
nvx-rs/​src/​host/​cli/​sandbox/​state.rs	Removes the CLI runtime-format constant.
nvx-rs/​src/​host/​cli/​sandbox/​mod.rs	Passes artifacts into lifecycle transitions.
nvx-rs/​src/​host/​cli/​sandbox/​lock.rs	Delegates locking to the shared store.
nvx-rs/​src/​host/​cli/​sandbox/​lifecycle.rs	Uses shared recovery, launch, and stop mechanisms.
nvx-rs/​src/​host/​cli/​sandbox/​identity.rs	Removes CLI-specific process identity handling.
nvx-rs/​src/​host/​artifacts.rs	Reads runtime identities from install metadata.
nvx-rs/​README.md	Documents lifecycle and compatibility changes.
doc/​run.md	Updates lifecycle usage and acceptance documentation.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-platform process recovery and the state-format switch warrant human review with completed current-head platform validation.

No open issues 🎉

3 resolved since last review

• Unjournaled control files permit duplicate VM starts
• Guest bundle omits required provenance files
• FIFO lock open can block indefinitely on Linux

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-platform recovery, lock handoff, and the non-migrating state-format switch warrant final human review alongside remaining CI validation.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-platform recovery, lock handoff, and incompatible runtime records warrant final human review and full backend CI confirmation.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-platform lock handoff, crash recovery, and persisted-runtime changes warrant final human review with full backend CI results.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The persisted-state format switch and cross-platform recovery and locking changes warrant final human review and confirmation of the full backend CI matrix.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The identity reader matches existing metadata formats, and the focused lifecycle and test refactors preserve behavior with no blocking issues identified.

No open issues 🎉

_{Review effort: Balanced}