diff --git a/.moon/workspace.yml b/.moon/workspace.yml
index 7d413909..fa1c63b5 100644
--- a/.moon/workspace.yml
+++ b/.moon/workspace.yml
@@ -56,6 +56,11 @@ projects:
   # the CI sweep — that suite is what catches a build-arg or closure-root drift,
   # since no compass CI step can build the image itself today.
   runner-image: 'tools/runner-image'
+  # The agent-image pin the microVM guest rootfs derives from. Registered so
+  # its typecheck + pure-core unit tests ride the CI sweep — that suite is what
+  # catches a provenance or layer-order drift, and moon discovers projects only
+  # from this map, so unregistered the whole guard suite is silently inert.
+  guest-image: 'tools/guest-image'
   # The Compass native-app release bundle: a heavy nix build (realises the
   # WebKitGTK cc/pkg-config closure) that stages the versioned tarball. Same
   # affected-detection posture as compass-agent-image — registered here so the
diff --git a/bun.lock b/bun.lock
index 786a6194..fcea345e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -169,6 +169,16 @@
         "typescript": "catalog:",
       },
     },
+    "tools/guest-image": {
+      "name": "@compass/guest-image",
+      "bin": {
+        "guest-image-pin-agent": "./pin-agent-image.ts",
+      },
+      "devDependencies": {
+        "@types/bun": "catalog:",
+        "typescript": "catalog:",
+      },
+    },
     "tools/inline-sql-gate": {
       "name": "@compass/inline-sql-gate",
       "bin": {
@@ -487,6 +497,8 @@
 
     "@compass/forge-linear-token": ["@compass/forge-linear-token@workspace:tools/forge-linear-token"],
 
+    "@compass/guest-image": ["@compass/guest-image@workspace:tools/guest-image"],
+
     "@compass/inline-sql-gate": ["@compass/inline-sql-gate@workspace:tools/inline-sql-gate"],
 
     "@compass/macos-bundle": ["@compass/macos-bundle@workspace:tools/macos-bundle"],
diff --git a/guest-image/agent-oci.lock b/guest-image/agent-oci.lock
new file mode 100644
index 00000000..bb7afe76
--- /dev/null
+++ b/guest-image/agent-oci.lock
@@ -0,0 +1,127 @@
+{
+	"repo": "ghcr.io/rigelbuild/compass-agent",
+	"tag": "git-7d22c69390cb",
+	"digest": "sha256:634aeee15954f43b9a009b2dd9fe2ad3b454f64dd09c9491957c03d0313a6823",
+	"layers": [
+		"sha256:989a42bd3ddf0028fce105bf936074ae1cad375bbabf868ba358161d6eddea56",
+		"sha256:50173e59368b86248a8fc447563bc692eb54cea61522d423c562037b27273b1f",
+		"sha256:609f4904737a247c83c6f5e57210a99c625ee6fef0e1a2bab7c1368f5cb7da95",
+		"sha256:9b1563075c8b42c7e91675d2c44177dfdfd47087996152d063e04b2c838c8f57",
+		"sha256:a27e5e982aec83990632c6891f73050659a47e9425d2f8ff4ba27e3a60fd3a05",
+		"sha256:83e4a642b15fa357dd60c58e34dce2dbe8bca77866e602c3ddb457fb86ed3791",
+		"sha256:a28acb06d258001260b8879bc49bad34a40235752ec067ebafff194c015bab78",
+		"sha256:1eefdcdcb94a4c13c0bb56dcb22a00c4b07ebf09b2a13441d6feb4f774765592",
+		"sha256:2b835b65e2621850178daf39a8b51501a77e0141ab1997fa49959855de597200",
+		"sha256:b4939a5f31ab0f55db6a137ece82f2d1dd837fd9a75a335535a3cdf34ea4ed0c",
+		"sha256:88337f8b7d5b5415714dc5db31f95397e6c0d69797e977ae630a45c6fd7b1f70",
+		"sha256:ce855785a761c203e0b4992059938de647b375b3c99662ec9a7b9446a39b46b7",
+		"sha256:a65a251cbf515329613b066e7137ff1bb7e76605afff8b63f5a1eece0fad4814",
+		"sha256:5087d0bd2d08b75bccdb9d9e0cdf3fe643d36a420750efb68b9ccb7d7cbfaf42",
+		"sha256:97290c6058d9cdb192d4a844731078d54b76e17e01926866c8b002ca0a22cf81",
+		"sha256:12d9b9a35a002c04b40dfa8ce19f1930844c756132db2a0acc9114e6d3c77be2",
+		"sha256:c904b30222e4fb1b1dfd2bef268e7acd862d30a027688ad705fe0ca824aa25b7",
+		"sha256:befa4be2046b290e0f318c2bae8d0c6e0b60fcbbec0e8b9c4e523e0fa2920fab",
+		"sha256:1a5561045f0d6f709a5af083cc9229d7c2a107e71d41b33c1a8360fea3e88266",
+		"sha256:20d466aba19a30ed1f9baf7721d7f3dec6343e9c2e56cabe71d080a01158c059",
+		"sha256:fb54e13d029c33ad1ee18e64b535951a2a38fc7fbdf54c7d1cf9a4079e2ba5cf",
+		"sha256:5cb7cb4604ee7d5784b1eec9595ba61d4710ebe5144d88d564f2d866fc36f63d",
+		"sha256:dfc15617d544c97e54dd90b3aa4ae226ea154ea20b19225bb0c7a9ae813f2f81",
+		"sha256:06d8edbc5d4b45454ed65016ebd473df9a73d731a1a318c61fb339690b2b2a0a",
+		"sha256:0198a70f4b3c743a14950e34e5faad8a10e05279da9d1ee23d9c61784189c911",
+		"sha256:85b200ba6a9563b01210fb6db146d687216b4f1e4ead539686522d9b745c9da4",
+		"sha256:e8e32b46884a076249c1ba0d8f8009f044908801b07e428e83e369ca52281bb2",
+		"sha256:8e8004a82bd80ac730a45ff11144afd39237e36e622ae1eae305e421a4ed9023",
+		"sha256:a2784d4ed644739b1e62165bfe0dc7691fabcfe85e953256efa54eb227c70575",
+		"sha256:9a110d87dee34a853f538f53f50df90c23f74bb53db2c53d3a2107155004b0cd",
+		"sha256:13de35f6e89265878c1ae16ab4229918fa813ec44be7157d2ada66599bf6be5f",
+		"sha256:f3a08b5ecac5276869ebd366319e108122fc87163c05bc9675d0f028f790467f",
+		"sha256:df281230c7a1c6db680798e6f966ced09429944ff0c5712eaed9232d11fab644",
+		"sha256:4fada2aae32b9938dc63e1b2ed0598a3975324ed6736c707e52ceecaeebdf5e1",
+		"sha256:4244ec3726b6b1a71d3c4cd9f0302a1a152a24b3f028b0080e35496ee1ab1dab",
+		"sha256:4eac009357ae2dd5ceba989358f0fa6ee78b5f183cd67f056a99dd02345e870b",
+		"sha256:a829f97edb5088eff29dfebae5d3660958e7d975885fecc51ce70ead4833a66c",
+		"sha256:6c7632a46e4ff00f8169a235bdbcf13ba72c8cedceea9dd668554e5603818ecd",
+		"sha256:cb66e85841af9451aa00ab4fe86b4cd882e72a5773c077f37925306bcfa1d246",
+		"sha256:4ca9a76c303917d8c4ebde29863514bd6d76e24d787f5f0e2e9adf9036912683",
+		"sha256:00f060b0330fc649c90ff8aed0d03759f4cdee31b2be667c09ce2160a6458636",
+		"sha256:bdfff65a8c7c8621704da3d42c65121a6ea8523e258aa59d015b23beb0420502",
+		"sha256:0d5cfe1be61877a897aea120f0928e295bfc0a88958ffc641faa19f9983302e4",
+		"sha256:728eac9836a08e8de1694f02fc8c29eac6170b3ef9286ee64eaecc4cfa53df8e",
+		"sha256:5d5bbab83a69df879f9af7f9560249903b5e4cd3ad008e35b7961abce039cbdc",
+		"sha256:246ed1b833889333ed005b5c3a72dd39235d1ad8211d6c70f86b86ebb407ef85",
+		"sha256:775d60e8d947f0b14ca30badc625df4b7d80bf87ba5e1b172d764052697a10fb",
+		"sha256:c964d986e2041dc5918b96df2d84106893a0099661f0e677634a8984fe965259",
+		"sha256:12c3a013e98cc6b4336bcf4c050a4b74e1deca42fcc2bcc9a6166977a357e475",
+		"sha256:e2926a71d238fac16fb251b1f1a316399b4aa05bf606b6be7ef307c50833a0d8",
+		"sha256:74ead26ad73b3ccdf0366060c36bed040a3bc72e78a6676619ff5f92abbc6999",
+		"sha256:a754daf94f43269c51efba261e2a1f2a2fe334c394537dbac00dc3f8d8df4a59",
+		"sha256:2baf24046fe64dd59b1daa3412ad8d0311a1d49f6f658e876e129a462a968a05",
+		"sha256:0e213195a5c4a56ba80f8fbcfcfab538763f98911e7e8c72bd6d671362fb743f",
+		"sha256:f41f723d758771feea97eb49b70accb3f71eb584909635ef32332b7093e664b5",
+		"sha256:ab2beaf90a91a92a339fc96abb64fdb39ed513cd19fcfb492e4cd546bb25acf2",
+		"sha256:f0c6726cd51279b847ff36fa7ff0d687a7959900e7544171df2bb2e8e3caf2d0",
+		"sha256:c40dd490d44cdc6440cb2683092145444b8f42886d07b714c75c1c2aaf103e50",
+		"sha256:b516c2ee390cbc32fd7310cc7af36eb246125c694444742c73e520cecae0e4df",
+		"sha256:5b1711b70bea797e1ce3412fbcf6a08db518a7c6824e76979b21068a97bd2cf9",
+		"sha256:9f7536248f41ecdf13dacde207e17123c60da3a94bd69a6ef8f7bd4d139eb960",
+		"sha256:5bc8acf2dea1d01db0898633dfd1bde185ceb274b7585b948d0dd324e2f0e3f5",
+		"sha256:66bece8745d11e9544e544fcb28a11392715247cb7e20c3be437ec570c59ba44",
+		"sha256:e31da11550fa2b023bdc7b75deaef05a255cd60de8ab2ab3b6bfccb7c27ef592",
+		"sha256:25ed9f7c6766d6942a72491c4df4f5e6ece1800dfee40763900a0fa43a2be5b5",
+		"sha256:9d19949397a22dc46c92e39023bd819dbd9c97998f7ec1540bb4e7cf780962be",
+		"sha256:06220d2ab5c467b16cfd243be799ea404c8f27aa9915bdf7d519d11d92e50fdb",
+		"sha256:ff4a05359598d8e219aa9bcb50e84c0155c30befb4a60eb470ab0f2867f7c7f0",
+		"sha256:49829c965f4ae698d07769fdcebaa3c6c99f87c99df9c03e263ba3aed7d644df",
+		"sha256:f5c5ed6c6f2df8e23f17f0db989fb12516eb7626e08ac1e5a7cb12d58b6b3d45",
+		"sha256:ac4c11458e54c5a34854ba6d54ffc262d9c6450d261b16069302d9367cde5698",
+		"sha256:8f9d57a9adef65c895542b90d3235b272e6349d574e4644e07b1b0a7519e2b5e",
+		"sha256:6e2f7a0e9efa1a18ea3829f0393c89bc9761cc6ae96a6aa9107d087f2c621c74",
+		"sha256:6aaf42086be878b2d8547a0565c022249cc1d05fe9402982f77eb51c53697b61",
+		"sha256:65294ae739b115754167fa6e5e737721a1ae59a8f28a3750642c24dbfaedc162",
+		"sha256:0b60a919cb943e44ec9b862389f2c86b8d86eb4ad3b855d5346bf11df1c34550",
+		"sha256:715f8f27508def1aae7ab159b1ea75b5924364c5f21b5d494eaddc2fdb79fc7f",
+		"sha256:b65b930bbd24ab4b07c3fbdc7c57c209c1b9905fe628c83cbc933e0c30577445",
+		"sha256:97ad1a929ca4155ee00fdc2d4f6d2b57278ae06e0c395230ec7113d821b3527d",
+		"sha256:bc8a89708d25b218cd31000d8eac61f324d49562f2c330197f1af68fc9bc652c",
+		"sha256:46cab03582f2a2720809cbbe22b8d9b445cb22d19de646d77fa0446ded5b5802",
+		"sha256:99b2de06e987ead1a31fd34a7f62653e0b8048659419c705ffe4c9e9657d419d",
+		"sha256:ef475c65af727c6a13570a37f1ef362c242f43a5f1a90a8a55f3e2f7bbce2d70",
+		"sha256:3ef92c85b3f0bec77b09c39249546b7f91fc7c371918ab6ab9948e59bd917fa6",
+		"sha256:ca2641e89ea1c87034ed4a274c3dc991d33f9447bb68b6f22e4b7d4edcf068c2",
+		"sha256:96e4db8add2228b01419c910d8ebc2ba01e2f242a610d74f7bbf677eafb53a40",
+		"sha256:7e69e346d08c4457b0e63f09960dfe24f752c960a864c092d48763b62c49e564",
+		"sha256:6e35e26aa14caa1f1815b6371660534eae37889992c0132c195eb525231f27c2",
+		"sha256:7306b70d6767a21686f9fed6e16919ba392093fbd58368be9a02b39f62cd3461",
+		"sha256:65f85994228e6dde888ff7fa7b6d96d92da9b98c9501186586fc7e53daeac2c3",
+		"sha256:1f952f741c864361946ac2407d122b6fb9b3f123129b148de514efedd3235d12",
+		"sha256:c958165a9542d4bf4393b9604b9eb6be3c7d9bba5804951826dcb096e3b67b95",
+		"sha256:ecac70470eabab90c8bed7011dacbe94f194d71fc9f54a9b34872bd0f98f6b88",
+		"sha256:a02defd4db5cc2b025f7a1c5ce7993a870176448e46c0a927f0af0713a3b6314",
+		"sha256:401e76c82da6cceb5ad589a2d2f0c4147edfac4f8201beddd2aa6bb50e7a529b",
+		"sha256:754284604d7120599f55426b596d3059a5f165d0a0f6945ff0c8a0c7dbe78d7d",
+		"sha256:aaae4d6fac166dd8391dd6658edd2a3f301221b39e71326e5ea5f1d6adf1b064",
+		"sha256:5a9b6b2a22916fcb634f882a6db07eac6d3adc76091acd1b0bc4ebac2d3f8a93",
+		"sha256:0f7b3d9b68a4182a7a1a69210f185b79602d7c4af167a8e0ef3f8164cd38c31f",
+		"sha256:7de18bb60520597810e1a194bedfea095e6ef1e50e1ded8bae5932b5de912f28",
+		"sha256:fc47246e342a6eb0a98ba9de3c22935a3efb207145225c11618c80231c1bb0d4",
+		"sha256:ee0a9aa87179703abee4b1cb415e07824062f39c2b04ee4f60a76df6966f3d74",
+		"sha256:203eeea7b1eb8205b03425e85285b5da506690c259ab0c6fa04ca8e96324696b",
+		"sha256:6e73d91899a55c1f0675d38edd0c204464dc292e8a00c1098c0d35a21838562b",
+		"sha256:c0b09b3836b9186903c246773edc9f8f87a3a03b961b0caecbe9eb90d19959c1",
+		"sha256:f32d5c68675ebc9e082de3df1038c3ad1d89d201505e621a85ba3577c2b215af",
+		"sha256:c2beac798a2dbe5871128478b2a3f10f538c8b8261e5c38eaf31e66aaa5edfa9",
+		"sha256:52380eaa83367c693530b0a7090ae394d01921000edc44670afbabce927f6e7f",
+		"sha256:7a844f24a8e47aa904741a2df961abec6d4afacc165ebef763c4d29af2dc5df3",
+		"sha256:402112cc028033bdb988d0cd3ef05efdc03c69f00edfa283631154282f38a65a",
+		"sha256:1a27431e1302ba23b4bc81e831d1d8dc8b15b4865fab9597ee3e8820c75937e7",
+		"sha256:4f1af9cd0cd69eb34e1768141d28c910c60362948689abc3386cd89f7e0151a1",
+		"sha256:fe2778aea835fa21fa28f93259017b12a4374b776047abb8735200cfc94f56ff",
+		"sha256:d4cf521bbf13c6e071ac0175177694f462483fc293e6753680cae7e40535f603",
+		"sha256:d0b7a7f7092eaccf2be2d988d5ce399fc40c137ff7c51c55cdc81e6ac91add9e",
+		"sha256:1d8ff8656e5da54cde4f2fff6b262d6d99f54ea1ce119ad655aef28131c6e107",
+		"sha256:d7594f8803ea13a94c80a3345f2706b0cb69d07c428c77ba632230fcb4248e8b",
+		"sha256:ee18288abf12a859737dc7bacfef6506657ea5582e184745f1e433422df945eb",
+		"sha256:462cce1dc39d5d73bafee275866bf3de96ca4f25594fe84e13ba873eef95b953",
+		"sha256:7564bc82edf713cb15a3d5406a213a27cff25f83663e1954c3bcc35c35df011e"
+	]
+}
diff --git a/guest-image/default.nix b/guest-image/default.nix
index e06bb6ac..d0b7cac7 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,95 @@ 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 !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.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>")}"
+        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.";
+
+  # 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
+  # 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;
+    }
+  ) lockedLayers;
+
+  # 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 +119,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 +139,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 +178,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 +213,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 +240,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 +269,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 +284,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 +324,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 +339,174 @@ 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/"
-        # 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).
+        # 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
+          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
+
+          # 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
+              # 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
+
+          # -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.*'
+          find "$root" -type d -exec chmod u+w {} +
+        done
+
+        # 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
+        while IFS= read -r p; do
           cp -a "$p" "$root/nix/store/"
+        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
+        # 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
+
+        # 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
+        # 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
+            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
+              # 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
+                /*)
+                  resolved=""
+                  rest="$link$tail"
+                  ;;
+                *)
+                  resolved=$(dirname "$resolved")
+                  [ "$resolved" = "/" ] || [ "$resolved" = "." ] && resolved=""
+                  rest="/$link$tail"
+                  ;;
+              esac
+            else
+              rest="$tail"
+            fi
+          done
+          target="$resolved"
+          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
+            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 b7393df9..262b9c5e 100644
--- a/guest-image/moon.yml
+++ b/guest-image/moon.yml
@@ -48,41 +48,27 @@ 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 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:
       - '**/*'
-      - '/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'
 
diff --git a/tools/guest-image/biome.json b/tools/guest-image/biome.json
new file mode 100644
index 00000000..ece11dd9
--- /dev/null
+++ b/tools/guest-image/biome.json
@@ -0,0 +1,4 @@
+{
+	"extends": "//",
+	"linter": { "rules": { "suspicious": { "noConsole": "off" } } }
+}
diff --git a/tools/guest-image/moon.yml b/tools/guest-image/moon.yml
new file mode 100644
index 00000000..609d0775
--- /dev/null
+++ b/tools/guest-image/moon.yml
@@ -0,0 +1,36 @@
+# yaml-language-server: $schema=https://moonrepo.dev/schemas/project.json
+#
+# guest-image: the agent-image pin the microVM guest rootfs derives from.
+# TypeScript rather than a shell script (the no-bash-gate CI task).
+#
+# The pin CLI itself talks to a registry, so it is not a gate task. The
+# typecheck/test tasks here ARE ordinary bun gates: they cover the pure core —
+# the provenance rejections and the layer-descriptor extraction whose drift
+# would silently make the rootfs unreproducible or stack a different
+# filesystem.
+#
+# A bun/TypeScript CLI, hoisted root-workspace member (`bun` tag): install is
+# inherited via .moon/tasks/tag-bun.yml and lint/format are whole-repo root
+# tasks, so this leaf carries no own bun.lock.
+layer: 'tool'
+language: 'typescript'
+tags: ['bun', 'ci-group.bun']
+
+tasks:
+  typecheck:
+    command: 'bunx tsc --noEmit'
+    deps: ['install']
+    inputs: ['*.ts', 'tsconfig.json', '/tsconfig.base.json', 'package.json', '/bun.lock']
+  test:
+    # The pure core (pin-core.ts): every provenance rejection (foreign repo,
+    # moving tag, malformed digest), the manifest-shape refusals, and the
+    # layer order that determines the stacked filesystem.
+    inputs: ['*.ts', 'tsconfig.json', '/tsconfig.base.json', 'package.json', '/bun.lock']
+  # The CI aggregate. Without it ci-matrix contributes NO target for this
+  # project (it emits `<id>:ci` only for a project defining a `ci` task), so
+  # the guard suite above would never run on a PR — registered in
+  # .moon/workspace.yml and still silently inert.
+  ci:
+    deps: ['typecheck', 'test']
+    options:
+      cache: false
diff --git a/tools/guest-image/package.json b/tools/guest-image/package.json
new file mode 100644
index 00000000..f959a577
--- /dev/null
+++ b/tools/guest-image/package.json
@@ -0,0 +1,14 @@
+{
+	"name": "@compass/guest-image",
+	"private": true,
+	"type": "module",
+	"description": "Pin the published compass-agent image the microVM guest rootfs derives from: resolve an immutable git-<sha12> tag to its manifest digest and layer descriptor set, and write guest-image/agent-oci.lock. The lock is the rootfs's whole provenance story, so the pin enforces it rather than documenting it.",
+	"module": "pin-agent-image.ts",
+	"bin": {
+		"guest-image-pin-agent": "./pin-agent-image.ts"
+	},
+	"devDependencies": {
+		"@types/bun": "catalog:",
+		"typescript": "catalog:"
+	}
+}
diff --git a/tools/guest-image/pin-agent-image.ts b/tools/guest-image/pin-agent-image.ts
new file mode 100644
index 00000000..f5c79eb7
--- /dev/null
+++ b/tools/guest-image/pin-agent-image.ts
@@ -0,0 +1,228 @@
+// Pin the published compass-agent image the guest rootfs derives from
+// (guest-image/agent-oci.lock).
+//
+// Two modes. `--tag git-<sha12>` pins an explicit build. `--relock` is the
+// Renovate postUpgradeTask: it re-derives the whole lock after the regex
+// manager bumped part of it.
+//
+// WHY --relock EXISTS (do not "simplify" it to a bare regex bump). The lock
+// carries the per-layer descriptor digests the nix fixed-output fetches key
+// on, and Renovate cannot compute those: a regex manager can move the tag and
+// manifest digest, but the layer set it leaves behind still describes the OLD
+// manifest, so every fetch would fail on every Renovate PR. This is the same
+// failure class tools/renovate/refresh-devenv-lock.ts names for devenv — a
+// rev-only rewrite leaves paired fields stale — and the same remedy: a
+// customManager PLUS a postUpgradeTask that makes the lock genuinely
+// consistent. The digest-only DefaultPostgresImage pin is NOT the precedent;
+// there a regex rewrite completes the update.
+//
+// HOW A NEW PIN IS DISCOVERED. The pinned tag is per-commit immutable
+// (`git-<sha12>`), so no datasource can order it and Renovate tracks the
+// moving `:latest` digest instead. The relock then resolves which immutable
+// tag `:latest` currently points at. That is sound because the publish lane
+// asserts `:latest` and `:git-<sha12>` share a config digest and fails closed
+// otherwise (.github/workflows/release.yml, publish-image).
+//
+// Needs `skopeo` and network on PATH. Reads are anonymous: the package is
+// public, so no registry credentials are required.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	AGENT_REPO,
+	EXIT,
+	isBuildTag,
+	lockFromInspect,
+	locksEqual,
+	PinError,
+	type PinLock,
+	renderLock,
+	validatePin,
+} from "./pin-core.ts";
+
+const LOCK_PATH = join(
+	import.meta.dir,
+	"..",
+	"..",
+	"guest-image",
+	"agent-oci.lock",
+);
+
+/** Where the moving tag lives. Only ever used to DISCOVER an immutable tag;
+ * never written into a lock. */
+const DISCOVERY_TAG = "latest";
+
+type Inspected = { digest: string; manifest: unknown };
+
+async function skopeo(args: string[]): Promise<string> {
+	const proc = Bun.spawn(["skopeo", ...args], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [out, err, code] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+	if (code !== 0) {
+		throw new PinError(
+			`skopeo ${args.join(" ")} failed (exit ${code}): ${err.trim()}`,
+			EXIT.registryFailed,
+		);
+	}
+	return out;
+}
+
+/** The manifest body, plus the digest OF THAT BODY.
+ *
+ * One fetch, hashed locally, because a manifest digest is by definition the
+ * sha256 of the manifest bytes (verified against the registry's own reported
+ * digest). Asking the registry separately would be two reads of a MUTABLE tag,
+ * so a publish landing between them would pair one manifest's body with
+ * another's digest — and the lock would describe layers the digest disowns. */
+async function inspect(reference: string): Promise<Inspected> {
+	const raw = await skopeo(["inspect", "--raw", `docker://${reference}`]);
+
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(raw);
+	} catch (err) {
+		throw new PinError(
+			`could not parse the manifest for ${reference}: ${String(err)}`,
+			EXIT.registryFailed,
+		);
+	}
+	const digest = `sha256:${new Bun.CryptoHasher("sha256").update(raw).digest("hex")}`;
+	return { digest, manifest };
+}
+
+/** The digest a reference resolves to, without pulling the manifest body.
+ * Tag discovery compares only digests, and the agent manifest is ~120 layers,
+ * so fetching bodies would download a lot to read one field. */
+async function resolvedDigest(reference: string): Promise<string> {
+	const meta = await skopeo([
+		"inspect",
+		"--format",
+		"{{.Digest}}",
+		`docker://${reference}`,
+	]);
+	const digest = meta.trim();
+	if (!digest) {
+		throw new PinError(
+			`skopeo reported no digest for ${reference}`,
+			EXIT.registryFailed,
+		);
+	}
+	return digest;
+}
+
+/** Resolve which immutable build tag `:latest` currently points at, by
+ * matching manifest digests. Fails loud rather than falling back to pinning
+ * `:latest`, which would defeat the whole lock.
+ *
+ * Newest-first: the registry lists tags oldest-first, and the tag we want is
+ * almost always the newest, so walking the list in order costs a round trip
+ * per historical tag (measured: ~115 misses, two minutes) to find the one at
+ * the end. Reversing makes the common case one probe. */
+async function discoverBuildTag(): Promise<string> {
+	const target = await resolvedDigest(`${AGENT_REPO}:${DISCOVERY_TAG}`);
+	const listed = await skopeo(["list-tags", `docker://${AGENT_REPO}`]);
+
+	let tags: unknown;
+	try {
+		tags = (JSON.parse(listed) as Record<string, unknown>).Tags;
+	} catch (err) {
+		throw new PinError(
+			`could not parse tag list: ${String(err)}`,
+			EXIT.registryFailed,
+		);
+	}
+	if (!Array.isArray(tags)) {
+		throw new PinError("registry returned no tag list", EXIT.registryFailed);
+	}
+
+	// Filter by the same predicate the lock validator enforces, not a looser
+	// `git-` prefix: a malformed `git-*` tag that matched the digest would be
+	// selected here and then hard-fail the whole relock downstream.
+	const candidates = tags.filter(isBuildTag).reverse();
+	for (const tag of candidates) {
+		if ((await resolvedDigest(`${AGENT_REPO}:${tag}`)) === target) return tag;
+	}
+	throw new PinError(
+		`no git-<sha12> tag resolves to the same manifest as :${DISCOVERY_TAG} (${target}) across ${candidates.length} candidate tag(s); the publish lane asserts the pair shares a digest, so this means an incoherent publish`,
+		EXIT.digestMismatch,
+	);
+}
+
+function readLock(): PinLock | undefined {
+	let body: string;
+	try {
+		body = readFileSync(LOCK_PATH, "utf8");
+	} catch {
+		return undefined;
+	}
+	try {
+		return validatePin(JSON.parse(body));
+	} catch (err) {
+		if (err instanceof PinError) throw err;
+		throw new PinError(
+			`${LOCK_PATH} is not valid JSON: ${String(err)}`,
+			EXIT.badLock,
+		);
+	}
+}
+
+async function pin(tag: string): Promise<number> {
+	const { digest, manifest } = await inspect(`${AGENT_REPO}:${tag}`);
+	const next = lockFromInspect(AGENT_REPO, tag, digest, manifest);
+
+	const current = readLock();
+	if (current && locksEqual(current, next)) {
+		console.log(`agent-oci.lock already pins ${tag} (${digest}) — no change`);
+		return 0;
+	}
+
+	writeFileSync(LOCK_PATH, renderLock(next));
+	console.log(
+		`pinned ${AGENT_REPO}:${tag}\n  digest: ${digest}\n  layers: ${next.layers.length}`,
+	);
+	return 0;
+}
+
+function usage(): number {
+	console.error(
+		"usage: bun tools/guest-image/pin-agent-image.ts --tag git-<sha12>\n" +
+			"       bun tools/guest-image/pin-agent-image.ts --relock",
+	);
+	return EXIT.usage;
+}
+
+async function main(): Promise<number> {
+	const argv = process.argv.slice(2);
+
+	if (argv.includes("--relock")) {
+		if (argv.length !== 1) return usage();
+		// Self-gate: a relock on a branch with no lock is a no-op, so the task
+		// stays cheap on every unrelated Renovate branch.
+		if (!readLock()) {
+			console.log("no agent-oci.lock on this branch — nothing to relock");
+			return 0;
+		}
+		return await pin(await discoverBuildTag());
+	}
+
+	const i = argv.indexOf("--tag");
+	const tag = i === -1 ? undefined : argv[i + 1];
+	if (tag === undefined || argv.length !== 2) return usage();
+	return await pin(tag);
+}
+
+try {
+	process.exit(await main());
+} catch (err) {
+	if (err instanceof PinError) {
+		console.error(`pin-agent-image: ${err.message}`);
+		process.exit(err.code);
+	}
+	throw err;
+}
diff --git a/tools/guest-image/pin-core.test.ts b/tools/guest-image/pin-core.test.ts
new file mode 100644
index 00000000..d1e133d5
--- /dev/null
+++ b/tools/guest-image/pin-core.test.ts
@@ -0,0 +1,289 @@
+import { describe, expect, test } from "bun:test";
+import {
+	AGENT_REPO,
+	digestRef,
+	EXIT,
+	isBuildTag,
+	isImageDigest,
+	layerDigests,
+	lockFromInspect,
+	locksEqual,
+	PinError,
+	type PinLock,
+	renderLock,
+	validatePin,
+} from "./pin-core.ts";
+
+const DIGEST =
+	"sha256:a2c90fd55c3e015c64a279973121d03c91736eed68d0cb0260cea9ff9b4ab94e";
+const LAYER_A =
+	"sha256:989a42bd3ddf0028fce105bf936074ae1cad375bbabf868ba358161d6eddea56";
+const LAYER_B =
+	"sha256:50173e59368b86248a8fc447563bc692eb54cea61522d423c562037b27273b1f";
+const TAG = "git-ec4954bd9400";
+
+const lock = (over: Partial<PinLock> = {}): PinLock => ({
+	repo: AGENT_REPO,
+	tag: TAG,
+	digest: DIGEST,
+	layers: [LAYER_A, LAYER_B],
+	...over,
+});
+
+const manifest = (over: Record<string, unknown> = {}) => ({
+	schemaVersion: 2,
+	mediaType: "application/vnd.oci.image.manifest.v1+json",
+	config: { mediaType: "application/vnd.oci.image.config.v1+json" },
+	layers: [
+		{
+			mediaType: "application/vnd.oci.image.layer.v1.tar+gzip",
+			digest: LAYER_A,
+			size: 898639,
+		},
+		{
+			mediaType: "application/vnd.oci.image.layer.v1.tar+gzip",
+			digest: LAYER_B,
+			size: 146238,
+		},
+	],
+	...over,
+});
+
+/** The exit code a thrown PinError carries, so a test names the fault class
+ * rather than just asserting that something threw. */
+const codeOf = (fn: () => unknown): number => {
+	try {
+		fn();
+	} catch (err) {
+		if (err instanceof PinError) return err.code;
+		throw err;
+	}
+	throw new Error("expected a PinError, nothing was thrown");
+};
+
+describe("validatePin provenance", () => {
+	test("rejects a repo other than the agent image", () => {
+		// The rootfs inherits this image's whole userland, so another repo
+		// silently swaps the agent out.
+		expect(
+			codeOf(() => validatePin(lock({ repo: "ghcr.io/evil/agent" }))),
+		).toBe(EXIT.provenance);
+	});
+
+	test("rejects a moving tag", () => {
+		expect(codeOf(() => validatePin(lock({ tag: "latest" })))).toBe(
+			EXIT.provenance,
+		);
+	});
+
+	test("rejects a git tag of the wrong hex width", () => {
+		expect(codeOf(() => validatePin(lock({ tag: "git-abc" })))).toBe(
+			EXIT.provenance,
+		);
+	});
+
+	test("rejects a non-hex git tag", () => {
+		expect(codeOf(() => validatePin(lock({ tag: "git-zzzzzzzzzzzz" })))).toBe(
+			EXIT.provenance,
+		);
+	});
+
+	test("accepts the publish lane's tag shape", () => {
+		expect(validatePin(lock()).tag).toBe(TAG);
+	});
+});
+
+describe("validatePin shape", () => {
+	test("rejects a malformed manifest digest", () => {
+		expect(codeOf(() => validatePin(lock({ digest: "sha256:abc" })))).toBe(
+			EXIT.badLock,
+		);
+	});
+
+	test("rejects a bare hex digest without its algorithm", () => {
+		expect(codeOf(() => validatePin(lock({ digest: DIGEST.slice(7) })))).toBe(
+			EXIT.badLock,
+		);
+	});
+
+	test("rejects an empty layer set, which would fetch nothing", () => {
+		expect(codeOf(() => validatePin(lock({ layers: [] })))).toBe(EXIT.badLock);
+	});
+
+	test("rejects a malformed layer digest", () => {
+		expect(
+			codeOf(() => validatePin(lock({ layers: [LAYER_A, "sha256:nope"] }))),
+		).toBe(EXIT.badLock);
+	});
+
+	test("rejects a non-object lock", () => {
+		expect(codeOf(() => validatePin([lock()]))).toBe(EXIT.badLock);
+		expect(codeOf(() => validatePin(null))).toBe(EXIT.badLock);
+	});
+
+	test("returns the layers in order", () => {
+		expect(validatePin(lock()).layers).toEqual([LAYER_A, LAYER_B]);
+	});
+});
+
+describe("lockFromInspect", () => {
+	test("builds a lock from the resolved digest and manifest", () => {
+		expect(lockFromInspect(AGENT_REPO, TAG, DIGEST, manifest())).toEqual(
+			lock(),
+		);
+	});
+
+	test("refuses a foreign repo before touching the manifest", () => {
+		expect(
+			codeOf(() =>
+				lockFromInspect("ghcr.io/other/img", TAG, DIGEST, manifest()),
+			),
+		).toBe(EXIT.provenance);
+	});
+
+	test("refuses a moving tag", () => {
+		expect(
+			codeOf(() => lockFromInspect(AGENT_REPO, "latest", DIGEST, manifest())),
+		).toBe(EXIT.provenance);
+	});
+
+	test("treats a malformed registry digest as a registry fault", () => {
+		// Distinct from a bad lock: nothing on disk is wrong, the registry
+		// answered with something unusable.
+		expect(
+			codeOf(() => lockFromInspect(AGENT_REPO, TAG, "garbage", manifest())),
+		).toBe(EXIT.registryFailed);
+	});
+});
+
+describe("layerDigests", () => {
+	test("refuses a multi-platform index", () => {
+		// An index would need a platform choice the lock has nowhere to record.
+		expect(
+			codeOf(() =>
+				layerDigests(
+					manifest({ mediaType: "application/vnd.oci.image.index.v1+json" }),
+				),
+			),
+		).toBe(EXIT.registryFailed);
+	});
+
+	test("refuses a docker v2 manifest", () => {
+		expect(
+			codeOf(() =>
+				layerDigests(
+					manifest({
+						mediaType: "application/vnd.docker.distribution.manifest.v2+json",
+					}),
+				),
+			),
+		).toBe(EXIT.registryFailed);
+	});
+
+	test("refuses an unexpected layer media type", () => {
+		expect(
+			codeOf(() =>
+				layerDigests(
+					manifest({
+						layers: [
+							{
+								mediaType: "application/vnd.oci.image.layer.v1.tar+zstd",
+								digest: LAYER_A,
+							},
+						],
+					}),
+				),
+			),
+		).toBe(EXIT.registryFailed);
+	});
+
+	test("refuses a manifest with no layers", () => {
+		expect(codeOf(() => layerDigests(manifest({ layers: [] })))).toBe(
+			EXIT.registryFailed,
+		);
+	});
+
+	test("preserves manifest order, which determines the stacked filesystem", () => {
+		// Asserted in BOTH directions on purpose: LAYER_B sorts before LAYER_A,
+		// so an extractor that sorted would still satisfy the flipped case alone.
+		expect(layerDigests(manifest())).toEqual([LAYER_A, LAYER_B]);
+
+		const flipped = manifest({
+			layers: [
+				{
+					mediaType: "application/vnd.oci.image.layer.v1.tar+gzip",
+					digest: LAYER_B,
+				},
+				{
+					mediaType: "application/vnd.oci.image.layer.v1.tar+gzip",
+					digest: LAYER_A,
+				},
+			],
+		});
+		expect(layerDigests(flipped)).toEqual([LAYER_B, LAYER_A]);
+	});
+});
+
+describe("locksEqual", () => {
+	test("an unchanged lock compares equal, so a relock no-ops", () => {
+		expect(locksEqual(lock(), lock())).toBe(true);
+	});
+
+	test("a moved digest compares unequal", () => {
+		expect(
+			locksEqual(lock(), lock({ digest: `sha256:${"b".repeat(64)}` })),
+		).toBe(false);
+	});
+
+	test("a reordered layer set compares unequal", () => {
+		// The bug the relock exists to catch: same bytes, different filesystem.
+		expect(locksEqual(lock(), lock({ layers: [LAYER_B, LAYER_A] }))).toBe(
+			false,
+		);
+	});
+
+	test("a dropped layer compares unequal", () => {
+		expect(locksEqual(lock(), lock({ layers: [LAYER_A] }))).toBe(false);
+	});
+});
+
+describe("rendering and refs", () => {
+	test("renders the exact committed bytes for a known lock", () => {
+		// Pinned against literal output, not against renderLock itself: the
+		// file is read by the nix eval and rewritten by the relock, so the
+		// indentation and key order ARE the contract. A self-comparison would
+		// pass for any deterministic implementation.
+		expect(renderLock(lock())).toBe(
+			`{\n\t"repo": "${AGENT_REPO}",\n\t"tag": "${TAG}",\n\t"digest": "${DIGEST}",\n\t"layers": [\n\t\t"${LAYER_A}",\n\t\t"${LAYER_B}"\n\t]\n}\n`,
+		);
+	});
+
+	test("renders valid JSON that round-trips through validatePin", () => {
+		expect(validatePin(JSON.parse(renderLock(lock())))).toEqual(lock());
+	});
+
+	test("ends with a newline", () => {
+		expect(renderLock(lock()).endsWith("}\n")).toBe(true);
+	});
+
+	test("pins by digest, never by tag", () => {
+		expect(digestRef(lock())).toBe(`${AGENT_REPO}@${DIGEST}`);
+		expect(digestRef(lock())).not.toContain(TAG);
+	});
+});
+
+describe("digest and tag predicates", () => {
+	test("isImageDigest requires the algorithm and full width", () => {
+		expect(isImageDigest(DIGEST)).toBe(true);
+		expect(isImageDigest(DIGEST.slice(0, 20))).toBe(false);
+		expect(isImageDigest(DIGEST.toUpperCase())).toBe(false);
+		expect(isImageDigest(undefined)).toBe(false);
+	});
+
+	test("isBuildTag accepts only the immutable publish tag", () => {
+		expect(isBuildTag(TAG)).toBe(true);
+		expect(isBuildTag("latest")).toBe(false);
+		expect(isBuildTag("git-ec4954bd940")).toBe(false);
+		expect(isBuildTag(`${TAG}-dirty`)).toBe(false);
+	});
+});
diff --git a/tools/guest-image/pin-core.ts b/tools/guest-image/pin-core.ts
new file mode 100644
index 00000000..27f0d936
--- /dev/null
+++ b/tools/guest-image/pin-core.ts
@@ -0,0 +1,240 @@
+// The pure core of the agent-image pin. Every function is a total map over its
+// inputs with no I/O, so pin-core.test.ts can drive each mapping — and each
+// fail-closed edge — without a registry or a subprocess.
+//
+// The guest rootfs derives from a PUBLISHED agent image rather than from the
+// agent's nix expressions, so the lock is the whole provenance story: it names
+// the one repo the rootfs may come from, an immutable per-commit tag, the
+// manifest digest those resolve to, and each layer descriptor digest the
+// fixed-output fetches key on. Provenance is enforced here rather than
+// documented, because a lock that pointed somewhere else would silently make
+// the rootfs unreproducible.
+
+/** Exit codes, numbered so a failed run names its own fault in CI. Distinct
+ * codes matter because the recoveries differ: 3 is a bad/hostile pin to
+ * correct, 4 is a registry/transport fault to retry, 5 means the registry no
+ * longer resolves the tag to the pinned digest (a re-pushed tag or a stale
+ * lock), 6 means the lock on disk is malformed. */
+export const EXIT = {
+	usage: 2,
+	provenance: 3,
+	registryFailed: 4,
+	digestMismatch: 5,
+	badLock: 6,
+} as const;
+
+/** The ONLY repo a guest rootfs may derive from. The rootfs inherits this
+ * image's entire userland, so accepting another repo would swap the agent
+ * — and its nixpkgs closure — for something unreviewed. */
+export const AGENT_REPO = "ghcr.io/rigelbuild/compass-agent";
+
+/** The publish lane's immutable per-commit tag (`git-` + 12 hex). `:latest`
+ * moves, so it is a DISCOVERY handle only and never what a lock pins. */
+const BUILD_TAG_PATTERN = /^git-[0-9a-f]{12}$/;
+
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+/** The agent image is a single-platform OCI manifest whose layers are gzipped
+ * tarballs; the pin refuses anything else rather than guessing, because an
+ * index would need a platform choice the lock has nowhere to record. */
+const MANIFEST_MEDIA_TYPE = "application/vnd.oci.image.manifest.v1+json";
+const LAYER_MEDIA_TYPE = "application/vnd.oci.image.layer.v1.tar+gzip";
+
+export type PinLock = {
+	repo: string;
+	tag: string;
+	digest: string;
+	layers: string[];
+};
+
+/** A pin fault that carries the exit code the CLI should die with, so the
+ * shell never has to re-derive which kind of failure it caught. */
+export class PinError extends Error {
+	readonly code: number;
+
+	constructor(message: string, code: number) {
+		super(message);
+		this.name = "PinError";
+		this.code = code;
+	}
+}
+
+export function isImageDigest(value: unknown): value is string {
+	return typeof value === "string" && DIGEST_PATTERN.test(value);
+}
+
+export function isBuildTag(value: unknown): value is string {
+	return typeof value === "string" && BUILD_TAG_PATTERN.test(value);
+}
+
+/** The immutable reference the nix fetches resolve. Never `repo:tag`: a tag is
+ * a mutable pointer, and GHCR has no server-side tag immutability. */
+export function digestRef(lock: PinLock): string {
+	return `${lock.repo}@${lock.digest}`;
+}
+
+/**
+ * Validate a lock parsed off disk, returning it narrowed.
+ *
+ * Throws rather than returning a partial lock: every caller (the nix eval's
+ * shape re-check, the relock's consistency gate) treats a malformed lock as
+ * fatal, and a lenient parse would let a half-valid lock reach a fetch.
+ */
+export function validatePin(value: unknown): PinLock {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new PinError("lock is not a JSON object", EXIT.badLock);
+	}
+	const lock = value as Record<string, unknown>;
+
+	if (lock.repo !== AGENT_REPO) {
+		throw new PinError(
+			`lock repo must be ${AGENT_REPO}, got ${JSON.stringify(lock.repo)}: the guest rootfs derives its whole userland from this image, so another repo would make it unreproducible`,
+			EXIT.provenance,
+		);
+	}
+	if (!isBuildTag(lock.tag)) {
+		throw new PinError(
+			`lock tag must match git-<12 hex>, got ${JSON.stringify(lock.tag)}: only the publish lane's per-commit tag is immutable, so a moving tag cannot be pinned`,
+			EXIT.provenance,
+		);
+	}
+	if (!isImageDigest(lock.digest)) {
+		throw new PinError(
+			`lock digest must be sha256:<64 hex>, got ${JSON.stringify(lock.digest)}`,
+			EXIT.badLock,
+		);
+	}
+	if (!Array.isArray(lock.layers) || lock.layers.length === 0) {
+		throw new PinError(
+			"lock layers must be a non-empty array: they are the fixed-output fetch keys, so an empty set would fetch nothing",
+			EXIT.badLock,
+		);
+	}
+	const layers = lock.layers.filter(isImageDigest);
+	if (layers.length !== lock.layers.length) {
+		const bad = lock.layers.find((l) => !isImageDigest(l));
+		throw new PinError(
+			`lock layers must each be sha256:<64 hex>, got ${JSON.stringify(bad)}`,
+			EXIT.badLock,
+		);
+	}
+
+	return {
+		repo: AGENT_REPO,
+		tag: lock.tag,
+		digest: lock.digest,
+		layers,
+	};
+}
+
+/**
+ * Build a lock from a `skopeo inspect --raw` manifest plus the digest the
+ * registry resolved for `tag`.
+ *
+ * The manifest digest is an INPUT, not something derived from the manifest
+ * body: it is what the registry returned for the tag, and recomputing it here
+ * would only re-assert our own hashing rather than what the registry serves.
+ */
+export function lockFromInspect(
+	repo: string,
+	tag: string,
+	digest: string,
+	manifest: unknown,
+): PinLock {
+	if (repo !== AGENT_REPO) {
+		throw new PinError(
+			`refusing to pin ${repo}: the guest rootfs may only derive from ${AGENT_REPO}`,
+			EXIT.provenance,
+		);
+	}
+	if (!isBuildTag(tag)) {
+		throw new PinError(
+			`refusing to pin tag ${JSON.stringify(tag)}: expected the publish lane's immutable git-<12 hex> tag`,
+			EXIT.provenance,
+		);
+	}
+	if (!isImageDigest(digest)) {
+		throw new PinError(
+			`registry returned a malformed digest for ${tag}: ${JSON.stringify(digest)}`,
+			EXIT.registryFailed,
+		);
+	}
+
+	return {
+		repo,
+		tag,
+		digest,
+		layers: layerDigests(manifest),
+	};
+}
+
+/**
+ * The layer descriptor digests, in manifest order.
+ *
+ * Order is load-bearing: the layers stack into the rootfs, so a reordered set
+ * would fetch the same bytes and unpack a different filesystem.
+ */
+export function layerDigests(manifest: unknown): string[] {
+	if (typeof manifest !== "object" || manifest === null) {
+		throw new PinError("manifest is not a JSON object", EXIT.registryFailed);
+	}
+	const m = manifest as Record<string, unknown>;
+
+	if (m.mediaType !== MANIFEST_MEDIA_TYPE) {
+		throw new PinError(
+			`expected a single-platform OCI manifest (${MANIFEST_MEDIA_TYPE}), got ${JSON.stringify(m.mediaType)}: an index would need a platform choice the lock cannot record`,
+			EXIT.registryFailed,
+		);
+	}
+	if (!Array.isArray(m.layers) || m.layers.length === 0) {
+		throw new PinError("manifest carries no layers", EXIT.registryFailed);
+	}
+
+	return m.layers.map((entry, i) => {
+		const layer: Record<string, unknown> =
+			typeof entry === "object" && entry !== null
+				? (entry as Record<string, unknown>)
+				: {};
+		if (layer.mediaType !== LAYER_MEDIA_TYPE) {
+			throw new PinError(
+				`layer ${i} has media type ${JSON.stringify(layer.mediaType)}, expected ${LAYER_MEDIA_TYPE}`,
+				EXIT.registryFailed,
+			);
+		}
+		const digest = layer.digest;
+		if (!isImageDigest(digest)) {
+			throw new PinError(
+				`layer ${i} has a malformed digest: ${JSON.stringify(digest)}`,
+				EXIT.registryFailed,
+			);
+		}
+		return digest;
+	});
+}
+
+/** Whether a relock would change anything. The relock self-gates on this so it
+ * is a cheap no-op on every unrelated Renovate branch. */
+export function locksEqual(a: PinLock, b: PinLock): boolean {
+	return (
+		a.repo === b.repo &&
+		a.tag === b.tag &&
+		a.digest === b.digest &&
+		a.layers.length === b.layers.length &&
+		a.layers.every((l, i) => l === b.layers[i])
+	);
+}
+
+/** Render a lock as the committed file body: stable key order and a trailing
+ * newline, so a relock that changed nothing produces a byte-identical file. */
+export function renderLock(lock: PinLock): string {
+	return `${JSON.stringify(
+		{
+			repo: lock.repo,
+			tag: lock.tag,
+			digest: lock.digest,
+			layers: lock.layers,
+		},
+		null,
+		"\t",
+	)}\n`;
+}
diff --git a/tools/guest-image/tsconfig.json b/tools/guest-image/tsconfig.json
new file mode 100644
index 00000000..d40cc9e5
--- /dev/null
+++ b/tools/guest-image/tsconfig.json
@@ -0,0 +1,11 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"lib": ["ES2022"],
+		"moduleDetection": "force",
+		"allowJs": true,
+		"allowImportingTsExtensions": true,
+		"noUncheckedIndexedAccess": true,
+		"types": ["bun"]
+	}
+}
diff --git a/tools/renovate/bot-config.json5 b/tools/renovate/bot-config.json5
index b35b0112..48a17b1a 100644
--- a/tools/renovate/bot-config.json5
+++ b/tools/renovate/bot-config.json5
@@ -82,7 +82,7 @@
   // addon, so the workflow sets RENOVATE_X_IGNORE_RE2=true to take the RegExp path
   // quietly.)
   //
-  // Seven entries, all load-bearing:
+  // Eight entries, all load-bearing:
   //   1. the toolchain-hash refresh, which re-prefetches the vendored-binary
   //      sha256 pins a tools/toolchain/versions/*.nix bump invalidates;
   //   2. the catalog lockfile regeneration. Renovate's custom.regex manager exports
@@ -130,9 +130,15 @@
   //      channel script's tail (biome eval, catalog pin, bun.lock, flake
   //      lockstep) has no counterpart in this scope: agent-image bakes no dev
   //      shell (`packages = [ ]`) and has no flake.
-  // (1), (3), (4), (5), (6), and (7) are `bun <script>.ts` — the Renovate hooks
-  // are TypeScript run via bun (AGENTS.md "Scripts: TypeScript over bash"); bun
-  // is on the runner PATH.
+  //   8. the guest-rootfs agent-image relock: on the moving `:latest` digest it
+  //      resolves which immutable `git-<sha12>` tag shares that manifest and
+  //      rewrites guest-image/agent-oci.lock's tag + digest + every layer
+  //      descriptor. The descriptors are the rootfs's fixed-output fetch keys
+  //      and Renovate cannot compute them, so a digest-only rewrite would
+  //      redden every fetch.
+  // (1), (3), (4), (5), (6), (7), and (8) are `bun <script>.ts` — the Renovate
+  // hooks are TypeScript run via bun (AGENTS.md "Scripts: TypeScript over
+  // bash"); bun is on the runner PATH.
   allowedCommands: [
     "^bun tools/renovate/refresh-toolchain-hashes\\.ts$",
     "^bun install --lockfile-only$",
@@ -141,5 +147,6 @@
     "^bun tools/renovate/refresh-go-overlay\\.ts$",
     "^bun tools/renovate/refresh-devenv-lock\\.ts$",
     "^bun tools/renovate/refresh-agent-image-nixpkgs\\.ts$",
+    "^bun tools/guest-image/pin-agent-image\\.ts --relock$",
   ],
 }
diff --git a/tools/renovate/config.json5 b/tools/renovate/config.json5
index 4e44621f..a673c94c 100644
--- a/tools/renovate/config.json5
+++ b/tools/renovate/config.json5
@@ -426,6 +426,37 @@
       datasourceTemplate: "docker",
       versioningTemplate: "docker",
     },
+    {
+      // ── Agent image the microVM guest rootfs derives from ──
+      // guest-image/agent-oci.lock pins the published compass-agent image the
+      // guest rootfs is built FROM, so an agent publish that never reaches this
+      // lock leaves the microVM backend running a stale agent indefinitely.
+      //
+      // Detection tracks the MOVING `:latest` digest, not the pinned tag: the
+      // lock pins an immutable per-commit `git-<sha12>`, which no datasource can
+      // order (there is no version in it to compare). The postUpgradeTask below
+      // resolves `:latest` back to whichever immutable tag currently shares its
+      // manifest, which is sound because the publish lane asserts the pair
+      // shares a config digest and fails closed (.github/workflows/release.yml).
+      //
+      // So the regex matches only the `digest` field, and `currentValue` is the
+      // literal `latest` the datasource can follow. The tag and layer fields are
+      // left for the relock — Renovate cannot compute the layer descriptor set.
+      //
+      // versioningTemplate is explicit `docker` for the same reason as the
+      // postgres pin above: a custom.regex manager defaults to `semver-coerced`
+      // regardless of datasource.
+      customType: "regex",
+      managerFilePatterns: ["/^guest-image/agent-oci\\.lock$/"],
+      matchStrings: [
+        "\"digest\": \"(?<currentDigest>sha256:[a-f0-9]{64})\"",
+      ],
+      depNameTemplate: "compass-agent-guest",
+      packageNameTemplate: "ghcr.io/rigelbuild/compass-agent",
+      currentValueTemplate: "latest",
+      datasourceTemplate: "docker",
+      versioningTemplate: "docker",
+    },
   ],
 
   // ── The github-actions manager: SHA-pin maintenance (RIG-2432) ──
@@ -852,6 +883,62 @@
         executionMode: "branch",
       },
     },
+    {
+      // ── Agent image currency: the microVM guest rootfs ──
+      // Solo-grouped like the devenv-fork rules above: its own groupName so it
+      // NEVER shares a branch with the "TypeScript dependencies" rollup (which
+      // also matches custom.regex) nor with any other branch-mode rule. That
+      // isolation is what makes the branch-mode postUpgradeTask safe — Renovate
+      // builds exactly ONE branch-mode task per branch, so a dep that never
+      // shares a branch owns that single slot. It is a docker pin like
+      // postgres-stack, but does NOT inherit that rule's soak — see below.
+      matchManagers: ["custom.regex"],
+      matchDepNames: ["compass-agent-guest"],
+      groupName: "compass-agent image (guest rootfs)",
+      // The repo-wide `minimumReleaseAge` + `internalChecksFilter: "strict"`
+      // measures age from a release timestamp, and this image HAS none: it is
+      // built by nix2container, which zeroes timestamps for reproducibility, so
+      // the registry reports `Created: 0001-01-01T00:00:00Z` (verified live).
+      // A strict cooldown over an unknown age keeps the digest permanently
+      // `pending` and cuts zero PRs — the stale-pin-forever outcome this rule
+      // exists to prevent. So the soak is nulled for THIS rule, matching the
+      // git-refs siblings and NOT the postgres pin, which keeps the soak
+      // precisely because Docker Hub carries a real timestamp for its digest.
+      // The compensating control is the mandatory human review before merge
+      // (no automerge is configured — see the top of this file).
+      minimumReleaseAge: null,
+      // Daily, in the same before-4am-ET window as the other currency rules:
+      // the agent image republishes on every push to main, so "keep current"
+      // means daily rather than on Renovate's default cadence.
+      schedule: ["before 4am"],
+      // ── The relock task. ──
+      // The regex update rewrites ONLY the digest, leaving `tag` and the
+      // per-layer descriptor set describing the PREVIOUS manifest. Those
+      // descriptors are the fixed-output fetch keys the rootfs derivation uses,
+      // so a digest-only bump would redden every fetch on every Renovate PR —
+      // the same stale-paired-field failure class refresh-devenv-lock.ts names
+      // for a rev-only rewrite, and the reason a bare regex manager is not
+      // sufficient here (unlike the digest-only postgres pin above, where the
+      // rewrite completes the update).
+      //
+      // The relock re-resolves the whole lock: it maps the moving `:latest`
+      // digest back to the immutable `git-<sha12>` tag that shares its
+      // manifest, then rewrites tag + digest + every layer descriptor together.
+      //
+      // fileFilters is an INCLUDE allowlist — Renovate commits ONLY matching
+      // files — and the lock is the only file this task writes. Listing less
+      // silent-drops the relock, shipping a digest bump whose layer set never
+      // moved.
+      //
+      // Self-hosted bot config MUST allow the command:
+      //   allowedCommands: [… , "^bun tools/guest-image/pin-agent-image\\.ts --relock$"]
+      // see tools/renovate/bot-config.json5 (config.test.ts pins them together).
+      postUpgradeTasks: {
+        commands: ["bun tools/guest-image/pin-agent-image.ts --relock"],
+        fileFilters: ["guest-image/agent-oci.lock"],
+        executionMode: "branch",
+      },
+    },
     {
       // ── devenv nixpkgs channel currency: agent base image ──
       // The agent-image sibling of the root channel rule above, scoped by the
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index f719f18d..bddc58ca 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -4,8 +4,10 @@ import { join } from "node:path";
 import botConfig from "./bot-config.json5";
 import config from "./config.json5";
 // The shipped FOD table. Imported (not restated) so the coverage guard at the
-// end re-derives its requirement from the declaration. Side-effect-safe: that
-// module does no I/O at import (main() is behind import.meta.main).
+// end of this file re-derives its requirement from the declaration itself.
+// Side-effect-safe: that module does no I/O at import (its main() is behind an
+// `import.meta.main` guard); the only load-time work is a fragment-disjointness
+// assertion over this same table.
 import { FOD_ENTRIES } from "./refresh-fod-hashes.ts";
 
 // Guard suite for compass's self-hosted Renovate config (RIG-2432). Covers compass's
@@ -192,29 +194,53 @@ const resolveGroupName = (dep: SyntheticDep): string | null | undefined => {
 };
 
 describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () => {
-	// postUpgradeTasks.commands are gated by the BOT config's allowedCommands
-	// allowlist, matched UNANCHORED via regEx(pattern).test(cmd) — so each entry's
-	// ^…$ IS the security property. Seven DISTINCT commands (the FOD refresh rides
-	// five sites under one entry, the devenv-fork relock both fork rules under one).
+	// postUpgradeTasks.commands are gated by the BOT config's global
+	// `allowedCommands` allowlist (a repo config cannot self-authorize a command),
+	// which Renovate matches UNANCHORED via regEx(pattern).test(cmd). So each
+	// entry's `^…$` IS the security property. Compass declares eight DISTINCT
+	// commands across the task sites (the FOD-hash refresh rides FIVE sites — see
+	// the per-site enumeration on the count test below — so it appears five times
+	// in the declared list but needs only one allowlist entry; the devenv-fork
+	// relock likewise rides BOTH devenv-fork rules under one command string, since
+	// the script self-gates on which lock changed); every
+	// distinct command must be permitted, every entry must be used, and no entry may
+	// be an unanchored substring rule. RIG-3100 added the fifth: the go↔go-overlay
+	// lockstep on the go pin's solo branch. RIG-2815 added the sixth: the
+	// devenv-fork relock on each devenv lock's solo branch. The seventh is the
+	// agent-image devenv-nixpkgs CHANNEL relock — the fourth devenv pin, on its
+	// own solo branch, with its own script because the root channel script's
+	// biome/catalog/bun.lock/flake tail has no counterpart in that scope. The
+	// eighth is the guest-rootfs agent-image relock, which rewrites the pinned
+	// tag, digest, and per-layer fetch keys together.
 	const commands = allDeclaredCommands();
 	const distinctCommands = [...new Set(commands)];
 	const allowed = bot.allowedCommands ?? [];
 
-	test("declares seven DISTINCT postUpgrade commands and seven allowlist entries", () => {
-		expect(distinctCommands).toHaveLength(7);
-		expect(allowed).toHaveLength(7);
+	test("declares eight DISTINCT postUpgrade commands and eight allowlist entries", () => {
+		expect(distinctCommands).toHaveLength(8);
+		expect(allowed).toHaveLength(8);
 	});
 
 	test("the fod-hash refresh is declared at all six task sites", () => {
-		// The command must ride every task shape that can own a bump moving a pinned
-		// FOD, because a rule-level task REPLACES the top-level one. The six sites:
-		// 1. top-level (gomod + bun/TS); 2. devenv-nixpkgs channel (moves pkgs.bun);
-		// 3. devenv fork root; 4. go↔go-overlay; 5. catalog; 6. fork agent-image.
-
-		// Sites 3, 4, 6 carry it fail-safe: each relocks ONE non-nixpkgs input, so
-		// none moves pkgs.bun today, but each writes a declared trigger of the
-		// entrypoint.nix entry, so the refresh is a no-op when nothing moved. The
-		// end-of-file guard keeps this true: a trigger site must run refresh LAST.
+		// The command must ride every task shape that can own a bump able to move a
+		// pinned FOD, because a rule-level task REPLACES the top-level one on its
+		// branch. The six sites, all carrying the refresh:
+		//   1. top-level (branch mode)      — gomod + bun/TypeScript-first branches
+		//   2. devenv-nixpkgs channel rule  — the channel moves pkgs.bun
+		//   3. devenv fork (root) rule      — relocks devenv.lock, a declared trigger
+		//   4. go ↔ go-overlay lockstep     — relocks devenv.lock likewise
+		//   5. workspaces.catalog rule      — update mode, eviction-proof
+		//   6. devenv fork (agent-image)    — relocks agent-image/devenv.lock, a
+		//                                     declared trigger of the same pin
+		// Sites 3, 4 and 6 carry it fail-safe: each relocks ONE non-nixpkgs input, so
+		// neither moves pkgs.bun today — but each writes a declared trigger of the
+		// entrypoint.nix entry, so the coupling holds at file granularity and the
+		// refresh's write is a no-op when nothing moved (the gate itself fires on
+		// those branches — the relocked devenv.lock IS the trigger — so the price
+		// is one extra realise, not nothing). The generalized guard at the end of
+		// this file is what keeps that coverage property true for future sites: it
+		// derives from FOD_ENTRIES that any site declaring a trigger must run the
+		// refresh LAST and name the pin's file.
 		expect(commands.filter((c) => c === FOD_COMMAND)).toHaveLength(6);
 		const topLevel = cfg.postUpgradeTasks?.commands ?? [];
 		expect(topLevel).toContain(FOD_COMMAND);
@@ -256,10 +282,11 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 		).toBe(false);
 	});
 
-	test("permits exactly the seven declared commands", () => {
+	test("permits exactly the eight declared commands", () => {
 		expect(distinctCommands.sort()).toEqual(
 			[
 				"bun install --lockfile-only",
+				"bun tools/guest-image/pin-agent-image.ts --relock",
 				"bun tools/renovate/refresh-agent-image-nixpkgs.ts",
 				"bun tools/renovate/refresh-devenv-lock.ts",
 				"bun tools/renovate/refresh-devenv-nixpkgs.ts",
@@ -272,10 +299,14 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 });
 
 describe("tools/renovate FOD-hash refresh wiring (PR #579)", () => {
-	// A dep bump moves a pinned Nix FOD hash; left stale the image build fails
-	// "hash mismatch". Renovate only COMMITS files a task's fileFilters name, so a
-	// task rewriting a FOD file without listing it silently drops the fix. This pins
-	// the two eviction-critical sites; the end-of-file guard covers every site.
+	// A dep bump moves a pinned Nix fixed-output-derivation hash; left stale the
+	// image build fails `hash mismatch in fixed-output derivation`. refresh-fod-
+	// hashes.ts recomputes it, but Renovate only COMMITS files a task's fileFilters
+	// name — so a task that rewrites a FOD file without listing it silently drops
+	// the fix and the bump PR still goes red. This describe pins the two
+	// eviction-critical sites named below site-by-site; the generalized guard at
+	// the end of this file covers the property across EVERY task site, present and
+	// future, deriving what each must declare from FOD_ENTRIES itself.
 	const topLevel = cfg.postUpgradeTasks;
 	const catalogRule = cfg.packageRules.find(
 		(r) =>
@@ -288,10 +319,13 @@ describe("tools/renovate FOD-hash refresh wiring (PR #579)", () => {
 	});
 
 	test("the top-level task commits ALL THREE Go/bun FOD files (fileFilters cover them)", () => {
-		// gomod + bun/npm-first branches inherit this slot; it must commit the Go
-		// vendorHash file, its flake.nix mirror (identical hash, refresh mirrors the
-		// value in), and the bun outputHash file. A missing flake.nix would drop the
-		// mirror edit → a gomod bump lands with flake.nix stale (RIG-2852 Gap 1).
+		// gomod branches + bun/npm-first branches inherit this slot; it must be able
+		// to commit the Go vendorHash file, its flake.nix mirror (identical hash,
+		// same buildGoModule proxyVendor set over go/ — refresh-fod-hashes.ts mirrors
+		// the recomputed value into it), and the bun outputHash file. Renovate only
+		// commits files a task's fileFilters names, so a missing flake.nix here would
+		// silently drop the mirror edit → a gomod bump lands with flake.nix's
+		// vendorHash stale and `nix flake check` red (RIG-2852 Gap 1).
 		expect(topLevel?.fileFilters).toContain("guest-image/default.nix");
 		expect(topLevel?.fileFilters).toContain("flake.nix");
 		expect(topLevel?.fileFilters).toContain("agent-image/entrypoint.nix");
@@ -320,10 +354,13 @@ describe("tools/renovate OSV vuln source honors the disable rules", () => {
 		expect(cfg.osvVulnerabilityAlerts).toBe(true);
 	});
 
-	// INVARIANT: a vuln fix is a packageRule carrying force: {...vulnerabilityAlerts},
-	// and applyPackageRules clears a prior skipReason when force.enabled is truthy —
-	// cancelling every enabled:false rule (postgres pin, gomod go, biome). The
-	// default object has no enabled key; assert it is absent.
+	// INVARIANT: a vuln fix is injected as a packageRule carrying
+	// `force: { ...vulnerabilityAlerts }`, and applyPackageRules clears a prior
+	// skipReason when force.enabled is truthy — which would CANCEL every
+	// `enabled: false` rule (the postgres CI-service pin, the gomod `go`
+	// directive, biome) and re-open the bumps they exist to hold shut. The
+	// default vulnerabilityAlerts object has no `enabled` key, so those disables
+	// hold; assert it is absent (never true).
 	test("does NOT set vulnerabilityAlerts.enabled (would re-open disabled bumps)", () => {
 		expect(cfg.vulnerabilityAlerts?.enabled).toBeUndefined();
 		expect(cfg.vulnerabilityAlerts?.enabled).not.toBe(true);
@@ -442,9 +479,10 @@ describe("tools/renovate root bun catalog manager", () => {
 
 describe("tools/renovate devenv nixpkgs lockstep", () => {
 	// The customManager surfacing devenv.lock's channel rev as a git-refs digest;
-	// find it by the dep it stamps, not index — and NOT by file pattern: the
-	// RIG-2815 devenv-FORK managers also match a devenv lock, so includes("devenv")
-	// would be ambiguous between three managers over the same two files.
+	// find it by the dep it stamps, not index — and NOT by file pattern alone:
+	// the RIG-2815 devenv-FORK managers also pattern-match a devenv lock, so a
+	// `includes("devenv")` finder would be ambiguous (order-dependent) between
+	// three managers over the same two files.
 	const devenvManager = cfg.customManagers?.find(
 		(m) => m.depNameTemplate === "cachix/devenv-nixpkgs",
 	);
@@ -502,8 +540,7 @@ describe("tools/renovate devenv nixpkgs lockstep", () => {
 
 	// Branch-mode lockstep task over the files the script writes: devenv.lock +
 	// package.json (biome catalog) + bun.lock (steps 2/4/5), flake.nix + flake.lock
-	// (step 6), and agent-image/entrypoint.nix (the FOD outputHash). compass has
-	// NO committed inner-rev guard file.
+	// (step 6), and agent-image/entrypoint.nix (the FOD outputHash).
 
 	// The FOD refresh is required: a channel bump moves pkgs.bun (the FOD builder)
 	// and, when the biome pin moves, re-resolves the bun.lock closure — either can
@@ -526,9 +563,11 @@ describe("tools/renovate devenv nixpkgs lockstep", () => {
 			"agent-image/entrypoint.nix",
 		]);
 		// Silent-drop guard (mirrors the top-level rule's flake.nix guard): step 6
-		// writes flake.nix + flake.lock, and fileFilters is an INCLUDE allowlist.
-		// Drop either and a channel bump ships with the flake skewed from devenv.lock
-		// → flake-parity reds while the script's own tests stay green.
+		// writes flake.nix + flake.lock, and fileFilters is an INCLUDE allowlist —
+		// Renovate commits ONLY listed files. Drop either from the filter and a
+		// channel bump ships with the flake skewed from devenv.lock → flake-parity
+		// reds on every bump while the script's own tests stay green. These two
+		// asserts turn that silent drop into a red test.
 		expect(task?.fileFilters).toContain("flake.nix");
 		expect(task?.fileFilters).toContain("flake.lock");
 		expect(task?.commands).toEqual([
@@ -557,10 +596,17 @@ describe("tools/renovate devenv nixpkgs lockstep", () => {
 });
 
 describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
-	// Both compass devenv scopes resolve github:RigelBuild/devenv by DEFAULT BRANCH,
-	// so the rev lives only in devenv.lock. Two customManagers surface the two locks'
-	// fork revs, each paired with its solo-branched relock rule. RD-1 keeps the locks
-	// on INDEPENDENT cadences, so this is two managers + two rules, not one pair.
+	// Both compass devenv scopes resolve github:RigelBuild/devenv by DEFAULT
+	// BRANCH, so the concrete rev lives only in devenv.lock and nothing moved it
+	// until T7. Two customManagers surface the two locks' fork revs as git-refs
+	// digests, each paired with its own solo-branched packageRule carrying the
+	// relock postUpgradeTask. RD-1 keeps the two locks on INDEPENDENT cadences
+	// (unify the source, do NOT reconcile the locks), which is why this is two
+	// managers + two rules + two groupNames and not one widened pair.
+	//
+	// Found by the dep each stamps, never by index or a bare "devenv" file-pattern
+	// substring (the devenv-nixpkgs channel manager pattern-matches the same root
+	// lock).
 	const RELOCK = "bun tools/renovate/refresh-devenv-lock.ts";
 	const forkScopes: {
 		label: string;
@@ -618,10 +664,15 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 			// The locks name no ref, so the tracked value is the default branch.
 			expect(manager?.currentValueTemplate).toBe("main");
 
-			// The file pattern must be ANCHORED to exactly this lock: a loose pattern
-			// would make the root manager extract from the agent-image lock too,
-			// collapsing the two scopes into one dep with conflicting digests. Pin the
-			// LITERAL first so a delimiter-semantics drift fails as a changed literal.
+			// The file pattern must be ANCHORED to exactly this lock: a loose
+			// pattern would make the root manager extract from the agent-image lock
+			// too (or vice versa), collapsing the two independent scopes into one
+			// dep with two files and two conflicting digests.
+			//
+			// Pin the LITERAL first, then re-parse it behaviourally below. The
+			// literal assertion is what makes a Renovate delimiter-semantics drift
+			// (e.g. how an unescaped interior `/` is read) fail as a changed literal
+			// rather than silently changing what the re-parse below is testing.
 			expect(manager?.managerFilePatterns).toEqual([patternLiteral]);
 			const pattern = manager?.managerFilePatterns?.[0];
 			const delimited = /^\/(.*)\/$/.exec(pattern as string);
@@ -635,10 +686,14 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 		},
 	);
 
-	// The matchString must recover EXACTLY ONE 40-hex rev from the REAL lock — the
-	// fork's own nodes.devenv.locked.rev. The anchor's safety is that "repo":
-	// "devenv", is followed by "rev" ONLY in the locked block (original is followed
-	// by "type"). Assert uniqueness so a lock-format change fails HERE.
+	// The matchString must recover EXACTLY ONE 40-hex rev from the REAL lock, and
+	// it must be the fork's own `nodes.devenv.locked.rev`. The anchor's whole
+	// safety argument is that `"repo": "devenv",` is followed by `"rev"` ONLY in
+	// the `locked` block — the `original` block repeats the repo but is followed
+	// by `"type"` (the input names no ref). Assert the uniqueness against ground
+	// truth so a devenv lock-format change fails HERE rather than silently
+	// binding to the wrong node (or to the `devenv-nixpkgs` node the channel
+	// manager owns).
 	test.each(forkScopes)(
 		"matchString extracts the fork rev from the real $label lock",
 		({ depName, lock }) => {
@@ -683,9 +738,13 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 	);
 
 	// Branch-mode relock over exactly the files the rule writes. fileFilters is an
-	// INCLUDE allowlist, so naming the sibling lock is dead surface and naming LESS
-	// silent-drops the relock. The root scope also carries the FOD refresh,
-	// relock-FIRST (its lock is a declared trigger of the entrypoint.nix pin).
+	// INCLUDE allowlist — Renovate commits ONLY listed files — so naming the
+	// sibling lock would be dead surface and naming LESS would silent-drop the
+	// relock, shipping a rev bump whose narHash/lastModified never moved (the same
+	// silent-drop mode the FOD guard above documents). The root scope additionally
+	// carries the FOD refresh, relock-FIRST: its lock is a declared trigger of the
+	// entrypoint.nix pin, and the reverse order would realise that pin against the
+	// still-at-base lock. The literal pins below turn a reordering into a red test.
 	test.each(forkScopes)(
 		"the $label relock postUpgradeTask is branch-mode over the files it writes",
 		({ depName, taskCommands, taskFileFilters }) => {
@@ -697,9 +756,10 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 	);
 
 	// ONE command string serves both rules — the script self-gates on WHICH lock
-	// changed — so a single anchored allowlist entry covers both. Assert the two
-	// rules share the string rather than drifting into two near-identical scripts
-	// (which would silently need a second allowlist entry).
+	// changed — so a single anchored allowlist entry covers both. This is the
+	// coupling the allowedCommands describe above counts; assert the two rules
+	// really do share the string rather than drifting into two near-identical
+	// scripts (which would silently need a second allowlist entry).
 	test("both fork rules declare the SAME relock command (one allowlist entry)", () => {
 		const declaring = cfg.packageRules.filter((r) =>
 			r.postUpgradeTasks?.commands?.includes(RELOCK),
@@ -710,10 +770,11 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 		).toEqual(["^bun tools/renovate/refresh-devenv-lock\\.ts$"]);
 	});
 
-	// The two locks must never land in ONE branch: two branch-mode relock tasks on a
-	// shared branch means Renovate builds only one and the other ships unrelocked.
-	// Replay last-match-wins semantics and assert each digest resolves to its own
-	// group, never the TS rollup.
+	// The two locks must never land in ONE branch: two branch-mode relock tasks
+	// on a shared branch means Renovate builds only one and the other lock ships
+	// rev-bumped-but-unrelocked. Replay the real last-match-wins packageRule
+	// semantics for each scope's digest and assert each resolves to its own
+	// group, never the TypeScript rollup (which also matches custom.regex).
 	test.each(forkScopes)(
 		"the $label fork digest resolves to its own solo branch, not the TS rollup",
 		({ depName, lock, groupName }) => {
@@ -733,10 +794,14 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 		expect(new Set(groups).size).toBe(forkScopes.length);
 	});
 
-	// M1 (RIG-2815 review): the relock nix runs the fork flakeref, which publishes
-	// no cache, so every rev is a from-source build — plausibly past Renovate's
-	// 15-min default timeout on a cold runner, which would kill the child and commit
-	// the regex bump unrelocked. Pin the raised ceiling. globalOnly, so bot-config.
+	// M1 (RIG-2815 review): the relock `nix run`s the fork flakeref, and the fork
+	// publishes no binary cache, so every fork rev is a from-source devenv build
+	// before the relock runs — measured minutes, plausibly past Renovate's 15-min
+	// default executionTimeout on a cold 2-vCPU runner. A timeout kills the child,
+	// the relock never runs, and Renovate still commits the regex bump (the exact
+	// half-relock this task exists to prevent). Pin the raised ceiling so a
+	// default change or accidental removal fails HERE, not as a nightly relock
+	// silently timing out. globalOnly, so it lives in bot-config.
 	test("bot-config sets an executionTimeout covering a cold fork build", () => {
 		expect(typeof bot.executionTimeout).toBe("number");
 		// Comfortably above the 15-min default; a cold from-source fork build can
@@ -744,10 +809,16 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 		expect(bot.executionTimeout).toBeGreaterThanOrEqual(30);
 	});
 
-	// M2 (RIG-2815 review): the relock's nix run needs the runner's nix.conf naming
-	// the devenv + cachix substituters and keys (the fork closure is not on
-	// cache.nixos.org). renovate.yml's extra_nix_config provides them; assert it
-	// still names both caches + keys so trimming them fails a test.
+	// M2 (RIG-2815 review): the relock's `nix run` depends on the runner's
+	// nix.conf naming the devenv + cachix substituters and their trusted keys —
+	// the fork's `#devenv` closure is not on cache.nixos.org and nix ignores the
+	// fork flake's own nixConfig non-interactively, so without these caches the
+	// realise cold-compiles the Nix fork from source and can exhaust the runner.
+	// Nothing in refresh-devenv-lock.ts provides them; renovate.yml's
+	// extra_nix_config does. Assert that block still names both caches + keys so
+	// trimming them there (e.g. once the PATH devenv-cli step is retired) fails a
+	// test rather than wedging the nightly relock. Same fail-closed posture as the
+	// self-pin workflow guard below (which already reads renovate.yml).
 	test("renovate.yml wires the substituters the relock nix run needs", () => {
 		const workflow = readFileSync(
 			join(repoRoot, ".github", "workflows", "renovate.yml"),
@@ -781,9 +852,11 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 	});
 
 	// L3 (RIG-2815 review): the two fork managers carry the SAME matchStrings
-	// literal (RD-1 forbids reconciling the rules; JSON5 has no anchor). Nothing else
-	// pins that they stay in sync, so a one-sided edit would drift silently. Assert
-	// they share one literal, mirroring the "same relock command" guard above.
+	// literal (RD-1 forbids reconciling the rules, and JSON5 has no anchor, so the
+	// duplication is deliberate). Nothing else pins that they stay in sync — each
+	// per-manager matchString test reads its own manager — so a one-sided edit
+	// would drift silently. Assert the two share one literal, mirroring the
+	// "same relock command" guard above.
 	test("both fork managers declare the IDENTICAL matchString literal", () => {
 		const literals = forkScopes.map(
 			(s) => managerFor(s.depName)?.matchStrings?.[0],
@@ -794,10 +867,15 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 });
 
 describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
-	// The fourth devenv pin. Three of the four were tracked; agent-image's CHANNEL
-	// rev was governed by no manager, so it only advanced by hand. This manager +
-	// rule pair gives it the same solo-branched, self-relocking shape as its
-	// siblings. Found by the dep it stamps: TWO managers now match this lock.
+	// The fourth devenv pin. Three of the four (root channel, root fork,
+	// agent-image fork) were tracked; agent-image's CHANNEL rev was governed by
+	// no manager at all, so it only advanced when someone relocked by hand. This
+	// manager + rule pair gives it the same solo-branched, self-relocking shape
+	// as its siblings.
+	//
+	// Found by the dep it stamps, never by index or a file-pattern substring:
+	// TWO managers now pattern-match agent-image/devenv.lock (this one and the
+	// fork manager), so a pattern-based finder would be order-dependent.
 	const REFRESH = "bun tools/renovate/refresh-agent-image-nixpkgs.ts";
 	const DEP = "cachix/devenv-nixpkgs-agent-image";
 	const LOCK = "agent-image/devenv.lock";
@@ -837,10 +915,12 @@ describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
 		expect(re.test(`a/${LOCK}`)).toBe(false); // anchored, no arbitrary prefix
 	});
 
-	// The matchString must recover EXACTLY ONE 40-hex rev from the REAL agent-image
-	// lock — the OUTER channel rev (nodes.nixpkgs.locked.rev), not the inner
-	// nixpkgs-src rev, the devenv FORK rev, or the original block (which repeats the
-	// repo but is followed by "ref", never "rev").
+	// The matchString must recover EXACTLY ONE 40-hex rev from the REAL
+	// agent-image lock, and it must be the OUTER channel rev
+	// (nodes.nixpkgs.locked.rev) — not the inner nixpkgs-src rev the relock
+	// refreshes from it, not the devenv FORK rev the sibling manager owns, and
+	// not the `original` block (which repeats `"repo": "devenv-nixpkgs"` but is
+	// followed by `"ref"`, never `"rev"` — the whole anchor-uniqueness argument).
 	test("matchString extracts the channel rev from the real agent-image lock", () => {
 		const lockText = readFileSync(join(repoRoot, LOCK), "utf8");
 		const matchString = manager?.matchStrings?.[0];
@@ -857,9 +937,10 @@ describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
 		expect(rev).not.toBe(parsed.nodes.devenv.locked.rev);
 	});
 
-	// It must not bind the ROOT lock — the file pattern is the only thing scoping
-	// it, so assert the two locks carry DIFFERENT channel revs today (RD-1) and
-	// that this manager's dep is the agent-image one.
+	// And it must not bind the ROOT lock at all — the manager's file pattern is
+	// the only thing scoping it, so assert the two locks really do carry
+	// DIFFERENT channel revs today (RD-1: unify the source, do NOT reconcile the
+	// locks) and that this manager's dep is the agent-image one.
 	test("the two scopes' channel revs are read independently, not reconciled", () => {
 		const agent = JSON.parse(readFileSync(join(repoRoot, LOCK), "utf8"));
 		const root = JSON.parse(
@@ -881,9 +962,10 @@ describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
 		).toBe(2);
 	});
 
-	// Solo-branched, scheduled, cooldown-nulled — its siblings' shape. The groupName
-	// must be UNIQUE: it makes the branch-mode relock task safe (one slot per branch)
-	// and keeps the two channel pins on independent cadences.
+	// Solo-branched, scheduled, cooldown-nulled — its siblings' shape. The
+	// groupName must be UNIQUE to this rule: it is what makes the branch-mode
+	// relock task safe (one branch-mode task slot per branch, so the dep must own
+	// its branch) AND what keeps the two channel pins on independent cadences.
 	test("the rule is solo-grouped, scheduled, and cooldown-exempt", () => {
 		expect(rule).toBeDefined();
 		expect(rule?.matchManagers).toContain("custom.regex");
@@ -898,10 +980,12 @@ describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
 		expect(rule?.minimumReleaseAge).toBeNull();
 	});
 
-	// Branch-mode task over EXACTLY the two files the script writes. fileFilters is
-	// an INCLUDE allowlist, so dropping entrypoint.nix would run the FOD refresh and
-	// silently discard it (hash mismatch on the image build), and dropping the lock
-	// would discard the relock.
+	// Branch-mode task over EXACTLY the two files the script writes. fileFilters
+	// is an INCLUDE allowlist — Renovate commits ONLY listed files — so dropping
+	// entrypoint.nix would run the FOD refresh and silently discard it, shipping
+	// a channel bump whose outputHash never moved (`hash mismatch in
+	// fixed-output derivation` on the image build), and dropping the lock would
+	// discard the relock itself.
 	test("the postUpgradeTask is branch-mode over the lock AND the FOD file", () => {
 		const task = rule?.postUpgradeTasks;
 		expect(task?.executionMode).toBe("branch");
@@ -909,10 +993,11 @@ describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
 		expect(task?.fileFilters).toEqual([LOCK, "agent-image/entrypoint.nix"]);
 	});
 
-	// A SEPARATE script from the root channel lockstep: the root script's tail
-	// (biome eval, catalog, bun.lock, flake) has no counterpart here. Assert the two
-	// rules do NOT share a command, so a "simplification" pointing this rule at the
-	// root script (relocking the ROOT lock on an agent-image branch) fails here.
+	// A SEPARATE script from the root channel lockstep, deliberately: the root
+	// script's tail (biome eval, catalog pin, bun.lock, flake lockstep) has no
+	// counterpart in this scope. Assert the two rules do NOT share a command, so
+	// a future "simplification" that points this rule at the root script — which
+	// would relock the ROOT lock on an agent-image branch — fails here.
 	test("does NOT reuse the root channel refresher", () => {
 		expect(rule?.postUpgradeTasks?.commands).not.toContain(
 			"bun tools/renovate/refresh-devenv-nixpkgs.ts",
@@ -926,10 +1011,11 @@ describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
 		).toEqual(["^bun tools/renovate/refresh-agent-image-nixpkgs\\.ts$"]);
 	});
 
-	// The two locks must never land in ONE branch, and this digest must never fold
-	// into the TS rollup — either puts two branch-mode tasks on one branch, where
-	// Renovate builds only one and the other ships unrelocked. Replay last-match-wins
-	// semantics.
+	// The two locks must never land in ONE branch, and this digest must never
+	// fold into the TypeScript rollup (which also matches custom.regex) — either
+	// would put two branch-mode tasks on one branch, where Renovate builds only
+	// one and the other pin ships bumped-but-unrelocked. Replay the real
+	// last-match-wins packageRule semantics.
 	test("the digest resolves to its own solo branch, not the TS rollup", () => {
 		const group = resolveGroupName({
 			manager: "custom.regex",
@@ -972,15 +1058,28 @@ describe("tools/renovate go ↔ go-overlay lockstep (RIG-3100)", () => {
 		expect(goOverlayRule?.matchDepNames).toContain("go");
 	});
 
-	// Branch-mode task over exactly the two files it writes: devenv.lock (the devenv
-	// update go-overlay re-lock) and the bun outputHash pin that re-lock invalidates
-	// (devenv.lock is a trigger of the entrypoint.nix FOD entry). It must NOT rewrite
-	// go.nix nor any other pin; fileFilters is an INCLUDE allowlist, so this pins it.
-
-	// Command order is load-bearing: re-lock FIRST, so the pin is realised against
-	// the written lock. Under a REVERSED order the go manager's scope never touches
-	// devenv.lock, so the FOD self-gate reads CLEAN and no-ops before the re-lock
-	// rewrites the lock — the refresh is silently SKIPPED, shipping the stale pin.
+	// Branch-mode task over exactly the two files it writes: devenv.lock (the
+	// `devenv update go-overlay` re-lock) and the bun outputHash pin that re-lock
+	// invalidates by declaration — devenv.lock is a trigger of the entrypoint.nix
+	// FOD entry, so the refresh rides here and its recomputed pin needs a filter
+	// slot to be committed. It must NOT rewrite go.nix (the go manager already
+	// did) nor any other hash pin, so listing anything else — guest-image/
+	// default.nix or flake.nix, whose entry triggers on go/go.mod|go.sum — would be
+	// dead filter surface; listing LESS would silent-drop the re-lock (shipping a
+	// go bump the overlay can't resolve → the exact CI red this task exists to
+	// prevent) or the refreshed pin. fileFilters is an INCLUDE allowlist, so this
+	// pins it. The command order is load-bearing: re-lock FIRST, so the pin is
+	// realised against the written lock. The failure mode under a REVERSED order
+	// differs here from the devenv-nixpkgs and devenv-fork sites: the go
+	// customManager's file scope is /^tools/toolchain/versions/go\.nix$/
+	// (config.json5:319), which never touches devenv.lock — so at the point a
+	// reversed refresh ran, the lock would still be byte-identical to base, its
+	// self-gate (`git diff --quiet <baseRef> -- devenv.lock`,
+	// refresh-fod-hashes.ts:265-274) would read CLEAN, and the refresh would
+	// no-op without realising anything; only THEN would `devenv update
+	// go-overlay` rewrite the lock. So the refresh is silently SKIPPED rather
+	// than realised against a stale lock — a different mechanism, the same end
+	// state: the bump ships the stale pin. Hence the literal pin below.
 	test("the lockstep postUpgradeTask is branch-mode over the files it writes", () => {
 		const task = goOverlayRule?.postUpgradeTasks;
 		expect(task?.executionMode).toBe("branch");
@@ -994,10 +1093,14 @@ describe("tools/renovate go ↔ go-overlay lockstep (RIG-3100)", () => {
 		]);
 	});
 
-	// Solo-branch safety: the branch-mode task slot is winner-take-all per branch,
-	// so this rule is safe ONLY because the go pin never shares a branch. The
-	// versions/*.nix un-group rule nulls its groupName, so a go bump solo-branches
-	// for BOTH minor and major (neither rule sets matchUpdateTypes).
+	// Solo-branch safety: the branch-mode task slot is winner-take-all per
+	// branch, so this rule is safe ONLY because the go pin never shares a branch.
+	// The versions/*.nix un-group rule nulls its groupName, so a go bump resolves
+	// to its own solo branch, never the TypeScript rollup — where it would
+	// collide with the top-level branch-mode task. Holds for BOTH minor and major
+	// bumps: the un-group rule has no matchUpdateTypes (fires for every type),
+	// and the go-overlay refresh rule likewise has none, so a major go bump also
+	// solo-branches and gets the overlay refresh on its own single task slot.
 	test.each(["minor", "major"] as const)(
 		"a go pin %s bump un-groups to its own solo branch (null), not the TS rollup",
 		(updateType) => {
@@ -1112,10 +1215,13 @@ describe("tools/renovate postgres + gomod go disables", () => {
 });
 
 describe("tools/renovate wails/v3 floor cap (RIG-2852, GTK4 migration)", () => {
-	// The GTK4 migration record freezes a "Never v3.1" floor: wails v3.1 removes the
-	// legacy GTK3 build tag, so an auto-opened v3.1 bump before the GTK4 flip would
-	// strand the app. A gomod rule caps wails/v3 below v3.1 via a REGEX allowedVersions
-	// (a semver range would wrongly reject the current v3.0.0 prerelease pin).
+	// The GTK4 migration record freezes a "Never v3.1" floor: wails v3.1 removes
+	// the legacy GTK3 build tag, so an auto-opened v3.1 bump before the GTK4 flip
+	// (RIG-2819) is proven would strand the app with no native shell. A gomod
+	// packageRule caps github.com/wailsapp/wails/v3 below v3.1 via a REGEX
+	// allowedVersions (not a semver range — gomod's node-semver ranges exclude a
+	// prerelease at a different major.minor.patch, so `< 3.1.0-0` would wrongly
+	// reject the current v3.0.0 prerelease pin). Find it by behavior, not index.
 	const wailsRule = cfg.packageRules.find(
 		(r) =>
 			r.matchManagers?.includes("gomod") &&
@@ -1134,10 +1240,13 @@ describe("tools/renovate wails/v3 floor cap (RIG-2852, GTK4 migration)", () => {
 	});
 
 	test("the cap admits the LIVE go.mod pin + future v3.0.x, rejects v3.1.x and v4+", () => {
-		// Compile the shipped regex and replay it. The load-bearing assertion reads
-		// the ACTUAL wails require line from go/go.mod and asserts the cap admits the
-		// pin — so a future pairing that opens zero PRs fails HERE, tied to ground
-		// truth. The boundary cases below pin the reject edge.
+		// Compile the shipped regex from its /.../ delimiters and replay it. The
+		// load-bearing assertion reads the ACTUAL wails require line from go/go.mod
+		// and asserts the cap admits whatever is pinned — so a future pin/regex
+		// pairing that would open zero PRs (the cap silently rejecting the real pin,
+		// the RIG-1220 freeze shape) fails HERE, tied to ground truth rather than a
+		// hard-coded literal. The boundary cases below then pin the reject edge so a
+		// fat-fingered cap (e.g. `^v?3\.`) that leaked v3.1 also fails.
 		const allowedVersions = wailsRule?.allowedVersions ?? "";
 		const matcher = new RegExp(allowedVersions.slice(1, -1));
 
@@ -1157,10 +1266,12 @@ describe("tools/renovate wails/v3 floor cap (RIG-2852, GTK4 migration)", () => {
 });
 
 describe("tools/renovate postgres-stack digest manager (RIG-2774, DL-260)", () => {
-	// DefaultPostgresImage is a standalone Go const the native managers can't see; a
-	// custom.regex manager surfaces it as a docker dep so postgres:18 digest rebuilds
-	// flow through a reviewable PR. DL-260 freezes the major at 18, so the paired rule
-	// pins allowedVersions to /^18$/. Find both by behavior, not index.
+	// DefaultPostgresImage (go/internal/stack/postgres_image.go) is a standalone Go
+	// const the native managers can't see; a custom.regex manager surfaces it as a
+	// docker dep so upstream postgres:18 rebuilds (same major, new digest) flow
+	// through a reviewable PR. DL-260 freezes the major at 18, so the paired
+	// packageRule pins allowedVersions to /^18$/ — the digest moves, an 18->19
+	// major never auto-opens. Find both by behavior, not index.
 	const pgManager = cfg.customManagers?.find((m) =>
 		m.managerFilePatterns?.some((p) => p.includes("postgres_image")),
 	);
@@ -1216,10 +1327,13 @@ describe("tools/renovate postgres-stack digest manager (RIG-2774, DL-260)", () =
 		expect(versionMatcher.test("19")).toBe(false);
 	});
 
-	// Load-bearing guard: the CI-service disable fence (matchDepNames ["postgres"],
-	// enabled false) is unscoped by manager/file, so a "postgres" depName here would
-	// inherit the disable and open ZERO PRs. Replay last-match-wins semantics for a
-	// synthetic postgres-stack docker dep and confirm it resolves ENABLED.
+	// Load-bearing behavioral guard: the CI-service disable fence
+	// (matchDepNames ["postgres"], enabled false) is unscoped by manager/file, so a
+	// `postgres` depName here would inherit the disable and open ZERO PRs. Replay
+	// Renovate's last-match-wins packageRule semantics (mirroring resolveGroupName's
+	// gates) for a synthetic postgres-stack docker dep and confirm it resolves
+	// ENABLED — this fails closed if the fence (or any future unscoped rule) ever
+	// swallows postgres-stack, silently defeating the automation.
 	const resolveEnabled = (dep: SyntheticDep): boolean => {
 		let enabled = true;
 		for (const rule of cfg.packageRules) {
@@ -1297,10 +1411,17 @@ describe("tools/renovate postgres-stack digest manager (RIG-2774, DL-260)", () =
 });
 
 describe("tools/renovate bun-types soak exemption ↔ bunfig excludes", () => {
-	// The catalog-scoped soak-exemption rule governs ONLY catalog deps, so its
-	// matchPackageNames must equal exactly the bunfig minimumReleaseAgeExcludes that
-	// ARE catalog deps — the bun-types pair. Other excludes are npm/overrides pins
-	// outside the catalog manager's reach; deriving from the manifest stays current.
+	// The catalog-scoped soak-exemption packageRule governs ONLY catalog deps
+	// (matchManagers custom.regex + matchDepTypes workspaces.catalog), so its
+	// matchPackageNames must equal exactly the bunfig `minimumReleaseAgeExcludes`
+	// entries that ARE catalog deps — i.e. the bun-types pair (@types/bun is a
+	// catalog pin; bun-types is its transitive lockstep). Every other bunfig
+	// exclude is a literal npm pin or an `overrides` pin (@tanstack/virtual-core,
+	// the Solid v2 / @tanstack query RC track, the two @rigelbuild/solid-* pins)
+	// outside the catalog manager's reach, so a catalog-scoped rule cannot and
+	// must not list them: a future auto-bump of those still soaks the 5 days.
+	// Deriving the catalog set from the real manifest (not a hard-coded list)
+	// keeps this guard current as the migration track lands and later retires.
 	const soakRule = cfg.packageRules.find(
 		(r) =>
 			r.minimumReleaseAge === null &&
@@ -1391,9 +1512,11 @@ describe("tools/renovate self-pin workflow (exact Renovate version)", () => {
 	});
 
 	// The preflight step probes with GH_TOKEN but classifies token-PRESENCE off
-	// RENOVATE_TOKEN, so the step MUST set RENOVATE_TOKEN, or index.ts short-circuits
-	// to reason="no-token" and exits 1 every run. Guard the env so that drop can't
-	// silently regress.
+	// RENOVATE_TOKEN (tools/renovate-preflight/index.ts) — so the step MUST set
+	// RENOVATE_TOKEN, or index.ts short-circuits to reason="no-token" and exits 1
+	// on every run, failing the job before Renovate starts. Guard the env so that
+	// drop can't silently regress (it shipped green once because nothing covered
+	// the preflight step's env).
 	test("the preflight step sets RENOVATE_TOKEN in its env", () => {
 		// Slice the preflight step: from its `- name: Preflight …` line to the
 		// next step boundary (`- name:`/`- uses:` at step indent) or EOF.
@@ -1408,34 +1531,60 @@ describe("tools/renovate self-pin workflow (exact Renovate version)", () => {
 });
 
 describe("tools/renovate FOD trigger coverage (every task site, derived from FOD_ENTRIES)", () => {
-	// THE CLASS THIS GUARDS. A pinned Nix FOD hash content-addresses a fetched
-	// dependency set, so a change to any trigger manifest invalidates it. A task
-	// naming a trigger in fileFilters may commit it, and Renovate commits ONLY listed
-	// files — shipping the lock with the pin on the OLD closure (PR #580).
-
-	// So the requirement is structural: any site that can write a declared trigger
-	// must ALSO run the refresh and name that entry's FOD file plus every mirrorFile
-	// (RIG-2852 Gap 1). The refresh self-gates on trigger change and fires here (a
-	// full realise); only the resulting WRITE is a no-op — one extra realise, worth it.
-
-	// Trigger sets are READ from FOD_ENTRIES, so adding a trigger or a new pinned FOD
-	// re-derives the requirement over every site automatically.
-
-	// DETECTION BOUNDARY. This reads fileFilters, so it misses a trigger written by
-	// Renovate's own manager update: the guest-image vendorHash triggers on
-	// go.mod/go.sum (gomod-manager-written), covered by assertion (top-level carries
-	// the refresh). A future rule-level gomod task would evict that slot unflagged.
-
-	// fileFilters entries are GLOB patterns, so coupling must be decided by glob
-	// match, not string equality — otherwise a site naming a trigger under a
-	// non-literal spelling is invisible here. Every entry is a literal path today,
-	// for which glob and equality coincide.
+	// THE CLASS THIS GUARDS. A pinned Nix fixed-output-derivation hash content-
+	// addresses a fetched dependency set, so it is invalidated by a change to any
+	// of the manifests refresh-fod-hashes.ts declares as that entry's `triggers`.
+	// A postUpgradeTask that names such a trigger in its fileFilters is declaring
+	// "this task may commit a change to that manifest" — and Renovate commits ONLY
+	// files a task's fileFilters names, so such a task ships the lock change while
+	// the pin beside it still addresses the OLD closure. The image build then fails
+	// `hash mismatch in fixed-output derivation` and the bump PR goes red — the
+	// failure that kept PR #580 red for weeks.
+	//
+	// So the requirement is structural, not per-site: any site that can write a
+	// declared trigger must ALSO run the refresh (to recompute the pin) and name
+	// that entry's FOD file plus every mirrorFile (or Renovate drops the recomputed
+	// pin on the floor — the RIG-2852 Gap 1 silent-drop shape). The refresh
+	// self-gates per entry on TRIGGER CHANGE, and devenv.lock is exactly what
+	// these tasks rewrite — so on those branches the gate FIRES rather than
+	// passing over: firing means writing a deliberately-fake SRI and running a
+	// full `nix build` of compass-guest-rootfs, a guaranteed fixed-output cache
+	// miss that forces a networked `bun install`. What is a no-op is the
+	// resulting WRITE (the same SRI), not the work. So covering a site whose
+	// installed tree did not actually move costs one extra rootfs realise per
+	// such branch (refresh-fod-hashes.ts:54: "costs at most one extra realise"),
+	// and no site's coverage gap is worth that price.
+	//
+	// The trigger sets are READ from FOD_ENTRIES rather than restated here, so
+	// adding a trigger or a new pinned FOD re-derives the requirement over every
+	// site automatically instead of needing a matching test edit.
+	//
+	// DETECTION BOUNDARY. What this reads is a site's fileFilters — i.e. the files
+	// the TASK declares it may commit. That misses the case where the trigger is
+	// written by Renovate's own manager update rather than by the task, because a
+	// manager's writes are never declared in fileFilters. The live instance is the
+	// guest-image/default.nix vendorHash: its triggers are go/go.mod and go/go.sum,
+	// which the gomod manager writes, so NO site names them and the pair below is
+	// empty for that entry — yet the pin still moves and the top-level task still
+	// has to refresh it. That leg is covered by assertion instead of derivation
+	// (the top-level site is pinned to carry the refresh, and gomod branches fall
+	// to the top-level slot because no rule-level task matches the gomod manager).
+	// A future rule-level task that matched gomod deps would evict that slot and
+	// this guard would NOT flag it; such a rule must carry the refresh, the FOD
+	// file, and its mirrorFiles by hand.
+
+	// fileFilters entries are GLOB patterns (Renovate matches them as globs, e.g.
+	// "**/*.js"), so coupling must be decided by glob match, not string equality —
+	// otherwise a site that names a trigger under any non-literal spelling is
+	// invisible here and the exact failure class this guard exists to catch ships
+	// silently. Every entry is a literal path today, for which a glob match and an
+	// equality test coincide.
 	const covers = (filters: string[], path: string): boolean =>
 		filters.some((filter) => new Bun.Glob(filter).match(path));
 
-	// Every declared task site, enumerated as allDeclaredCommands does: the
-	// top-level task plus every packageRule-level one. Labelled so a failure names
-	// the offending site.
+	// Every declared task site, enumerated exactly as allDeclaredCommands does:
+	// the top-level task plus every packageRule-level one. Labelled so a failure
+	// names the offending site rather than an index alone.
 	const taskSites: { label: string; task: PostUpgradeTasks }[] = [];
 	if (cfg.postUpgradeTasks) {
 		taskSites.push({ label: "top-level", task: cfg.postUpgradeTasks });
@@ -1461,20 +1610,29 @@ describe("tools/renovate FOD trigger coverage (every task site, derived from FOD
 	});
 
 	test("the coupled (site, entry) set has its expected shape (guard is not vacuous)", () => {
-		// The guard iterates coupled, so a thinned set would pass checking nothing.
-		// entrypoint.nix is carried by TWO entries sharing one trigger list, so
-		// renaming one trigger dissolves many pairings while the count stays positive.
-		// Pinning the exact count catches that; a new pairing updates this number.
-
-		// 12 = six sites naming a trigger of the two entrypoint.nix entries (2 × 6),
-		// plus the guestd vendorHash entry's zero pairs — its triggers go.mod/go.sum
-		// are written by the gomod MANAGER and named by no fileFilters.
+		// The guard below iterates `coupled`, so a set that emptied or thinned out
+		// would leave it passing while checking nothing. A bare `> 0` cannot see
+		// the thinning: the pairs bind only two of the three entries, and the
+		// entrypoint.nix pin is now carried by TWO entries (the authoritative
+		// write and its verify sibling) sharing one trigger list, so renaming a
+		// single trigger dissolves many pairings while leaving the count positive.
+		// Pinning the exact count catches a partial trigger rename, or a
+		// fileFilters edit, that dissolves any single pairing. It does NOT check
+		// WHICH sites are coupled — the per-site describes above pin that — only
+		// that the population has not shrunk or grown. A newly coupled site is a
+		// deliberate edit: update this number in the same change.
+		//
+		// 12 = six sites naming a trigger of the two entrypoint.nix entries
+		// (2 entries × 6 sites), plus the guestd vendorHash entry's zero pairs —
+		// its triggers are go/go.mod and go/go.sum, which the gomod MANAGER writes
+		// and no fileFilters names.
 		expect(coupled.length).toBe(12);
 		expect(taskSites.length).toBeGreaterThan(0);
 	});
 
-	// Violation messages, built outside the scan loop so the loop below stays the
-	// three predicates it checks.
+	// Violation messages, built outside the scan loop: each states the failure
+	// mechanism a maintainer needs, and keeping them here leaves the loop below
+	// as the three predicates it checks.
 	const missingRefresh = (context: string): string =>
 		`${context}, but does NOT run '${FOD_COMMAND}'. A task that commits ` +
 		`a trigger change without recomputing the pin ships a lockfile ` +
@@ -1506,9 +1664,14 @@ describe("tools/renovate FOD trigger coverage (every task site, derived from FOD
 		`the stale pin exactly as if no refresh ran.`;
 
 	// A command that refreshes the FOD pin IN-PROCESS rather than by shelling
-	// FOD_COMMAND. A script importing refreshFodEntries satisfies the guard; adding
-	// the command beside it would pay a SECOND realise. Each entry lists the call site
-	// that makes it true, so a script added without it fails the assertion.
+	// FOD_COMMAND. The guard's job is to ensure a site committing a trigger
+	// recomputes the pin; a script that imports refreshFodEntries and drives the
+	// same table satisfies that as completely as the standalone command, and
+	// adding the command beside it would pay a SECOND faked-pin realise (a full
+	// FOD cache miss plus a networked bun install) to rewrite a value already
+	// correct. Each entry is listed with the call site that makes it true, so this
+	// stays a per-script statement of fact and never a blanket exemption: a script
+	// added here without that call fails the assertion below.
 	const IN_PROCESS_REFRESHERS: Record<string, string> = {
 		// refresh-agent-image-nixpkgs.ts: relocks the agent-image channel, then
 		// awaits refreshFodEntries(agentImageFodEntries()) — the authoritative write
@@ -1568,3 +1731,101 @@ describe("tools/renovate FOD trigger coverage (every task site, derived from FOD
 		expect(coupled.flatMap(violationsFor)).toEqual([]);
 	});
 });
+
+describe("tools/renovate guest-rootfs agent-image pin lockstep", () => {
+	// guest-image/agent-oci.lock pins the published compass-agent image the
+	// microVM guest rootfs is built FROM. The lock carries the per-layer
+	// descriptor digests the rootfs's fixed-output fetches key on, which Renovate
+	// cannot compute — so the manager MUST be paired with a relock task, exactly
+	// like the devenv-lock pair and unlike the digest-only postgres pin. These
+	// assertions are what keep that pairing from being trimmed back to a bare
+	// regex bump, which would redden every fetch on every Renovate PR.
+	const DEP = "compass-agent-guest";
+	const RELOCK = "bun tools/guest-image/pin-agent-image.ts --relock";
+	const LOCK = "guest-image/agent-oci.lock";
+
+	const manager = cfg.customManagers?.find((m) => m.depNameTemplate === DEP);
+	const rule = cfg.packageRules.find((r) => r.matchDepNames?.includes(DEP));
+
+	test("a custom.regex manager surfaces the pin from the lock file", () => {
+		expect(manager).toBeDefined();
+		expect(manager?.customType).toBe("regex");
+		expect(manager?.packageNameTemplate).toBe(
+			"ghcr.io/rigelbuild/compass-agent",
+		);
+		expect(
+			manager?.managerFilePatterns?.some((p) => p.includes("agent-oci")),
+		).toBe(true);
+	});
+
+	test("detection rides the moving tag, because the pinned tag cannot be ordered", () => {
+		// The lock pins an immutable per-commit `git-<sha12>`; no datasource can
+		// order it, so the dep's currentValue is the moving `latest` and only the
+		// digest is matched.
+		expect(manager?.currentValueTemplate).toBe("latest");
+		expect(manager?.matchStrings?.join("")).toContain("currentDigest");
+	});
+
+	test("versioning is explicit docker, not the regex manager's semver default", () => {
+		// A custom.regex manager defaults to `semver-coerced` regardless of
+		// datasource, which mishandles a digest reference.
+		expect(manager?.datasourceTemplate).toBe("docker");
+		expect(manager?.versioningTemplate).toBe("docker");
+	});
+
+	test("the pin's rule runs the relock as a branch-mode task", () => {
+		expect(rule).toBeDefined();
+		expect(rule?.postUpgradeTasks?.commands).toContain(RELOCK);
+		// Branch mode is what gives the task the branch's single task slot.
+		expect(rule?.postUpgradeTasks?.executionMode).toBe("branch");
+	});
+
+	test("the rule is solo-grouped, so it owns that single task slot", () => {
+		// Sharing a branch with the rollup would contend for the one branch-mode
+		// slot and silently drop the relock.
+		expect(rule?.groupName).toBeDefined();
+		const sharing = cfg.packageRules.filter(
+			(r) => r.groupName === rule?.groupName,
+		);
+		expect(sharing).toHaveLength(1);
+	});
+
+	test("fileFilters permits the lock, so the relock's write is committed", () => {
+		// fileFilters is an INCLUDE allowlist: omit the lock and Renovate computes
+		// the relock and then drops it.
+		expect(rule?.postUpgradeTasks?.fileFilters).toContain(LOCK);
+	});
+
+	test("the relock command is permitted by an anchored allowlist entry", () => {
+		const allowed = bot.allowedCommands ?? [];
+		expect(allowed.some((a) => new RegExp(a).test(RELOCK))).toBe(true);
+		// …and the anchoring refuses an appended-metacharacter variant.
+		expect(allowed.some((a) => new RegExp(a).test(`${RELOCK}; id`))).toBe(
+			false,
+		);
+	});
+
+	test("the cooldown is nulled, so an unknown-age digest is not held forever", () => {
+		// nix2container zeroes timestamps for reproducibility, so this image
+		// reports Created: 0001-01-01T00:00:00Z and the repo-wide
+		// minimumReleaseAge + internalChecksFilter:"strict" would keep the digest
+		// permanently `pending` — zero PRs, pin stale forever. Unlike the
+		// postgres pin, which keeps the soak because its registry supplies a
+		// real timestamp.
+		expect(rule?.minimumReleaseAge).toBeNull();
+	});
+
+	test("the pin's dep resolves ENABLED, not swallowed by an unscoped rule", () => {
+		// Fails closed if any future rule disables this depName the way the
+		// `postgres` CI-service fence disables its namesake.
+		expect(
+			resolveGroupName({
+				manager: "custom.regex",
+				depName: "compass-agent-guest",
+				packageName: "ghcr.io/rigelbuild/compass-agent",
+				fileName: LOCK,
+				updateType: "digest",
+			}),
+		).toBe("compass-agent image (guest rootfs)");
+	});
+});