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.