Merge main into connection snapshot truth

Keep PR 918 current with main and add a maintainer patch so app.settings.set surfaces MCP startup failures as tool errors while MCP startup notifications are shown or dismissed from a single runtime policy.

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

Author: shanselman

AGENTS.md

@@ -13,6 +13,8 @@ Required steps:
 3. Run tray tests:
    - `dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore`
 
+This is the required local closeout subset for agents. CI also builds and runs additional connection, setup, CLI, UI, integration, and E2E suites; see `docs/TEST_COVERAGE.md` for the broader inventory.
+
 If a command fails:
 
 1. Fix the issue.

DEVELOPMENT.md

@@ -44,10 +44,18 @@ openclaw-windows-hub/
 │   │   ├── Models.cs                 # Data models (SessionInfo, ChannelHealth, etc.)
 │   │   └── IOpenClawLogger.cs        # Logging interface
 │   │
+│   ├── OpenClaw.Connection/          # Gateway registry, credentials, connection manager
+│   │
 │   ├── OpenClaw.Chat/                # Native chat model and reducer
 │   │   ├── ChatModels.cs             # Threads, entries, events, provider contract
 │   │   └── ChatTimelineReducer.cs    # Timeline state transitions
 │   │
+│   ├── OpenClaw.Cli/                 # WebSocket connect/send/probe validator
+│   │
+│   ├── OpenClaw.WinNode.Cli/         # winnode local MCP/Windows-node CLI
+│   │
+│   ├── OpenClaw.SetupEngine/         # Local WSL gateway setup and setup-code support
+│   │
 │   ├── OpenClawTray.FunctionalUI/    # Small in-repo declarative WinUI helper
 │   │   └── FunctionalUI.cs           # Components, hooks, elements, host control
 │   │
@@ -59,8 +67,12 @@ openclaw-windows-hub/
 │   │   └── Helpers/                  # Icon generation, utilities
 │   │
 ├── tests/
-│   ├── OpenClaw.Shared.Tests/        # Unit tests for shared library
-│   └── OpenClaw.Tray.Tests/          # Tests for tray helpers (menu, settings, deep links)
+│   ├── OpenClaw.Shared.Tests/        # Unit tests for shared library/capabilities/MCP
+│   ├── OpenClaw.Connection.Tests/    # Gateway registry and connection manager tests
+│   ├── OpenClaw.Tray.Tests/          # Tests for tray helpers (menu, settings, deep links)
+│   ├── OpenClaw.WinNode.Cli.Tests/   # winnode CLI contract tests
+│   ├── OpenClaw.SetupEngine.Tests/   # Setup engine tests
+│   └── OpenClaw.Tray.UITests/        # Native WinUI/A2UI UI tests
 │
 ├── tools/
 │   └── icongen/                      # Icon generation tool
@@ -76,16 +88,18 @@ openclaw-windows-hub/
 ### Project Dependencies
 
 ```
-OpenClaw.Tray.WinUI  ──depends on──▶  OpenClaw.Shared
-OpenClaw.Shared.Tests  ──tests──▶  OpenClaw.Shared
-OpenClaw.Tray.Tests  ──tests──▶  OpenClaw.Shared
+OpenClaw.Tray.WinUI  ──depends on──▶  OpenClaw.Shared + OpenClaw.Connection + OpenClaw.Chat
+OpenClaw.WinNode.Cli  ──depends on──▶  OpenClaw.Shared
+OpenClaw.SetupEngine  ──supports──▶  local WSL gateway setup
+OpenClaw.*.Tests  ──test──▶  corresponding shared, connection, tray, setup, and CLI surfaces
 ```
 
 ### Key Subsystems
 
 | Subsystem | Location | Purpose |
 |-----------|----------|---------|
 | **Gateway Communication** | `OpenClaw.Shared/OpenClawGatewayClient.cs` | WebSocket client with protocol v3, reconnect/backoff logic |
+| **Connection Management** | `OpenClaw.Connection/` | Gateway registry, credential precedence, pairing, tunnels, and reconnect policy |
 | **Notification System** | `OpenClaw.Tray.WinUI/App.xaml.cs` | Event routing, toast notifications, classification |
 | **WebView2 Integration** | `OpenClaw.Tray.WinUI/Windows/ChatWindow.xaml.cs` | Embedded chat panel with lifecycle management |
 | **Tray Icon Management** | `OpenClaw.Tray.WinUI/Helpers/IconHelper.cs` | GDI handle management, dynamic icon generation |

README.md

@@ -21,20 +21,26 @@ This monorepo contains the Windows hub, shared client libraries, and CLI utiliti
 | Project | Description |
 |---------|-------------|
 | **OpenClaw.Tray.WinUI** | System tray application (WinUI 3) for quick access to OpenClaw |
-| **OpenClaw.Shared** | Shared gateway client library |
+| **OpenClaw.Connection** | Gateway registry, credential resolution, and connection manager |
+| **OpenClaw.Shared** | Shared gateway client library, capabilities, and MCP bridge |
+| **OpenClaw.Chat** | Native chat model and timeline reducer |
 | **OpenClaw.Cli** | CLI validator for WebSocket connect/send/probe using tray settings |
+| **OpenClaw.WinNode.Cli** | `winnode` CLI for invoking local Windows node/MCP capabilities |
+| **OpenClaw.SetupEngine** | Local gateway setup, WSL installation, and setup-code support |
 
 ## 🚀 Quick Start
 
 > **End-user installer?** Download the latest stable x64 or ARM64 installer from the [OpenClaw Windows docs](https://docs.openclaw.ai/platforms/windows), or see [docs/SETUP.md](docs/SETUP.md) for step-by-step installation (no build required).
 >
 > **Managed WSL gateway?** Local setup creates a locked-down app-owned `OpenClawGateway` distro. See [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) for editing `openclaw.json` as the `openclaw` user and using root for protected-file administration.
+>
+> **Operator or node?** Start with [Operator and node concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the beginner-facing glossary of gateway, operator, node, pairing, reapproval, and allowlisted node capabilities.
 
-Direct downloads from the latest OpenClaw release:
+Direct downloads from the latest OpenClaw Windows release:
 
-- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-x64.exe)
-- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-arm64.exe)
-- [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt)
+- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-x64.exe)
+- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-arm64.exe)
+- [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt)
 
 ### Prerequisites
 - Windows 10 (20H2+) or Windows 11
@@ -54,6 +60,9 @@ Use the setup script to install or verify local Windows build prerequisites:
 # Check only; do not install packages or change git safe.directory
 .\scripts\setup-dev.ps1 -CheckOnly
 
+# Install/verify prerequisites without adding the checkout to git safe.directory
+.\scripts\setup-dev.ps1 -NoTrustRepository
+
 # Setup and run the required build/test validation
 .\scripts\setup-dev.ps1 -RunValidation
 ```
@@ -211,6 +220,8 @@ These features are available in Windows but not in the Mac app:
 
 ### 🔌 Node Mode (Agent Control)
 
+If the operator/node split is new to you, read [Operator and node concepts](docs/OPERATOR_NODE_CONCEPTS.md) before enabling Node Mode.
+
 When Node Mode is enabled in Settings, your Windows PC becomes a **node** that the OpenClaw agent can control - just like the Mac app! The agent can:
 
 | Capability | Commands | Description |

build.ps1

@@ -1,12 +1,12 @@
-<#
+<#
 .SYNOPSIS
     Build script for OpenClaw Windows Hub
 
 .DESCRIPTION
     Builds all projects, checks prerequisites, and provides clear guidance.
 
 .PARAMETER Project
-    Which project to build: All, Tray, WinUI, Shared, Cli
+    Which project to build: All, Tray, WinUI, Shared, Cli, WinNodeCli, SetupEngine
     Default: All
 
 .PARAMETER Configuration
@@ -322,7 +322,10 @@ if ($issues.Count -gt 0) {
 Write-Header "Building Projects ($Configuration)"
 
 # Detect runtime identifier based on architecture
-$rid = if ($arch -eq "ARM64") { "win-arm64" } else { "win-x64" }
+$rid = switch ($arch) {
+    "ARM64" { "win-arm64" }
+    default { "win-x64" }
+}
 Write-Info "Runtime identifier: $rid"
 
 $buildResults = @{}

docs/CONNECTION_ARCHITECTURE.md

@@ -69,17 +69,21 @@ Inbound chat and agent timeline events must include the gateway's canonical `ses
 ## Startup wiring (App.xaml.cs)
 
 ```
-1. Create GatewayRegistry(dataDir)
-2. Create CredentialResolver(identityReader)
-3. Create GatewayClientFactory()
-4. Create NodeConnector(logger)
-5. Create SshTunnelManager(tunnelService, logger)
-6. Create GatewayConnectionManager(resolver, factory, registry, ...,
-                                    nodeConnector, tunnelManager)
-7. Subscribe to StateChanged → update tray icon + hub window
-8. Subscribe to OperatorClientChanged → wire/unwire 25+ data event handlers
-9. Subscribe to NodeConnector.ClientCreated → NodeService.AttachClient
-10. Call ConnectAsync() → connects to active gateway
+1. Create GatewayRegistry(SettingsManager.SettingsDirectoryPath)
+2. Load gateway registry from gateways.json
+3. Create CredentialResolver(DeviceIdentityFileReader.Instance)
+4. Create GatewayClientFactory()
+5. Create ConnectionDiagnostics()
+6. Create NodeConnector(logger, diagnostics)
+7. Wire NodeConnector.ClientCreated → NodeService.AttachClient
+8. Create SshTunnelService(logger)
+9. Create GatewayConnectionManager(resolver, factory, registry, logger,
+                                    identityStore, nodeConnector, node mode flag,
+                                    diagnostics, tunnelService)
+10. Subscribe to OperatorClientChanged → wire/unwire 25+ data event handlers
+11. Subscribe to StateChanged → update tray icon + hub window
+12. Ensure NodeService exists before gateway initialization
+13. Call InitializeGatewayClient() → connects to active gateway
 ```
 
 Settings changes are classified by `SettingsChangeClassifier.Classify()` which compares `ConnectionSettingsSnapshot` before/after to determine the minimum reconnect action:
@@ -129,7 +133,7 @@ Idle → Connecting → Connected
 %APPDATA%\OpenClawTray\gateways\<id>\device-key-ed25519.json  — keypair + tokens
 ```
 
-Each `GatewayRecord` contains: `Id`, `Url`, `FriendlyName`, `SharedGatewayToken`, `BootstrapToken`, `LastConnected`, `SshTunnel` config, and an `IdentityDirName`.
+Each `GatewayRecord` contains: `Id`, `Url`, `FriendlyName`, `SharedGatewayToken`, `BootstrapToken`, `LastConnected`, `SshTunnel` config, `IsLocal`, `RequiresV2Signature`, `SetupManagedDistroName`, and `BrowserControlPort`. The `IdentityDirName` property is computed from `Id`.
 
 `SettingsManager` still owns general tray settings (node mode, MCP mode, SSH tunnel toggles, notifications, UI preferences). It may read legacy `Token` / `BootstrapToken` JSON fields into memory for migration, but save must not write those legacy credential fields back.
 
@@ -146,6 +150,13 @@ The invariant is that a paired device token always wins. Do not downgrade a pair
 
 **`CredentialResolver`** implements the precedence for WebSocket connections (operator and node roles).
 
+Node credential precedence follows the same invariant with a distinct stored token:
+
+1. **Stored node device token** in the per-gateway identity directory.
+2. **`GatewayRecord.SharedGatewayToken`** — shared token fallback when no paired node token exists.
+3. **`GatewayRecord.BootstrapToken`** — one-time setup, limited scopes.
+4. **No credential** — caller logs and skips node client init.
+
 **`InteractiveGatewayCredentialResolver`** resolves credentials for HTTP surfaces (chat URL `?token=` auth). It **prefers SharedGatewayToken** over DeviceToken because HTTP endpoints expect the shared token, not the per-device WebSocket token.
 
 ## Client instance lifecycle
@@ -179,7 +190,7 @@ When **another** device or node requests pairing, the gateway broadcasts `device
 
 ## SSH tunnel integration
 
-`SshTunnelService` manages an SSH local port-forward process. `SshTunnelManager` wraps it behind `ISshTunnelManager` for the connection manager.
+`SshTunnelService` manages an SSH local port-forward process and implements `ISshTunnelManager` directly for the connection manager.
 
 When a `GatewayRecord` has `SshTunnel` config, the connection manager starts the tunnel before connecting the WebSocket client to `ws://localhost:<localPort>`. The config stores the SSH daemon port (`sshPort`, default `22`) separately from the remote gateway port forwarded by `-L`.
 
@@ -203,8 +214,9 @@ The `EnableMcpServer=true`, `EnableNodeMode=false` path creates a local-only `No
 Tray actions should never silently no-op on common pairing/configuration issues:
 
 - Chat resolves credentials from the active registry record and per-gateway identity. If no usable credential exists, it opens Connection settings instead.
-- Canvas opens only when the Windows node is initialized and paired; otherwise it opens Connection settings.
+- Canvas opens only when the Windows node is initialized, paired, and the Canvas capability is enabled in settings; otherwise it opens Connection settings.
 - Quick Send uses the live operator client and surfaces scope/pairing errors from gateway calls.
+- `system.run` and `system.run.prepare` are gated by `NodeSystemRunEnabled` (default `true` for backward compatibility). When disabled, those commands are dropped from advertised capabilities and invocations are rejected.
 
 ## Legacy migration
 

docs/MCP_MODE.md

@@ -100,12 +100,12 @@ public bool EnableNodeMode { get; set; }      // open WebSocket to gateway
 public bool EnableMcpServer { get; set; }     // run local MCP HTTP server
 ```
 
-| `EnableNodeMode` | `EnableMcpServer` | Result |
+| `EnableNodeMode` | `EnableMcpServer` | Behavior |
 |---|---|---|
-| off | off | Operator-only (legacy default) |
-| off | on | **MCP server only, no gateway** |
-| on | off | Gateway node, no MCP |
-| on | on | Gateway node + MCP |
+| false | false | Operator-only (legacy default) |
+| false | true | **MCP server only, no gateway** |
+| true | false | Gateway node, no MCP |
+| true | true | Gateway node + MCP |
 
 Settings UI exposes both toggles in the Advanced section, with the live MCP endpoint URL and current status (`Listening` / `Stopped — save and restart to start` / `Disabled`).
 

docs/OPERATOR_NODE_CONCEPTS.md

@@ -0,0 +1,82 @@
+# Operator and Node Concepts
+
+OpenClaw Companion connects a Windows PC to an OpenClaw gateway in two separate
+roles. A new install can use both roles at once, but they have different jobs and
+different approval paths.
+
+## Quick Glossary
+
+| Term | Meaning |
+| --- | --- |
+| Gateway | The OpenClaw service that coordinates agents, channels, sessions, devices, and nodes. The Windows app talks to it over WebSocket. |
+| Local WSL gateway | A dedicated `OpenClawGateway` WSL distro installed by the Windows onboarding flow. It is app-owned and locked down rather than a general-purpose Ubuntu profile. |
+| Operator | The user-facing control role. The tray app uses the operator connection for Quick Send, chat, diagnostics, channel controls, setup, and approving pairing requests. |
+| Node | The controllable Windows machine role. When Node Mode is enabled, the tray app advertises Windows capabilities such as screenshots, canvas, camera, notifications, and approved command execution. |
+| Pairing | The gateway approval flow that turns a new device or node request into a trusted identity with a stored device token. |
+| Reapproval | A later approval request when a paired node asks for new or changed trust, such as command capability access. |
+| Allowlisted node capability | A node command the gateway is explicitly allowed to invoke, configured in the gateway `allowCommands` list. Windows-side settings and policies can still block the command. |
+
+## How the Roles Work Together
+
+The operator role is the control surface. It signs in to the gateway, sends chat
+messages, shows status, opens diagnostics, and approves device or node pairing
+requests when the gateway says approval is required.
+
+The node role is the Windows capability surface. It tells the gateway which
+Windows-native tools are available, then waits for approved gateway calls. Node
+Mode does not mean every tool can run automatically. A capability has to be
+enabled in Windows settings, allowed by the gateway, and in some cases approved
+by a local Windows policy prompt.
+
+A typical local setup uses this sequence:
+
+1. OpenClaw Companion installs or connects to a gateway.
+2. The tray app connects as an operator so you can send messages and manage setup.
+3. If Node Mode is enabled, the same Windows app also connects as a node.
+4. The gateway asks for pairing approval before trusting the new device or node.
+5. After approval, the gateway can invoke only the node capabilities that are
+   enabled locally and allowlisted by gateway policy.
+
+## Local WSL Gateway Versus Existing Gateway
+
+The default onboarding path installs a local WSL gateway for users who do not
+already have one. That gateway runs on the same Windows PC and is managed by the
+OpenClaw Companion setup flow.
+
+Advanced setup is for users who already have a local, remote, or manually
+managed gateway. In that case, the Windows app still uses the same operator and
+node roles; only the gateway location and credentials are different.
+
+## Pairing, Tokens, and Reapproval
+
+Pairing is gateway-owned. Setup codes, bootstrap tokens, and shared gateway
+tokens can help the app connect for the first time, but a paired device token
+takes precedence after approval. This keeps long-lived operator and node
+identity scoped to the gateway record that issued it.
+
+Some trust decisions are intentionally not automatic. Node command trust and
+capability reapproval stay pending until an operator explicitly approves them,
+so a new or changed node capability is visible before the gateway can use it.
+
+## Capability Allowlist
+
+Node Mode advertises available Windows commands, but the gateway decides which
+commands it may call through `gateway.nodes.allowCommands` in
+`~/.openclaw/openclaw.json`. Add exact command names such as `screen.snapshot`,
+`canvas.present`, or `system.run`; wildcard entries are not expanded by the
+gateway.
+
+Privacy-sensitive commands, especially `screen.record`, `camera.snap`,
+`camera.clip`, `stt.transcribe`, `tts.speak`, and `system.run`, should only be
+allowlisted when you want the gateway to be able to request that behavior.
+Windows permissions, Node Mode toggles, and the local exec policy can still add
+stricter checks.
+
+## Where to Go Next
+
+- Follow [Installation and setup](SETUP.md) for first-run onboarding and
+  troubleshooting.
+- See [Node Mode](../README.md#-node-mode-agent-control) for capability names
+  and allowlist examples.
+- Read [Connection architecture](CONNECTION_ARCHITECTURE.md) for contributor
+  details about token precedence, pairing, and connection lifecycle.