dotnet · AR-May · Jun 17, 2026 · Apr 13, 2026 · Apr 24, 2026 · Apr 14, 2026
diff --git a/MSBuild.Dev.slnf b/MSBuild.Dev.slnf
@@ -11,6 +11,8 @@
       "src\\MSBuild.UnitTests\\Microsoft.Build.CommandLine.UnitTests.csproj",
       "src\\MSBuild\\MSBuild.csproj",
       "src\\MSBuild.Benchmarks\\MSBuild.Benchmarks.csproj",
+      "src\\MSBuild.Coordinator\\MSBuild.Coordinator.csproj",
+      "src\\MSBuild.Coordinator.UnitTests\\MSBuild.Coordinator.UnitTests.csproj",
       "src\\StringTools\\StringTools.csproj",
       "src\\Tasks.UnitTests\\Microsoft.Build.Tasks.UnitTests.csproj",
       "src\\Tasks\\Microsoft.Build.Tasks.csproj",

diff --git a/MSBuild.SourceBuild.slnf b/MSBuild.SourceBuild.slnf
@@ -5,6 +5,7 @@
       "src\\Build\\Microsoft.Build.csproj",
       "src\\Framework\\Microsoft.Build.Framework.csproj",
       "src\\MSBuild\\MSBuild.csproj",
+      "src\\MSBuild.Coordinator\\MSBuild.Coordinator.csproj",
       "src\\Package\\Localization\\Localization.csproj",
       "src\\Tasks\\Microsoft.Build.Tasks.csproj",
       "src\\Utilities\\Microsoft.Build.Utilities.csproj",

diff --git a/MSBuild.slnx b/MSBuild.slnx
@@ -74,6 +74,14 @@
   <Project Path="src/MSBuild.Bootstrap/MSBuild.Bootstrap.csproj">
     <Platform Solution="*|x64" Project="x64" />
   </Project>
+  <Project Path="src/MSBuild.Coordinator.UnitTests/MSBuild.Coordinator.UnitTests.csproj" Id="a6947a1c-6f87-47de-a23f-519b9e05af47">
+    <Platform Solution="*|ARM64" Project="arm64" />
+    <Platform Solution="*|x64" Project="x64" />
+  </Project>
+  <Project Path="src/MSBuild.Coordinator/MSBuild.Coordinator.csproj" Id="96b6c6a6-8219-4c15-b296-c30c6222ca02">
+    <Platform Solution="*|ARM64" Project="arm64" />
+    <Platform Solution="*|x64" Project="x64" />
+  </Project>
   <Project Path="src/MSBuild.EndToEnd.Tests/Microsoft.Build.EndToEnd.Tests.csproj">
     <Platform Solution="*|x64" Project="x64" />
   </Project>

diff --git a/documentation/MSBuild-Coordinator.md b/documentation/MSBuild-Coordinator.md
@@ -0,0 +1,308 @@
+# MSBuild Build Coordinator: Architecture and Flow
+
+> **Important Note:** This document describes the architecture and design of the MSBuild Build Coordinator at a high level. 
+> For current implementation details, class structures, method signatures, or specific code patterns, always consult the source code directly.
+> This ensures you're working with accurate, up-to-date information.
+
+## Overview
+
+The **MSBuild Build Coordinator** is a resource management system that orchestrates and enforces fair-share allocation of build nodes across multiple simultaneous MSBuild processes. It prevents system resource exhaustion by maintaining a global node budget and dynamically distributing available nodes among competing builds.
+
+### Purpose
+
+When multiple MSBuild processes run concurrently (common in CI/CD environments, distributed builds, or user multi-tasking), each process could independently attempt to spawn the maximum number of nodes, leading to:
+- System resource exhaustion
+- Excessive memory consumption
+- CPU contention and slowdown
+- Reduced overall build throughput
+
+The coordinator solves this by:
+1. **Enforcing a global node budget** (defaults to processor count)
+2. **Implementing fair-share allocation** to distribute available nodes fairly
+3. **Monitoring build health** via periodic heartbeats
+4. **Auto-shutting down** after a timeout period
+
+---
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    System with Multiple Builds                   │
+└──────────────────────────────────────────────────────────────────┘
+
+  Build 1               Build 2               Build 3
+    │                     │                     │
+    │ RequestNodes(4)     │ RequestNodes(4)     │ RequestNodes(4)
+    │                     │                     │
+    └─────────────────────┼─────────────────────┘
+            (via Named Pipes - IPC)
+                    ↓
+      ┌────────────────────────────────────┐
+      │   MSBuild Build Coordinator        │
+      │                                    │
+      │  ┌──────────────────────────────┐  │
+      │  │  Node Budget Manager         │  │
+      │  │  • Total Budget: 8 nodes     │  │
+      │  │  • Allocated: 8              │  │
+      │  │  • Available: 0              │  │
+      │  └──────────────────────────────┘  │
+      │                                    │
+      │  ┌──────────────────────────────┐  │
+      │  │  Active Builds               │  │
+      │  │  • Build 1: 4 nodes          │  │
+      │  │  • Build 2: 4 nodes          │  │
+      │  └──────────────────────────────┘  │
+      │                                    │
+      │  ┌──────────────────────────────┐  │
+      │  │  Waiting Builds Queue        │  │
+      │  │  • Build 3: waiting          │  │
+      │  └──────────────────────────────┘  │
+      └────────────────────────────────────┘
+            ↓                      ↓
+    Grant(nodes=2)        Wait(queued)
+```
+
+---
+
+## Component Architecture
+
+### Key Components
+
+**Coordinator Server** ([src/MSBuild.Coordinator/](src/MSBuild.Coordinator/))
+- `CoordinatorServer.cs` - Main server that listens for client connections via named pipe
+- `NodeBudgetManager.cs` - Implements node allocation and fair-share logic
+- `ClientConnection.cs` - Manages individual client connections
+- `BuildGrant.cs` - Represents a node allocation to a build
+- `Program.cs` - Server launcher and singleton instance management
+
+**Client-Side** ([src/Build/BackEnd/BuildManager/](src/Build/BackEnd/BuildManager/))
+- `CoordinatorClient.cs` - Client connection handler integrated into BuildManager
+- `BuildManager.cs` - Requests nodes from coordinator and sets build parallelism
+
+**Protocol** ([src/Framework/Coordinator/](src/Framework/Coordinator/))
+- Message types: `RequestNodesMessage`, `HeartbeatMessage`, `ReleaseNodesMessage`, `NodeGrantMessage`, `WaitMessage`, `ErrorMessage`
+- `CoordinatorSettings.cs` - Configuration management
+- `Protocol.cs` - Protocol versioning
+
+### Directory Structure
+
+```
+src/
+├── MSBuild.Coordinator/                           # Coordinator server executable
+│   ├── CoordinatorServer.cs
+│   ├── NodeBudgetManager.cs
+│   ├── ClientConnection.cs
+│   ├── BuildGrant.cs
+│   ├── Program.cs
+│   └── ...
+├── Framework/Coordinator/                         # Protocol and interfaces
+│   ├── RequestNodesMessage.cs
+│   ├── HeartbeatMessage.cs
+│   ├── ReleaseNodesMessage.cs
+│   ├── NodeGrantMessage.cs
+│   ├── WaitMessage.cs
+│   ├── ErrorMessage.cs
+│   ├── CoordinatorSettings.cs
+│   ├── Protocol.cs
+│   └── ...
+├── Build/BackEnd/BuildManager/
+│   ├── BuildManager.cs
+│   ├── CoordinatorClient.cs
+│   └── ...
+└── MSBuild.Coordinator.UnitTests/
+    ├── CoordinatorServerTests.cs
+    ├── NodeBudgetManagerTests.cs
+    └── ...
+```
+
+---
+
+## Communication Protocol
+
+### Message Types
+
+The coordinator uses a binary protocol with six message types:
+
+**Client → Server:**
+- `RequestNodesMessage` - Sent when a build starts, requests a node grant
+- `HeartbeatMessage` - Periodic keep-alive message (default: every 5 seconds)
+- `ReleaseNodesMessage` - Sent when build completes, releases allocated nodes
+
+**Server → Client:**
+- `NodeGrantMessage` - Grants nodes to a build
+- `WaitMessage` - Indicates build is queued, no nodes immediately available
+- `ErrorMessage` - Indicates an error condition (e.g., protocol version mismatch)
+
+Each message includes a protocol version for compatibility verification.
+
+**Source:** [src/Framework/Coordinator/](src/Framework/Coordinator/)
+
+### Message Flow Example
+
+```
+Successful Grant:
+  Build → RequestNodesMessage(4)
+  Build ← NodeGrantMessage(4)
+  Build → Heartbeat (every 5s)
+  Build → ReleaseNodesMessage (on completion)
+
+Build Queued:
+  Build → RequestNodesMessage(4)
+  Build ← WaitMessage (queue position 1)
+  Build → Heartbeat (every 5s while waiting)
+  Eventually: Build ← NodeGrantMessage(2) [after fair-share calculation]
+```
+
+---
+
+## Fair-Share Allocation Algorithm
+
+### Core Concept
+
+When multiple builds compete for limited nodes, the coordinator distributes them fairly using:
+
+```
+fair_share = max(1, available_nodes / (waiting_builds + 1))
+```
+
+This ensures:
+- Every waiting build gets at least 1 node
+- Available nodes are divided equally among contenders
+- Nodes are processed from the wait queue as they become available
+
+### Example Scenarios
+
+**Two Competing Builds** (8 total nodes)
+- Build A gets 4 nodes (active)
+- Build B requests 4 nodes → Available: 4, Waiting: 1
+- Fair share: max(1, 4 / 2) = 2 nodes
+- Build B granted 2 nodes
+
+**Multiple Builds in Queue** (8 total nodes)
+- Build A uses 4 nodes
+- Build B waiting (wants 6) and Build C waiting (wants 8)
+- When A completes: 4 nodes available, 2 waiting
+- Build B: fair_share = max(1, 4 / 2) = 2 nodes
+- Build C: fair_share = max(1, 2 / 1) = 2 nodes
+
+---
+
+## Integration with BuildManager
+
+### How Coordination Works
+
+During build initialization:
+
+1. BuildManager checks if `MSBUILDUSECOORDINATOR` environment variable is set
+2. If enabled, `CoordinatorClient` attempts to connect to the coordinator
+3. Sends `RequestNodesMessage` with desired node count
+4. Receives either `NodeGrantMessage` (nodes granted) or `WaitMessage` (queued)
+5. Updates build's maximum node count based on grant
+6. During execution, spawns build nodes limited by this capped value
+7. On completion, sends `ReleaseNodesMessage` to free nodes for other builds
+
+**Key Principle:** The coordinator is entirely optional. If it's unavailable or disabled, the build uses its requested node count without coordination.
+
+**Sources:**
+- [src/Build/BackEnd/BuildManager/BuildManager.cs](src/Build/BackEnd/BuildManager/BuildManager.cs)
+- [src/Build/BackEnd/BuildManager/CoordinatorClient.cs](src/Build/BackEnd/BuildManager/CoordinatorClient.cs)
+- [src/Framework/Traits.cs](src/Framework/Traits.cs) - Enablement logic
+
+---
+
+## Configuration and Environment Variables
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MSBUILDUSECOORDINATOR` | (empty) | Enable coordinator (set to any value to enable) |
+| `MSBUILDCOORDINATORPIPENAME` | `msbuild-coordinator-{UserName}` | Override default pipe name |
+| `MSBUILDCOORDINATORNODEBUDGET` | Processor count | Override total node budget |
+| `MSBUILDCOORDINATORHEARTBEAT` | 5000 | Override heartbeat interval (ms) |
+| `MSBUILDCOORDINATORSHUTDOWNTIMEOUT` | 60000 | Override shutdown timeout (ms) |
+
+---
+
+## Lifecycle and Operation
+
+### Coordinator Startup
+
+1. When first MSBuild process needs coordination, it attempts to start the coordinator
+2. Coordinator uses a system-wide mechanism to ensure only one instance runs
+3. If an instance already exists, the new process connects as a client instead
+4. Coordinator listens on a named pipe for client connections
+
+**Source:** [src/MSBuild.Coordinator/Program.cs](src/MSBuild.Coordinator/Program.cs)
+
+### Heartbeat Monitoring
+
+The coordinator detects stalled or crashed clients through periodic heartbeats:
+
+- Clients send heartbeat messages at configured intervals (default: 5 seconds)
+- Coordinator tracks missed heartbeats
+- After threshold is reached (default: 3 misses = 15 seconds), client is considered stalled
+- Coordinator automatically releases nodes allocated to stalled client
+- Waiting builds can then be granted those nodes
+
+**Source:** [src/MSBuild.Coordinator/CoordinatorServer.cs](src/MSBuild.Coordinator/CoordinatorServer.cs)
+
+### Graceful Shutdown
+
+When a build completes normally:
+
+1. Client sends `ReleaseNodesMessage` with its grant ID
+2. Coordinator frees those nodes
+3. Processes waiting queue to allocate freed nodes to waiting builds
+4. If no active or waiting clients remain, coordinator enters timeout mode
+5. After 60 seconds of inactivity, coordinator exits
+
+**Source:** [src/MSBuild.Coordinator/CoordinatorServer.cs](src/MSBuild.Coordinator/CoordinatorServer.cs)
+
+---
+
+## Error Handling
+
+### Resilient Design
+
+The coordinator system is designed to be fully optional:
+
+- **Unavailable coordinator** → Build proceeds without coordination using full node count
+- **Connection failure** → Build proceeds independently
+- **Protocol mismatch** → Graceful fallback to unlimited nodes
+- **Crashed client** → Detected via heartbeat timeout, resources cleaned up
+- **Coordinator crash** → Next build can launch new instance
+
+This means coordinator failures never block or degrade build execution—they only disable coordination.
+
+**Sources:**
+- [src/Build/BackEnd/BuildManager/CoordinatorClient.cs](src/Build/BackEnd/BuildManager/CoordinatorClient.cs)
+- [src/MSBuild.Coordinator/CoordinatorServer.cs](src/MSBuild.Coordinator/CoordinatorServer.cs)
+
+---
+
+## Testing
+
+### Unit Tests
+
+Comprehensive test coverage in [src/MSBuild.Coordinator.UnitTests/](src/MSBuild.Coordinator.UnitTests/):
+
+- Protocol serialization/deserialization
+- Node budget manager allocation logic
+- Fair-share algorithm correctness
+- Heartbeat monitoring
+- Multi-build coordination scenarios
+- Error conditions and edge cases
+
+---
+
+## Source Code References
+
+For detailed implementation information, refer to:
+
+- **Server Implementation:** `src/MSBuild.Coordinator/`
+- **Protocol Definitions:** `src/Framework/Coordinator/`
+- **Client Integration:** `src/Build/BackEnd/BuildManager/` 
+- **Configuration:** `src/Framework/Traits.cs`, `src/Framework/Coordinator/CoordinatorSettings.cs`
+- **Tests:** `src/MSBuild.Coordinator.UnitTests/`
@@ -113,6 +113,10 @@
       <FreshlyBuiltBinaries Include="$(MSBuildTaskHostBinPath)**\*.pdb" />
       <FreshlyBuiltBinaries Include="$(MSBuildTaskHostBinPath)**\*.exe.config" />
       <FreshlyBuiltBinaries Include="$(MSBuildTaskHostBinPath)**\*.dll.config" />
+
+      <!-- Only copy the coordinator's own binaries; transitive dependencies (e.g. Microsoft.IO.Redist)
+           are already provided by the Bootstrap/MSBuild output. -->
+      <FreshlyBuiltBinaries Include="$(CoordinatorBinPath)**\MSBuild.Coordinator.*" />
 
       <FreshlyBuiltBinariesx64 Include="$(X64BinPath)**\*.dll" />
       <FreshlyBuiltBinariesx64 Include="$(X64BinPath)**\*.exe" />
@@ -126,6 +130,8 @@
       <FreshlyBuiltBinariesx64 Include="$(MSBuildTaskHostX64BinPath)**\*.pdb" />
       <FreshlyBuiltBinariesx64 Include="$(MSBuildTaskHostX64BinPath)**\*.exe.config" />
       <FreshlyBuiltBinariesx64 Include="$(MSBuildTaskHostX64BinPath)**\*.dll.config" />
+
+      <FreshlyBuiltBinariesx64 Include="$(CoordinatorX64BinPath)**\MSBuild.Coordinator.*" />
 
       <FreshlyBuiltBinariesArm64 Include="$(X64BinPath)\Microsoft.Build.Tasks.Core.dll" />
       <FreshlyBuiltBinariesArm64 Include="$(X64BinPath)\Microsoft.Build.dll" />
@@ -134,6 +140,8 @@
       <FreshlyBuiltBinariesArm64 Include="$(Arm64BinPath)**\*.pdb" />
       <FreshlyBuiltBinariesArm64 Include="$(Arm64BinPath)**\*.exe.config" />
       <FreshlyBuiltBinariesArm64 Include="$(Arm64BinPath)**\*.dll.config" />
+
+      <FreshlyBuiltBinariesArm64 Include="$(CoordinatorArm64BinPath)**\MSBuild.Coordinator.*" />
 
       <FreshlyBuiltRootProjects Include="$(OutputPath)Microsoft.Common.props" />
       <FreshlyBuiltRootProjects Include="$(OutputPath)Microsoft.VisualStudioVersion.*.Common.props" />
@@ -238,6 +246,7 @@
 
     <PropertyGroup>
       <InstallDir>$(ArtifactsBinDir)bootstrap\core\</InstallDir>
+      <CoordinatorBinPath>$(ArtifactsBinDir)MSBuild.Coordinator\$(Configuration)\$(TargetFramework.ToLowerInvariant())\</CoordinatorBinPath>
     </PropertyGroup>
 
     <InstallDotNetCoreTask DotNetInstallScriptRootPath="$(DotNetRoot)" InstallDir="$(InstallDir)" Version="$(BootstrapSdkVersion)"/>
@@ -248,6 +257,9 @@
     <ItemGroup>
      <!-- *.deps.json are excluded because the SDK rewrites these files for consistency with the rest of the SDK, so take their version. -->
       <FreshlyBuiltNetBinaries Include="$(OutDir)**\*.*" Exclude="$(OutDir)**\*.deps.json" />
+      <FreshlyBuiltNetBinaries Include="$(CoordinatorBinPath)**\*.dll" />
+      <FreshlyBuiltNetBinaries Include="$(CoordinatorBinPath)**\*.exe" />
+      <FreshlyBuiltNetBinaries Include="$(CoordinatorBinPath)**\*.runtimeconfig.json" />
     </ItemGroup>
 
     <!-- The copying of these dependencies is required by bootstrap\**\sdk\**\NuGet.RestoreEx.targets. Otherwise NuGet.Build.Tasks.dll can not be found. -->

diff --git a/src/Build/AssemblyInfo.cs b/src/Build/AssemblyInfo.cs
@@ -25,6 +25,7 @@
 [assembly: InternalsVisibleTo("Microsoft.Build.UnitTests.Shared, PublicKey=002400000480000094000000060200000024000052534131000400000100010015c01ae1f50e8cc09ba9eac9147cf8fd9fce2cfe9f8dce4f7301c4132ca9fb50ce8cbf1df4dc18dd4d210e4345c744ecb3365ed327efdbc52603faa5e21daa11234c8c4a73e51f03bf192544581ebe107adee3a34928e39d04e524a9ce729d5090bfd7dad9d10c722c0def9ccc08ff0a03790e48bcd1f9b6c476063e1966a1c4")]
 [assembly: InternalsVisibleTo("Microsoft.Build.Tasks.Cop, PublicKey=002400000480000094000000060200000024000052534131000400000100010015c01ae1f50e8cc09ba9eac9147cf8fd9fce2cfe9f8dce4f7301c4132ca9fb50ce8cbf1df4dc18dd4d210e4345c744ecb3365ed327efdbc52603faa5e21daa11234c8c4a73e51f03bf192544581ebe107adee3a34928e39d04e524a9ce729d5090bfd7dad9d10c722c0def9ccc08ff0a03790e48bcd1f9b6c476063e1966a1c4")]
 [assembly: InternalsVisibleTo("Microsoft.Build.BuildCheck.UnitTests, PublicKey=002400000480000094000000060200000024000052534131000400000100010015c01ae1f50e8cc09ba9eac9147cf8fd9fce2cfe9f8dce4f7301c4132ca9fb50ce8cbf1df4dc18dd4d210e4345c744ecb3365ed327efdbc52603faa5e21daa11234c8c4a73e51f03bf192544581ebe107adee3a34928e39d04e524a9ce729d5090bfd7dad9d10c722c0def9ccc08ff0a03790e48bcd1f9b6c476063e1966a1c4")]
+[assembly: InternalsVisibleTo("MSBuild.Coordinator.UnitTests, PublicKey=002400000480000094000000060200000024000052534131000400000100010015c01ae1f50e8cc09ba9eac9147cf8fd9fce2cfe9f8dce4f7301c4132ca9fb50ce8cbf1df4dc18dd4d210e4345c744ecb3365ed327efdbc52603faa5e21daa11234c8c4a73e51f03bf192544581ebe107adee3a34928e39d04e524a9ce729d5090bfd7dad9d10c722c0def9ccc08ff0a03790e48bcd1f9b6c476063e1966a1c4")]
 // DO NOT expose Internals to "Microsoft.Build.UnitTests.OM.OrcasCompatibility" as this assembly is supposed to only see public interface
 
 // This will enable passing the SafeDirectories flag to any P/Invoke calls/implementations within the assembly,