fix: reject unsupported odd macOS CPU counts

Author: czmDeRepository

cmd/vm/clone.go

@@ -28,6 +28,13 @@ func (h *Handler) Clone(cmd *cobra.Command, args []string) error {
 	if err = requireCNIVNCPassword(netMode == netCNI, vnc, vncPass); err != nil {
 		return err
 	}
+	cpus := srcRec.CPUs
+	if cmd.Flags().Changed("cpus") {
+		cpus, _ = cmd.Flags().GetInt("cpus")
+	}
+	if err = validateMacOSCPUs(cpus); err != nil {
+		return err
+	}
 	// SRC's disk names are reserved: extra --data-disk specs must not collide and the combined count still honors the AHCI cap
 	reserved := make([]string, len(srcRec.DataDisks))
 	for i, p := range srcRec.DataDisks {
@@ -53,13 +60,10 @@ func (h *Handler) Clone(cmd *cobra.Command, args []string) error {
 	}
 	r := &record{
 		Name: name, Image: srcRec.Image, ImageDigest: digest, Disk: overlay,
-		OVMFCode: srcRec.OVMFCode, OVMFVars: ovmfVars, CPUs: srcRec.CPUs, Memory: srcRec.Memory,
+		OVMFCode: srcRec.OVMFCode, OVMFVars: ovmfVars, CPUs: cpus, Memory: srcRec.Memory,
 		DataDisks: append(copied, newDisks...),
 		VMID:      utils.GenerateID(), Created: time.Now().Format(time.RFC3339),
 	}
-	if cmd.Flags().Changed("cpus") {
-		r.CPUs, _ = cmd.Flags().GetInt("cpus")
-	}
 	if cmd.Flags().Changed("memory") {
 		r.Memory, _ = cmd.Flags().GetString("memory")
 	}

cmd/vm/handler_test.go

@@ -2,11 +2,34 @@ package vm
 
 import (
 	"slices"
+	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 )
 
+func TestValidateMacOSCPUs(t *testing.T) {
+	for _, tt := range []struct {
+		cpus    int
+		wantErr bool
+	}{
+		{cpus: -2, wantErr: true},
+		{cpus: 0, wantErr: true},
+		{cpus: 1, wantErr: true},
+		{cpus: 2},
+		{cpus: 3, wantErr: true},
+		{cpus: 4},
+	} {
+		err := validateMacOSCPUs(tt.cpus)
+		if (err != nil) != tt.wantErr {
+			t.Fatalf("validateMacOSCPUs(%d) error = %v, wantErr %v", tt.cpus, err, tt.wantErr)
+		}
+		if err != nil && !strings.Contains(err.Error(), "positive even number") {
+			t.Fatalf("validateMacOSCPUs(%d) error = %v", tt.cpus, err)
+		}
+	}
+}
+
 func TestCloneOpenCoreBase(t *testing.T) {
 	tests := []struct {
 		name string

cmd/vm/lifecycle.go

@@ -127,8 +127,8 @@ func (h *Handler) create(cmd *cobra.Command, image string) (*record, error) {
 		return nil, err
 	}
 	cpus, _ := cmd.Flags().GetInt("cpus")
-	if cpus < 1 {
-		return nil, fmt.Errorf("--cpus must be at least 1, got %d", cpus)
+	if err = validateMacOSCPUs(cpus); err != nil {
+		return nil, err
 	}
 	vnc, _ := cmd.Flags().GetInt("vnc")
 	vncPass, _ := cmd.Flags().GetString("vnc-password")
@@ -168,6 +168,13 @@ func (h *Handler) create(cmd *cobra.Command, image string) (*record, error) {
 	return r, saveRec(dir, r)
 }
 
+func validateMacOSCPUs(cpus int) error {
+	if cpus < 1 || cpus%2 != 0 {
+		return fmt.Errorf("--cpus must be a positive even number, got %d", cpus)
+	}
+	return nil
+}
+
 func (h *Handler) launch(cmd *cobra.Command, dir string, r *record) error {
 	ctx := cliutil.CommandContext(cmd)
 	logger := log.WithFunc("cmd.vm.launch")

docs/vm.md

@@ -12,8 +12,8 @@ Every VM boots the same way on Intel and AMD:
   baked into the macOS qcow2 — the same image boots under a different loader on Intel vs AMD.
 - **CPU:** `Skylake-Client` spoofing `GenuineIntel` with `-hle,-rtm` (TSX off), `+invtsc`, and
   `vmware-cpuid-freq=on`. The TSC flags are load-bearing: without them macOS self-calibrates the TSC
-  and spins pathologically under nested KVM on first boot. QEMU receives an explicit one-thread-per-core
-  topology so odd vCPU counts do not get inferred as unsupported multi-threaded cores.
+  and spins pathologically under nested KVM on first boot. `--cpus` must be a positive even number;
+  create/run/clone reject odd counts before VM state is created because this macOS stack does not boot them.
 - **OpenCore picker:** the shipped `OpenCore.qcow2` template boots the default entry immediately with
   no picker UI (a visible picker can't be driven reliably headlessly — OpenCanopy cancels its
   `Timeout` countdown on stray USB-enumeration input and then waits forever). `--random-smbios`

qemu/launch.go

@@ -45,6 +45,7 @@ type Spec struct {
 
 // Args returns the qemu-system-x86_64 argument vector for the macOS guest.
 func (s Spec) Args() []string {
+	cores := max(s.CPUs/2, 1)
 	varsFmt := "raw"
 	if IsQcow2NVRAM(s.OVMFVars) {
 		varsFmt = "qcow2"
@@ -60,8 +61,7 @@ func (s Spec) Args() []string {
 		"-enable-kvm", "-m", s.Memory,
 		"-cpu", macOSCPU,
 		"-machine", machine,
-		// Implicit threads lets QEMU infer SMT layouts (3 vCPUs -> 1 core x 3 threads) that macOS boots slowly or not at all.
-		"-smp", fmt.Sprintf("%d,cores=%d,threads=1,sockets=1", s.CPUs, s.CPUs),
+		"-smp", fmt.Sprintf("%d,cores=%d,sockets=1", s.CPUs, cores),
 		"-device", "qemu-xhci,id=xhci",
 		"-device", "usb-kbd,bus=xhci.0",
 		"-device", "usb-tablet,bus=xhci.0",

qemu/launch_test.go

@@ -148,13 +148,13 @@ func TestArgsCPU(t *testing.T) {
 			t.Fatalf("-cpu missing load-bearing %s: %s", f, cpu[0])
 		}
 	}
-	if got := argVals(s.Args(), "-smp"); len(got) != 1 || got[0] != "4,cores=4,threads=1,sockets=1" {
+	if got := argVals(s.Args(), "-smp"); len(got) != 1 || got[0] != "4,cores=2,sockets=1" {
 		t.Fatalf("unexpected CPU topology: %v", got)
 	}
 
-	s.CPUs = 3
-	if got := argVals(s.Args(), "-smp"); len(got) != 1 || got[0] != "3,cores=3,threads=1,sockets=1" {
-		t.Fatalf("unexpected odd CPU topology: %v", got)
+	s.CPUs = 2
+	if got := argVals(s.Args(), "-smp"); len(got) != 1 || got[0] != "2,cores=1,sockets=1" {
+		t.Fatalf("unexpected two-vCPU topology: %v", got)
 	}
 }