Add TCG override path for Windows VM smoke recovery

Author: mjenkinsaktion

docs/RUNBOOKS.md

@@ -53,6 +53,7 @@ Backend spec:
 - Start VM implementation: `scripts/runtime/windows/start-vm.ps1`
 - Stop VM: `scripts/runtime/windows/stop-vm.cmd`
 - Smoke checklist: `scripts/runtime/windows/smoke-check.cmd`
+- Smoke checklist (force TCG): `scripts/runtime/windows/smoke-check-tcg.cmd`
 
 ## Linux-Portable Run Flow
 1. `pcoder` starts/ensures VM via `start-vm.cmd`.
@@ -61,6 +62,11 @@ Backend spec:
 4. Tool command runs over SSH in guest project directory.
 5. Project is copied back to host after run (unless `--no-sync-back`).
 
+Acceleration override (Windows troubleshooting):
+- `PCODER_VM_ACCEL_MODE=auto` (default): try WHPX then fallback to TCG if launch fails.
+- `PCODER_VM_ACCEL_MODE=whpx`: force WHPX only.
+- `PCODER_VM_ACCEL_MODE=tcg`: force software virtualization when WHPX boot/SSH is unreliable.
+
 ## Auth Operations
 - Show auth modes and portable auth paths: `pcoder auth status`
 - Login with OAuth in current default mode: `pcoder auth login codex`, `pcoder auth login claude`

docs/exec-plans/active/EP-001-portable-coder-foundation-and-multi-provider-mvp.md

@@ -48,6 +48,8 @@ Initial user target providers/tools:
 - [x] (2026-02-20) Fix Windows smoke SSH probe command invocation so readiness check validates `echo vm-ready` output correctly
 - [x] (2026-02-20) Update Windows smoke SSH probe to pass remote commands directly (avoids PowerShell stdin encoding edge cases)
 - [x] (2026-02-20) Normalize Windows PowerShell native `ssh` stderr handling so host-key warnings do not abort readiness probes
+- [x] (2026-02-20) Add Windows VM acceleration override (`PCODER_VM_ACCEL_MODE`) to force TCG when WHPX guests fail to reach SSH readiness
+- [x] (2026-02-20) Add `smoke-check-tcg.cmd` helper for one-command Windows smoke validation in forced software mode
 - [ ] (2026-02-18) Document setup/runbook and close out EP-001
 
 ## Context and Orientation
@@ -131,6 +133,7 @@ Acceptance criteria for EP-001:
 - 2026-02-20: Passing `ssh ... bash -lc <script>` as split args can drop expected output semantics; piping script content to `bash -s` is safer for deterministic probing.
 - 2026-02-20: Piping probe scripts into native `ssh` from Windows PowerShell can hit stdin encoding edge cases; direct remote command args are more reliable.
 - 2026-02-20: In Windows PowerShell, native stderr can surface as terminating `ErrorRecord` when `$ErrorActionPreference='Stop'`, so probe wrappers must normalize stderr explicitly.
+- 2026-02-20: Some hosts can launch QEMU with WHPX but still fail guest SSH readiness; explicit TCG override is needed for deterministic recovery.
 
 ## Decision Log
 - 2026-02-18: Adopt harness-first planning model before implementation.

scripts/runtime/windows/smoke-check-tcg.cmd

@@ -0,0 +1,9 @@
+@echo off
+setlocal EnableExtensions
+
+set "PCODER_VM_ACCEL_MODE=tcg"
+set "SCRIPT_DIR=%~dp0"
+
+call "%SCRIPT_DIR%smoke-check.cmd" %*
+exit /b %errorlevel%
+

scripts/runtime/windows/smoke-check.ps1

@@ -232,7 +232,11 @@ try {
       $lastDetail = '(no ssh output)'
     }
     $lastDetail = $lastDetail -replace '\r?\n', ' '
-    throw "Timed out waiting for VM SSH readiness after ${SshReadyTimeoutSeconds}s. Last output: $lastDetail"
+    $hint = ''
+    if ($mode -eq 'accelerated-whpx') {
+      $hint = " Hint: retry with `$env:PCODER_VM_ACCEL_MODE='tcg' to force software virtualization."
+    }
+    throw "Timed out waiting for VM SSH readiness after ${SshReadyTimeoutSeconds}s. Last output: $lastDetail$hint"
   }
 
   if (-not $SkipToolChecks) {

scripts/runtime/windows/start-vm.ps1

@@ -191,6 +191,11 @@ if (Test-Path $vmPid) {
 
 Stop-CloudInitServer
 
+$requestedAccelMode = if ($env:PCODER_VM_ACCEL_MODE) { "$($env:PCODER_VM_ACCEL_MODE)".ToLowerInvariant() } else { 'auto' }
+if ($requestedAccelMode -ne 'auto' -and $requestedAccelMode -ne 'whpx' -and $requestedAccelMode -ne 'tcg') {
+  throw "Invalid PCODER_VM_ACCEL_MODE '$requestedAccelMode'. Expected one of: auto, whpx, tcg."
+}
+
 $requestedPortRaw = $env:PCODER_VM_SSH_PORT
 $sshPort = 0
 if ($requestedPortRaw) {
@@ -220,6 +225,32 @@ $baseArgs = @(
   '-smbios', "type=1,serial=ds=nocloud-net;s=http://10.0.2.2:$cloudInitPort/"
 )
 
+if ($requestedAccelMode -eq 'whpx') {
+  $forcedWhpx = Start-QemuAttempt -Mode 'accelerated-whpx' -AccelerationArgs @('-accel', 'whpx') -BaseArgs $baseArgs -QemuBinary $qemuExe -LogPath $vmLog
+  if ($forcedWhpx) {
+    $forcedWhpx.Id | Out-File -Encoding ascii -FilePath $vmPid
+    'accelerated-whpx' | Out-File -Encoding ascii -FilePath $vmMode
+    $sshPort | Out-File -Encoding ascii -FilePath $sshPortFile
+    Write-Host "VM started in forced accelerated mode (whpx). PID: $($forcedWhpx.Id). SSH port: $sshPort"
+    exit 0
+  }
+  Stop-CloudInitServer
+  throw "Failed to start VM in forced whpx mode. Check log: $vmLog"
+}
+
+if ($requestedAccelMode -eq 'tcg') {
+  $forcedTcg = Start-QemuAttempt -Mode 'portable-forced-tcg' -AccelerationArgs @('-accel', 'tcg') -BaseArgs $baseArgs -QemuBinary $qemuExe -LogPath $vmLog
+  if ($forcedTcg) {
+    $forcedTcg.Id | Out-File -Encoding ascii -FilePath $vmPid
+    'portable-fallback-tcg' | Out-File -Encoding ascii -FilePath $vmMode
+    $sshPort | Out-File -Encoding ascii -FilePath $sshPortFile
+    Write-Host "VM started in forced portable mode (tcg). PID: $($forcedTcg.Id). SSH port: $sshPort"
+    exit 0
+  }
+  Stop-CloudInitServer
+  throw "Failed to start VM in forced tcg mode. Check log: $vmLog"
+}
+
 $accelerated = Start-QemuAttempt -Mode 'accelerated-whpx' -AccelerationArgs @('-accel', 'whpx') -BaseArgs $baseArgs -QemuBinary $qemuExe -LogPath $vmLog
 if ($accelerated) {
   $accelerated.Id | Out-File -Encoding ascii -FilePath $vmPid