feat(fleet): poll async sandbox preparation

Merged
KH
8d ago
+2226-44

Merge order (with cloud #4137)

  • Cloud first is safe: deploy cloud #4137 (async-v1 preparation), then merge this.
  • Relay first is also safe as of 5e51d9a95: against a Cloud without async-v1, the client accepts the synchronous 201, retries once without preparationMode on a 400 field rejection, and parses a typed 5xx (relayfile_mount_failed, sandbox_capacity_exhausted) immediately instead of polling a status route that does not exist. Before that commit, relay-before-cloud reproduced the smoke-B outcome-unknown shape.
  • Generated sandbox identities are printed so an interrupted spawn can be resumed with --sandbox-id; persisting them and Ctrl-C reconciliation are tracked in #1925.

Closes AgentWorkforce/cloud#4126

Summary

  • opts replay-safe Agent37 fleet spawns into Cloud async-v1 preparation
  • polls durable status with bounded requests and never replays a lost phase-advance response before reconciliation
  • preserves exact cleanup identity and surfaces authentication, cancellation, malformed-ready, and identity-mismatch failures safely

Verification

  • 204 focused async preparation and CLI regression tests
  • monorepo typecheck
  • Prettier and diff checks

🤖 Generated with Claude Code

[!NOTE]
Medium Risk
Changes core fleet sandbox provisioning, polling, and error/cleanup semantics across CLI and cloud client; extensive tests mitigate regressions but behavior under partial Cloud upgrades and network loss is complex.

Overview
fleet spawn --sandbox (unpinned or Agent37) now provisions through Cloud’s durable async-v1 flow instead of one long blocking ensure: the CLI prints the generated sbx_ identity up front (resume with --sandbox-id), streams preparation phase warnings via onPreparationProgress, and passes preparationMode: 'async-v1' into @agent-relay/cloud.

ensureCloudFleetSandbox implements the client contract: phase polling on /preparation (GET/POST), Retry-After pacing, reconciliation after dropped ensure/advance responses without replaying ensure or blind advances, and typed terminal failures (sandboxAbsent, preparationFailure with code/phase/causeStage). Older Cloud still works via synchronous 201, a one-shot retry when preparationMode is rejected, and immediate handling of typed 5xx (e.g. relayfile_mount_failed, capacity) without status polling.

Terminal prep failures skip redundant deleteCloudFleetSandbox when Cloud confirms no sandbox is running.

Reviewed by Cursor Bugbot for commit 5e51d9a95f7bf0361ee83669518cfc13af224c6b. Bugbot is set up for automated code reviews on this repo. Configure here.

Agent Relay sessions

  • codex session 01a0fc15 · opened via gh pr create · last active 2026-10-02