docs(windows): route main documentation to the Windows release branch

.agents/skills/build-openshell-mxc-windows/reference.md

@@ -1,7 +1,10 @@
 # Reference: Windows MSVC maintenance lane
 
 Companion to [SKILL.md](SKILL.md). Use this file for quick lookup while
-maintaining the existing build-only Windows MSVC lane.
+maintaining the native Windows MSVC and MXC runtime lane on the
+[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows).
+Run the commands below from that branch or a branch based on it, including
+when reading this reference on `main`.
 
 ## Lane Files
 
@@ -33,15 +36,35 @@ For host-native full validation, detect architecture first:
 $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
 if ($arch -eq [System.Runtime.InteropServices.Architecture]::Arm64) {
     mise run --skip-tools windows:check:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:check:arm64 failed." }
     mise run --skip-tools windows:build:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:build:arm64 failed." }
     mise run --skip-tools windows:test:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:arm64 failed." }
     mise run --skip-tools windows:test:unsupported:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:unsupported:arm64 failed." }
+    mise run --skip-tools windows:test:mxc-real:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:arm64 failed." }
     mise run --skip-tools windows:artifacts
+    if ($LASTEXITCODE -ne 0) { throw "windows:artifacts failed." }
+    mise run --skip-tools windows:e2e:mxc
+    if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
 } else {
     mise run --skip-tools windows:ci
+    if ($LASTEXITCODE -ne 0) { throw "windows:ci failed." }
+    mise run --skip-tools windows:test:mxc-real:x64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:x64 failed." }
+    mise run --skip-tools windows:e2e:mxc
+    if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
 }
 ```
 
+`windows:ci` does not include the real MXC runtime tests or E2E. Run the matching
+`windows:test:mxc-real:*` task and `windows:e2e:mxc` explicitly.
+These tasks can report `SKIP` when the executor or backend is unavailable;
+full validation requires an MXC-capable host. E2E exits nonzero when any
+required runtime scenario fails or skips.
+
 The native test tasks reject a target that does not match the host architecture.
 Do not report x64 compatibility-under-emulation coverage from an ARM64 run.
 
@@ -75,7 +98,7 @@ Ninja to `PATH`, while the crypto crates select `clang-cl`. Use a short
 
 ## Unsupported Driver Rules
 
-Windows is a build target only. These runtimes remain unsupported:
+These Windows runtimes remain unsupported:
 
 - Docker
 - Kubernetes
@@ -115,11 +138,10 @@ top-level workspace targets for check/test:
 ```
 
 The gateway keeps platform configuration and unsupported-operation contracts
-without depending on the Docker, Kubernetes, Podman, sandbox runtime,
-standalone supervisor, supervisor process runtime, VM, or VFIO crates. The MXC
-driver does depend on the cross-platform supervisor network library for its host
-egress proxy. The Kubernetes Secrets and Vault libraries still compile as
-gateway dependencies; only their standalone Unix-socket binaries and
+without depending on the Docker, Kubernetes, Podman, VM, or VFIO runtime crates.
+The MXC runtime compiles the supervisor, supervisor-process library, and sandbox
+boundary on Windows. The Kubernetes Secrets and Vault libraries still compile
+as gateway dependencies; only their standalone Unix-socket binaries and
 package-level tests are excluded as top-level targets.
 
 The supervisor and supervisor-process packages now participate as top-level

.agents/skills/sync-agent-infra/SKILL.md

@@ -28,6 +28,7 @@ Run after adding, removing, or renaming a skill or crate; changing issue or PR c
 | TUI behavior | `tui-development` |
 | Release artifacts or smoke coverage | `test-release-canary` |
 | CI diagnostics | `watch-github-actions` |
+| Native Windows builds, runtime, or release branch guidance | `build-openshell-mxc-windows`; keep Windows implementation links on `windows` even in docs merged to `main` |
 | Gator supervision | `launch-openshell-gator` |
 | SBOM workflow | `sbom` |
 | RFC workflow | `create-rfc` |

AGENTS.md

@@ -50,7 +50,8 @@ Do not rely on this file for a full inventory. The detailed public and contribut
 | `crates/openshell-driver-docker/` | Docker compute driver | In-process `ComputeDriver` backend for local Docker sandbox containers |
 | `crates/openshell-driver-podman/` | Podman compute driver | In-process `ComputeDriver` backend for local Podman sandbox containers |
 | `crates/openshell-driver-vm/` | VM compute driver | Standalone libkrun-backed `ComputeDriver` subprocess (embeds its own rootfs + runtime) |
-| `crates/openshell-driver-mxc/` | Microsoft MXC compute driver | In-process Windows AppContainer and isolation-session compute backend |
+| [`crates/openshell-driver-mxc/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-driver-mxc) (`windows` branch) | Microsoft MXC compute driver | Native Windows ProcessContainer backend; see the Windows branch for the maintained implementation |
+| [`crates/openshell-mxc-boundary/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-mxc-boundary) (`windows` branch) | Windows sandbox boundary | Dedicated Windows workload boundary paired with the host supervisor |
 | `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
 | `crates/openshell-prover-cli/` | Policy prover CLI | Standalone local policy boundary checks |
 | `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization |

CI.md

@@ -67,11 +67,25 @@ For an intentional minor-train incompatibility, record the Buf finding,
 linked issue, consumer impact, and migration plan in the PR. Keep the finding
 visible; do not disable the job or add a broad Buf ignore rule.
 
-Windows PR checks are opt-in: add `test:windows`, then select **Re-run all jobs**
+### Windows validation
+
+Native Windows implementation and releases use the
+[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows), independently
+of the `main` release train described in this document. Shared documentation on
+`main` must retain that branch placement. See [WINDOWS.md](WINDOWS.md) for the
+native MSVC build and MXC runtime requirements.
+
+The [Windows MSVC workflow on `windows`](https://github.com/NVIDIA/OpenShell/blob/windows/.github/workflows/windows-msvc.yml)
+runs native x64 and ARM64 lanes. Windows PR checks are opt-in: add
+`test:windows`, then select **Re-run all jobs**
 on the current Windows MSVC run. Subsequent mirrored commits run them automatically.
 Windows checks are not required for merging and do not run in merge queues.
-Main and manual runs also build release binaries, with `continue-on-error: true`
-so Windows failures do not fail the workflow.
+Pushes to `windows` and manual runs on that branch seed the lint/test caches and run dependent
+release binary builds. Those jobs use `continue-on-error: true`, so inspect
+their individual results rather than treating a green workflow as qualification.
+The jobs do not upload or publish the binaries. Native Windows packages are
+not supplied through the `main` installer or release train. Real MXC runtime qualification requires a
+capable host and the [Windows runtime tests](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation).
 
 ### Advisory compatibility review
 

CONTRIBUTING.md

@@ -114,7 +114,7 @@ Contributor and maintainer skills live in `.agents/skills/`. They are marked int
 | Triage          | `apply-triage-action`     | Apply, reject, or defer one explicitly selected triage recommendation                               |
 | Platform        | `helm-dev-environment`    | Start and manage the local Kubernetes development environment                                       |
 | Platform        | `tui-development`         | Development guide for the ratatui-based terminal UI                                                 |
-| Platform        | `build-openshell-mxc-windows` | Maintain and validate the build-only x64 and ARM64 Windows MSVC lane                             |
+| Platform        | `build-openshell-mxc-windows` | Maintain and validate native x64 and ARM64 MSVC builds and MXC runtime on the `windows` branch |
 | Documentation   | `update-docs-from-commits` | Scan recent commits and draft doc updates for user-facing changes                                  |
 | Maintenance     | `sync-agent-infra`        | Detect and fix drift across agent-first infrastructure files                                        |
 | Reference       | `sbom`                    | Generate SBOMs and resolve dependency licenses                                                      |
@@ -141,6 +141,12 @@ When recording a triage outcome, replace the previous assessment state rather th
 
 ## Prerequisites
 
+Native Windows development uses the [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows).
+Follow [Native Windows support](WINDOWS.md) for checkout, MSVC prerequisites,
+runtime requirements, and limitations. Target Windows implementation PRs at
+`windows`. Shared documentation can merge into `main`, but Windows-specific
+source and task links must continue to point to `windows`.
+
 Install [mise](https://mise.jdx.dev/). This is used to set up the development environment.
 
 ```bash
@@ -163,7 +169,7 @@ echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish
 echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
 ```
 
-Project requirements:
+Linux/macOS development requirements:
 
 - Rust 1.94+
 - Python 3.11+
@@ -202,7 +208,7 @@ cargo build -p openshell-prover-cli --features vendored-z3
 Local gateway image and E2E builds enable `vendored-z3` so their
 copied gateway binaries do not need a shared Z3 library in the runtime image.
 
-For x86-64 and ARM64 Windows MSVC builds, use one of these Z3 paths:
+For x86-64 and ARM64 Windows MSVC builds from the `windows` branch, use one of these Z3 paths:
 
 - Prebuilt Z3 (the default for `windows:*` tasks): `z3-sys` downloads the
   pinned Z3 5.1.0 GitHub release for the target architecture on the first
@@ -225,8 +231,10 @@ cargo build -p openshell-prover --target x86_64-pc-windows-msvc --features prebu
 
 ### Windows full build
 
-To build the full set of Windows binaries, including `openshell-gateway.exe`
-and `openshell.exe`, use the `windows:build:x64` mise task instead of a
+Run these commands in a `windows`-based checkout. To build the full set of
+Windows binaries, including `openshell-gateway.exe`, `openshell.exe`,
+`openshell-supervisor.exe`, and `openshell-windows-sandbox.exe`,
+use the `windows:build:x64` mise task instead of a
 single-crate `cargo build`. It downloads the pinned prebuilt Z3 release by default. A
 full build also compiles crates that use `bindgen` (e.g. the MXC driver on
 Windows), so it requires `libclang.dll`; if LLVM is not on the default search
@@ -237,6 +245,12 @@ $env:LIBCLANG_PATH='C:\Program Files\Microsoft Visual Studio\2022\<Edition>\VC\T
 mise run --skip-tools windows:build:x64
 ```
 
+For ARM64, use `windows:build:arm64` with ARM64 MSVC components and host-native
+LLVM. Keep the matching `libz3.dll` staged by the build beside the executables.
+See [Windows validation](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation)
+for native tests and MXC E2E requirements. Docker is not required for the native
+Windows build or MXC runtime.
+
 To use a local x64 Z3 release instead of the prebuilt download, set
 `Z3_LIBRARY_PATH_OVERRIDE` and `Z3_SYS_Z3_HEADER` before running the task:
 
@@ -256,6 +270,9 @@ xcode-select --install
 
 ## Getting Started
 
+The gateway and shell shortcuts below describe Linux/macOS development.
+For native Windows, use the [Windows build and runtime instructions](WINDOWS.md).
+
 ```bash
 # One-time trust
 mise trust

README.md

@@ -38,6 +38,8 @@ openshell sandbox create --name demo
 
 The installer sets up the CLI and a local gateway. The default sandbox image is minimal Ubuntu with no agent installed. To run a real agent, follow [Run Your First Agent](https://docs.nvidia.com/openshell/latest/about/run-your-first-agent): it runs OpenCode against a free OpenRouter model and shows how to approve new access as the agent needs it.
 
+For native Windows support through Microsoft MXC, see the [Windows build and runtime guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md) for setup and current limitations.
+
 ## Explore Further
 
 - [Sandboxes](https://docs.nvidia.com/openshell/latest/how-it-works/sandboxes/overview): images, runtimes, GPUs, and lifecycle.

TESTING.md

@@ -72,6 +72,44 @@ task skips them. Run them on an idle machine with
 
 ### Native Windows validation
 
+Start with the [Windows build prerequisites](WINDOWS.md#build) in a checkout
+based on `windows`. Run the lane matching the native host:
+
+```powershell
+# Native x64 host
+mise run --skip-tools windows:lint:x64
+mise run --skip-tools windows:build:x64
+mise run --skip-tools windows:test:x64
+mise run --skip-tools windows:test:unsupported:x64
+
+# Native ARM64 host
+mise run --skip-tools windows:lint:arm64
+mise run --skip-tools windows:build:arm64
+mise run --skip-tools windows:test:arm64
+mise run --skip-tools windows:test:unsupported:arm64
+```
+
+The test tasks use the CI nextest profile and server test support. They reject
+a target that does not match the host architecture. `windows:ci` is the x64-host
+aggregate, including ARM64 cross-check/build unless explicitly skipped; it
+does not establish native ARM64 test coverage.
+
+For runtime validation, provision a capable MXC host and build its native
+release binaries first. On x64, run:
+
+```powershell
+mise run --skip-tools windows:test:mxc-real:x64
+mise run --skip-tools windows:e2e:mxc
+```
+
+Use `windows:test:mxc-real:arm64` on ARM64. The real-runtime unit tests can
+report `SKIP` when the executor or backend is absent; E2E returns nonzero
+when required runtime coverage is missing. Report passed, failed, and
+skipped/ignored executions separately, including why any probe gated coverage.
+Passing E2E does not qualify the [known Windows enforcement gaps](WINDOWS.md#runtime-and-current-limits).
+See the [Windows test task definitions](https://github.com/NVIDIA/OpenShell/blob/windows/tasks/windows.toml)
+for boundary, loopback, network, and audit suites.
+
 Use `mise run --skip-tools pre-commit` with the existing Rust/MSVC toolchain.
 Windows now checks tracked Cargo lockfiles through PowerShell rather than
 skipping them.

WINDOWS.md

@@ -0,0 +1,113 @@
+# Native Windows support
+
+The [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows) is the
+development and release branch for native Windows OpenShell. The Windows
+implementation stays on that branch. This guide and other shared documentation
+can also appear on `main`; their presence there does not move the Windows
+implementation or release source to `main`.
+
+Native Windows uses Microsoft MXC ProcessContainer isolation on x64 and ARM64.
+It is separate from running Linux OpenShell inside WSL 2. Docker, Podman,
+Kubernetes, and MicroVM are not native Windows compute backends.
+
+## Runtime and current limits
+
+The gateway links the MXC compute driver. It starts a trusted
+`openshell-supervisor.exe` on the host and an
+`openshell-windows-sandbox.exe` boundary inside each ProcessContainer. The pair
+uses the authenticated Sandbox Protocol for process operations and forwarding.
+The host supervisor applies network policy and endpoint-bound provider credentials
+through an authenticated explicit proxy. Workloads must support that proxy.
+
+MXC maps filesystem and UI policy to native controls. This implementation is
+under development and is not a production-qualified security boundary:
+
+- Outer-fence guarantees are temporarily asserted for compatibility testing.
+  Exclusive supervisor-mediated egress and live access revocation are unverified.
+- The loopback exception can expose unrelated host-local services to workloads.
+  Treat the gateway host as trusted.
+- Foreground main-process attachment and ConPTY resize are unavailable. Create
+  command workloads with `--detach`.
+- Gateway restart recovery for live MXC generations is not supported.
+
+See the Windows branch's [MXC driver documentation](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-driver-mxc/README.md)
+for the current capabilities and enforcement limits, and its
+[boundary library documentation](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-mxc-boundary/README.md)
+for the runtime architecture. Passing build or E2E checks does not establish
+the missing security guarantees.
+
+## Get the Windows source
+
+Use a separate checkout so an existing `main` checkout can remain in place:
+
+```powershell
+git clone --branch windows https://github.com/NVIDIA/OpenShell.git OpenShell-windows
+Set-Location OpenShell-windows
+mise trust
+```
+
+Base native Windows implementation changes on `windows` and target that branch
+for review. Documentation-only changes can also merge into `main`, while
+retaining explicit `windows` branch links for Windows code, tasks, and runtime
+instructions. The `main` installer and its dev, prerelease, and stable artifacts
+are not the native Windows distribution path.
+
+## Build
+
+Use Windows with rustup, mise, Visual Studio C++ Build Tools, a Windows SDK,
+and host-compatible LLVM/libclang. Install the MSVC components for each target
+you build, including ARM64 tools and Spectre-mitigated libraries for ARM64.
+The [Windows build skill](https://github.com/NVIDIA/OpenShell/blob/windows/.agents/skills/build-openshell-mxc-windows/SKILL.md)
+lists the full prerequisites and environment overrides.
+
+Run the build matching your target:
+
+```powershell
+# x64
+mise run --skip-tools windows:build:x64
+
+# ARM64
+mise run --skip-tools windows:build:arm64
+```
+
+The tasks produce `openshell.exe`, `openshell-gateway.exe`,
+`openshell-supervisor.exe`, and `openshell-windows-sandbox.exe` under
+`target/<target-triple>/release/`. Keep these binaries from the same build
+together with the matching `libz3.dll` staged by the build task. The target
+triples are `x86_64-pc-windows-msvc` and `aarch64-pc-windows-msvc`.
+`CARGO_TARGET_DIR` can override the output root.
+
+The build uses pinned prebuilt Z3 by default. Compile and test hosts do not
+need a working MXC runtime; running native sandboxes does. These tasks do not
+install an MSI, register a Windows service, or publish a release.
+
+## Prepare and run MXC
+
+Use MXC 1.0.0 and a host that passes the native ProcessContainer capability
+probe. Place `wxc-exec.exe` outside `WindowsApps` or an MSIX package directory
+and configure its absolute path.
+
+```powershell
+& "C:\mxc\wxc-exec.exe" --probe
+```
+
+`probes.baseContainerSupportsIngressHostLoopbackAllow` must be `true`.
+A Windows version number alone does not establish runtime compatibility.
+Configure `compute_driver = "mxc"` and use the matching
+[Windows gateway configuration](https://github.com/NVIDIA/OpenShell/blob/windows/docs/how-it-works/gateways/configuration.mdx#configure-mxc)
+and [example gateway TOML](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-driver-mxc/examples/mxc-gateway.toml).
+Command-based sandbox creation requires administrator opt-in with
+`allow_driver_config = true`, a workload command and working directory, and
+`--detach`. Use a sandbox policy to grant the required filesystem and network
+access.
+
+## Validate
+
+Follow [native Windows validation](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation)
+for native x64 or ARM64 lint, build, unit tests, and real MXC tests. Cross-building
+ARM64 on x64 does not run native ARM64 tests. Real MXC tests and E2E require a
+capable host; record probe-gated skips separately from passes.
+
+The [Windows CI guidance](https://github.com/NVIDIA/OpenShell/blob/windows/CI.md#windows-validation)
+describes opt-in PR checks and branch builds. A successful compilation or an
+advisory CI run is not a Windows release qualification result.