fix(run): wait for image to be ready before creating instance

[rgarcia]

Problem

The CLI was immediately attempting to create an instance after calling POST /images, which returns 202 Accepted with status: pending. Since image builds are asynchronous, the instance creation would fail with image_not_ready error.

This caused a race condition where the first hypeman run debian:12 would fail (retrying 3 times), but a second run would succeed after the background build completed.

Solution

Added polling logic to wait for the image status to become ready (or failed) before proceeding to create the instance.

Status updates are shown to the user as the image progresses through build stages:

• Queued... (pending)
• Pulling image... (pulling)
• Converting to disk image... (converting)
• Image ready. (ready)

Testing

# Delete any existing debian:12 image first, then:
./hypeman run debian:12

Should now show progress and wait for the image to be ready before creating the instance.

[mesa-dot-dev]

Mesa Description

Problem

The CLI was immediately attempting to create an instance after calling POST /images, which returns 202 Accepted with status: pending. Since image builds are asynchronous, the instance creation would fail with image_not_ready error.

This caused a race condition where the first hypeman run debian:12 would fail (retrying 3 times), but a second run would succeed after the background build completed.

Solution

Added polling logic to wait for the image status to become ready (or failed) before proceeding to create the instance.

Status updates are shown to the user as the image progresses through build stages:

• Queued... (pending)
• Pulling image... (pulling)
• Converting to disk image... (converting)
• Image ready. (ready)

Implementation Details

The run command in pkg/cmd/run.go has been updated to handle image pulling and building asynchronously. It now polls the image status, providing real-time feedback to the user until the image is ready.

Security Impact

Testing

# Delete any existing debian:12 image first, then:
./hypeman run debian:12

Should now show progress and wait for the image to be ready before creating the instance.

^{Description generated by Mesa. Update settings}

[mesa-dot-dev]

Performed full review of 9d7cf81...048ee73

Analysis

1. Unbounded Polling Risk: The waitForImageReady function lacks a timeout or retry limit, potentially causing the CLI to poll indefinitely if an image build stalls in a non-terminal state. This could be problematic for automated scripts, unaware users, or backend issues.

2. Polling Efficiency Concerns: The fixed 1-second polling interval may be too aggressive for long-running image builds, potentially causing unnecessary API load. Consider implementing exponential backoff or configurable intervals.

3. Inconsistent Error Handling: Early status checks return errors without showing initial status information, which could confuse users about failure reasons. Additional user feedback would improve clarity when polling is skipped.

Tip

Help

Slash Commands:

• /review - Request a full code review
• /review latest - Review only changes since the last review
• /describe - Generate PR description. This will update the PR body or issue comment depending on your configuration
• /help - Get help with Mesa commands and configuration options

^{1 files reviewed | 0 comments | Edit Agent Settings • Read Docs}