Fix Windows runtime bootstrap/start-vm edge cases

Author: mjenkinsaktion

docs/RUNBOOKS.md

@@ -1,6 +1,6 @@
 ---
 owner: Mike Jenkins
-last_verified: 2026-02-18
+last_verified: 2026-02-20
 ---
 
 # Runbooks
@@ -74,6 +74,25 @@ Backend spec:
 - Validate project path argument handling with spaces.
 - Validate selected runtime mode is reflected in diagnostics output.
 
+## Local Preflight (Before Windows VM Smoke)
+Use this deterministic preflight to validate launcher wiring before VM testing. Windows VM smoke remains `scripts/runtime/windows/smoke-check.cmd`.
+
+1. Syntax + onboarding checks:
+```bash
+node --check scripts/pcoder.cjs
+scripts/pcoder setup --init --show
+```
+2. Doctor with stubbed runners:
+```bash
+PCODER_CODEX_CMD=node PCODER_CLAUDE_CMD=node scripts/pcoder doctor
+```
+3. API-mode host-native launch checks with stubbed runners:
+```bash
+scripts/pcoder setup --codex-auth api --claude-auth api --windows-mode host-native --show
+OPENAI_API_KEY=pcoder-preflight PCODER_CODEX_CMD=node scripts/pcoder run codex --mode host-native -- --version
+ANTHROPIC_AUTH_TOKEN=pcoder-preflight PCODER_CLAUDE_CMD=node scripts/pcoder run claude --mode host-native -- --version
+```
+
 ## Incident Recovery
 - If runtime corruption is detected, clear `runtime/` and rerun bootstrap.
 - If profile corruption is detected, restore `profiles/profiles.json` from version control.

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

@@ -1,6 +1,6 @@
 ---
 owner: Mike Jenkins
-last_verified: 2026-02-18
+last_verified: 2026-02-20
 ---
 
 # EP-001 - Portable Coder Foundation and Multi-Provider MVP
@@ -39,7 +39,10 @@ Initial user target providers/tools:
 - [x] (2026-02-18) Implement onboarding/settings and dual auth mode support (`pcoder setup`, `pcoder auth`, persistent portable state)
 - [x] (2026-02-18) Add Windows smoke checklist scripts for VM boot/SSH/guest tool validation
 - [x] (2026-02-18) Add Windows runtime bootstrap installer (`bootstrap-runtime`) to fetch QEMU/image and generate SSH keys
-- [ ] (2026-02-18) Validate Codex + Claude launches in one portable layout
+- [x] (2026-02-20) Validate Codex + Claude launches in one portable layout
+- [x] (2026-02-20) Fix Windows bootstrap `ssh-keygen` argument handling for empty-passphrase key generation
+- [x] (2026-02-20) Fix Windows VM start cloud-init port selection to fallback when default range is exhausted
+- [x] (2026-02-20) Add Windows helper script to patch legacy `start-vm.ps1` cloud-init port fallback on existing local clones
 - [ ] (2026-02-18) Document setup/runbook and close out EP-001
 
 ## Context and Orientation
@@ -114,6 +117,10 @@ Acceptance criteria for EP-001:
 - 2026-02-18: MVP project handoff uses SCP sync in/out of VM instead of shared-folder mounts to reduce host dependency assumptions.
 - 2026-02-18: OAuth + API dual-mode support required explicit onboarding state and per-tool auth-mode persistence.
 - 2026-02-18: Profile resolution needed per-tool default fallback to avoid cross-provider env validation errors in API mode.
+- 2026-02-20: Host-native and stubbed CI-equivalent validation passed on Linux host for Codex + Claude launch flows.
+- 2026-02-20: Windows VM smoke validation remains target-specific and is still tracked separately from Linux-host checks.
+- 2026-02-20: PowerShell `Start-Process -ArgumentList` rejected empty elements, so `ssh-keygen -N` required explicit empty-string handling.
+- 2026-02-20: Some Windows hosts had no free ports in `38080-38120`; cloud-init server startup now needs fallback port allocation.
 
 ## Decision Log
 - 2026-02-18: Adopt harness-first planning model before implementation.

scripts/runtime/windows/apply-start-vm-port-fix.cmd

@@ -0,0 +1,14 @@
+@echo off
+setlocal EnableExtensions
+
+set "SCRIPT_DIR=%~dp0"
+set "PATCH_PS1=%SCRIPT_DIR%apply-start-vm-port-fix.ps1"
+
+if not exist "%PATCH_PS1%" (
+  echo Error: missing patch script: %PATCH_PS1%
+  exit /b 1
+)
+
+powershell -NoProfile -ExecutionPolicy Bypass -File "%PATCH_PS1%"
+exit /b %errorlevel%
+

scripts/runtime/windows/apply-start-vm-port-fix.ps1

@@ -0,0 +1,43 @@
+param()
+
+$ErrorActionPreference = 'Stop'
+
+$startVmPath = Join-Path $PSScriptRoot 'start-vm.ps1'
+if (-not (Test-Path $startVmPath)) {
+  throw "Missing target script: $startVmPath"
+}
+
+$text = Get-Content -Path $startVmPath -Raw -Encoding UTF8
+$marker = 'Preferred cloud-init port range 38080-38120 unavailable; using ephemeral port $cloudInitPort.'
+
+if ($text.Contains($marker)) {
+  Write-Host "Patch already present in $startVmPath"
+  exit 0
+}
+
+$oldLine = '$cloudInitPort = Get-FreeTcpPort -StartPort 38080 -EndPort 38120'
+$replacement = @'
+$cloudInitPort = 0
+try {
+  $cloudInitPort = Get-FreeTcpPort -StartPort 38080 -EndPort 38120
+} catch {
+  $listener = [System.Net.Sockets.TcpListener]::new([System.Net.IPAddress]::Loopback, 0)
+  try {
+    $listener.Start()
+    $cloudInitPort = ([System.Net.IPEndPoint]$listener.LocalEndpoint).Port
+  } finally {
+    try { $listener.Stop() } catch {}
+  }
+  Write-Host "Preferred cloud-init port range 38080-38120 unavailable; using ephemeral port $cloudInitPort."
+}
+'@
+
+if (-not $text.Contains($oldLine)) {
+  throw "Could not find expected line to patch in $startVmPath"
+}
+
+$updated = $text.Replace($oldLine, $replacement)
+Set-Content -Path $startVmPath -Value $updated -Encoding UTF8
+
+Write-Host "Applied cloud-init port fallback patch to $startVmPath"
+

scripts/runtime/windows/bootstrap-runtime.ps1

@@ -168,7 +168,8 @@ if (-not (Test-Path $sshPrivate) -or -not (Test-Path $sshPublic)) {
     throw "Missing ssh-keygen in PATH. Install OpenSSH client feature or set up runtime/linux/ssh/id_ed25519 manually."
   }
 
-  $genArgs = @('-t', 'ed25519', '-N', '', '-f', $sshPrivate, '-C', 'portable-coder')
+  # Start-Process rejects empty ArgumentList elements, so pass -N "" in one string.
+  $genArgs = "-t ed25519 -N `"`" -f `"$sshPrivate`" -C portable-coder"
   $keyProc = Start-Process -FilePath $sshKeygen -ArgumentList $genArgs -PassThru -Wait -NoNewWindow
   if ($keyProc.ExitCode -ne 0) {
     throw "ssh-keygen failed with exit code $($keyProc.ExitCode)"

scripts/runtime/windows/start-vm.ps1

@@ -51,6 +51,17 @@ function Get-FreeTcpPort {
   throw "No free TCP port found in range $StartPort-$EndPort"
 }
 
+function Get-EphemeralTcpPort {
+  $listener = [System.Net.Sockets.TcpListener]::new([System.Net.IPAddress]::Loopback, 0)
+  try {
+    $listener.Start()
+    $endpoint = [System.Net.IPEndPoint]$listener.LocalEndpoint
+    return $endpoint.Port
+  } finally {
+    try { $listener.Stop() } catch {}
+  }
+}
+
 function Stop-CloudInitServer {
   if (Test-Path $cloudInitPidFile) {
     $raw = Get-Content $cloudInitPidFile -ErrorAction SilentlyContinue | Select-Object -First 1
@@ -188,7 +199,13 @@ if ($requestedPortRaw) {
   $sshPort = Get-FreeTcpPort -StartPort 2222 -EndPort 2299
 }
 
-$cloudInitPort = Get-FreeTcpPort -StartPort 38080 -EndPort 38120
+$cloudInitPort = 0
+try {
+  $cloudInitPort = Get-FreeTcpPort -StartPort 38080 -EndPort 38120
+} catch {
+  $cloudInitPort = Get-EphemeralTcpPort
+  Write-Host "Preferred cloud-init port range 38080-38120 unavailable; using ephemeral port $cloudInitPort."
+}
 $guestUser = if ($env:PCODER_VM_USER) { $env:PCODER_VM_USER } else { 'portable' }
 $pubKeyValue = (Get-Content $sshPublicKey -Raw).Trim()
 Write-CloudInitSeed -PublicKey $pubKeyValue -UserName $guestUser