Add Windows guest control and ConPTY

[sjmiller609]

summary

• cross-compile the guest agent as a Windows LocalSystem service
• listen through the virtio-win VioSock provider while retaining the existing gRPC protocol
• add SYSTEM and active-desktop execution sessions
• add ConPTY terminal allocation and resize handling
• support Windows file copy, stat, readiness, and graceful shutdown
• bind command trees to kill-on-close Job Objects and terminate them synchronously
• promote Windows instances to Running when guest-agent readiness is proven
• move guest-service protocol and lifecycle rationale into lib/system/README.md

targeted tests

• guest, guest-agent, and Windows readiness unit tests
• Windows guest-agent cross-compilation

Additional terminal signal-parity work is intentionally deferred. Long-running KVM and full CI suites were not run for this review pass.

---

Note

High Risk
Touches guest command execution, Windows token impersonation for desktop sessions, vsock transport, and process-tree kill semantics. Bugs here can leak processes, run commands as the interactive user, or break instance readiness.

Overview
Windows guests now run the same vsock gRPC guest protocol as Linux. The agent is cross-compiled as hypeman-guest-agent.exe, installed as the HypemanGuestAgent LocalSystem service, and listens through virtio-win VioSock.

Exec gains an explicit session (system vs desktop). Desktop mode impersonates the active interactive user so UI processes can appear on that desktop. Interactive sessions use ConPTY with resize; non-interactive commands use redirected handles. Windows process trees start suspended, join a kill-on-close Job Object, then resume so timeouts and RPC close terminate descendants.

Windows instances no longer skip the guest agent. Readiness probes use cmd.exe, and a successful agent probe can mark the instance Running. File copy/stat skip Unix ownership; network reconfigure is unimplemented; shutdown uses shutdown.exe. CI builds the Windows agent and runs a QEMU guest-control integration test against /ci/windows/image-agent.qcow2.

^{Reviewed by Cursor Bugbot for commit 0886125. Bugbot is set up for automated code reviews on this repo. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	github.com/​aymanbagabas/​go-pty@​v0.2.2

View full report

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0886125. Configure here.}

[cursor]

TTY skips session validation

Medium Severity

Unix TTY exec never calls configureExecCommand, so EXEC_SESSION_DESKTOP and unknown sessions are not rejected on the PTY path. Non-TTY Unix correctly validates via configureExecCommand. A desktop or invalid session with tty=true against a Linux guest therefore runs as SYSTEM instead of failing.

Additional Locations (1)

• lib/system/guest_agent/exec_no_tty_unix.go#L20-L26

 

^{Reviewed by Cursor Bugbot for commit 0886125. Configure here.}

[cursor]

Desktop missing interactive station

High Severity

Desktop sessions set a user Token and CREATE_SUSPENDED but never set SysProcAttr.Desktop to winsta0\default. From a Session-0 LocalSystem service, that leaves processes on the service window station, so UI processes do not appear on the active interactive desktop despite the documented DESKTOP session behavior.

Additional Locations (1)

• lib/system/guest_agent/exec_tty_windows.go#L47-L51

 

^{Reviewed by Cursor Bugbot for commit 0886125. Configure here.}