docs(windows): document the Windows implementation and release branch

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

@@ -8,9 +8,16 @@ metadata:
 # Build OpenShell-MXC for Windows
 
 This skill maintains the existing native Windows MSVC build lane in the
-OpenShell repository. The Windows lane is already present in `main`; do not
-treat this skill as a first-time porting recipe unless the user explicitly asks
-for a new fork or a from-scratch bring-up.
+OpenShell repository's [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows).
+That branch owns native Windows implementation and releases. Shared docs may
+also appear on `main`; always direct Windows work to `windows` and use explicit
+Windows branch links for implementation details. See
+[Native Windows support](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md).
+
+Before running the tasks below, use a `windows`-based checkout and read the
+[skill from that branch](https://github.com/NVIDIA/OpenShell/blob/windows/.agents/skills/build-openshell-mxc-windows/SKILL.md).
+The task and runtime descriptions refer to that checkout, not to any older
+Windows source snapshot retained on `main`.
 
 The lane validates that OpenShell can compile and test on Windows MSVC for the
 supported deliverables:
@@ -107,7 +114,7 @@ did not request.
 
 In scope:
 
-- Refreshing a local checkout to the latest upstream GitHub `main`.
+- Refreshing a local checkout to the latest upstream GitHub `windows` branch.
 - Maintaining `tasks/windows.toml` and `tasks/scripts/windows-msvc.ps1`.
 - Running x64 and ARM64 MSVC checks.
 - Building x64 and ARM64 release binaries for `openshell-gateway`, `openshell`,
@@ -150,13 +157,13 @@ Out of scope:
 ## Recommended Checkout Flow
 
 From a fork checkout where `upstream` points to the official
-`NVIDIA/OpenShell` GitHub repository, use:
+`NVIDIA/OpenShell` GitHub repository, refresh the Windows branch:
 
 ```powershell
-git fetch upstream main
-git switch main
-git merge --ff-only upstream/main
-git branch --set-upstream-to=upstream/main main
+git fetch upstream windows
+git switch windows
+git merge --ff-only upstream/windows
+git branch --set-upstream-to=upstream/windows windows
 git status --short --branch
 ```
 
@@ -181,6 +188,7 @@ The lane targets a Windows host with Visual Studio Build Tools and rustup.
 | Windows SDK | `where.exe rc.exe` from a Developer PowerShell | Install an SDK containing target libraries and ARM64 tools. |
 | Rust via rustup | `rustc --version` | Add each target being validated: `x86_64-pc-windows-msvc` and/or `aarch64-pc-windows-msvc`. The wrapper also adds the selected target. |
 | mise | `mise --version` | Used as a task runner only. |
+| cargo-nextest | `cargo nextest --version` | Required by `windows:test:x64`, `windows:test:arm64`, and `windows:ci`. Install the pinned tool with `mise install --locked github:nextest-rs/nextest` before using `--skip-tools`, as the Windows workflow does. |
 | Git | `git --version` | Needed for checkout and sync work. |
 | PowerShell | `$PSVersionTable.PSVersion` | Windows PowerShell 5.1 works; PowerShell 7 is quieter with mise shell hooks. |
 
@@ -195,7 +203,7 @@ from this skill.
 | `OPENSHELL_MXC_SKIP_ARM64` | `0` | Set to `1` to skip ARM64 when using `all` tasks. |
 | `OPENSHELL_WINDOWS_BUILD_JOBS` | `CARGO_BUILD_JOBS`, then `4` | Positive Cargo job limit used by the wrapper. |
 | `CARGO_TARGET_DIR` | `target` under repo root | Override Cargo output location. Use a short absolute path when x64-to-ARM64 builds approach Windows path-length limits. |
-| `Z3_LIBRARY_PATH_OVERRIDE` | unset | Directory containing an x64 system `libz3.lib`; not valid for ARM64. |
+| `Z3_LIBRARY_PATH_OVERRIDE` | unset | Directory containing target-compatible system `libz3.lib` and `libz3.dll`, used instead of the prebuilt download. |
 | `Z3_SYS_Z3_HEADER` | unset | Full `z3.h` path required with a system Z3 library. |
 | `Z3_SYS_Z3_VERSION` | `5.1.0` | Pinned official prebuilt Z3 release selected by the wrapper. |
 | `READ_ONLY_GITHUB_TOKEN` | unset | Optional token for the Z3 release lookup; GitHub Actions supplies `github.token`. |
@@ -237,30 +245,45 @@ $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
 switch ($arch.ToString()) {
     "X64" {
         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." }
     }
     "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." }
     }
     default {
         throw "Unsupported Windows host architecture for OpenShell MSVC validation: $arch"
     }
 }
 ```
 
+Full validation requires an MXC-capable host. E2E exits nonzero when any
+required runtime scenario fails or skips.
+
 On x64 hosts, `windows:ci` is the full current CI contract and runs in this
 order:
 
 1. x64 check.
 2. ARM64 check, unless `OPENSHELL_MXC_SKIP_ARM64=1`.
 3. x64 release build.
 4. ARM64 release build, unless skipped.
-5. Native x64 workspace tests.
+5. Native x64 workspace tests through Nextest's `ci` profile with `openshell-server/test-support` enabled.
 6. Focused unsupported-driver contract tests.
 7. Artifact reporting.
 
@@ -294,9 +317,10 @@ Run `rust:lockfiles:check`, `sdk:ts:ci`, and `go:ci` through the Windows-aware
 tasks when validating those surfaces. Do not count the Go
 Windows ARM64 race-detector exclusion or POSIX permission-bit skips as security
 coverage. SDK test dependencies must remain at their lockfile versions.
-Its Rust check, Clippy, and test dependencies enter the same MSVC environment
-for the native host target and use an inherited compiler wrapper when it is
-available. Linux glibc
+Its Clippy dependency enters the MSVC environment for the native host target
+and uses an inherited compiler wrapper when it is available. The separate
+`rust:check` and `test:rust` tasks use the same wrapper; `pre-commit` runs
+formatting and lint checks, not those compile and test tasks. Linux glibc
 installer tests and Linux service/RPM packaging-asset tests skip explicitly;
 the Linux build-environment shell-helper test also skips; cross-platform checks
 continue to run. The blocking Windows Clippy pass excludes unsupported
@@ -318,8 +342,8 @@ crypto dependency builds.
 | `windows:check:arm64` | `cargo check --workspace` for `aarch64-pc-windows-msvc`, with the same top-level exclusions. |
 | `windows:build:x64` | Release-builds `openshell-gateway.exe`, `openshell.exe`, `openshell-supervisor.exe`, and `openshell-windows-sandbox.exe` for x64. |
 | `windows:build:arm64` | Release-builds the same four binaries for ARM64. |
-| `windows:test:x64` | Runs native x64 workspace tests with `--no-fail-fast`, excluding unsupported Windows packages as top-level workspace targets. |
-| `windows:test:arm64` | Runs native ARM64 workspace tests with `--no-fail-fast` and the same package exclusions. Rejects non-ARM64 hosts. |
+| `windows:test:x64` | Runs `cargo nextest run --profile ci --workspace` natively on x64 with `openshell-server/test-support` and the selected Z3 features; excludes unsupported Windows packages as top-level workspace targets. The profile disables fail-fast. |
+| `windows:test:arm64` | Runs the same Nextest CI profile and test-support features natively on ARM64, with the same package exclusions. Rejects non-ARM64 hosts. |
 | `windows:test:unsupported:x64` | Re-runs focused `openshell-gateway` tests for unsupported Windows driver behavior. |
 | `windows:test:unsupported:arm64` | Re-runs the same focused contracts natively on ARM64. Rejects non-ARM64 hosts. |
 | `windows:test:mxc-real:x64` | Runs the serial, ignored real-`wxc-exec` integration suite natively on x64 through the MSVC wrapper. Rejects non-x64 hosts. |
@@ -469,7 +493,7 @@ When reporting `windows:ci`, distinguish these categories:
 - Passed tests from the full ARM64 workspace test log when run on a native
   ARM64 host.
 - The focused unsupported-contract re-run.
-- Explicit Cargo ignored tests, usually ignored doc examples.
+- Nextest skipped tests, including ignored real-MXC tests. Nextest does not run doc tests.
 - Tests hidden by `#[cfg(not(target_os = "windows"))]`; these often appear as
   `running 0 tests`, not as ignored tests.
 - Test-name `filtered out` counts from focused `cargo test` invocations.
@@ -484,8 +508,8 @@ Useful log files:
 | `build-aarch64-pc-windows-msvc-check.log` | ARM64 check output. |
 | `build-x86_64-pc-windows-msvc-release.log` | x64 release build output. |
 | `build-aarch64-pc-windows-msvc-release.log` | ARM64 release build output. |
-| `test-x86_64-pc-windows-msvc.log` | Full native x64 workspace test output. |
-| `test-aarch64-pc-windows-msvc.log` | Full native ARM64 workspace test output. |
+| `test-x86_64-pc-windows-msvc-precommit.log` | Native x64 workspace Nextest output from `windows:test:x64` or `windows:ci`, with server test support. |
+| `test-aarch64-pc-windows-msvc-precommit.log` | Native ARM64 workspace Nextest output from `windows:test:arm64`, with server test support. |
 | `test-x86_64-pc-windows-msvc-unsupported-*.log` | Focused unsupported-driver contract output. |
 | `test-aarch64-pc-windows-msvc-unsupported-*.log` | Focused native ARM64 contract output. |
 | `test-x86_64-pc-windows-msvc-mxc-real.log` | Native x64 real-MXC integration output. |

.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 native Windows MSVC and MXC runtime 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.
 

.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

@@ -25,7 +25,7 @@ Do not rely on this file for a full inventory. The detailed public and contribut
 | `crates/openshell-conformance/` | CLI conformance library | Reusable driver-agnostic scenarios and command runner |
 | `crates/openshell-server/` | Gateway server | Control-plane API, sandbox lifecycle, auth boundary |
 | `crates/openshell-sandbox/` | Sandbox runtime | Capability-free workload launcher, process identity, and seccomp-mediated I/O |
-| `crates/openshell-mxc-boundary/` | Windows sandbox boundary | Windows boundary library and dedicated openshell-windows-sandbox binary for MXC process operations, containment confirmation, and shared-protocol forwarding |
+| [`crates/openshell-mxc-boundary/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-mxc-boundary) (`windows` branch) | Windows sandbox boundary | Windows boundary library and dedicated openshell-windows-sandbox binary for MXC process operations, containment confirmation, and shared-protocol forwarding |
 | `crates/openshell-supervisor/` | Supervisor runtime | Gateway session, policy evaluation, credentials, and upstream networking |
 | `crates/openshell-binary-identity/` | Binary identity | Shared trusted procfs executable identity resolution for isolation backends |
 | `crates/openshell-isolation-interface/` | Isolation backend interface | RFC 0012 `IsolationBackend` trait and types; the supervisor-facing runtime contract |
@@ -50,7 +50,7 @@ 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 ProcessContainer backend that pairs a host isolation-backend supervisor with `openshell-windows-sandbox` inside MXC |
+| [`crates/openshell-driver-mxc/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-driver-mxc) (`windows` branch) | Microsoft MXC compute driver | In-process Windows ProcessContainer backend that pairs a host isolation-backend supervisor with `openshell-windows-sandbox` inside MXC |
 | `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

@@ -66,11 +66,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