Telli · Oct 8, 2026
diff --git a/.github/scripts/Publish-Binaries.ps1 b/.github/scripts/Publish-Binaries.ps1
@@ -0,0 +1,40 @@
+param(
+    [Parameter(Mandatory)][ValidateSet('win-x64','win-arm64','linux-x64','linux-arm64','osx-x64','osx-arm64')][string]$Runtime,
+    [Parameter(Mandatory)][ValidatePattern('^\d+\.\d+\.\d+([-.][0-9A-Za-z.-]+)?$')][string]$Version,
+    [string]$OutputDirectory = 'artifacts/binaries'
+)
+$ErrorActionPreference = 'Stop'
+$repositoryRoot = (Resolve-Path (Join-Path $PSScriptRoot '../..')).Path
+$outputRoot = [System.IO.Path]::GetFullPath($OutputDirectory)
+$scratch = Join-Path ([System.IO.Path]::GetTempPath()) ('sharpclaw-publish-' + [Guid]::NewGuid().ToString('N'))
+try {
+    $publish = Join-Path $scratch 'publish'
+    $stage = Join-Path $scratch 'stage'
+    New-Item -ItemType Directory -Path $stage,$outputRoot -Force | Out-Null
+    & dotnet publish (Join-Path $repositoryRoot 'src/SharpClaw.Code.Cli/SharpClaw.Code.Cli.csproj') --configuration Release --runtime $Runtime --self-contained true --output $publish --disable-build-servers `
+        -p:PackAsTool=false -p:PublishSingleFile=true -p:PublishTrimmed=false -p:PublishAot=false `
+        -p:IncludeNativeLibrariesForSelfExtract=true -p:IncludeAllContentForSelfExtract=true `
+        "-p:Version=$Version" "-p:PackageVersion=$Version" "-p:InformationalVersion=$Version" -p:IncludeSourceRevisionInInformationalVersion=false
+    if ($LASTEXITCODE -ne 0) { throw "Binary publish failed: $Runtime" }
+    $sourceExecutable = if ($Runtime.StartsWith('win-')) { 'SharpClaw.Code.Cli.exe' } else { 'SharpClaw.Code.Cli' }
+    $executable = if ($Runtime.StartsWith('win-')) { 'sharpclaw.exe' } else { 'sharpclaw' }
+    Copy-Item (Join-Path $publish $sourceExecutable) (Join-Path $stage $executable)
+    Copy-Item (Join-Path $repositoryRoot 'LICENSE') $stage
+    Copy-Item (Join-Path $repositoryRoot 'README.md') $stage
+    $stem = "sharpclaw-$Version-$Runtime"
+    if ($Runtime.StartsWith('win-')) {
+        $archive = Join-Path $outputRoot "$stem.zip"
+        Compress-Archive -Path (Join-Path $stage '*') -DestinationPath $archive -Force
+    } else {
+        & chmod +x (Join-Path $stage $executable)
+        if ($LASTEXITCODE -ne 0) { throw 'Could not preserve executable permission.' }
+        $archive = Join-Path $outputRoot "$stem.tar.gz"
+        & tar -czf $archive -C $stage $executable LICENSE README.md
+        if ($LASTEXITCODE -ne 0) { throw 'Could not create binary archive.' }
+    }
+    $checksum = (Get-FileHash $archive -Algorithm SHA256).Hash.ToLowerInvariant()
+    [System.IO.File]::WriteAllText("$archive.sha256", "$checksum  $([System.IO.Path]::GetFileName($archive))`n")
+    Write-Host "Created $archive"
+} finally {
+    if (Test-Path $scratch) { Remove-Item $scratch -Recurse -Force }
+}
diff --git a/.github/scripts/Test-Binary.ps1 b/.github/scripts/Test-Binary.ps1
@@ -0,0 +1,65 @@
+param(
+    [Parameter(Mandatory)][string]$Archive,
+    [Parameter(Mandatory)][ValidateSet('win-x64','win-arm64','linux-x64','linux-arm64','osx-x64','osx-arm64')][string]$Runtime,
+    [Parameter(Mandatory)][string]$Version
+)
+$ErrorActionPreference = 'Stop'
+$repositoryRoot = (Resolve-Path (Join-Path $PSScriptRoot '../..')).Path
+$architecture = [System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture.ToString().ToLowerInvariant()
+$platform = if ($IsWindows) { 'win' } elseif ($IsMacOS) { 'osx' } else { 'linux' }
+if ("$platform-$architecture" -ne $Runtime) { throw "Smoke must execute on a matching runner: expected $Runtime, got $platform-$architecture." }
+$scratch = Join-Path ([System.IO.Path]::GetTempPath()) ('sharpclaw-binary-smoke-' + [Guid]::NewGuid().ToString('N'))
+$previousBinary = $env:SHARPCLAW_TEST_BINARY
+try {
+    $extract = Join-Path $scratch 'extract'
+    $workspace = Join-Path $scratch 'workspace'
+    New-Item -ItemType Directory -Path $extract,$workspace -Force | Out-Null
+    $archivePath = (Resolve-Path $Archive).Path
+    $checksumPath = "$archivePath.sha256"
+    if (!(Test-Path $checksumPath)) { throw 'Binary archive checksum is missing.' }
+    $expected = (Get-Content $checksumPath -Raw).Split(' ')[0]
+    if ((Get-FileHash $archivePath -Algorithm SHA256).Hash.ToLowerInvariant() -ne $expected) { throw 'Binary archive checksum mismatch.' }
+    if ($IsWindows) { Expand-Archive $archivePath $extract }
+    else {
+        & tar -xzf $archivePath -C $extract
+        if ($LASTEXITCODE -ne 0) { throw 'Archive extraction failed.' }
+    }
+    $executableName = if ($IsWindows) { 'sharpclaw.exe' } else { 'sharpclaw' }
+    $binary = Join-Path $extract $executableName
+    $files = @(Get-ChildItem $extract -File | Select-Object -ExpandProperty Name | Sort-Object)
+    if (($files -join ',') -ne ((@($executableName,'LICENSE','README.md') | Sort-Object) -join ',')) { throw 'Archive must contain exactly executable, LICENSE, and README.md.' }
+    # An empty PATH and isolated runtime roots prove the native bundle starts without resolving an ambient dotnet host.
+    $start = [System.Diagnostics.ProcessStartInfo]::new($binary)
+    $start.UseShellExecute = $false
+    $start.RedirectStandardOutput = $true
+    $start.RedirectStandardError = $true
+    $start.WorkingDirectory = $workspace
+    $start.ArgumentList.Add('--output-format'); $start.ArgumentList.Add('json'); $start.ArgumentList.Add('version')
+    $start.Environment['PATH'] = ''
+    foreach ($key in @('DOTNET_ROOT','DOTNET_ROOT_X64','DOTNET_ROOT_ARM64')) { $start.Environment[$key] = (Join-Path $scratch 'no-dotnet') }
+    $start.Environment['DOTNET_MULTILEVEL_LOOKUP'] = '0'
+    $process = [System.Diagnostics.Process]::Start($start)
+    $stdout = $process.StandardOutput.ReadToEndAsync(); $stderr = $process.StandardError.ReadToEndAsync()
+    if (!$process.WaitForExit(30000)) { $process.Kill($true); throw 'Self-contained startup timed out.' }
+    $text = $stdout.GetAwaiter().GetResult(); $errorText = $stderr.GetAwaiter().GetResult()
+    if ($process.ExitCode -ne 0) { throw "No-runtime version failed: $errorText" }
+    $process.Dispose()
+    $versionResult = $text | ConvertFrom-Json
+    if ($versionResult.succeeded -ne $true -or $versionResult.data.InformationalVersion -ne $Version) { throw "Binary did not report release identity $Version`: $text" }
+    [System.IO.File]::WriteAllText((Join-Path $workspace 'note.txt'), 'offline binary SQLite index smoke')
+    & $binary --cwd $workspace --output-format json verify --permission-mode dangerFullAccess
+    if ($LASTEXITCODE -ne 0) { throw 'Non-.NET verification skip failed.' }
+    & $binary --cwd $workspace --output-format json index refresh
+    if ($LASTEXITCODE -ne 0) { throw 'SQLite index refresh failed.' }
+    & $binary --cwd $workspace --output-format json index stats
+    if ($LASTEXITCODE -ne 0) { throw 'SQLite index stats failed.' }
+    # Real SDK client tests launch the relocated native binary, exercise both default and elevated calls,
+    # and prove bundled SQLite, Roslyn BuildHost, semantic rename/undo, and actual build/TRX test results.
+    $env:SHARPCLAW_TEST_BINARY = $binary
+    & dotnet test (Join-Path $repositoryRoot 'tests/SharpClaw.Code.IntegrationTests/SharpClaw.Code.IntegrationTests.csproj') --configuration Release --filter 'FullyQualifiedName~InboundMcpStdioTests' --disable-build-servers
+    if ($LASTEXITCODE -ne 0) { throw 'Relocated binary MCP/semantic/build/test smoke failed.' }
+    Write-Host "Binary smoke passed: $Runtime $Version"
+} finally {
+    $env:SHARPCLAW_TEST_BINARY = $previousBinary
+    if (Test-Path $scratch) { Remove-Item $scratch -Recurse -Force }
+}
diff --git a/.github/scripts/Test-Packages.ps1 b/.github/scripts/Test-Packages.ps1
@@ -9,6 +9,7 @@ $scratchRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("sharpclaw-package-s
 $packageOutput = Join-Path $scratchRoot "packages"
 $toolPath = Join-Path $scratchRoot "tool"
 $consumerPath = Join-Path $scratchRoot "consumer"
+$previousNugetPackages = $env:NUGET_PACKAGES
 $nugetConfigPath = Join-Path $scratchRoot "NuGet.Config"
 
 try {
@@ -18,7 +19,7 @@ try {
 
     $packages = @(Get-ChildItem $packageOutput -Filter "*.nupkg" | Where-Object { $_.Name -notlike "*.symbols.nupkg" })
     $unexpected = @($packages | Where-Object { $_.BaseName -notlike "SharpClaw.Code*" })
-    if ($packages.Count -ne 21) { throw "Expected 21 production packages, found $($packages.Count)." }
+    if ($packages.Count -ne 22) { throw "Expected 22 production packages, found $($packages.Count)." }
     if ($unexpected.Count -gt 0) { throw "Unexpected packages: $($unexpected.Name -join ', ')." }
 
     & dotnet new console --framework net10.0 --output $consumerPath --no-restore
@@ -34,18 +35,41 @@ try {
     & dotnet nuget add source "https://api.nuget.org/v3/index.json" --name nuget.org --configfile $nugetConfigPath
     if ($LASTEXITCODE -ne 0) { throw "Could not configure the NuGet.org package source." }
 
+    # Reused preview versions must never resolve an older global-cache or public-feed SharpClaw package.
+    $env:NUGET_PACKAGES = Join-Path $scratchRoot "consumer-package-cache"
+    [xml]$config = Get-Content $nugetConfigPath -Raw
+    $mapping = $config.CreateElement("packageSourceMapping")
+    foreach ($entry in @(@("sharpclaw-local", "SharpClaw.Code*"), @("nuget.org", "*"))) {
+        $source = $config.CreateElement("packageSource"); $source.SetAttribute("key", $entry[0])
+        $pattern = $config.CreateElement("package"); $pattern.SetAttribute("pattern", $entry[1])
+        $source.AppendChild($pattern) | Out-Null; $mapping.AppendChild($source) | Out-Null
+    }
+    $config.configuration.AppendChild($mapping) | Out-Null
+    $config.Save($nugetConfigPath)
     & dotnet restore (Join-Path $consumerPath "consumer.csproj") --configfile $nugetConfigPath
     if ($LASTEXITCODE -ne 0) { throw "Could not restore the aggregate SDK package." }
+    [System.IO.File]::WriteAllText((Join-Path $consumerPath "Program.cs"), @'
+using Microsoft.Extensions.DependencyInjection;
+using SharpClaw.Code.Runtime;
+using SharpClaw.Code.Mcp.Server;
+using SharpClaw.Code.Mcp.Abstractions;
+var services = new ServiceCollection();
+services.AddSharpClawRuntime();
+services.AddSharpClawMcpServer();
+using var provider = services.BuildServiceProvider();
+Console.WriteLine(provider.GetRequiredService<ISharpClawMcpServer>().GetType().Name);
+'@)
     & dotnet build (Join-Path $consumerPath "consumer.csproj") --configuration $Configuration --no-restore
     if ($LASTEXITCODE -ne 0) { throw "The aggregate SDK package failed to build in a clean consumer." }
 
-    & dotnet tool install --tool-path $toolPath SharpClaw.Code.Cli --version $PackageVersion --add-source $packageOutput --ignore-failed-sources
+    & dotnet tool install --tool-path $toolPath SharpClaw.Code.Cli --version $PackageVersion --configfile $nugetConfigPath
     if ($LASTEXITCODE -ne 0) { throw "The CLI tool package failed to install." }
     $toolExecutable = if ($IsWindows) { Join-Path $toolPath "sharpclaw.exe" } else { Join-Path $toolPath "sharpclaw" }
     & $toolExecutable version
     if ($LASTEXITCODE -ne 0) { throw "The installed CLI tool failed its version smoke test." }
 }
 finally {
+    $env:NUGET_PACKAGES = $previousNugetPackages
     if (Test-Path $scratchRoot) {
         Remove-Item $scratchRoot -Recurse -Force
     }

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -5,12 +5,13 @@ on:
     tags: ['v*']
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
-  publish:
+  validate:
     runs-on: ubuntu-latest
-    environment: nuget
+    outputs:
+      version: ${{ steps.version.outputs.value }}
     steps:
       - uses: actions/checkout@v7
       - name: Validate semantic version tag
@@ -22,8 +23,7 @@ jobs:
           $version = $env:REF_NAME -replace '^v', ''
           if ($version -notmatch '^\d+\.\d+\.\d+([-.][0-9A-Za-z.-]+)?$') { throw "Tag is not a supported semantic version." }
           "value=$version" >> $env:GITHUB_OUTPUT
-      - name: Setup .NET
-        uses: actions/setup-dotnet@v6
+      - uses: actions/setup-dotnet@v6
         with:
           dotnet-version: '10.0.x'
       - name: Restore
@@ -32,17 +32,109 @@ jobs:
         shell: pwsh
         run: ./.github/scripts/Test-VulnerablePackages.ps1 -Target SharpClawCode.sln
       - name: Build
-        run: dotnet build SharpClawCode.sln --no-restore --configuration Release --warnaserror
+        run: dotnet build SharpClawCode.sln --no-restore --configuration Release --warnaserror -p:Version=${{ steps.version.outputs.value }}
       - name: Test
         run: dotnet test SharpClawCode.sln --no-build --configuration Release
+      - name: Agent scenario gates
+        run: |
+          dotnet run --project src/SharpClaw.Code.Cli/SharpClaw.Code.Cli.csproj --no-build --configuration Release -- test run
+          dotnet run --project src/SharpClaw.Code.Cli/SharpClaw.Code.Cli.csproj --no-build --configuration Release -- test gates
+      - name: Documentation
+        run: |
+          dotnet tool restore
+          dotnet docfx docs/docfx.json --warningsAsErrors
       - name: Pack production artifacts
-        run: dotnet pack SharpClawCode.Packages.slnf --no-build --configuration Release --output ./nupkg -p:PackageVersion=${{ steps.version.outputs.value }}
+        run: dotnet pack SharpClawCode.Packages.slnf --no-build --configuration Release --output ./nupkg -p:Version=${{ steps.version.outputs.value }} -p:PackageVersion=${{ steps.version.outputs.value }}
       - name: Verify package installability
         shell: pwsh
         run: ./.github/scripts/Test-Packages.ps1 -PackageVersion ${{ steps.version.outputs.value }}
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-packages
+          path: nupkg/*
+          if-no-files-found: error
+
+  binaries:
+    needs: validate
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - rid: win-x64
+            runner: windows-2025
+          - rid: win-arm64
+            runner: windows-11-arm
+          - rid: linux-x64
+            runner: ubuntu-24.04
+          - rid: linux-arm64
+            runner: ubuntu-24.04-arm
+          - rid: osx-x64
+            runner: macos-15-intel
+          - rid: osx-arm64
+            runner: macos-15
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: '10.0.x'
+      - name: Publish self-contained binary
+        shell: pwsh
+        run: ./.github/scripts/Publish-Binaries.ps1 -Runtime ${{ matrix.rid }} -Version ${{ needs.validate.outputs.version }}
+      - name: Unpack and smoke actual architecture
+        shell: pwsh
+        env:
+          RELEASE_VERSION: ${{ needs.validate.outputs.version }}
+          RELEASE_RID: ${{ matrix.rid }}
+        run: |
+          $extension = if ($env:RELEASE_RID.StartsWith('win-')) { 'zip' } else { 'tar.gz' }
+          ./.github/scripts/Test-Binary.ps1 -Archive "artifacts/binaries/sharpclaw-$env:RELEASE_VERSION-$env:RELEASE_RID.$extension" -Runtime $env:RELEASE_RID -Version $env:RELEASE_VERSION
+      - uses: actions/upload-artifact@v7
+        with:
+          name: binary-${{ matrix.rid }}
+          path: artifacts/binaries/*
+          if-no-files-found: error
+
+  publish:
+    needs: [validate, binaries]
+    runs-on: ubuntu-latest
+    environment: nuget
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: '10.0.x'
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-packages
+          path: release
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: binary-*
+          merge-multiple: true
+          path: release
+      - name: Validate complete release artifact set
+        shell: pwsh
+        env:
+          RELEASE_VERSION: ${{ needs.validate.outputs.version }}
+        run: |
+          $packages = @(Get-ChildItem release -Filter '*.nupkg')
+          $symbols = @(Get-ChildItem release -Filter '*.snupkg')
+          if ($packages.Count -ne 22 -or $symbols.Count -ne 22) { throw 'Release requires all 22 production packages and symbol packages.' }
+          foreach ($rid in @('win-x64','win-arm64','linux-x64','linux-arm64','osx-x64','osx-arm64')) {
+            $extension = if ($rid.StartsWith('win-')) { 'zip' } else { 'tar.gz' }
+            $archive = "release/sharpclaw-$env:RELEASE_VERSION-$rid.$extension"
+            if (!(Test-Path $archive) -or !(Test-Path "$archive.sha256")) { throw "Missing binary/checksum: $rid" }
+            $expected = (Get-Content "$archive.sha256" -Raw).Split(' ')[0]
+            if ((Get-FileHash $archive -Algorithm SHA256).Hash.ToLowerInvariant() -ne $expected) { throw "Checksum mismatch: $rid" }
+          }
       - name: Push to NuGet
-        run: dotnet nuget push './nupkg/*.nupkg' --api-key '${{ secrets.NUGET_API_KEY }}' --source https://api.nuget.org/v3/index.json --skip-duplicate
+        env:
+          NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
+        run: dotnet nuget push 'release/*.nupkg' --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json --skip-duplicate
       - name: Create GitHub release
         env:
           GH_TOKEN: ${{ github.token }}
-        run: gh release create '${{ github.ref_name }}' ./nupkg/*.nupkg ./nupkg/*.snupkg --verify-tag --generate-notes --title '${{ github.ref_name }}'
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release create "$RELEASE_TAG" release/* --verify-tag --generate-notes --title "$RELEASE_TAG"
diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -23,7 +23,10 @@
     <PackageVersion Include="Microsoft.Extensions.AI" Version="10.10.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.10.1" />
     <PackageVersion Include="ModelContextProtocol" Version="1.2.0" />
+    <PackageVersion Include="ModelContextProtocol.AspNetCore" Version="1.2.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.9.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.9.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="5.9.0" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.12" />
     <PackageVersion Include="Spectre.Console" Version="0.55.0" />
     <PackageVersion Include="System.Security.Cryptography.ProtectedData" Version="10.0.12" />