From d4ac94089c9fcf1e8a0be7b47a93c2d5a56cf260 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Tue, 25 Aug 2026 17:11:33 -0400
Subject: [PATCH 1/3] feat(renovate): auto-refresh pinned Nix FOD hashes on dep
 bump (RIG-2727)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A Renovate dependency bump moves a pinned Nix fixed-output-derivation (FOD) hash, but nothing regenerates it — so the bump PR fails CI on `hash mismatch in fixed-output derivation` and can't land without a manual hand-fix. PR #579 (`golang.org/x/net` → v0.56.0 security bump) hit exactly this: its `Gates (moon + pgtest)` job failed building `compass-guestd-go-modules.drv` because the gomod change moved the Go module set but left `guest-image/default.nix`'s pinned `vendorHash` stale.

Compass pins exactly two FOD hashes outside the vendored `forks/` trees:

- Go `vendorHash` (buildGoModule compass-guestd) in `guest-image/default.nix` — moved by a `go/go.mod` | `go/go.sum` bump (gomod manager).
- bun `outputHash` (recursive FOD of `bun install`) in `agent-image/entrypoint.nix` — moved by a `bun.lock` bump (bun/catalog manager).

Neither is a URL hash `nix store prefetch-file` can recompute (that is `refresh-toolchain-hashes.ts`'s job for the vendored-binary pins). A `vendorHash`/`outputHash` is only knowable by realising the derivation. `tools/renovate/refresh-fod-hashes.ts` self-gates per FOD on its trigger manifest, fakes the pin to force the mismatch, builds the guest-image rootfs vehicle (which realises both FODs, failing fast at the FOD before the heavy compile/pack), parses the reported `got:` SRI for that derivation, and writes it back — so the bump PR lands green.

Wired at two sites to survive Renovate's winner-take-all per-branch task slot: top-level `postUpgradeTasks` (branch mode — gomod and bun/npm-first branches) and the catalog `packageRule` (update mode — catalog-first branches, where the collapsed branch config evicts the top-level branch task). One command string → one anchored `allowedCommands` entry. Guarded by `config.test.ts` (command↔allowlist coupling, both-site wiring, fileFilters coverage) and a `refresh-fod-hashes.test.ts` regression suite. Verified end-to-end against real nix: the shipped script recomputes both hashes to their exact committed values.

Spec-impact: none. Refs #579. Refs RIG-2727

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/bot-config.json5           |  15 +-
 tools/renovate/config.json5               |  89 +++++-
 tools/renovate/config.test.ts             |  85 +++++-
 tools/renovate/refresh-fod-hashes.test.ts | 343 ++++++++++++++++++++++
 tools/renovate/refresh-fod-hashes.ts      | 248 ++++++++++++++++
 5 files changed, 753 insertions(+), 27 deletions(-)
 create mode 100644 tools/renovate/refresh-fod-hashes.test.ts
 create mode 100755 tools/renovate/refresh-fod-hashes.ts

diff --git a/tools/renovate/bot-config.json5 b/tools/renovate/bot-config.json5
index f4ac838f9..13f468653 100644
--- a/tools/renovate/bot-config.json5
+++ b/tools/renovate/bot-config.json5
@@ -56,7 +56,7 @@
   // addon, so the workflow sets RENOVATE_X_IGNORE_RE2=true to take the RegExp path
   // quietly.)
   //
-  // Three entries, all load-bearing:
+  // Four 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
@@ -68,11 +68,20 @@
   //   3. the devenv-nixpkgs lockstep, which re-locks devenv.lock at a new channel
   //      rev and rewrites the biome catalog pin to the version that rev bakes,
   //      keeping dev-shell baked==catalog parity.
-  // (1) and (3) are `bun <script>.ts` — the Renovate hooks are TypeScript run via
-  // bun (AGENTS.md "Scripts: TypeScript over bash"); bun is on the runner PATH.
+  //   4. the FOD-hash refresh, which recomputes the pinned Nix fixed-output-
+  //      derivation hashes a dep bump invalidates — the Go `vendorHash`
+  //      (guest-image/default.nix) on a gomod bump, the bun `outputHash`
+  //      (agent-image/entrypoint.nix) on a bun/catalog bump. Left stale the image
+  //      build fails `hash mismatch in fixed-output derivation` (PR #579). Wired at
+  //      both the top-level (branch mode) and catalog-rule (update mode)
+  //      postUpgradeTasks in config.json5 — one command string, so ONE allowlist
+  //      entry covers both sites.
+  // (1), (3), and (4) 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$",
     "^bun tools/renovate/refresh-devenv-nixpkgs\\.ts$",
+    "^bun tools/renovate/refresh-fod-hashes\\.ts$",
   ],
 }
diff --git a/tools/renovate/config.json5 b/tools/renovate/config.json5
index 179235aa8..660ffb85b 100644
--- a/tools/renovate/config.json5
+++ b/tools/renovate/config.json5
@@ -339,6 +339,22 @@
       enabled: false,
     },
     {
+      // ── Go dependency rollup + guestd vendorHash lockstep ──
+      // A gomod bump rewrites go/go.mod|go.sum, moving the fetched Go module set —
+      // which invalidates the pinned `vendorHash` in guest-image/default.nix
+      // (buildGoModule compass-guestd, no in-repo vendor/ dir). Nothing regenerates
+      // that hash on its own, so the guest-image nix build fails
+      // `hash mismatch in fixed-output derivation …-go-modules.drv` and the bump PR
+      // goes red (PR #579's exact failure). The refresh task recomputes it in the
+      // same branch so the PR lands green.
+      //
+      // The command is NOT declared here — it rides the TOP-LEVEL postUpgradeTasks
+      // (branch mode) below, which every gomod branch inherits (a gomod branch
+      // never shares the single branch-task slot with the catalog rule, whose task
+      // is `executionMode: "update"`). refresh-fod-hashes.ts self-gates on
+      // go/go.mod|go.sum, so it refreshes the Go vendorHash alone here and no-ops
+      // the bun outputHash. Keeping the command in one place (top-level) avoids a
+      // second branch-mode task that would compete for that slot.
       matchManagers: ["gomod"],
       matchUpdateTypes: ["patch", "minor"],
       groupName: "Go dependencies",
@@ -468,15 +484,33 @@
       // changing, so the evicted task would have been a no-op. It runs once per
       // catalog upgrade, which is harmless: `bun install --lockfile-only` is
       // idempotent and writes only bun.lock.
+      // The catalog-scoped task ALSO carries the FOD-hash refresh, for the same
+      // eviction reason it must carry the lockfile regen: a catalog bump changes
+      // compass-agent's installed node_modules tree (it consumes `catalog:` deps —
+      // effect, opentelemetry), which moves the pinned `outputHash` in
+      // agent-image/entrypoint.nix; left stale the agent/guest-image build fails
+      // `hash mismatch …-node-modules.drv`. The top-level branch-mode FOD task
+      // (below) is evicted on a catalog-FIRST rollup branch (the collapsed branch
+      // config spreads the alphabetically-first upgrade, and only ONE branch-mode
+      // task is built), so the refresh must ALSO ride this per-upgrade "update"
+      // pass to fire on every catalog branch regardless of sort order. Same command
+      // string as top-level → one allowlist entry; refresh-fod-hashes.ts self-gates
+      // on bun.lock so it refreshes the bun outputHash alone here and no-ops the Go
+      // vendorHash. Idempotent, so a double-fire (both passes on a bun-first branch)
+      // is harmless.
       //
-      // Self-hosted bot config MUST allow the command:
-      //   allowedCommands: [… , "^bun install --lockfile-only$"]
+      // Self-hosted bot config MUST allow both commands:
+      //   allowedCommands: [… , "^bun install --lockfile-only$",
+      //                          "^bun tools/renovate/refresh-fod-hashes\\.ts$"]
       // see tools/renovate/bot-config.json5 (config.test.ts pins the two together).
       matchManagers: ["custom.regex"],
       matchDepTypes: ["workspaces.catalog"],
       postUpgradeTasks: {
-        commands: ["bun install --lockfile-only"],
-        fileFilters: ["bun.lock"],
+        commands: [
+          "bun install --lockfile-only",
+          "bun tools/renovate/refresh-fod-hashes.ts",
+        ],
+        fileFilters: ["bun.lock", "agent-image/entrypoint.nix"],
         executionMode: "update",
       },
     },
@@ -496,24 +530,47 @@
     },
   ],
 
-  // ── Toolchain hash coupling ──
-  // A versions/*.nix toolchain pin bump (bun/node/moon) leaves the vendored-binary
-  // sha256 pins beside each version stale → the dev-shell/CI build fails. This
-  // script re-prefetches and rewrites all three platform legs in each changed pin
-  // file in the same branch so the bump PR lands green. It self-gates (no-op unless
-  // a versions/*.nix pin changed), so it's cheap on every other branch — and it
-  // no-ops on go.nix, whose hashes come from go-overlay, not a per-file pin.
-  // `executionMode: branch` runs it once per branch after the update is applied.
+  // ── Toolchain hash + FOD hash coupling (top-level branch-mode tasks) ──
+  // Two refreshers ride the single per-branch task slot Renovate builds from the
+  // collapsed branch config; both self-gate on their trigger files, so each is a
+  // cheap no-op on a branch it doesn't apply to.
+  //
+  //  1. refresh-toolchain-hashes.ts — a versions/*.nix toolchain pin bump
+  //     (bun/node/moon) leaves the vendored-binary sha256 pins beside each version
+  //     stale → the dev-shell/CI build fails. Re-prefetches and rewrites all three
+  //     platform legs in each changed pin file in the same branch. Self-gates (no-op
+  //     unless a versions/*.nix pin changed); no-ops on go.nix, whose hashes come
+  //     from go-overlay.
+  //  2. refresh-fod-hashes.ts — a gomod bump (go/go.mod|go.sum) moves the pinned
+  //     Go vendorHash in guest-image/default.nix; a bun bump (bun.lock) moves the
+  //     pinned bun outputHash in agent-image/entrypoint.nix. Left stale the
+  //     guest-image/agent-image build fails `hash mismatch in fixed-output
+  //     derivation` (PR #579). Recomputes the invalidated hash by realising it.
+  //     Self-gates per FOD on its trigger manifest. This is the branch-mode leg
+  //     that covers gomod branches and bun/npm-first TypeScript-rollup branches;
+  //     catalog-FIRST rollup branches evict this whole top-level task (their
+  //     collapsed config carries the catalog rule's update-mode task instead), so
+  //     the SAME fod command also rides that rule above — one command, one
+  //     allowlist entry, idempotent on a double-fire.
   //
-  // Self-hosted bot config MUST allow the command:
-  //   allowedCommands: ["^bun tools/renovate/refresh-toolchain-hashes\\.ts$"]
-  // and the runner needs `nix` (nix-command) on PATH.
+  // `executionMode: branch` runs each once per branch after the update is applied.
+  //
+  // Self-hosted bot config MUST allow both commands:
+  //   allowedCommands: ["^bun tools/renovate/refresh-toolchain-hashes\\.ts$",
+  //                     "^bun tools/renovate/refresh-fod-hashes\\.ts$"]
+  // and the runner needs `nix` (nix-command) on PATH (refresh-fod-hashes realises
+  // a nix build; refresh-toolchain-hashes prefetches).
   postUpgradeTasks: {
-    commands: ["bun tools/renovate/refresh-toolchain-hashes.ts"],
+    commands: [
+      "bun tools/renovate/refresh-toolchain-hashes.ts",
+      "bun tools/renovate/refresh-fod-hashes.ts",
+    ],
     fileFilters: [
       "tools/toolchain/versions/bun.nix",
       "tools/toolchain/versions/node.nix",
       "tools/toolchain/versions/moon.nix",
+      "guest-image/default.nix",
+      "agent-image/entrypoint.nix",
     ],
     executionMode: "branch",
   },
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index e26945640..667058905 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -188,15 +188,36 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 	// 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 has exactly 3 commands and 3
-	// allowlist entries; every command must be permitted, every entry must be used,
-	// and no entry may be an unanchored substring rule.
+	// entry's `^…$` IS the security property. Compass declares four DISTINCT
+	// commands across the task sites (the FOD-hash refresh rides two sites — the
+	// top-level branch-mode task and the catalog rule's update-mode task — so it
+	// appears twice in the declared list but needs only one allowlist entry); every
+	// distinct command must be permitted, every entry must be used, and no entry may
+	// be an unanchored substring rule.
 	const commands = allDeclaredCommands();
+	const distinctCommands = [...new Set(commands)];
 	const allowed = bot.allowedCommands ?? [];
 
-	test("declares exactly three postUpgrade commands and three allowlist entries", () => {
-		expect(commands).toHaveLength(3);
-		expect(allowed).toHaveLength(3);
+	test("declares four DISTINCT postUpgrade commands and four allowlist entries", () => {
+		expect(distinctCommands).toHaveLength(4);
+		expect(allowed).toHaveLength(4);
+	});
+
+	test("the fod-hash refresh is declared at BOTH task sites (top-level + catalog)", () => {
+		// The command must ride two sites so it fires on every branch shape: the
+		// top-level branch-mode slot (gomod + bun/npm-first branches) AND the catalog
+		// rule's update-mode pass (catalog-first branches evict the top-level slot).
+		// If it collapses to one site, one of those branch shapes ships a stale FOD
+		// pin — PR #579's failure. So the raw (non-deduped) list carries it twice.
+		const fod = "bun tools/renovate/refresh-fod-hashes.ts";
+		expect(commands.filter((c) => c === fod)).toHaveLength(2);
+		const topLevel = cfg.postUpgradeTasks?.commands ?? [];
+		expect(topLevel).toContain(fod);
+		const catalogRule = cfg.packageRules.find(
+			(r) =>
+				r.matchDepTypes?.includes("workspaces.catalog") && r.postUpgradeTasks,
+		);
+		expect(catalogRule?.postUpgradeTasks?.commands).toContain(fod);
 	});
 
 	test("every declared command is permitted by an anchored allowlist entry", () => {
@@ -222,19 +243,67 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 				new RegExp(a).test("bun install --lockfile-only; id"),
 			),
 		).toBe(false);
+		// …including on the FOD command (a `; rm -rf` tail must not slip through).
+		expect(
+			allowed.some((a) =>
+				new RegExp(a).test("bun tools/renovate/refresh-fod-hashes.ts; id"),
+			),
+		).toBe(false);
 	});
 
-	test("permits exactly the three RIG-2432 commands", () => {
-		expect(commands.sort()).toEqual(
+	test("permits exactly the four RIG-2432 commands", () => {
+		expect(distinctCommands.sort()).toEqual(
 			[
 				"bun install --lockfile-only",
 				"bun tools/renovate/refresh-devenv-nixpkgs.ts",
+				"bun tools/renovate/refresh-fod-hashes.ts",
 				"bun tools/renovate/refresh-toolchain-hashes.ts",
 			].sort(),
 		);
 	});
 });
 
+describe("tools/renovate FOD-hash refresh wiring (PR #579)", () => {
+	// 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. Guard both sites' fileFilters.
+	const FOD = "bun tools/renovate/refresh-fod-hashes.ts";
+	const topLevel = cfg.postUpgradeTasks;
+	const catalogRule = cfg.packageRules.find(
+		(r) =>
+			r.matchDepTypes?.includes("workspaces.catalog") && r.postUpgradeTasks,
+	);
+
+	test("the top-level branch-mode task runs the fod refresh and is branch mode", () => {
+		expect(topLevel?.commands).toContain(FOD);
+		expect(topLevel?.executionMode).toBe("branch");
+	});
+
+	test("the top-level task commits BOTH FOD files (fileFilters cover them)", () => {
+		// gomod branches + bun/npm-first branches inherit this slot; it must be able
+		// to commit both the Go vendorHash file and the bun outputHash file.
+		expect(topLevel?.fileFilters).toContain("guest-image/default.nix");
+		expect(topLevel?.fileFilters).toContain("agent-image/entrypoint.nix");
+	});
+
+	test("the catalog rule runs the fod refresh in UPDATE mode (eviction-proof)", () => {
+		// A catalog-first rollup branch evicts the top-level branch task, so the
+		// refresh must also ride the catalog rule's per-upgrade update pass.
+		expect(catalogRule?.postUpgradeTasks?.commands).toContain(FOD);
+		expect(catalogRule?.postUpgradeTasks?.executionMode).toBe("update");
+	});
+
+	test("the catalog task commits the bun outputHash file it can move", () => {
+		// A catalog bump moves the bun outputHash (compass-agent consumes catalog:
+		// deps); it never touches the Go module set, so only entrypoint.nix is listed.
+		expect(catalogRule?.postUpgradeTasks?.fileFilters).toContain(
+			"agent-image/entrypoint.nix",
+		);
+	});
+});
+
 describe("tools/renovate OSV vuln source honors the fork fence", () => {
 	// Renovate owns security remediation. OSV is the config-driven vuln source
 	// that respects the forks/*/** disable packageRule, unlike a repo-wide toggle.
diff --git a/tools/renovate/refresh-fod-hashes.test.ts b/tools/renovate/refresh-fod-hashes.test.ts
new file mode 100644
index 000000000..3a4e3a0ef
--- /dev/null
+++ b/tools/renovate/refresh-fod-hashes.test.ts
@@ -0,0 +1,343 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmod, mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { $ } from "bun";
+import {
+	FOD_ENTRIES,
+	type FodEntry,
+	parseGotForFragment,
+	rewriteInlineHash,
+} from "./refresh-fod-hashes.ts";
+
+// Regression + unit test for tools/renovate/refresh-fod-hashes.ts (PR #579).
+//
+// The bug this guards against: a dependency bump moves a pinned Nix
+// fixed-output-derivation hash (the Go `vendorHash` in guest-image/default.nix on
+// a gomod bump; the bun `outputHash` in agent-image/entrypoint.nix on a bun/
+// catalog bump), and nothing regenerates it, so the image build fails
+// `hash mismatch in fixed-output derivation` and the bump PR goes red. The
+// refresher recomputes the hash IN the bump branch so the PR lands green.
+//
+// The failure mode is precisely the script's cwd × git-cwd-relative-pathspec
+// gate interaction plus the fake-hash→build→parse-`got:` recovery — only a real
+// run in a real git repo exercises it. So this drives the ACTUAL shipped script
+// (never a re-implementation) inside a throwaway git tree with a FAKE `nix` on
+// PATH that emits the `hash mismatch … got: <sri>` shape keyed to the faked pin.
+//
+// Network-free & deterministic: the stub `nix` derives a stable `got:` SRI from
+// the drv fragment it's asked to build, so a run is fully offline and asserting a
+// pin took the fragment-specific stub value proves both that the per-FOD gate
+// fired AND that the correct derivation's hash was parsed and written back.
+//
+// The fixture layout, trigger files, and pin markers are DERIVED from the
+// script's own exported FOD_ENTRIES table, so a rebase that edits the table keeps
+// this test honest without a second edit.
+
+const SCRIPT_REL = "tools/renovate/refresh-fod-hashes.ts";
+const REAL_SCRIPT = join(import.meta.dir, "refresh-fod-hashes.ts");
+
+// Resolve each FOD entry from the shipped table, throwing on drift so the fixture
+// follows the script. A returning helper (not a top-level `if (!x) throw`) gives a
+// non-nullable type that narrows into the closures below.
+function mustFind(fragment: string): FodEntry {
+	const entry = FOD_ENTRIES.find((e) => e.drvFragment === fragment);
+	if (!entry) {
+		throw new Error(`fixture drift: expected a '${fragment}' FOD entry`);
+	}
+	return entry;
+}
+const GO_ENTRY = mustFind("go-modules");
+const BUN_ENTRY = mustFind("node-modules");
+
+// Hermetic git: no user/global/system config leakage, identity from env only.
+const HERMETIC_ENV = {
+	...process.env,
+	GIT_CONFIG_GLOBAL: "/dev/null",
+	GIT_CONFIG_SYSTEM: "/dev/null",
+	GIT_AUTHOR_NAME: "PR579 test",
+	GIT_AUTHOR_EMAIL: "pr579@example.invalid",
+	GIT_COMMITTER_NAME: "PR579 test",
+	GIT_COMMITTER_EMAIL: "pr579@example.invalid",
+};
+
+// A distinct placeholder SRI per pinned FOD file so an accidental rewrite is
+// unmistakable and unrelated lines stay distinguishable. None equals a stub value.
+const PLACEHOLDER_GO = "sha256-PLACEHOLDERgovendor00000000000000000000=";
+const PLACEHOLDER_BUN = "sha256-PLACEHOLDERbunoutput00000000000000000000=";
+
+// Minimal nix files carrying the real markers the script keys on. The script only
+// reads/rewrites the marker line, so the surrounding nix need not be buildable —
+// the fake `nix` never actually evaluates it. The marker already ends in
+// `sha256-`, so interpolate the placeholder body WITHOUT its own `sha256-` prefix
+// (else the line carries `sha256-sha256-…`).
+const bodyOf = (sri: string) => sri.replace(/^sha256-/, "");
+const GO_NIX_FIXTURE = `let
+  guestd = pkgs.buildGoModule {
+    ${GO_ENTRY.marker}${bodyOf(PLACEHOLDER_GO)}";
+  };
+in guestd
+`;
+const BUN_NIX_FIXTURE = `let
+  nodeModules = pkgs.stdenv.mkDerivation {
+    ${BUN_ENTRY.marker}${bodyOf(PLACEHOLDER_BUN)}";
+  };
+in nodeModules
+`;
+
+// A fake `nix`: parse the `-f <file> <target>` build request and emit a
+// `hash mismatch` block for BOTH FODs (the real build with --keep-going reports
+// every stale FOD), each with a fragment-derived deterministic `got:` SRI. Shape
+// matches what parseGotForFragment scans for. Offline.
+const STUB_NIX = `#!/usr/bin/env bash
+# Ignore all args; emit the mismatch shape for both known FODs to stderr.
+emit() {
+  local frag="$1"
+  local digest
+  digest="$(printf %s "$frag" | sha256sum | cut -d' ' -f1)"
+  echo "error: hash mismatch in fixed-output derivation '/nix/store/deadbeef-compass-\${frag}.drv':" >&2
+  echo "         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" >&2
+  echo "            got:    sha256-stub-\${digest}" >&2
+}
+emit go-modules
+emit node-modules
+exit 1
+`;
+
+// Mirror the stub's fragment→SRI derivation so the expected value is computable
+// in-process.
+function stubSriForFragment(fragment: string): string {
+	const hasher = new Bun.CryptoHasher("sha256");
+	hasher.update(fragment);
+	return `sha256-stub-${hasher.digest("hex")}`;
+}
+
+// The `sha256-…` value on the marker line of a pin file.
+function hashOnMarker(nixText: string, marker: string): string | undefined {
+	const line = nixText.split("\n").find((l) => l.includes(marker));
+	return line?.match(/sha256-[^"]*/)?.[0];
+}
+
+// Build a throwaway repo mirroring the minimal repo-root layout and commit it as
+// the `main` baseline: both pin files, both trigger manifests, the shipped script.
+async function buildBaselineRepo(): Promise<string> {
+	const repo = await mkdtemp(join(tmpdir(), "pr579-"));
+	const write = async (rel: string, body: string) => {
+		const abs = join(repo, rel);
+		await mkdir(dirname(abs), { recursive: true });
+		await Bun.write(abs, body);
+	};
+
+	// Exercise the SHIPPED script, not a hand-copy.
+	await write(SCRIPT_REL, await readFile(REAL_SCRIPT, "utf8"));
+	// Pin files at the paths the TABLE declares.
+	await write(GO_ENTRY.file, GO_NIX_FIXTURE);
+	await write(BUN_ENTRY.file, BUN_NIX_FIXTURE);
+	// Trigger manifests (content is irrelevant; only their diff-vs-base matters).
+	for (const trigger of [...GO_ENTRY.triggers, ...BUN_ENTRY.triggers]) {
+		await write(trigger, "baseline\n");
+	}
+	// The fake nix.
+	const binDir = join(repo, "stubbin");
+	await mkdir(binDir, { recursive: true });
+	await Bun.write(join(binDir, "nix"), STUB_NIX);
+	await chmod(join(binDir, "nix"), 0o755);
+
+	await $`git init -q -b main`.cwd(repo).env(HERMETIC_ENV).quiet();
+	await $`git add -A`.cwd(repo).env(HERMETIC_ENV).quiet();
+	await $`git commit -q -m baseline`.cwd(repo).env(HERMETIC_ENV).quiet();
+	// Point origin/main at the baseline so the script's PRIMARY base-ref path
+	// (`git rev-parse --verify -q origin/main`) is exercised, not just the local
+	// fallback. origin is the repo itself; no network.
+	await $`git remote add origin .`.cwd(repo).env(HERMETIC_ENV).quiet();
+	await $`git update-ref refs/remotes/origin/main main`
+		.cwd(repo)
+		.env(HERMETIC_ENV)
+		.quiet();
+	return repo;
+}
+
+// Run the shipped script exactly as Renovate does: cwd = repo root, stub nix
+// first on PATH, base branch = the committed baseline.
+async function runRefresh(repo: string) {
+	return await $`bun ${SCRIPT_REL}`
+		.cwd(repo)
+		.env({
+			...HERMETIC_ENV,
+			PATH: `${join(repo, "stubbin")}:${process.env.PATH}`,
+			RENOVATE_BASE_BRANCH: "main",
+		})
+		.quiet()
+		.nothrow();
+}
+
+describe("tools/renovate/refresh-fod-hashes.ts gate (PR #579)", () => {
+	let repo: string;
+	beforeEach(async () => {
+		repo = await buildBaselineRepo();
+	});
+	afterEach(async () => {
+		if (repo) await rm(repo, { recursive: true, force: true });
+	});
+
+	// THE regression: after a go/go.mod bump, the per-FOD gate must fire from the
+	// repo root and the Go vendorHash must be rewritten to the value the build
+	// reported for the go-modules FOD. On a wrong cwd the gate's cwd-relative
+	// pathspec misses the root manifest → "nothing to do" → placeholder survives.
+	test("refreshes the Go vendorHash after a go/go.mod bump", async () => {
+		await Bun.write(join(repo, "go/go.mod"), "bumped\n");
+
+		const res = await runRefresh(repo);
+		const stdout = res.stdout.toString();
+
+		expect(res.exitCode).toBe(0);
+		expect(stdout).not.toContain("nothing to do");
+		const goNix = await readFile(join(repo, GO_ENTRY.file), "utf8");
+		expect(hashOnMarker(goNix, GO_ENTRY.marker)).toBe(
+			stubSriForFragment("go-modules"),
+		);
+	});
+
+	// A gomod-only bump refreshes the Go vendorHash and leaves the bun outputHash
+	// pin byte-for-byte untouched — the per-FOD self-gate granularity.
+	test("a go/go.mod bump leaves the bun outputHash pin untouched", async () => {
+		const bunBefore = await readFile(join(repo, BUN_ENTRY.file), "utf8");
+		await Bun.write(join(repo, "go/go.mod"), "bumped\n");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+
+		const goNix = await readFile(join(repo, GO_ENTRY.file), "utf8");
+		expect(hashOnMarker(goNix, GO_ENTRY.marker)).toBe(
+			stubSriForFragment("go-modules"),
+		);
+		expect(await readFile(join(repo, BUN_ENTRY.file), "utf8")).toBe(bunBefore);
+	});
+
+	// A bun.lock bump refreshes only the bun outputHash; the Go vendorHash is left
+	// untouched (its trigger, go/go.mod|go.sum, did not change).
+	test("a bun.lock bump refreshes the bun outputHash and leaves the Go pin", async () => {
+		const goBefore = await readFile(join(repo, GO_ENTRY.file), "utf8");
+		await Bun.write(join(repo, "bun.lock"), "bumped\n");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+
+		const bunNix = await readFile(join(repo, BUN_ENTRY.file), "utf8");
+		expect(hashOnMarker(bunNix, BUN_ENTRY.marker)).toBe(
+			stubSriForFragment("node-modules"),
+		);
+		expect(await readFile(join(repo, GO_ENTRY.file), "utf8")).toBe(goBefore);
+	});
+
+	// Restore-on-completion: the script fakes the pin to force the mismatch, then
+	// writes the REAL value — never leaving the fake all-A hash in the tree.
+	test("never leaves the fake all-A SRI in a refreshed pin file", async () => {
+		await Bun.write(join(repo, "go/go.sum"), "bumped\n");
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+		const goNix = await readFile(join(repo, GO_ENTRY.file), "utf8");
+		expect(goNix).not.toContain("sha256-AAAAAAAA");
+	});
+
+	// The self-gate contract: with NO trigger manifest changed the script is a
+	// cheap no-op — no build, no rewrite. Guards against the gate being dropped.
+	test("is a no-op when no trigger manifest changed", async () => {
+		const res = await runRefresh(repo);
+		const stdout = res.stdout.toString();
+
+		expect(res.exitCode).toBe(0);
+		expect(stdout).toContain("nothing to do");
+		const goNix = await readFile(join(repo, GO_ENTRY.file), "utf8");
+		expect(hashOnMarker(goNix, GO_ENTRY.marker)).toBe(PLACEHOLDER_GO);
+	});
+
+	// Silent-no-op defense: if the build reports no `got:` for the gated FOD (a
+	// broken build, or a parse regression), the script must fail LOUD (exit≠0),
+	// never write an empty/placeholder pin and exit 0.
+	test("fails loud (exit≠0) when the build reports no got: for the FOD", async () => {
+		// Replace nix with one that fails WITHOUT a mismatch block.
+		await Bun.write(
+			join(repo, "stubbin", "nix"),
+			"#!/usr/bin/env bash\necho 'error: build failed' >&2\nexit 1\n",
+		);
+		await chmod(join(repo, "stubbin", "nix"), 0o755);
+		await Bun.write(join(repo, "go/go.mod"), "bumped\n");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).not.toBe(0);
+		expect(res.stderr.toString()).toMatch(/no 'got:' SRI/);
+		// The pin was restored to its original placeholder, not left faked.
+		const goNix = await readFile(join(repo, GO_ENTRY.file), "utf8");
+		expect(hashOnMarker(goNix, GO_ENTRY.marker)).toBe(PLACEHOLDER_GO);
+	});
+});
+
+describe("parseGotForFragment", () => {
+	const OUT = [
+		"error: hash mismatch in fixed-output derivation '/nix/store/x-compass-go-modules.drv':",
+		"         specified: sha256-AAAA=",
+		"            got:    sha256-realgo=",
+		"error: hash mismatch in fixed-output derivation '/nix/store/y-compass-node-modules.drv':",
+		"         specified: sha256-BBBB=",
+		"            got:    sha256-realbun=",
+	].join("\n");
+
+	test("returns the got: SRI for the matching drv fragment", () => {
+		expect(parseGotForFragment(OUT, "go-modules")).toBe("sha256-realgo=");
+		expect(parseGotForFragment(OUT, "node-modules")).toBe("sha256-realbun=");
+	});
+
+	test("does not misattribute a sibling FOD's got: to the wrong fragment", () => {
+		// Only the go block present; asking for node-modules must find nothing,
+		// never fall through to the go got:.
+		const onlyGo = OUT.split("\n").slice(0, 3).join("\n");
+		expect(parseGotForFragment(onlyGo, "node-modules")).toBeUndefined();
+		expect(parseGotForFragment(onlyGo, "go-modules")).toBe("sha256-realgo=");
+	});
+
+	test("returns undefined when no mismatch is reported", () => {
+		expect(
+			parseGotForFragment("built '/nix/store/x'\n", "go-modules"),
+		).toBeUndefined();
+	});
+});
+
+describe("rewriteInlineHash", () => {
+	test("rewrites the sha256 on the marker line to the new SRI", () => {
+		const out = rewriteInlineHash(
+			GO_NIX_FIXTURE,
+			GO_ENTRY.marker,
+			"sha256-newgo=",
+			GO_ENTRY.file,
+		);
+		expect(hashOnMarker(out, GO_ENTRY.marker)).toBe("sha256-newgo=");
+	});
+
+	test("is idempotent — rewriting to the same SRI yields identical content", () => {
+		const out = rewriteInlineHash(
+			GO_NIX_FIXTURE,
+			GO_ENTRY.marker,
+			PLACEHOLDER_GO,
+			GO_ENTRY.file,
+		);
+		expect(out).toBe(GO_NIX_FIXTURE);
+	});
+
+	test("throws on an empty new SRI", () => {
+		expect(() =>
+			rewriteInlineHash(GO_NIX_FIXTURE, GO_ENTRY.marker, "", GO_ENTRY.file),
+		).toThrow(/empty/);
+	});
+
+	test("throws when the marker is not found", () => {
+		expect(() =>
+			rewriteInlineHash(
+				GO_NIX_FIXTURE,
+				'noSuch = "sha256-',
+				"sha256-x=",
+				GO_ENTRY.file,
+			),
+		).toThrow(/marker .* not found/);
+	});
+});
diff --git a/tools/renovate/refresh-fod-hashes.ts b/tools/renovate/refresh-fod-hashes.ts
new file mode 100755
index 000000000..8e223f710
--- /dev/null
+++ b/tools/renovate/refresh-fod-hashes.ts
@@ -0,0 +1,248 @@
+#!/usr/bin/env bun
+// Renovate postUpgradeTask: refresh the pinned Nix fixed-output-derivation (FOD)
+// hashes a dependency bump invalidates, so a dep-bump PR lands green instead of
+// red on a `hash mismatch in fixed-output derivation` build break (the RIG-2432
+// easy-dep-bump goal, PR #579's failure class).
+//
+// Compass pins exactly two FOD hashes outside the vendored forks/ trees, each
+// content-addressing a fetched dependency set that MOVES when a manifest bumps:
+//
+//   guest-image/default.nix   vendorHash   compass-guestd's Go module set
+//                                          (buildGoModule; no vendor/ dir) —
+//                                          invalidated by a go/go.mod|go.sum bump
+//   agent-image/entrypoint.nix outputHash  compass-agent's installed node_modules
+//                                          tree (recursive FOD of `bun install`) —
+//                                          invalidated by a bun.lock bump
+//
+// Neither is a URL hash a `nix store prefetch-file` can recompute (that is
+// refresh-toolchain-hashes.ts's job for the vendored-binary pins). A vendorHash /
+// outputHash is only knowable by REALISING the derivation: build it, read the SRI
+// Nix reports on the mismatch. Both FODs live in the guest-image rootfs closure
+// (guest-image/default.nix imports agent-image/entrypoint.nix with root's pkgs),
+// so ONE build vehicle realises both — and with a deliberately-wrong pin the
+// build fails FAST at the FOD, never proceeding to the heavy guestd compile or
+// erofs pack.
+//
+// Mechanism, per gated entry:
+//   1. Rewrite the entry's hash to a fixed FAKE value.
+//   2. `nix build` the rootfs vehicle (--keep-going so a co-stale sibling FOD
+//      does not mask this one) — it fails with the entry's real `got:` SRI.
+//   3. Parse the `got:` for THIS entry's derivation (matched by a drv-name
+//      fragment, so a sibling FOD's mismatch can never be misattributed).
+//   4. Write the real SRI back. Fail LOUD (exit 1) if no `got:` is found — a
+//      silent no-op would ship the stale pin this task exists to fix.
+//
+// Self-gating: for each entry, act only when one of its trigger manifests differs
+// from the base branch (mirrors refresh-toolchain-hashes.ts's versions/*.nix
+// gate). So it is a cheap no-op on every branch that touches neither manifest,
+// a gomod bump refreshes only the Go vendorHash, and a bun bump only the bun
+// outputHash. Idempotent: re-running rewrites the same SRI.
+//
+// Wired from config.json5 both at top-level postUpgradeTasks (branch mode —
+// covers gomod branches and pure-bun-first TypeScript-rollup branches) and on the
+// catalog packageRule (update mode — covers catalog-first rollup branches, where
+// the collapsed branch config evicts the top-level branch task; see that rule's
+// note). Both are the same `bun tools/renovate/refresh-fod-hashes.ts` command,
+// allowlisted once in bot-config.json5 (config.test.ts pins the two together).
+//
+// Requires `nix` (nix-command) + `bun` + `git` on PATH and network. The build is
+// self-contained: `nix build` fetches the Go/bun toolchains it needs into the
+// store itself, so only nix + network are load-bearing for the realise step (bun
+// runs this script; git drives the self-gate). The Renovate workflow's toolchain
+// bootstrap provides all of them (.github/workflows/renovate.yml).
+//
+// Design: docs/designs/repo/compass-renovate-migration.md
+//
+// Exit codes:
+//   0 - hash(es) refreshed, or a no-op branch (no trigger manifest changed).
+//   1 - a step failed (build produced no `got:`, or a marker was missing) —
+//       fail loud, never ship a half-refreshed pin set.
+
+import { $ } from "bun";
+
+// The build vehicle that realises both FODs, and the Nix file it is expressed in.
+// Repo-root-relative (the runner cwd = repo root; main() chdirs there).
+export const BUILD_FILE = "guest-image/default.nix";
+export const BUILD_TARGET = "compass-guest-rootfs";
+
+// A syntactically-valid but deliberately-wrong SRI. Building any FOD against it
+// forces the `hash mismatch … got: <real>` error we parse. All-A base64 is a
+// canonical fake (matches the lib.fakeHash convention the nix files document).
+const FAKE_SRI = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+
+// The two pinned FODs. Exported so the test derives its fixtures from the shipped
+// table rather than restating it — a rebase that edits the table keeps the test
+// honest with no second edit.
+export type FodEntry = {
+	// Nix file carrying the pinned hash (repo-root-relative).
+	file: string;
+	// Unique substring on the hash line — the attr name + `= "sha256-` prefix, so
+	// it matches exactly one line and cannot bind a comment or a sibling attr.
+	marker: string;
+	// A fragment of this FOD's derivation name, used to attribute the correct
+	// `got:` when --keep-going reports multiple mismatches. Distinct per entry.
+	drvFragment: string;
+	// Manifests whose change invalidates this FOD (repo-root-relative). The
+	// per-entry self-gate fires when any of these differs from the base branch.
+	triggers: string[];
+};
+
+export const FOD_ENTRIES: FodEntry[] = [
+	{
+		file: "guest-image/default.nix",
+		marker: 'vendorHash = "sha256-',
+		drvFragment: "go-modules",
+		triggers: ["go/go.mod", "go/go.sum"],
+	},
+	{
+		file: "agent-image/entrypoint.nix",
+		marker: 'outputHash = "sha256-',
+		drvFragment: "node-modules",
+		triggers: ["bun.lock"],
+	},
+];
+
+// ── Pure rewrite: replace the `sha256-…` SRI on the line carrying `marker`. ──
+// Unlike refresh-toolchain-hashes.ts (whose hash sits on the line AFTER the URL
+// marker), a vendorHash/outputHash IS the marker line. Throws on an empty SRI or
+// a missing marker, so a silent no-op can't ship a stale pin. Idempotent.
+export function rewriteInlineHash(
+	fileText: string,
+	marker: string,
+	newSri: string,
+	file: string,
+): string {
+	if (!newSri) {
+		throw new Error(
+			`renovate-fod: empty recomputed hash for '${marker}' in ${file}`,
+		);
+	}
+	const lines = fileText.split("\n");
+	const i = lines.findIndex((l) => l.includes(marker));
+	if (i === -1) {
+		throw new Error(`renovate-fod: marker '${marker}' not found in ${file}`);
+	}
+	const line = lines[i] as string;
+	lines[i] = line.replace(/sha256-[^"]*/, newSri);
+	return lines.join("\n");
+}
+
+// ── Parse the `got:` SRI for the derivation whose name contains `fragment`. ──
+// Nix prints, per mismatching FOD:
+//     error: hash mismatch in fixed-output derivation '/nix/store/…-<frag>.drv':
+//              specified: sha256-<fake>
+//                 got:    sha256-<real>
+// Scoping to the fragment means a co-stale sibling FOD's mismatch (only possible
+// defensively — the two triggers never change on one branch) is never
+// misattributed. Returns undefined if this FOD did not report a mismatch.
+export function parseGotForFragment(
+	nixOutput: string,
+	fragment: string,
+): string | undefined {
+	const lines = nixOutput.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const l = lines[i] as string;
+		if (
+			l.includes("hash mismatch in fixed-output derivation") &&
+			l.includes(fragment)
+		) {
+			for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+				const m = (lines[j] as string).match(/got:\s*(sha256-\S+)/);
+				if (m?.[1]) return m[1];
+			}
+		}
+	}
+	return undefined;
+}
+
+// Recompute one entry's SRI: fake the pin, build the vehicle, read the reported
+// `got:` for this FOD, then restore the file to the ORIGINAL text (the caller
+// writes the real SRI). Restores on every path so a failure never leaves a fake
+// pin in the tree.
+async function recompute(entry: FodEntry, origText: string): Promise<string> {
+	await Bun.write(
+		entry.file,
+		rewriteInlineHash(origText, entry.marker, FAKE_SRI, entry.file),
+	);
+	try {
+		const res =
+			await $`nix build -f ${BUILD_FILE} ${BUILD_TARGET} --no-link --keep-going`
+				.nothrow()
+				.quiet();
+		const out = `${res.stdout.toString()}\n${res.stderr.toString()}`;
+		const got = parseGotForFragment(out, entry.drvFragment);
+		if (!got) {
+			throw new Error(
+				`renovate-fod: no 'got:' SRI for '${entry.drvFragment}' after building ` +
+					`${BUILD_TARGET} with a faked ${entry.marker} — build output:\n` +
+					out.split("\n").slice(-30).join("\n"),
+			);
+		}
+		return got;
+	} finally {
+		await Bun.write(entry.file, origText);
+	}
+}
+
+async function main(): Promise<void> {
+	// Resolve the repo root from git, not a hardcoded depth: Renovate invokes this
+	// as a postUpgradeTask and the paths above are repo-root-relative, so a wrong
+	// cwd would silently no-op the gate. git is already required (the gate diffs),
+	// so this adds no dependency and is move-proof.
+	const repoRoot = (await $`git rev-parse --show-toplevel`.text()).trim();
+	process.chdir(repoRoot);
+
+	const baseBranch = process.env.RENOVATE_BASE_BRANCH || "main";
+	let baseRef = baseBranch;
+	if (
+		(await $`git rev-parse --verify -q origin/${baseBranch}`.nothrow().quiet())
+			.exitCode === 0
+	) {
+		baseRef = `origin/${baseBranch}`;
+	}
+
+	// Per-entry gate: act only on FODs whose trigger manifests this branch changed
+	// vs base. A gomod bump opens the Go entry alone; a bun bump the bun entry
+	// alone; a branch touching neither manifest no-ops with no build.
+	const gated: FodEntry[] = [];
+	for (const entry of FOD_ENTRIES) {
+		let changed = false;
+		for (const trigger of entry.triggers) {
+			const gate = await $`git diff --quiet ${baseRef} -- ${trigger}`
+				.nothrow()
+				.quiet();
+			if (gate.exitCode !== 0) {
+				changed = true;
+				break;
+			}
+		}
+		if (changed) gated.push(entry);
+	}
+
+	if (gated.length === 0) {
+		console.log(
+			`renovate-fod: no FOD trigger manifest changed vs ${baseRef}; nothing to do.`,
+		);
+		return;
+	}
+
+	for (const entry of gated) {
+		const origText = await Bun.file(entry.file).text();
+		console.log(
+			`renovate-fod: ${entry.file} (${entry.drvFragment}) trigger changed; recomputing ${entry.marker.replace(/ = .*/, "")} ...`,
+		);
+		const got = await recompute(entry, origText);
+		await Bun.write(
+			entry.file,
+			rewriteInlineHash(origText, entry.marker, got, entry.file),
+		);
+		console.log(`renovate-fod: ${entry.file} -> ${got}`);
+	}
+
+	console.log("renovate-fod: FOD hashes refreshed.");
+}
+
+// Run only when executed directly (not imported by the test file).
+if (import.meta.main) {
+	await main();
+}

From ea588d171afec5c2ea35ac5943302cfa14ec0dc7 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Tue, 25 Aug 2026 17:41:53 -0400
Subject: [PATCH 2/3] fix(renovate): address FOD-hash review findings
 (RIG-2727)

Review-loop fixes on PR #626, additive over the submitted tip:

- Document the verified biome/devenv-channel FOD-refresh exemption. The
  devenv-nixpkgs lockstep branch rewrites bun.lock + the biome catalog pin
  but intentionally omits the FOD refresh; biome is a root-only devDependency
  absent from compass-agent's filtered `bun install --filter '@compass/agent'`
  tree (verified: not in node_modules nor .bun), so a channel bump cannot move
  agent-image/entrypoint.nix's outputHash. Pinned by an explicit config.test.ts
  guard so a future biome-in-compass-agent change forces a revisit.
- Correct the catalog-rule comment: the per-upgrade FOD refresh leg is
  idempotent but NOT free (it re-realises the node_modules FOD once per catalog
  upgrade). Kept last-write-wins; noted why a same-branch short-circuit is
  unsafe without relying on Renovate's grouped-update apply ordering.
- Make the got:-SRI parse robust: scan from the mismatch header to the next
  header instead of a fixed 5-line window, so a future nix that adds context
  lines before `got:` can't silently wedge every FOD build. Add window-boundary
  + no-cross-block-bleed tests.
- Write the recomputed SRI literally (function replacer) so a `$`-bearing value
  can never be interpreted as a replacement pattern. Add a literal-write test.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/config.json5               | 31 +++++++++++++++--
 tools/renovate/config.test.ts             | 14 ++++++++
 tools/renovate/refresh-fod-hashes.test.ts | 42 +++++++++++++++++++++++
 tools/renovate/refresh-fod-hashes.ts      | 16 +++++++--
 4 files changed, 98 insertions(+), 5 deletions(-)

diff --git a/tools/renovate/config.json5 b/tools/renovate/config.json5
index 660ffb85b..b59ac0bd0 100644
--- a/tools/renovate/config.json5
+++ b/tools/renovate/config.json5
@@ -447,6 +447,20 @@
       // would be a no-op here anyway. fileFilters cover exactly the files the script
       // writes (compass has no committed inner-rev guard file, so no such entry).
       //
+      // FOD-REFRESH IS INTENTIONALLY ABSENT here, though this branch rewrites
+      // bun.lock + a workspace manifest (the biome catalog pin) — the two inputs
+      // agent-image/entrypoint.nix names as moving its bun `outputHash`. It is
+      // safe because biome never enters the hashed tree: the FOD installs with
+      // `bun install --frozen-lockfile --ignore-scripts --filter '@compass/agent'`
+      // (entrypoint.nix), and biome is a ROOT-ONLY devDependency (package.json
+      // `devDependencies`, absent from @compass/agent's manifest). Verified: that
+      // exact filtered install yields biome in neither `node_modules` nor the
+      // `.bun` virtual store, so a channel/biome bump cannot move outputHash. If
+      // biome ever becomes a compass-agent dependency, this rule must append
+      // `bun tools/renovate/refresh-fod-hashes.ts` + `agent-image/entrypoint.nix`
+      // to its task (it runs after the bun.lock rewrite, so it would self-gate and
+      // refresh in the same branch). config.test.ts pins this exemption.
+      //
       // Self-hosted bot config MUST allow the command:
       //   allowedCommands: [… , "^bun tools/renovate/refresh-devenv-nixpkgs\\.ts$"]
       // see tools/renovate/bot-config.json5 (config.test.ts pins the two together).
@@ -496,8 +510,21 @@
       // pass to fire on every catalog branch regardless of sort order. Same command
       // string as top-level → one allowlist entry; refresh-fod-hashes.ts self-gates
       // on bun.lock so it refreshes the bun outputHash alone here and no-ops the Go
-      // vendorHash. Idempotent, so a double-fire (both passes on a bun-first branch)
-      // is harmless.
+      // vendorHash. Correctness is last-write-wins and order-independent.
+      //
+      // COST — unlike the lockfile leg, the FOD leg is idempotent but NOT free.
+      // `executionMode: "update"` runs it once PER catalog upgrade, and each run
+      // fakes the pin (a guaranteed FOD cache-miss) and realises the rootfs
+      // vehicle, forcing a full networked `bun install` of compass-agent's
+      // node_modules FOD. On a K-dep catalog rollup the outputHash is thus
+      // re-realised K times — including for catalog deps outside compass-agent's
+      // closure (astro/stylelint/starlight move bun.lock but not the hashed tree),
+      // which pay a realise to confirm no change. Accepted: last-write-wins is
+      // correct and a same-branch short-circuit is unsafe without relying on
+      // Renovate's grouped-update apply ordering (an early per-upgrade pass could
+      // see a partial tree and freeze a wrong hash). The double-fire on a
+      // bun-first branch (both this pass and the top-level task) is likewise
+      // correct, just a second realise.
       //
       // Self-hosted bot config MUST allow both commands:
       //   allowedCommands: [… , "^bun install --lockfile-only$",
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index 667058905..3561e33cf 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -492,6 +492,15 @@ describe("tools/renovate devenv nixpkgs lockstep", () => {
 
 	// Branch-mode lockstep task over exactly the three files the script writes
 	// (compass has NO committed inner-rev guard file, unlike the internal monorepo's fourth entry).
+	//
+	// The `every(... refresh-devenv-nixpkgs ...)` assertion also PINS the verified
+	// FOD-refresh exemption: this branch rewrites bun.lock + the biome catalog pin,
+	// but biome is a root-only devDependency absent from the FOD's filtered
+	// `--filter '@compass/agent'` install (verified: not in node_modules nor .bun),
+	// so a channel bump cannot move agent-image/entrypoint.nix's outputHash and the
+	// FOD refresh is intentionally NOT wired here. If biome ever enters the
+	// compass-agent closure, adding the FOD command is what makes this test fail —
+	// forcing a conscious revisit of the exemption rather than a silent red build.
 	test("the lockstep postUpgradeTask is branch-mode over the written files", () => {
 		const task = devenvRule?.postUpgradeTasks;
 		expect(task?.executionMode).toBe("branch");
@@ -506,6 +515,11 @@ describe("tools/renovate devenv nixpkgs lockstep", () => {
 				/^bun tools\/renovate\/refresh-devenv-nixpkgs\.ts$/.test(c),
 			),
 		).toBe(true);
+		// Explicit: the FOD refresh is NOT on this rule (the verified exemption).
+		expect(task?.commands).not.toContain(
+			"bun tools/renovate/refresh-fod-hashes.ts",
+		);
+		expect(task?.fileFilters).not.toContain("agent-image/entrypoint.nix");
 	});
 
 	// The digest-excludes-rollup seam: the TS rollup ALSO matches custom.regex, so
diff --git a/tools/renovate/refresh-fod-hashes.test.ts b/tools/renovate/refresh-fod-hashes.test.ts
index 3a4e3a0ef..36e2d8c98 100644
--- a/tools/renovate/refresh-fod-hashes.test.ts
+++ b/tools/renovate/refresh-fod-hashes.test.ts
@@ -296,6 +296,34 @@ describe("parseGotForFragment", () => {
 		expect(parseGotForFragment(onlyGo, "go-modules")).toBe("sha256-realgo=");
 	});
 
+	test("finds got: beyond a fixed 5-line window (scans to next header)", () => {
+		// Guards the unbounded within-block scan against a future nix that adds
+		// context lines before `got:` (or wraps the drv path) — a fixed lookahead
+		// window would silently miss it and fail every FOD build.
+		const wide = [
+			"error: hash mismatch in fixed-output derivation '/nix/store/x-compass-go-modules.drv':",
+			"         specified: sha256-AAAA=",
+			"         (context line a)",
+			"         (context line b)",
+			"         (context line c)",
+			"            got:    sha256-farbelow=",
+		].join("\n");
+		expect(parseGotForFragment(wide, "go-modules")).toBe("sha256-farbelow=");
+	});
+
+	test("stops at the next mismatch header (no cross-block got: bleed)", () => {
+		// A fragment whose own block reports no got: (defensive) must not scan past
+		// the next header and steal the sibling's got:.
+		const noGotThenSibling = [
+			"error: hash mismatch in fixed-output derivation '/nix/store/x-compass-go-modules.drv':",
+			"         specified: sha256-AAAA=",
+			"error: hash mismatch in fixed-output derivation '/nix/store/y-compass-node-modules.drv':",
+			"         specified: sha256-BBBB=",
+			"            got:    sha256-realbun=",
+		].join("\n");
+		expect(parseGotForFragment(noGotThenSibling, "go-modules")).toBeUndefined();
+	});
+
 	test("returns undefined when no mismatch is reported", () => {
 		expect(
 			parseGotForFragment("built '/nix/store/x'\n", "go-modules"),
@@ -340,4 +368,18 @@ describe("rewriteInlineHash", () => {
 			),
 		).toThrow(/marker .* not found/);
 	});
+
+	test("inserts the new SRI literally (no $-sequence interpretation)", () => {
+		// A base64 SRI cannot contain `$` today, but the write must stay literal so
+		// a future parse widening can't let `$&`/`$1`/`$$` in the replacement mangle
+		// the pin. Feed a `$`-bearing value and assert it lands verbatim.
+		const withDollars = "sha256-a$&b$1c$$d=";
+		const out = rewriteInlineHash(
+			GO_NIX_FIXTURE,
+			GO_ENTRY.marker,
+			withDollars,
+			GO_ENTRY.file,
+		);
+		expect(hashOnMarker(out, GO_ENTRY.marker)).toBe(withDollars);
+	});
 });
diff --git a/tools/renovate/refresh-fod-hashes.ts b/tools/renovate/refresh-fod-hashes.ts
index 8e223f710..c481e1321 100755
--- a/tools/renovate/refresh-fod-hashes.ts
+++ b/tools/renovate/refresh-fod-hashes.ts
@@ -123,7 +123,11 @@ export function rewriteInlineHash(
 		throw new Error(`renovate-fod: marker '${marker}' not found in ${file}`);
 	}
 	const line = lines[i] as string;
-	lines[i] = line.replace(/sha256-[^"]*/, newSri);
+	// Function replacer: newSri is inserted LITERALLY. A string replacement would
+	// interpret `$&`/`$1`/`$$` sequences in it — inert for a base64 SRI today
+	// (alphabet A-Za-z0-9+/=), but a latent silent-corruption path if the parse
+	// ever widened, so keep the write literal.
+	lines[i] = line.replace(/sha256-[^"]*/, () => newSri);
 	return lines.join("\n");
 }
 
@@ -146,8 +150,14 @@ export function parseGotForFragment(
 			l.includes("hash mismatch in fixed-output derivation") &&
 			l.includes(fragment)
 		) {
-			for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
-				const m = (lines[j] as string).match(/got:\s*(sha256-\S+)/);
+			// Scan from this header to the NEXT mismatch header (or end of output),
+			// not a fixed N-line window: the `got:` line's offset below the header is
+			// nix's mismatch-block shape, and pinning it to a magic count would break
+			// silently if a future nix wrapped the drv path or added context lines.
+			for (let j = i + 1; j < lines.length; j++) {
+				const lj = lines[j] as string;
+				if (lj.includes("hash mismatch in fixed-output derivation")) break;
+				const m = lj.match(/got:\s*(sha256-\S+)/);
 				if (m?.[1]) return m[1];
 			}
 		}

From 5f43f24ea0d52bb35abb3e56be3cbf1732ff01bc Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Tue, 25 Aug 2026 17:54:04 -0400
Subject: [PATCH 3/3] fix(renovate): guard FOD_ENTRIES drvFragment attribution
 ambiguity (RIG-2727)

Round-2 review low finding: parseGotForFragment attributes a nix mismatch
block to a FOD by `drvName.includes(fragment)`. Safe for the current two
fragments ("go-modules"/"node-modules", mutually disjoint), but a future
FOD_ENTRIES edit adding an ambiguous fragment (e.g. a bare "modules") would
silently misattribute a got: SRI and write the wrong hash.

Add a module-load assertion that no drvFragment is a substring of another, so
such an edit fails loud at import rather than misattributing at runtime, plus a
test stating the invariant.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/refresh-fod-hashes.test.ts | 16 ++++++++++++++++
 tools/renovate/refresh-fod-hashes.ts      | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/tools/renovate/refresh-fod-hashes.test.ts b/tools/renovate/refresh-fod-hashes.test.ts
index 36e2d8c98..d47f751b4 100644
--- a/tools/renovate/refresh-fod-hashes.test.ts
+++ b/tools/renovate/refresh-fod-hashes.test.ts
@@ -383,3 +383,19 @@ describe("rewriteInlineHash", () => {
 		expect(hashOnMarker(out, GO_ENTRY.marker)).toBe(withDollars);
 	});
 });
+
+describe("FOD_ENTRIES table invariant", () => {
+	test("no drvFragment is a substring of another (got: attribution safety)", () => {
+		// parseGotForFragment attributes a mismatch block by includes(fragment);
+		// if one fragment contained another, one entry's got: could bind the
+		// other's block and write the wrong hash. The module also asserts this at
+		// load time — this test states the property explicitly and pins it against
+		// a future table edit.
+		for (const a of FOD_ENTRIES) {
+			for (const b of FOD_ENTRIES) {
+				if (a === b) continue;
+				expect(b.drvFragment.includes(a.drvFragment)).toBe(false);
+			}
+		}
+	});
+});
diff --git a/tools/renovate/refresh-fod-hashes.ts b/tools/renovate/refresh-fod-hashes.ts
index c481e1321..81b9f2116 100755
--- a/tools/renovate/refresh-fod-hashes.ts
+++ b/tools/renovate/refresh-fod-hashes.ts
@@ -102,6 +102,23 @@ export const FOD_ENTRIES: FodEntry[] = [
 	},
 ];
 
+// Fragment attribution (parseGotForFragment) matches a mismatch block by
+// `drvName.includes(fragment)`, so two fragments where one contains the other
+// (e.g. "modules" vs "node-modules") would let one entry's got: bind the other's
+// block and write the WRONG hash. The current two fragments are mutually
+// disjoint; assert it at load time so a future table edit that reintroduces an
+// ambiguous fragment fails loud here rather than silently misattributing at run.
+for (const a of FOD_ENTRIES) {
+	for (const b of FOD_ENTRIES) {
+		if (a !== b && b.drvFragment.includes(a.drvFragment)) {
+			throw new Error(
+				`renovate-fod: ambiguous drvFragment '${a.drvFragment}' is a substring of ` +
+					`'${b.drvFragment}' — fragments must be mutually disjoint for got: attribution`,
+			);
+		}
+	}
+}
+
 // ── Pure rewrite: replace the `sha256-…` SRI on the line carrying `marker`. ──
 // Unlike refresh-toolchain-hashes.ts (whose hash sits on the line AFTER the URL
 // marker), a vendorHash/outputHash IS the marker line. Throws on an empty SRI or