New features

Kernel version pinning and resolution

Avocado projects can now declare one or more named kernel configurations at the top level and reference them per-runtime. The kernel: block accepts either a singleton (synthesized as the implicit default entry) or a named map:

kernel:
  yocto-6-6:
    package: kernel-image-6.6
    version: '*'
  yocto-5-15:
    package: kernel-image-5.15
    version: '*'

runtimes:
  dev:
    kernel: yocto-6-6 # named reference
  prod:
    kernel: # inline override
      package: kernel-image
      version: '6.6.*'

Kernels may also be sourced from a compile section instead of a package feed (for custom Yocto or out-of-tree kernels):

kernel:
  custom:
    compile: my-kernel-section
    install: scripts/install-kernel.sh

provision and deploy now validate kernel consistency across sysroots before writing to the device or flashing. If the kernel installed in rootfs diverges from the kernel sysroot, the CLI will report the drift and abort.

See Kernel configuration for the full option reference.

Runtime-scoped extensions and AVOCADO_RUNTIME

Extension lifecycle commands (ext build, ext clean, ext image, ext dnf, ext checkout, ext package) now accept a -r/--runtime flag. When a runtime is provided, the command operates on the per-runtime extension sysroot instead of the shared per-target tree, and the AVOCADO_RUNTIME environment variable is forwarded into the container so that $AVOCADO_EXT_SYSROOTS is scoped to the correct runtime directory.

avocado ext build my-ext -r prod
AVOCADO_RUNTIME=prod avocado ext build my-ext

Runtime membership is now recorded in the lockfile (lockfile v6), so extension state is tracked per-runtime rather than globally. runtime build propagates AVOCADO_RUNTIME to all sub-container invocations automatically.

default_runtime config option

A new top-level default_runtime field sets the project-wide default runtime for commands that scope by runtime. This avoids passing -r on every invocation:

default_runtime: dev

runtimes:
  dev: { ... }
  prod: { ... }

Resolution order: CLI -r/--runtime > AVOCADO_RUNTIME env var > default_runtime config > auto-resolved sole runtime.

The AVOCADO_RUNTIME environment variable mirrors this at the shell level and takes precedence over the config value.

See Default runtime for details.

Overlay support for rootfs and initramfs

Rootfs and initramfs configs now accept an overlay field that merges a source directory from your project into the sysroot after package installation:

rootfs:
  overlay: overlays/rootfs # short form: merge mode

initramfs:
  overlay:
    dir: overlays/initramfs
    mode: opaque # fully replaces directory contents

Merge mode (default) uses rsync -a — adds and replaces files but leaves unrelated files alone. Opaque mode uses cp -r — fully replaces the directory. Overlay config participates in the sysroot stamp hash, so changes trigger a reinstall.

See Overlay for details.

---

Bug fixes

• deploy now validates the runtime build stamp (not the provision stamp) before flashing, preventing stale images from being deployed.
• Rootfs and initramfs stamps now include kernel config in their input hash — changing a kernel pin invalidates the sysroot and triggers a clean reinstall.
• When a lockfile kernel pin no longer satisfies the configured version spec, the kernel is re-resolved and the sysroot is reinstalled rather than silently using an out-of-spec kernel.
• On kernel pin change, rootfs and initramfs are cleaned and reinstalled so all kernel modules match the new kernel.
• Lockfile saves are now serialized through a process-wide gate with a disk-merge step, preventing concurrent readers from seeing truncated (EOF) state.
• Extension lockfile entries written during ext install now persist even when the extension has zero packages (membership is tracked independently of package count).
• Runtime extension package maps are now merged at the package-map level on lockfile load, not at the whole-lock level, preventing cross-runtime package contamination.
• query_installed_packages forwards env_vars into the container so that runtime-scoped DNF queries resolve the correct sysroot.

---

Other

• Lockfile schema bumped to v6: extensions are now tracked under targets.<t>.runtimes.<r>.extensions instead of a flat global map. The CLI migrates v5 lockfiles automatically on first write.
• Lockfile writes use atomic rename so concurrent readers never observe a partial file.
• Dependency updates: crossterm 0.28 → 0.29, serde_jcs 0.1 → 0.2, sha2 0.10 → 0.11, tough 0.21 → 0.22.