Enforce sparse-only guest directory copy

[sjmiller609]

Summary

• switch CopyGuestDirectory to skip logs/runtime sockets, rely on sparse extent copying, and propagate ErrSparseCopyUnsupported
• ensure forks fail fast when SEEK_DATA/SEEK_HOLE are unavailable and surface a clearer error path plus updated readiness probe handling
• add sparse-block tests for successful copy, skip logic, and unsupported platforms, along with docs on the requirements

Testing

• existing integration tests cover it

---

Note

Medium Risk
Changes the on-disk cloning path used by instance forks and introduces a hard requirement on filesystem sparse-seek support, which could break forks on some environments. Sparse extent copying and new readiness probes may surface previously hidden edge cases in fork/restore timing.

Overview
Fork cloning now preserves sparsity and skips runtime artifacts. CopyGuestDirectory switches from dense io.Copy to sparse extent copying via SEEK_DATA/SEEK_HOLE, skips the logs/ subtree (entirely) and continues skipping runtime socket files.

Forks now fail explicitly when sparse seeking isn’t available. A new forkvm.ErrSparseCopyUnsupported is returned on unsupported filesystems/platforms and instances.forkInstanceFromStoppedOrStandby surfaces a clearer “sparse-capable filesystem required” error.

Improved fork/exec readiness checks and tests. Guest-agent readiness probing is refactored/reused and ForkInstance now waits for the agent before returning a running fork; tests are updated/added to validate sparse preservation, skip behavior, and the unsupported-sparse error path, and docs describe the new copy requirements.

^{Written by Cursor Bugbot for commit 30c2676. This will update automatically on new commits. Configure here.}

[cursor]

Risk assessment: Medium-High.

I evaluated the risk from the code diff itself (not PR narrative). This change modifies fork-critical runtime behavior in shared paths:

• switches guest directory copy to sparse-only extent logic (SEEK_DATA/SEEK_HOLE) with new platform-dependent failure behavior
• changes what guest artifacts are copied (skips logs directory)
• alters readiness checks and error handling in fork flow for running instances

Given the production behavioral impact, platform/filesystem dependencies, and performance-sensitive codepath, this requires human review before merge.

Actions taken:

• requested reviewers: @rgarcia, @hiroTamada
• no approval issued

---

  

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}