fix: guard bootstrap prompt against already-configured workspaces (#729)

Root cause: OnboardingChatBootstrapper.BootstrapAsync() only checked the
HasInjectedFirstRunBootstrap flag, which could be unset (false) even when
the user already had a configured gateway (e.g. fresh app install over an
existing workspace, settings migration, or flag reset). This caused the
first-run ritual prompt to fire against an already-configured workspace,
risking unintended rewrites of SOUL.md, AGENTS.md, and other workspace files.

Fix: Add an optional GatewayRegistry parameter to BootstrapAsync(). Before
sending the bootstrap message, check SetupExistingGatewayClassifier
.HasAnyExistingGatewayConnection(). If an existing gateway configuration is
detected, silently mark the gate as consumed and return true without sending
the prompt. ChatPage.xaml.cs now passes app.Registry to BootstrapAsync()
to enable this guard.

Tests: 4 new unit tests cover the existing-gateway-skip path (SharedGatewayToken,
BootstrapToken), the empty-registry first-run path, and the no-registry path
(backward compatibility). All 996 tray tests pass.

Closes #729

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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,3 +1,4 @@
+using OpenClaw.Connection;
 using OpenClaw.Shared;
 using System;
 using System.Collections.Generic;
@@ -36,12 +37,27 @@ public static async Task<bool> BootstrapAsync(
         IOperatorGatewayClient? client,
         SettingsManager settings,
         TimeSpan? completionTimeout = null,
-        CancellationToken cancellationToken = default)
+        CancellationToken cancellationToken = default,
+        GatewayRegistry? registry = null)
     {
         ArgumentNullException.ThrowIfNull(settings);
 
         if (settings.HasInjectedFirstRunBootstrap)
             return true;
+
+        // Guard: if the user already has a configured gateway, treat this as a non-first-run
+        // installation and silently consume the bootstrap gate without sending the prompt.
+        // This prevents the first-run ritual from firing against an already-configured workspace
+        // in cases where the HasInjectedFirstRunBootstrap flag was not persisted (e.g. fresh
+        // app install over an existing workspace, settings migration, or flag reset).
+        if (registry is not null && SetupExistingGatewayClassifier.HasAnyExistingGatewayConnection(
+                registry, settings, SettingsManager.SettingsDirectoryPath))
+        {
+            MarkBootstrapped(settings);
+            Logger.Info("[OnboardingChatBootstrapper] Existing gateway configuration detected; skipping first-run bootstrap prompt.");
+            return true;
+        }
+
         if (client == null || !client.IsConnectedToGateway)
             return false;
         if (Interlocked.CompareExchange(ref s_inFlight, 1, 0) != 0)

tests/OpenClaw.Tray.Tests/OnboardingChatBootstrapperTests.cs

@@ -1,3 +1,4 @@
+using OpenClaw.Connection;
 using OpenClaw.Shared;
 using OpenClawTray.Services;
 using System.Text.Json;
@@ -82,6 +83,92 @@ public async Task BootstrapAsync_DoesNotConsumeGate_WhenCompletionTimesOut()
         Assert.False(settings.HasInjectedFirstRunBootstrap);
     }
 
+    [Fact]
+    public async Task BootstrapAsync_SkipsPromptAndMarksBootstrapped_WhenRegistryHasExistingGatewayWithSharedToken()
+    {
+        var settings = new SettingsManager(_settingsDir);
+        var client = new FakeOperatorGatewayClient { IsConnectedToGateway = true };
+
+        var registryDir = Path.Combine(_settingsDir, "registry-existing");
+        Directory.CreateDirectory(registryDir);
+        var registry = new GatewayRegistry(registryDir);
+        registry.AddOrUpdate(new GatewayRecord
+        {
+            Id = "gw-existing",
+            Url = "ws://192.168.1.10:18789",
+            SharedGatewayToken = "existing-shared-token"
+        });
+
+        var result = await OnboardingChatBootstrapper.BootstrapAsync(client, settings, TimeSpan.FromSeconds(5), registry: registry);
+
+        Assert.True(result, "Should return true when existing gateway is detected.");
+        Assert.Equal(0, client.SendCount);
+        Assert.True(settings.HasInjectedFirstRunBootstrap, "Gate should be marked so the check doesn't repeat.");
+    }
+
+    [Fact]
+    public async Task BootstrapAsync_SkipsPromptAndMarksBootstrapped_WhenRegistryHasExistingGatewayWithBootstrapToken()
+    {
+        var settings = new SettingsManager(_settingsDir);
+        var client = new FakeOperatorGatewayClient { IsConnectedToGateway = true };
+
+        var registryDir = Path.Combine(_settingsDir, "registry-bootstrap");
+        Directory.CreateDirectory(registryDir);
+        var registry = new GatewayRegistry(registryDir);
+        registry.AddOrUpdate(new GatewayRecord
+        {
+            Id = "gw-bootstrap",
+            Url = "ws://my-gateway:18789",
+            BootstrapToken = "existing-bootstrap-token"
+        });
+
+        var result = await OnboardingChatBootstrapper.BootstrapAsync(client, settings, TimeSpan.FromSeconds(5), registry: registry);
+
+        Assert.True(result);
+        Assert.Equal(0, client.SendCount);
+        Assert.True(settings.HasInjectedFirstRunBootstrap);
+    }
+
+    [Fact]
+    public async Task BootstrapAsync_SendsBootstrapPrompt_WhenRegistryIsEmptyAndGatewayIsNew()
+    {
+        var settings = new SettingsManager(_settingsDir);
+        var client = new FakeOperatorGatewayClient { Result = new ChatSendResult { RunId = "run-new" } };
+
+        var registryDir = Path.Combine(_settingsDir, "registry-empty");
+        Directory.CreateDirectory(registryDir);
+        var registry = new GatewayRegistry(registryDir);
+        // Registry has no records — this is a true first-run scenario.
+
+        var task = OnboardingChatBootstrapper.BootstrapAsync(client, settings, TimeSpan.FromSeconds(5), registry: registry);
+        // slopwatch-ignore: SW004 Test delay is an intentional bounded async wait; replacing it would change the scenario under test.
+        await Task.Delay(50);
+        client.RaiseFinalAssistant("run-new");
+        var result = await task;
+
+        Assert.True(result);
+        Assert.Equal(1, client.SendCount);
+        Assert.Equal(OnboardingChatBootstrapper.Message, client.LastMessage);
+        Assert.True(settings.HasInjectedFirstRunBootstrap);
+    }
+
+    [Fact]
+    public async Task BootstrapAsync_SendsBootstrapPrompt_WhenNoRegistryProvided()
+    {
+        var settings = new SettingsManager(_settingsDir);
+        var client = new FakeOperatorGatewayClient { Result = new ChatSendResult { RunId = "run-noregistry" } };
+
+        var task = OnboardingChatBootstrapper.BootstrapAsync(client, settings, TimeSpan.FromSeconds(5));
+        // slopwatch-ignore: SW004 Test delay is an intentional bounded async wait; replacing it would change the scenario under test.
+        await Task.Delay(50);
+        client.RaiseFinalAssistant("run-noregistry");
+        var result = await task;
+
+        Assert.True(result);
+        Assert.Equal(1, client.SendCount);
+        Assert.True(settings.HasInjectedFirstRunBootstrap);
+    }
+
 #pragma warning disable CS0067
     private sealed class FakeOperatorGatewayClient : IOperatorGatewayClient
     {