fix(vm): bind cached registry images to verified manifest digests

[alangou]

Summary

Bind VM registry downloads to the manifest digest used for the image cache identity. Resolving a tag and then pulling it independently could cache different image contents under the resolved digest; both VM registry preparation paths now pull through an immutable digest reference and reject mismatched manifest bytes before downloading blobs.

Related Issue

None.

Changes

• Resolve tags once and preserve caller-supplied digest pins for bootstrap and prepared-image downloads, including retries.
• Use the existing OCI client's byte verification for single manifests, multi-platform indexes, and selected platform manifests.
• Advance bootstrap cache layout to v6 and prepared-image layout to v4 so new preparations do not reuse older entries. Hash source identities to keep cache and staging filenames bounded for longer digests such as SHA-512.
• Add seven loopback registry tests covering mismatches, tag changes, retries, index children, forged headers, explicit pins, and SHA-512 compatibility. Document cache rebuilding on upgrade.

Testing

• VM driver suite passes serially: 250 tests, including all seven new registry tests.
• Both manifest/cache identity mismatch regressions failed against the original implementation and pass with the fix.
• VM driver Clippy, Rust formatting, and diff checks pass.
• Published documentation checks pass: zero errors, three warnings.
• VM boot E2E was not run locally: this environment has no /dev/kvm. The test:e2e label requests the repository's core E2E lane.

The parallel VM unit suite hits driver::preparation::tests::restart_reclaims_inactive_attempts_and_preserves_active_shared_and_unknown_data; the same failure was reproduced on the unmodified baseline. The complete serial suite passes. Registry tests validate manifest verification and staging without booting a VM; successful-manifest cases deliberately stop at a missing blob response.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Relevant driver README and published runtime documentation updated

[github-actions]

Label test:e2e applied for 78e65a8. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4342.docs.buildwithfern.com/openshell

[alangou]

gator-agent

Maintainer Approval Needed

Gator completed its independent code review of the VM registry cache fix and found no blocking findings. Required checks are green on the current head, including core E2E and both managed and external VM E2E paths.

Action required: a maintainer should review and approve this PR.

Gator metadata

• Validation: Concentrated VM-driver correctness fix that binds registry downloads to immutable manifest digests and prevents older unverified cache entries from being reused.
• Review: Full initial patch reviewed; no findings or carried obligations.
• Docs: Driver README and published runtime documentation explain digest verification and cache rebuilding.
• Checks: OpenShell / Branch Checks, OpenShell / Helm Lint, OpenShell / Trivy Changes, DCO, and vouch are green on the current head.
• E2E: test:e2e; OpenShell / E2E and managed/external VM E2E passed. The earlier label rerun hint is satisfied by the completed current-head run.
• Approval: No maintainer approval is present.
• Head SHA: 78e65a89418bf9fbf732562630d9347b5906dbff
• Base SHA: 0e981be906ef34b26464b39a7de49e1f7823b697
• Merge base SHA: 67adcf1a3cf054be54dfdbf6a44c65b4d426b1ec
• Patch ID: 594d1dc9190d53c7791047de2595cb435751604f
• Gator payload: 12
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:approval-needed

[alangou]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: Gator review found no blocking findings, and the last recorded required checks and E2E results passed.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.

Gator metadata

• Head SHA: 78e65a89418bf9fbf732562630d9347b5906dbff
• Gator payload: 12