v0.5.5: fix real-hardware boot crash — shadow back in heap as first allocation

User's machine: boot reached 'rsnix: boot done — shell' then panicked
'len is 0, index 0' at the first cell write — CELLS (the vt grid) was
valid at vt::init and empty at the first shell paint, i.e. something
stomped the heap between vt::init and the shell banner.  The only
change in that window vs the working v0.5.3 was the v0.5.4 move of the
1.9 MB display shadow from the heap to the fb-aware page allocator:
on this machine's memory layout the page-allocator shadow's fill loop
(480K words) clobbered the heap's vt vectors.

- Shadow is again the *first* heap allocation, in gop::init before
  vt::init builds its grids (the v0.5.3 layout that provably boots on
  the user's hardware) — nothing else in the heap can collide with it.
- init_heap now splits the free list at the GOP framebuffer hole
  instead of subtracting its size from one block that still *spanned*
  the hole — no heap allocation of any size can land on the display.
- Kept the panic-proof try_reserve + fb-overlap rejection + no-shadow
  warning band; dropped the late init_shadow() call in main.rs.
- Verified on QEMU: shadow @ 0x1980020 origin=heap, allocated before
  vt::init, fb clean at 0x80000000; all 5 suites PASS; 0 warnings.

4 files changed, 188 insertions, 115 deletions

diff --git a/rsdos/src/main.rs b/rsdos/src/main.rs
index aa116e4..2717dff 100644
--- a/rsdos/src/main.rs
+++ b/rsdos/src/main.rs
@@ -162,7 +162,13 @@ pub unsafe extern "efiapi" fn efi_main(image_handle: Handle, system_table: *mut
     let (rows, cols) = rsnix::vt::size();
     rsnix::serial_println!("vt: terminal ready ({}x{})", rows, cols);
     let (fw, fh) = rsnix::gop::pixel_dims();
-    rsnix::gop::boot_marker(&alloc::format!("rsnix: gop {}x{} vt {}x{} ok", fw, fh, cols, rows));
+    rsnix::gop::boot_marker(&alloc::format!(
+        "rsnix: gop {}x{} vt {}x{} ok",
+        fw,
+        fh,
+        cols,
+        rows
+    ));
 
     // ExitBootServices — we now own the machine
     if unsafe { (bs.exit_boot_services)(image_handle, map_key) } != EFI_SUCCESS {
@@ -212,7 +218,6 @@ pub unsafe extern "efiapi" fn efi_main(image_handle: Handle, system_table: *mut
     } else {
         rsnix::serial_println!("pages: init FAILED");
     }
-    rsnix::gop::init_shadow();
     rsnix::gop::boot_marker("rsnix: shadow ok");
     if rsnix::memory::page_self_test() {
         rsnix::serial_println!("pages: self-test OK (alloc/free/runs)");
diff --git a/rsnix/src/gop.rs b/rsnix/src/gop.rs
index 90c24bf..d37468f 100644
--- a/rsnix/src/gop.rs
+++ b/rsnix/src/gop.rs
@@ -80,8 +80,7 @@ const STAGE_MAX: usize = 96;
 /// The last boot stage string (for the panic band).
 pub fn last_boot_stage() -> alloc::string::String {
     unsafe {
-        alloc::string::String::from_utf8_lossy(&LAST_BOOT_STAGE[..LAST_BOOT_STAGE_LEN])
-            .into_owned()
+        alloc::string::String::from_utf8_lossy(&LAST_BOOT_STAGE[..LAST_BOOT_STAGE_LEN]).into_owned()
     }
 }
 
@@ -210,7 +209,7 @@ pub fn init(gop: &mut GraphicsOutputProtocol) {
     let bgr = info.pixel_format == PIXEL_BGR;
     let _ = fg;
 
-    let fb = Framebuffer {
+    let fbf = Framebuffer {
         base,
         width,
         height,
@@ -221,14 +220,8 @@ pub fn init(gop: &mut GraphicsOutputProtocol) {
         bgr,
     };
 
-    // The RAM backbuffer is allocated *after* ExitBootServices by
-    // `init_shadow()` (main.rs) — via the fb-aware page allocator so it
-    // can never land on the framebuffer (see init_shadow).  Nothing is
-    // drawn between fb.clear() here and init_shadow(), so the blank
-    // shadow is in sync with the cleared display.
-
-    // Re-stash the post-SetMode region (base can move) for the page
-    // allocator, and log the authoritative geometry for diagnostics.
+    // Re-stash the post-SetMode region (base can move) for the
+    // allocators, and log the authoritative geometry for diagnostics.
     unsafe {
         FB_REGION_BASE = mode.framebuffer_base as usize;
         FB_REGION_SIZE = mode.framebuffer_size;
@@ -244,104 +237,65 @@ pub fn init(gop: &mut GraphicsOutputProtocol) {
         bgr
     );
 
-    fb.clear();
+    fbf.clear();
 
     unsafe {
-        FB = Some(fb);
-    }
-}
-
-/// Allocate the RAM backbuffer.  Must run *after*
-/// `memory::init_page_allocator` (which excludes the GOP framebuffer
-/// pages per-page), and before any text is painted.
-///
-/// The heap (pre-ExitBootServices) is excluded from the fb region only
-/// by a coarse overlap subtraction that still leaves one contiguous
-/// free block *spanning* the fb hole — a 1.9 MB shadow allocation could
-/// therefore land *on* the framebuffer on machines where firmware
-/// reports it as ConventionalMemory.  A shadow aliased over the display
-/// makes every scroll a 1.8 MB MMIO→MMIO memcpy, which can wedge a
-/// real uncached framebuffer (a stall, not a fault — hence no dump).
-/// The page allocator marks those pages used, so the shadow can never
-/// land there.  Heap allocation is kept only as a fallback, with an
-/// explicit overlap rejection.
-pub fn init_shadow() {
+        FB = Some(fbf);
+    }
+
+    // The RAM backbuffer is the *first* heap allocation: allocated here
+    // (pre-ExitBootServices, before vt::init builds its grids) so no
+    // other heap object can collide with it — the v0.5.3 layout that
+    // provably boots on real hardware.  The heap free list excludes the
+    // fb region (init_heap splits at the fb hole) and we additionally
+    // reject any range overlapping the fb, so the shadow can never
+    // alias the display (an aliased shadow turns every scroll into a
+    // 1.8 MB MMIO→MMIO memcpy on an uncached real fb — a wedge).
+    // Allocation failure degrades to no-shadow mode, never panics.
     unsafe {
-        let Some(fb) = fb().as_ref() else {
-            return;
-        };
-        let words = (fb.pitch * fb.height) / 4;
-        if words == 0 {
-            return;
-        }
-        let bytes = words * 4;
-        let pages = bytes.div_ceil(crate::memory::PAGE_SIZE);
-        let mut origin = "none";
-
-        // Primary: fb-aware page allocator (fb pages already marked
-        // used by init_page_allocator).  Defensively refuse the range if
-        // it ever overlaps the fb region anyway.
-        if let Some(p) = crate::memory::alloc_pages(pages) {
-            let overlaps = FB_REGION_SIZE > 0
-                && p < FB_REGION_BASE + FB_REGION_SIZE
-                && p + bytes > FB_REGION_BASE;
-            if !overlaps {
-                SHADOW = p as *mut u32;
-                SHADOW_WORDS = words;
-                origin = "page-alloc";
-                for i in 0..words {
-                    *SHADOW.add(i) = fb.bg;
+        if let Some(fbinfo) = fb().as_ref() {
+            let words = (fbinfo.pitch * fbinfo.height) / 4;
+            if words > 0 {
+                let bytes = words * 4;
+                #[allow(clippy::slow_vector_initialization)] // deliberate: try_reserve must not panic
+                let mut v: alloc::vec::Vec<u32> = alloc::vec::Vec::new();
+                if v.try_reserve_exact(words).is_ok() {
+                    v.resize(words, 0); // can't fail after the reserve
+                    let p = v.as_ptr() as usize;
+                    let overlaps = FB_REGION_SIZE > 0
+                        && p < FB_REGION_BASE + FB_REGION_SIZE
+                        && p + bytes > FB_REGION_BASE;
+                    if !overlaps {
+                        SHADOW = v.as_ptr() as *mut u32;
+                        SHADOW_WORDS = words;
+                        for i in 0..words {
+                            *SHADOW.add(i) = fbinfo.bg;
+                        }
+                        core::mem::forget(v); // shadow owns the memory now
+                    }
                 }
-            }
-        }
-        if origin == "none" {
-            // Fallback: heap — must never panic here: an OOM would halt
-            // the kernel before the shell banner, a blank screen on real
-            // hardware (the old `vec![0; words]` could abort).  On any
-            // failure we degrade to no-shadow mode instead.
-            #[allow(clippy::slow_vector_initialization)] // deliberate: try_reserve must not panic
-            let mut v: alloc::vec::Vec<u32> = alloc::vec::Vec::new();
-            if v.try_reserve_exact(words).is_ok() {
-                v.resize(words, 0); // can't fail after the reserve
-                let p = v.as_ptr() as usize;
-                let overlaps = FB_REGION_SIZE > 0
-                    && p < FB_REGION_BASE + FB_REGION_SIZE
-                    && p + bytes > FB_REGION_BASE;
-                if !overlaps {
-                    SHADOW = v.as_ptr() as *mut u32;
-                    SHADOW_WORDS = words;
-                    origin = "heap";
-                    core::mem::forget(v); // shadow owns the memory now
+                let (rbase, rsize) = (FB_REGION_BASE, FB_REGION_SIZE);
+                let (shadow, swords) = (SHADOW as usize, SHADOW_WORDS);
+                crate::serial_println!(
+                    "gop: shadow @ {:#x} words={} fb={:#x}..{:#x} origin=heap",
+                    shadow,
+                    swords,
+                    rbase,
+                    rbase + rsize,
+                );
+                if SHADOW.is_null() {
+                    let msg =
+                        "gop: WARNING — shadow rejected (fb overlap); no-shadow fallback";
+                    crate::serial_println!("{}", msg);
+                    let lines: alloc::vec::Vec<&str> = msg
+                        .as_bytes()
+                        .chunks(100)
+                        .map(|c| core::str::from_utf8(c).unwrap_or("?"))
+                        .collect();
+                    dump_lines(&lines);
                 }
             }
         }
-        let (rbase, rsize) = (FB_REGION_BASE, FB_REGION_SIZE);
-        let (shadow, swords) = (SHADOW as usize, SHADOW_WORDS);
-        crate::serial_println!(
-            "gop: shadow @ {:#x} words={} fb={:#x}..{:#x} origin={}",
-            shadow,
-            swords,
-            rbase,
-            rbase + rsize,
-            origin
-        );
-        // Real hardware has no serial console: surface a degraded shadow
-        // (heap fallback or rejected allocation) as a visible warning
-        // band so a boot on hardware shows it on the screen.
-        if origin != "page-alloc" {
-            let msg = if SHADOW.is_null() {
-                "gop: WARNING — shadow allocation rejected (fb overlap); no-shadow fallback"
-            } else {
-                "gop: WARNING — shadow from heap (page allocator unavailable)"
-            };
-            crate::serial_println!("{}", msg);
-            let lines: alloc::vec::Vec<&str> = msg
-                .as_bytes()
-                .chunks(100)
-                .map(|c| core::str::from_utf8(c).unwrap_or("?"))
-                .collect();
-            dump_lines(&lines);
-        }
     }
 }
 
diff --git a/rsnix/src/memory.rs b/rsnix/src/memory.rs
index a947c53..605125a 100644
--- a/rsnix/src/memory.rs
+++ b/rsnix/src/memory.rs
@@ -366,18 +366,33 @@ fn init_heap() {
             if d.kind == MEMORY_TYPE_CONVENTIONAL {
                 let s = d.physical_start as usize;
                 let e = s + d.number_of_pages as usize * 4096;
-                // Subtract any overlap with the framebuffer region.
-                let (cs, ce) = match fb {
-                    Some((b, sz)) if e > b && s < b + sz => (s.max(b), e.min(b + sz)),
-                    _ => (e, s), // no overlap → empty range
-                };
-                let mut sz = e - s;
-                if ce > cs {
-                    sz -= ce - cs;
+                // Split at the framebuffer hole so the free list NEVER
+                // contains fb pages: a coarse size subtraction leaves one
+                // block *spanning* the hole, letting a large allocation
+                // (e.g. the 1.9 MB display shadow) straddle the display.
+                let mut lo = s;
+                if let Some((b, sz)) = fb
+                    && e > b
+                    && s < b + sz
+                {
+                    let h0 = b.max(s);
+                    let h1 = (b + sz).min(e);
+                    if h0 > lo {
+                        // Segment before the hole.
+                        let seg = h0 - lo;
+                        if seg > best_size {
+                            best_start = lo;
+                            best_size = seg;
+                        }
+                    }
+                    lo = h1;
                 }
-                if sz > best_size {
-                    best_start = s;
-                    best_size = sz;
+                if e > lo {
+                    let seg = e - lo;
+                    if seg > best_size {
+                        best_start = lo;
+                        best_size = seg;
+                    }
                 }
             }
         }
diff --git a/scripts/build-image-release.sh b/scripts/build-image-release.sh
new file mode 100755
index 0000000..32f8f91
--- /dev/null
+++ b/scripts/build-image-release.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+#
+# scripts/build-image.sh — assemble a bootable rs-dos disk image (UEFI/GPT)
+#
+# Layout:
+#   Partition 1: ESP (FAT32) — rsboot bootloader + kernel
+#
+# Output:
+#   rs-dos.img (or custom path) — bootable raw disk image for UEFI
+#
+# Usage:
+#   ./scripts/build-image.sh [output.img]
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_DIR"
+
+BUILD_DIR="$PROJECT_DIR/build"
+ESP_DIR="$PROJECT_DIR/esp"
+
+IMAGE="${1:-$PROJECT_DIR/rs-dos.img}"
+TARGET=x86_64-unknown-uefi
+PROFILE=release
+OUT_DIR="target/${TARGET}/${PROFILE}"
+
+BOOTLOADER="$BUILD_DIR/bootloader/BOOTX64.EFI"
+KERNEL="$OUT_DIR/rsdos.efi"
+BZIMAGE="$ESP_DIR/bzImage"
+INITRD="$ESP_DIR/initramfs.cpio.gz"
+BOOT_EFI="$ESP_DIR/EFI/BOOT/BOOTX64.EFI"
+
+ESP_START=2048 # 1 MiB offset (standard alignment)
+ESP_SIZE_MB=64
+
+IMAGE_SIZE_MB=$((ESP_SIZE_MB + 2)) # ESP + GPT gap + backup
+
+# ---- checks ----
+for cmd in sfdisk mkfs.vfat mcopy truncate dd; do
+        if ! command -v "$cmd" &>/dev/null; then
+                echo "Error: $cmd not found"
+                exit 1
+        fi
+done
+
+# ---- build kernel ----
+echo "[1/4] Building kernel..."
+cargo build --release --package rsdos --target x86_64-unknown-uefi ${CARGO_FLAGS:-}
+
+# ---- build bootloader ----
+echo "[2/4] Building bootloader..."
+if [ ! -f "$BOOTLOADER" ]; then
+        "$SCRIPT_DIR/build-bootloader.sh"
+fi
+
+# ---- assemble ESP ----
+echo "[3/4] Assembling ESP..."
+mkdir -p "$ESP_DIR/EFI/BOOT"
+cp "$KERNEL" "$BZIMAGE"
+cp "$BOOTLOADER" "$BOOT_EFI"
+if [ ! -f "$INITRD" ]; then
+        printf '' | gzip >"$INITRD"
+fi
+
+# ---- create disk image ----
+echo "[4/4] Writing disk image..."
+rm -f "$IMAGE"
+truncate -s "${IMAGE_SIZE_MB}M" "$IMAGE"
+
+# GPT partition table: single EFI System partition
+sfdisk --quiet "$IMAGE" <<EOF
+label: gpt
+type=U, start=$ESP_START, size=+
+EOF
+
+# Build FAT32 image with ESP contents
+ESP_IMG=$(mktemp)
+truncate -s "${ESP_SIZE_MB}M" "$ESP_IMG"
+mkfs.vfat -F 32 -n "RS-DOS" "$ESP_IMG" >/dev/null 2>&1
+
+# Copy files into FAT
+mmd -i "$ESP_IMG" ::/EFI 2>/dev/null || true
+mmd -i "$ESP_IMG" ::/EFI/BOOT 2>/dev/null || true
+mcopy -i "$ESP_IMG" "$BOOT_EFI" ::/EFI/BOOT/BOOTX64.EFI
+mcopy -i "$ESP_IMG" "$BZIMAGE" ::/bzImage 2>/dev/null || true
+mcopy -i "$ESP_IMG" "$INITRD" ::/initramfs.cpio.gz 2>/dev/null || true
+
+# Inject FAT into image at partition offset
+dd if="$ESP_IMG" of="$IMAGE" bs=512 seek="$ESP_START" conv=notrunc 2>/dev/null
+rm -f "$ESP_IMG"
+
+echo ""
+echo "=== Done: $IMAGE ==="
+ls -lh "$IMAGE"
+echo ""
+echo "Boot with:  ./scripts/boot-image.sh"
+echo "USB:        sudo dd if=$IMAGE of=/dev/sdX bs=4M status=progress"