From 0c4ac17b82f1577a0873e0681a563b2cdc62521b Mon Sep 17 00:00:00 2001
From: Thales Maciel <thales@thalesmaciel.com>
Date: Sun, 8 Mar 2026 20:43:51 -0300
Subject: [PATCH] Stabilize kernel materialization parallelism

---
 AGENTS.md                                     |  1 +
 runtime_sources/README.md                     |  4 +++
 .../scripts/build_microvm_kernel.sh           | 30 ++++++++++++++++++-
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2b3f6b1..2910223 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,6 +20,7 @@ This repository ships `pyro-mcp`, an MCP-compatible package for ephemeral VM lif
 - Use `make runtime-materialize` to build real runtime inputs into `build/runtime_sources/`.
 - Use `make runtime-publish-official-environments-oci` after materialization to push the official OCI environments to their configured registry targets.
 - Use `make runtime-fetch-binaries`, `make runtime-build-kernel-real`, and `make runtime-build-rootfs-real` if you need to debug the real-source pipeline step by step.
+- If kernel materialization hits compiler crashes on a smaller host, retry with `PYRO_KERNEL_BUILD_JOBS=1 make runtime-build-kernel-real` or `PYRO_KERNEL_BUILD_JOBS=1 make runtime-materialize`.
 - Use `make runtime-boot-check` to run a direct Firecracker boot validation against the bundled runtime artifacts.
 - Use `make runtime-network-check` to validate outbound internet access from inside the guest.
 - Use `make demo` to validate deterministic VM lifecycle execution.
diff --git a/runtime_sources/README.md b/runtime_sources/README.md
index 5dc4849..bd128a1 100644
--- a/runtime_sources/README.md
+++ b/runtime_sources/README.md
@@ -25,6 +25,10 @@ Build requirements for the real path:
 - outbound network access to GitHub and Debian snapshot mirrors
 - enough disk for a kernel build plus 2G ext4 images per profile
 
+Kernel build note:
+- the kernel builder now defaults to conservative parallelism to avoid compiler crashes on memory-constrained hosts
+- if you still need to force a lower setting, use `PYRO_KERNEL_BUILD_JOBS=1 make runtime-build-kernel-real` or `PYRO_KERNEL_BUILD_JOBS=1 make runtime-materialize`
+
 Current status:
 1. Firecracker and Jailer are materialized from pinned official release artifacts.
 2. The kernel and rootfs images are built from pinned inputs into `build/runtime_sources/`.
diff --git a/runtime_sources/linux-x86_64/scripts/build_microvm_kernel.sh b/runtime_sources/linux-x86_64/scripts/build_microvm_kernel.sh
index 8a48a32..3b52daf 100755
--- a/runtime_sources/linux-x86_64/scripts/build_microvm_kernel.sh
+++ b/runtime_sources/linux-x86_64/scripts/build_microvm_kernel.sh
@@ -7,6 +7,7 @@ source_url=""
 config_url=""
 workdir=""
 output=""
+jobs="${PYRO_KERNEL_BUILD_JOBS:-}"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -16,6 +17,7 @@ while [[ $# -gt 0 ]]; do
     --config-url) config_url="$2"; shift 2 ;;
     --workdir) workdir="$2"; shift 2 ;;
     --output) output="$2"; shift 2 ;;
+    --jobs) jobs="$2"; shift 2 ;;
     *) echo "unknown arg: $1" >&2; exit 1 ;;
   esac
 done
@@ -27,6 +29,31 @@ done
 : "${workdir:?missing --workdir}"
 : "${output:?missing --output}"
 
+if [[ -z "$jobs" ]]; then
+  cpu_jobs="$(nproc)"
+  mem_available_kib="$(awk '/MemAvailable:/ { print $2; exit }' /proc/meminfo || true)"
+  jobs="$cpu_jobs"
+  if [[ "$mem_available_kib" =~ ^[0-9]+$ ]]; then
+    # Keep kernel compilation conservative by default; high parallelism can trigger
+    # compiler crashes on memory-constrained hosts even when CPU count is high.
+    mem_jobs="$(( mem_available_kib / (1536 * 1024) ))"
+    if (( mem_jobs < 1 )); then
+      mem_jobs=1
+    fi
+    if (( mem_jobs < jobs )); then
+      jobs="$mem_jobs"
+    fi
+  fi
+  if (( jobs > 2 )); then
+    jobs=2
+  fi
+fi
+
+if ! [[ "$jobs" =~ ^[1-9][0-9]*$ ]]; then
+  echo "invalid --jobs value: $jobs" >&2
+  exit 1
+fi
+
 mkdir -p "$workdir" "$(dirname "$output")"
 workdir="$(cd "$workdir" && pwd)"
 output_dir="$(cd "$(dirname "$output")" && pwd)"
@@ -48,13 +75,14 @@ tar -xf linux.tar.xz -C linux-src --strip-components=1
 cd linux-src
 cp /work/kernel.config .config
 make olddefconfig
-make -j"$(nproc)" vmlinux
+make -j"$KERNEL_MAKE_JOBS" vmlinux
 cp vmlinux /work/out/vmlinux
 SCRIPT
 chmod +x "$container_script"
 mkdir -p "$workdir/out"
 
 docker run --rm \
+  -e KERNEL_MAKE_JOBS="$jobs" \
   -e KERNEL_SOURCE_URL="$source_url" \
   -e KERNEL_CONFIG_URL="$config_url" \
   -v "$workdir:/work" \