From e028dc07884c5397dafd95f66549d74dcaff945a Mon Sep 17 00:00:00 2001
From: "Paul Campbell (AgOS)" <paulcam@microsoft.com>
Date: Tue, 2 Jun 2026 20:19:04 -0700
Subject: [PATCH] feat(setup): inject Windows-node guidance into AGENTS.md
 after pairing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add WindowsNodeBootstrapContextStep that runs after node pairing and
injects a managed BEGIN/END block into the gateway's AGENTS.md
(workspace resolved from `openclaw config get agents.defaults.workspace`,
or from a `WindowsNodeContext.WorkspacePath` override). The injected
block tells the running OpenClaw agent how to use the paired Windows
tray node (nodes tool, exec host=node, tools.exec defaults, etc.).

The file mutation is pure POSIX shell + awk + base64 — no Node.js
dependency, no embedded JS, no heredocs. Bare WSL distros (and the
gateway distro) do not have node installed, so the previous
node-based approach failed at runtime.

Scripts that need bash variable handling are piped to `bash -s` via
stdin instead of being passed as argv to `bash -c`, because wsl.exe
performs shell variable expansion on argv before bash sees it and
silently drops user-defined $var references. New
docs/WSL_EXE_ARGV_PITFALL.md documents the footgun, the empirical
reproduction against fresh Ubuntu-26.04, and the ranked fixes.

Notable changes:
* CommandRunner.RunInWslAsync gains opt-in `inputViaStdin: true`
  that switches argv to `bash -s` and pipes the script over stdin
* WindowsNodeBootstrapContextStep computes the absolute workspace
  path once via ExpandLinuxPath and threads it through both
  `openclaw setup --workspace` and the apply script, so `~/foo` or
  relative-path overrides cannot land in different directories
* RunOpenclawSetupAsync and ResolveWorkspacePathAsync use the stdin
  path because their scripts include $PATH via WslPathPrefix
* Apply script is idempotent and handles missing/symlink/malformed
  AGENTS.md; rollback removes the managed block in-place
* Cross-references in AGENTS.md and docs/WINDOWS_NODE_TESTING.md
  surface the pitfall doc from likely discovery points
* Tests cover apply/rollback shape, override expansion, per-call
  stdin-vs-argv invariants, and a tilde-override regression
* Verified end-to-end against bare Ubuntu-26.04 (no openclaw, no
  node): apply-to-missing, apply-preserves-content, idempotency
  (exactly 1 BEGIN marker after second apply), rollback restores
  original content

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 AGENTS.md                                     |   1 +
 docs/ONBOARDING_WIZARD.md                     |   2 +
 docs/WINDOWS_NODE_TESTING.md                  |   8 +
 docs/WSL_EXE_ARGV_PITFALL.md                  | 134 +++++++
 src/OpenClaw.SetupEngine/CommandRunner.cs     |  87 ++++-
 src/OpenClaw.SetupEngine/SetupContext.cs      |  10 +
 src/OpenClaw.SetupEngine/SetupPipeline.cs     |   1 +
 src/OpenClaw.SetupEngine/SetupSteps.cs        | 332 +++++++++++++++++-
 .../WindowsNodeContextSection.cs              |  27 ++
 src/OpenClaw.SetupEngine/default-config.json  |  10 +
 .../SetupConfigTests.cs                       |  14 +
 .../SetupPipelineTests.cs                     |   5 +-
 .../SetupStepsTests.cs                        | 285 ++++++++++++++-
 13 files changed, 906 insertions(+), 10 deletions(-)
 create mode 100644 docs/WSL_EXE_ARGV_PITFALL.md
 create mode 100644 src/OpenClaw.SetupEngine/WindowsNodeContextSection.cs

diff --git a/AGENTS.md b/AGENTS.md
index 6c288035f..5450e3b2e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,6 +37,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`.
 
 Important current facts:
 
diff --git a/docs/ONBOARDING_WIZARD.md b/docs/ONBOARDING_WIZARD.md
index f58dd1f65..34ebd127f 100644
--- a/docs/ONBOARDING_WIZARD.md
+++ b/docs/ONBOARDING_WIZARD.md
@@ -26,6 +26,8 @@ Installs and connects a new app-owned `OpenClawGateway` WSL instance from a clea
 
 The managed distro is locked down and is not intended to be a normal interactive Ubuntu profile. For editing `openclaw.json` as the `openclaw` user and using root for protected-file administration, see [Managing the locked-down WSL gateway](WSL_GATEWAY_ADMIN.md).
 
+After node pairing, local WSL setup ensures OpenClaw has seeded the 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 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.
+
 ### Wizard
 Renders server-defined setup steps via RPC (`wizard.start` / `wizard.next`). The gateway controls the flow — steps can be:
 - **Note** — informational messages
diff --git a/docs/WINDOWS_NODE_TESTING.md b/docs/WINDOWS_NODE_TESTING.md
index c0e5cba3e..deef91590 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 node pairing, setup ensures OpenClaw has seeded the 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 any user-authored `AGENTS.md` content 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
 
 ### 1. Settings Toggle
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/CommandRunner.cs b/src/OpenClaw.SetupEngine/CommandRunner.cs
index b3818a35d..e8863a3f4 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
@@ -139,13 +178,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", "");
@@ -158,7 +233,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;
@@ -171,6 +249,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/SetupContext.cs b/src/OpenClaw.SetupEngine/SetupContext.cs
index 0accdd230..9471b4aa4 100644
--- a/src/OpenClaw.SetupEngine/SetupContext.cs
+++ b/src/OpenClaw.SetupEngine/SetupContext.cs
@@ -31,6 +31,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}";
 
@@ -234,6 +235,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 b33a132e7..b7e81a03f 100644
--- a/src/OpenClaw.SetupEngine/SetupPipeline.cs
+++ b/src/OpenClaw.SetupEngine/SetupPipeline.cs
@@ -57,6 +57,7 @@ public static List<SetupStep> BuildDefaultSteps()
             new MintBootstrapTokenStep(),
             new PairOperatorStep(),
             new PairNodeStep(),
+            new WindowsNodeBootstrapContextStep(),
             new VerifyEndToEndStep(),
             new RunGatewayWizardStep(),
             new StartKeepaliveStep(),
diff --git a/src/OpenClaw.SetupEngine/SetupSteps.cs b/src/OpenClaw.SetupEngine/SetupSteps.cs
index 69bf34268..540963b69 100644
--- a/src/OpenClaw.SetupEngine/SetupSteps.cs
+++ b/src/OpenClaw.SetupEngine/SetupSteps.cs
@@ -934,9 +934,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)
         {
@@ -2298,6 +2304,326 @@ public override Task RollbackAsync(SetupContext ctx, CancellationToken ct)
     }
 }
 
+public sealed class WindowsNodeBootstrapContextStep : SetupStep
+{
+    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)
+    {
+        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");
+
+        // Compute the absolute workspace path BEFORE running `openclaw setup`
+        // so the same path goes to both setup and the apply script. Otherwise
+        // an override like `~/foo` or `relative/foo` could land setup in one
+        // directory and the apply step in another.
+        var workspaceOverride = ctx.Config.WindowsNodeContext.WorkspacePath?.Trim();
+        string workspace;
+        if (!string.IsNullOrWhiteSpace(workspaceOverride))
+        {
+            workspace = ExpandLinuxPath(workspaceOverride, home);
+            var setupResult = await RunOpenclawSetupAsync(ctx, distro, user, workspace, ct);
+            if (!setupResult.IsSuccess)
+                return setupResult;
+        }
+        else
+        {
+            var setupResult = await RunOpenclawSetupAsync(ctx, distro, user, workspaceAbsolute: null, ct);
+            if (!setupResult.IsSuccess)
+                return setupResult;
+
+            var resolved = await ResolveWorkspacePathAsync(ctx, distro, user, home, ct);
+            if (string.IsNullOrWhiteSpace(resolved))
+                return StepResult.Fail("Could not resolve OpenClaw agent workspace path");
+            workspace = resolved;
+        }
+
+        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))
+            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)
+    {
+        if (!ctx.Config.WindowsNodeContext.Enabled)
+            return;
+
+        var distro = ctx.DistroName;
+        if (string.IsNullOrWhiteSpace(distro))
+            return;
+
+        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)
+        {
+            ctx.Logger.Warn("Windows node context rollback skipped: could not resolve Linux home directory");
+            return;
+        }
+
+        var workspace = await ResolveWorkspacePathAsync(ctx, distro, user, home, ct);
+        if (string.IsNullOrWhiteSpace(workspace))
+        {
+            ctx.Logger.Warn("Windows node context rollback skipped: could not resolve workspace path");
+            return;
+        }
+
+        // Uses stdin to bypass wsl.exe argv variable-expansion (see docs/WSL_EXE_ARGV_PITFALL.md).
+        var result = await ctx.Commands.RunInWslAsync(distro, BuildRollbackScript(workspace), timeout, ct: ct, user: user, inputViaStdin: true);
+
+        if (result.ExitCode != 0)
+            ctx.Logger.Warn($"Windows node context rollback failed (exit {result.ExitCode}): {FirstNonEmpty(result.Stderr, result.Stdout)}");
+    }
+
+    internal static async Task<string?> ResolveLinuxHomeAsync(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;
+
+        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;
+    }
+
+    internal static async Task<StepResult> RunOpenclawSetupAsync(SetupContext ctx, string distro, string user, string? workspaceAbsolute, CancellationToken ct)
+    {
+        var setupCommand = string.IsNullOrWhiteSpace(workspaceAbsolute)
+            ? "openclaw setup"
+            : $"openclaw setup --workspace {ShellEscape(workspaceAbsolute)}";
+
+        var script = $"set -e\n{ctx.WslPathPrefix}\n{setupCommand} >/dev/null";
+        // 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);
+
+        var script = $"{ctx.WslPathPrefix}\nopenclaw config get agents.defaults.workspace --json 2>/dev/null";
+        // 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);
+
+        var raw = ExtractWorkspaceFromConfigOutput(result.Stdout);
+        if (string.IsNullOrWhiteSpace(raw))
+            raw = $"{home.TrimEnd('/')}/.openclaw/workspace";
+
+        return ExpandLinuxPath(raw, home);
+    }
+
+    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=$(grep -cFx -- "$begin_marker" "$agents" || true)
+            end_count=$(grep -cFx -- "$end_marker" "$agents" || true)
+            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=$(grep -nFx -- "$begin_marker" "$agents" | head -1 | cut -d: -f1)
+                end_line=$(grep -nFx -- "$end_marker" "$agents" | head -1 | cut -d: -f1)
+                if [ "$end_line" -lt "$begin_line" ]; then
+                    echo "WINDOWS_NODE_CONTEXT_MARKERS_MALFORMED:$agents" >&2
+                    exit 4
+                fi
+            fi
+            tmp="$agents.new.$$"
+            awk -v BEGIN_M="$begin_marker" -v END_M="$end_marker" '
+              BEGIN { in_block = 0 }
+              $0 == BEGIN_M { in_block = 1; next }
+              in_block && $0 == END_M { in_block = 0; next }
+              in_block { next }
+              /^[[:space:]]*$/ { blank = blank "\n"; next }
+              { printf "%s%s\n", blank, $0; blank = "" }
+            ' "$agents" > "$tmp"
+            if [ -s "$tmp" ]; then
+                printf '\n' >> "$tmp"
+            fi
+            printf '%s' "$block_b64" | base64 -d >> "$tmp"
+            printf '\n' >> "$tmp"
+            mv "$tmp" "$agents"
+            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 0
+            fi
+            begin_count=$(grep -cFx -- "$begin_marker" "$agents" || true)
+            end_count=$(grep -cFx -- "$end_marker" "$agents" || true)
+            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=$(grep -nFx -- "$begin_marker" "$agents" | head -1 | cut -d: -f1)
+            end_line=$(grep -nFx -- "$end_marker" "$agents" | head -1 | cut -d: -f1)
+            if [ "$end_line" -lt "$begin_line" ]; then
+                echo "WINDOWS_NODE_CONTEXT_MARKERS_MALFORMED:$agents" >&2
+                exit 4
+            fi
+            tmp="$agents.new.$$"
+            awk -v BEGIN_M="$begin_marker" -v END_M="$end_marker" '
+              BEGIN { in_block = 0 }
+              $0 == BEGIN_M { in_block = 1; next }
+              in_block && $0 == END_M { in_block = 0; next }
+              in_block { next }
+              { print }
+            ' "$agents" > "$tmp"
+            mv "$tmp" "$agents"
+            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..d52c86be9
--- /dev/null
+++ b/src/OpenClaw.SetupEngine/WindowsNodeContextSection.cs
@@ -0,0 +1,27 @@
+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.
+
+If the user wants permissive WSL gateway exec defaults, suggest:
+
+```bash
+openclaw config unset tools.exec.mode || true
+openclaw config set tools.exec.ask off
+openclaw config set tools.exec.host auto
+openclaw config set tools.exec.security full
+openclaw config get tools.exec
+```
+
+Notes: unset `tools.exec.mode` avoids a schema conflict; `ask off` disables gateway exec prompts; `host auto` keeps default routing; `security full` makes gateway exec permissive; `get tools.exec` verifies the result.
+""";
+
+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..a9da5bfb4 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 OpenClaw runtime workspace AGENTS.md.
+  "WindowsNodeContext": {
+    "Enabled": true,
+    // Optional WSL workspace path override; null = let `openclaw setup` use configured/default workspace.
+    "WorkspacePath": null,
+    // Seconds allowed for OpenClaw workspace seeding and AGENTS.md context injection.
+    "TimeoutSeconds": 180
   }
 }
diff --git a/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs b/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs
index ef29b9fbc..b46cd305e 100644
--- a/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs
+++ b/tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs
@@ -32,6 +32,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]
@@ -286,6 +289,17 @@ 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("openclaw config set tools.exec.host auto", 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 0e4debd0c..10c2fa8cb 100644
--- a/tests/OpenClaw.SetupEngine.Tests/SetupPipelineTests.cs
+++ b/tests/OpenClaw.SetupEngine.Tests/SetupPipelineTests.cs
@@ -60,13 +60,16 @@ public void BuildDefaultSteps_IncludesCurrentSetupFlow()
     {
         var steps = SetupStepFactory.BuildDefaultSteps();
 
-        Assert.Equal(18, steps.Count);
+        Assert.Equal(19, steps.Count);
         Assert.IsType<PreflightOsStep>(steps[0]);
         Assert.IsType<PreflightWslStep>(steps[1]);
         Assert.IsType<CleanupStaleDistroStep>(steps[2]);
         Assert.IsType<CleanupStaleGatewayStep>(steps[3]);
         Assert.Contains(steps, s => s is ValidateWslLockdownStep);
         Assert.Contains(steps, s => s is RunGatewayWizardStep);
+        var pairNodeIndex = steps.FindIndex(s => s is PairNodeStep);
+        Assert.IsType<WindowsNodeBootstrapContextStep>(steps[pairNodeIndex + 1]);
+        Assert.IsType<VerifyEndToEndStep>(steps[pairNodeIndex + 2]);
         Assert.IsType<StartKeepaliveStep>(steps[^1]);
     }
 
diff --git a/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs b/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs
index e4e0ebb0b..590ad4e6c 100644
--- a/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs
+++ b/tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs
@@ -966,15 +966,287 @@ public void DefaultConfig_NoPairingScopeFields()
         Assert.Empty(scopeProps);
     }
 
+    [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("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("WINDOWS_NODE_CONTEXT_ABSENT", script);
+        Assert.Contains("WINDOWS_NODE_CONTEXT_REMOVED", 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));
+    }
+
+    [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 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(4, 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 setup", commands.WslCalls[1].Command);
+        Assert.Contains("openclaw config get agents.defaults.workspace", commands.WslCalls[2].Command);
+        Assert.Contains("workspace='/home/openclaw/.openclaw/workspace'", commands.WslCalls[3].Command);
+        // getent uses $(id -un) command-substitution and no $vars, so argv path is safe.
+        Assert.False(commands.WslCalls[0].InputViaStdin);
+        // openclaw setup + config get scripts both 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);
+        // Apply script uses $workspace etc., must use stdin.
+        Assert.True(commands.WslCalls[3].InputViaStdin);
+    }
+
+    [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 setup"))
+                    return Ok("");
+                if (command.Contains("openclaw config get agents.defaults.workspace"))
+                    return Ok("\"~/.openclaw/workspace\"\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);
+
+        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);
+        // The getent helper still uses argv (no $vars); config-get helper now uses stdin.
+        Assert.False(commands.WslCalls[0].InputViaStdin);
+        Assert.Contains("getent passwd", commands.WslCalls[0].Command);
+        Assert.Contains(commands.WslCalls, c =>
+            c.Command.Contains("openclaw config get agents.defaults.workspace") && c.InputViaStdin);
+    }
+
+    [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 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);
 
     private static CommandResult Fail(string stderr = "")
         => new(1, "", stderr, TimeSpan.Zero, TimedOut: false);
 
-    private sealed class FakeCommandRunner(Func<string[], CommandResult> run) : ICommandRunner
+    private sealed class FakeCommandRunner(
+        Func<string[], CommandResult> run,
+        Func<string, string, string?, CommandResult>? runInWsl = null) : ICommandRunner
     {
         public List<(string Executable, string[] Arguments)> Calls { get; } = [];
+        public List<(string DistroName, string Command, TimeSpan Timeout, string? User, bool InputViaStdin)> WslCalls { get; } = [];
 
         public Task<CommandResult> RunAsync(
             string executable,
@@ -995,7 +1267,14 @@ public Task<CommandResult> RunInWslAsync(
             TimeSpan timeout,
             IReadOnlyDictionary<string, string>? environment = null,
             CancellationToken ct = default,
-            string? user = null)
-            => throw new NotSupportedException("RunInWslAsync is not expected in these tests.");
+            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.");
+
+            return Task.FromResult(runInWsl(distroName, command, user));
+        }
     }
 }