feat(providers): recommend warm starts

Author: vincentkoc

CHANGELOG.md

@@ -11,6 +11,7 @@
 - Added `crabbox providers recommend offline-validation` for credentialless local, BYO SSH, and external-provider validation guidance.
 - Added normalized provider lifecycle capabilities and `--lifecycle` filters to `crabbox providers` and `crabbox providers recommend`.
 - Added `crabbox providers recommend failure-diagnostics` for failed-run triage guidance across proof, session, artifact, download, preview, and SSH-debuggable providers.
+- Added `crabbox providers recommend warm-start` for low-latency repeated-run guidance across local runtimes, cache volumes, retained sessions, pause/resume, and workspace-state providers.
 
 ### Fixed
 

docs/commands/providers.md

@@ -125,6 +125,7 @@ crabbox providers recommend run-session
 crabbox providers recommend team-cloud
 crabbox providers recommend workspace-reuse
 crabbox providers recommend versioned-workspace
+crabbox providers recommend warm-start
 crabbox providers recommend forkable-workspace --workspace fork
 crabbox providers recommend versioned-workspace --target macos --workspace fork
 crabbox providers recommend worker-runtime --json
@@ -192,6 +193,11 @@ Supported use cases:
 - `versioned-workspace`: providers with native checkpoint, fork, restore, or
   snapshot-reference capabilities. Aliases include `workspace-reuse`,
   `forkable-workspace`, `durable-workspace`, and `stateful-workspace`.
+- `warm-start`: providers with local runtimes, reusable cache volumes, retained
+  sessions, pause/resume, or workspace-state features that can reduce repeated
+  setup overhead. Aliases include `warm-pool`, `prewarm`, and
+  `low-latency-start`. This is provider selection guidance over existing
+  reuse signals, not a guarantee of native warm-pool APIs.
 - `windows`: native Windows and WSL2 targets.
 - `worker-runtime`: Worker/module-runtime execution.
 

docs/features/provider-landscape.md

@@ -138,6 +138,9 @@ Ship these in small PRs:
    cloud API-backed leases.
    Use `crabbox providers recommend pause-resume` when long-running sandbox or
    dev-environment state needs to be parked and resumed.
+   Use `crabbox providers recommend warm-start` when repeated runs should
+   prefer local runtimes, reusable caches, retained sessions, pause/resume, or
+   workspace-state signals before paying remote cold-start cost.
 4. Strengthen workspace reuse before runtime-specific forking.
    Checkpoint, fork, restore, and provider snapshot semantics should be testable
    through the CLI before adding live microVM fan-out. Use

internal/cli/providers.go

@@ -470,6 +470,7 @@ func providerRecommendationUseCases() []string {
 		"self-hosted",
 		"team-cloud",
 		"versioned-workspace",
+		"warm-start",
 		"windows",
 		"worker-runtime",
 	}
@@ -555,6 +556,10 @@ func normalizeProviderRecommendationUseCase(value string) (string, bool) {
 		"forkable-workspaces", "durable-workspace", "stateful-workspace",
 		"snapshot-fork":
 		return "versioned-workspace", true
+	case "warm-start", "warm", "warmup", "warm-up", "warm-pool", "warm-pools",
+		"prewarm", "pre-warm", "prewarmed", "pre-warmed", "low-latency-start",
+		"low-latency", "reuse-state", "reuse-runtime":
+		return "warm-start", true
 	case "windows", "win":
 		return "windows", true
 	case "worker", "worker-runtime", "module", "module-run":
@@ -1251,6 +1256,44 @@ func scoreProviderRecommendation(entry providerMatrixEntry, useCase string) (int
 		if hasFeature(FeatureCleanup) {
 			add(8, "can clean up provider-owned workspace resources")
 		}
+	case "warm-start":
+		hasWarmSignal := hasFeature(FeatureCacheVolume) || hasFeature(FeatureRunSession) ||
+			hasFeature(FeaturePauseResume) || hasFeature(FeatureCheckpoint) ||
+			hasFeature(FeatureFork) || hasFeature(FeatureRestore) ||
+			hasFeature(FeatureSnapshot) || strings.HasPrefix(category, "local-")
+		if !hasWarmSignal {
+			break
+		}
+		if strings.HasPrefix(category, "local-") {
+			add(45, "local runtime avoids cloud cold starts")
+		}
+		if hasFeature(FeatureCacheVolume) {
+			add(35, "can reuse dependency/cache volumes")
+		}
+		if hasFeature(FeatureRunSession) {
+			add(30, "can reuse retained run sessions")
+		}
+		if hasFeature(FeaturePauseResume) {
+			add(28, "can pause and resume warm runtime state")
+		}
+		if hasFeature(FeatureCheckpoint) || hasFeature(FeatureFork) || hasFeature(FeatureRestore) || hasFeature(FeatureSnapshot) {
+			add(25, "can reuse prepared workspace state")
+		}
+		if hasFeature(FeatureCrabboxSync) || hasFeature(FeatureArchiveSync) {
+			add(16, "can seed warm state from the current checkout")
+		}
+		if category == "ci-proof-runner" {
+			add(14, "CI proof runner is optimized for repeated validation loops")
+		}
+		if hasFeature(FeatureCleanup) {
+			add(12, "can clean up warm-start resources")
+		}
+		if hasFeature(FeatureRunProof) || hasFeature(FeatureRunArtifacts) || hasFeature(FeatureRunDownloads) {
+			add(8, "can retain evidence without keeping every run hot")
+		}
+		if hasTarget(targetLinux) || hasTarget(targetWorkerRuntime) {
+			add(6, "supports common warm-start targets")
+		}
 	case "windows":
 		if hasTarget(targetWindows + "/" + WindowsModeNormal) {
 			add(80, "supports native Windows")
@@ -1340,6 +1383,7 @@ func printProviderRecommendationUseCases(out io.Writer) {
 	fmt.Fprintln(out, "  crabbox providers recommend run-session")
 	fmt.Fprintln(out, "  crabbox providers recommend team-cloud")
 	fmt.Fprintln(out, "  crabbox providers recommend versioned-workspace")
+	fmt.Fprintln(out, "  crabbox providers recommend warm-start")
 	fmt.Fprintln(out, "  crabbox providers recommend forkable-workspace --workspace fork")
 }
 

internal/cli/providers_test.go

@@ -511,6 +511,7 @@ func TestProvidersRecommendListsUseCases(t *testing.T) {
 		"run-session",
 		"team-cloud",
 		"versioned-workspace",
+		"warm-start",
 		"worker-runtime",
 	} {
 		if !strings.Contains(text, want) {
@@ -738,6 +739,64 @@ func TestProvidersRecommendFailureDiagnosticsPrefersInspectableEvidence(t *testi
 	}
 }
 
+func TestProvidersRecommendWarmStartPrefersReusableState(t *testing.T) {
+	recommendations := recommendProvidersForUseCase(providerMatrix(), "warm-start", 12)
+	if len(recommendations) == 0 {
+		t.Fatal("expected warm-start recommendations")
+	}
+	if recommendations[0].Provider != "local-container" && recommendations[0].Provider != "parallels" {
+		t.Fatalf("top warm-start provider=%q recommendations=%v", recommendations[0].Provider, recommendations)
+	}
+	foundCache := false
+	foundSession := false
+	foundPause := false
+	foundWorkspaceState := false
+	foundLocalRuntime := false
+	for _, recommendation := range recommendations {
+		hasCache := providerRecommendationHasFeature(recommendation.Features, FeatureCacheVolume)
+		hasSession := providerRecommendationHasFeature(recommendation.Features, FeatureRunSession)
+		hasPause := providerRecommendationHasFeature(recommendation.Features, FeaturePauseResume)
+		hasWorkspaceState := providerRecommendationHasFeature(recommendation.Features, FeatureCheckpoint) ||
+			providerRecommendationHasFeature(recommendation.Features, FeatureFork) ||
+			providerRecommendationHasFeature(recommendation.Features, FeatureRestore) ||
+			providerRecommendationHasFeature(recommendation.Features, FeatureSnapshot)
+		hasLocalRuntime := strings.HasPrefix(recommendation.Category, "local-")
+		if !hasCache && !hasSession && !hasPause && !hasWorkspaceState && !hasLocalRuntime {
+			t.Fatalf("warm-start recommendation lacks warm-state signal: %#v", recommendation)
+		}
+		foundCache = foundCache || hasCache
+		foundSession = foundSession || hasSession
+		foundPause = foundPause || hasPause
+		foundWorkspaceState = foundWorkspaceState || hasWorkspaceState
+		foundLocalRuntime = foundLocalRuntime || hasLocalRuntime
+	}
+	if !foundCache || !foundSession || !foundPause || !foundWorkspaceState || !foundLocalRuntime {
+		t.Fatalf("warm-start should include cache, session, pause/resume, workspace-state, and local-runtime signals: %#v", recommendations)
+	}
+}
+
+func TestProvidersRecommendWarmPoolAlias(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := (App{Stdout: &stdout, Stderr: &stderr}).providers(context.Background(), []string{
+		"recommend", "warm-pool",
+		"--limit", "1",
+		"--json",
+	})
+	if err != nil {
+		t.Fatalf("providers recommend warm-pool error=%v stderr=%q", err, stderr.String())
+	}
+	var entries []providerRecommendationEntry
+	if err := json.Unmarshal(stdout.Bytes(), &entries); err != nil {
+		t.Fatalf("invalid json: %v\n%s", err, stdout.String())
+	}
+	if len(entries) != 1 {
+		t.Fatalf("warm-pool alias entries=%#v", entries)
+	}
+	if entries[0].Provider != "local-container" && entries[0].Provider != "parallels" {
+		t.Fatalf("warm-pool alias should prefer local reusable state providers: %#v", entries)
+	}
+}
+
 func TestProvidersRecommendFailedRunAlias(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	err := (App{Stdout: &stdout, Stderr: &stderr}).providers(context.Background(), []string{