Skip to content

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, default vaultfold-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.exe into 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 pinned GOTOOLCHAIN in go.work.
  • For every module declared in go.work, the script runs go build ./..., go vet ./... and go test ./... on the VM, adding -race only 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-latest runner 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 -race is not supported on windows/arm64 (verified against the go1.27.1 toolchain pinned by go.work: go test -race fails immediately with "-race is not supported on windows/arm64"). check-windows.sh therefore runs the Windows test pass without -race; race-enabled coverage still only runs on the platforms scripts/coverage.sh supports (linux/darwin amd64/arm64 hosts today). A real data race that only manifests on Windows would not be caught by either this VM or make 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 -race is supported. Rejected for now only because CI is deliberately disabled during the initial build; check-windows.sh is a stand-in for the gap until then, not a replacement for it. When CI is re-enabled, the hosted windows-latest job remains the required check; make check-windows stays 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.
  • -race is silently skipped on this VM's architecture; a reviewer relying on make check-windows for race coverage would be wrong to. This is called out in the script's own output, not just here.