W — Windows support (stretch): port surface and prerequisites

[yashranaway]

Tracking issue for the Windows port. Not required for "done" — owner decision, 2026-08-04: later / best-effort. See architecture decisions §6 and ROADMAP Phase W.

Blocked on

Phase 2 — the HostCore + BrowserEngine extraction (#21) and typed errors (#22). Without that seam, Windows means a third hand-written copy of every command. Do not start before it lands.

Shape of the work

The WKWebView host is never ported. Windows runs the Chromium engine only.

• Transport — named pipes with a SID-based peer check, replacing AF_UNIX + getpeereid/SO_PEERCRED. Windows has AF_UNIX, but no filesystem mode bits and no SO_PEERCRED, and the stale-socket probe does not map.
• Runtime directory — %LOCALAPPDATA% with ACLs instead of /tmp/headless-<uid> at 0700.
• Process spawn — CreateProcess + CreatePipe + SetHandleInformation. Chromium on Windows takes --remote-debugging-pipe handles via STARTUPINFO, not fds 3/4, so spawnChromium needs a Win32 rewrite.
• CDP I/O — overlapped I/O or WaitForMultipleObjects instead of poll().
• Artifact store — ACLs instead of POSIX modes; CREATE_NEW for the O_EXCL guarantee. Every "0600 in a 0700 dir" claim is POSIX-only today.
• Signals — console control handler instead of SIGTERM/SIGINT dispatch sources.
• Browser discovery — registry + Program Files, Edge as a candidate, ; PATH splitting.
• FFmpeg discovery — .exe resolution under the same allow-list-not-PATH rule.
• Elevation check — replace the getuid() != 0 root refusal with an elevated-token check.
• Scripts — the build/test/E2E suite is POSIX sh; needs re-authoring.
• Distribution — winget manifest (Phase 3 patterns apply).

Already portable

Protocol.swift, CLI.swift, AgentRuntime.swift (the injected JS is engine-agnostic), Diagnostics.swift, Flows.swift, CaptureFormats.swift, ScreenshotSeries.swift, MCP/main.swift, and Recording.swift modulo executable discovery.

Interim answer

Docker Desktop / WSL2 with the published image (#41). That is the documented Windows path until this ships.

Exit test

The Linux E2E scenario passes on a Windows runner against the Chromium engine, and winget install headless works.

[yashranaway]

Spike result (2026-08-22, per PLAN.md step 1 and ADR §6 update): native Windows via Swift is not viable today.

Tested on real windows-latest runners with Swift 6.3.3:

• No Linux→Windows cross-compilation (Swift SDKs don't target Windows)
• winget toolchain is broken out of the box: runtime DLLs split across Toolchains\ and Runtimes\ trees; swift.exe exits STATUS_DLL_NOT_FOUND until manually merged
• Even after repair, swiftc hello.swift fails: "unable to load standard library for target x86_64-unknown-windows-msvc" — SPM and direct compilation both fail

Consequence: the Chromium engine adapter can't be written in Swift with this toolchain. WSL2/Docker is now documented in README as the supported Windows path. Native support stays behind a revisit trigger: either a materially better Swift-for-Windows toolchain, or a scoped Rust port of the shared core (new ADR required first).

Evidence: .github/workflows/windows-spike.yml on branch spike/windows-core, run logs preserved there.