From 9f4d455295ee4952f19b315a4a3c89c1679864ca Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 2 Sep 2026 17:37:02 -0400
Subject: [PATCH 1/2] feat(renovate): couple go bump to go-overlay refresh
 (RIG-3100)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A Renovate `go` toolchain bump rewrites only the version string in
tools/toolchain/versions/go.nix; the per-platform hashes come from the
go-overlay flake input, whose rev is pinned in devenv.lock. go-overlay's
`versions` set only carries go releases at or before that rev, so a bump to a
newer go than the pinned overlay provides evals `go-bin.versions.<new>` against
a stale overlay and reds CI (`attribute '"<ver>"' missing` /
`gate-tools.nix langs produced no store paths`).

Couple the two: a rule-level postUpgradeTask on the go pin's solo branch runs a
new refresh-go-overlay.ts that advances the go-overlay input
(`devenv update go-overlay`) and validates the bumped version resolves through
gate-tools.nix's `langs.go` — the same build-free eval path CI uses — so a go
bump lands in one green PR instead of a red one needing a manual overlay
follow-up.

- refresh-go-overlay.ts: self-gate on go.nix vs base → advance overlay →
  validate `langs.go.version` === go.nix pin (fail loud on mismatch/missing).
- refresh-go-overlay.core.ts: pure devenv.lock/go.nix parsing (unit-tested).
- config.json5: matchDepNames ["go"] on custom.regex, branch-mode task over
  devenv.lock alone; stale "no refresh leg" comment on the go manager rewritten.
- bot-config.json5: allowlist the command (5th entry).
- config.test.ts: command-count/set guards 4→5 + solo-branch grouping invariant.

Mirrors the refresh-devenv-nixpkgs.ts (RIG-2432) pattern. Fixes the compass
#650 (go v1.27) red class.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/bot-config.json5               |  15 +-
 tools/renovate/config.json5                   |  57 ++++-
 tools/renovate/config.test.ts                 |  62 ++++-
 .../renovate/refresh-go-overlay.core.test.ts  |  73 ++++++
 tools/renovate/refresh-go-overlay.core.ts     |  73 ++++++
 tools/renovate/refresh-go-overlay.test.ts     | 226 ++++++++++++++++++
 tools/renovate/refresh-go-overlay.ts          | 172 +++++++++++++
 7 files changed, 663 insertions(+), 15 deletions(-)
 create mode 100644 tools/renovate/refresh-go-overlay.core.test.ts
 create mode 100644 tools/renovate/refresh-go-overlay.core.ts
 create mode 100644 tools/renovate/refresh-go-overlay.test.ts
 create mode 100644 tools/renovate/refresh-go-overlay.ts

diff --git a/tools/renovate/bot-config.json5 b/tools/renovate/bot-config.json5
index 80a259e0..4e951f74 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.)
   //
-  // Four entries, all load-bearing:
+  // Five 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
@@ -78,12 +78,21 @@
   //      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.
+  //   5. the go↔go-overlay lockstep, which on a go.nix toolchain bump advances
+  //      the go-overlay input in devenv.lock to a rev that provides the new go
+  //      release and validates it resolves through gate-tools.nix's `langs.go`
+  //      (the same path CI uses). go-overlay's `versions` set only carries
+  //      releases at or before its pinned rev, so without this a bump to a newer
+  //      go than the overlay provides evals a missing attr and reds CI
+  //      (RIG-3100).
+  // (1), (3), (4), and (5) 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$",
+    "^bun tools/renovate/refresh-go-overlay\\.ts$",
   ],
 }
diff --git a/tools/renovate/config.json5 b/tools/renovate/config.json5
index 17cd7610..04617112 100644
--- a/tools/renovate/config.json5
+++ b/tools/renovate/config.json5
@@ -227,12 +227,17 @@
       // regex (the internal monorepo tracked devenv.nix; compass tracks go.nix instead). The
       // version is dotted in go.nix, so there is NO dots↔underscores gymnastics —
       // capture it straight for the golang-version datasource, and devenv.nix picks
-      // it up automatically at eval time. A go bump changes no pin file, so this
-      // manager carries no postUpgradeTasks refresh leg (the overlay ships the
-      // hashes; refresh-toolchain-hashes.ts self-gates past go.nix). Auto-opens
-      // like every other toolchain manager (Matt's ruling: all toolchain bumps
-      // auto-open). The go.mod `go` directive tracks this pin minus at most one
-      // minor by MANUAL policy (go/go.mod:10-12), so the gomod `go`-directive
+      // it up automatically at eval time. A go bump rewrites go.nix and no hash
+      // pin (the overlay ships the hashes), so refresh-toolchain-hashes.ts
+      // self-gates past it — but the go-overlay input pinned in devenv.lock can
+      // LAG upstream go: its `versions` set only carries releases at or before
+      // its rev, so a bump to a newer go than the pinned overlay provides evals a
+      // missing attr and reds CI. The go↔go-overlay lockstep packageRule below
+      // (matchDepNames ["go"]) carries the refresh leg that advances the overlay
+      // input in the same branch and validates the new version resolves. Auto-
+      // opens like every other toolchain manager (Matt's ruling: all toolchain
+      // bumps auto-open). The go.mod `go` directive tracks this pin minus at most
+      // one minor by MANUAL policy (go/go.mod:10-12), so the gomod `go`-directive
       // update is disabled below — a pin bump may occasionally need a manual go.mod
       // follow-up.
       customType: "regex",
@@ -564,6 +569,46 @@
         executionMode: "branch",
       },
     },
+    {
+      // ── Go toolchain ↔ go-overlay lockstep (RIG-3100) ──
+      // The go customManager (above) opens a solo branch that rewrites ONLY the
+      // version string in tools/toolchain/versions/go.nix. The per-platform
+      // hashes come from the go-overlay input, whose rev is pinned in
+      // devenv.lock — and go-overlay's `versions` set only carries go releases
+      // at or before that rev. So when Renovate bumps go.nix to a release newer
+      // than the pinned overlay provides, both the dev shell (devenv.nix's
+      // `go_X_Y_Z` attr) and the parity gate (gate-tools.nix's
+      // `go-bin.versions.<ver>`) eval a missing attribute and CI dies
+      // `attribute '"<ver>"' missing` / `gate-tools.nix langs produced no store
+      // paths`. This task, on that branch, advances the go-overlay input to a
+      // rev that provides the new version and validates it resolves through the
+      // SAME gate-tools.nix `langs.go` path CI uses — so a go bump lands in ONE
+      // green PR instead of a red one needing a manual overlay follow-up.
+      //
+      // `executionMode: "branch"` runs it once after the go.nix update is
+      // applied; safe here because the go pin never shares a branch — the
+      // versions/*.nix un-group rule above nulls its groupName, so it owns its
+      // own branch and thus the single branch-mode task slot Renovate builds per
+      // branch. Rule-level postUpgradeTasks REPLACE the top-level one for
+      // matching branches; the evicted top-level task's refresh-toolchain-hashes
+      // leg self-gates on the vendored-binary versions/*.nix pins and no-ops on
+      // go.nix anyway (go's hashes come from the overlay, not a sha256 pin), so
+      // nothing is lost. fileFilters is an INCLUDE allowlist — Renovate commits
+      // ONLY files matching it — and the refresh writes exactly devenv.lock (the
+      // `devenv update go-overlay` re-lock); it does NOT rewrite go.nix (the go
+      // manager already did) nor any hash pin, so devenv.lock is the sole entry.
+      //
+      // Self-hosted bot config MUST allow the command:
+      //   allowedCommands: [… , "^bun tools/renovate/refresh-go-overlay\\.ts$"]
+      // see tools/renovate/bot-config.json5 (config.test.ts pins the two together).
+      matchManagers: ["custom.regex"],
+      matchDepNames: ["go"],
+      postUpgradeTasks: {
+        commands: ["bun tools/renovate/refresh-go-overlay.ts"],
+        fileFilters: ["devenv.lock"],
+        executionMode: "branch",
+      },
+    },
     {
       // ── Catalog lockfile coupling ──
       // The regex manager exports no `updateArtifacts`, so NOTHING regenerates
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index 6698a48f..c90109c2 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -188,19 +188,20 @@ 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 declares four DISTINCT
+	// entry's `^…$` IS the security property. Compass declares five 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.
+	// be an unanchored substring rule. RIG-3100 added the fifth: the go↔go-overlay
+	// lockstep on the go pin's solo branch.
 	const commands = allDeclaredCommands();
 	const distinctCommands = [...new Set(commands)];
 	const allowed = bot.allowedCommands ?? [];
 
-	test("declares four DISTINCT postUpgrade commands and four allowlist entries", () => {
-		expect(distinctCommands).toHaveLength(4);
-		expect(allowed).toHaveLength(4);
+	test("declares five DISTINCT postUpgrade commands and five allowlist entries", () => {
+		expect(distinctCommands).toHaveLength(5);
+		expect(allowed).toHaveLength(5);
 	});
 
 	test("the fod-hash refresh is declared at BOTH task sites (top-level + catalog)", () => {
@@ -251,12 +252,13 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 		).toBe(false);
 	});
 
-	test("permits exactly the four RIG-2432 commands", () => {
+	test("permits exactly the five RIG-2432/RIG-3100 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-go-overlay.ts",
 				"bun tools/renovate/refresh-toolchain-hashes.ts",
 			].sort(),
 		);
@@ -558,6 +560,54 @@ describe("tools/renovate devenv nixpkgs lockstep", () => {
 	});
 });
 
+describe("tools/renovate go ↔ go-overlay lockstep (RIG-3100)", () => {
+	// The packageRule coupling a go.nix toolchain bump to a go-overlay input
+	// refresh — found by its command, not index.
+	const goOverlayRule = cfg.packageRules.find((r) =>
+		r.postUpgradeTasks?.commands?.some((c) =>
+			/refresh-go-overlay\.ts$/.test(c),
+		),
+	);
+
+	test("the go-overlay refresh rule matches the go dep on the custom.regex manager", () => {
+		expect(goOverlayRule).toBeDefined();
+		expect(goOverlayRule?.matchManagers).toContain("custom.regex");
+		expect(goOverlayRule?.matchDepNames).toContain("go");
+	});
+
+	// Branch-mode task over exactly devenv.lock — the sole file the refresh
+	// writes (the `devenv update go-overlay` re-lock). It must NOT rewrite go.nix
+	// (the go manager already did) nor any hash pin, so listing anything else
+	// 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. fileFilters is an INCLUDE allowlist, so this pins it.
+	test("the lockstep postUpgradeTask is branch-mode over devenv.lock alone", () => {
+		const task = goOverlayRule?.postUpgradeTasks;
+		expect(task?.executionMode).toBe("branch");
+		expect(task?.fileFilters).toEqual(["devenv.lock"]);
+		expect(task?.commands).toEqual([
+			"bun tools/renovate/refresh-go-overlay.ts",
+		]);
+	});
+
+	// 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.
+	test("a go pin bump un-groups to its own solo branch (null), not the TS rollup", () => {
+		const group = resolveGroupName({
+			manager: "custom.regex",
+			fileName: "tools/toolchain/versions/go.nix",
+			depName: "go",
+			depType: "toolchain",
+			updateType: "minor",
+		});
+		expect(group).toBeNull();
+		expect(group).not.toBe("TypeScript dependencies");
+	});
+});
+
 describe("tools/renovate solo-branch grouping outcomes", () => {
 	// Replay Renovate's last-match-wins packageRule semantics: a toolchain pin
 	// bump and the devenv digest must NEVER resolve into the 'TypeScript
diff --git a/tools/renovate/refresh-go-overlay.core.test.ts b/tools/renovate/refresh-go-overlay.core.test.ts
new file mode 100644
index 00000000..ff3e293d
--- /dev/null
+++ b/tools/renovate/refresh-go-overlay.core.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { goOverlayLockedRev, goPinVersion } from "./refresh-go-overlay.core.ts";
+
+// Unit tests for the pure transform core of refresh-go-overlay.ts (RIG-3100):
+// reading the go-overlay locked rev out of devenv.lock and the go version out
+// of go.nix. No nix / network / git — those shell-outs live in the entry point
+// and are exercised by the PR's own CI run. These assert the parsing that a
+// wrong line would silently corrupt (validating the eval against a stale rev or
+// an `undefined` version).
+
+const repoRoot = join(import.meta.dir, "..", "..");
+
+describe("goOverlayLockedRev", () => {
+	// The extraction must recover the real go-overlay rev from the checked-in
+	// devenv.lock — the real-manifest guard style: a devenv lock-format change
+	// (the node moves/renames) fails HERE, loudly, instead of silently
+	// validating against a stale/wrong overlay rev in production.
+	test("recovers the go-overlay rev from the real devenv.lock", () => {
+		const lock = readFileSync(join(repoRoot, "devenv.lock"), "utf8");
+		const rev = goOverlayLockedRev(lock);
+		expect(rev).toMatch(/^[a-f0-9]{40}$/);
+		expect(rev).toBe(JSON.parse(lock).nodes["go-overlay"].locked.rev);
+	});
+
+	test("throws on invalid JSON", () => {
+		expect(() => goOverlayLockedRev("{not json")).toThrow(/not valid JSON/);
+	});
+
+	test("throws when the go-overlay node is absent", () => {
+		const noNode = JSON.stringify({
+			nodes: { nixpkgs: { locked: { rev: "x" } } },
+		});
+		expect(() => goOverlayLockedRev(noNode)).toThrow(/go-overlay rev/);
+	});
+
+	test("throws on a non-40-hex rev (shape drift)", () => {
+		const shortRev = JSON.stringify({
+			nodes: { "go-overlay": { locked: { rev: "abc123" } } },
+		});
+		expect(() => goOverlayLockedRev(shortRev)).toThrow(/go-overlay rev/);
+	});
+});
+
+describe("goPinVersion", () => {
+	// The extraction must recover the real go version from the checked-in go.nix
+	// — the same literal the config.json5 go manager's matchString keys off, so a
+	// go-pin format change fails HERE instead of validating the eval against an
+	// undefined target.
+	test("recovers the go version from the real go.nix", () => {
+		const goNix = readFileSync(
+			join(repoRoot, "tools", "toolchain", "versions", "go.nix"),
+			"utf8",
+		);
+		const version = goPinVersion(goNix);
+		expect(version).toMatch(/^\d+\.\d+/);
+	});
+
+	test("reads the version out of a version-only pin literal", () => {
+		expect(goPinVersion('{ version = "1.27.0"; }')).toBe("1.27.0");
+	});
+
+	test("throws when the version literal is absent", () => {
+		expect(() => goPinVersion("{ }")).toThrow(/dotted go version/);
+	});
+
+	test("throws on a non-dotted version (shape drift)", () => {
+		expect(() => goPinVersion('{ version = "latest"; }')).toThrow(
+			/dotted go version/,
+		);
+	});
+});
diff --git a/tools/renovate/refresh-go-overlay.core.ts b/tools/renovate/refresh-go-overlay.core.ts
new file mode 100644
index 00000000..bdfc54b5
--- /dev/null
+++ b/tools/renovate/refresh-go-overlay.core.ts
@@ -0,0 +1,73 @@
+// Pure decision/transform core for refresh-go-overlay.ts (RIG-3100).
+//
+// Split out from the entry point so the load-bearing string/JSON reads — the
+// go-overlay input's locked rev out of devenv.lock and the go version out of
+// go.nix — are unit-testable without a nix runner, a network, or a git tree.
+// The entry point owns the shell-outs (re-lock, eval); this file owns the
+// parsing. NO shell-outs, NO fs beyond text passed in.
+
+/**
+ * The concrete go-overlay rev the dev shell resolved, read from devenv.lock's
+ * `go-overlay` node (`nodes.go-overlay.locked.rev`). This is the overlay rev
+ * gate-tools.nix fetches (`lock.nodes.go-overlay.locked`) to resolve
+ * `go-bin.versions.<goPin>` — so a `devenv update go-overlay` that advances it
+ * is what makes a newly-released go version resolve. Parsed as JSON (devenv.lock
+ * is JSON), throwing loudly if the node or a 40-hex rev is absent — a shape
+ * change must fail the task, never silently eval against a stale (too-old) rev.
+ */
+export function goOverlayLockedRev(devenvLockText: string): string {
+	let lock: unknown;
+	try {
+		lock = JSON.parse(devenvLockText);
+	} catch (error) {
+		throw new Error(
+			`refresh-go-overlay: devenv.lock is not valid JSON: ${String(error)}`,
+		);
+	}
+	// Narrow with `in`/`typeof` at each level so every access is actually
+	// checked (devenv.lock is external-boundary data; no schema validator is in
+	// the repo). A shape change surfaces as the loud throw below, never a
+	// silently-wrong read.
+	const isObj = (v: unknown): v is Record<string, unknown> =>
+		typeof v === "object" && v !== null;
+	let rev: unknown;
+	if (isObj(lock) && "nodes" in lock && isObj(lock.nodes)) {
+		const node = lock.nodes["go-overlay"];
+		if (isObj(node) && "locked" in node && isObj(node.locked)) {
+			rev = node.locked.rev;
+		}
+	}
+	if (typeof rev !== "string" || !/^[a-f0-9]{40}$/.test(rev)) {
+		throw new Error(
+			"refresh-go-overlay: could not read a 40-hex go-overlay rev from devenv.lock " +
+				"(nodes['go-overlay'].locked.rev) — devenv lock shape may have changed.",
+		);
+	}
+	return rev;
+}
+
+// The go pin literal in tools/toolchain/versions/go.nix, which single-sources
+// the go toolchain version version-only (`{ version = "1.26.6"; }`, hashes come
+// from go-overlay). The go customManager in config.json5 rewrites exactly this
+// value on a bump; the refresh task reads it back to know which version the new
+// overlay rev must provide.
+const GO_PIN_VERSION_RE = /version\s*=\s*"([^"]+)"/;
+
+/**
+ * The go version pinned in go.nix, read from the `version = "<ver>"` literal.
+ * Returns the bare version string. Throws if the literal is absent or the value
+ * is not a dotted version (fail loud — a missing pin must not silently no-op and
+ * then validate the eval against `undefined`). Mirrors the raw-text read the
+ * config.json5 go manager's matchString does, so both key off the same literal.
+ */
+export function goPinVersion(goNixText: string): string {
+	const match = GO_PIN_VERSION_RE.exec(goNixText);
+	const version = match?.[1];
+	if (version === undefined || !/^\d+\.\d+/.test(version)) {
+		throw new Error(
+			"refresh-go-overlay: could not read a dotted go version from go.nix " +
+				'(`version = "<ver>"`) — go pin shape may have changed.',
+		);
+	}
+	return version;
+}
diff --git a/tools/renovate/refresh-go-overlay.test.ts b/tools/renovate/refresh-go-overlay.test.ts
new file mode 100644
index 00000000..3712cce8
--- /dev/null
+++ b/tools/renovate/refresh-go-overlay.test.ts
@@ -0,0 +1,226 @@
+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 { join } from "node:path";
+import { $ } from "bun";
+
+// Orchestration harness for tools/renovate/refresh-go-overlay.ts (RIG-3100).
+//
+// The pure transforms (rev/version extraction) are unit-tested in
+// refresh-go-overlay.core.test.ts. This drives the SHIPPED entry point end to
+// end inside a throwaway git repo with stub `devenv`/`nix` on PATH, so the step
+// SEQUENCING is exercised offline + deterministically: self-gate → read target
+// → advance overlay → validate eval. The real nix eval + devenv re-lock run for
+// real against the vendored devenv in the PR's own CI; here they are stubbed so
+// the failure mode under test is the script's own control flow, not the
+// network.
+
+// The shipped entry point, invoked as Renovate will: `bun tools/renovate/…ts`,
+// cwd = repo root. Copied into the throwaway repo so the SHIPPED file runs, not
+// a re-implementation.
+const SCRIPT_REL = "tools/renovate/refresh-go-overlay.ts";
+const CORE_REL = "tools/renovate/refresh-go-overlay.core.ts";
+const REAL_SCRIPT = join(import.meta.dir, "refresh-go-overlay.ts");
+const REAL_CORE = join(import.meta.dir, "refresh-go-overlay.core.ts");
+
+const GO_NIX_REL = "tools/toolchain/versions/go.nix";
+const GATE_REL = "tools/toolchain/gate-tools.nix";
+const DEVENV_LOCK_REL = "devenv.lock";
+
+// Hermetic git: identity from env only, no user/global/system config leakage.
+const HERMETIC_ENV = {
+	GIT_CONFIG_GLOBAL: "/dev/null",
+	GIT_CONFIG_SYSTEM: "/dev/null",
+	GIT_AUTHOR_NAME: "t",
+	GIT_AUTHOR_EMAIL: "t@t",
+	GIT_COMMITTER_NAME: "t",
+	GIT_COMMITTER_EMAIL: "t@t",
+	HOME: "/dev/null",
+};
+
+const OVERLAY_REV_BASE = "1111111111111111111111111111111111111111";
+const OVERLAY_REV_BUMP = "2222222222222222222222222222222222222222";
+
+const GO_VERSION_BASE = "1.26.6";
+const GO_VERSION_BUMP = "1.27.0";
+
+function goNix(version: string): string {
+	return `{ version = "${version}"; }\n`;
+}
+
+// Minimal devenv.lock carrying only the go-overlay node the core reads
+// (nodes['go-overlay'].locked.rev) — the field the script logs across the
+// advance.
+function devenvLock(overlayRev: string): string {
+	return `${JSON.stringify(
+		{
+			nodes: {
+				"go-overlay": {
+					locked: {
+						lastModified: 1,
+						narHash: "sha256-AAAA",
+						owner: "purpleclay",
+						repo: "go-overlay",
+						rev: overlayRev,
+						type: "github",
+					},
+					original: {
+						owner: "purpleclay",
+						repo: "go-overlay",
+						type: "github",
+					},
+				},
+				root: { inputs: { "go-overlay": "go-overlay" } },
+			},
+			root: "root",
+			version: 7,
+		},
+		null,
+		2,
+	)}\n`;
+}
+
+// A stand-in gate-tools.nix the stub `nix` never actually evaluates (the stub
+// intercepts `nix eval`), present only so the file the script names exists in
+// the tree — the SHIPPED script passes its path to `nix eval -f`.
+const GATE_STUB = "{ }\n";
+
+// Stub `devenv`: on `devenv update go-overlay`, rewrite devenv.lock to the
+// BUMPED overlay rev — simulating the real re-lock advancing the input to the
+// latest upstream rev. Any other invocation is a no-op success. Offline.
+const STUB_DEVENV = `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = "update" ]; then
+  cat > devenv.lock <<'LOCK'
+${devenvLock(OVERLAY_REV_BUMP)}
+LOCK
+fi
+exit 0
+`;
+
+// Stub `nix`: intercept `nix eval … -f <gate> langs.go.version`. Return the go
+// version go.nix now pins by reading it out of the tree — modelling the real
+// overlay resolving `go-bin.versions.<pin>` once the input is advanced. A
+// SENTINEL override file lets a test force a mismatch (an overlay that resolves
+// a DIFFERENT version) to exercise the fail-loud path.
+const STUB_NIX = `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = "eval" ]; then
+  if [ -f .force-resolved ]; then
+    cat .force-resolved
+    exit 0
+  fi
+  grep -oE 'version = "[^"]+"' ${GO_NIX_REL} | head -1 | sed -E 's/version = "([^"]+)"/\\1/' | tr -d '\\n'
+  exit 0
+fi
+exit 0
+`;
+
+async function buildRepo(): Promise<string> {
+	const repo = await mkdtemp(join(tmpdir(), "rig3100-"));
+	await mkdir(join(repo, "tools", "renovate"), { recursive: true });
+	await mkdir(join(repo, "tools", "toolchain", "versions"), {
+		recursive: true,
+	});
+	await mkdir(join(repo, "stubbin"), { recursive: true });
+
+	// Ship the REAL script + its core, so the SHIPPED file runs unmodified.
+	await Bun.write(join(repo, SCRIPT_REL), await readFile(REAL_SCRIPT, "utf8"));
+	await Bun.write(join(repo, CORE_REL), await readFile(REAL_CORE, "utf8"));
+
+	await Bun.write(join(repo, GO_NIX_REL), goNix(GO_VERSION_BASE));
+	await Bun.write(join(repo, GATE_REL), GATE_STUB);
+	await Bun.write(join(repo, DEVENV_LOCK_REL), devenvLock(OVERLAY_REV_BASE));
+
+	for (const [name, body] of [
+		["devenv", STUB_DEVENV],
+		["nix", STUB_NIX],
+	] as const) {
+		await Bun.write(join(repo, "stubbin", name), body);
+		await chmod(join(repo, "stubbin", name), 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();
+	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 as Renovate does: `bun tools/renovate/…ts`, cwd = repo
+// root, stubs first on PATH so no real nix/devenv/network is touched. The real
+// `bun` runs the script itself; git stays the real binary.
+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-go-overlay.ts coupling (RIG-3100)", () => {
+	let repo: string;
+	beforeEach(async () => {
+		repo = await buildRepo();
+	});
+	afterEach(async () => {
+		if (repo) await rm(repo, { recursive: true, force: true });
+	});
+
+	// Self-gate: with go.nix unchanged vs base, the script is a cheap no-op — no
+	// overlay advance, no eval. Guards the gate against being dropped (an
+	// unconditional run would re-lock + eval on EVERY Renovate branch). Gate on
+	// go.nix, the file the go manager rewrites — NOT devenv.lock.
+	test("is a no-op when go.nix is unchanged vs base", async () => {
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+		expect(res.stdout.toString()).toContain("nothing to do");
+		// devenv.lock untouched (overlay not advanced).
+		const lock = await readFile(join(repo, DEVENV_LOCK_REL), "utf8");
+		expect(lock).toContain(OVERLAY_REV_BASE);
+		expect(lock).not.toContain(OVERLAY_REV_BUMP);
+	});
+
+	// The end-to-end happy path: bump go.nix (what the customManager's regex
+	// update does), run the script, and assert it advanced the go-overlay input
+	// in devenv.lock and the CI-path eval now resolves the bumped version.
+	test("advances go-overlay and validates the bumped version resolves", async () => {
+		await Bun.write(join(repo, GO_NIX_REL), goNix(GO_VERSION_BUMP));
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+		expect(res.stdout.toString()).not.toContain("nothing to do");
+		expect(res.stdout.toString()).toContain(
+			`target version=${GO_VERSION_BUMP}`,
+		);
+		// devenv.lock's go-overlay rev advanced to the bumped rev.
+		const lock = await readFile(join(repo, DEVENV_LOCK_REL), "utf8");
+		expect(lock).toContain(OVERLAY_REV_BUMP);
+		expect(lock).not.toContain(OVERLAY_REV_BASE);
+		// The validation eval saw the bumped version resolve.
+		expect(res.stdout.toString()).toContain(`resolves go ${GO_VERSION_BUMP}`);
+	});
+
+	// Fail-loud: if the overlay advance does NOT land the pinned version (the rev
+	// is still too old, so the CI-path eval resolves a DIFFERENT version), the
+	// script must die non-zero rather than ship a go bump the overlay can't
+	// resolve — the whole point of the validation step.
+	test("fails loud (exit≠0) when the resolved version mismatches the pin", async () => {
+		await Bun.write(join(repo, GO_NIX_REL), goNix(GO_VERSION_BUMP));
+		// Force the stub eval to resolve a stale version, as a too-old overlay
+		// rev would (the attr for the new version is missing, so the resolver
+		// lands the older one it does carry).
+		await Bun.write(join(repo, ".force-resolved"), GO_VERSION_BASE);
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).not.toBe(0);
+	});
+});
diff --git a/tools/renovate/refresh-go-overlay.ts b/tools/renovate/refresh-go-overlay.ts
new file mode 100644
index 00000000..235f87a0
--- /dev/null
+++ b/tools/renovate/refresh-go-overlay.ts
@@ -0,0 +1,172 @@
+// Renovate postUpgradeTask: couple a go toolchain pin bump to a go-overlay
+// input refresh (RIG-3100).
+//
+// Context. Compass single-sources the go version in
+// tools/toolchain/versions/go.nix (`{ version = "1.26.6"; }`, version-only —
+// the per-platform hashes come from the go-overlay flake input). Both the dev
+// shell (devenv.nix, `go_X_Y_Z` overlay attr) and the parity gate
+// (tools/toolchain/gate-tools.nix, `go-bin.versions.<ver>`) select go-overlay
+// at that pinned version, and both build over the devenv.lock-pinned
+// go-overlay rev. The go customManager (config.json5) opens a branch that
+// rewrites ONLY the version string in go.nix. But go-overlay's `versions` set
+// only carries go releases at or before the rev pinned in devenv.lock — so when
+// Renovate bumps go.nix to a version newer than that rev provides, CI evals
+// `go-bin.versions.<new>` against a stale overlay and dies with `attribute
+// '"<ver>"' missing` / `gate-tools.nix langs produced no store paths`. This
+// task, run on that branch, makes the bump land green in one PR:
+//
+//   1. Self-gate — exit 0 unless go.nix differs from the base branch, so it's a
+//      cheap no-op on every non-go Renovate branch (mirrors
+//      refresh-devenv-nixpkgs.ts's devenv.lock gate; the trigger file here is
+//      go.nix, the file the go manager rewrites — NOT devenv.lock, which the go
+//      bump does not touch).
+//   2. Read target — the go version go.nix now pins (the bump's new value).
+//   3. Advance the overlay — `devenv update go-overlay` re-locks the go-overlay
+//      input in devenv.lock to its latest upstream rev (which provides the new
+//      go release). Networked, but light: it re-locks the input, it does NOT
+//      build the toolchain. Fail loud: a stale lock must never ship.
+//   4. Validate build-free — eval that the new go version now resolves through
+//      the SAME path CI uses: gate-tools.nix's `langs.go.version`, which selects
+//      `go-bin.versions.<goPin>` over the (now-advanced) overlay rev. A
+//      `.version` selector is eval-only (no toolchain build); a still-too-old
+//      overlay makes the attr missing and the eval FAILS here, loud and
+//      in-branch, instead of red CI on the PR. Assert the evaluated version ===
+//      the go.nix target — the core correctness guarantee.
+//
+// Design: docs/designs/repo/compass-renovate-migration.md
+//
+// Invoked by the go packageRule's postUpgradeTasks command (config.json5) as
+// `bun tools/renovate/refresh-go-overlay.ts`, allowlisted in bot-config.json5.
+// Requires `nix` (nix-command) + `devenv` + `bun` + network on the runner PATH
+// — the Renovate workflow provisions nix and the vendored devenv shim (there is
+// no ambient devenv on compass CI).
+//
+// Exit codes:
+//   0 - overlay advanced + validated (or a no-op branch: go.nix unchanged vs
+//       base).
+//   1 - a step failed (re-lock or the validation eval) — fail loud, never ship a
+//       go bump the overlay cannot resolve.
+
+import { readFileSync } from "node:fs";
+import { $ } from "bun";
+import { goOverlayLockedRev, goPinVersion } from "./refresh-go-overlay.core.ts";
+
+// The go toolchain pin — the file the go manager rewrites and this task's
+// self-gate trigger. The gate file CI evals `langs` from — the same resolver
+// the dev shell and the parity gate select go through, so validating its
+// `langs.go.version` proves the real CI path. Repo-root-relative (the runner
+// cwd = repo root).
+const GO_NIX = "tools/toolchain/versions/go.nix";
+const GO_NIX_GATE_FILE = "tools/toolchain/gate-tools.nix";
+// The devenv lock the overlay refresh re-locks; read to log the go-overlay rev
+// before/after the advance so the coupling is observable in the task log.
+const DEVENV_LOCK = "devenv.lock";
+
+/**
+ * Read the pinned go version resolved through gate-tools.nix's `langs.go` — the
+ * EXACT path CI uses (ci.yml `nix eval -f tools/toolchain/gate-tools.nix
+ * langs`), so a validation pass here proves the real CI eval will pass. The
+ * `.version` selector is eval-only: it reads the derivation's version attribute
+ * without building the toolchain. A go-overlay rev too old to carry the pinned
+ * version makes `go-bin.versions.<ver>` a missing attribute, so this eval FAILS
+ * — which is the signal.
+ *
+ * Empirically confirmed against the current tree (go.nix=1.26.6, overlay pinned
+ * at 675c971d) — this exact invocation returns `1.26.6`:
+ *   nix eval --raw --extra-experimental-features 'nix-command flakes' \
+ *     -f tools/toolchain/gate-tools.nix langs.go.version
+ */
+async function evalResolvedGoVersion(): Promise<string> {
+	// --raw so the value is the bare version string, no JSON quoting. The extra
+	// experimental-features flag matches how the toolchain hook invokes nix; the
+	// runner enables nix-command but we pass it explicitly so a local run
+	// (tests, a manual repro) works without relying on the ambient nix.conf.
+	const version = (
+		await $`nix eval --raw --extra-experimental-features ${"nix-command flakes"} -f ${GO_NIX_GATE_FILE} ${"langs.go.version"}`.text()
+	).trim();
+	if (!/^\d+\.\d+/.test(version)) {
+		throw new Error(
+			`refresh-go-overlay: eval of ${GO_NIX_GATE_FILE} langs.go.version yielded a non-version string ${JSON.stringify(version)}`,
+		);
+	}
+	return version;
+}
+
+async function main(): Promise<number> {
+	// Resolve the repo root from git, not a hardcoded depth — Renovate invokes
+	// this as a postUpgradeTask and every path below is repo-root-relative, so a
+	// wrong cwd would silently no-op the gate. git is already a hard dependency
+	// here.
+	const repoRoot = (await $`git rev-parse --show-toplevel`.text()).trim();
+	process.chdir(repoRoot);
+
+	// ── Step 1: self-gate on go.nix changing vs the base branch. ──
+	// The go bump rewrites go.nix (NOT devenv.lock — the overlay refresh below is
+	// what will write devenv.lock), so gate on go.nix, the file the go manager
+	// touches.
+	const baseBranch = process.env.RENOVATE_BASE_BRANCH || "main";
+	// Prefer the remote-tracking ref (matches the toolchain hook); fall back to
+	// the bare branch name when origin/<base> is absent (a local run).
+	let baseRef = baseBranch;
+	if (
+		(
+			await $`git rev-parse --verify -q ${`origin/${baseBranch}`}`
+				.nothrow()
+				.quiet()
+		).exitCode === 0
+	) {
+		baseRef = `origin/${baseBranch}`;
+	}
+	const goNixUnchanged =
+		(await $`git diff --quiet ${baseRef} -- ${GO_NIX}`.nothrow().quiet())
+			.exitCode === 0;
+	if (goNixUnchanged) {
+		console.log(
+			`refresh-go-overlay: ${GO_NIX} unchanged vs ${baseRef}; nothing to do.`,
+		);
+		return 0;
+	}
+
+	// ── Step 2: read the target go version the bump now pins. ──
+	const targetVersion = goPinVersion(readFileSync(GO_NIX, "utf8"));
+	console.log(`refresh-go-overlay: go.nix target version=${targetVersion}`);
+
+	// ── Step 3: advance the go-overlay input to a rev that provides it. ──
+	// The regex bump moved only go.nix's version string; the overlay rev pinned
+	// in devenv.lock may predate that go release, so `go-bin.versions.<new>` is a
+	// missing attr. `devenv update go-overlay` re-locks that one input to its
+	// latest upstream rev without building the toolchain. Fail loud — a stale
+	// lock ships a go bump the overlay cannot resolve.
+	const overlayRevBefore = goOverlayLockedRev(
+		readFileSync(DEVENV_LOCK, "utf8"),
+	);
+	console.log(
+		`refresh-go-overlay: advancing go-overlay from ${overlayRevBefore} (devenv update go-overlay) ...`,
+	);
+	await $`devenv update go-overlay`;
+	const overlayRevAfter = goOverlayLockedRev(readFileSync(DEVENV_LOCK, "utf8"));
+	console.log(`refresh-go-overlay: go-overlay now at ${overlayRevAfter}.`);
+
+	// ── Step 4: validate the new version resolves through the CI path. ──
+	// Eval gate-tools.nix's langs.go.version — the same resolver CI runs (ci.yml
+	// evals `langs` from this file) — so a pass here proves the PR's CI eval
+	// passes. A still-too-old overlay makes the attr missing and this eval throws
+	// non-zero, in-branch. Assert the resolved version matches the target so a
+	// partial/wrong overlay advance never slips through green.
+	console.log(
+		`refresh-go-overlay: validating go ${targetVersion} resolves via ${GO_NIX_GATE_FILE} langs.go ...`,
+	);
+	const resolved = await evalResolvedGoVersion();
+	if (resolved !== targetVersion) {
+		throw new Error(
+			`refresh-go-overlay: overlay resolves go ${resolved} but go.nix pins ${targetVersion} — ` +
+				"the go-overlay refresh did not land the pinned version (rev still too old, or a mismatched advance).",
+		);
+	}
+	console.log(
+		`refresh-go-overlay: validated — go-overlay now resolves go ${resolved}. done.`,
+	);
+	return 0;
+}
+
+process.exit(await main());

From 629ff8601dfef3907bebc8a8a3ee1055cb2f0668 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 2 Sep 2026 18:28:43 -0400
Subject: [PATCH 2/2] test(renovate): harden go-overlay coupling tests
 (RIG-3100 review)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address the review's two low findings on the go↔go-overlay lockstep:

- refresh-go-overlay.test.ts: model the PRIMARY RIG-3100 failure (a
  too-old overlay makes go-bin.versions.<new> a MISSING attr, so the
  CI-path eval exits non-zero) via a new `.force-eval-fail` stub sentinel
  + a fail-loud test; assert the shipped eval hits the REAL CI target
  (gate-tools.nix langs.go.version) by recording the stub's args, so a
  typo'd file/attr can't pass green against an arg-agnostic stub.
- config.test.ts: extend the solo-branch grouping guard to cover a
  `major` go bump as well as `minor` (test.each), documenting that a
  major bump also un-groups to its own branch and gets the overlay refresh.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/config.test.ts             | 30 +++++++------
 tools/renovate/refresh-go-overlay.test.ts | 52 +++++++++++++++++------
 2 files changed, 58 insertions(+), 24 deletions(-)

diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index c90109c2..47c66fbb 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -594,18 +594,24 @@ describe("tools/renovate go ↔ go-overlay lockstep (RIG-3100)", () => {
 	// 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.
-	test("a go pin bump un-groups to its own solo branch (null), not the TS rollup", () => {
-		const group = resolveGroupName({
-			manager: "custom.regex",
-			fileName: "tools/toolchain/versions/go.nix",
-			depName: "go",
-			depType: "toolchain",
-			updateType: "minor",
-		});
-		expect(group).toBeNull();
-		expect(group).not.toBe("TypeScript dependencies");
-	});
+	// 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) => {
+			const group = resolveGroupName({
+				manager: "custom.regex",
+				fileName: "tools/toolchain/versions/go.nix",
+				depName: "go",
+				depType: "toolchain",
+				updateType,
+			});
+			expect(group).toBeNull();
+			expect(group).not.toBe("TypeScript dependencies");
+		},
+	);
 });
 
 describe("tools/renovate solo-branch grouping outcomes", () => {
diff --git a/tools/renovate/refresh-go-overlay.test.ts b/tools/renovate/refresh-go-overlay.test.ts
index 3712cce8..1c07e43f 100644
--- a/tools/renovate/refresh-go-overlay.test.ts
+++ b/tools/renovate/refresh-go-overlay.test.ts
@@ -98,14 +98,24 @@ fi
 exit 0
 `;
 
-// Stub `nix`: intercept `nix eval … -f <gate> langs.go.version`. Return the go
-// version go.nix now pins by reading it out of the tree — modelling the real
-// overlay resolving `go-bin.versions.<pin>` once the input is advanced. A
-// SENTINEL override file lets a test force a mismatch (an overlay that resolves
-// a DIFFERENT version) to exercise the fail-loud path.
+// Stub `nix`: intercept `nix eval … -f <gate> langs.go.version` and model the
+// two go-overlay outcomes the script must tell apart. It records its args so a
+// test can assert the SHIPPED script evals the REAL CI target (a typo'd
+// file/attr would otherwise pass green here), then branches on sentinel files:
+//   .force-eval-fail — the PRIMARY RIG-3100 failure: a too-old overlay makes
+//     go-bin.versions.<new> a MISSING attr, so `nix eval` exits non-zero.
+//   .force-resolved  — a partial/wrong advance: the eval SUCCEEDS but yields a
+//     DIFFERENT version, exercising the resolved !== target equality guard.
+// With neither, it reads the version go.nix now pins out of the tree — modelling
+// the real overlay resolving go-bin.versions.<pin> once the input is advanced.
 const STUB_NIX = `#!/usr/bin/env bash
 set -euo pipefail
 if [ "\${1:-}" = "eval" ]; then
+  echo "$@" > .nix-eval-args
+  if [ -f .force-eval-fail ]; then
+    echo "error: attribute matching the pinned go version is missing" >&2
+    exit 1
+  fi
   if [ -f .force-resolved ]; then
     cat .force-resolved
     exit 0
@@ -207,20 +217,38 @@ describe("tools/renovate/refresh-go-overlay.ts coupling (RIG-3100)", () => {
 		expect(lock).not.toContain(OVERLAY_REV_BASE);
 		// The validation eval saw the bumped version resolve.
 		expect(res.stdout.toString()).toContain(`resolves go ${GO_VERSION_BUMP}`);
+		// The eval hit the REAL CI target (gate-tools.nix langs.go.version), not a
+		// typo'd file/attr that would pass green against an arg-agnostic stub.
+		const evalArgs = await readFile(join(repo, ".nix-eval-args"), "utf8");
+		expect(evalArgs).toContain(GATE_REL);
+		expect(evalArgs).toContain("langs.go.version");
 	});
 
-	// Fail-loud: if the overlay advance does NOT land the pinned version (the rev
-	// is still too old, so the CI-path eval resolves a DIFFERENT version), the
-	// script must die non-zero rather than ship a go bump the overlay can't
-	// resolve — the whole point of the validation step.
+	// Fail-loud, partial-advance case: the overlay advances but still resolves a
+	// DIFFERENT version than the pin (a wrong/partial advance where the eval
+	// SUCCEEDS). The resolved !== target equality guard must catch it and die
+	// non-zero rather than ship a go bump the overlay does not actually resolve.
 	test("fails loud (exit≠0) when the resolved version mismatches the pin", async () => {
 		await Bun.write(join(repo, GO_NIX_REL), goNix(GO_VERSION_BUMP));
-		// Force the stub eval to resolve a stale version, as a too-old overlay
-		// rev would (the attr for the new version is missing, so the resolver
-		// lands the older one it does carry).
+		// Force the eval to resolve a DIFFERENT version than the pin, modelling a
+		// partial/wrong overlay advance whose eval succeeds — exercising the
+		// equality guard (the missing-attr eval-throw is the sibling test below).
 		await Bun.write(join(repo, ".force-resolved"), GO_VERSION_BASE);
 
 		const res = await runRefresh(repo);
 		expect(res.exitCode).not.toBe(0);
 	});
+
+	// Fail-loud, missing-attr case: the PRIMARY RIG-3100 failure. A still-too-old
+	// overlay makes `go-bin.versions.<new>` a missing attribute, so the CI-path
+	// eval itself exits non-zero — it does NOT fall back to an older release. The
+	// script must propagate that as a non-zero exit, in-branch, instead of red CI
+	// on the PR.
+	test("fails loud (exit≠0) when the validation eval fails (missing overlay attr)", async () => {
+		await Bun.write(join(repo, GO_NIX_REL), goNix(GO_VERSION_BUMP));
+		await Bun.write(join(repo, ".force-eval-fail"), "");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).not.toBe(0);
+	});
 });