sandbox: accept only the distro layer and scratch

[Jay (jay23606)]

Refs #556. Part one: the NVX side. The OpenVMM change is a separate PR and the pin is not bumped here.

Summary

• Launcher, guest init agent, microVM test, and docs accept only the distro layer and scratch. runtime and custom are refused.
• The sandbox-blocks guest check now expects two devices and verifies the freed windows 0xd0004000/0xd0005000 are absent.
• Works with the current OpenVMM pin, since the removed roles are never requested. Bumping the pin to the OpenVMM change is the follow-up.

Test

• python -m unittest test_nvx_tools: 533 tests pass (54 skipped as before).
• ruff check and format, and pyright strict on Linux and Windows: clean. bash -n on the guest agent and the sandbox script.
• The microVM hardware scenarios were not run here.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Existing validation assertions still expect four devices, and managed configurations can silently discard removed layer roles.

2 open findings

• Update device assertions to expect only distro and scratch · New
• Validate the sole layer role before deserializing the launch · New

What changed in this PR

Implements the NVX portion of #556, restricting sandbox storage to one distro layer and writable scratch. The OpenVMM pin remains unchanged.

Changes:

• Restricts launcher and guest-agent layer handling to distro.
• Updates block discovery checks for two devices and unused former slots.
• Revises launch-contract tests and documentation.

File	Description
scripts/​test_nvx_tools.py	Tests the single-distro launch contract.
scripts/​nvx_tools/​sandbox.py	Restricts layer roles and count.
scripts/​nvx_tools/​microvm_tests.py	Attaches only distro and scratch.
scripts/​nvx_tools/​microvm_test_scripts/​sandbox-blocks.sh	Checks two devices and freed windows.
guest/​common/​nvx-init-agent	Removes multi-layer mounting and teardown.
doc/​usage.md	Documents distro-only layer support.
doc/​run.md	Updates the sandbox storage description.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The scoped removal is consistent and has no identified blocking issues; hardware scenarios remain unverified.

0 open findings

2 resolved since last review

• Update device assertions to expect only distro and scratch
• Validate the sole layer role before deserializing the launch

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

No blocking issues remain in the scoped changes, which preserve fixed device addresses; hardware scenarios were not run.

0 open findings

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The scoped changes consistently enforce the intended storage contract with no blocking issues identified; hardware scenarios remain untested.

0 open findings

🧠 Review effort: Balanced

[Pedro Henrique Penna (ppenna)]

Thanks for this change! A heads-up: #597 (PR 4 of the #359 stack) moves nvx.py sandbox onto the Rust nvx-rs CLI and deletes the Python launch profile in scripts/nvx_tools/sandbox.py that this PR edits. So that the behavior isn't lost, #597 implements it in Rust: the launch profile accepts only the distro layer, with the same messages and check order (unsupported layer role 'runtime'; choose distro and a sandbox requires exactly one read-only distro layer), and it carries your nvx-init-agent, sandbox-blocks.sh, scenario, test, and doc changes as they are. Your review there would be very welcome.

[Copilot]

🟢 Approval recommended

The scoped restriction is consistent across implementation, tests, and documentation, with no blocking issues identified; hardware scenarios remain unverified.

No open issues 🎉

_{Review effort: Balanced}