add diagnosability for plain-Windows path

Logging additions: surface the decisions Lima makes that previously
went unmarked, so a `--debug` run on a failing host shows enough to
diagnose without source-diving.

  sshutil.IsSSHCygwin: log the toolchain detection result once per
  process at Debug level, including the full ssh.exe path and whether
  cygpath.exe was found alongside. Caches the result in a sync.Once,
  so the log fires exactly once even when many call sites consult it.

  ioutilx.WindowsSubsystemPath: when the native fallback is taken
  (cygpath unavailable), log the input -> output mapping at Debug, so
  unexpected drive-letter conversions are visible in the trace.

  downloader.decompressLocal: change "decompressing X with gzip" to
  either "with in-process gzip" or "with external <cmd>" depending on
  which path was taken. The previous message was misleading after the
  in-process gzip change because it still said "with gzip" for both.

  copytool.scp / rsync: log Debug when ControlMaster options are
  stripped on Windows, so a copy-failure trace makes the mux decision
  visible without reading the source.

  hostagent.setupMount: log the resolved sftp-server LocalPath at
  Debug, so reverse-sshfs failures surface what was actually passed.

CI: the windows-plain job now produces a tool inventory so failures
have actionable context.

  Print PATH before and after the Cygwin/MSYS2/Git-for-Windows scrub.

  Enumerate every external binary Lima might shell out to on Windows,
  classified into required (must resolve and must come from
  C:\Windows\...), forbidden (must not resolve at all -- cygpath,
  pacman), and optional (logged for context, e.g. rsync, gzip,
  qemu-img). Fail with an actionable message if a required tool is
  missing or a forbidden one is found, so the CI failure points at the
  scrub regex rather than the smoke test that follows.

  Pass --debug to every limactl invocation in the smoke test, and add
  an "if: failure()" step that dumps ha.stderr.log, ha.stdout.log,
  serial.log, lima.yaml, and ssh.config from the instance directory.

  Persist the scrubbed PATH into $GITHUB_ENV so the smoke test and
  the failure-dump step run against the same environment as the
  verification step.

Signed-off-by: Jan Dubois <jan.dubois@suse.com>

Author: jandubois

.github/workflows/test.yml

@@ -301,45 +301,135 @@ jobs:
     - name: Build limactl
       # Avoid `make` so the build does not require MSYS2 make / bash.
       run: go build -o _output\bin\limactl.exe .\cmd\limactl
-    - name: Smoke test (create / start / shell / copy / stop / delete)
+    - name: Scrub PATH and verify only native Windows toolchain is reachable
       run: |
         $ErrorActionPreference = 'Stop'
+        Write-Host "PATH before scrub:"
+        $env:PATH -split ';' | ForEach-Object { Write-Host "  $_" }
         # Scrub PATH of Cygwin/MSYS2/Git-for-Windows toolchains so that
         # limactl is forced to use native Windows binaries only. The
         # GitHub runner image has these pre-installed and on PATH by
         # default; we want to simulate a vanilla Windows host where
         # users have not installed Git for Windows or MSYS2.
-        $env:PATH = ($env:PATH -split ';' | Where-Object {
+        $scrubbed = ($env:PATH -split ';' | Where-Object {
           $_ -notmatch '\\msys(64|2)\\' -and
           $_ -notmatch '\\Git\\(usr|mingw\d+)\\bin' -and
           $_ -notmatch '\\Git\\cmd' -and
-          $_ -notmatch '\\Git\\bin'
+          $_ -notmatch '\\Git\\bin' -and
+          $_ -notmatch '\\cygwin\d*\\'
         }) -join ';'
+        # Persist the scrubbed PATH into subsequent steps so the smoke test
+        # and any post-step diagnostics see the same environment.
+        Add-Content -Path $env:GITHUB_ENV -Value "PATH=$scrubbed"
+        $env:PATH = $scrubbed
+        Write-Host ""
+        Write-Host "PATH after scrub:"
+        $env:PATH -split ';' | ForEach-Object { Write-Host "  $_" }
+        Write-Host ""
+        # Required: ssh must be the native Windows OpenSSH binary, since
+        # that is the toolchain we are exercising.
         $sshSrc = (Get-Command ssh).Source
         Write-Host "ssh resolves to: $sshSrc"
         if ($sshSrc -notlike 'C:\Windows\System32\OpenSSH\ssh.exe') {
           Write-Error "Expected native Windows OpenSSH; got $sshSrc"
           exit 1
         }
-        if (Get-Command cygpath -ErrorAction SilentlyContinue) {
-          $cyg = (Get-Command cygpath).Source
-          Write-Error "cygpath is still on PATH at $cyg; PATH scrub did not catch it"
+        # Tool inventory: print the resolved location of every external binary
+        # Lima might shell out to on Windows, so the workflow log captures the
+        # exact toolchain layout the test ran against. Tools split into:
+        #   required-native: must come from C:\Windows or be a built-in like wsl.
+        #   forbidden: must NOT resolve at all on a "plain Windows" host.
+        #   optional: may or may not be present; logged for context. Lima has
+        #             graceful fallbacks (id, rsync) or only needs them for
+        #             non-default code paths (qemu-img, decompressors).
+        $required = @('ssh','scp','ssh-keygen','sftp-server','wsl','tar')
+        $forbidden = @{
+          'cygpath' = 'cygpath comes from MSYS2/Git-for-Windows/Cygwin only'
+          'pacman'  = 'pacman comes from MSYS2 only'
+        }
+        # bash.exe is interesting but ambiguous: Windows 10/11 ship a WSL
+        # launcher named bash.exe in System32, which is fine. Git for Windows
+        # also ships a bash.exe in usr/bin. Log it but do not fail on it.
+        $optional = @('bash','sh','gzip','bzip2','xz','zstd','rsync','id','make','awk','sed','qemu-img')
+
+        Write-Host ""
+        Write-Host "=== Required tools (must resolve) ==="
+        $missingRequired = @()
+        foreach ($cmd in $required) {
+          $found = Get-Command $cmd -ErrorAction SilentlyContinue
+          if ($found) { Write-Host ("  {0,-15} -> {1}" -f $cmd, $found.Source) }
+          else { Write-Host ("  {0,-15} -> NOT FOUND" -f $cmd); $missingRequired += $cmd }
+        }
+        Write-Host ""
+        Write-Host "=== Forbidden tools (must not resolve on plain Windows) ==="
+        $foundForbidden = @()
+        foreach ($cmd in $forbidden.Keys) {
+          $found = Get-Command $cmd -ErrorAction SilentlyContinue
+          if ($found) {
+            Write-Host ("  {0,-15} -> {1}    (FORBIDDEN: {2})" -f $cmd, $found.Source, $forbidden[$cmd])
+            $foundForbidden += $cmd
+          } else {
+            Write-Host ("  {0,-15} -> not found (good)" -f $cmd)
+          }
+        }
+        Write-Host ""
+        Write-Host "=== Optional tools (logged for context, not asserted) ==="
+        foreach ($cmd in $optional) {
+          $found = Get-Command $cmd -ErrorAction SilentlyContinue
+          if ($found) { Write-Host ("  {0,-15} -> {1}" -f $cmd, $found.Source) }
+          else { Write-Host ("  {0,-15} -> not found" -f $cmd) }
+        }
+        Write-Host ""
+        if ($missingRequired.Count -gt 0) {
+          Write-Error ("Required tools not on PATH: " + ($missingRequired -join ', '))
+          exit 1
+        }
+        if ($foundForbidden.Count -gt 0) {
+          Write-Error ("Forbidden tools still on PATH: " + ($foundForbidden -join ', ') + ". Update the scrub regex in this step.")
           exit 1
         }
-        $env:LIMA_HOME = "$env:TEMP\lima-plain"
+    - name: Smoke test (create / start / shell / copy / stop / delete)
+      env:
+        # Surface decisions in path-translation, ssh-args, mux-stripping, etc.
+        # The Debug-level logging is only useful when this job fails, but the
+        # success-case noise is small and CI logs are kept for a long time.
+        LIMA_HOME: ${{ runner.temp }}\lima-plain
+      run: |
+        $ErrorActionPreference = 'Stop'
         if (Test-Path $env:LIMA_HOME) { Remove-Item $env:LIMA_HOME -Recurse -Force }
         New-Item -ItemType Directory -Path $env:LIMA_HOME | Out-Null
         # Use the same WSL2 rootfs template that windows-wsl2 uses, so this
         # job exercises a real boot rather than the smallest synthetic config.
-        & .\_output\bin\limactl.exe create --tty=false --name=plain `
+        & .\_output\bin\limactl.exe --debug create --tty=false --name=plain `
           .\templates\experimental\wsl2.yaml
-        & .\_output\bin\limactl.exe start plain
-        & .\_output\bin\limactl.exe shell --tty=false plain -- uname -srm
+        & .\_output\bin\limactl.exe --debug start plain
+        & .\_output\bin\limactl.exe --debug shell --tty=false plain -- uname -srm
         'roundtrip' | Out-File -Encoding ascii "$env:LIMA_HOME\rt.txt"
-        & .\_output\bin\limactl.exe copy "$env:LIMA_HOME\rt.txt" plain:/tmp/rt.txt
-        & .\_output\bin\limactl.exe shell --tty=false plain -- cat /tmp/rt.txt
-        & .\_output\bin\limactl.exe stop plain
-        & .\_output\bin\limactl.exe delete --force plain
+        & .\_output\bin\limactl.exe --debug copy "$env:LIMA_HOME\rt.txt" plain:/tmp/rt.txt
+        & .\_output\bin\limactl.exe --debug shell --tty=false plain -- cat /tmp/rt.txt
+        & .\_output\bin\limactl.exe --debug stop plain
+        & .\_output\bin\limactl.exe --debug delete --force plain
+    - name: Dump Lima logs on failure
+      if: failure()
+      env:
+        LIMA_HOME: ${{ runner.temp }}\lima-plain
+      run: |
+        # Hostagent logs are the most useful artefact when start fails.
+        # Print everything Lima wrote about the instance so failures show up
+        # in the workflow run instead of being lost when the runner is gone.
+        $instDir = "$env:LIMA_HOME\plain"
+        if (-not (Test-Path $instDir)) {
+          Write-Host "No instance directory at $instDir, nothing to dump."
+          exit 0
+        }
+        Get-ChildItem $instDir | Format-Table Name, Length, LastWriteTime
+        foreach ($name in 'ha.stdout.log','ha.stderr.log','serial.log','lima.yaml','ssh.config') {
+          $p = Join-Path $instDir $name
+          if (Test-Path $p) {
+            Write-Host ("===== {0} =====" -f $p)
+            Get-Content $p
+          }
+        }
 
   qemu:
     name: "Integration tests (QEMU, macOS host)"

pkg/copytool/rsync.go

@@ -133,6 +133,7 @@ func (t *rsyncTool) Command(ctx context.Context, paths []string, opts *Options)
 					// so rsync's ssh transport does not try to use a
 					// ControlMaster socket that is unavailable or unreliable
 					// on Windows.
+					logrus.Debug("rsync: stripping ControlMaster/ControlPath/ControlPersist (Windows)")
 					sshOpts = sshutil.SSHOptsRemovingControlPath(sshOpts)
 				}
 

pkg/copytool/scp.go

@@ -11,6 +11,7 @@ import (
 	"runtime"
 
 	"github.com/coreos/go-semver/semver"
+	"github.com/sirupsen/logrus"
 
 	"github.com/lima-vm/lima/v2/pkg/limatype"
 	"github.com/lima-vm/lima/v2/pkg/sshutil"
@@ -128,6 +129,7 @@ func (t *scpTool) Command(ctx context.Context, paths []string, opts *Options) (*
 		// socket), and Cygwin-based ssh has known reliability issues with
 		// sftp over a mux socket. See also the equivalent handling in
 		// hostagent and limactl shell.
+		logrus.Debug("scp: stripping ControlMaster/ControlPath/ControlPersist (Windows)")
 		sshOpts = sshutil.SSHOptsRemovingControlPath(sshOpts)
 	}
 	sshArgs := sshutil.SSHArgsFromOpts(sshOpts)

pkg/downloader/downloader.go

@@ -526,7 +526,11 @@ func decompressorByMagic(file string) string {
 }
 
 func decompressLocal(ctx context.Context, decompressCmd, dst, src, ext, description string) error {
-	logrus.Infof("decompressing %s with %v", ext, decompressCmd)
+	if decompressCmd == "gzip" {
+		logrus.Infof("decompressing %s with in-process gzip", ext)
+	} else {
+		logrus.Infof("decompressing %s with external %q", ext, decompressCmd)
+	}
 
 	st, err := os.Stat(src)
 	if err != nil {

pkg/hostagent/mount.go

@@ -66,6 +66,7 @@ func (a *HostAgent) setupMount(ctx context.Context, m limatype.Mount) (*mount, e
 		if err != nil {
 			return nil, err
 		}
+		logrus.Debugf("reverse-sshfs: host path %q resolved to %q for sftp-server", m.Location, resolvedLocation)
 	}
 
 	sshAddress, sshPort := a.sshAddressPort()

pkg/ioutilx/ioutilx.go

@@ -64,7 +64,9 @@ func WindowsSubsystemPath(ctx context.Context, orig string) (string, error) {
 		logrus.WithError(err).Debugf("cygpath unavailable for %q, attempting native conversion", orig)
 	}
 	if vol := filepath.VolumeName(orig); len(vol) == 2 && vol[1] == ':' {
-		return "/" + strings.ToLower(vol[:1]) + filepath.ToSlash(orig[2:]), nil
+		out := "/" + strings.ToLower(vol[:1]) + filepath.ToSlash(orig[2:])
+		logrus.Debugf("native cygpath fallback: %q -> %q", orig, out)
+		return out, nil
 	}
 	return "", fmt.Errorf("cannot convert %q to a Cygwin-style path: cygpath unavailable and input is not a drive-letter path", orig)
 }

pkg/sshutil/sshutil.go

@@ -69,25 +69,44 @@ func NewSSHExe() (SSHExe, error) {
 	return sshExe, nil
 }
 
+var cygwinDetect struct {
+	sync.Once
+	isCygwin bool
+}
+
 // IsSSHCygwin reports whether sshExe is a Cygwin-based build of OpenSSH
 // (e.g. Git for Windows, MSYS2, or Cygwin itself), as opposed to native
 // Windows OpenSSH. The detection is based on whether cygpath.exe lives in
 // the same directory as ssh.exe, which is the layout used by Git for Windows
 // and MSYS2. Always returns false on non-Windows.
+//
+// The first call's result is cached and logged at Debug level. Subsequent
+// calls return the same answer regardless of the sshExe passed; in practice
+// limactl uses a single ssh binary throughout a process, so this is fine
+// and avoids spamming the log when toolchain-aware code paths run repeatedly.
 func IsSSHCygwin(sshExe SSHExe) bool {
 	if runtime.GOOS != "windows" || sshExe.Exe == "" {
 		return false
 	}
-	path := sshExe.Exe
-	if !filepath.IsAbs(path) {
-		resolved, err := exec.LookPath(path)
-		if err != nil {
-			return false
+	cygwinDetect.Do(func() {
+		path := sshExe.Exe
+		if !filepath.IsAbs(path) {
+			resolved, err := exec.LookPath(path)
+			if err != nil {
+				logrus.WithError(err).Debugf("IsSSHCygwin: cannot resolve %q via PATH; assuming native", sshExe.Exe)
+				return
+			}
+			path = resolved
 		}
-		path = resolved
-	}
-	_, err := os.Stat(filepath.Join(filepath.Dir(path), "cygpath.exe"))
-	return err == nil
+		cygpathPath := filepath.Join(filepath.Dir(path), "cygpath.exe")
+		if _, err := os.Stat(cygpathPath); err == nil {
+			cygwinDetect.isCygwin = true
+			logrus.Debugf("ssh at %q detected as Cygwin-based (found %q alongside)", path, cygpathPath)
+		} else {
+			logrus.Debugf("ssh at %q detected as native Windows OpenSSH (no cygpath.exe alongside)", path)
+		}
+	})
+	return cygwinDetect.isCygwin
 }
 
 // PathForSSH converts orig to the path form expected by the ssh family of