Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

feat(windows): package the endpoint as an MSI

shukieshahe048babd899b
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 297edf03..bd31f1c4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -348,3 +348,144 @@ jobs:
- name: Endpoint install smoke test
run: sh packaging/macos/smoke-endpoint.sh
+
+ # Builds the MSI and installs it, because the only claim worth making about an installer is that
+ # installing it works. Everything else -- that the files are in the package, that the custom action
+ # is sequenced correctly -- is inference from a manifest.
+ #
+ # The mirror of linux-package-smoke, which installs the .deb and checks the endpoint came up.
+ windows-package-smoke:
+ runs-on: windows-2025
+ # Bounded for the same reason windows-test is: a wedged msiexec would otherwise hold a runner for
+ # the GitHub default of six hours.
+ timeout-minutes: 25
+ defaults:
+ run:
+ shell: pwsh
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-go@v5
+ with:
+ go-version-file: cli/beacon/go.mod
+
+ # Cheap, and it runs before anything is built: a syntax error in a packaging script would
+ # otherwise surface inside an MSI custom action, where what the user sees is a rollback.
+ - name: Validate the packaging scripts
+ run: pwsh -NoProfile -File packaging/windows/test-endpoint-scripts.ps1
+
+ - name: Build the binaries
+ run: |
+ Set-Location cli\beacon-hooks
+ go build -ldflags "-s -w" -o beacon-hooks.exe .
+ if ($LASTEXITCODE -ne 0) { throw "beacon-hooks build failed" }
+ # Embedded before the CLI is built, or the CLI carries the placeholder and hook
+ # installation fails at runtime with an architecture mismatch.
+ Copy-Item beacon-hooks.exe ..\beacon\internal\embedded\hooks.bin -Force
+ Set-Location ..\beacon
+ go build -o beacon.exe .
+ if ($LASTEXITCODE -ne 0) { throw "beacon build failed" }
+
+ - name: Build the collector
+ run: |
+ go install go.opentelemetry.io/collector/cmd/[email protected]
+ Set-Location collector-builder
+ New-Item -ItemType Directory -Force -Path dist | Out-Null
+ $env:GOOS = 'windows'; $env:GOARCH = 'amd64'; $env:CGO_ENABLED = '0'
+ & "$(go env GOPATH)\bin\builder.exe" --config builder.yaml
+ if ($LASTEXITCODE -ne 0) { throw "collector build failed" }
+ # The builder names its output from dist.name verbatim and does not append .exe, even
+ # though what it emits is a PE binary. Both spellings are accepted so a future builder
+ # version that does append it keeps working.
+ $produced = 'dist\beacon-otelcol\beacon-otelcol'
+ if (-not (Test-Path -LiteralPath $produced) -and (Test-Path -LiteralPath "$produced.exe")) {
+ $produced = "$produced.exe"
+ }
+ if (-not (Test-Path -LiteralPath $produced)) { throw "collector build produced no binary" }
+ Copy-Item $produced beacon-otelcol.exe
+
+ - name: Build the MSI
+ run: |
+ # A real-looking version rather than 0.0.0: MSI compares versions field by field, and
+ # building at 0.0.0 would mean the upgrade path is never exercised here.
+ pwsh -NoProfile -File packaging\windows\build-msi.ps1 `
+ -Version 0.0.1 `
+ -BeaconExe cli\beacon\beacon.exe `
+ -HooksExe cli\beacon-hooks\beacon-hooks.exe `
+ -CollectorExe collector-builder\beacon-otelcol.exe `
+ -OutFile $env:GITHUB_WORKSPACE\BeaconEndpointAgent.msi
+ if (-not (Test-Path -LiteralPath "$env:GITHUB_WORKSPACE\BeaconEndpointAgent.msi")) {
+ throw "no MSI was produced"
+ }
+
+ - name: Install it
+ run: |
+ # /qn is silent, and the verbose log is what makes a custom-action failure diagnosable --
+ # without it msiexec reports only an exit code.
+ $log = "$env:GITHUB_WORKSPACE\install.log"
+ $p = Start-Process msiexec.exe -Wait -PassThru -ArgumentList @(
+ '/i', "$env:GITHUB_WORKSPACE\BeaconEndpointAgent.msi", '/qn', '/l*v', $log
+ )
+ if ($p.ExitCode -ne 0) {
+ Write-Output "--- install log (tail) ---"
+ Get-Content -LiteralPath $log -Tail 120 | Write-Output
+ throw "msiexec /i exited $($p.ExitCode)"
+ }
+
+ - name: The endpoint must be installed and running
+ run: |
+ $beacon = Join-Path $env:ProgramFiles 'Beacon\bin\beacon.exe'
+ if (-not (Test-Path -LiteralPath $beacon)) { throw "beacon.exe is not at $beacon" }
+ foreach ($name in @('beacon-hooks.exe', 'beacon-otelcol.exe')) {
+ $path = Join-Path $env:ProgramFiles "Beacon\bin\$name"
+ if (-not (Test-Path -LiteralPath $path)) { throw "$name is missing from the payload" }
+ }
+
+ # The claim a package makes is a *running* endpoint, so the service is asserted rather than
+ # the files. Installing three binaries and registering nothing would pass a file check.
+ & sc.exe query BeaconCollector | Out-String | Write-Output
+ $state = (& sc.exe query BeaconCollector | Out-String)
+ if ($state -notmatch 'RUNNING') {
+ & $beacon endpoint status --system | Out-String | Write-Output
+ throw "the BeaconCollector service is not running after install"
+ }
+
+ $status = & $beacon endpoint status --system --json | Out-String
+ Write-Output $status
+ if ($status -notmatch '"kind"\s*:\s*"windows-service"') {
+ throw "status does not report the windows-service backend; the install picked a different one"
+ }
+
+ - name: Uninstall must remove the service and keep the data
+ run: |
+ $logDir = Join-Path $env:ProgramData 'Beacon\Endpoint\logs'
+ $configPath = Join-Path $env:ProgramData 'Beacon\Endpoint\config.json'
+ $hadConfig = Test-Path -LiteralPath $configPath
+
+ $p = Start-Process msiexec.exe -Wait -PassThru -ArgumentList @(
+ '/x', "$env:GITHUB_WORKSPACE\BeaconEndpointAgent.msi", '/qn',
+ '/l*v', "$env:GITHUB_WORKSPACE\uninstall.log"
+ )
+ if ($p.ExitCode -ne 0) {
+ Get-Content -LiteralPath "$env:GITHUB_WORKSPACE\uninstall.log" -Tail 120 | Write-Output
+ throw "msiexec /x exited $($p.ExitCode)"
+ }
+
+ # The failure this guards against is the one review caught in the service backend: an
+ # uninstall that reports success while the service stays registered and starts at boot.
+ $query = (& sc.exe query BeaconCollector 2>&1 | Out-String)
+ if ($query -notmatch '1060') {
+ Write-Output $query
+ throw "the BeaconCollector service still exists after uninstall"
+ }
+
+ if (Test-Path -LiteralPath (Join-Path $env:ProgramFiles 'Beacon\bin\beacon.exe')) {
+ throw "the payload was not removed"
+ }
+
+ # Retention, which is a contract rather than an accident: an uninstall is often the first
+ # half of an upgrade, and destroying an operator's configuration and collected telemetry is
+ # not something a package removal should do without being asked.
+ if ($hadConfig -and -not (Test-Path -LiteralPath $configPath)) {
+ throw "uninstall removed the endpoint configuration; only a purge should do that"
+ }
+ Write-Output "config retained: $(Test-Path -LiteralPath $configPath), logs retained: $(Test-Path -LiteralPath $logDir)"
diff --git a/packaging/windows/beacon.wxs b/packaging/windows/beacon.wxs
new file mode 100644
index 00000000..4a15c4bc
--- /dev/null
+++ b/packaging/windows/beacon.wxs
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ The Windows counterpart of the signed macOS .pkg and the Linux .deb/.rpm.
+
+ The point of a package is that installing it is the whole user-facing action. It must produce a
+ running system-mode endpoint that is capturing the interactive user's agent activity, not a
+ directory of binaries plus two commands to discover. Everything below exists to make that true.
+
+ The payload deliberately mirrors /opt/beacon: bin beside scripts, so the collector sits next to the
+ CLI where DiscoverBinary looks for it first, and so the layout is one thing to reason about across
+ three platforms.
+
+ Unsigned for now, by decision. An unsigned MSI shows a SmartScreen warning, which is acceptable for
+ early adopters and not for GA; Authenticode is a later change that adds signing to the release job
+ without altering anything here.
+-->
+<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
+ <Package
+ Name="Beacon Endpoint Agent"
+ Manufacturer="Asymptote Labs"
+ Version="$(var.Version)"
+ Language="1033"
+ Scope="perMachine"
+ Compressed="yes"
+ InstallerVersion="500"
+ UpgradeCode="6D3B2A94-5E1C-4C8A-9F2D-7B4E1A6C3D50">
+
+ <SummaryInformation Description="Endpoint telemetry agent for AI coding agents" />
+
+ <!--
+ Left on the default schedule (afterInstallValidate), which removes the older product early in
+ the sequence. That means an upgrade runs the old package's uninstall action, then lays down the
+ new files, then runs the install action below — ending in an install, which is the state we
+ want.
+
+ This is the same hazard the RPM packaging documents, where the outgoing package's %preun runs
+ after the incoming package's %post and stops the service the new one just started. The ordering
+ here avoids it rather than needing a %posttrans equivalent, but it is the reason the schedule is
+ stated explicitly instead of inherited silently.
+ -->
+ <MajorUpgrade
+ AllowSameVersionUpgrades="yes"
+ DowngradeErrorMessage="A newer version of [ProductName] is already installed." />
+
+ <MediaTemplate EmbedCab="yes" />
+
+ <StandardDirectory Id="ProgramFiles64Folder">
+ <Directory Id="INSTALLFOLDER" Name="Beacon">
+ <Directory Id="BinFolder" Name="bin" />
+ <Directory Id="ScriptsFolder" Name="scripts" />
+ </Directory>
+ </StandardDirectory>
+
+ <ComponentGroup Id="BeaconPayload">
+ <Component Id="BeaconCli" Directory="BinFolder">
+ <File Id="BeaconExeFile" Source="$(var.StageDir)\bin\beacon.exe" KeyPath="yes" />
+ </Component>
+ <!--
+ The hook adapter ships as its own file even though the CLI also embeds a copy. The embedded
+ one is what `endpoint hooks install` writes into a user profile; this one is what a fleet
+ tool or a support engineer can invoke directly, and having it on disk makes an install
+ inspectable.
+ -->
+ <Component Id="BeaconHooks" Directory="BinFolder">
+ <File Id="BeaconHooksExeFile" Source="$(var.StageDir)\bin\beacon-hooks.exe" KeyPath="yes" />
+ </Component>
+ <Component Id="BeaconCollector" Directory="BinFolder">
+ <File Id="BeaconOtelcolExeFile" Source="$(var.StageDir)\bin\beacon-otelcol.exe" KeyPath="yes" />
+ </Component>
+ <Component Id="InstallScript" Directory="ScriptsFolder">
+ <File Id="InstallEndpointScriptFile" Source="$(var.StageDir)\scripts\install-endpoint.ps1" KeyPath="yes" />
+ </Component>
+ <Component Id="UninstallScript" Directory="ScriptsFolder">
+ <File Id="UninstallEndpointScriptFile" Source="$(var.StageDir)\scripts\uninstall-endpoint.ps1" KeyPath="yes" />
+ </Component>
+ </ComponentGroup>
+
+ <Feature Id="Main" Title="Beacon Endpoint Agent" Level="1">
+ <ComponentGroupRef Id="BeaconPayload" />
+ </Feature>
+
+ <!--
+ Both actions run the shipped PowerShell scripts rather than invoking beacon.exe with their own
+ flag lists, exactly as the .deb and .rpm postinstall scripts call install-endpoint.sh. Two lists
+ of flags that have to agree is a thing that stops agreeing.
+
+ deferred with Impersonate="no" so they run as LocalSystem: the install writes under
+ %ProgramData% and registers a service, neither of which an unelevated token can do. It also
+ means `user-config repair-installed` takes its LocalSystem path and resolves the console user
+ through WTS, rather than configuring whichever account happened to launch the installer.
+
+ -NonInteractive and -NoProfile because there is no console here and a machine's PowerShell
+ profile must not be able to change what an installer does.
+ -->
+ <CustomAction Id="BeaconInstallEndpoint"
+ Directory="ScriptsFolder"
+ ExeCommand="&quot;[System64Folder]WindowsPowerShell\v1.0\powershell.exe&quot; -NoProfile -NonInteractive -ExecutionPolicy Bypass -File &quot;install-endpoint.ps1&quot;"
+ Execute="deferred"
+ Impersonate="no"
+ Return="check" />
+
+ <!--
+ Return="ignore" on removal, and Before="RemoveFiles" because the script needs beacon.exe to
+ still exist. A failed uninstall action leaves the package half-removed, which is a worse state
+ for a user than a leftover service they can see and stop.
+ -->
+ <CustomAction Id="BeaconUninstallEndpoint"
+ Directory="ScriptsFolder"
+ ExeCommand="&quot;[System64Folder]WindowsPowerShell\v1.0\powershell.exe&quot; -NoProfile -NonInteractive -ExecutionPolicy Bypass -File &quot;uninstall-endpoint.ps1&quot;"
+ Execute="deferred"
+ Impersonate="no"
+ Return="ignore" />
+
+ <InstallExecuteSequence>
+ <!-- NOT REMOVE, so this runs on a first install and on an upgrade, but not during removal. -->
+ <Custom Action="BeaconInstallEndpoint" After="InstallFiles" Condition="NOT REMOVE" />
+ <Custom Action="BeaconUninstallEndpoint" Before="RemoveFiles" Condition="REMOVE=&quot;ALL&quot;" />
+ </InstallExecuteSequence>
+ </Package>
+</Wix>
diff --git a/packaging/windows/build-msi.ps1 b/packaging/windows/build-msi.ps1
new file mode 100644
index 00000000..68db849c
--- /dev/null
+++ b/packaging/windows/build-msi.ps1
@@ -0,0 +1,87 @@
+# Builds the Beacon Endpoint Agent MSI from already-built binaries.
+#
+# Deliberately does not build Go code. The release job compiles the binaries once, for the targets it
+# publishes, and this packages what it produced -- so an MSI can never contain a binary that differs
+# from the one in the archive next to it.
+#
+# Usage:
+# .\build-msi.ps1 -Version 0.1.2 -BeaconExe ... -HooksExe ... -CollectorExe ... -OutFile ...
+[CmdletBinding()]
+param(
+ [Parameter(Mandatory = $true)][string]$Version,
+ [Parameter(Mandatory = $true)][string]$BeaconExe,
+ [Parameter(Mandatory = $true)][string]$HooksExe,
+ [Parameter(Mandatory = $true)][string]$CollectorExe,
+ [string]$OutFile,
+ # Pinned by the caller so a build is reproducible and a WiX release cannot change the output
+ # underneath us.
+ [string]$WixVersion = '5.0.2'
+)
+
+$ErrorActionPreference = 'Stop'
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# MSI ProductVersion is strictly numeric: major.minor.build, each field bounded. A tag like v0.1.2
+# arrives with the v attached, and a snapshot version carries a suffix, neither of which MSI accepts
+# -- so they are normalized here rather than failing deep inside WiX with a message about a field.
+$normalized = $Version.TrimStart('v', 'V')
+if ($normalized -match '^(\d+)\.(\d+)\.(\d+)') {
+ $normalized = "$($Matches[1]).$($Matches[2]).$($Matches[3])"
+} else {
+ throw "version '$Version' is not major.minor.patch; MSI ProductVersion cannot represent it"
+}
+
+if ([string]::IsNullOrWhiteSpace($OutFile)) {
+ $OutFile = Join-Path (Get-Location) "BeaconEndpointAgent-$normalized-x64.msi"
+}
+
+foreach ($input in @($BeaconExe, $HooksExe, $CollectorExe)) {
+ if (-not (Test-Path -LiteralPath $input)) {
+ throw "input binary not found: $input"
+ }
+}
+
+# Staged into a layout the .wxs references by relative path, so the WiX source does not have to know
+# where the caller keeps its build outputs.
+$stage = Join-Path ([System.IO.Path]::GetTempPath()) ("beacon-msi-" + [Guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Force -Path (Join-Path $stage 'bin'), (Join-Path $stage 'scripts') | Out-Null
+try {
+ Copy-Item -LiteralPath $BeaconExe -Destination (Join-Path $stage 'bin\beacon.exe')
+ Copy-Item -LiteralPath $HooksExe -Destination (Join-Path $stage 'bin\beacon-hooks.exe')
+ Copy-Item -LiteralPath $CollectorExe -Destination (Join-Path $stage 'bin\beacon-otelcol.exe')
+ Copy-Item -LiteralPath (Join-Path $scriptDir 'install-endpoint.ps1') -Destination (Join-Path $stage 'scripts\install-endpoint.ps1')
+ Copy-Item -LiteralPath (Join-Path $scriptDir 'uninstall-endpoint.ps1') -Destination (Join-Path $stage 'scripts\uninstall-endpoint.ps1')
+
+ # The dotnet tool rather than a preinstalled WiX: it pins a version, it does not depend on what a
+ # runner image happens to ship, and it works the same on a maintainer's machine.
+ $wix = Get-Command wix -ErrorAction SilentlyContinue
+ if (-not $wix) {
+ Write-Output "installing WiX $WixVersion"
+ & dotnet tool install --global wix --version $WixVersion
+ if ($LASTEXITCODE -ne 0) { throw "installing WiX failed with exit code $LASTEXITCODE" }
+ $env:PATH = "$env:PATH;$env:USERPROFILE\.dotnet\tools"
+ }
+
+ Write-Output "building $OutFile (version $normalized)"
+ & wix build `
+ -arch x64 `
+ -d "Version=$normalized" `
+ -d "StageDir=$stage" `
+ -o $OutFile `
+ (Join-Path $scriptDir 'beacon.wxs')
+ if ($LASTEXITCODE -ne 0) { throw "wix build failed with exit code $LASTEXITCODE" }
+
+ if (-not (Test-Path -LiteralPath $OutFile)) {
+ throw "wix reported success but produced no file at $OutFile"
+ }
+
+ # The checksum ships beside the package for the same reason the macOS .pkg has one: it is the
+ # only integrity check available on an unsigned artifact, and it stays mandatory once signing is
+ # added rather than being replaced by it.
+ $hash = (Get-FileHash -LiteralPath $OutFile -Algorithm SHA256).Hash.ToLower()
+ "$hash $(Split-Path -Leaf $OutFile)" | Set-Content -LiteralPath "$OutFile.sha256" -Encoding ascii
+ Write-Output "sha256: $hash"
+ Write-Output $OutFile
+} finally {
+ Remove-Item -LiteralPath $stage -Recurse -Force -ErrorAction SilentlyContinue
+}
diff --git a/packaging/windows/install-endpoint.ps1 b/packaging/windows/install-endpoint.ps1
new file mode 100644
index 00000000..e80491d0
--- /dev/null
+++ b/packaging/windows/install-endpoint.ps1
@@ -0,0 +1,82 @@
+# Installs the Beacon endpoint in system mode on Windows.
+#
+# Called by the MSI's install custom action, and usable directly for fleet tooling (Intune, SCCM, a
+# login script). Configuration is environment-first, matching packaging/linux/install-endpoint.sh and
+# packaging/macos/install-endpoint.sh so a mixed fleet has one contract rather than three.
+#
+# There is deliberately only one definition of what a system install means. The MSI runs this script
+# rather than invoking beacon.exe with its own flag list, exactly as the .deb and .rpm postinstall
+# scripts call install-endpoint.sh -- two lists of flags that must agree is a thing that stops
+# agreeing.
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+
+function Get-EnvOrDefault {
+ param([string]$Name, [string]$Default)
+ $value = [Environment]::GetEnvironmentVariable($Name)
+ if ([string]::IsNullOrWhiteSpace($value)) { return $Default }
+ return $value
+}
+
+# The installed layout, which mirrors /opt/beacon: bin next to scripts, so the collector sits beside
+# the CLI where DiscoverBinary looks for it first.
+$installRoot = Get-EnvOrDefault 'BEACON_INSTALL_ROOT' (Join-Path $env:ProgramFiles 'Beacon')
+$beaconBin = Get-EnvOrDefault 'BEACON_BIN' (Join-Path $installRoot 'bin\beacon.exe')
+
+if (-not (Test-Path -LiteralPath $beaconBin)) {
+ throw "beacon.exe was not found at $beaconBin"
+}
+
+$harnesses = Get-EnvOrDefault 'BEACON_ENDPOINT_HARNESSES' 'claude,codex'
+$grpcPort = Get-EnvOrDefault 'BEACON_OTLP_GRPC_PORT' '4317'
+$httpPort = Get-EnvOrDefault 'BEACON_OTLP_HTTP_PORT' '4318'
+$collector = Get-EnvOrDefault 'BEACON_COLLECTOR' ''
+$service = Get-EnvOrDefault 'BEACON_SERVICE' ''
+$noStart = Get-EnvOrDefault 'BEACON_NO_START' '0'
+
+# Auto-detected rather than required, so a manual invocation without BEACON_COLLECTOR still works.
+# DiscoverBinary would find this on its own -- it is passed explicitly so that a failure says which
+# collector was expected instead of "no collector found".
+if ([string]::IsNullOrWhiteSpace($collector)) {
+ $packaged = Join-Path $installRoot 'bin\beacon-otelcol.exe'
+ if (Test-Path -LiteralPath $packaged) { $collector = $packaged }
+}
+
+$installArgs = @(
+ 'endpoint', 'install', '--system',
+ '--harness', $harnesses,
+ '--otlp-grpc-port', $grpcPort,
+ '--otlp-http-port', $httpPort
+)
+if (-not [string]::IsNullOrWhiteSpace($collector)) { $installArgs += @('--collector', $collector) }
+# Empty means auto-detect, which on Windows resolves to the Service Control Manager for a system
+# install. Passing it explicitly is for a fleet that wants the supervised fallback instead.
+if (-not [string]::IsNullOrWhiteSpace($service)) { $installArgs += @('--service', $service) }
+if ($noStart -eq '1') { $installArgs += '--no-start' }
+
+Write-Output "beacon: installing the system endpoint"
+& $beaconBin @installArgs
+if ($LASTEXITCODE -ne 0) {
+ throw "beacon endpoint install failed with exit code $LASTEXITCODE"
+}
+
+# A system endpoint runs elevated, and the install above configured *this* account's Claude Code and
+# Codex settings. For an MSI that account is whoever ran the installer, or SYSTEM when a management
+# tool deployed it -- neither of which is necessarily the person at the keyboard. This second step
+# resolves that person and configures their runtime.
+#
+# Without it the collector runs perfectly and captures nothing anyone cares about. That is not
+# hypothetical: it is exactly what the Linux package did before the equivalent step was added.
+#
+# Non-fatal, and it says why when it cannot. An unattended install may have no interactive user at
+# all, which is a legitimate outcome rather than a failure.
+Write-Output "beacon: configuring the interactive user's agent runtime"
+& $beaconBin endpoint user-config repair-installed --system --harness $harnesses
+if ($LASTEXITCODE -ne 0) {
+ Write-Warning ("beacon: could not configure the interactive user's agent runtime; " +
+ "run 'beacon endpoint user-config repair-installed --system' once logged in")
+}
+
+Write-Output "beacon: endpoint installed. Check it with: beacon endpoint status --system"
diff --git a/packaging/windows/test-endpoint-scripts.ps1 b/packaging/windows/test-endpoint-scripts.ps1
new file mode 100644
index 00000000..5e07c58b
--- /dev/null
+++ b/packaging/windows/test-endpoint-scripts.ps1
@@ -0,0 +1,77 @@
+# Validates the Windows packaging scripts without installing anything.
+#
+# The counterpart of packaging/macos/test-endpoint-scripts.sh, and it exists for the same reason: a
+# packaging script only runs during an install, so a syntax error in one is invisible until someone
+# installs the package -- at which point it fails inside an MSI custom action, where the diagnostic a
+# user sees is a rollback and an error code.
+#
+# Parsing is most of the value here. PowerShell parses a whole file before executing any of it, so an
+# unbalanced brace anywhere means nothing runs at all.
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$failures = 0
+
+function Fail {
+ param([string]$Message)
+ Write-Error $Message
+ $script:failures++
+}
+
+$scripts = @('install-endpoint.ps1', 'uninstall-endpoint.ps1', 'build-msi.ps1')
+foreach ($name in $scripts) {
+ $path = Join-Path $scriptDir $name
+ if (-not (Test-Path -LiteralPath $path)) {
+ Fail "missing script: $name"
+ continue
+ }
+ $tokens = $null
+ $errors = $null
+ [System.Management.Automation.Language.Parser]::ParseFile($path, [ref]$tokens, [ref]$errors) | Out-Null
+ if ($errors -and $errors.Count -gt 0) {
+ foreach ($parseError in $errors) { Write-Output " $($parseError.Extent.StartLineNumber): $($parseError.Message)" }
+ Fail "$name does not parse"
+ } else {
+ Write-Output "ok: $name parses"
+ }
+}
+
+# The install and uninstall contracts, asserted as text rather than by running them: both need
+# elevation and a real machine, and what matters here is that the flags have not drifted from what
+# the other platforms' scripts pass.
+$install = Get-Content -Raw -LiteralPath (Join-Path $scriptDir 'install-endpoint.ps1')
+foreach ($needle in @('endpoint', 'install', '--system', 'user-config', 'repair-installed')) {
+ if ($install -notmatch [regex]::Escape($needle)) {
+ Fail "install-endpoint.ps1 no longer references '$needle'"
+ }
+}
+# The step whose absence made the Linux package produce a healthy collector that captured nothing.
+if ($install -notmatch 'repair-installed') {
+ Fail "install-endpoint.ps1 must configure the interactive user's runtime, or the endpoint captures nothing"
+}
+
+$uninstall = Get-Content -Raw -LiteralPath (Join-Path $scriptDir 'uninstall-endpoint.ps1')
+foreach ($needle in @('--keep-logs', '--keep-config', 'BEACON_PURGE')) {
+ if ($uninstall -notmatch [regex]::Escape($needle)) {
+ Fail "uninstall-endpoint.ps1 no longer honors '$needle'; removing the product must not destroy configuration or logs by default"
+ }
+}
+
+# The WiX source has to keep running the scripts rather than growing its own copy of the flags.
+$wxs = Get-Content -Raw -LiteralPath (Join-Path $scriptDir 'beacon.wxs')
+foreach ($needle in @('install-endpoint.ps1', 'uninstall-endpoint.ps1')) {
+ if ($wxs -notmatch [regex]::Escape($needle)) {
+ Fail "beacon.wxs no longer invokes $needle"
+ }
+}
+if ($wxs -match 'ExeCommand="[^"]*beacon\.exe') {
+ Fail "beacon.wxs invokes beacon.exe directly; the install contract belongs in one place, not two"
+}
+
+if ($failures -gt 0) {
+ Write-Output "$failures check(s) failed"
+ exit 1
+}
+Write-Output 'Windows packaging scripts passed.'
diff --git a/packaging/windows/uninstall-endpoint.ps1 b/packaging/windows/uninstall-endpoint.ps1
new file mode 100644
index 00000000..e53ac2d1
--- /dev/null
+++ b/packaging/windows/uninstall-endpoint.ps1
@@ -0,0 +1,49 @@
+# Removes the Beacon endpoint on Windows.
+#
+# Called by the MSI's uninstall custom action, and usable directly for fleet tooling.
+#
+# Configuration and logs survive by default. That is the same retention contract the Debian packaging
+# follows: removing the product should not destroy an operator's settings or the telemetry they have
+# collected, because an uninstall is often the first half of an upgrade or a reinstall. Set
+# BEACON_PURGE=1 to remove them, which is the deliberate, separate act.
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+
+function Get-EnvOrDefault {
+ param([string]$Name, [string]$Default)
+ $value = [Environment]::GetEnvironmentVariable($Name)
+ if ([string]::IsNullOrWhiteSpace($value)) { return $Default }
+ return $value
+}
+
+$installRoot = Get-EnvOrDefault 'BEACON_INSTALL_ROOT' (Join-Path $env:ProgramFiles 'Beacon')
+$beaconBin = Get-EnvOrDefault 'BEACON_BIN' (Join-Path $installRoot 'bin\beacon.exe')
+$purge = Get-EnvOrDefault 'BEACON_PURGE' '0'
+
+if (-not (Test-Path -LiteralPath $beaconBin)) {
+ # Nothing to do, and not an error. An uninstall must not fail because the thing it removes is
+ # already gone -- a failed uninstall custom action leaves the MSI half-removed, which is a worse
+ # state than either finishing or never starting.
+ Write-Output "beacon: $beaconBin is not present; nothing to uninstall"
+ exit 0
+}
+
+$uninstallArgs = @('endpoint', 'uninstall', '--system')
+if ($purge -ne '1') {
+ $uninstallArgs += @('--keep-logs', '--keep-config')
+ Write-Output "beacon: removing the endpoint, keeping configuration and logs (set BEACON_PURGE=1 to remove them)"
+} else {
+ Write-Output "beacon: removing the endpoint, configuration and logs"
+}
+
+& $beaconBin @uninstallArgs
+if ($LASTEXITCODE -ne 0) {
+ # Reported, not thrown. The service and its registration are what matter here, and `endpoint
+ # uninstall` is idempotent -- so a non-zero exit is worth surfacing but not worth wedging an MSI
+ # removal over. A user who cannot uninstall the package has a worse problem than a leftover file.
+ Write-Warning "beacon: endpoint uninstall exited $LASTEXITCODE; check 'beacon endpoint status --system'"
+}
+
+Write-Output "beacon: endpoint removed"