Repository navigation
Give first-time image preparation its own bounded deadline #3952
Description
User Story
As a user creating a sandbox from an uncached image, I want image preparation to have a documented time budget separate from policy repair, so that a slow first setup can complete without disabling bounded failure handling.
Problem Statement
The first recorded large bootstrap exceeded the gateway's 300-second provisioning repair window before Ready. That window currently includes cold image preparation. It was introduced for durable configuration/admission repair, so increasing the CLI wait would not address this failure.
Impact / Why This Matters
A valid first-time setup can fail while downloading or preparing its image. Users may need to choose a smaller bootstrap or repeat preparation, even though no policy error required repair.
Proposed Design
Expose and persist image preparation as a bounded phase distinct from supervisor admission and policy repair. Show the current phase and reason for timeout. Transition only on trusted progress for the current attempt and preserve an absolute preparation ceiling. After that transition, retain the existing repair-window behavior for real configuration changes. Restarts, duplicate progress and no-op settings writes must not extend preparation indefinitely.
Acceptance Criteria
- A documented reference image can take more than five minutes to prepare within its configured preparation budget and then proceed to admission.
- An invalid policy receives the intended admission repair window rather than time left over from image preparation.
- Stalled preparation expires at its own deadline with an inspectable reason and invokes cleanup.
- Gateway/driver restart, duplicate progress and no-op settings writes do not extend the absolute preparation deadline or revive an expired attempt.
- Real committed configuration changes retain the existing admission repair-window behavior introduced by feat(sandbox): validate configuration before workload activation #3259.
- Deterministic lifecycle tests cover the two phases and their transition without depending on Internet download timing.
Alternatives Considered
Raising the global 300-second constant changes policy-repair behavior for every attempt. Increasing only the CLI wait cannot alter the gateway deadline. Preparing every image manually can avoid a cold create but does not provide a repeatable default setup.
Agent Investigation
No response
Checklist
- I've reviewed existing issues and the published docs
- This is a design proposal, not a "please build this" request
Activity
purp commentedon Sep 30, 2026
feat(server): separate image preparation and admission deadlines
fix(gateway): give image preparation its own deadline (NVIDIA#4038)