refactor: shared CH/FC backend templates and helper consolidation

Pull pause/resume, restore, and process-launch sequences into Backend
methods on the hypervisor package so both backends call thin wrappers:

- WithPausedVM (around CH/FC snapshot capture): centralizes pause →
  defer-resume → eager-resume-on-success bookkeeping.
- RestoreSequence + DirectRestoreSequence: validate-CPU → resolve →
  optional override-check → preflight → kill → optional disk lock →
  merge-or-populate → after-extract. Backends supply only the differing
  hooks. FC's tar-stream and direct-dir paths now share both templates.
- LaunchVMProcess: netns enter → exec.Cmd start → WritePIDFile →
  WaitForSocket, with deferred kill-and-cleanup on any error path. CH/FC
  start.go drop ~30 LOC of identical fork/wait scaffolding each.

Also pull cross-cutting helpers into hypervisor/utils:
CloneStorageConfigs, IsUnderDir, ValidateMetaPaths,
LoadAndValidateMeta, ReverseLayers. CH now applies the same
sidecar-path-trust check FC has had — defense in depth against tampered
cocoon.json paths in imported snapshots.

Smaller cleanups bundled in:
- utils.MapValues + utils.PeekReader generic helpers (used by image
  index list, network list, vm list, gzip and qcow2 sniffers).
- cmp.Or for trivial fallback assignments in cmd/core, cmd/vm, oci/boot.
- EnsureVmlinux uses utils.AtomicWriteFile.
- saveCmdline uses utils.AtomicWriteFile + cmdlineFileName constant.
- LaunchSpec drops BinaryName/Timeout fields — derived from BackendConfig.
- Sweep A renames: runtimeFiletoCLIArg → runtimeFileToCLIArg, fcPid →
  fcPID, GCStaleTemp/GCCollectBlobs moved above private helpers.
- Bug fix: unwrapGzip no longer wraps a nil error when the stream is
  shorter than the gzip magic.

Tests: PeekReader, MapValues, IsUnderDir, ValidateMetaPaths,
CloneStorageConfigs, ReverseLayers. ValidateMetaPaths is
security-sensitive (path traversal rejection) and gets dedicated cases
for /etc/shadow, kernel-out-of-root, and initrd-out-of-root.

make lint clean on linux + darwin; make test passes (utils coverage
82.5 → was 79.8; hypervisor 7.2 → 3.6).

Author: CMGS

cmd/core/helpers.go

@@ -233,10 +233,7 @@ func EnsureImage(ctx context.Context, backends []imagebackend.Images, vmCfg *typ
 	logger := log.WithFunc("core.EnsureImage")
 
 	// Use digest for lookup when available; fall back to tag/URL.
-	lookupRef := vmCfg.ImageDigest
-	if lookupRef == "" {
-		lookupRef = vmCfg.Image
-	}
+	lookupRef := cmp.Or(vmCfg.ImageDigest, vmCfg.Image)
 
 	for _, b := range backends {
 		if b.Type() != vmCfg.ImageType {
@@ -693,9 +690,7 @@ func normalizeDataDiskSpecs(specs []types.DataDiskSpec) error {
 	}
 	autoIdx := 1
 	for i := range specs {
-		if specs[i].FSType == "" {
-			specs[i].FSType = types.FSTypeExt4
-		}
+		specs[i].FSType = cmp.Or(specs[i].FSType, types.FSTypeExt4)
 		if specs[i].FSType != types.FSTypeExt4 && specs[i].FSType != types.FSTypeNone {
 			return fmt.Errorf("--data-disk: invalid fstype %q", specs[i].FSType)
 		}

cmd/vm/run.go

@@ -1,6 +1,7 @@
 package vm
 
 import (
+	"cmp"
 	"context"
 	"fmt"
 	"slices"
@@ -265,10 +266,8 @@ func (h Handler) prepareClone(ctx context.Context, cmd *cobra.Command, conf *con
 		}
 	}
 
-	nics, _ := cmd.Flags().GetInt("nics")
-	if nics == 0 {
-		nics = cfg.NICs
-	}
+	nicsFlag, _ := cmd.Flags().GetInt("nics")
+	nics := cmp.Or(nicsFlag, cfg.NICs)
 	if nics < cfg.NICs {
 		return nil, "", nil, nil, fmt.Errorf("--nics %d below snapshot minimum %d", nics, cfg.NICs)
 	}

hypervisor/backend.go

@@ -8,6 +8,7 @@ import (
 	"io/fs"
 	"maps"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"time"
 
@@ -50,6 +51,7 @@ type BackendConfig interface {
 	BinaryName() string
 	PIDFileName() string
 	TerminateGracePeriod() time.Duration
+	SocketWaitTimeout() time.Duration
 	EffectivePoolSize() int
 	IndexFile() string
 	RunDir() string
@@ -85,12 +87,7 @@ func (b *Backend) Inspect(ctx context.Context, ref string) (*types.VM, error) {
 func (b *Backend) List(ctx context.Context) ([]*types.VM, error) {
 	var result []*types.VM
 	return result, b.DB.With(ctx, func(idx *VMIndex) error {
-		for _, rec := range idx.VMs {
-			if rec == nil {
-				continue
-			}
-			result = append(result, b.ToVM(rec))
-		}
+		result = utils.MapValues(idx.VMs, b.ToVM)
 		return nil
 	})
 }
@@ -147,6 +144,41 @@ func (b *Backend) WithRunningVM(ctx context.Context, rec *VMRecord, fn func(pid
 	return fn(pid)
 }
 
+// WithPausedVM pauses a running VM, runs fn, then resumes it. Resume is
+// guaranteed via defer: if fn returns an error the resume failure is logged
+// and the inner error is propagated; if fn succeeds the resume error is
+// promoted to the return value (snapshot data is captured but the VM is
+// stuck). Both backends use this around snapshot capture.
+func (b *Backend) WithPausedVM(ctx context.Context, rec *VMRecord, pause, resume, fn func() error) error {
+	return b.WithRunningVM(ctx, rec, func(_ int) error {
+		if err := pause(); err != nil {
+			return fmt.Errorf("pause: %w", err)
+		}
+		var resumed bool
+		var resumeErr error
+		logger := log.WithFunc(b.Typ + ".WithPausedVM")
+		doResume := func() {
+			if resumed {
+				return
+			}
+			resumed = true
+			resumeErr = resume()
+			if resumeErr != nil {
+				logger.Warnf(ctx, "resume VM %s: %v", rec.ID, resumeErr)
+			}
+		}
+		defer doResume()
+		if err := fn(); err != nil {
+			return err
+		}
+		doResume()
+		if resumeErr != nil {
+			return fmt.Errorf("snapshot data captured but resume failed: %w", resumeErr)
+		}
+		return nil
+	})
+}
+
 func (b *Backend) UpdateStates(ctx context.Context, ids []string, state types.VMState) error {
 	if len(ids) == 0 {
 		return nil
@@ -633,6 +665,66 @@ func SocketPath(runDir string) string { return filepath.Join(runDir, APISocketNa
 
 func ConsoleSockPath(runDir string) string { return filepath.Join(runDir, ConsoleSockName) }
 
+// LaunchSpec carries the per-call inputs to LaunchVMProcess. The shared
+// BinaryName / SocketWaitTimeout come from the Backend's BackendConfig and
+// don't repeat here.
+type LaunchSpec struct {
+	Cmd       *exec.Cmd
+	PIDPath   string
+	SockPath  string
+	NetnsPath string // empty = host netns
+	OnFail    func() // optional cleanup hook on any error path
+}
+
+// LaunchVMProcess optionally enters a netns, starts spec.Cmd, writes the PID
+// file, and waits for the API socket. On any post-Start error the process is
+// killed and the PID file is removed before returning. The caller is
+// responsible for reaping cmd via cmd.Wait() in a goroutine on success.
+func (b *Backend) LaunchVMProcess(ctx context.Context, spec LaunchSpec) (pid int, err error) {
+	started := false
+	pidWritten := false
+	binaryName := b.Conf.BinaryName()
+	defer func() {
+		if err == nil {
+			return
+		}
+		if started {
+			_ = spec.Cmd.Process.Kill()
+			_ = spec.Cmd.Wait()
+		}
+		if pidWritten {
+			_ = os.Remove(spec.PIDPath)
+		}
+		if spec.OnFail != nil {
+			spec.OnFail()
+		}
+	}()
+
+	if spec.NetnsPath != "" {
+		restore, nsErr := EnterNetns(spec.NetnsPath)
+		if nsErr != nil {
+			return 0, fmt.Errorf("enter netns: %w", nsErr)
+		}
+		defer restore()
+	}
+
+	if err = spec.Cmd.Start(); err != nil {
+		return 0, fmt.Errorf("exec %s: %w", binaryName, err)
+	}
+	started = true
+	pid = spec.Cmd.Process.Pid
+
+	if err = utils.WritePIDFile(spec.PIDPath, pid); err != nil {
+		return 0, fmt.Errorf("write PID file: %w", err)
+	}
+	pidWritten = true
+
+	if err = WaitForSocket(ctx, spec.SockPath, pid, b.Conf.SocketWaitTimeout(), binaryName); err != nil {
+		return 0, err
+	}
+	return pid, nil
+}
+
 // PrepareStagingDir creates a sibling staging directory, extracts the snapshot
 // tar into it, and returns a cleanup function that removes the staging dir.
 func PrepareStagingDir(runDir string, snapshot io.Reader) (stagingDir string, cleanup func(), err error) {
@@ -650,3 +742,132 @@ func PrepareStagingDir(runDir string, snapshot io.Reader) (stagingDir string, cl
 	}
 	return stagingDir, cleanup, nil
 }
+
+// RestoreSpec carries the backend-specific hooks for RestoreSequence. The
+// shared template handles host-CPU validation, ResolveForRestore, staging,
+// preflight, kill, and merge — backends supply only the differing pieces.
+type RestoreSpec struct {
+	VMCfg         *types.VMConfig
+	Snapshot      io.Reader
+	OverrideCheck func(rec *VMRecord, vmCfg *types.VMConfig) error // optional pre-kill resource validation
+	Preflight     func(stagingDir string, rec *VMRecord) error
+	Kill          func(ctx context.Context, vmID string, rec *VMRecord) error
+	Wrap          func(rec *VMRecord, fn func() error) error // optional disk lock wrapping merge+afterExtract
+	BeforeMerge   func(rec *VMRecord) error                  // optional pre-merge hook (e.g. FC removes stale COW)
+	AfterExtract  func(ctx context.Context, vmID string, vmCfg *types.VMConfig, rec *VMRecord) (*types.VM, error)
+}
+
+// DirectRestoreSpec mirrors RestoreSpec but takes a local source directory
+// rather than a streaming tar. Populate replaces the staging+merge step:
+// backends decide how to copy the snapshot files into rec.RunDir (typically
+// clean old artifacts, then per-file hardlink/reflink/copy).
+type DirectRestoreSpec struct {
+	VMCfg         *types.VMConfig
+	SrcDir        string
+	OverrideCheck func(rec *VMRecord, vmCfg *types.VMConfig) error
+	Preflight     func(srcDir string, rec *VMRecord) error
+	Kill          func(ctx context.Context, vmID string, rec *VMRecord) error
+	Wrap          func(rec *VMRecord, fn func() error) error
+	Populate      func(rec *VMRecord, srcDir string) error
+	AfterExtract  func(ctx context.Context, vmID string, vmCfg *types.VMConfig, rec *VMRecord) (*types.VM, error)
+}
+
+// RestoreSequence runs the shared restore flow used by both backends:
+// validate host CPU, resolve VM, stage tar, preflight, kill, merge, then
+// hand off to AfterExtract for backend-specific resume.
+func (b *Backend) RestoreSequence(ctx context.Context, vmRef string, spec RestoreSpec) (*types.VM, error) {
+	if err := ValidateHostCPU(spec.VMCfg.CPU); err != nil {
+		return nil, err
+	}
+	vmID, rec, err := b.ResolveForRestore(ctx, vmRef)
+	if err != nil {
+		return nil, err
+	}
+	if spec.OverrideCheck != nil {
+		if checkErr := spec.OverrideCheck(rec, spec.VMCfg); checkErr != nil {
+			return nil, checkErr
+		}
+	}
+
+	stagingDir, cleanupStaging, err := PrepareStagingDir(rec.RunDir, spec.Snapshot)
+	if err != nil {
+		return nil, err
+	}
+	defer cleanupStaging()
+
+	if preflightErr := spec.Preflight(stagingDir, rec); preflightErr != nil {
+		return nil, fmt.Errorf("snapshot preflight: %w", preflightErr)
+	}
+	if killErr := spec.Kill(ctx, vmID, rec); killErr != nil {
+		return nil, killErr
+	}
+
+	var result *types.VM
+	inner := func() error {
+		if spec.BeforeMerge != nil {
+			if err := spec.BeforeMerge(rec); err != nil {
+				return err
+			}
+		}
+		if mergeErr := MergeDirInto(stagingDir, rec.RunDir); mergeErr != nil {
+			b.MarkError(ctx, vmID)
+			return fmt.Errorf("apply staged snapshot: %w", mergeErr)
+		}
+		var afterErr error
+		result, afterErr = spec.AfterExtract(ctx, vmID, spec.VMCfg, rec)
+		return afterErr
+	}
+	if spec.Wrap != nil {
+		if err := spec.Wrap(rec, inner); err != nil {
+			return nil, err
+		}
+	} else if err := inner(); err != nil {
+		return nil, err
+	}
+	return result, nil
+}
+
+// DirectRestoreSequence runs the local-snapshot-dir variant of restore: the
+// caller supplies a srcDir already on disk. Same outage-safe ordering as
+// RestoreSequence (preflight before kill, optional disk lock around populate
+// + afterExtract).
+func (b *Backend) DirectRestoreSequence(ctx context.Context, vmRef string, spec DirectRestoreSpec) (*types.VM, error) {
+	if err := ValidateHostCPU(spec.VMCfg.CPU); err != nil {
+		return nil, err
+	}
+	vmID, rec, err := b.ResolveForRestore(ctx, vmRef)
+	if err != nil {
+		return nil, err
+	}
+	if spec.OverrideCheck != nil {
+		if checkErr := spec.OverrideCheck(rec, spec.VMCfg); checkErr != nil {
+			return nil, checkErr
+		}
+	}
+
+	if preflightErr := spec.Preflight(spec.SrcDir, rec); preflightErr != nil {
+		return nil, fmt.Errorf("snapshot preflight: %w", preflightErr)
+	}
+	if killErr := spec.Kill(ctx, vmID, rec); killErr != nil {
+		return nil, killErr
+	}
+
+	var result *types.VM
+	inner := func() error {
+		if populateErr := spec.Populate(rec, spec.SrcDir); populateErr != nil {
+			b.MarkError(ctx, vmID)
+			return populateErr
+		}
+		var afterErr error
+		result, afterErr = spec.AfterExtract(ctx, vmID, spec.VMCfg, rec)
+		return afterErr
+	}
+	if spec.Wrap != nil {
+		if wrapErr := spec.Wrap(rec, inner); wrapErr != nil {
+			return nil, wrapErr
+		}
+	} else if innerErr := inner(); innerErr != nil {
+		return nil, innerErr
+	}
+	return result, nil
+}

hypervisor/cloudhypervisor/args.go

@@ -151,10 +151,10 @@ func buildCLIArgs(cfg *chVMConfig, socketPath string) []string {
 	}
 
 	if cfg.Serial != nil {
-		args = append(args, "--serial", runtimeFiletoCLIArg(cfg.Serial))
+		args = append(args, "--serial", runtimeFileToCLIArg(cfg.Serial))
 	}
 	if cfg.Console != nil {
-		args = append(args, "--console", runtimeFiletoCLIArg(cfg.Console))
+		args = append(args, "--console", runtimeFileToCLIArg(cfg.Console))
 	}
 
 	return args
@@ -248,7 +248,7 @@ func balloonToCLIArg(b *chBalloon) string {
 	return args.String()
 }
 
-func runtimeFiletoCLIArg(c *chRuntimeFile) string {
+func runtimeFileToCLIArg(c *chRuntimeFile) string {
 	switch strings.ToLower(c.Mode) {
 	case "file":
 		return "file=" + c.File

hypervisor/cloudhypervisor/clone.go

@@ -47,7 +47,7 @@ func (ch *CloudHypervisor) cloneAfterExtract(ctx context.Context, vmID string, v
 		return nil, fmt.Errorf("parse CH config: %w", err)
 	}
 
-	meta, err := hypervisor.LoadSnapshotMeta(runDir)
+	meta, err := hypervisor.LoadAndValidateMeta(runDir, ch.conf.RootDir, ch.conf.Config.RunDir)
 	if err != nil {
 		return nil, fmt.Errorf("load snapshot meta: %w", err)
 	}