[PR #252] [MERGED] fix(volume): avoid VM snapshots during sandbox deletion

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/252 **Author:** [@yingdi-shan](https://github.com/yingdi-shan) **Created:** 9/7/2026 **Status:** ✅ Merged **Merged:** 9/9/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `fix/volume-delete-without-vm-snapshot` --- ### 📝 Commits (1) - [`027befc`](https://github.com/kvcache-ai/AgentENV/commit/027befc2b4e94355a711f365029993cfe2d94564) fix(volume): delete sandboxes without capturing VM state ### 📊 Changes **15 files changed** (+911 additions, -134 deletions) <details> <summary>View changed files</summary> 📝 `docs/src/concepts/volumes.md` (+10 -0) 📝 `scripts/tests/e2e/suites/15_volume.sh` (+16 -0) 📝 `src/orchestrator/service.rs` (+147 -80) 📝 `src/orchestrator/tests.rs` (+250 -11) 📝 `src/sandbox/backend.rs` (+12 -0) 📝 `src/sandbox/extra_drive.rs` (+10 -1) 📝 `src/sandbox/firecracker/overlaybd_snapshot.rs` (+6 -4) 📝 `src/sandbox/firecracker/sandbox.rs` (+133 -2) 📝 `src/sandbox/mock.rs` (+29 -2) 📝 `src/sandbox/process.rs` (+72 -31) 📝 `src/sandbox/ublk/device.rs` (+1 -1) 📝 `src/volume.rs` (+17 -0) 📝 `storage/ublk-daemon/src/client.rs` (+36 -2) 📝 `storage/ublk-daemon/tests/ublk_daemon_test.rs` (+2 -0) 📝 `tests/integration/snapshot_attached_drive.rs` (+170 -0) </details> ### 📄 Description ## What Delete sandboxes with mounted volumes by freezing the writable filesystems, sealing and publishing their layers, and stopping the VM. Deletion no longer captures disposable memory, rootfs, or VM state. ## Why The existing deletion path pauses the entire sandbox to preserve volume writes. A volume-only checkpoint avoids that work and leaves a clean filesystem journal for the next mount. ## Related issue Extracted from #247 alongside #253 (OCI UID/GID startup) and #254 (BuildKit). The layer-reuse optimization in #249 remains separate. ## Scope and non-goals Mounted-volume deletion, timeout eviction, failure recovery, regression tests, and volume documentation. BuildKit integration and OCI UID/GID resolution are submitted separately. ## Design and behavior changes - Keep volume reservations until publication succeeds and the VM stops. - Thaw and restore the original runtime after recoverable capture or publication failures. Terminal failures tear down the runtime and its persisted state. - Bound freeze/thaw RPCs and check mountpoints before freezing, so an unmounted path cannot freeze the guest root filesystem. - Explicit pause and graceful shutdown continue to save resumable VM state. ## Compatibility and operations - Public API or generated protocol: unchanged; the internal sandbox backend gains freeze/thaw operations. - Configuration or defaults: unchanged. - Snapshot manifest, artifact layout, or storage format: unchanged. - Upgrade and rollback: no migration required. - Host requirements, permissions, ports, or dependencies: existing Firecracker, ublk, and guest BusyBox requirements. ## Validation - [x] `make fmt` - [x] `make clippy` - [x] `make test-unit` - [x] Relevant Rust integration tests - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text make fmt clippy: passed make test-unit: passed, including capability and ublk checks cargo test -p agentenv --test integration frozen_volumes_survive_deletion_without_vm_snapshot -- --nocapture: passed git diff --check: passed ``` The VM test passed with multiple volumes, recovery after a partial freeze failure, thaw/reseal, subPath mounts, a non-root default user, and dirty-file preservation in a replacement VM. It ran as a non-root user through the repository capability runner with isolated state and dependency copies. No timing benchmark was run; the regression tests verify that deletion does not invoke a full VM pause/snapshot. Go and generated API checks do not apply. ## Risks and reviewer notes Review deletion ordering in `src/orchestrator/service.rs` and freeze recovery in `src/sandbox/firecracker/sandbox.rs`. Filesystem freezing flushes filesystem state; application buffers still require application-level coordination. Guest root-selection helpers overlap identically with the OCI startup fix and merge cleanly. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by focused regression tests. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] No generated code was manually edited. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi commented

2026-10-29 14:21:54 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/252
Author: @yingdi-shan
Created: 9/7/2026
Status: ✅ Merged
Merged: 9/9/2026
Merged by: @yingdi-shan

Base: main ← Head: fix/volume-delete-without-vm-snapshot

📝 Commits (1)

027befc fix(volume): delete sandboxes without capturing VM state

📊 Changes

15 files changed (+911 additions, -134 deletions)

View changed files

📝 docs/src/concepts/volumes.md (+10 -0)
📝 scripts/tests/e2e/suites/15_volume.sh (+16 -0)
📝 src/orchestrator/service.rs (+147 -80)
📝 src/orchestrator/tests.rs (+250 -11)
📝 src/sandbox/backend.rs (+12 -0)
📝 src/sandbox/extra_drive.rs (+10 -1)
📝 src/sandbox/firecracker/overlaybd_snapshot.rs (+6 -4)
📝 src/sandbox/firecracker/sandbox.rs (+133 -2)
📝 src/sandbox/mock.rs (+29 -2)
📝 src/sandbox/process.rs (+72 -31)
📝 src/sandbox/ublk/device.rs (+1 -1)
📝 src/volume.rs (+17 -0)
📝 storage/ublk-daemon/src/client.rs (+36 -2)
📝 storage/ublk-daemon/tests/ublk_daemon_test.rs (+2 -0)
📝 tests/integration/snapshot_attached_drive.rs (+170 -0)

📄 Description

What

Delete sandboxes with mounted volumes by freezing the writable filesystems, sealing and publishing their layers, and stopping the VM. Deletion no longer captures disposable memory, rootfs, or VM state.

Why

The existing deletion path pauses the entire sandbox to preserve volume writes. A volume-only checkpoint avoids that work and leaves a clean filesystem journal for the next mount.

Extracted from #247 alongside #253 (OCI UID/GID startup) and #254 (BuildKit). The layer-reuse optimization in #249 remains separate.

Scope and non-goals

Mounted-volume deletion, timeout eviction, failure recovery, regression tests, and volume documentation. BuildKit integration and OCI UID/GID resolution are submitted separately.

Design and behavior changes

Keep volume reservations until publication succeeds and the VM stops.
Thaw and restore the original runtime after recoverable capture or publication failures. Terminal failures tear down the runtime and its persisted state.
Bound freeze/thaw RPCs and check mountpoints before freezing, so an unmounted path cannot freeze the guest root filesystem.
Explicit pause and graceful shutdown continue to save resumable VM state.

Compatibility and operations

Public API or generated protocol: unchanged; the internal sandbox backend gains freeze/thaw operations.
Configuration or defaults: unchanged.
Snapshot manifest, artifact layout, or storage format: unchanged.
Upgrade and rollback: no migration required.
Host requirements, permissions, ports, or dependencies: existing Firecracker, ublk, and guest BusyBox requirements.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

make fmt clippy: passed
make test-unit: passed, including capability and ublk checks
cargo test -p agentenv --test integration frozen_volumes_survive_deletion_without_vm_snapshot -- --nocapture: passed
git diff --check: passed

The VM test passed with multiple volumes, recovery after a partial freeze failure, thaw/reseal, subPath mounts, a non-root default user, and dirty-file preservation in a replacement VM. It ran as a non-root user through the repository capability runner with isolated state and dependency copies. No timing benchmark was run; the regression tests verify that deletion does not invoke a full VM pause/snapshot. Go and generated API checks do not apply.

Risks and reviewer notes

Review deletion ordering in src/orchestrator/service.rs and freeze recovery in src/sandbox/firecracker/sandbox.rs. Filesystem freezing flushes filesystem state; application buffers still require application-level coordination. Guest root-selection helpers overlap identically with the OCI startup fix and merge cleanly.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by focused regression tests.
Logs and examples contain no credentials, tokens, or private registry information.
No generated code was manually edited.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

bsakaguchi