From b199b17e3a55ecc951d6f26848f5e87fff95060c Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Tue, 15 Sep 2026 20:25:37 -0400
Subject: [PATCH 1/3] feat(guest-image): derive the guest rootfs from the
 pinned agent OCI image

The guest userland was a second nix evaluation of the agent image's
expressions under a different nixpkgs pin, so the microVM guest and the
published container could drift silently.

The rootfs now unpacks the published image itself: per-layer
fixed-output fetches keyed by the locked descriptor digests, applied in
manifest order with each layer's whiteouts resolved against the lower
layers before its own content lands. A boot layer is overlaid on top
and wins every conflict: guestd as /sbin/init, modprobe, /lib/modules
from the root-pinned kernel, and a writable /etc/resolv.conf.

Two build-time gates keep it honest. The eval re-checks the lock's
shape, and the userland contract is verified on the assembled tree by
resolving every path component inside it -- the way the kernel will
after switch_root -- so a missing /bin/sh breaks the build instead of
shipping a guest that cannot arm egress.

Refs RIG-3787

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 guest-image/default.nix | 346 ++++++++++++++++++++++++----------------
 guest-image/moon.yml    |  34 ++--
 2 files changed, 223 insertions(+), 157 deletions(-)

diff --git a/guest-image/default.nix b/guest-image/default.nix
index e06bb6ac1..db2011386 100644
--- a/guest-image/default.nix
+++ b/guest-image/default.nix
@@ -1,19 +1,11 @@
 # The Compass microVM guest image: the three nix attrs V2a's cloud-hypervisor
-# runtime consumes to boot a session guest — a direct-boot kernel, a packed erofs
-# root filesystem, and a module initramfs. It reuses agent-image/'s toolchain
-# closure, so the guest ships the same agent runtime as the container path — one
-# closure, two artifact shapes (OCI layers there, a bootable erofs image here).
-#
-# Pin divergence (a parity note V2a honors): `agent-image/toolchain.nix` is
-# called here with ROOT's `pkgs` (the root devenv.lock), NOT agent-image's own
-# pin, so the whole rootfs closure resolves from the root pin. Deliberate: the
-# guest-image moon gate's `inputs` track the root devenv.lock, so the gate
-# reschedules on a root-pin move. agent-image's OCI build keeps its own pin; the
-# two closures are the same shape through two nixpkgs revisions.
+# runtime consumes to boot a session guest. The rootfs userland IS the published
+# agent OCI image unpacked, fetched fixed-output against `agent-oci.lock`, so
+# guest/container drift is not expressible. Only the boot layer is added on top.
 let
   # The root devenv.lock-pinned nixpkgs, resolved as the other plain nix gates do
-  # (read the lock, fetch that rev, import it). This is the "root's pkgs" the pin
-  # divergence turns on.
+  # (read the lock, fetch that rev, import it). Supplies the BOOT layer only: the
+  # agent userland comes from the OCI image, not from this pin.
   lock = builtins.fromJSON (builtins.readFile ../devenv.lock);
   node = lock.nodes.nixpkgs.locked;
   nixpkgsSrc = builtins.fetchTarball {
@@ -23,24 +15,65 @@ let
   pkgs = import nixpkgsSrc { };
   lib = pkgs.lib;
 
-  # The SAME bundled agent entrypoint and toolchain closure the agent image ships,
-  # imported unchanged and fed root's `pkgs`. Their own relative imports resolve
-  # against agent-image/, not this file, so importing them here is transparent.
-  compassAgent = import ../agent-image/entrypoint.nix { inherit pkgs lib; };
-  toolchain = import ../agent-image/toolchain.nix { inherit pkgs compassAgent; };
-
-  # The real guest init (T2, go/cmd/compass-guestd): the guest-side supervisor —
-  # mounts the API filesystems, brings networking up (in-process DHCP), mounts the
-  # virtio-fs workspace, serves the vsock Health handshake as guest PID 1.
-  # buildGoModule of the backend module; static (CGO_ENABLED=0) so it needs no
-  # in-guest libc a switch_root'd PID 1 cannot assume.
-  #   * src is renamed off `go` so buildGoModule's $GOPATH unpack does not collide
-  #     ("go.mod file not found").
-  #   * proxyVendor is required: wails/secretspec //go:embed patterns reference
-  #     darwin/windows-only files a vendor-tree build would fail on; proxyVendor
-  #     touches only the packages actually compiled for linux/amd64.
-  #   * vendorHash pins the fetched module set; recompute with `lib.fakeHash` on a
-  #     go.mod/go.sum move.
+  # The pinned agent image, written only by tools/guest-image/pin-agent-image.ts.
+  # The shape is re-checked HERE as well as in the pin tool: the tool guards the
+  # write path, this guards the eval, and a hand-edited lock has to defeat both.
+  agentLock = builtins.fromJSON (builtins.readFile ./agent-oci.lock);
+
+  # Split registry host from repository path: the lock stores the full
+  # reference, the v2 API needs the two separately.
+  agentRegistry = "ghcr.io";
+  agentPath = "rigelbuild/compass-agent";
+  agentRepo = "${agentRegistry}/${agentPath}";
+
+  # A digest is only a pin if it is a real sha256. `match` returns null on any
+  # deviation, so a truncated or hex-invalid digest fails eval instead of
+  # reaching fetchurl as an unenforceable hash.
+  isSha256 = s: builtins.isString s && builtins.match "sha256:[0-9a-f]{64}" s != null;
+
+  # Fail at eval, naming the field, rather than letting a malformed lock surface
+  # as an opaque fetch or hash error deep in the build.
+  checkedLock =
+    let
+      bad =
+        if agentLock.repo or null != agentRepo then
+          "repo must be ${agentRepo}, got ${toString (agentLock.repo or "<missing>")}"
+        else if builtins.match "git-[0-9a-f]{12}" (agentLock.tag or "") == null then
+          "tag must match git-<sha12>, got ${toString (agentLock.tag or "<missing>")}"
+        else if !isSha256 (agentLock.digest or "") then
+          "digest must be sha256:<64 hex>, got ${toString (agentLock.digest or "<missing>")}"
+        else if !builtins.isList (agentLock.layers or null) || agentLock.layers == [ ] then
+          "layers must be a non-empty list"
+        else if !builtins.all isSha256 agentLock.layers then
+          "every layer must be sha256:<64 hex>"
+        else
+          null;
+    in
+    if bad == null then
+      agentLock
+    else
+      throw "guest-image: agent-oci.lock is not a valid pin: ${bad}. Rewrite it with `bun tools/guest-image/pin-agent-image.ts --relock`, never by hand.";
+
+  # Each layer blob, fetched fixed-output against its descriptor digest -- the
+  # registry's own content address, where one archive's narHash would track
+  # skopeo's byte layout. The bearer is GHCR's literal anonymous public-read
+  # token, not a credential: an unauthenticated blob GET 401s demanding one.
+  agentLayers = map (
+    digest:
+    pkgs.fetchurl {
+      url = "https://${agentRegistry}/v2/${agentPath}/blobs/${digest}";
+      curlOptsList = [
+        "-H"
+        "Authorization: Bearer QQ=="
+      ];
+      hash = digest;
+    }
+  ) checkedLock.layers;
+
+  # The guest-side supervisor, running as guest PID 1: mounts the API
+  # filesystems, brings networking up, serves the vsock Health handshake. Static
+  # since a switch_root'd PID 1 cannot assume a libc; src is renamed off `go` so
+  # buildGoModule's unpack cannot collide.
   guestd = pkgs.buildGoModule {
     pname = "compass-guestd";
     version = "0-v2a";
@@ -56,8 +89,8 @@ let
       "-s"
       "-w"
     ];
-    # This slice only packages the binary; guestd's logic is unit-tested under the
-    # backend gate and the real boot is T4's KVM-gated proof.
+    # This derivation only packages the binary; guestd's logic is unit-tested
+    # under the backend gate and the real boot is proved by the KVM-gated test.
     doCheck = false;
   };
 
@@ -76,16 +109,10 @@ let
   # the separate `modules` output, consumed by both the rootfs and the initrd.
   kernel = pkgs.linuxPackages.kernel;
 
-  # The module set the initramfs loads before switch_root, via kmod modprobe from
-  # the shrunk closure, because the guest has no udev/systemd-modules-load to
-  # autoload post-switch_root (guestd IS init). These loads persist across
-  # switch_root, so every driver the guest needs is bound by the time guestd
-  # starts: the boot-critical set mounts the root overlay (virtio transport +
-  # block, erofs, overlayfs); the runtime set covers guestd's net/workspace/vsock
-  # and af_packet (its in-process DHCP client's raw socket — without it the lease
-  # fails EAFNOSUPPORT). Every one is `=m` in the pinned kernel; the check below
-  # fails the build on a pin move that flips one to `=y` or drops it, rather than
-  # shipping a guest that boots but cannot reach network, workspace, or host.
+  # The initramfs modprobes these before switch_root: nothing autoloads
+  # afterwards (guestd IS init) and the loads persist across it. af_packet is
+  # load-bearing -- guestd's DHCP raw socket fails EAFNOSUPPORT without it.
+  # The check below breaks the build if a pin move flips one to `=y`.
   bootModules = [
     "virtio_pci"
     "virtio_blk"
@@ -121,7 +148,7 @@ let
     ${lib.concatMapStringsSep "\n" (sym: ''
       if ! grep -qx '${sym}=m' ${kernel.configfile}; then
         echo "guest-image: BUILD-BREAK — kernel .config lacks '${sym}=m'." >&2
-        echo "  The initramfs assumes ${sym} is a loadable module (record §(a))." >&2
+        echo "  The initramfs assumes ${sym} is a loadable module." >&2
         echo "  A kernel-pin move flipped it to =y or dropped it; the initrd would" >&2
         echo "  not boot. Re-audit guest-image/default.nix bootModules against the" >&2
         echo "  new kernel before proceeding." >&2
@@ -156,7 +183,7 @@ let
     fail() {
       echo "compass-guest-initrd: $1" >&2
       # Give the console a moment to flush before PID 1 exits and the kernel
-      # panics, so the cause is visible in T4's captured serial log.
+      # panics, so the cause is visible in the captured serial log.
       exec sh -c 'echo "compass-guest-initrd: boot aborted"; exit 1'
     }
 
@@ -183,13 +210,10 @@ let
       -o lowerdir=/mnt/lower,upperdir=/mnt/rw/upper,workdir=/mnt/rw/work \
       /mnt/root || fail "mount whole-root overlay failed"
 
-    # No pre-switch_root existence check on /mnt/root/sbin/init: it is an
-    # ABSOLUTE store symlink (-> /nix/store/…-compass-guestd/bin/compass-guestd),
-    # so `test -x` would follow the symlink and resolve its absolute target
-    # against the CURRENT process root — still the initramfs, where guestd is
-    # absent — and fail-close on every correct image. switch_root below is the
-    # gate: it chroots into /mnt/root first, so /sbin/init resolves in the
-    # overlay where guestd exists, and it is itself `|| fail`-closed.
+    # No pre-switch_root check on /mnt/root/sbin/init: it is an ABSOLUTE store
+    # symlink, so `test -x` resolves it against the CURRENT root (still the
+    # initramfs, where guestd is absent) and fail-closes on every correct image.
+    # switch_root chroots first, and is itself `|| fail`-closed.
 
     # Hand off to the real guest init. switch_root tears down the initramfs and
     # execs /sbin/init as PID 1 in the overlay root.
@@ -215,39 +239,12 @@ let
     ];
   };
 
-  # The rootfs contents tree: a store-path symlink farm + a real writable
-  # resolv.conf + the kernel's full /lib/modules tree; the erofs step below packs
-  # its store closure into the bootable image. Assembled by hand (not `buildEnv`)
-  # so resolv.conf lands as a real file and the closure references stay explicit.
-  rootfsTree = pkgs.runCommand "compass-guest-rootfs-tree" { } ''
-    mkdir -p $out/bin $out/sbin $out/etc $out/lib
-
-    # The agent-image toolchain closure: its /bin and /etc, symlinked in. These
-    # point into the store closure the packed image ships — the same
-    # relocated-/etc + store-closure shape nix2container gives the OCI artifact.
-    for f in ${toolchain}/bin/*; do
-      ln -s "$f" "$out/bin/$(basename "$f")"
-    done
-    if [ -d ${toolchain}/etc ]; then
-      cp -a ${toolchain}/etc/. $out/etc/
-      # cp -a preserves the store's read-only dir/file modes; make the staged
-      # /etc writable so the resolv.conf install below lands cleanly.
-      chmod -R u+w $out/etc
-    fi
-
-    # The egress prerequisites (microvm-runner.md:446-449) plus /bin/sh. Already
-    # present via the toolchain closure above (agent-image/toolchain.nix:144-147),
-    # linked again here explicitly so the guest's contract does not depend on the
-    # toolchain's internal package list. `ln -sf` because the toolchain loop may
-    # already have created these names. /bin/sh is load-bearing under always-arm
-    # (record §(e)): every microVM Start spawns `/bin/sh -c <script>` to arm
-    # egress, so a missing /bin/sh is a total-backend outage, not egress-only.
-    # bashInteractive is already in the rootfs closure via the toolchain, so the
-    # link adds zero closure.
-    ln -sf ${pkgs.nftables}/bin/nft $out/bin/nft
-    ln -sf ${pkgs.getent}/bin/getent $out/bin/getent
-    ln -sf ${pkgs.gawk}/bin/awk $out/bin/awk
-    ln -sf ${pkgs.bashInteractive}/bin/sh $out/bin/sh
+  # The boot layer: everything the guest needs that the agent OCI image does not
+  # carry. Kept as its own derivation so the erofs step can lay it over the
+  # unpacked image and so its store closure is computed separately — the agent
+  # image ships its own /nix/store, this does not.
+  bootLayer = pkgs.runCommand "compass-guest-boot-layer" { } ''
+    mkdir -p $out/sbin $out/bin $out/etc $out/lib
 
     # The real guest init, reachable both as /sbin/init and by name on PATH.
     ln -s ${guestd}/bin/compass-guestd $out/sbin/init
@@ -257,42 +254,34 @@ let
     # the guest's net bringup can rewrite it through the tmpfs overlay at boot.
     install -Dm644 ${resolvConf} $out/etc/resolv.conf
 
-    # The kernel's FULL /lib/modules tree (record §(a)), depmod metadata and
-    # all: guestd's virtio_net/virtiofs/vsock transport and V3's in-guest
-    # netfilter arm resolve their modules from here. Already in the closure (the
-    # kernel is substituted) — zero extra build. A symlink into the modules
-    # output; the erofs packing below dereferences it into the image.
+    # The kernel's FULL /lib/modules tree, depmod metadata and all: guestd's
+    # virtio_net/virtiofs/vsock transport and the in-guest netfilter arm resolve
+    # their modules from here. Already in the closure (the kernel is
+    # substituted), so this costs no extra build.
     ln -s ${kernel.modules}/lib/modules $out/lib/modules
 
-    # The kernel module-autoload usermode helper. The guest has no
-    # udev/systemd-modules-load (guestd is PID 1, §(d)), so post-switch_root the
-    # ONLY on-demand module loader is the kernel's request_module() path: when
-    # in-kernel code needs an unloaded module it execs the binary named by
-    # /proc/sys/kernel/modprobe (CONFIG_MODPROBE_PATH is unset in the pinned
-    # kernel, so this defaults to /sbin/modprobe). Nothing staged that binary,
-    # so request_module was a silent no-op and the /lib/modules tree above was
-    # necessary but NOT sufficient (the false OQ-3 assumption, RIG-3028): the
-    # first `nft` of the egress arm opened a NETLINK_NETFILTER socket, the
-    # kernel fired request_module("net-pf-16-proto-12") -> nfnetlink, found no
-    # helper, and nf_tables never registered -> EPROTONOSUPPORT (mnl.c:66), so
-    # §(e) always-arm failed EVERY microVM Start. Staging kmod's modprobe here
-    # (NOT busybox's: modules are .ko.xz and CONFIG_MODULE_DECOMPRESS is unset,
-    # so the helper must decompress in userspace — the same reason the initrd
-    # uses kmod at line 244) closes that: any module the guest asks for
-    # autoloads on demand from the shipped tree via its depmod alias/dep
-    # metadata. This is the general mechanism (not a fixed preload), so it also
-    # covers egress rulesets beyond the base one — a future user-defined rule
-    # pulling a new nft expression module autoloads with no guest-image change.
-    # The ${pkgs.kmod} reference pulls kmod into the rootfs closure; the erofs
-    # packing below materializes it into the image. Plain `ln -s` (no -f): no
-    # prior modprobe name exists to overwrite, matching /sbin/init above.
+    # The kernel's request_module() helper: without the binary named by
+    # /proc/sys/kernel/modprobe it silently no-ops, making the module tree above
+    # necessary but NOT sufficient -- nf_tables never registered and every
+    # microVM Start failed to arm egress. kmod's: modules are .ko.xz.
     ln -s ${pkgs.kmod}/bin/modprobe $out/sbin/modprobe
   '';
 
-  # The store closure the rootfs symlink farm points into, materialized into the
-  # erofs image so it is self-contained and bootable (/nix/store lives in the
-  # image, made writable by the overlay upper).
-  rootfsClosure = pkgs.closureInfo { rootPaths = [ rootfsTree ]; };
+  # The boot layer's store closure. The agent image carries its own store paths
+  # inside its layers, so only these need materializing alongside.
+  bootClosure = pkgs.closureInfo { rootPaths = [ bootLayer ]; };
+
+  # The userland contract the Runner and guestd depend on, asserted at
+  # derivation time against the ASSEMBLED tree: an agent-image change that
+  # dropped one fails the build instead of booting a guest that cannot arm
+  # egress (/bin/sh missing is a total backend outage) or run the agent.
+  userlandContract = [
+    "bin/sh"
+    "bin/nft"
+    "bin/getent"
+    "bin/awk"
+    "bin/compass-agent"
+  ];
 
   # A fixed filesystem UUID for the erofs image. mkfs.erofs otherwise stamps a
   # random UUID, which would defeat bit-reproducibility; pinning it (with -T0 and
@@ -305,11 +294,10 @@ in
   # ${compass-guest-kernel}/bzImage.
   compass-guest-kernel = kernel;
 
-  # The packed rootfs: a reproducible read-only erofs image (the boot disk
-  # cloud-hypervisor attaches on virtio-blk). $out IS the image file, so the CI
-  # leg's COMPASS_TEST_GUEST_ROOTFS export points straight at it. Deterministic
-  # flags (-T0, --all-root, -U <fixed>); the build packs twice and `cmp`s the two
-  # at build time so any nondeterminism fails the gate, not V5 hash-verify.
+  # The packed rootfs: a reproducible read-only erofs image, the boot disk
+  # cloud-hypervisor attaches on virtio-blk. $out IS the image file, so the CI
+  # leg's COMPASS_TEST_GUEST_ROOTFS points straight at it. The build packs twice
+  # and `cmp`s the two, so nondeterminism fails here rather than at hash-verify.
   compass-guest-rootfs =
     pkgs.runCommand "compass-guest-rootfs.erofs"
       {
@@ -321,26 +309,114 @@ in
       ''
         root=$(mktemp -d)
 
-        # Stage the rootfs tree (its store-path symlinks preserved) and the store
-        # closure they resolve into, so the image is self-contained.
-        cp -a ${rootfsTree}/. "$root/"
+        # Whiteouts in a layer hide only the layers BELOW it, so each layer's
+        # markers are applied to the accreting tree before its own content is
+        # extracted -- an opaque marker applied afterwards would delete the
+        # sibling files that same layer adds.
+        for layer in ${lib.concatStringsSep " " agentLayers}; do
+          tar -tzf "$layer" | sed 's|^\./||' | { grep '\.wh\.' || true; } | while read -r marker; do
+            dir=$(dirname "$marker")
+            base=$(basename "$marker")
+            if [ "$base" = ".wh..wh..opq" ]; then
+              find "$root/$dir" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+            else
+              rm -rf "$root/$dir/''${base#.wh.}"
+            fi
+          done
+
+          # --overwrite and the chmod are load-bearing: nix2container layers carry
+          # /nix/store paths with the store's read-only modes, so without them tar
+          # fails "File exists" on a duplicated entry and "Permission denied"
+          # writing into an already-extracted r-xr-xr-x directory.
+          tar -xzf "$layer" -C "$root" --overwrite --no-same-permissions \
+            --exclude='.wh.*' --exclude='*/.wh.*'
+          chmod -R u+w "$root"
+        done
+
         # cp -a preserves the store's read-only dir modes; make the staged tree
-        # writable so the /nix/store population and mkfs.erofs's own metadata
-        # walk can proceed (--all-root normalizes ownership; -T0 normalizes
-        # timestamps, so these staging perms never reach the packed image).
+        # writable so the boot layer and /nix/store population can proceed
+        # (--all-root normalizes ownership; -T0 normalizes timestamps, so these
+        # staging perms never reach the packed image).
+        chmod -R u+w "$root"
+
+        # Lay the boot layer over the unpacked image. It wins on any path
+        # conflict: /sbin/init, /sbin/modprobe, /lib/modules and the writable
+        # /etc/resolv.conf are the guest's, not the container's.
+        cp -a --remove-destination ${bootLayer}/. "$root/"
         chmod -R u+w "$root"
+
+        # The boot layer's own store closure. The agent layers already carry
+        # their /nix/store paths, so only these are added.
         mkdir -p "$root/nix/store"
-        for p in $(cat ${rootfsClosure}/store-paths); do
+        for p in $(cat ${bootClosure}/store-paths); do
           cp -a "$p" "$root/nix/store/"
         done
+        chmod -R u+w "$root"
+
+        # The userland contract, checked on the ASSEMBLED tree. EVERY component
+        # resolves inside $root, as the kernel will after switch_root: following
+        # only the final symlink resolves an intermediate /bin -> /nix/store/...
+        # against the BUILDER's store, passing an image with no /bin/sh at all.
+        for p in ${lib.concatStringsSep " " userlandContract}; do
+          resolved=""
+          rest="/$p"
+          hops=0
+          while [ -n "$rest" ]; do
+            hops=$((hops + 1))
+            if [ "$hops" -gt 40 ]; then
+              echo "guest-image: BUILD-BREAK — /$p is a symlink loop in the image." >&2
+              exit 1
+            fi
+            comp=''${rest#/}
+            comp=''${comp%%/*}
+            tail=''${rest#/"$comp"}
+            case "$comp" in
+              . | "")
+                rest="$tail"
+                continue
+                ;;
+              ..)
+                resolved=$(dirname "$resolved")
+                [ "$resolved" = "/" ] || [ "$resolved" = "." ] && resolved=""
+                rest="$tail"
+                continue
+                ;;
+            esac
+            resolved="$resolved/$comp"
+            if [ -L "$root$resolved" ]; then
+              link=$(readlink "$root$resolved")
+              case "$link" in
+                /*)
+                  resolved=""
+                  rest="$link$tail"
+                  ;;
+                *)
+                  resolved=$(dirname "$resolved")
+                  [ "$resolved" = "/" ] || [ "$resolved" = "." ] && resolved=""
+                  rest="/$link$tail"
+                  ;;
+              esac
+            else
+              rest="$tail"
+            fi
+          done
+          target="$resolved"
+          if [ ! -e "$root$target" ]; then
+            echo "guest-image: BUILD-BREAK — /$p does not resolve inside the rootfs." >&2
+            echo "  It resolves to $target, which the image does not carry." >&2
+            echo "  The guest userland comes from the pinned agent image" >&2
+            echo "  (${checkedLock.repo}@${checkedLock.digest})." >&2
+            echo "  Either that image stopped shipping it, or a layer failed to" >&2
+            echo "  unpack. /bin/sh missing is a TOTAL backend outage: every" >&2
+            echo "  microVM Start shells out to arm egress." >&2
+            exit 1
+          fi
+        done
 
-        # Pack twice with identical deterministic flags and assert bit-equality.
-        # --workers=1 removes multi-threaded job-queue ordering as a determinism
-        # variable; the tree is small, so the cost is negligible. Scope: this is
-        # an intra-run smoke check only — it cannot catch cross-machine/-time/-tool
-        # drift. The real cross-build reproducibility guarantee is nix's
-        # input-addressing plus the stable -U/-T0/--all-root flags (verified with
-        # `nix build --rebuild`); V5's preflight hash-verify is the load-bearing gate.
+        # Pack twice with identical flags and assert bit-equality; --workers=1
+        # removes job-queue ordering as a variable. Intra-run smoke check only:
+        # cross-machine drift is caught by nix's input-addressing plus the
+        # stable flags, and by the preflight hash-verify.
         flags="-T0 --all-root -U ${rootfsUUID} --workers=1"
         mkfs.erofs $flags img1.erofs "$root"
         mkfs.erofs $flags img2.erofs "$root"
diff --git a/guest-image/moon.yml b/guest-image/moon.yml
index b7393df95..c7dffbb5f 100644
--- a/guest-image/moon.yml
+++ b/guest-image/moon.yml
@@ -48,41 +48,31 @@ tasks:
     options:
       cache: false
       runInCI: true
-    # The rootfs build closure. The rootfs imports agent-image/toolchain.nix +
-    # entrypoint.nix (fed ROOT's pkgs), which resolve the vendored bun through
-    # tools/toolchain/toolchain-tools.nix + versions/**, bundle the compass-agent
-    # (packages/compass-agent/** + package.json + bun.lock), and pin the whole
-    # closure to the root devenv.lock — so each of those is a first-class input:
-    # a change to any reschedules this build under per-PR affected detection. A
-    # glob that misses one silently skips a build that should have run and leaves
-    # the E4 cache stale (the same closure-approximation risk the record calls
-    # out, § E3). A leading `/` is workspace-root-relative (the convention
-    # agent-image/moon.yml:58-63 uses); the bare glob is this project's own tree.
+    # The rootfs build closure. The agent userland now comes from the pinned
+    # OCI image, not a local nix build of the agent sources, so the agent-side
+    # input is `agent-oci.lock` alone (covered by the `**/*` glob below): a
+    # change to the agent reaches this build only by the pin moving, and a pin
+    # move IS a change to that file. The remaining entries are the BOOT
+    # layer's closure. A glob that misses one silently skips a build that
+    # should have run and leaves the E4 cache stale (§ E3). A leading `/` is
+    # workspace-root-relative; the bare glob is this project's own tree.
     inputs:
       - '**/*'
-      - '/agent-image/toolchain.nix'
-      - '/agent-image/entrypoint.nix'
-      - '/tools/toolchain/toolchain-tools.nix'
-      - '/tools/toolchain/versions/**'
       # The microVM boot leg (ci.yml `microvm` job) realizes this VMM-env
       # (cloud-hypervisor/virtiofsd/passt) to boot the guest image this project
       # builds. Tracking it here keeps the moon graph — not a hand-kept path
       # list — the source of the leg's true build closure, so a change to only
       # the VMM-env still marks this project affected and the boot test runs.
       - '/tools/toolchain/microvm-vmm-env.nix'
-      - '/packages/compass-agent/**'
-      # T1 packages the T2 guestd binary (buildGoModule of go/cmd/compass-guestd)
-      # as the rootfs /sbin/init, so the backend module is now a build input: a
-      # guestd or go.mod/go.sum change must reschedule this build. The module
-      # manifests are called out explicitly (a vendorHash move forces a rebuild)
-      # alongside the guestd command + its internal package tree.
+      # guestd is the rootfs /sbin/init, so the backend module is a build
+      # input: a guestd or go.mod/go.sum change must reschedule this build. The
+      # module manifests are called out explicitly (a vendorHash move forces a
+      # rebuild) alongside the guestd command + its internal package tree.
       - '/go/go.mod'
       - '/go/go.sum'
       - '/go/cmd/compass-guestd/**'
       - '/go/internal/guestd/**'
       - '/go/internal/gen/**'
-      - '/package.json'
-      - '/bun.lock'
       - '/devenv.lock'
       - '/devenv.yaml'
 

From 816555fe5a9e9957d84a22c3b8b862fb2d71e1aa Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 16 Sep 2026 17:06:25 -0400
Subject: [PATCH 2/3] fix(guest-image): bind the rootfs to its pinned manifest
 and confine unpacking

Review findings on the OCI-derived rootfs, each with a reproduced counterexample:

- The lock's manifest digest constrained nothing: only the layer descriptors
  decided what was unpacked, so a lock pairing that digest with another image's
  valid layers built clean. The manifest is now fetched fixed-output against the
  digest (a manifest digest is the sha256 of its body) and its own ordered layer
  list must equal the lock's.
- A lower layer's absolute symlink used as a parent path let tar write, and the
  whiteout `rm -rf` delete, outside the staged root. Such parents are dropped
  before extraction and a `..` member now breaks the build.
- The userland contract passed on a non-executable or a directory; it now
  requires an executable regular file.
- setuid/setgid files are asserted absent rather than assumed.

The packed image is byte-identical: the published layers trip none of these.

Refs RIG-3787
---
 guest-image/default.nix | 72 ++++++++++++++++++++++++++++++++++++++---
 guest-image/moon.yml    | 12 +++----
 2 files changed, 71 insertions(+), 13 deletions(-)

diff --git a/guest-image/default.nix b/guest-image/default.nix
index db2011386..739b56304 100644
--- a/guest-image/default.nix
+++ b/guest-image/default.nix
@@ -54,6 +54,32 @@ let
     else
       throw "guest-image: agent-oci.lock is not a valid pin: ${bad}. Rewrite it with `bun tools/guest-image/pin-agent-image.ts --relock`, never by hand.";
 
+  # The pinned manifest, fetched fixed-output against the lock's digest: a
+  # manifest digest IS the sha256 of its body, so nix's hash check authenticates
+  # it outright. Without this the digest would be decoration -- the layer
+  # descriptors alone decide what gets unpacked.
+  agentManifest = pkgs.fetchurl {
+    url = "https://${agentRegistry}/v2/${agentPath}/manifests/${checkedLock.digest}";
+    curlOptsList = [
+      "-H"
+      "Authorization: Bearer QQ=="
+      "-H"
+      "Accept: application/vnd.oci.image.manifest.v1+json"
+    ];
+    hash = checkedLock.digest;
+  };
+
+  # The manifest's own ordered layer list. Reading it here rather than trusting
+  # the lock's copy binds the unpacked bytes to the pinned image: a hand-edited
+  # lock pairing this digest with another image's valid layers no longer builds.
+  manifestLayers = map (l: l.digest) (builtins.fromJSON (builtins.readFile agentManifest)).layers;
+
+  lockedLayers =
+    if manifestLayers == checkedLock.layers then
+      checkedLock.layers
+    else
+      throw "guest-image: agent-oci.lock layers do not match the manifest it pins (${checkedLock.digest}). Rewrite it with `bun tools/guest-image/pin-agent-image.ts --relock`, never by hand.";
+
   # Each layer blob, fetched fixed-output against its descriptor digest -- the
   # registry's own content address, where one archive's narHash would track
   # skopeo's byte layout. The bearer is GHCR's literal anonymous public-read
@@ -68,7 +94,7 @@ let
       ];
       hash = digest;
     }
-  ) checkedLock.layers;
+  ) lockedLayers;
 
   # The guest-side supervisor, running as guest PID 1: mounts the API
   # filesystems, brings networking up, serves the vsock Health handshake. Static
@@ -314,7 +340,32 @@ in
         # extracted -- an opaque marker applied afterwards would delete the
         # sibling files that same layer adds.
         for layer in ${lib.concatStringsSep " " agentLayers}; do
-          tar -tzf "$layer" | sed 's|^\./||' | { grep '\.wh\.' || true; } | while read -r marker; do
+          members=$(tar -tzf "$layer" | sed 's|^\./||')
+
+          # Archive names drive the rm -rf and tar writes below, so a `..`
+          # component fails the build rather than being sanitized: tar would
+          # follow it out of the staged tree.
+          if printf '%s\n' "$members" | grep -qE '(^|/)\.\.(/|$)'; then
+            echo "guest-image: BUILD-BREAK — layer $layer has a '..' member path." >&2
+            exit 1
+          fi
+
+          # A layer replacing a lower layer's symlink with a real directory is
+          # legitimate OCI, but tar would write THROUGH the stale symlink --
+          # outside $root when its target is absolute. Drop such parents so tar
+          # materializes a directory instead.
+          for d in $(printf '%s\n' "$members" | sed -n 's|/[^/]*$||p' | sort -u); do
+            p=""
+            IFS=/
+            for c in $d; do
+              [ -n "$c" ] || continue
+              p="$p/$c"
+              if [ -L "$root$p" ]; then rm -f "$root$p"; fi
+            done
+            unset IFS
+          done
+
+          printf '%s\n' "$members" | { grep '\.wh\.' || true; } | while read -r marker; do
             dir=$(dirname "$marker")
             base=$(basename "$marker")
             if [ "$base" = ".wh..wh..opq" ]; then
@@ -351,6 +402,17 @@ in
         for p in $(cat ${bootClosure}/store-paths); do
           cp -a "$p" "$root/nix/store/"
         done
+
+        # A setuid/setgid binary is a privilege path back to root, which the
+        # guest's non-root agent must not have. Belt-and-braces: the unprivileged
+        # builder cannot set those bits anyway (tar drops them), so this catches
+        # a future privileged builder or a cp that preserves them.
+        suid=$(find "$root" -type f -perm /6000 -printf '%M %P\n' || true)
+        if [ -n "$suid" ]; then
+          echo "guest-image: BUILD-BREAK — setuid/setgid files in the rootfs:" >&2
+          printf '%s\n' "$suid" >&2
+          exit 1
+        fi
         chmod -R u+w "$root"
 
         # The userland contract, checked on the ASSEMBLED tree. EVERY component
@@ -401,9 +463,9 @@ in
             fi
           done
           target="$resolved"
-          if [ ! -e "$root$target" ]; then
-            echo "guest-image: BUILD-BREAK — /$p does not resolve inside the rootfs." >&2
-            echo "  It resolves to $target, which the image does not carry." >&2
+          if [ ! -f "$root$target" ] || [ ! -x "$root$target" ]; then
+            echo "guest-image: BUILD-BREAK — /$p is not an executable in the rootfs." >&2
+            echo "  It resolves to $target, which the image does not carry as one." >&2
             echo "  The guest userland comes from the pinned agent image" >&2
             echo "  (${checkedLock.repo}@${checkedLock.digest})." >&2
             echo "  Either that image stopped shipping it, or a layer failed to" >&2
diff --git a/guest-image/moon.yml b/guest-image/moon.yml
index c7dffbb5f..262b9c5ec 100644
--- a/guest-image/moon.yml
+++ b/guest-image/moon.yml
@@ -48,14 +48,10 @@ tasks:
     options:
       cache: false
       runInCI: true
-    # The rootfs build closure. The agent userland now comes from the pinned
-    # OCI image, not a local nix build of the agent sources, so the agent-side
-    # input is `agent-oci.lock` alone (covered by the `**/*` glob below): a
-    # change to the agent reaches this build only by the pin moving, and a pin
-    # move IS a change to that file. The remaining entries are the BOOT
-    # layer's closure. A glob that misses one silently skips a build that
-    # should have run and leaves the E4 cache stale (§ E3). A leading `/` is
-    # workspace-root-relative; the bare glob is this project's own tree.
+    # The agent userland comes from the pinned OCI image, so the agent-side
+    # input is `agent-oci.lock` alone, covered by `**/*` below; the rest is the
+    # boot layer's closure. A glob that misses one silently skips a build that
+    # should have run. A leading `/` is workspace-root-relative.
     inputs:
       - '**/*'
       # The microVM boot leg (ci.yml `microvm` job) realizes this VMM-env

From abc8a2969bea1bdb13f860add1040f4531a3a297 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 16 Sep 2026 18:34:31 -0400
Subject: [PATCH 3/3] fix(guest-image): preserve published file modes and
 anchor whiteout markers

Correctness-lens findings on the OCI-derived rootfs, each reproduced first:

- Extraction used --no-same-permissions, so every member took the builder's
  umask instead of its published mode: /bin packed 0755 where the image ships
  0555. Extract with -p and re-open staging write access on directories only,
  then restore the directories' published modes before packing. Directory
  members are selected by tar's type flag, since these layers list directories
  with no trailing slash.
- The whiteout scan matched the marker prefix anywhere in a path, so an
  ordinary directory whose name contained it became a delete order.
  Reproduced deleting a lower-layer file outright. The match is now anchored
  to a marker-prefixed final component.
- An opaque marker naming a missing directory was swallowed by a redirect to
  /dev/null plus a true fallback; it now breaks the build, since it means the
  layer stack is not what this build thinks it is.
- The image root's mode was a chmod side effect (0555 inherited from the boot
  layer's store path until a later pass happened to widen it); it is now set
  outright.
- The store-path loop word-split an unquoted command substitution under
  nullglob, so a path containing a glob metacharacter was silently dropped,
  yielding an incomplete rootfs. It now reads line-wise.
- The contract resolver counted path components, not symlink hops, so a deep
  symlink-free path could be reported as a loop.
- The lock guard called builtins.match on a non-string tag, replacing the
  curated error with a raw nix type error.

Not fixed, measured: mkfs.erofs drops the sticky bit on /tmp whatever the
staged mode, so /tmp packs 0777 rather than 1777. The rootfs boots read-only,
so the lower layer's mode is not what makes /tmp writable.

Refs RIG-3787
---
 guest-image/default.nix | 76 ++++++++++++++++++++++++++++-------------
 1 file changed, 52 insertions(+), 24 deletions(-)

diff --git a/guest-image/default.nix b/guest-image/default.nix
index 739b56304..d0b7cac7c 100644
--- a/guest-image/default.nix
+++ b/guest-image/default.nix
@@ -36,9 +36,13 @@ let
   checkedLock =
     let
       bad =
-        if agentLock.repo or null != agentRepo then
+        if !builtins.isAttrs agentLock then
+          "lock must be a JSON object"
+        else if !builtins.isString (agentLock.repo or null) || agentLock.repo != agentRepo then
           "repo must be ${agentRepo}, got ${toString (agentLock.repo or "<missing>")}"
-        else if builtins.match "git-[0-9a-f]{12}" (agentLock.tag or "") == null then
+        else if
+          !builtins.isString (agentLock.tag or null) || builtins.match "git-[0-9a-f]{12}" agentLock.tag == null
+        then
           "tag must match git-<sha12>, got ${toString (agentLock.tag or "<missing>")}"
         else if !isSha256 (agentLock.digest or "") then
           "digest must be sha256:<64 hex>, got ${toString (agentLock.digest or "<missing>")}"
@@ -365,31 +369,40 @@ in
             unset IFS
           done
 
-          printf '%s\n' "$members" | { grep '\.wh\.' || true; } | while read -r marker; do
+          # A marker is a `.wh.`-prefixed final COMPONENT. Matching the
+          # substring anywhere would read an ordinary path that merely contains
+          # `.wh.` as a delete order against a file the layer legitimately
+          # ships.
+          printf '%s\n' "$members" | { grep -E '(^|/)\.wh\.' || true; } | while read -r marker; do
             dir=$(dirname "$marker")
             base=$(basename "$marker")
+            case "$base" in
+              .wh.*) ;;
+              *) continue ;;
+            esac
             if [ "$base" = ".wh..wh..opq" ]; then
-              find "$root/$dir" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+              # A marker naming a path the lower layers never created means the
+              # layer stack is not what this build thinks it is; fail loudly
+              # rather than swallowing the status.
+              if [ ! -d "$root/$dir" ]; then
+                echo "guest-image: BUILD-BREAK — opaque marker names a missing directory $dir." >&2
+                exit 1
+              fi
+              find "$root/$dir" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
             else
               rm -rf "$root/$dir/''${base#.wh.}"
             fi
           done
 
-          # --overwrite and the chmod are load-bearing: nix2container layers carry
-          # /nix/store paths with the store's read-only modes, so without them tar
-          # fails "File exists" on a duplicated entry and "Permission denied"
-          # writing into an already-extracted r-xr-xr-x directory.
-          tar -xzf "$layer" -C "$root" --overwrite --no-same-permissions \
+          # -p restores each member's recorded mode; without it every member
+          # takes the builder's umask instead (measured: /bin packed 0755 where
+          # the image ships 0555). Staging write access is re-opened on
+          # DIRECTORIES only, leaving file modes as published.
+          tar -xzpf "$layer" -C "$root" --overwrite \
             --exclude='.wh.*' --exclude='*/.wh.*'
-          chmod -R u+w "$root"
+          find "$root" -type d -exec chmod u+w {} +
         done
 
-        # cp -a preserves the store's read-only dir modes; make the staged tree
-        # writable so the boot layer and /nix/store population can proceed
-        # (--all-root normalizes ownership; -T0 normalizes timestamps, so these
-        # staging perms never reach the packed image).
-        chmod -R u+w "$root"
-
         # Lay the boot layer over the unpacked image. It wins on any path
         # conflict: /sbin/init, /sbin/modprobe, /lib/modules and the writable
         # /etc/resolv.conf are the guest's, not the container's.
@@ -399,9 +412,9 @@ in
         # The boot layer's own store closure. The agent layers already carry
         # their /nix/store paths, so only these are added.
         mkdir -p "$root/nix/store"
-        for p in $(cat ${bootClosure}/store-paths); do
+        while IFS= read -r p; do
           cp -a "$p" "$root/nix/store/"
-        done
+        done < ${bootClosure}/store-paths
 
         # A setuid/setgid binary is a privilege path back to root, which the
         # guest's non-root agent must not have. Belt-and-braces: the unprivileged
@@ -413,7 +426,20 @@ in
           printf '%s\n' "$suid" >&2
           exit 1
         fi
-        chmod -R u+w "$root"
+
+        # Re-extract the directory members to restore their published modes,
+        # undoing the staging u+w. / is then set outright: `cp -a ${bootLayer}/.`
+        # stamps the store's 0555 onto it, so leaving it to a chmod's residue
+        # makes / untraversable or accidentally right depending on ordering.
+        for layer in ${lib.concatStringsSep " " agentLayers}; do
+          # Select directory members by tar's type flag: these layers list
+          # directories with no trailing slash, so matching on one restores
+          # nothing.
+          if tar -tvzf "$layer" | awk '$1 ~ /^d/ {print $NF}' > dirs.txt; then
+            tar -xzpf "$layer" -C "$root" --overwrite --no-recursion -T dirs.txt
+          fi
+        done
+        chmod 0755 "$root"
 
         # The userland contract, checked on the ASSEMBLED tree. EVERY component
         # resolves inside $root, as the kernel will after switch_root: following
@@ -424,11 +450,6 @@ in
           rest="/$p"
           hops=0
           while [ -n "$rest" ]; do
-            hops=$((hops + 1))
-            if [ "$hops" -gt 40 ]; then
-              echo "guest-image: BUILD-BREAK — /$p is a symlink loop in the image." >&2
-              exit 1
-            fi
             comp=''${rest#/}
             comp=''${comp%%/*}
             tail=''${rest#/"$comp"}
@@ -446,6 +467,13 @@ in
             esac
             resolved="$resolved/$comp"
             if [ -L "$root$resolved" ]; then
+              # Count symlink traversals, not path components: a deep
+              # symlink-free path is not a loop, and Linux's own ELOOP is 40.
+              hops=$((hops + 1))
+              if [ "$hops" -gt 40 ]; then
+                echo "guest-image: BUILD-BREAK — /$p is a symlink loop in the image." >&2
+                exit 1
+              fi
               link=$(readlink "$root$resolved")
               case "$link" in
                 /*)