diff --git a/AGENTS.md b/AGENTS.md
index 2343c9ad2..3a58046e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,6 +77,7 @@ Start with these docs before changing connection, pairing, node, MCP, or tray UX
 - `docs/MCP_MODE.md` - local MCP server mode and the `EnableNodeMode` / `EnableMcpServer` matrix.
 - `docs/WINDOWS_NODE_TESTING.md` - Windows node capabilities, manual smokes, and gateway-dependent behavior.
 - `docs/ONBOARDING_WIZARD.md` - first-run setup flow, setup-code/bootstrap pairing, and test isolation.
+- `docs/WSL_EXE_ARGV_PITFALL.md` - wsl.exe argv variable-expansion pitfall; required reading before adding any multi-line WSL script through `RunInWslAsync`.
 
 ## Architecture Guardrails for Large Refactors
 
diff --git a/docs/ONBOARDING_WIZARD.md b/docs/ONBOARDING_WIZARD.md
index 2eb9c75e0..2eb44c4f8 100644
--- a/docs/ONBOARDING_WIZARD.md
+++ b/docs/ONBOARDING_WIZARD.md
@@ -34,6 +34,8 @@ The Capabilities page applies the selected profile to both setup config and runt
 
 ### OpenClaw onboard
 
+After OpenClaw onboard completes—or when the user explicitly skips it—local setup runs the pinned gateway CLI's non-interactive baseline initializer against the final runtime workspace, then writes fixed Windows-node guidance into a setup-owned managed section of that workspace's `AGENTS.md`. The section is replaced idempotently between markers, preserves user-authored `AGENTS.md` content and file permissions outside those markers, and does not modify OpenClaw source files. This helps the initial companion-app OpenClaw session know to use the Windows node / `nodes` tool for Windows desktop, files, screenshots, camera, notifications, browser proxy, and Windows command tasks.
+
 Renders server-defined setup steps via RPC (`wizard.start` / `wizard.next`). The gateway controls the flow — steps can be:
 - **Note** — informational messages
 - **Confirm** — yes/no decisions
diff --git a/docs/WINDOWS_NODE_TESTING.md b/docs/WINDOWS_NODE_TESTING.md
index 121df574f..2a2c1a888 100644
--- a/docs/WINDOWS_NODE_TESTING.md
+++ b/docs/WINDOWS_NODE_TESTING.md
@@ -12,6 +12,14 @@ The Windows Node feature allows the tray app to receive commands from the OpenCl
 4. Toggle "Enable Node Mode" ON
 5. Click Save
 
+## Companion-App Setup Guidance
+
+For app-owned local WSL setup, after OpenClaw onboard completes or is explicitly skipped, setup runs the pinned gateway CLI's non-interactive baseline initializer against the final runtime workspace and then injects fixed Windows-node guidance into that workspace's `AGENTS.md`. The injected block is setup-owned and idempotently replaced between managed markers, preserving user-authored content and file permissions outside those markers and leaving OpenClaw source files unchanged.
+
+**Note on the apply script's WSL invocation.** The `WindowsNodeBootstrapContextStep` apply and rollback scripts are piped to `bash -s` via stdin (`RunInWslAsync(..., inputViaStdin: true)`) rather than the default `bash -c` argv path. This is required because `wsl.exe` performs shell variable expansion on argv before invoking bash, which would drop user-defined `$var` references in the multi-line script (`workspace='...'` followed by `mkdir -p "$workspace"` becomes `mkdir -p ""`). See `docs/WSL_EXE_ARGV_PITFALL.md` for the full writeup.
+
+The guidance helps the first companion-app OpenClaw session route Windows desktop, files, screenshots, camera, notifications, browser proxy, and Windows command tasks through the Windows node / `nodes` tool.
+
 ## What You Can Test Now
 
 ### Agent-driven UI and MCP validation
diff --git a/docs/WSL_EXE_ARGV_PITFALL.md b/docs/WSL_EXE_ARGV_PITFALL.md
new file mode 100644
index 000000000..aee6d6977
--- /dev/null
+++ b/docs/WSL_EXE_ARGV_PITFALL.md
@@ -0,0 +1,134 @@
+# WSL.exe argv variable-expansion pitfall
+
+## Summary
+
+`wsl.exe -- bash -c <script>` expands shell-variable references in argv before invoking `bash`, so Bash receives an already-mutated script string; any `$var` or `${var}` not defined in the Windows process environment at `wsl.exe` invocation time is dropped to an empty string.
+
+## Reproduction
+
+```powershell
+function Invoke-Wsl([string[]]$arr) {
+  $psi = New-Object System.Diagnostics.ProcessStartInfo
+  $psi.FileName = "wsl.exe"
+  $psi.RedirectStandardOutput = $true
+  $psi.RedirectStandardError = $true
+  $psi.UseShellExecute = $false
+  $psi.CreateNoWindow = $true
+  foreach ($a in $arr) { [void]$psi.ArgumentList.Add($a) }
+  $p = [System.Diagnostics.Process]::Start($psi)
+  $out = $p.StandardOutput.ReadToEnd()
+  $err = $p.StandardError.ReadToEnd()
+  $p.WaitForExit()
+  "EXIT=$($p.ExitCode) STDOUT=[$out] STDERR=[$err]"
+}
+
+# BROKEN: argv path — $x is dropped before bash sees it
+Invoke-Wsl @("-d","Ubuntu-26.04","--","bash","-c","x=abc; echo VAL=`$x")
+# → EXIT=0 STDOUT=[VAL=]  ← assignment ran, but $x was already expanded to empty
+
+# WORKING: stdin path — script bytes arrive at bash intact
+$psi = New-Object System.Diagnostics.ProcessStartInfo
+$psi.FileName = "wsl.exe"
+$psi.RedirectStandardOutput = $true
+$psi.RedirectStandardInput = $true
+$psi.UseShellExecute = $false
+foreach ($a in @("-d","Ubuntu-26.04","--","bash","-s")) { [void]$psi.ArgumentList.Add($a) }
+$p = [System.Diagnostics.Process]::Start($psi)
+$p.StandardInput.WriteLine("x=abc; echo VAL=`$x")
+$p.StandardInput.Close()
+$p.StandardOutput.ReadToEnd()
+# → VAL=abc
+```
+
+## What bash actually receives
+
+Empirical results from dumping `/proc/$$/cmdline` inside Bash on a fresh Ubuntu-26.04 WSL distro:
+
+| Pattern in script string | What bash actually receives |
+|---|---|
+| `$PATH` (defined in Windows env at `wsl.exe` invocation time) | the full Windows `PATH` expansion |
+| `$workspace` (not defined in Windows env) | **removed (empty)** |
+| `${workspace}` braced (not defined in Windows env) | **removed (empty)** |
+| `$$` | `wsl.exe` parent process's PID, not the Bash PID |
+| `\$workspace` backslash-escaped | preserved as `$workspace`; Bash then expands it normally |
+| `$(echo hi)` command substitution | preserved; Bash expands it |
+| Single-quoted `'$workspace'` | still expanded; single quotes do not help because `wsl.exe` runs before Bash |
+| Double-quoted `"$workspace"` | still expanded |
+| Subshell `( workspace=x; echo $workspace )` | the inner `$workspace` is still dropped |
+| Prefix assignment `x=abc echo $x` | `$x` is still dropped |
+
+Concrete failure mode:
+
+```bash
+workspace='/home/openclaw/.openclaw/workspace'
+mkdir -p "$workspace"   # → mkdir: cannot create directory '': No such file or directory
+```
+
+The assignment runs because it has no `$var` reference, but `$workspace` on the next line is removed during `wsl.exe` argv translation.
+
+## Why
+
+`wsl.exe`'s argv translation layer treats argv strings as command-line text and performs shell metacharacter expansion before launching the target process. By the time `bash -c` runs, the original `$var` syntax is gone and Bash cannot recover it. This behavior is consistent across single quotes, double quotes, braces, subshells, and prefix assignment because they are all interpreted by `wsl.exe` before Bash sees the script.
+
+## Fixes (in order of preference)
+
+### 1. Pipe the script over stdin via `RunInWslAsync(..., inputViaStdin: true)`
+
+`wsl.exe` does not rewrite stdin. Prefer this for any multi-line script that uses Bash variables, `${...}`, or `$$`.
+
+```csharp
+var script = """
+workspace='/home/openclaw/.openclaw/workspace'
+mkdir -p "$workspace"
+printf 'bash pid=%s\n' "$$"
+""";
+
+await commandRunner.RunInWslAsync(
+    distroName,
+    script,
+    cancellationToken,
+    inputViaStdin: true);
+```
+
+### 2. C#-interpolate every value into the script string
+
+Do not store values in Bash variables; bake the values into the script literally. This is the workaround used by `src/OpenClaw.SetupEngine/SetupSteps.cs:936-945` in `ValidateWslLockdownStep`. It is acceptable for short scripts with a small fixed value set and no spaces in values.
+
+```csharp
+var workspace = "/home/openclaw/.openclaw/workspace";
+var script = $"mkdir -p {workspace} && test -d {workspace}";
+
+await commandRunner.RunInWslAsync(distroName, script, cancellationToken);
+```
+
+### 3. Backslash-escape `\$var`
+
+Escaping the dollar sign preserves it through `wsl.exe` and lets Bash expand it later.
+
+```powershell
+wsl.exe -d Ubuntu-26.04 -- bash -c "x=abc; echo VAL=\`$x"
+```
+
+This works for single isolated references, but it is fragile and easy to miss in any non-trivial script. Treat it as a last resort.
+
+## What does NOT work
+
+All of these failed workarounds were verified empirically:
+
+- **Single quotes** — `'$workspace'` is still rewritten before Bash sees the quotes.
+- **Double quotes** — `"$workspace"` is also rewritten before Bash sees the quotes.
+- **Braces** — `${workspace}` is removed just like `$workspace`.
+- **Subshells** — `( workspace=x; echo $workspace )` still loses the inner `$workspace`.
+- **Prefix assignment** — `x=abc echo $x` still expands `$x` before the assignment can matter.
+- **`-e VAR=val` flag forwarding** — forwarded environment values do not prevent argv rewriting before Bash receives the script.
+- **Switching to `/bin/sh`** — the mutation happens in `wsl.exe`, before any shell starts.
+
+## Where this matters in the codebase
+
+- `src/OpenClaw.SetupEngine/CommandRunner.cs` — `RunInWslAsync` exposes the opt-in `inputViaStdin` parameter.
+- `src/OpenClaw.SetupEngine/SetupSteps.cs:936-945` — `ValidateWslLockdownStep` uses workaround #2, C# interpolation.
+- `src/OpenClaw.SetupEngine/SetupSteps.cs` `WindowsNodeBootstrapContextStep` — uses workaround #1, stdin.
+
+## Related
+
+- `docs/XAML_COMPILER_BUG.md` — sibling footgun doc for XAML compiler crashes.
diff --git a/src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs b/src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs
index 66c8c746c..1b075bc48 100644
--- a/src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs
+++ b/src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs
@@ -316,6 +316,7 @@ private void Onboard_Click(object sender, RoutedEventArgs e)
     private static List<SetupStep> BuildSteps(SetupConfig config)
         => SetupStepFactory.BuildDefaultSteps()
             .Where(step => step is not RunGatewayWizardStep)
+            .Where(step => config.SkipWizard || step is not WindowsNodeBootstrapContextStep)
             .ToList();
 }
 
diff --git a/src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs b/src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs
index 0f93569ed..2d440b996 100644
--- a/src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs
+++ b/src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs
@@ -27,6 +27,7 @@ public sealed partial class WizardPage : Page
     private WizardStepCategory _stepCategory = WizardStepCategory.Acknowledge;
     private bool _sensitive;
     private bool _errorState;
+    private bool _finalizationErrorState;
     private int _operationGeneration;
     private int _wizardStepCount;
     private int _progressPolls;
@@ -104,6 +105,7 @@ private async Task StartWizardAsync(bool clearTranscript = true)
         try
         {
             _errorState = false;
+            _finalizationErrorState = false;
             HideRecoveryActions();
             // Cancel any in-progress server-side wizard session before starting a
             // fresh one, so the gateway doesn't reject wizard.start with "wizard
@@ -236,8 +238,7 @@ private async Task ApplyPayloadAsync(JsonElement payload)
                 if (generation != _operationGeneration || _errorState)
                     return;
 
-                // Permissions are collected before install, so the wizard completes straight to summary.
-                SetupWindow.Active?.NavigateToComplete(true, TimeSpan.Zero, _config!.LogPath);
+                await CompleteSetupAsync(generation);
                 return;
             }
 
@@ -514,6 +515,14 @@ private async Task PrimaryClickAsync()
     {
         if (_errorState)
         {
+            if (_finalizationErrorState)
+            {
+                _errorState = false;
+                _finalizationErrorState = false;
+                await CompleteSetupAsync(_operationGeneration);
+                return;
+            }
+
             await StartWizardAsync();
             return;
         }
@@ -1008,6 +1017,7 @@ private void SetBusy(string status)
     private void ShowError(string message)
     {
         _errorState = true;
+        _finalizationErrorState = false;
         BusyRing.Visibility = Visibility.Collapsed;
         BusyRing.IsActive = false;
         StatusText.Text = "Wizard needs attention";
@@ -1021,6 +1031,14 @@ private void ShowError(string message)
         MaybeShowGatewayRecovery();
     }
 
+    private void ShowFinalizationError(string message)
+    {
+        ShowError(message);
+        _finalizationErrorState = true;
+        StatusText.Text = "Windows integration needs attention";
+        PrimaryButton.Content = "Retry Windows integration";
+    }
+
     private async Task EnterWizardErrorAsync(string detail)
     {
         if (_errorState)
@@ -1140,13 +1158,36 @@ private async Task RestartGatewayAsync()
 
     private async Task SkipWizardAsync()
     {
-        AdvanceOperationGeneration();
+        var generation = AdvanceOperationGeneration();
+        _errorState = false;
         HideRecoveryActions();
         SetBusy("Skipping wizard...");
         await CancelCurrentSessionAsync();
-        // Permissions were already collected before install, so skipping OpenClaw
-        // onboard completes straight to the summary.
-        SetupWindow.Active?.NavigateToComplete(true, TimeSpan.Zero, _config!.LogPath);
+        await CompleteSetupAsync(generation);
+    }
+
+    private async Task CompleteSetupAsync(int generation)
+    {
+        if (generation != _operationGeneration || _errorState)
+            return;
+
+        var setupWindow = SetupWindow.Active;
+        if (setupWindow is null or { IsClosed: true })
+            return;
+
+        SetBusy("Finishing Windows integration...");
+        var contextResult = await setupWindow.ApplyWindowsNodeContextAsync();
+        if (generation != _operationGeneration || setupWindow.IsClosed)
+            return;
+
+        if (!contextResult.IsSuccess)
+        {
+            ShowFinalizationError($"OpenClaw onboard finished, but Windows node guidance could not be installed: {contextResult.Message}");
+            return;
+        }
+
+        // Permissions were collected before install, so completion goes straight to summary.
+        setupWindow.NavigateToComplete(true, TimeSpan.Zero, _config!.LogPath);
     }
 
     private async Task CancelCurrentSessionAsync()
diff --git a/src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs b/src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs
index 93433c962..46c69bbc9 100644
--- a/src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs
+++ b/src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs
@@ -13,8 +13,12 @@ public sealed partial class SetupWindow : Window
 {
     private SetupConfig _config = null!;
     private SetupRunLock? _setupLock;
+    private readonly CancellationTokenSource _lifetimeCts = new();
+    private Task<StepResult>? _contextApplyTask;
     private readonly TaskCompletionSource<bool> _initialContentReady =
         new(TaskCreationOptions.RunContinuationsAsynchronously);
+    private readonly TaskCompletionSource<bool> _cleanupCompleted =
+        new(TaskCreationOptions.RunContinuationsAsynchronously);
     private bool _isClosed;
     private bool _persistStartupPreferenceOnComplete = true;
     private bool _showStartupPreferenceOnComplete = true;
@@ -26,6 +30,7 @@ public sealed partial class SetupWindow : Window
     public event EventHandler? AdvancedSetupRequested;
     public event EventHandler<SetupCompletedEventArgs>? SetupCompleted;
     public bool IsClosed => _isClosed;
+    public Task CleanupCompleted => _cleanupCompleted.Task;
     internal string DataDir => _dataDir;
     internal string LocalDataDir => _localDataDir;
     public bool CanNavigateToWizard =>
@@ -109,14 +114,32 @@ public SetupWindow(
             _showStartupPreferenceOnComplete = false;
         }
 
-        Closed += (_, _) =>
+        Closed += async (_, _) =>
         {
             _isClosed = true;
             _initialContentReady.TrySetResult(true);
-            _setupLock?.Dispose();
-            _setupLock = null;
-            if (ReferenceEquals(Active, this))
-                Active = null;
+            try
+            {
+                _lifetimeCts.Cancel();
+                if (_contextApplyTask is { } contextApplyTask)
+                    await contextApplyTask;
+            }
+            catch (OperationCanceledException)
+            {
+                // Window teardown owns this cancellation; cleanup still must finish.
+            }
+            catch (Exception ex)
+            {
+                System.Diagnostics.Debug.WriteLine($"Setup cleanup failed: {ex}");
+            }
+            finally
+            {
+                _setupLock?.Dispose();
+                _setupLock = null;
+                if (ReferenceEquals(Active, this))
+                    Active = null;
+                _cleanupCompleted.TrySetResult(true);
+            }
         };
 
         var previewPage = SetupPreview.RequestedPage;
@@ -168,6 +191,52 @@ public bool TryNavigateToWizard(bool back = false)
         return true;
     }
 
+    internal async Task<StepResult> ApplyWindowsNodeContextAsync()
+    {
+        if (_contextApplyTask is { } existingTask)
+            return await existingTask;
+
+        _contextApplyTask = ApplyWindowsNodeContextCoreAsync();
+        try
+        {
+            return await _contextApplyTask;
+        }
+        finally
+        {
+            _contextApplyTask = null;
+        }
+    }
+
+    private async Task<StepResult> ApplyWindowsNodeContextCoreAsync()
+    {
+        if (!_config.WindowsNodeContext.Enabled)
+            return StepResult.Skip("Windows node context injection disabled");
+
+        var ct = _lifetimeCts.Token;
+        using var logger = new SetupLogger(filePath: null);
+        using var journal = new TransactionJournal(filePath: null, logger);
+        var context = new SetupContext(
+            _config,
+            logger,
+            journal,
+            new CommandRunner(logger),
+            ct,
+            _dataDir,
+            _localDataDir);
+        // This is an idempotent refresh after onboarding, not a transactional
+        // install. A failed refresh must not remove a valid block from an earlier run.
+        var pipeline = new SetupPipeline(
+            [new WindowsNodeBootstrapContextStep()],
+            rollbackOnFailureOverride: false);
+        var result = await pipeline.RunAsync(context);
+        return result.Outcome switch
+        {
+            PipelineOutcome.Success => StepResult.Ok("Windows node context injected"),
+            PipelineOutcome.Cancelled => StepResult.Fail("Windows node context injection was cancelled"),
+            _ => StepResult.Fail(result.Message ?? "Windows node context injection failed")
+        };
+    }
+
     public void NavigateToComplete(bool success, TimeSpan elapsed, string? logPath, string? errorMessage = null)
         => NavigateTo(
             typeof(CompletePage),
diff --git a/src/OpenClaw.SetupEngine/CommandRunner.cs b/src/OpenClaw.SetupEngine/CommandRunner.cs
index e60fa89d8..99f8ff027 100644
--- a/src/OpenClaw.SetupEngine/CommandRunner.cs
+++ b/src/OpenClaw.SetupEngine/CommandRunner.cs
@@ -18,13 +18,52 @@ Task<CommandResult> RunAsync(
         string? stdinInput = null,
         CancellationToken ct = default);
 
+    /// <summary>
+    /// Run a command inside a WSL distro.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// By default (<paramref name="inputViaStdin"/> = false) the script is passed
+    /// as argv to <c>wsl.exe -- bash -c &lt;script&gt;</c>. wsl.exe performs shell
+    /// variable expansion on argv before invoking bash, which drops any
+    /// <c>$var</c> or <c>${var}</c> reference that is not defined in the Windows
+    /// process environment. See <c>docs/WSL_EXE_ARGV_PITFALL.md</c> for the full
+    /// writeup.
+    /// </para>
+    /// <para>
+    /// For multi-line scripts that use bash variables, set
+    /// <paramref name="inputViaStdin"/> to <c>true</c>. The script is then piped
+    /// to <c>bash -s</c> via stdin, which wsl.exe does not touch.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Safe: bash variables survive because the script arrives via stdin.
+    /// await runner.RunInWslAsync(distro, """
+    ///     workspace='/home/me/ws'
+    ///     mkdir -p "$workspace"
+    ///     """, TimeSpan.FromSeconds(15), inputViaStdin: true);
+    /// </code>
+    /// </example>
+    /// <param name="distroName">The WSL distribution name passed to <c>wsl.exe -d</c>.</param>
+    /// <param name="command">The bash script or command to run.</param>
+    /// <param name="timeout">The maximum time to wait before killing the process.</param>
+    /// <param name="environment">Optional environment variables to forward into WSL via WSLENV.</param>
+    /// <param name="ct">A cancellation token for aborting the process.</param>
+    /// <param name="user">Optional WSL user passed to <c>wsl.exe -u</c>.</param>
+    /// <param name="inputViaStdin">
+    /// When true, the script is piped to <c>bash -s</c> via stdin instead of
+    /// being passed as argv to <c>bash -c</c>. Use this for any multi-line
+    /// script that uses bash variables or <c>$$</c>.
+    /// </param>
     Task<CommandResult> RunInWslAsync(
         string distroName,
         string command,
         TimeSpan timeout,
         IReadOnlyDictionary<string, string>? environment = null,
         CancellationToken ct = default,
-        string? user = null);
+        string? user = null,
+        bool inputViaStdin = false);
 }
 
 public sealed class CommandRunner : ICommandRunner
@@ -147,13 +186,49 @@ public async Task<CommandResult> RunAsync(
     /// <summary>
     /// Run a command inside a WSL distro.
     /// </summary>
+    /// <remarks>
+    /// <para>
+    /// By default (<paramref name="inputViaStdin"/> = false) the script is passed
+    /// as argv to <c>wsl.exe -- bash -c &lt;script&gt;</c>. wsl.exe performs shell
+    /// variable expansion on argv before invoking bash, which drops any
+    /// <c>$var</c> or <c>${var}</c> reference that is not defined in the Windows
+    /// process environment. See <c>docs/WSL_EXE_ARGV_PITFALL.md</c> for the full
+    /// writeup.
+    /// </para>
+    /// <para>
+    /// For multi-line scripts that use bash variables, set
+    /// <paramref name="inputViaStdin"/> to <c>true</c>. The script is then piped
+    /// to <c>bash -s</c> via stdin, which wsl.exe does not touch.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Safe: bash variables survive because the script arrives via stdin.
+    /// await runner.RunInWslAsync(distro, """
+    ///     workspace='/home/me/ws'
+    ///     mkdir -p "$workspace"
+    ///     """, TimeSpan.FromSeconds(15), inputViaStdin: true);
+    /// </code>
+    /// </example>
+    /// <param name="distroName">The WSL distribution name passed to <c>wsl.exe -d</c>.</param>
+    /// <param name="command">The bash script or command to run.</param>
+    /// <param name="timeout">The maximum time to wait before killing the process.</param>
+    /// <param name="environment">Optional environment variables to forward into WSL via WSLENV.</param>
+    /// <param name="ct">A cancellation token for aborting the process.</param>
+    /// <param name="user">Optional WSL user passed to <c>wsl.exe -u</c>.</param>
+    /// <param name="inputViaStdin">
+    /// When true, the script is piped to <c>bash -s</c> via stdin instead of
+    /// being passed as argv to <c>bash -c</c>. Use this for any multi-line
+    /// script that uses bash variables or <c>$$</c>.
+    /// </param>
     public Task<CommandResult> RunInWslAsync(
         string distroName,
         string command,
         TimeSpan timeout,
         IReadOnlyDictionary<string, string>? environment = null,
         CancellationToken ct = default,
-        string? user = null)
+        string? user = null,
+        bool inputViaStdin = false)
     {
         // Strip Windows \r to avoid bash "$'\r': command not found" errors
         command = command.Replace("\r", "");
@@ -166,7 +241,10 @@ public Task<CommandResult> RunInWslAsync(
             args.Add(user);
         }
 
-        args.AddRange(["--", "bash", "-c", command]);
+        if (inputViaStdin)
+            args.AddRange(["--", "bash", "-s"]);
+        else
+            args.AddRange(["--", "bash", "-c", command]);
 
         // Pass WSL environment variables via WSLENV
         Dictionary<string, string>? env = null;
@@ -179,6 +257,9 @@ public Task<CommandResult> RunInWslAsync(
                 : wslEnvKeys;
         }
 
+        if (inputViaStdin)
+            return RunAsync("wsl.exe", args.ToArray(), timeout, env, stdinInput: command, ct: ct);
+
         return RunAsync("wsl.exe", args.ToArray(), timeout, env, ct: ct);
     }
 
diff --git a/src/OpenClaw.SetupEngine/Program.cs b/src/OpenClaw.SetupEngine/Program.cs
index 65d85ec2b..c3fe59054 100644
--- a/src/OpenClaw.SetupEngine/Program.cs
+++ b/src/OpenClaw.SetupEngine/Program.cs
@@ -147,7 +147,7 @@ public static async Task<int> Main(string[] args)
         }
         else if (wizardOnly)
         {
-            steps = [new RunGatewayWizardStep()];
+            steps = SetupStepFactory.BuildWizardOnlySteps();
         }
         else
         {
diff --git a/src/OpenClaw.SetupEngine/SetupContext.cs b/src/OpenClaw.SetupEngine/SetupContext.cs
index 2743a1966..1a3589916 100644
--- a/src/OpenClaw.SetupEngine/SetupContext.cs
+++ b/src/OpenClaw.SetupEngine/SetupContext.cs
@@ -33,6 +33,7 @@ public sealed class SetupConfig
     public CapabilitiesConfig Capabilities { get; set; } = new();
     public TraySettingsConfig Settings { get; set; } = new();
     public PairingConfig Pairing { get; set; } = new();
+    public WindowsNodeContextConfig WindowsNodeContext { get; set; } = new();
 
     public string EffectiveGatewayUrl => GatewayUrl ?? $"ws://localhost:{GatewayPort}";
 
@@ -288,6 +289,15 @@ public sealed class PairingConfig
     public int TimeoutSeconds { get; set; } = 60;
 }
 
+// ─── Windows Node Context Injection ───
+
+public sealed class WindowsNodeContextConfig
+{
+    public bool Enabled { get; set; } = true;
+    public string? WorkspacePath { get; set; }
+    public int TimeoutSeconds { get; set; } = 180;
+}
+
 // ─── Step Result ───
 
 public enum StepOutcome { Success, Skipped, Failed, FailedTerminal }
diff --git a/src/OpenClaw.SetupEngine/SetupPipeline.cs b/src/OpenClaw.SetupEngine/SetupPipeline.cs
index e8ce757fc..7b5fa3204 100644
--- a/src/OpenClaw.SetupEngine/SetupPipeline.cs
+++ b/src/OpenClaw.SetupEngine/SetupPipeline.cs
@@ -38,6 +38,12 @@ public sealed record StepProgressEvent(string StepId, string DisplayName, StepOu
 
 public static class SetupStepFactory
 {
+    public static List<SetupStep> BuildWizardOnlySteps() =>
+    [
+        new RunGatewayWizardStep(),
+        new WindowsNodeBootstrapContextStep(),
+    ];
+
     public static List<SetupStep> BuildDefaultSteps()
     {
         return
@@ -60,6 +66,7 @@ public static List<SetupStep> BuildDefaultSteps()
             new PairNodeStep(),
             new VerifyEndToEndStep(),
             new RunGatewayWizardStep(),
+            new WindowsNodeBootstrapContextStep(),
             new StartKeepaliveStep(),
         ];
     }
@@ -71,12 +78,14 @@ public sealed class SetupPipeline
 {
     private readonly List<SetupStep> _steps;
     private readonly List<SetupStep> _completedSteps = new();
+    private readonly bool? _rollbackOnFailureOverride;
 
     public event EventHandler<StepProgressEvent>? StepProgress;
 
-    public SetupPipeline(IEnumerable<SetupStep> steps)
+    public SetupPipeline(IEnumerable<SetupStep> steps, bool? rollbackOnFailureOverride = null)
     {
         _steps = steps.ToList();
+        _rollbackOnFailureOverride = rollbackOnFailureOverride;
     }
 
     public async Task<PipelineResult> RunAsync(SetupContext ctx)
@@ -169,7 +178,7 @@ public async Task<PipelineResult> RunAsync(SetupContext ctx)
             else
                 ctx.Logger.Warn($"SetupPipeline: Step '{step.Id}' failed: {result.Message}");
 
-            if (ctx.Config.RollbackOnFailure)
+            if (_rollbackOnFailureOverride ?? ctx.Config.RollbackOnFailure)
             {
                 await RollbackFailedStep(step, ctx);
                 await RollbackCompletedSteps(ctx);
diff --git a/src/OpenClaw.SetupEngine/SetupSteps.cs b/src/OpenClaw.SetupEngine/SetupSteps.cs
index d70dbafc3..0ce5a36d8 100644
--- a/src/OpenClaw.SetupEngine/SetupSteps.cs
+++ b/src/OpenClaw.SetupEngine/SetupSteps.cs
@@ -1025,9 +1025,15 @@ public override async Task<StepResult> ExecuteAsync(SetupContext ctx, Cancellati
         };
 
         // Generate per-directory checks inline (no bash variables).
-        // wsl.exe -- bash -c mangles double-quotes and bash $var references,
-        // so we avoid both: paths have no spaces (safe unquoted) and all
-        // values are C#-interpolated rather than stored in bash variables.
+        // wsl.exe argv variable-expansion pitfall: see docs/WSL_EXE_ARGV_PITFALL.md.
+        // `wsl.exe -- bash -c <script>` performs shell-variable expansion on argv
+        // before bash sees it, so any $var that isn't defined in the Windows env
+        // gets dropped. This step works around the issue by C#-interpolating every
+        // value into the script string (no bash variables) — that pattern is fine
+        // for short scripts with a small fixed value set and no spaces in values.
+        // New multi-line callers should prefer the stdin path:
+        //   ctx.Commands.RunInWslAsync(..., inputViaStdin: true)
+        // which pipes the script via `bash -s` stdin and bypasses the issue entirely.
         var dirChecks = new System.Text.StringBuilder();
         foreach (var d in requiredDirs)
         {
@@ -2728,6 +2734,628 @@ public override Task RollbackAsync(SetupContext ctx, CancellationToken ct)
     }
 }
 
+internal sealed record WindowsNodeContextTarget(string DistroName, string User, string WorkspacePath);
+
+internal sealed class WindowsNodeContextInstallState
+{
+    public List<WindowsNodeContextTarget> Targets { get; set; } = [];
+}
+
+public sealed class WindowsNodeBootstrapContextStep : SetupStep
+{
+    private const string InstallStateFileName = "windows-node-context.json";
+    private WindowsNodeContextTarget? _currentTarget;
+    private bool _currentTargetWasNew;
+    private bool _executeAttempted;
+
+    public override string Id => "windows-node-context";
+    public override string DisplayName => "Inject Windows node context";
+
+    public override bool CanSkip(SetupContext ctx) => !ctx.Config.WindowsNodeContext.Enabled;
+
+    public override async Task<StepResult> ExecuteAsync(SetupContext ctx, CancellationToken ct)
+    {
+        _executeAttempted = true;
+        var distro = ctx.DistroName!;
+        var user = ctx.Config.Wsl.User;
+        var timeout = TimeSpan.FromSeconds(Math.Max(1, ctx.Config.WindowsNodeContext.TimeoutSeconds));
+
+        var home = await ResolveLinuxHomeAsync(ctx, distro, user, ct);
+        if (home is null)
+            return StepResult.Fail("Could not resolve Linux home directory for openclaw user");
+
+        // Resolve before baseline setup and pass the same absolute path to both
+        // setup and injection. The managed gateway starts from this user's home,
+        // so relative configured paths are home-relative rather than caller-cwd-relative.
+        var workspace = await ResolveWorkspacePathAsync(ctx, distro, user, home, ct);
+        if (string.IsNullOrWhiteSpace(workspace))
+            return StepResult.Fail("Could not resolve OpenClaw agent workspace path");
+
+        var workspaceOverride = ctx.Config.WindowsNodeContext.WorkspacePath?.Trim();
+        var runBaselineSetup = !string.IsNullOrWhiteSpace(workspaceOverride);
+        if (!runBaselineSetup)
+        {
+            var defaultWorkspace = await ResolveConfiguredDefaultWorkspacePathAsync(ctx, distro, user, home, ct);
+            if (string.IsNullOrWhiteSpace(defaultWorkspace))
+                return StepResult.Fail("Could not resolve OpenClaw default workspace path");
+
+            runBaselineSetup = string.Equals(
+                workspace.TrimEnd('/'),
+                defaultWorkspace.TrimEnd('/'),
+                StringComparison.Ordinal);
+        }
+
+        // Per-agent workspaces are already initialized by onboarding/agents add.
+        // Running global setup for one would rewrite agents.defaults.workspace.
+        if (runBaselineSetup)
+        {
+            var setupResult = await RunOpenclawSetupAsync(ctx, distro, user, workspace, ct);
+            if (!setupResult.IsSuccess)
+                return setupResult;
+        }
+
+        var target = new WindowsNodeContextTarget(distro, user, workspace);
+        try
+        {
+            _currentTargetWasNew = await RecordAppliedTargetAsync(ctx, target, ct);
+            _currentTarget = target;
+        }
+        catch (Exception ex)
+        {
+            return StepResult.Fail($"Could not persist Windows node context install state: {ex.Message}", ex);
+        }
+
+        var script = BuildApplyScript(workspace);
+        // Uses stdin to bypass wsl.exe argv variable-expansion (see docs/WSL_EXE_ARGV_PITFALL.md).
+        var result = await ctx.Commands.RunInWslAsync(distro, script, timeout, ct: ct, user: user, inputViaStdin: true);
+
+        if (result.ExitCode != 0 || !result.Stdout.Contains("WINDOWS_NODE_CONTEXT_READY", StringComparison.Ordinal))
+        {
+            if (_currentTargetWasNew && result.ExitCode is 2 or 4)
+            {
+                try
+                {
+                    await RemoveRecordedTargetAsync(ctx, target, ct);
+                    _currentTarget = null;
+                    _currentTargetWasNew = false;
+                }
+                catch (Exception ex)
+                {
+                    return StepResult.Fail(
+                        $"Windows node context injection failed and install-state cleanup also failed: {ex.Message}",
+                        ex);
+                }
+            }
+
+            return StepResult.Fail($"Windows node context injection failed (exit {result.ExitCode}): {FirstNonEmpty(result.Stderr, result.Stdout)}");
+        }
+
+        ctx.Logger.Info($"Windows node context injected into workspace: {workspace}");
+        return StepResult.Ok("Windows node context injected");
+    }
+
+    public override async Task RollbackAsync(SetupContext ctx, CancellationToken ct)
+    {
+        var timeout = TimeSpan.FromSeconds(Math.Max(1, ctx.Config.WindowsNodeContext.TimeoutSeconds));
+        var hasInstallState = File.Exists(InstallStatePath(ctx));
+        WindowsNodeContextTarget[] targets;
+        if (_currentTarget is { } current)
+        {
+            targets = [current];
+        }
+        else if (_executeAttempted)
+        {
+            // Failed-step rollback for an attempt that never modified a target.
+            // Do not reinterpret this as a fresh uninstall of earlier installs.
+            return;
+        }
+        else if (hasInstallState)
+        {
+            var state = await ReadInstallStateAsync(ctx, ct);
+            targets = state.Targets.ToArray();
+        }
+        else
+        {
+            var legacyTarget = await ResolveLegacyUninstallTargetAsync(ctx, ct);
+            targets = legacyTarget is null ? [] : [legacyTarget];
+        }
+        if (targets.Length == 0)
+            return;
+
+        var failures = new List<string>();
+        foreach (var target in targets)
+        {
+            // Uses stdin to bypass wsl.exe argv variable-expansion (see docs/WSL_EXE_ARGV_PITFALL.md).
+            var result = await ctx.Commands.RunInWslAsync(
+                target.DistroName,
+                BuildRollbackScript(target.WorkspacePath),
+                timeout,
+                ct: ct,
+                user: target.User,
+                inputViaStdin: true);
+
+            if (result.ExitCode != 0 && !IsMissingDistroResult(result))
+            {
+                failures.Add(
+                    $"{target.DistroName}:{target.WorkspacePath} (exit {result.ExitCode}): " +
+                    FirstNonEmpty(result.Stderr, result.Stdout));
+            }
+        }
+
+        if (failures.Count > 0)
+            throw new InvalidOperationException("Windows node context cleanup failed: " + string.Join("; ", failures));
+
+        if (_currentTarget is { } appliedTarget)
+        {
+            await RemoveRecordedTargetAsync(ctx, appliedTarget, ct);
+        }
+        else
+        {
+            File.Delete(InstallStatePath(ctx));
+        }
+    }
+
+    private static async Task<WindowsNodeContextTarget?> ResolveLegacyUninstallTargetAsync(
+        SetupContext ctx,
+        CancellationToken ct)
+    {
+        var distro = ctx.DistroName;
+        if (string.IsNullOrWhiteSpace(distro))
+            return null;
+
+        var user = ctx.Config.Wsl.User;
+        var (home, result) = await QueryLinuxHomeAsync(ctx, distro, user, ct);
+        if (home is null)
+        {
+            if (IsMissingDistroResult(result))
+                return null;
+            throw new InvalidOperationException(
+                "Could not resolve Linux home directory while cleaning legacy Windows node context: " +
+                FirstNonEmpty(result.Stderr, result.Stdout));
+        }
+
+        var workspace = await ResolveWorkspacePathAsync(ctx, distro, user, home, ct);
+        if (string.IsNullOrWhiteSpace(workspace))
+            throw new InvalidOperationException("Could not resolve workspace while cleaning legacy Windows node context");
+
+        return new WindowsNodeContextTarget(distro, user, workspace);
+    }
+
+    internal static string InstallStatePath(SetupContext ctx) =>
+        Path.Combine(ctx.LocalDataDir, InstallStateFileName);
+
+    internal static async Task<bool> RecordAppliedTargetAsync(
+        SetupContext ctx,
+        WindowsNodeContextTarget target,
+        CancellationToken ct)
+    {
+        var state = await ReadInstallStateAsync(ctx, ct);
+        var exists = state.Targets.Contains(target);
+        if (exists)
+            return false;
+
+        state.Targets.Add(target);
+        var json = JsonSerializer.Serialize(state, SetupConfig.JsonWriteOptions);
+        await AtomicFile.WriteAllTextAsync(InstallStatePath(ctx), json, ct);
+        return true;
+    }
+
+    internal static async Task<WindowsNodeContextInstallState> ReadInstallStateAsync(
+        SetupContext ctx,
+        CancellationToken ct)
+    {
+        var path = InstallStatePath(ctx);
+        if (!File.Exists(path))
+            return new WindowsNodeContextInstallState();
+
+        var json = await File.ReadAllTextAsync(path, ct);
+        var state = JsonSerializer.Deserialize<WindowsNodeContextInstallState>(json, SetupConfig.JsonOptions)
+            ?? throw new InvalidDataException("Windows node context install state is empty");
+        if (state.Targets.Any(target =>
+                string.IsNullOrWhiteSpace(target.DistroName) ||
+                string.IsNullOrWhiteSpace(target.User) ||
+                string.IsNullOrWhiteSpace(target.WorkspacePath) ||
+                !target.WorkspacePath.StartsWith('/')))
+        {
+            throw new InvalidDataException("Windows node context install state contains an invalid target");
+        }
+
+        return state;
+    }
+
+    private static async Task RemoveRecordedTargetAsync(
+        SetupContext ctx,
+        WindowsNodeContextTarget target,
+        CancellationToken ct)
+    {
+        var state = await ReadInstallStateAsync(ctx, ct);
+        state.Targets.RemoveAll(candidate => candidate == target);
+        if (state.Targets.Count == 0)
+        {
+            File.Delete(InstallStatePath(ctx));
+            return;
+        }
+
+        var json = JsonSerializer.Serialize(state, SetupConfig.JsonWriteOptions);
+        await AtomicFile.WriteAllTextAsync(InstallStatePath(ctx), json, ct);
+    }
+
+    internal static bool IsMissingDistroResult(CommandResult result)
+    {
+        if (result.ExitCode == 0)
+            return false;
+
+        var output = FirstNonEmpty(result.Stderr, result.Stdout);
+        return output.Contains("There is no distribution with the supplied name", StringComparison.OrdinalIgnoreCase) ||
+               output.Contains("WSL_E_DISTRO_NOT_FOUND", StringComparison.OrdinalIgnoreCase);
+    }
+
+    internal static async Task<string?> ResolveLinuxHomeAsync(SetupContext ctx, string distro, string user, CancellationToken ct)
+    {
+        var (home, _) = await QueryLinuxHomeAsync(ctx, distro, user, ct);
+        return home;
+    }
+
+    internal static async Task<(string? Home, CommandResult Result)> QueryLinuxHomeAsync(
+        SetupContext ctx,
+        string distro,
+        string user,
+        CancellationToken ct)
+    {
+        var result = await ctx.Commands.RunInWslAsync(
+            distro,
+            "getent passwd \"$(id -un)\" | cut -d: -f6",
+            TimeSpan.FromSeconds(15),
+            ct: ct,
+            user: user);
+
+        if (result.ExitCode != 0)
+            return (null, result);
+
+        var home = result.Stdout
+            .Split(['\r', '\n'], StringSplitOptions.RemoveEmptyEntries)
+            .Select(line => line.Trim())
+            .FirstOrDefault(line => line.Length > 0 && line.StartsWith('/'));
+
+        return (string.IsNullOrWhiteSpace(home) ? null : home, result);
+    }
+
+    internal static async Task<StepResult> RunOpenclawSetupAsync(SetupContext ctx, string distro, string user, string workspaceAbsolute, CancellationToken ct)
+    {
+        var workspaceArg = ShellEscape(workspaceAbsolute);
+
+        // The pinned 2026.6.11 CLI uses plain `setup` for baseline initialization;
+        // newer/custom CLIs require `--baseline`. Detect the installed contract.
+        var script = $"""
+            set -e
+            {ctx.WslPathPrefix}
+            if openclaw setup --help 2>&1 | grep -q -- '--baseline'; then
+                openclaw setup --baseline --workspace {workspaceArg} >/dev/null
+            else
+                openclaw setup --workspace {workspaceArg} >/dev/null
+            fi
+            """;
+        // Uses stdin to bypass wsl.exe argv variable-expansion (the script's
+        // PATH prefix references $PATH, which would be expanded to the
+        // Windows PATH on the argv path). See docs/WSL_EXE_ARGV_PITFALL.md.
+        var result = await ctx.Commands.RunInWslAsync(
+            distro,
+            script,
+            TimeSpan.FromSeconds(Math.Max(30, ctx.Config.WindowsNodeContext.TimeoutSeconds / 2)),
+            ct: ct,
+            user: user,
+            inputViaStdin: true);
+
+        if (result.ExitCode != 0)
+            return StepResult.Fail($"openclaw setup failed (exit {result.ExitCode}): {FirstNonEmpty(result.Stderr, result.Stdout)}");
+
+        return StepResult.Ok();
+    }
+
+    internal static async Task<string?> ResolveWorkspacePathAsync(SetupContext ctx, string distro, string user, string home, CancellationToken ct)
+    {
+        var workspaceOverride = ctx.Config.WindowsNodeContext.WorkspacePath?.Trim();
+        if (!string.IsNullOrWhiteSpace(workspaceOverride))
+            return ExpandLinuxPath(workspaceOverride, home);
+
+        // `agents list` resolves per-agent overrides and returns the effective
+        // workspace used by the default/main chat agent.
+        var script = $"{ctx.WslPathPrefix}\nopenclaw agents list --json";
+        // Uses stdin to bypass wsl.exe argv variable-expansion (the script's
+        // PATH prefix references $PATH). See docs/WSL_EXE_ARGV_PITFALL.md.
+        var result = await ctx.Commands.RunInWslAsync(
+            distro,
+            script,
+            TimeSpan.FromSeconds(15),
+            ct: ct,
+            user: user,
+            inputViaStdin: true);
+
+        if (result.TimedOut || result.ExitCode != 0)
+            return null;
+
+        var raw = ExtractDefaultAgentWorkspaceFromAgentsOutput(result.Stdout);
+        return string.IsNullOrWhiteSpace(raw) ? null : ExpandLinuxPath(raw, home);
+    }
+
+    internal static async Task<string?> ResolveConfiguredDefaultWorkspacePathAsync(
+        SetupContext ctx,
+        string distro,
+        string user,
+        string home,
+        CancellationToken ct)
+    {
+        var script = $"{ctx.WslPathPrefix}\nopenclaw config get agents.defaults.workspace --json";
+        var result = await ctx.Commands.RunInWslAsync(
+            distro,
+            script,
+            TimeSpan.FromSeconds(15),
+            ct: ct,
+            user: user,
+            inputViaStdin: true);
+
+        if (result.TimedOut)
+            return null;
+
+        var raw = ExtractWorkspaceFromConfigOutput(result.Stdout);
+        if (result.ExitCode != 0)
+        {
+            // Pinned 2026.6.11 reports an absent key with exit 1. Only that
+            // known case may select the default; other read failures must not
+            // be persisted by the subsequent `setup --workspace` call.
+            if (!result.Stderr.Contains(
+                    "Config path not found: agents.defaults.workspace",
+                    StringComparison.Ordinal))
+                return null;
+
+            raw = $"{home.TrimEnd('/')}/.openclaw/workspace";
+        }
+        else if (string.IsNullOrWhiteSpace(raw))
+        {
+            // A present JSON null uses OpenClaw's default. Empty or malformed
+            // successful output is an operational failure, not evidence that
+            // the key is absent.
+            if (!result.Stdout
+                    .Split(['\r', '\n'], StringSplitOptions.RemoveEmptyEntries)
+                    .Any(line => string.Equals(line.Trim(), "null", StringComparison.Ordinal)))
+                return null;
+
+            raw = $"{home.TrimEnd('/')}/.openclaw/workspace";
+        }
+
+        return ExpandLinuxPath(raw, home);
+    }
+
+    internal static string? ExtractDefaultAgentWorkspaceFromAgentsOutput(string stdout)
+    {
+        if (string.IsNullOrWhiteSpace(stdout))
+            return null;
+
+        var lines = stdout.Split(['\r', '\n'], StringSplitOptions.None);
+        for (var i = 0; i < lines.Length; i++)
+        {
+            var trimmed = lines[i].TrimStart();
+            if (!trimmed.StartsWith('['))
+                continue;
+
+            var candidate = string.Join('\n', lines.Skip(i));
+            var end = candidate.LastIndexOf(']');
+            if (end < 0)
+                continue;
+
+            try
+            {
+                using var document = JsonDocument.Parse(candidate[..(end + 1)]);
+                if (document.RootElement.ValueKind != JsonValueKind.Array)
+                    continue;
+
+                JsonElement? main = null;
+                foreach (var agent in document.RootElement.EnumerateArray())
+                {
+                    if (agent.ValueKind != JsonValueKind.Object)
+                        continue;
+
+                    if (agent.TryGetProperty("isDefault", out var isDefault) &&
+                        isDefault.ValueKind == JsonValueKind.True)
+                    {
+                        main = agent;
+                        break;
+                    }
+
+                    if (main is null &&
+                        agent.TryGetProperty("id", out var id) &&
+                        string.Equals(id.GetString(), "main", StringComparison.OrdinalIgnoreCase))
+                        main = agent;
+                }
+
+                if (main is { } selected &&
+                    selected.TryGetProperty("workspace", out var workspace) &&
+                    workspace.ValueKind == JsonValueKind.String)
+                    return workspace.GetString();
+            }
+            catch (JsonException)
+            {
+                // Keep scanning in case a warning line started with '['.
+            }
+        }
+
+        return null;
+    }
+
+    internal static string? ExtractWorkspaceFromConfigOutput(string stdout)
+    {
+        if (string.IsNullOrWhiteSpace(stdout))
+            return null;
+
+        // openclaw config get --json prints a JSON value; warnings may be on stderr (suppressed)
+        // or as banner lines on stdout. Walk lines from bottom to find a usable value.
+        var lines = stdout
+            .Split(['\r', '\n'], StringSplitOptions.None)
+            .Select(line => line.Trim())
+            .Where(line => line.Length > 0)
+            .ToArray();
+
+        for (var i = lines.Length - 1; i >= 0; i--)
+        {
+            var candidate = lines[i];
+            // Try JSON string parse first
+            if (candidate.StartsWith('"') && candidate.EndsWith('"'))
+            {
+                try
+                {
+                    return System.Text.Json.JsonSerializer.Deserialize<string>(candidate);
+                }
+                catch (System.Text.Json.JsonException)
+                {
+                    continue;
+                }
+            }
+
+            if (candidate == "null")
+                continue;
+
+            // Plain string (non-JSON output)
+            if (candidate.StartsWith('/') || candidate.StartsWith('~'))
+                return candidate;
+        }
+
+        return null;
+    }
+
+    internal static string ExpandLinuxPath(string path, string home)
+    {
+        var trimmed = path.Trim();
+        if (string.IsNullOrWhiteSpace(trimmed) || trimmed == "null" || trimmed == "undefined")
+            return $"{home.TrimEnd('/')}/.openclaw/workspace";
+
+        if (trimmed == "~")
+            return home;
+        if (trimmed.StartsWith("~/", StringComparison.Ordinal))
+            return $"{home.TrimEnd('/')}/{trimmed[2..]}";
+        if (trimmed.StartsWith('/'))
+            return trimmed;
+        return $"{home.TrimEnd('/')}/{trimmed}";
+    }
+
+    internal static string BuildApplyScript(string absoluteWorkspacePath)
+        => $$"""
+            set -e
+            set -o pipefail
+            workspace={{ShellEscape(absoluteWorkspacePath)}}
+            agents="$workspace/AGENTS.md"
+            block_b64={{ShellEscape(ManagedBlockBase64())}}
+            begin_marker={{ShellEscape(WindowsNodeContextSection.BeginMarker)}}
+            end_marker={{ShellEscape(WindowsNodeContextSection.EndMarker)}}
+            if [ -L "$agents" ]; then
+                echo "AGENTS_SYMLINK:$agents" >&2
+                exit 2
+            fi
+            if [ ! -f "$agents" ]; then
+                mkdir -p "$workspace"
+                : > "$agents"
+                echo "WINDOWS_NODE_CONTEXT_BOOTSTRAP_FALLBACK:$agents"
+            fi
+            begin_count=$(awk -v M="$begin_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) count++ } END { print count + 0 }' "$agents")
+            end_count=$(awk -v M="$end_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) count++ } END { print count + 0 }' "$agents")
+            if [ "$begin_count" -gt 1 ] || [ "$end_count" -gt 1 ] || [ "$begin_count" != "$end_count" ]; then
+                echo "WINDOWS_NODE_CONTEXT_MARKERS_MALFORMED:$agents" >&2
+                exit 4
+            fi
+            if [ "$begin_count" = 1 ]; then
+                begin_line=$(awk -v M="$begin_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) { print NR; exit } }' "$agents")
+                end_line=$(awk -v M="$end_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) { print NR; exit } }' "$agents")
+                if [ "$end_line" -lt "$begin_line" ]; then
+                    echo "WINDOWS_NODE_CONTEXT_MARKERS_MALFORMED:$agents" >&2
+                    exit 4
+                fi
+            fi
+            tmp=$(mktemp "$workspace/.AGENTS.md.openclaw.XXXXXX")
+            trap 'rm -f -- "$tmp"' EXIT
+            awk -v BEGIN_M="$begin_marker" -v END_M="$end_marker" '
+              BEGIN { in_block = 0 }
+              { marker_line = $0; sub(/\r$/, "", marker_line) }
+              marker_line == BEGIN_M { in_block = 1; next }
+              in_block && marker_line == END_M { in_block = 0; next }
+              in_block { next }
+              /^[[:space:]]*$/ { blank = blank $0 ORS; next }
+              { printf "%s%s%s", blank, $0, ORS; blank = "" }
+            ' "$agents" > "$tmp"
+            if [ -s "$tmp" ]; then
+                printf '\n' >> "$tmp"
+            fi
+            printf '%s' "$block_b64" | base64 -d >> "$tmp"
+            printf '\n' >> "$tmp"
+            chmod --reference="$agents" "$tmp"
+            mv -- "$tmp" "$agents"
+            trap - EXIT
+            echo "WINDOWS_NODE_CONTEXT_WORKSPACE:$workspace"
+            echo "WINDOWS_NODE_CONTEXT_READY"
+            """;
+
+    internal static string BuildRollbackScript(string absoluteWorkspacePath)
+        => $$"""
+            set -e
+            set -o pipefail
+            workspace={{ShellEscape(absoluteWorkspacePath)}}
+            agents="$workspace/AGENTS.md"
+            begin_marker={{ShellEscape(WindowsNodeContextSection.BeginMarker)}}
+            end_marker={{ShellEscape(WindowsNodeContextSection.EndMarker)}}
+            if [ ! -e "$agents" ]; then
+                echo "WINDOWS_NODE_CONTEXT_ABSENT"
+                exit 0
+            fi
+            if [ -L "$agents" ]; then
+                echo "AGENTS_SYMLINK_ROLLBACK_SKIPPED:$agents"
+                exit 5
+            fi
+            begin_count=$(awk -v M="$begin_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) count++ } END { print count + 0 }' "$agents")
+            end_count=$(awk -v M="$end_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) count++ } END { print count + 0 }' "$agents")
+            if [ "$begin_count" = 0 ] && [ "$end_count" = 0 ]; then
+                echo "WINDOWS_NODE_CONTEXT_REMOVED"
+                exit 0
+            fi
+            if [ "$begin_count" != 1 ] || [ "$end_count" != 1 ]; then
+                echo "WINDOWS_NODE_CONTEXT_MARKERS_MALFORMED:$agents" >&2
+                exit 4
+            fi
+            begin_line=$(awk -v M="$begin_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) { print NR; exit } }' "$agents")
+            end_line=$(awk -v M="$end_marker" '{ marker_line=$0; sub(/\r$/, "", marker_line); if (marker_line == M) { print NR; exit } }' "$agents")
+            if [ "$end_line" -lt "$begin_line" ]; then
+                echo "WINDOWS_NODE_CONTEXT_MARKERS_MALFORMED:$agents" >&2
+                exit 4
+            fi
+            tmp=$(mktemp "$workspace/.AGENTS.md.openclaw.XXXXXX")
+            trap 'rm -f -- "$tmp"' EXIT
+            awk -v BEGIN_M="$begin_marker" -v END_M="$end_marker" '
+              BEGIN { in_block = 0 }
+              { marker_line = $0; sub(/\r$/, "", marker_line) }
+              marker_line == BEGIN_M { in_block = 1; next }
+              in_block && marker_line == END_M { in_block = 0; next }
+              in_block { next }
+              { print }
+            ' "$agents" > "$tmp"
+            chmod --reference="$agents" "$tmp"
+            mv -- "$tmp" "$agents"
+            trap - EXIT
+            echo "WINDOWS_NODE_CONTEXT_REMOVED"
+            """;
+
+    private static string ManagedBlockBase64()
+        => Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(WindowsNodeContextSection.ManagedBlock));
+
+    private static string ShellEscape(string value) => "'" + value.Replace("'", "'\\''") + "'";
+
+    private static string FirstNonEmpty(params string[] values)
+        => values.Select(v => v.Trim()).FirstOrDefault(v => v.Length > 0) ?? "no output";
+
+    private static string? ReadMarkerValue(string output, string marker)
+        => output
+            .Split(['\r', '\n'], StringSplitOptions.RemoveEmptyEntries)
+            .Select(line => line.Trim())
+            .FirstOrDefault(line => line.StartsWith(marker, StringComparison.Ordinal))
+            ?[marker.Length..];
+}
+
 public sealed class VerifyEndToEndStep : SetupStep
 {
     public override string Id => "verify-e2e";
diff --git a/src/OpenClaw.SetupEngine/WindowsNodeContextSection.cs b/src/OpenClaw.SetupEngine/WindowsNodeContextSection.cs
new file mode 100644
index 000000000..7af849a59
--- /dev/null
+++ b/src/OpenClaw.SetupEngine/WindowsNodeContextSection.cs
@@ -0,0 +1,15 @@
+namespace OpenClaw.SetupEngine;
+
+internal static class WindowsNodeContextSection
+{
+    public const string BeginMarker = "<!-- BEGIN OPENCLAW WINDOWS NODE CONTEXT: managed by OpenClaw Windows setup -->";
+    public const string EndMarker = "<!-- END OPENCLAW WINDOWS NODE CONTEXT -->";
+
+    public const string Payload = """
+This WSL gateway may be paired with the OpenClaw Windows tray node. For Windows desktop, Windows files, screenshots, camera, notifications, browser proxy, or Windows commands, use the `nodes` tool (`status` / `describe`) and target the Windows node instead of assuming the WSL shell can do it.
+
+For Windows shell work, use `exec host=node` / `system.run`; normal gateway exec runs in WSL. If Windows node commands fail, ask the user to check the tray Permissions page: Node mode, System run (or the requested capability), and Exec policy. If settings changed or capabilities look stale, ask the user to reconnect/restart the Windows node or gateway.
+""";
+
+    public static string ManagedBlock => $"{BeginMarker}\n{Payload.TrimEnd()}\n{EndMarker}";
+}
diff --git a/src/OpenClaw.SetupEngine/default-config.json b/src/OpenClaw.SetupEngine/default-config.json
index b5c38c028..1c375084f 100644
--- a/src/OpenClaw.SetupEngine/default-config.json
+++ b/src/OpenClaw.SetupEngine/default-config.json
@@ -127,5 +127,15 @@
   "Pairing": {
     // Max seconds to wait for pairing handshake
     "TimeoutSeconds": 60
+  },
+
+  // ─── Windows Node Context Injection ───
+  // Inject setup-owned guidance into the final OpenClaw runtime workspace AGENTS.md.
+  "WindowsNodeContext": {
+    "Enabled": true,
+    // Optional WSL workspace path override; null = let the pinned gateway CLI's baseline setup use its configured/default workspace.
+    "WorkspacePath": null,
+    // Seconds allowed for OpenClaw workspace seeding and AGENTS.md context injection.
+    "TimeoutSeconds": 180
   }
 }
diff --git a/src/OpenClaw.Tray.WinUI/App.xaml.cs b/src/OpenClaw.Tray.WinUI/App.xaml.cs
index 9f25e29e6..abbc39cda 100644
--- a/src/OpenClaw.Tray.WinUI/App.xaml.cs
+++ b/src/OpenClaw.Tray.WinUI/App.xaml.cs
@@ -3711,13 +3711,20 @@ private async Task ShowOnboardingAsync()
         if (_settings == null)
             return (null, false);
 
-        if (_setupWindow != null)
+        while (_setupWindow != null)
         {
             var existingSetupWindow = _setupWindow;
             await existingSetupWindow.WaitForInitialContentReadyAsync();
-            if (ReferenceEquals(_setupWindow, existingSetupWindow) && !existingSetupWindow.IsClosed)
-                existingSetupWindow.BringToFrontForSetupLaunch();
-            return (existingSetupWindow, false);
+            if (!existingSetupWindow.IsClosed)
+            {
+                if (ReferenceEquals(_setupWindow, existingSetupWindow))
+                    existingSetupWindow.BringToFrontForSetupLaunch();
+                return (existingSetupWindow, false);
+            }
+
+            await existingSetupWindow.CleanupCompleted;
+            if (ReferenceEquals(_setupWindow, existingSetupWindow))
+                _setupWindow = null;
         }
 
         try
@@ -3732,8 +3739,9 @@ private async Task ShowOnboardingAsync()
             _setupWindow = setupWindow;
             setupWindow.AdvancedSetupRequested += OnSetupAdvancedSetupRequested;
             setupWindow.SetupCompleted += OnSetupCompleted;
-            setupWindow.Closed += (_, _) =>
+            setupWindow.Closed += async (_, _) =>
             {
+                await setupWindow.CleanupCompleted;
                 if (ReferenceEquals(_setupWindow, setupWindow))
                     _setupWindow = null;
             };
diff --git a/tests/OpenClaw.E2ETests/Setup/E2ESetupFixture.cs b/tests/OpenClaw.E2ETests/Setup/E2ESetupFixture.cs
index c2e072c32..507cfecc2 100644
--- a/tests/OpenClaw.E2ETests/Setup/E2ESetupFixture.cs
+++ b/tests/OpenClaw.E2ETests/Setup/E2ESetupFixture.cs
@@ -478,7 +478,8 @@ private Process SpawnTray(string exePath)
     public async Task<OpenClaw.SetupEngine.CommandResult> RunInWslAsync(
         string command,
         TimeSpan? timeout = null,
-        IReadOnlyDictionary<string, string>? environment = null)
+        IReadOnlyDictionary<string, string>? environment = null,
+        bool inputViaStdin = false)
     {
         command = command.Replace("\r", "");
         Log($"WSL command: {SanitizeForLog(command)}");
@@ -489,6 +490,7 @@ private Process SpawnTray(string exePath)
             UseShellExecute = false,
             RedirectStandardOutput = true,
             RedirectStandardError = true,
+            RedirectStandardInput = inputViaStdin,
             CreateNoWindow = true,
         };
 
@@ -496,8 +498,9 @@ private Process SpawnTray(string exePath)
         psi.ArgumentList.Add(_distroName);
         psi.ArgumentList.Add("--");
         psi.ArgumentList.Add("bash");
-        psi.ArgumentList.Add("-c");
-        psi.ArgumentList.Add(command);
+        psi.ArgumentList.Add(inputViaStdin ? "-s" : "-c");
+        if (!inputViaStdin)
+            psi.ArgumentList.Add(command);
 
         if (environment is { Count: > 0 })
         {
@@ -515,6 +518,13 @@ private Process SpawnTray(string exePath)
         using var process = Process.Start(psi)
             ?? throw new InvalidOperationException("Failed to start wsl.exe");
 
+        if (inputViaStdin)
+        {
+            await process.StandardInput.WriteAsync(command);
+            await process.StandardInput.WriteAsync("\n");
+            process.StandardInput.Close();
+        }
+
         var stdoutTask = process.StandardOutput.ReadToEndAsync();
         var stderrTask = process.StandardError.ReadToEndAsync();
         var timedOut = false;
diff --git a/tests/OpenClaw.E2ETests/Setup/SetupAndConnectTests.cs b/tests/OpenClaw.E2ETests/Setup/SetupAndConnectTests.cs
index b39c21545..2d8a07eae 100644
--- a/tests/OpenClaw.E2ETests/Setup/SetupAndConnectTests.cs
+++ b/tests/OpenClaw.E2ETests/Setup/SetupAndConnectTests.cs
@@ -99,6 +99,15 @@ public async Task FullSetup_WslAndGatewayConfiguration_FilesValidated()
         Assert.Contains("default=openclaw", wslConf.Stdout);
         Assert.Contains("useWindowsTimezone=true", wslConf.Stdout);
 
+        var agentsContext = await _fixture.RunInWslAsync(
+            "cat /home/openclaw/.openclaw/workspace/AGENTS.md",
+            TimeSpan.FromSeconds(15));
+        AssertCommandSucceeded(agentsContext, "read managed Windows node context");
+        Assert.Contains("<!-- BEGIN OPENCLAW WINDOWS NODE CONTEXT: managed by OpenClaw Windows setup -->", agentsContext.Stdout);
+        Assert.Contains("exec host=node", agentsContext.Stdout);
+        Assert.Contains("<!-- END OPENCLAW WINDOWS NODE CONTEXT -->", agentsContext.Stdout);
+        Assert.DoesNotContain("tools.exec.security full", agentsContext.Stdout);
+
         var openClawJsonProbe = await _fixture.RunInWslAsync(
             "paths=$(find /home/openclaw/.openclaw /opt/openclaw /etc/openclaw -type f -name openclaw.json 2>/dev/null | sort); if [ -z \"$paths\" ]; then echo 'OPENCLAW_JSON_PATH:<not-found>'; else for path in $paths; do echo OPENCLAW_JSON_PATH:$path; cat \"$path\"; done; fi",
             TimeSpan.FromSeconds(15));
@@ -154,6 +163,41 @@ public async Task FullSetup_WslAndGatewayConfiguration_FilesValidated()
         Assert.Contains(Directory.EnumerateFiles(identityDir), path => Path.GetFileName(path).Contains("device-key", StringComparison.OrdinalIgnoreCase));
     }
 
+    [E2EFact]
+    public async Task FullSetup_WindowsNodeContext_RemainsIdempotentAfterCrlfEdit()
+    {
+        const string agents = "/home/openclaw/.openclaw/workspace/AGENTS.md";
+        const string beginMarker = "<!-- BEGIN OPENCLAW WINDOWS NODE CONTEXT: managed by OpenClaw Windows setup -->";
+        const string endMarker = "<!-- END OPENCLAW WINDOWS NODE CONTEXT -->";
+        var convert = await _fixture.RunInWslAsync(
+            $"tmp=$(mktemp); {{ printf 'CRLF_SENTINEL\\r\\n'; awk '{{ printf \"%s\\r\\n\", $0 }}' {agents}; }} > \"$tmp\"; mv \"$tmp\" {agents}",
+            TimeSpan.FromSeconds(15),
+            inputViaStdin: true);
+        AssertCommandSucceeded(convert, "convert AGENTS.md to CRLF");
+
+        var config = SetupConfig.LoadFromFile(_fixture.ConfigPath);
+        using var logger = new SetupLogger(filePath: null);
+        using var journal = new TransactionJournal(filePath: null, logger);
+        var context = new SetupContext(
+            config,
+            logger,
+            journal,
+            new CommandRunner(logger),
+            CancellationToken.None,
+            _fixture.DataDir,
+            _fixture.LocalAppDataRoot);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(context, CancellationToken.None);
+        Assert.True(result.IsSuccess, result.Message);
+
+        var probe = await _fixture.RunInWslAsync(
+            $"awk 'BEGIN {{ b=0; e=0 }} {{ line=$0; sub(/\\r$/, \"\", line); if (line == \"{beginMarker}\") b++; if (line == \"{endMarker}\") e++ }} END {{ print b, e }}' {agents}; grep -q $'CRLF_SENTINEL\\r$' {agents}",
+            TimeSpan.FromSeconds(15),
+            inputViaStdin: true);
+        AssertCommandSucceeded(probe, "verify CRLF context replacement");
+        Assert.Contains("1 1", probe.Stdout);
+    }
+
     [E2EFact]
     public async Task FullSetup_TrayStartsWslKeepAlive()
     {
diff --git a/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs b/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs
index bab5a27c9..77bed545c 100644
--- a/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs
+++ b/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs
@@ -34,6 +34,9 @@ public void Defaults_AreReasonable()
         Assert.Equal("loopback", config.Gateway.Bind);
         Assert.False(config.SkipPermissions);
         Assert.False(config.SkipWizard);
+        Assert.True(config.WindowsNodeContext.Enabled);
+        Assert.Null(config.WindowsNodeContext.WorkspacePath);
+        Assert.Equal(180, config.WindowsNodeContext.TimeoutSeconds);
     }
 
     [Fact]
@@ -391,6 +394,19 @@ public void PairingConfig_Defaults()
         Assert.Equal(60, pairing.TimeoutSeconds);
     }
 
+    [Fact]
+    public void WindowsNodeContextSection_ManagedBlock_ContainsMarkersAndPayload()
+    {
+        var block = WindowsNodeContextSection.ManagedBlock;
+
+        Assert.StartsWith(WindowsNodeContextSection.BeginMarker + "\n", block);
+        Assert.Contains("This WSL gateway may be paired", block);
+        Assert.Contains("exec host=node", block);
+        Assert.DoesNotContain("tools.exec.security full", block);
+        Assert.DoesNotContain("tools.exec.ask off", block);
+        Assert.EndsWith("\n" + WindowsNodeContextSection.EndMarker, block);
+    }
+
     [Fact]
     public void StepResult_Ok_IsSuccess()
     {
diff --git a/tests/OpenClaw.SetupEngine.Tests/SetupPipelineTests.cs b/tests/OpenClaw.SetupEngine.Tests/SetupPipelineTests.cs
index eb12523d1..2a90b2ac0 100644
--- a/tests/OpenClaw.SetupEngine.Tests/SetupPipelineTests.cs
+++ b/tests/OpenClaw.SetupEngine.Tests/SetupPipelineTests.cs
@@ -60,7 +60,7 @@ public void BuildDefaultSteps_IncludesCurrentSetupFlow()
     {
         var steps = SetupStepFactory.BuildDefaultSteps();
 
-        Assert.Equal(19, steps.Count);
+        Assert.Equal(20, steps.Count);
         Assert.IsType<PreflightOsStep>(steps[0]);
         Assert.IsType<PreflightWslStep>(steps[1]);
         Assert.IsType<CleanupStaleDistroStep>(steps[2]);
@@ -70,9 +70,24 @@ public void BuildDefaultSteps_IncludesCurrentSetupFlow()
         var cliInstallIndex = steps.FindIndex(s => s is InstallCliStep);
         Assert.Equal(cliInstallIndex - 1, caSyncIndex);
         Assert.Contains(steps, s => s is RunGatewayWizardStep);
+        var pairNodeIndex = steps.FindIndex(s => s is PairNodeStep);
+        Assert.IsType<VerifyEndToEndStep>(steps[pairNodeIndex + 1]);
+        var wizardIndex = steps.FindIndex(s => s is RunGatewayWizardStep);
+        Assert.IsType<WindowsNodeBootstrapContextStep>(steps[wizardIndex + 1]);
         Assert.IsType<StartKeepaliveStep>(steps[^1]);
     }
 
+    [Fact]
+    public void BuildWizardOnlySteps_FinalizesWindowsNodeContextAfterWizard()
+    {
+        var steps = SetupStepFactory.BuildWizardOnlySteps();
+
+        Assert.Collection(
+            steps,
+            step => Assert.IsType<RunGatewayWizardStep>(step),
+            step => Assert.IsType<WindowsNodeBootstrapContextStep>(step));
+    }
+
     [Fact]
     public async Task RunAsync_StepFails_ReturnsFailed()
     {
@@ -210,6 +225,26 @@ public async Task RunAsync_StepFails_WithoutRollbackConfig_NoRollback()
         Assert.False(rollbackCalled);
     }
 
+    [Fact]
+    public async Task RunAsync_StepFails_WithRollbackOverrideDisabled_NoRollback()
+    {
+        var rollbackCalled = false;
+        var config = new SetupConfig { RollbackOnFailure = true };
+        var ctx = CreateContext(config);
+        var pipeline = new SetupPipeline([
+            new MockStep(
+                "refresh",
+                (_, _) => Task.FromResult(StepResult.Fail("refresh failed")),
+                (_, _) => { rollbackCalled = true; return Task.CompletedTask; }),
+        ], rollbackOnFailureOverride: false);
+
+        var result = await pipeline.RunAsync(ctx);
+
+        Assert.Equal(PipelineOutcome.Failed, result.Outcome);
+        Assert.False(rollbackCalled);
+        Assert.True(config.RollbackOnFailure);
+    }
+
     [Fact]
     public async Task RunAsync_SkippableStep_IsSkipped()
     {
diff --git a/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs b/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs
index 384881e72..e18d70b8d 100644
--- a/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs
+++ b/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs
@@ -1624,6 +1624,609 @@ public async Task SyncWindowsCaCerts_RollbackFailureIsPropagated()
         Assert.Contains("remove failed", error.Message, StringComparison.Ordinal);
     }
 
+    [Fact]
+    public void WindowsNodeContext_CanSkipWhenDisabled()
+    {
+        var ctx = CreateContext(new SetupConfig
+        {
+            WindowsNodeContext = new WindowsNodeContextConfig { Enabled = false }
+        });
+
+        Assert.True(new WindowsNodeBootstrapContextStep().CanSkip(ctx));
+    }
+
+    [Fact]
+    public void WindowsNodeContext_BuildApplyScript_UsesAbsolutePathAndMinimalShape()
+    {
+        var script = WindowsNodeBootstrapContextStep.BuildApplyScript("/home/openclaw/.openclaw/workspace");
+
+        Assert.Contains("set -o pipefail", script);
+        Assert.Contains("workspace='/home/openclaw/.openclaw/workspace'", script);
+        Assert.Contains("AGENTS_SYMLINK:$agents", script);
+        Assert.Contains("mkdir -p \"$workspace\"", script);
+        Assert.Contains(": > \"$agents\"", script);
+        Assert.Contains("WINDOWS_NODE_CONTEXT_BOOTSTRAP_FALLBACK", script);
+        Assert.Contains("awk -v BEGIN_M=\"$begin_marker\" -v END_M=\"$end_marker\"", script);
+        Assert.Contains("printf '%s' \"$block_b64\" | base64 -d >> \"$tmp\"", script);
+        Assert.Contains("mktemp \"$workspace/.AGENTS.md.openclaw.XXXXXX\"", script);
+        Assert.Contains("chmod --reference=\"$agents\" \"$tmp\"", script);
+        Assert.Contains("sub(/\\r$/, \"\", marker_line)", script);
+        Assert.Contains("WINDOWS_NODE_CONTEXT_MARKERS_MALFORMED", script);
+        Assert.Contains("WINDOWS_NODE_CONTEXT_READY", script);
+        // Must not depend on node or carry an embedded JS payload.
+        Assert.DoesNotContain(" node ", script);
+        Assert.DoesNotContain(" node -", script);
+        Assert.DoesNotContain("apply_js_b64", script);
+        Assert.DoesNotContain("openclaw setup", script);
+        Assert.DoesNotContain("openclaw config get", script);
+        Assert.DoesNotContain("AGENTS_MISSING_AFTER_SETUP", script);
+        Assert.DoesNotContain("$HOME", script);
+        Assert.DoesNotContain("case \"$candidate\"", script);
+        Assert.DoesNotContain("<<'NODE'", script);
+        Assert.DoesNotContain("OPENCLAW_GATEWAY_TOKEN", script);
+    }
+
+    [Fact]
+    public void WindowsNodeContext_BuildRollbackScript_UsesAbsolutePathAndMinimalShape()
+    {
+        var script = WindowsNodeBootstrapContextStep.BuildRollbackScript("/home/openclaw/.openclaw/workspace");
+
+        Assert.Contains("set -o pipefail", script);
+        Assert.Contains("workspace='/home/openclaw/.openclaw/workspace'", script);
+        Assert.Contains("awk -v BEGIN_M=\"$begin_marker\" -v END_M=\"$end_marker\"", script);
+        Assert.Contains("mktemp \"$workspace/.AGENTS.md.openclaw.XXXXXX\"", script);
+        Assert.Contains("chmod --reference=\"$agents\" \"$tmp\"", script);
+        Assert.Contains("sub(/\\r$/, \"\", marker_line)", script);
+        Assert.Contains("WINDOWS_NODE_CONTEXT_ABSENT", script);
+        Assert.Contains("WINDOWS_NODE_CONTEXT_REMOVED", script);
+        Assert.Contains("AGENTS_SYMLINK_ROLLBACK_SKIPPED:$agents", script);
+        Assert.Contains("exit 5", script);
+        // Must not depend on node or carry an embedded JS payload.
+        Assert.DoesNotContain(" node ", script);
+        Assert.DoesNotContain(" node -", script);
+        Assert.DoesNotContain("rollback_js_b64", script);
+        Assert.DoesNotContain("openclaw setup", script);
+        Assert.DoesNotContain("openclaw config get", script);
+        Assert.DoesNotContain("rm -f \"$agents\"", script);
+        Assert.DoesNotContain("$HOME", script);
+        Assert.DoesNotContain("case \"$candidate\"", script);
+        Assert.DoesNotContain("<<'NODE'", script);
+    }
+
+    [Theory]
+    [InlineData("/home/openclaw/.openclaw/workspace", "/home/openclaw", "/home/openclaw/.openclaw/workspace")]
+    [InlineData("~", "/home/openclaw", "/home/openclaw")]
+    [InlineData("~/.openclaw/custom workspace", "/home/openclaw", "/home/openclaw/.openclaw/custom workspace")]
+    [InlineData("relative/path", "/home/openclaw", "/home/openclaw/relative/path")]
+    [InlineData("", "/home/openclaw", "/home/openclaw/.openclaw/workspace")]
+    [InlineData("null", "/home/openclaw", "/home/openclaw/.openclaw/workspace")]
+    [InlineData("undefined", "/home/openclaw", "/home/openclaw/.openclaw/workspace")]
+    [InlineData("/abs/path", "/home/openclaw/", "/abs/path")]
+    [InlineData("~/x", "/home/openclaw/", "/home/openclaw/x")]
+    public void WindowsNodeContext_ExpandLinuxPath_ResolvesCorrectly(string input, string home, string expected)
+    {
+        Assert.Equal(expected, WindowsNodeBootstrapContextStep.ExpandLinuxPath(input, home));
+    }
+
+    [Theory]
+    [InlineData("\"/home/openclaw/.openclaw/workspace\"\n", "/home/openclaw/.openclaw/workspace")]
+    [InlineData("Config warnings:\n- plugins.entries.device-pair\n\"/home/openclaw/.openclaw/workspace\"\n", "/home/openclaw/.openclaw/workspace")]
+    [InlineData("\"~/.openclaw/workspace\"\n", "~/.openclaw/workspace")]
+    [InlineData("/home/openclaw/.openclaw/workspace\n", "/home/openclaw/.openclaw/workspace")]
+    [InlineData("null\n", null)]
+    [InlineData("", null)]
+    public void WindowsNodeContext_ExtractWorkspaceFromConfigOutput_ParsesValues(string stdout, string? expected)
+    {
+        Assert.Equal(expected, WindowsNodeBootstrapContextStep.ExtractWorkspaceFromConfigOutput(stdout));
+    }
+
+    [Theory]
+    [InlineData("[{\"id\":\"main\",\"workspace\":\"/home/openclaw/main\",\"isDefault\":true}]", "/home/openclaw/main")]
+    [InlineData("Warning\n[\n  {\"id\":\"other\",\"workspace\":\"/home/openclaw/other\",\"isDefault\":false},\n  {\"id\":\"primary\",\"workspace\":\"/home/openclaw/primary\",\"isDefault\":true}\n]\n", "/home/openclaw/primary")]
+    [InlineData("[{\"id\":\"main\",\"workspace\":\"~/main\"}]", "~/main")]
+    [InlineData("not json", null)]
+    public void WindowsNodeContext_ExtractDefaultAgentWorkspace_ParsesCanonicalAgentsList(string stdout, string? expected)
+    {
+        Assert.Equal(expected, WindowsNodeBootstrapContextStep.ExtractDefaultAgentWorkspaceFromAgentsOutput(stdout));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_RunsInWslAsConfiguredUserAndResolvesWorkspace()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("openclaw setup"))
+                    return Ok("");
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("\"~/.openclaw/workspace\"\n");
+                if (command.Contains("WINDOWS_NODE_CONTEXT_READY"))
+                    return Ok(string.Join("\n",
+                        "WINDOWS_NODE_CONTEXT_BOOTSTRAP_FALLBACK:/home/openclaw/.openclaw/workspace/AGENTS.md",
+                        "WINDOWS_NODE_CONTEXT_WORKSPACE:/home/openclaw/.openclaw/workspace",
+                        "WINDOWS_NODE_CONTEXT_READY",
+                        ""));
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.Equal(5, commands.WslCalls.Count);
+        Assert.All(commands.WslCalls, c =>
+        {
+            Assert.Equal("OpenClawGateway", c.DistroName);
+            Assert.Equal("openclaw", c.User);
+        });
+        Assert.Contains("getent passwd", commands.WslCalls[0].Command);
+        Assert.Contains("openclaw agents list --json", commands.WslCalls[1].Command);
+        Assert.Contains("openclaw config get agents.defaults.workspace", commands.WslCalls[2].Command);
+        Assert.Contains("openclaw setup --help", commands.WslCalls[3].Command);
+        Assert.Contains("openclaw setup --baseline --workspace '/home/openclaw/.openclaw/workspace'", commands.WslCalls[3].Command);
+        Assert.Contains("openclaw setup --workspace '/home/openclaw/.openclaw/workspace'", commands.WslCalls[3].Command);
+        Assert.Contains("workspace='/home/openclaw/.openclaw/workspace'", commands.WslCalls[4].Command);
+        // getent uses $(id -un) command-substitution and no $vars, so argv path is safe.
+        Assert.False(commands.WslCalls[0].InputViaStdin);
+        // agents list + config get + openclaw setup scripts reference $PATH via WslPathPrefix,
+        // which wsl.exe would rewrite on the argv path — see docs/WSL_EXE_ARGV_PITFALL.md.
+        Assert.True(commands.WslCalls[1].InputViaStdin);
+        Assert.True(commands.WslCalls[2].InputViaStdin);
+        Assert.True(commands.WslCalls[3].InputViaStdin);
+        // Apply script uses $workspace etc., must use stdin.
+        Assert.True(commands.WslCalls[4].InputViaStdin);
+        var state = await WindowsNodeBootstrapContextStep.ReadInstallStateAsync(ctx, CancellationToken.None);
+        Assert.Contains(state.Targets, target =>
+            target.DistroName == "OpenClawGateway" &&
+            target.User == "openclaw" &&
+            target.WorkspacePath == "/home/openclaw/.openclaw/workspace");
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_ResolvesRelativeConfiguredWorkspaceFromGatewayUserHome()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/relative/workspace"));
+                if (command.Contains("openclaw setup"))
+                    return Ok("");
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("\"relative/workspace\"\n");
+                if (command.Contains("workspace='/home/openclaw/relative/workspace'"))
+                    return Ok("WINDOWS_NODE_CONTEXT_READY\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.Contains(commands.WslCalls,
+            c => c.Command.Contains("openclaw setup --workspace '/home/openclaw/relative/workspace'"));
+        Assert.Contains(commands.WslCalls,
+            c => c.Command.Contains("workspace='/home/openclaw/relative/workspace'"));
+        Assert.DoesNotContain(commands.WslCalls, c => c.Command == "pwd -P");
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_UsesDefaultOnlyWhenWorkspaceKeyIsAbsent()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return new CommandResult(
+                        1,
+                        "",
+                        "Config path not found: agents.defaults.workspace. Run openclaw config validate to inspect config shape.",
+                        TimeSpan.Zero,
+                        TimedOut: false);
+                if (command.Contains("openclaw setup --workspace '/home/openclaw/.openclaw/workspace'"))
+                    return Ok();
+                if (command.Contains("workspace='/home/openclaw/.openclaw/workspace'"))
+                    return Ok("WINDOWS_NODE_CONTEXT_READY\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.Contains(commands.WslCalls,
+            c => c.Command.Contains("openclaw setup --workspace '/home/openclaw/.openclaw/workspace'"));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_DoesNotPersistDefaultWhenWorkspaceLookupFails()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Fail("gateway config is temporarily unavailable");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.Equal(StepOutcome.Failed, result.Outcome);
+        Assert.Contains("Could not resolve OpenClaw default workspace path", result.Message);
+        Assert.DoesNotContain(commands.WslCalls, c => c.Command.Contains("openclaw setup"));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_DoesNotPersistDefaultForMalformedWorkspaceOutput()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("Config warning without a value\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.Equal(StepOutcome.Failed, result.Outcome);
+        Assert.DoesNotContain(commands.WslCalls, c => c.Command.Contains("openclaw setup"));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_UsesEffectiveDefaultAgentWorkspaceWithoutRewritingDefaults()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/main-agent"));
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("\"~/.openclaw/workspace\"\n");
+                if (command.Contains("workspace='/home/openclaw/main-agent'"))
+                    return Ok("WINDOWS_NODE_CONTEXT_READY\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.DoesNotContain(commands.WslCalls, c => c.Command.Contains("openclaw setup"));
+        Assert.Contains(commands.WslCalls, c => c.Command.Contains("workspace='/home/openclaw/main-agent'"));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_FailsWhenEffectiveAgentWorkspaceLookupFails()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Fail("agents unavailable");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+        var priorTarget = new WindowsNodeContextTarget("prior-distro", "openclaw", "/prior/workspace");
+        await WindowsNodeBootstrapContextStep.RecordAppliedTargetAsync(
+            ctx,
+            priorTarget,
+            CancellationToken.None);
+
+        var step = new WindowsNodeBootstrapContextStep();
+        var result = await step.ExecuteAsync(ctx, CancellationToken.None);
+        var callsAfterExecute = commands.WslCalls.Count;
+        await step.RollbackAsync(ctx, CancellationToken.None);
+
+        Assert.Equal(StepOutcome.Failed, result.Outcome);
+        Assert.Contains("Could not resolve OpenClaw agent workspace path", result.Message);
+        Assert.DoesNotContain(commands.WslCalls, c => c.Command.Contains("openclaw config get"));
+        Assert.DoesNotContain(commands.WslCalls, c => c.Command.Contains("openclaw setup"));
+        Assert.Equal(callsAfterExecute, commands.WslCalls.Count);
+        var state = await WindowsNodeBootstrapContextStep.ReadInstallStateAsync(ctx, CancellationToken.None);
+        Assert.Equal([priorTarget], state.Targets);
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_RemovesNewStateWhenSymlinkCheckMakesNoChange()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("\"~/.openclaw/workspace\"\n");
+                if (command.Contains("openclaw setup"))
+                    return Ok();
+                if (command.Contains("AGENTS_SYMLINK:$agents"))
+                    return new CommandResult(2, "", "AGENTS_SYMLINK", TimeSpan.Zero, TimedOut: false);
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var step = new WindowsNodeBootstrapContextStep();
+        var result = await step.ExecuteAsync(ctx, CancellationToken.None);
+        var callsAfterExecute = commands.WslCalls.Count;
+        await step.RollbackAsync(ctx, CancellationToken.None);
+
+        Assert.Equal(StepOutcome.Failed, result.Outcome);
+        Assert.False(File.Exists(WindowsNodeBootstrapContextStep.InstallStatePath(ctx)));
+        Assert.Equal(callsAfterExecute, commands.WslCalls.Count);
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_UsesExplicitWorkspaceOverride()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw setup --workspace"))
+                    return Ok("");
+                if (command.Contains("workspace='/custom/abs/path'"))
+                    return Ok("WINDOWS_NODE_CONTEXT_READY\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(new SetupConfig
+        {
+            WindowsNodeContext = new WindowsNodeContextConfig { WorkspacePath = "/custom/abs/path" }
+        }, commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.True(result.IsSuccess, result.Message);
+        // No config-get call when override is set.
+        Assert.DoesNotContain(commands.WslCalls, c => c.Command.Contains("openclaw config get"));
+        // Absolute path threads through to BOTH the setup command and the apply script
+        // (verified by the apply script asserting workspace='/custom/abs/path').
+        Assert.Contains(commands.WslCalls, c => c.Command.Contains("openclaw setup --workspace '/custom/abs/path'"));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_OverrideWithTilde_ExpandsBeforePassingToSetup()
+    {
+        // Regression: a ~/foo override must be expanded once so that the same
+        // absolute path goes to `openclaw setup --workspace` and the apply script.
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw setup --workspace"))
+                    return Ok("");
+                if (command.Contains("workspace='/home/openclaw/custom-ws'"))
+                    return Ok("WINDOWS_NODE_CONTEXT_READY\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(new SetupConfig
+        {
+            WindowsNodeContext = new WindowsNodeContextConfig { WorkspacePath = "~/custom-ws" }
+        }, commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.True(result.IsSuccess, result.Message);
+        Assert.Contains(commands.WslCalls,
+            c => c.Command.Contains("openclaw setup --workspace '/home/openclaw/custom-ws'"));
+        Assert.DoesNotContain(commands.WslCalls,
+            c => c.Command.Contains("--workspace '~/custom-ws'"));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Rollback_RunsRollbackScriptViaStdin()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("WINDOWS_NODE_CONTEXT_REMOVED"))
+                    return Ok("WINDOWS_NODE_CONTEXT_REMOVED\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+        await WindowsNodeBootstrapContextStep.RecordAppliedTargetAsync(
+            ctx,
+            new WindowsNodeContextTarget("recorded-distro", "recorded-user", "/recorded/workspace"),
+            CancellationToken.None);
+
+        await new WindowsNodeBootstrapContextStep().RollbackAsync(ctx, CancellationToken.None);
+
+        Assert.NotEmpty(commands.WslCalls);
+        // Last call is the rollback script and must use stdin.
+        Assert.Contains("WINDOWS_NODE_CONTEXT_REMOVED", commands.WslCalls[^1].Command);
+        Assert.True(commands.WslCalls[^1].InputViaStdin);
+        var rollback = Assert.Single(commands.WslCalls);
+        Assert.Equal("recorded-distro", rollback.DistroName);
+        Assert.Equal("recorded-user", rollback.User);
+        Assert.Contains("workspace='/recorded/workspace'", rollback.Command);
+        Assert.False(File.Exists(WindowsNodeBootstrapContextStep.InstallStatePath(ctx)));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Rollback_PropagatesCleanupFailureAndKeepsStateForRetry()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) => command.Contains("WINDOWS_NODE_CONTEXT_REMOVED")
+                ? Fail("cannot update AGENTS.md")
+                : Fail($"unexpected wsl command: {command}"));
+        var ctx = CreateContext(commands: commands);
+        await WindowsNodeBootstrapContextStep.RecordAppliedTargetAsync(
+            ctx,
+            new WindowsNodeContextTarget("recorded-distro", "recorded-user", "/recorded/workspace"),
+            CancellationToken.None);
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(() =>
+            new WindowsNodeBootstrapContextStep().RollbackAsync(ctx, CancellationToken.None));
+
+        Assert.Contains("cannot update AGENTS.md", error.Message);
+        Assert.True(File.Exists(WindowsNodeBootstrapContextStep.InstallStatePath(ctx)));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Rollback_RemovesExistingTargetStateAfterCleanup()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("\"~/.openclaw/workspace\"\n");
+                if (command.Contains("openclaw setup"))
+                    return Ok();
+                if (command.Contains("WINDOWS_NODE_CONTEXT_READY"))
+                    return Ok("WINDOWS_NODE_CONTEXT_READY\n");
+                if (command.Contains("WINDOWS_NODE_CONTEXT_REMOVED"))
+                    return Ok("WINDOWS_NODE_CONTEXT_REMOVED\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+        var target = new WindowsNodeContextTarget(
+            "OpenClawGateway",
+            "openclaw",
+            "/home/openclaw/.openclaw/workspace");
+        await WindowsNodeBootstrapContextStep.RecordAppliedTargetAsync(ctx, target, CancellationToken.None);
+        var step = new WindowsNodeBootstrapContextStep();
+        Assert.True((await step.ExecuteAsync(ctx, CancellationToken.None)).IsSuccess);
+
+        await step.RollbackAsync(ctx, CancellationToken.None);
+
+        Assert.False(File.Exists(WindowsNodeBootstrapContextStep.InstallStatePath(ctx)));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Rollback_TreatsMissingRecordedDistroAsCleaned()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) => command.Contains("WINDOWS_NODE_CONTEXT_REMOVED")
+                ? new CommandResult(1, "", "WSL_E_DISTRO_NOT_FOUND", TimeSpan.Zero, TimedOut: false)
+                : Fail($"unexpected wsl command: {command}"));
+        var ctx = CreateContext(commands: commands);
+        await WindowsNodeBootstrapContextStep.RecordAppliedTargetAsync(
+            ctx,
+            new WindowsNodeContextTarget("missing-distro", "openclaw", "/recorded/workspace"),
+            CancellationToken.None);
+
+        await new WindowsNodeBootstrapContextStep().RollbackAsync(ctx, CancellationToken.None);
+
+        Assert.False(File.Exists(WindowsNodeBootstrapContextStep.InstallStatePath(ctx)));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Rollback_CleansLegacyEffectiveWorkspaceWithoutStateFile()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/legacy-main"));
+                if (command.Contains("WINDOWS_NODE_CONTEXT_REMOVED"))
+                    return Ok("WINDOWS_NODE_CONTEXT_REMOVED\n");
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        await new WindowsNodeBootstrapContextStep().RollbackAsync(ctx, CancellationToken.None);
+
+        Assert.Contains(commands.WslCalls, call => call.Command.Contains("getent passwd"));
+        Assert.Contains(commands.WslCalls, call => call.Command.Contains("openclaw agents list --json"));
+        Assert.Contains(commands.WslCalls, call => call.Command.Contains("workspace='/home/openclaw/legacy-main'"));
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_FailsWhenHomeUnresolvable()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return new CommandResult(1, "", "", TimeSpan.Zero, TimedOut: false);
+                return Fail($"unexpected wsl command: {command}");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.Equal(StepOutcome.Failed, result.Outcome);
+        Assert.Contains("Could not resolve Linux home directory", result.Message);
+    }
+
+    [Fact]
+    public async Task WindowsNodeContext_Execute_FailsWithoutReadyMarker()
+    {
+        var commands = new FakeCommandRunner(
+            _ => Fail("unexpected RunAsync"),
+            (_, command, _) =>
+            {
+                if (command.Contains("getent passwd"))
+                    return Ok("/home/openclaw\n");
+                if (command.Contains("openclaw agents list --json"))
+                    return Ok(AgentsListJson("/home/openclaw/.openclaw/workspace"));
+                if (command.Contains("openclaw setup"))
+                    return Ok("");
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("\"~/.openclaw/workspace\"\n");
+                return Fail("apply script failed");
+            });
+        var ctx = CreateContext(commands: commands);
+
+        var result = await new WindowsNodeBootstrapContextStep().ExecuteAsync(ctx, CancellationToken.None);
+
+        Assert.Equal(StepOutcome.Failed, result.Outcome);
+        Assert.Contains("Windows node context injection failed", result.Message);
+    }
+
     private static CommandResult Ok(string stdout = "", string stderr = "")
         => new(0, stdout, stderr, TimeSpan.Zero, TimedOut: false);
 
@@ -1636,6 +2239,9 @@ private static CommandResult FailWithStdout(string stdout)
     private static CommandResult TimedOut()
         => new(-1, "", "", TimeSpan.FromSeconds(30), TimedOut: true);
 
+    private static string AgentsListJson(string workspace, string id = "main", bool isDefault = true)
+        => JsonSerializer.Serialize(new[] { new { id, workspace, isDefault } });
+
     private static string NulSeparated(string value)
         => string.Join("\0", value.ToCharArray()) + "\0";
 
@@ -1656,7 +2262,7 @@ private sealed class FakeCommandRunner(
     {
         public List<(string Executable, string[] Arguments)> Calls { get; } = [];
         public List<(string Executable, string[] Arguments, string? StdinInput)> DetailedCalls { get; } = [];
-        public List<(string DistroName, string Command, TimeSpan Timeout)> WslCalls { get; } = [];
+        public List<(string DistroName, string Command, TimeSpan Timeout, string? User, bool InputViaStdin)> WslCalls { get; } = [];
 
         public Task<CommandResult> RunAsync(
             string executable,
@@ -1678,12 +2284,13 @@ public Task<CommandResult> RunInWslAsync(
             TimeSpan timeout,
             IReadOnlyDictionary<string, string>? environment = null,
             CancellationToken ct = default,
-            string? user = null)
+            string? user = null,
+            bool inputViaStdin = false)
         {
+            WslCalls.Add((distroName, command, timeout, user, inputViaStdin));
             if (runInWsl == null)
                 throw new NotSupportedException("RunInWslAsync is not expected in these tests.");
 
-            WslCalls.Add((distroName, command, timeout));
             return Task.FromResult(runInWsl(distroName, command, timeout));
         }
     }
diff --git a/tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs b/tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs
index 049094935..6f9474432 100644
--- a/tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs
+++ b/tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs
@@ -353,10 +353,22 @@ public void Setup_IsHostedInTrayAndUsesSelfRestartAfterCompletion()
         Assert.Contains("gatewayPortOverride: AppIdentity.SetupGatewayPort", source);
         Assert.Contains("SetupRunLock.TryAcquire(_dataDir", setupWindow);
         Assert.Contains("new SetupContext(", progressPage);
+        Assert.Contains("step is not RunGatewayWizardStep", progressPage);
+        Assert.Contains("config.SkipWizard || step is not WindowsNodeBootstrapContextStep", progressPage);
         Assert.Contains("_dataDir,", progressPage);
         Assert.Contains("_localDataDir);", progressPage);
         Assert.Contains("setupWindow?.DataDir ?? SetupContext.ResolveDataDir()", welcomePage);
         Assert.Contains("SetupWindow.Active?.DataDir ?? SetupContext.ResolveDataDir()", wizardPage);
+        Assert.Contains("await CompleteSetupAsync(generation)", wizardPage);
+        Assert.Contains("ApplyWindowsNodeContextAsync", wizardPage);
+        Assert.Contains("var pipeline = new SetupPipeline(", setupWindow);
+        Assert.Contains("[new WindowsNodeBootstrapContextStep()]", setupWindow);
+        Assert.Contains("rollbackOnFailureOverride: false", setupWindow);
+        AssertInOrder(
+            setupWindow,
+            "_lifetimeCts.Cancel()",
+            "await contextApplyTask",
+            "_setupLock?.Dispose()");
         Assert.Contains("distroNameOverride: _config.DistroName", wizardPage);
         Assert.Contains("if (AppIdentity.IsDev)", updateCoordinator);
         Assert.Contains("Skipping release-channel update check in development build", updateCoordinator);
@@ -438,6 +450,37 @@ public void SetupCompletion_PersistsStartupChoiceBeforeRestart()
             "handler.Invoke");
     }
 
+    [Fact]
+    public void SetupWindowOwnership_WaitsForCleanupBeforeAllowingAnotherRun()
+    {
+        var root = TestRepositoryPaths.GetRepositoryRoot();
+        var app = File.ReadAllText(Path.Combine(root, "src", "OpenClaw.Tray.WinUI", "App.xaml.cs"));
+        var setupWindow = File.ReadAllText(Path.Combine(root, "src", "OpenClaw.SetupEngine.UI", "SetupWindow.xaml.cs"));
+
+        Assert.Contains("public Task CleanupCompleted => _cleanupCompleted.Task", setupWindow);
+        AssertInOrder(
+            setupWindow,
+            "_lifetimeCts.Cancel()",
+            "await contextApplyTask",
+            "catch (OperationCanceledException)",
+            "_setupLock?.Dispose()",
+            "_cleanupCompleted.TrySetResult(true)");
+        Assert.Contains("rollbackOnFailureOverride: false", setupWindow);
+        AssertInOrder(
+            app,
+            "while (_setupWindow != null)",
+            "await existingSetupWindow.WaitForInitialContentReadyAsync()",
+            "if (!existingSetupWindow.IsClosed)",
+            "await existingSetupWindow.CleanupCompleted",
+            "_setupWindow = null",
+            "new SetupWindow(");
+        AssertInOrder(
+            app,
+            "setupWindow.Closed += async",
+            "await setupWindow.CleanupCompleted",
+            "_setupWindow = null");
+    }
+
     [Fact]
     public void CompletePage_UsesCompletionArgsForStartupPreference()
     {
@@ -554,6 +597,33 @@ public void WizardSecondaryButton_DoesNotSkipEntireWizardInErrorState()
         Assert.Contains("SendCurrentAnswerAsync(skip: true)", method);
     }
 
+    [Fact]
+    public void WizardCompletion_AppliesWindowsNodeContextBeforeSummary()
+    {
+        var root = TestRepositoryPaths.GetRepositoryRoot();
+        var source = File.ReadAllText(Path.Combine(root, "src", "OpenClaw.SetupEngine.UI", "Pages", "WizardPage.xaml.cs"));
+        var complete = ExtractMethod(source, "CompleteSetupAsync");
+        var skip = ExtractMethod(source, "SkipWizardAsync");
+        var primary = ExtractMethod(source, "PrimaryClickAsync");
+        var finalizationError = ExtractMethod(source, "ShowFinalizationError");
+
+        AssertInOrder(
+            complete,
+            "ApplyWindowsNodeContextAsync",
+            "if (!contextResult.IsSuccess)",
+            "NavigateToComplete(true");
+        Assert.Contains("await CompleteSetupAsync(generation)", skip);
+        Assert.Contains("_errorState = false", skip);
+        AssertInOrder(
+            primary,
+            "if (_finalizationErrorState)",
+            "_errorState = false",
+            "await CompleteSetupAsync(_operationGeneration)",
+            "await StartWizardAsync()");
+        Assert.Contains("ShowFinalizationError", complete);
+        Assert.Contains("Retry Windows integration", finalizationError);
+    }
+
     [Fact]
     public void WizardConnect_UsesActiveGatewayRecordUrl()
     {