Guard first-run bootstrap for existing workspaces

Fail closed when an existing gateway is configured but workspace-state probing is inconclusive, so first-run bootstrap does not overwrite an established workspace. Use the active SettingsManager directory for legacy identity detection and add regression coverage for timeout/failure paths.

Author: github-actions[bot]

src/OpenClaw.Tray.WinUI/Pages/ChatPage.xaml.cs

@@ -496,12 +496,14 @@ private async Task NavigateWhenChatReadyAsync(
             }
 
             WaitingStatusText.Text = LocalizationHelper.GetString("ChatPage_ChatReady");
+            var app = (App)Application.Current;
             var bootstrapped = await OnboardingChatBootstrapper.BootstrapAsync(
                 connectionManager?.OperatorClient,
-                ((App)Application.Current).Settings,
+                app.Settings,
                 TimeSpan.FromSeconds(90),
-                cancellationToken).ConfigureAwait(true);
-            if (!bootstrapped && !((App)Application.Current).Settings.HasInjectedFirstRunBootstrap)
+                cancellationToken,
+                registry: app.Registry).ConfigureAwait(true);
+            if (!bootstrapped && !app.Settings.HasInjectedFirstRunBootstrap)
             {
                 Logger.Warn("[ChatPage] Gateway hatching bootstrap did not complete; navigating to empty chat");
             }

src/OpenClaw.Tray.WinUI/Services/OnboardingChatBootstrapper.cs

@@ -1,6 +1,8 @@
+using OpenClaw.Connection;
 using OpenClaw.Shared;
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
@@ -10,6 +12,22 @@ namespace OpenClawTray.Services;
 public static class OnboardingChatBootstrapper
 {
     private static int s_inFlight;
+    private static readonly TimeSpan ExistingWorkspaceProbeTimeout = TimeSpan.FromSeconds(3);
+    private static readonly HashSet<string> ExistingWorkspaceMarkerFiles = new(StringComparer.Ordinal)
+    {
+        "SOUL.md",
+        "IDENTITY.md",
+        "USER.md",
+        "HEARTBEAT.md",
+        "MEMORY.md",
+    };
+
+    private enum ExistingWorkspaceState
+    {
+        Unknown,
+        Empty,
+        Existing,
+    }
 
     public const string Message =
         "Hi! I just installed OpenClaw and you're my brand-new agent. " +
@@ -36,14 +54,47 @@ public static async Task<bool> BootstrapAsync(
         IOperatorGatewayClient? client,
         SettingsManager settings,
         TimeSpan? completionTimeout = null,
-        CancellationToken cancellationToken = default)
+        CancellationToken cancellationToken = default,
+        GatewayRegistry? registry = null,
+        TimeSpan? existingWorkspaceProbeTimeout = null)
     {
         ArgumentNullException.ThrowIfNull(settings);
 
         if (settings.HasInjectedFirstRunBootstrap)
             return true;
+
         if (client == null || !client.IsConnectedToGateway)
             return false;
+
+        // A saved gateway credential is not enough to suppress hatching: fresh local setup
+        // creates registry-backed credentials before the first-run prompt has been sent.
+        // Only consume the gate when the connected workspace already contains durable
+        // OpenClaw state that the bootstrap ritual would otherwise rewrite.
+        if (registry is not null &&
+            SetupExistingGatewayClassifier.HasAnyExistingGatewayConnection(
+                registry,
+                settings,
+                settings.SettingsDirectory))
+        {
+            var workspaceState = await ProbeExistingWorkspaceStateAsync(
+                client,
+                existingWorkspaceProbeTimeout ?? ExistingWorkspaceProbeTimeout,
+                cancellationToken).ConfigureAwait(true);
+
+            if (workspaceState == ExistingWorkspaceState.Existing)
+            {
+                MarkBootstrapped(settings);
+                Logger.Info("[OnboardingChatBootstrapper] Existing OpenClaw workspace state detected; skipping first-run bootstrap prompt.");
+                return true;
+            }
+
+            if (workspaceState == ExistingWorkspaceState.Unknown)
+            {
+                Logger.Warn("[OnboardingChatBootstrapper] Workspace state probe was unavailable; not sending first-run bootstrap automatically.");
+                return false;
+            }
+        }
+
         if (Interlocked.CompareExchange(ref s_inFlight, 1, 0) != 0)
         {
             Logger.Info("[OnboardingChatBootstrapper] Bootstrap skipped because another gateway send is in flight");
@@ -94,6 +145,122 @@ public static async Task<bool> BootstrapAsync(
         }
     }
 
+    private static async Task<ExistingWorkspaceState> ProbeExistingWorkspaceStateAsync(
+        IOperatorGatewayClient client,
+        TimeSpan timeout,
+        CancellationToken cancellationToken)
+    {
+        const string agentId = "main";
+        using var observer = new AgentFilesListObserver(client, agentId);
+        try
+        {
+            await client.RequestAgentFilesListAsync(agentId).ConfigureAwait(true);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"[OnboardingChatBootstrapper] Workspace state probe failed: {ex.Message}");
+            return ExistingWorkspaceState.Unknown;
+        }
+
+        var payload = await observer.WaitForFilesListAsync(
+            DateTimeOffset.UtcNow + timeout,
+            cancellationToken).ConfigureAwait(true);
+
+        if (payload is null)
+        {
+            Logger.Warn("[OnboardingChatBootstrapper] Workspace state probe returned no file list.");
+            return ExistingWorkspaceState.Unknown;
+        }
+
+        return ContainsExistingWorkspaceMarker(payload.Value)
+            ? ExistingWorkspaceState.Existing
+            : ExistingWorkspaceState.Empty;
+    }
+
+    private static bool ContainsExistingWorkspaceMarker(JsonElement payload)
+    {
+        if (!payload.TryGetProperty("files", out var filesEl) || filesEl.ValueKind != JsonValueKind.Array)
+            return false;
+
+        foreach (var fileEl in filesEl.EnumerateArray())
+        {
+            var exists = !fileEl.TryGetProperty("exists", out var existsEl) ||
+                         existsEl.ValueKind != JsonValueKind.False;
+            if (!exists)
+                continue;
+
+            if (!fileEl.TryGetProperty("name", out var nameEl))
+                continue;
+
+            var name = nameEl.GetString();
+            if (string.IsNullOrWhiteSpace(name))
+                continue;
+
+            if (ExistingWorkspaceMarkerFiles.Contains(Path.GetFileName(name)))
+                return true;
+        }
+
+        return false;
+    }
+
+    private sealed class AgentFilesListObserver : IDisposable
+    {
+        private readonly IOperatorGatewayClient _client;
+        private readonly string _agentId;
+        private readonly TaskCompletionSource<JsonElement?> _completion = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        public AgentFilesListObserver(IOperatorGatewayClient client, string agentId)
+        {
+            _client = client;
+            _agentId = agentId;
+            _client.AgentFilesListUpdated += OnAgentFilesListUpdated;
+        }
+
+        public async Task<JsonElement?> WaitForFilesListAsync(
+            DateTimeOffset timeoutAt,
+            CancellationToken cancellationToken)
+        {
+            if (_completion.Task.IsCompleted)
+                return await _completion.Task.ConfigureAwait(true);
+
+            var remaining = timeoutAt - DateTimeOffset.UtcNow;
+            if (remaining <= TimeSpan.Zero)
+                return null;
+
+            var completed = await Task.WhenAny(_completion.Task, Task.Delay(remaining, cancellationToken)).ConfigureAwait(true);
+            if (completed != _completion.Task)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                return null;
+            }
+
+            return await _completion.Task.ConfigureAwait(true);
+        }
+
+        public void Dispose()
+        {
+            _client.AgentFilesListUpdated -= OnAgentFilesListUpdated;
+        }
+
+        private void OnAgentFilesListUpdated(object? sender, JsonElement payload)
+        {
+            if (sender != _client)
+                return;
+
+            if (payload.TryGetProperty("agentId", out var agentIdEl) &&
+                !string.Equals(agentIdEl.GetString(), _agentId, StringComparison.OrdinalIgnoreCase))
+            {
+                return;
+            }
+
+            _completion.TrySetResult(payload.Clone());
+        }
+    }
+
     private sealed class RunCompletionObserver : IDisposable
     {
         private readonly IOperatorGatewayClient _client;

src/OpenClaw.Tray.WinUI/Services/SettingsManager.cs

@@ -22,6 +22,7 @@ public class SettingsManager
 
     public static string SettingsDirectoryPath => GetDefaultSettingsDirectory();
     public static string SettingsPath => Path.Combine(SettingsDirectoryPath, "settings.json");
+    public string SettingsDirectory => _settingsDirectory;
 
     /// <summary>Raised after settings are persisted to disk.</summary>
     public event EventHandler? Saved;