Give first-time image preparation its own bounded deadline

[shiju-nv]

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

[purp]

📋 triage-agent

Triage Assessment

Classification: validated-bug

Summary

Reproduced on v0.1.2 with high confidence. A cold create of a large image failed at exactly 300 s while still in Preparing image cache, even though the configuration was valid. The error also tells the user to "repair its configuration", which doesn't apply to this failure.

Investigation

Setup: v0.1.2 release binaries, MicroVM with a valid gateway_jwt, a signed driver, Apple Silicon (macOS 26.7), and --from nvcr.io/nvidia/pytorch:25.08-py3 with an empty cache.

• About 1.4 GB was staged in 300 s, and then: ProvisioningTimedOut: Provisioning repair window expired after 300 seconds … repair its configuration, then run openshell sandbox start.
• On main, one constant REPAIR_WINDOW_MS = 300_000 (crates/openshell-server/src/compute/provisioning_deadline.rs:14) is armed at create (grpc/sandbox.rs:608) and stays armed until Ready. Image preparation has no separate budget.
• The driver already emits ResolvingImage and PreparingRootfs progress events, which could mark the phase transition.
• Related: Sandbox startup exits instead of waiting for repair when the gateway refuses its policy #3784 (policy-repair behavior) and Reclaim inactive image staging after failed or cancelled MicroVM creation #3953 (the staging left behind by this timeout).

Impact Signals

• Affected users/scope: first-time creates of large images on slower links, with an empty VM image cache.
• Regression: unknown. The window was introduced for policy repair (feat(sandbox): validate configuration before workload activation #3259).
• Workaround: partial: retry after cleanup, use a smaller image, or pre-warm the cache.
• Evidence quality: high: live reproduction plus code path.

Disposition

Accepted by @purp on 2026-09-30 as part of the #3955 macOS MicroVM review.