refactor: final /code + /simplify pass — close audit loop

Aggregate findings from 5 parallel audit agents (ordering/types/naming,
errors+modernization, reuse, quality, efficiency) across 156 non-test files.
All actionable items applied; net -3 LOC.

Reuse / templates:
- hypervisor.PreflightRestore template: load+validate sidecar, integrity
  callback, ValidateRoleSequence. CH/FC preflightRestore become 3-line
  delegations.
- cmd/core.resolveOwner generic: ResolveImageOwner and resolveVMOwner
  collapse onto one helper parameterized by found-callback + sentinels.
- firecracker.putJSON generic: 5 putXxx helpers collapse to thin wrappers.

Efficiency:
- snapshot/localfile.Delete batches the per-id store.Update into a single
  transaction (was N+1 flock cycles on M-ref delete).
- cmd/vm.recoverNetwork uses one List + map lookup instead of M Inspect
  calls under DB lock.
- network/cni: drop redundant LinkByName re-fetch when overrideMAC is set
  (already known value).

Style / dead code:
- Remove dead vmAPI / vmAPICall (unused after the *APIOnce migration).
- Remove duplicate TODO(inspect) in cloudhypervisor/extend.go.
- Drop firecracker PR-number reference from clone.go (per comment hygiene).
- Restore exec-justification comment in cloudhypervisor/start.go.
- utils/tar: errors.Is(err, io.EOF) instead of == comparison.
- strconv.Itoa / FormatInt instead of fmt.Sprintf("%d", ...).
- cloudhypervisor/snapshot: cowName via filepath.Base(cowPath) instead of
  branched literal.
- cmd/vm: vmID[:8] → network.VMIDPrefix.

Layout:
- network/bridge/bridge_other.go: var before type.
- images/cloudimg/inspect.go: var before type.

make lint dual-platform 0 issues; make test all pass.

Author: CMGS

cmd/core/helpers.go

@@ -270,27 +270,41 @@ func EnsureImage(ctx context.Context, backends []imagebackend.Images, vmCfg *typ
 }
 
 func ResolveImageOwner(ctx context.Context, backends []imagebackend.Images, ref string) (imagebackend.Images, error) {
-	var matches []imagebackend.Images
-	for _, b := range backends {
+	return resolveOwner(backends, ref, func(b imagebackend.Images) (bool, error) {
 		img, err := b.Inspect(ctx, ref)
+		return img != nil, err
+	},
+		fmt.Errorf("image %q: not found in any backend", ref),
+		fmt.Errorf("image %s: %w", ref, imagebackend.ErrAmbiguous),
+	)
+}
+
+// resolveOwner returns the unique backend among backends for which found
+// reports true. notFound is returned when zero match; ambiguous wraps the
+// caller-supplied error and lists the matched backend types.
+func resolveOwner[T interface{ Type() string }](backends []T, ref string, found func(T) (bool, error), notFound, ambiguous error) (T, error) {
+	var matches []T
+	var zero T
+	for _, b := range backends {
+		ok, err := found(b)
 		if err != nil {
-			return nil, fmt.Errorf("inspect %s in %s: %w", ref, b.Type(), err)
+			return zero, fmt.Errorf("inspect %s in %s: %w", ref, b.Type(), err)
 		}
-		if img != nil {
+		if ok {
 			matches = append(matches, b)
 		}
 	}
 	switch len(matches) {
 	case 0:
-		return nil, fmt.Errorf("image %q: not found in any backend", ref)
+		return zero, notFound
 	case 1:
 		return matches[0], nil
 	default:
 		names := make([]string, len(matches))
 		for i, b := range matches {
 			names[i] = b.Type()
 		}
-		return nil, fmt.Errorf("image %s: %w (backends: %s)", ref, imagebackend.ErrAmbiguous, strings.Join(names, ", "))
+		return zero, fmt.Errorf("%w (backends: %s)", ambiguous, strings.Join(names, ", "))
 	}
 }
 
@@ -503,30 +517,17 @@ func findHypervisorFactory(typ config.HypervisorType) func(*config.Config) (hype
 }
 
 func resolveVMOwner(ctx context.Context, hypers []hypervisor.Hypervisor, ref string) (hypervisor.Hypervisor, error) {
-	var matches []hypervisor.Hypervisor
-	for _, h := range hypers {
-		_, resolveErr := h.Inspect(ctx, ref)
-		if resolveErr == nil {
-			matches = append(matches, h)
-			continue
+	return resolveOwner(hypers, ref, func(h hypervisor.Hypervisor) (bool, error) {
+		if _, err := h.Inspect(ctx, ref); err == nil {
+			return true, nil
+		} else if !errors.Is(err, hypervisor.ErrNotFound) {
+			return false, err
 		}
-		if errors.Is(resolveErr, hypervisor.ErrNotFound) {
-			continue
-		}
-		return nil, fmt.Errorf("inspect %s in %s: %w", ref, h.Type(), resolveErr)
-	}
-	switch len(matches) {
-	case 0:
-		return nil, fmt.Errorf("vm %s: %w", ref, hypervisor.ErrNotFound)
-	case 1:
-		return matches[0], nil
-	default:
-		names := make([]string, len(matches))
-		for i, h := range matches {
-			names[i] = h.Type()
-		}
-		return nil, fmt.Errorf("vm %s: %w (backends: %s)", ref, hypervisor.ErrAmbiguous, strings.Join(names, ", "))
-	}
+		return false, nil
+	},
+		fmt.Errorf("vm %s: %w", ref, hypervisor.ErrNotFound),
+		fmt.Errorf("vm %s: %w", ref, hypervisor.ErrAmbiguous),
+	)
 }
 
 // sanitizeVMName derives a safe VM name from an image reference.

cmd/vm/attach.go

@@ -1,6 +1,7 @@
 package vm
 
 import (
+	"context"
 	"errors"
 	"fmt"
 
@@ -14,18 +15,10 @@ import (
 )
 
 func (h Handler) FsAttach(cmd *cobra.Command, args []string) error {
-	ctx, conf, err := h.Init(cmd)
+	ctx, a, err := resolveAttacher[fs.Attacher](h, cmd, args, "fs attach", fs.ErrUnsupportedBackend)
 	if err != nil {
 		return err
 	}
-	hyper, err := cmdcore.FindHypervisor(ctx, conf, args[0])
-	if err != nil {
-		return fmt.Errorf("fs attach: %w", err)
-	}
-	a, ok := hyper.(fs.Attacher)
-	if !ok {
-		return fmt.Errorf("fs attach: backend %s: %w", hyper.Type(), fs.ErrUnsupportedBackend)
-	}
 	socket, _ := cmd.Flags().GetString("socket")
 	tag, _ := cmd.Flags().GetString("tag")
 	numQ, _ := cmd.Flags().GetInt("num-queues")
@@ -42,18 +35,10 @@ func (h Handler) FsAttach(cmd *cobra.Command, args []string) error {
 }
 
 func (h Handler) FsDetach(cmd *cobra.Command, args []string) error {
-	ctx, conf, err := h.Init(cmd)
+	ctx, a, err := resolveAttacher[fs.Attacher](h, cmd, args, "fs detach", fs.ErrUnsupportedBackend)
 	if err != nil {
 		return err
 	}
-	hyper, err := cmdcore.FindHypervisor(ctx, conf, args[0])
-	if err != nil {
-		return fmt.Errorf("fs detach: %w", err)
-	}
-	a, ok := hyper.(fs.Attacher)
-	if !ok {
-		return fmt.Errorf("fs detach: backend %s: %w", hyper.Type(), fs.ErrUnsupportedBackend)
-	}
 	tag, _ := cmd.Flags().GetString("tag")
 	if err := a.FsDetach(ctx, args[0], tag); err != nil {
 		return classifyAttachErr(err)
@@ -66,18 +51,10 @@ func (h Handler) FsDetach(cmd *cobra.Command, args []string) error {
 }
 
 func (h Handler) DeviceAttach(cmd *cobra.Command, args []string) error {
-	ctx, conf, err := h.Init(cmd)
+	ctx, a, err := resolveAttacher[vfio.Attacher](h, cmd, args, "device attach", vfio.ErrUnsupportedBackend)
 	if err != nil {
 		return err
 	}
-	hyper, err := cmdcore.FindHypervisor(ctx, conf, args[0])
-	if err != nil {
-		return fmt.Errorf("device attach: %w", err)
-	}
-	a, ok := hyper.(vfio.Attacher)
-	if !ok {
-		return fmt.Errorf("device attach: backend %s: %w", hyper.Type(), vfio.ErrUnsupportedBackend)
-	}
 	pci, _ := cmd.Flags().GetString("pci")
 	id, _ := cmd.Flags().GetString("id")
 	deviceID, err := a.DeviceAttach(ctx, args[0], vfio.Spec{PCI: pci, ID: id})
@@ -92,18 +69,10 @@ func (h Handler) DeviceAttach(cmd *cobra.Command, args []string) error {
 }
 
 func (h Handler) DeviceDetach(cmd *cobra.Command, args []string) error {
-	ctx, conf, err := h.Init(cmd)
+	ctx, a, err := resolveAttacher[vfio.Attacher](h, cmd, args, "device detach", vfio.ErrUnsupportedBackend)
 	if err != nil {
 		return err
 	}
-	hyper, err := cmdcore.FindHypervisor(ctx, conf, args[0])
-	if err != nil {
-		return fmt.Errorf("device detach: %w", err)
-	}
-	a, ok := hyper.(vfio.Attacher)
-	if !ok {
-		return fmt.Errorf("device detach: backend %s: %w", hyper.Type(), vfio.ErrUnsupportedBackend)
-	}
 	id, _ := cmd.Flags().GetString("id")
 	if err := a.DeviceDetach(ctx, args[0], id); err != nil {
 		return classifyAttachErr(err)
@@ -115,6 +84,27 @@ func (h Handler) DeviceDetach(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// resolveAttacher resolves args[0] to a hypervisor and asserts it implements
+// A (fs.Attacher / vfio.Attacher). The op string ("fs attach", "device detach")
+// prefixes both error wraps so the four handlers no longer repeat the
+// Init→FindHypervisor→type-assert boilerplate.
+func resolveAttacher[A any](h Handler, cmd *cobra.Command, args []string, op string, errUnsupported error) (context.Context, A, error) {
+	var zero A
+	ctx, conf, err := h.Init(cmd)
+	if err != nil {
+		return ctx, zero, err
+	}
+	hyper, err := cmdcore.FindHypervisor(ctx, conf, args[0])
+	if err != nil {
+		return ctx, zero, fmt.Errorf("%s: %w", op, err)
+	}
+	a, ok := hyper.(A)
+	if !ok {
+		return ctx, zero, fmt.Errorf("%s: backend %s: %w", op, hyper.Type(), errUnsupported)
+	}
+	return ctx, a, nil
+}
+
 // classifyAttachErr surfaces ErrNotRunning more clearly than the generic wrap.
 func classifyAttachErr(err error) error {
 	if errors.Is(err, hypervisor.ErrNotRunning) {

cmd/vm/lifecycle.go

@@ -238,9 +238,23 @@ func (h Handler) recoverNetwork(ctx context.Context, conf *config.Config, hyper
 	// Cache bridge providers by device name to avoid redundant netlink lookups.
 	bridgeProviders := map[string]network.Network{}
 
+	// Single List → map by ID/name avoids one Inspect-per-ref under DB lock.
+	all, err := hyper.List(ctx)
+	if err != nil {
+		logger.Warnf(ctx, "list VMs for recovery: %v", err)
+		return
+	}
+	byRef := make(map[string]*types.VM, len(all)*2)
+	for _, vm := range all {
+		byRef[vm.ID] = vm
+		if vm.Config.Name != "" {
+			byRef[vm.Config.Name] = vm
+		}
+	}
+
 	for _, ref := range refs {
-		vm, err := hyper.Inspect(ctx, ref)
-		if err != nil || vm == nil || len(vm.NetworkConfigs) == 0 {
+		vm := byRef[ref]
+		if vm == nil || len(vm.NetworkConfigs) == 0 {
 			continue
 		}
 

cmd/vm/run.go

@@ -246,7 +246,7 @@ func (h Handler) prepareClone(ctx context.Context, cmd *cobra.Command, conf *con
 	}
 	vmID := utils.GenerateID()
 	if vmCfg.Name == "" {
-		vmCfg.Name = "cocoon-clone-" + vmID[:8]
+		vmCfg.Name = "cocoon-clone-" + network.VMIDPrefix(vmID)
 	}
 
 	// Auto-pull base image if --pull is set (cross-node clone).

hypervisor/cloudhypervisor/extend.go

@@ -67,10 +67,6 @@ func (ch *CloudHypervisor) FsDetach(ctx context.Context, vmRef, tag string) erro
 }
 
 // FsList enumerates currently attached vhost-user-fs devices.
-//
-// TODO(inspect): cmd/vm Inspect calls FsList and DeviceList back-to-back,
-// each fetching its own vm.info. A combined Lister returning both arrays
-// from a single vm.info call would halve the round-trips on a running VM.
 func (ch *CloudHypervisor) FsList(ctx context.Context, vmRef string) ([]fs.Attached, error) {
 	return listWith(ctx, ch, vmRef, func(info *chVMInfoResponse) []fs.Attached {
 		out := make([]fs.Attached, 0, len(info.Config.Fs))
@@ -129,8 +125,6 @@ func (ch *CloudHypervisor) DeviceDetach(ctx context.Context, vmRef, id string) e
 }
 
 // DeviceList enumerates currently attached VFIO PCI passthrough devices.
-//
-// TODO(inspect): see FsList note — combined Lister would dedupe vm.info.
 func (ch *CloudHypervisor) DeviceList(ctx context.Context, vmRef string) ([]vfio.Attached, error) {
 	return listWith(ctx, ch, vmRef, func(info *chVMInfoResponse) []vfio.Attached {
 		out := make([]vfio.Attached, 0, len(info.Config.Devices))
@@ -187,6 +181,13 @@ func (ch *CloudHypervisor) attachWith(
 	if pci.ID != "" {
 		return pci.ID, nil
 	}
+	// CH always returns 200 with PciDeviceInfo on add-fs/add-device, so this
+	// path means we accepted the alt 204 success code and lost the body. The
+	// fallback covers the user-supplied id; an empty fallback (e.g. VFIO with
+	// no --id) would otherwise leave the caller without a detach key.
+	if fallbackID == "" {
+		return "", fmt.Errorf("%s: empty response body and no fallback id (CH returned no PciDeviceInfo)", endpoint)
+	}
 	return fallbackID, nil
 }
 

hypervisor/cloudhypervisor/helper.go

@@ -93,21 +93,10 @@ func hasMemoryRangeFile(srcDir string) (bool, error) {
 	return false, nil
 }
 
-func vmAPI(ctx context.Context, hc *http.Client, endpoint string, body []byte, successCodes ...int) error {
-	_, err := vmAPICall(ctx, hc, endpoint, body, successCodes...)
-	return err
-}
-
-// vmAPICall returns the raw response body so callers that need to decode
-// PciDeviceInfo (vm.add-fs, vm.add-device, ...) can use the same retry path.
-func vmAPICall(ctx context.Context, hc *http.Client, endpoint string, body []byte, successCodes ...int) ([]byte, error) {
-	return utils.DoAPIWithRetry(ctx, hc, http.MethodPut, "http://localhost/api/v1/"+endpoint, body, successCodes...)
-}
-
-// vmAPIOnce sends a single PUT without DoWithRetry. Use for non-idempotent
-// endpoints — e.g. vm.add-fs / vm.add-device — where a retry after a
-// network drop or 5xx that landed on CH after the device was already added
-// would surface as a misleading "duplicate id" rejection.
+// vmAPIOnce sends a single PUT without DoWithRetry. Used for non-idempotent
+// endpoints where a retry after a lost response could mask the original
+// success as a misleading "duplicate id" / wrong-state rejection. Returns the
+// raw body so add-fs/add-device callers can decode PciDeviceInfo.
 func vmAPIOnce(ctx context.Context, hc *http.Client, endpoint string, body []byte, successCodes ...int) ([]byte, error) {
 	return utils.DoAPIOnce(ctx, hc, http.MethodPut, "http://localhost/api/v1/"+endpoint, body, successCodes...)
 }
@@ -225,7 +214,8 @@ func decodePciDeviceInfo(resp []byte) (chPciDeviceInfo, error) {
 }
 
 func powerButton(ctx context.Context, hc *http.Client) error {
-	return vmAPI(ctx, hc, "vm.power-button", nil)
+	_, err := vmAPIOnce(ctx, hc, "vm.power-button", nil)
+	return err
 }
 
 // queryConsolePTY retrieves the virtio-console PTY path from a running CH

hypervisor/cloudhypervisor/restore.go

@@ -26,17 +26,8 @@ func (ch *CloudHypervisor) Restore(ctx context.Context, vmRef string, vmCfg *typ
 	})
 }
 
-// preflightRestore validates the sidecar and asserts the snapshot's role
-// sequence is a valid prefix of rec (cidata-only suffix is the one extension).
 func (ch *CloudHypervisor) preflightRestore(srcDir string, rec *hypervisor.VMRecord) error {
-	meta, err := hypervisor.LoadAndValidateMeta(srcDir, ch.conf.RootDir, ch.conf.Config.RunDir)
-	if err != nil {
-		return err
-	}
-	if err := validateSnapshotIntegrity(srcDir, meta.StorageConfigs); err != nil {
-		return err
-	}
-	return hypervisor.ValidateRoleSequence(meta.StorageConfigs, rec.StorageConfigs)
+	return hypervisor.PreflightRestore(srcDir, ch.conf.RootDir, ch.conf.Config.RunDir, rec, validateSnapshotIntegrity)
 }
 
 func (ch *CloudHypervisor) killForRestore(ctx context.Context, vmID string, rec *hypervisor.VMRecord) error {

hypervisor/cloudhypervisor/snapshot.go

@@ -32,10 +32,7 @@ func (ch *CloudHypervisor) Snapshot(ctx context.Context, ref string) (*types.Sna
 
 	directBoot := isDirectBoot(rec.BootConfig)
 	cowPath := ch.cowPath(vmID, directBoot)
-	cowName := "overlay.qcow2"
-	if directBoot {
-		cowName = "cow.raw"
-	}
+	cowName := filepath.Base(cowPath)
 
 	tmpDir, err := os.MkdirTemp(ch.conf.VMRunDir(vmID), "snapshot-")
 	if err != nil {

hypervisor/cloudhypervisor/start.go

@@ -55,6 +55,7 @@ func (ch *CloudHypervisor) launchProcess(ctx context.Context, rec *hypervisor.VM
 		defer logFile.Close() //nolint:errcheck
 	}
 
+	// shell out: the cloud-hypervisor binary is the authoritative VMM.
 	cmd := exec.Command(ch.conf.CHBinary, args...) //nolint:gosec
 	// Setpgid so CH survives if this process exits.
 	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}

hypervisor/cloudhypervisor/utils.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 
 	"github.com/projecteru2/core/log"
@@ -46,7 +47,7 @@ func qemuExpandImage(ctx context.Context, path string, targetSize int64, directB
 	if targetSize <= virtualSize {
 		return nil
 	}
-	if err := utils.RunQemuImg(ctx, "resize", path, fmt.Sprintf("%d", targetSize)); err != nil {
+	if err := utils.RunQemuImg(ctx, "resize", path, strconv.FormatInt(targetSize, 10)); err != nil {
 		return fmt.Errorf("resize %s: %w", path, err)
 	}
 	return nil