0024: Local Windows verification via a UTM ARM64 VM over SSH
- Status: accepted
- Date: 2026-09-25
The number was assigned at merge into staging (this file was
XXXX-local-windows-verification-via-utm-vm.md until then).
Context
Windows-only code (for example cmd/vaultfold's terminal-echo handling, and
the agent daemon's named-pipe transport and its DACL-restricted, per-user
access checks) is cross-compiled and go vet-ed for windows on every push
by make crossbuild, but its tests have never run on an actual Windows
host: go test cannot execute a cross-compiled binary for a GOOS other
than the host's, and hosted CI is disabled while the core is being built
(CONTRIBUTING.md, "Verification is local (initial build)"). docs/STATUS.md
records this gap explicitly. Some behavior can only be observed on real
Windows: named-pipe DACLs refusing a different Windows user, the client
PID lookup used to authorize a caller, and go-winio's pipe listener and
dialer. A contributor or agent working on this code has had no way to run
it before opening a PR.
A UTM-hosted Windows 11 ARM64 VM is available on the development Mac, reachable over key-based SSH as an administrator, with Git for Windows and Go installable via winget. This is a real (if narrow) Windows host, usable today, without waiting for hosted CI to be re-enabled.
Decision
Add make check-windows (scripts/check-windows.sh), a local, on-demand
target that is not part of make check and not run by the pre-push hook
or by CI:
- The target host is
$VAULTFOLD_WIN_HOST, defaultvaultfold-win(an SSH config alias). The script fails fast with a clear message if the host is unreachable, before copying anything. - The current working tree (tracked files at HEAD, plus uncommitted
changes) is archived and piped over
ssh ... tar.exeinto a scratch directory on the VM. Nothing is installed or configured on the VM by the script itself; the VM's Go and Git toolchains are set up once, out of band (winget), following the pinnedGOTOOLCHAINin go.work. - For every module declared in go.work, the script runs
go build ./...,go vet ./...andgo test ./...on the VM, adding-raceonly where the installed Go's race detector supports the VM's GOARCH (see "ARM64 vs x64" below); it never assumes race support. and exits non-zero if any module fails. - A second local, non-admin Windows user (
vftest) exists on the VM for the cross-user pipe DACL tests, created once out of band with a generated password that never leaves the VM. A test harness runs a process as that user non-interactively via a Scheduled Task registered with/RU vftest /RP <password>(the password is supplied once, at registration, and Task Scheduler stores it; it is never re-entered per run). This is the mechanism by which "a different user must be refused by the pipe DACL" can actually be exercised, rather than only asserted against a synthetic SID in-process. - Documented in CONTRIBUTING.md as an on-demand check a contributor or reviewer can run before or during Windows-sensitive work; it is not a gate any PR is blocked on, and it is not one of the required checks listed in CONTRIBUTING.md's "Pull requests" section.
ARM64 vs x64
The VM is windows/arm64. This covers:
- That the code builds, vets and passes its tests on a real Windows kernel and filesystem at all (never previously exercised).
- Named-pipe DACL enforcement, the client PID lookup and go-winio's pipe code paths, which are OS-level, not architecture-level.
- Windows-specific file and terminal behavior (path separators, line endings, console mode).
It does not cover:
- windows/amd64, which is what hosted CI's
windows-latestrunner is and what most vaultfold users run. ARM64 and x64 Windows share the same Win32 API surface for the code this project has today, but a future amd64-specific issue (or an amd64-only dependency) would not be caught here. - The race detector: at the time of writing,
go test -raceis not supported on windows/arm64 (verified against the go1.27.1 toolchain pinned by go.work:go test -racefails immediately with "-race is not supported on windows/arm64").check-windows.shtherefore runs the Windows test pass without-race; race-enabled coverage still only runs on the platformsscripts/coverage.shsupports (linux/darwin amd64/arm64 hosts today). A real data race that only manifests on Windows would not be caught by either this VM ormake coverage. - Anything that needs code signing, MSI packaging or a clean-install Windows machine; the VM is a long-lived dev image, not a fresh install.
Alternatives considered
- Hosted GitHub Actions
windows-latest. This is the eventual plan (CONTRIBUTING.md's "Plan: re-enable CI... with... Windows on every PR") and is windows/amd64, which most users run and where-raceis supported. Rejected for now only because CI is deliberately disabled during the initial build;check-windows.shis a stand-in for the gap until then, not a replacement for it. When CI is re-enabled, the hostedwindows-latestjob remains the required check;make check-windowsstays as an on-demand, faster local loop and as the only way to exercise the cross-user pipe DACL scenario, which a single-user hosted runner cannot do without the same kind of second-account setup. - Cross-compile and vet only (the status quo,
make crossbuild). Rejected as sufficient on its own: it already runs on every push and catches compile and vet errors, but by construction never runs a test binary, so it cannot exercise pipe DACLs, the PID lookup, go-winio, or any other runtime behavior.
Consequences
- Windows-sensitive changes (the daemon's transport, terminal handling) can be verified against a real Windows host before a PR is opened, closing the gap docs/STATUS.md records.
- The check depends on a machine-local VM that is not reproducible in CI and not available to every contributor; it is a convenience and a stronger local signal, not a substitute for the required checks in CONTRIBUTING.md's "Pull requests" section.
-raceis silently skipped on this VM's architecture; a reviewer relying onmake check-windowsfor race coverage would be wrong to. This is called out in the script's own output, not just here.