fix(tray): browser control stuck without shared gateway token (#1066)

* fix(tray): explain browser proxy when shared gateway token is missing

Setup-code pairing can connect without a SharedGatewayToken, which silently skipped browser capability declaration and left the UI stuck on Enabled, not active yet. Surface Needs gateway shared token, warn in Command Center, and log the concrete skip reason.

Refs: openclaw/openclaw#115989

* fix(tray): separate browser proxy no-client from missing-token UI

Only show Needs shared token / Command Center guidance when a node client is attached; disconnected gateways should not tell operators to paste a token.

* fix(tray): align browser.proxy missing-token UX across live session surfaces

Use manager NodeState for remediation, and share topology-aware remote/SSH
endpoint guidance across Connection pill tooltips, Command Center, and
app.connection diagnostics so token-only copy does not overpromise.

Author: trippyogi

docs/WINDOWS_NODE_TESTING.md

@@ -144,6 +144,12 @@ Local MCP clients also see MCP-only `app.*` commands such as `app.navigate`, `ap
 - Ensure Windows notifications are enabled for the app
 - Check if notification settings in the app are enabled
 
+### Browser control stays enabled but never declares `browser`
+- Setup-code / QR pairing can connect with a device token and leave `GatewayRecord.SharedGatewayToken` empty. Browser control will not declare `browser` / `browser.proxy` until a shared gateway token is saved for that gateway.
+- Expect Connection capability pills to say **Needs gateway shared token** (not "Enabled, not active yet") only while the node WebSocket session is live and the shared token is missing. Disconnected or attached-but-disconnected states should ask for reconnect, not a token paste. The pill keeps that short label; its tooltip matches Command Center remediation detail.
+- Command Center, Connection pill tooltips, and `app.connection.status` / `app.connection.gateways` use the same live-session rule for the shared-token caveat. For a remote (non-loopback) gateway without an explicit `BrowserControlPort` or SSH browser-proxy forward — including SSH tunnels whose effective URL is `127.0.0.1` — that caveat also mentions the endpoint/forward requirement; the shared token alone is not enough for usable remote browser.proxy.
+- Enter the gateway shared token in Settings, save, and reconnect node mode. Bootstrap tokens are not the shared gateway token.
+
 ### `browser.proxy` reports no browser-control host
 - Confirm the Browser proxy bridge toggle is enabled in Settings, then save and reconnect or re-pair if the gateway keeps an older command snapshot.
 - The bridge is local-only: it calls `http://127.0.0.1:<gateway-port+2>` from Windows. For a gateway on `ws://127.0.0.1:18789`, the browser-control host must listen on `127.0.0.1:18791`.

src/OpenClaw.Tray.WinUI/App.CapabilityHandlers.cs

@@ -256,10 +256,16 @@ private void WireAppCapabilityHandlers()
         };
 
         connection.GatewaysHandler = () =>
-            Task.FromResult<object?>(ConnectionDiagnosticsProjection.BuildGateways(
+        {
+            var nodeSessionLive = BrowserProxyActivation.IsNodeSessionLive(
+                _connectionManager?.CurrentSnapshot.NodeState
+                    ?? OpenClaw.Connection.RoleConnectionState.Idle);
+            return Task.FromResult<object?>(ConnectionDiagnosticsProjection.BuildGateways(
                 _gatewayRegistry?.GetAll() ?? [],
                 _gatewayRegistry?.ActiveGatewayId,
-                nodeBrowserProxyEnabled: _settings?.NodeBrowserProxyEnabled != false));
+                nodeBrowserProxyEnabled: _settings?.NodeBrowserProxyEnabled != false,
+                nodeSessionLive: nodeSessionLive));
+        };
 
         connection.ApplySetupCodeHandler = async setupCode =>
         {

src/OpenClaw.Tray.WinUI/App.xaml.cs

@@ -3848,6 +3848,8 @@ private AppStateSnapshot CaptureSnapshot()
             EffectiveBrowserControlPort = activeGateway?.BrowserControlPort,
             HasActiveGatewayRecord = activeGateway != null,
             ActiveGatewayHasSharedToken = !string.IsNullOrWhiteSpace(activeGateway?.SharedGatewayToken),
+            NodeConnectionState = _connectionManager?.CurrentSnapshot.NodeState
+                ?? OpenClaw.Connection.RoleConnectionState.Idle,
             ActiveGatewaySshTunnel = activeGateway?.SshTunnel
         };
     }

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

@@ -930,18 +930,37 @@ or NodeCardState.OnNodeRateLimited
 
             if (showSurfaces && settings is not null)
             {
+                var activeGateway = _gatewayRegistry?.GetActive();
+                var hasSharedGatewayToken = !string.IsNullOrWhiteSpace(
+                    activeGateway?.SharedGatewayToken);
+                // Same manager NodeState signal as app.connection.* / Command Center.
+                var nodeSessionLive = BrowserProxyActivation.IsNodeSessionLive(
+                    _connectionManager?.CurrentSnapshot.NodeState
+                        ?? OpenClaw.Connection.RoleConnectionState.Idle);
+                // Match Command Center CaptureSnapshot: active record URL, else settings.
+                var requiresRemoteBrowserEndpoint =
+                    BrowserProxyActivation.RequiresRemoteBrowserEndpoint(
+                        gatewayUrl: activeGateway?.Url ?? settings.GatewayUrl,
+                        browserControlPort: activeGateway?.BrowserControlPort,
+                        sshTunnel: activeGateway?.SshTunnel);
                 var pillFp = BuildCapabilityPillFingerprint(
                     plan.NodeCard,
                     plan.NodeEffectiveCapabilities,
                     plan.NodePendingDeclaredCapabilities,
-                    settings);
+                    settings,
+                    hasSharedGatewayToken,
+                    nodeSessionLive,
+                    requiresRemoteBrowserEndpoint);
                 if (_capabilityPillsFingerprint != pillFp)
                 {
                     _capabilityPillsFingerprint = pillFp;
                     NodeCapabilityPillsHost.Child = BuildCapabilityPills(
                         plan.NodeEffectiveCapabilities,
                         plan.NodePendingDeclaredCapabilities,
-                        settings);
+                        settings,
+                        hasSharedGatewayToken,
+                        nodeSessionLive,
+                        requiresRemoteBrowserEndpoint);
                 }
 
                 NodeCapabilityPillsHost.Visibility =
@@ -1194,12 +1213,15 @@ private static Border BuildBulletRow(string text)
         return new Border { Child = grid };
     }
 
-    private enum CapabilityPillState { Active, Pending, Off }
+    private enum CapabilityPillState { Active, Pending, NeedsSharedToken, Off }
 
     private WrapPanel BuildCapabilityPills(
         IReadOnlyList<string> effective,
         IReadOnlyList<string> pendingDeclared,
-        SettingsManager settings)
+        SettingsManager settings,
+        bool hasSharedGatewayToken,
+        bool nodeSessionLive,
+        bool requiresRemoteBrowserEndpoint)
     {
         var panel = new WrapPanel { HorizontalSpacing = 6, VerticalSpacing = 6 };
         var effectiveSet = new HashSet<string>(
@@ -1224,12 +1246,36 @@ private WrapPanel BuildCapabilityPills(
         var shown = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
         foreach (var (name, labelKey, glyph, enabled) in canonical)
         {
-            var state = effectiveSet.Contains(name)
-                ? CapabilityPillState.Active
-                : (pendingSet.Contains(name) || enabled)
-                    ? CapabilityPillState.Pending
-                    : CapabilityPillState.Off;
-            panel.Children.Add(MakeCapabilityPill(LocalizationHelper.GetString(labelKey), glyph, state, isHighContrast));
+            var kind = name.Equals("browser", StringComparison.OrdinalIgnoreCase)
+                ? BrowserProxyActivation.ResolveCapabilityPillKind(
+                    toggleEnabled: enabled,
+                    effective: effectiveSet.Contains(name),
+                    pendingDeclared: pendingSet.Contains(name),
+                    hasSharedGatewayToken: hasSharedGatewayToken,
+                    nodeSessionLive: nodeSessionLive)
+                : effectiveSet.Contains(name)
+                    ? BrowserProxyActivation.CapabilityPillKind.Active
+                    : (pendingSet.Contains(name) || enabled)
+                        ? BrowserProxyActivation.CapabilityPillKind.PendingApproval
+                        : BrowserProxyActivation.CapabilityPillKind.Off;
+            var state = kind switch
+            {
+                BrowserProxyActivation.CapabilityPillKind.Active => CapabilityPillState.Active,
+                BrowserProxyActivation.CapabilityPillKind.NeedsSharedToken => CapabilityPillState.NeedsSharedToken,
+                BrowserProxyActivation.CapabilityPillKind.PendingApproval => CapabilityPillState.Pending,
+                _ => CapabilityPillState.Off,
+            };
+            var remoteForPill = name.Equals("browser", StringComparison.OrdinalIgnoreCase) &&
+                                kind == BrowserProxyActivation.CapabilityPillKind.NeedsSharedToken
+                ? requiresRemoteBrowserEndpoint
+                : false;
+            panel.Children.Add(MakeCapabilityPill(
+                LocalizationHelper.GetString(labelKey),
+                glyph,
+                state,
+                isHighContrast,
+                kind,
+                remoteForPill));
             shown.Add(name);
         }
 
@@ -1245,15 +1291,29 @@ private WrapPanel BuildCapabilityPills(
                 "system" => (LocalizationHelper.GetString("ConnectionPage_NodeCap_System"), FluentIconCatalog.System),
                 _ => (HumanizeNodeToken(name), FluentIconCatalog.System),
             };
-            panel.Children.Add(MakeCapabilityPill(label, glyph, state, isHighContrast));
+            panel.Children.Add(MakeCapabilityPill(
+                label,
+                glyph,
+                state,
+                isHighContrast,
+                kind: state == CapabilityPillState.Active
+                    ? BrowserProxyActivation.CapabilityPillKind.Active
+                    : BrowserProxyActivation.CapabilityPillKind.PendingApproval,
+                requiresRemoteBrowserEndpoint: false));
         }
 
         return panel;
     }
 
     private const double CapabilityPillFillOpacity = 0.14;
 
-    private Border MakeCapabilityPill(string label, string glyph, CapabilityPillState state, bool isHighContrast)
+    private Border MakeCapabilityPill(
+        string label,
+        string glyph,
+        CapabilityPillState state,
+        bool isHighContrast,
+        BrowserProxyActivation.CapabilityPillKind kind,
+        bool requiresRemoteBrowserEndpoint)
     {
         var (fillBrush, iconBrush, textBrush, stateKey, stateGlyph) = state switch
         {
@@ -1277,6 +1337,16 @@ private Border MakeCapabilityPill(string label, string glyph, CapabilityPillStat
                 ResolveBrush("SystemFillColorCautionBrush"),
                 "ConnectionPage_NodePillState_Pending",
                 FluentIconCatalog.StatusWarn),
+            CapabilityPillState.NeedsSharedToken => (
+                TintBrush(
+                    "SystemFillColorCriticalBrush",
+                    "SystemFillColorCriticalBackgroundBrush",
+                    CapabilityPillFillOpacity,
+                    isHighContrast),
+                ResolveBrush("SystemFillColorCriticalBrush"),
+                ResolveBrush("SystemFillColorCriticalBrush"),
+                "ConnectionPage_NodePillState_NeedsGatewayToken",
+                FluentIconCatalog.StatusWarn),
             _ => (
                 ResolveBrush("SubtleFillColorTertiaryBrush"),
                 ResolveBrush("TextFillColorTertiaryBrush"),
@@ -1303,14 +1373,18 @@ private Border MakeCapabilityPill(string label, string glyph, CapabilityPillStat
         content.Children.Add(capabilityIcon);
 
         var stateText = LocalizationHelper.GetString(stateKey);
+        var detailText = BrowserProxyActivation.ResolveCapabilityPillTooltip(
+            kind,
+            stateText,
+            requiresRemoteBrowserEndpoint);
         var labelText = new TextBlock
         {
             Text = label,
             FontSize = 12,
             Foreground = textBrush,
             VerticalAlignment = VerticalAlignment.Center,
         };
-        AutomationProperties.SetName(labelText, $"{label}: {stateText}");
+        AutomationProperties.SetName(labelText, $"{label}: {detailText}");
         content.Children.Add(labelText);
 
         if (stateGlyph != null)
@@ -1334,7 +1408,7 @@ private Border MakeCapabilityPill(string label, string glyph, CapabilityPillStat
             Background = fillBrush,
             Child = content,
         };
-        ToolTipService.SetToolTip(pill, stateText);
+        ToolTipService.SetToolTip(pill, detailText);
         return pill;
     }
 
@@ -1366,7 +1440,10 @@ private static string BuildCapabilityPillFingerprint(
         NodeCardState state,
         IReadOnlyList<string> effective,
         IReadOnlyList<string> pendingDeclared,
-        SettingsManager settings)
+        SettingsManager settings,
+        bool hasSharedGatewayToken,
+        bool nodeSessionLive,
+        bool requiresRemoteBrowserEndpoint)
     {
         var eff = string.Join(
             ",",
@@ -1384,7 +1461,7 @@ private static string BuildCapabilityPillFingerprint(
             settings.NodeLocationEnabled ? '1' : '0',
             settings.NodeTtsEnabled ? '1' : '0',
             settings.NodeSttEnabled ? '1' : '0');
-        return $"{state}|{eff}|{pend}|{toggles}";
+        return $"{state}|{eff}|{pend}|{toggles}|{(hasSharedGatewayToken ? '1' : '0')}|{(nodeSessionLive ? '1' : '0')}|{(requiresRemoteBrowserEndpoint ? '1' : '0')}";
     }
 
     /// <summary>

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

@@ -39,6 +39,13 @@ internal sealed record AppStateSnapshot
     public bool HasActiveGatewayRecord          { get; init; }
     public bool ActiveGatewayHasSharedToken     { get; init; }
 
+    /// <summary>
+    /// Manager-owned node role state. Shared-token browser remediation uses
+    /// <see cref="BrowserProxyActivation.IsNodeSessionLive"/> on this value so
+    /// Command Center matches <c>app.connection.*</c> diagnostics.
+    /// </summary>
+    public OpenClaw.Connection.RoleConnectionState NodeConnectionState { get; init; }
+
     /// <summary>SSH tunnel config from the active GatewayRecord. Null means this gateway is
     /// direct (no tunnel), NOT "unknown". Only meaningful when HasActiveGatewayRecord is true.</summary>
     public SshTunnelConfig? ActiveGatewaySshTunnel { get; init; }