fix(setup): explain WSL platform install failures

After an elevated WSL install fails, run a best-effort GitHub quota diagnostic and distinguish likely quota exhaustion from other download failures. Diagnostic timeouts never replace the original failure.

Offer Store, winget, and elevated PowerShell recovery routes, and allow the platform step to be retried.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Signed-off-by: Joel Fernandes <joelagnelf@nvidia.com>

Author: RomneyDa

src/OpenClaw.SetupEngine/PreflightWslStep.cs

@@ -221,7 +221,10 @@ internal static async Task<StepResult> InstallWslPlatformAsync(SetupContext ctx,
                 return StepResult.Terminal("WSL platform install requires a restart. Reboot Windows, then run setup again.");
 
             if (process.ExitCode != 0)
-                return StepResult.Fail($"WSL platform install failed with exit code {process.ExitCode}.");
+            {
+                GitHubApiQuota? quota = await WslPlatformInstallDiagnostics.QueryGitHubQuotaAsync(ct);
+                return StepResult.Fail(WslPlatformInstallDiagnostics.DescribeFailure(process.ExitCode, quota));
+            }
 
             var probe = await ctx.Commands.RunAsync(
                 WslConstants.WslExePath,
@@ -240,6 +243,10 @@ internal static async Task<StepResult> InstallWslPlatformAsync(SetupContext ctx,
         {
             return StepResult.Fail("WSL platform install was cancelled at the elevation prompt.");
         }
+        catch (OperationCanceledException) when (ct.IsCancellationRequested)
+        {
+            throw;
+        }
         catch (Exception ex)
         {
             return StepResult.Fail($"WSL platform install failed: {ex.Message}", ex);
@@ -266,7 +273,7 @@ internal EnsureWslPlatformStep(
 
     public override string Id => "ensure-wsl-platform";
     public override string DisplayName => "Prepare WSL platform";
-    public override bool CanRetry => false;
+    public override bool CanRetry => true;
 
     public override async Task<StepResult> ExecuteAsync(SetupContext ctx, CancellationToken ct)
     {

src/OpenClaw.SetupEngine/WslPlatformInstallDiagnostics.cs

@@ -0,0 +1,67 @@
+using System.Text.Json;
+
+namespace OpenClaw.SetupEngine;
+
+internal sealed record GitHubApiQuota(int Limit, int Remaining, DateTimeOffset ResetsAt)
+{
+    public bool IsExhausted => Remaining <= 0;
+    public int Used => Math.Max(0, Limit - Remaining);
+}
+
+internal static class WslPlatformInstallDiagnostics
+{
+    private const string RateLimitUrl = "https://api.github.com/rate_limit";
+    private const string WslStoreProductId = "9P9TQF7MRM4R";
+
+    public static string SelfInstallInstructions =>
+        "Install WSL yourself, then run setup again:" + Environment.NewLine +
+        $"  Microsoft Store: {WslInstallSupport.UpdateUrl}" + Environment.NewLine +
+        $"  Or run: winget install --id {WslStoreProductId} --source msstore" + Environment.NewLine +
+        "  Or, in elevated PowerShell: wsl --install --no-distribution" + Environment.NewLine +
+        "Reboot if Windows asks for one.";
+
+    public static string DescribeFailure(int exitCode, GitHubApiQuota? quota)
+    {
+        string reason = quota is { IsExhausted: true }
+            ? $"The WSL installer may need GitHub, and this network's unauthenticated API quota " +
+              $"is exhausted ({quota.Used}/{quota.Limit}) until {quota.ResetsAt.ToLocalTime():HH:mm}."
+            : "The WSL download did not complete. A network, policy, or installer error may be blocking it.";
+
+        return $"WSL platform install failed with exit code {exitCode}. {reason}" +
+            Environment.NewLine + Environment.NewLine + SelfInstallInstructions;
+    }
+
+    public static async Task<GitHubApiQuota?> QueryGitHubQuotaAsync(CancellationToken ct)
+    {
+        using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(5) };
+        return await QueryGitHubQuotaAsync(http, ct);
+    }
+
+    internal static async Task<GitHubApiQuota?> QueryGitHubQuotaAsync(HttpClient http, CancellationToken ct)
+    {
+        try
+        {
+            using var request = new HttpRequestMessage(HttpMethod.Get, RateLimitUrl);
+            request.Headers.UserAgent.ParseAdd("OpenClawSetup");
+            using var response = await http.SendAsync(request, ct);
+            if (!response.IsSuccessStatusCode)
+                return null;
+
+            await using var body = await response.Content.ReadAsStreamAsync(ct);
+            using var json = await JsonDocument.ParseAsync(body, cancellationToken: ct);
+            JsonElement core = json.RootElement.GetProperty("resources").GetProperty("core");
+            return new(
+                core.GetProperty("limit").GetInt32(),
+                core.GetProperty("remaining").GetInt32(),
+                DateTimeOffset.FromUnixTimeSeconds(core.GetProperty("reset").GetInt64()));
+        }
+        catch (OperationCanceledException) when (!ct.IsCancellationRequested)
+        {
+            return null;
+        }
+        catch (Exception ex) when (ex is not OperationCanceledException)
+        {
+            return null;
+        }
+    }
+}

tests/OpenClaw.SetupEngine.Tests/WslPlatformInstallDiagnosticsTests.cs

@@ -0,0 +1,63 @@
+using System.Net;
+
+namespace OpenClaw.SetupEngine.Tests;
+
+public class WslPlatformInstallDiagnosticsTests
+{
+    [Theory]
+    [InlineData(0, true)]
+    [InlineData(10, false)]
+    public void DescribeFailure_ExplainsCauseAndRecovery(int remaining, bool exhausted)
+    {
+        var quota = new GitHubApiQuota(60, remaining, DateTimeOffset.UtcNow.AddMinutes(10));
+
+        string message = WslPlatformInstallDiagnostics.DescribeFailure(1, quota);
+
+        Assert.Contains("exit code 1", message);
+        Assert.Equal(exhausted, message.Contains("quota is exhausted", StringComparison.OrdinalIgnoreCase));
+        Assert.Contains(WslInstallSupport.UpdateUrl, message);
+        Assert.Contains("winget install --id 9P9TQF7MRM4R --source msstore", message);
+        Assert.Contains("wsl --install --no-distribution", message);
+    }
+
+    [Fact]
+    public void DescribeFailure_UnknownQuota_DoesNotClaimRateLimit()
+    {
+        string message = WslPlatformInstallDiagnostics.DescribeFailure(5, quota: null);
+
+        Assert.Contains("network, policy, or installer error", message);
+        Assert.DoesNotContain("quota is exhausted", message);
+    }
+
+    [Fact]
+    public async Task QueryGitHubQuota_TimeoutIsBestEffort()
+    {
+        using var http = new HttpClient(new DelayedHandler()) { Timeout = TimeSpan.FromMilliseconds(20) };
+
+        Assert.Null(await WslPlatformInstallDiagnostics.QueryGitHubQuotaAsync(http, CancellationToken.None));
+    }
+
+    [Fact]
+    public async Task QueryGitHubQuota_CallerCancellationPropagates()
+    {
+        using var http = new HttpClient(new DelayedHandler());
+        using var cts = new CancellationTokenSource(TimeSpan.FromMilliseconds(20));
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(() =>
+            WslPlatformInstallDiagnostics.QueryGitHubQuotaAsync(http, cts.Token));
+    }
+
+    [Fact]
+    public void EnsureWslPlatform_IsRetryable() => Assert.True(new EnsureWslPlatformStep().CanRetry);
+
+    private sealed class DelayedHandler : HttpMessageHandler
+    {
+        protected override async Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            await Task.Delay(TimeSpan.FromSeconds(10), cancellationToken);
+            return new(HttpStatusCode.OK);
+        }
+    }
+}