From 9145227afbb19eb7d886688a708df94b0045c3a0 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 9 Sep 2026 15:11:35 -0400
Subject: [PATCH] feat(renovate): track the agent-image nixpkgs channel pin
 (RIG-3365)

The agent base image's devenv scope pins both a devenv-nixpkgs channel rev and
a RigelBuild/devenv fork rev, but only the fork was tracked. Three of the four
devenv pins in the tree moved on a Renovate cadence; agent-image's channel rev
only ever moved when someone relocked it by hand.

Add the fourth pin: a customManager over agent-image/devenv.lock's nixpkgs node
under its own depName, a solo-branched packageRule, and a scope-correct
refresher that relocks via the devenv CLI the lock itself pins.

The refresher is separate from refresh-devenv-nixpkgs.ts rather than a widened
scope on it. That script's tail is root-only: it mirrors the channel's biome
into the catalog and locksteps the repo-root flake.nix. agent-image bakes
nothing into a shell and has no flake, so widening would put the whole tail
behind a conditional on a path two live rules already depend on.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/bot-config.json5               |  18 +-
 tools/renovate/config.json5                   | 137 ++++++-
 tools/renovate/config.test.ts                 | 268 ++++++++++--
 .../refresh-agent-image-nixpkgs.core.ts       |  81 ++++
 .../refresh-agent-image-nixpkgs.test.ts       | 381 ++++++++++++++++++
 tools/renovate/refresh-agent-image-nixpkgs.ts | 278 +++++++++++++
 tools/renovate/refresh-fod-hashes.ts          |  68 +++-
 7 files changed, 1180 insertions(+), 51 deletions(-)
 create mode 100644 tools/renovate/refresh-agent-image-nixpkgs.core.ts
 create mode 100644 tools/renovate/refresh-agent-image-nixpkgs.test.ts
 create mode 100644 tools/renovate/refresh-agent-image-nixpkgs.ts

diff --git a/tools/renovate/bot-config.json5 b/tools/renovate/bot-config.json5
index 27213769..e19bda76 100644
--- a/tools/renovate/bot-config.json5
+++ b/tools/renovate/bot-config.json5
@@ -82,7 +82,7 @@
   // addon, so the workflow sets RENOVATE_X_IGNORE_RE2=true to take the RegExp path
   // quietly.)
   //
-  // Six entries, all load-bearing:
+  // Seven 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
@@ -121,9 +121,18 @@
   //      regex-bumped rev beside a stale hash. Both devenv-fork packageRules
   //      declare this ONE command — the script self-gates on WHICH lock
   //      changed — so one entry covers both (RIG-2815).
-  // (1), (3), (4), (5), and (6) are `bun <script>.ts` — the Renovate hooks are
-  // TypeScript run via bun (AGENTS.md "Scripts: TypeScript over bash"); bun is on
-  // the runner PATH.
+  //   7. the agent-image devenv-nixpkgs CHANNEL relock, the fourth devenv pin:
+  //      on that lock's channel digest bump it runs `devenv update nixpkgs` in
+  //      agent-image/ under that lock's own devenv, then refreshes
+  //      agent-image/entrypoint.nix's bun `outputHash` — the channel rev
+  //      resolves the bun that FOD's builder uses, so an advance can invalidate
+  //      the pin with no manifest change. SEPARATE from (3) because the root
+  //      channel script's tail (biome eval, catalog pin, bun.lock, flake
+  //      lockstep) has no counterpart in this scope: agent-image bakes no dev
+  //      shell (`packages = [ ]`) and has no flake.
+  // (1), (3), (4), (5), (6), and (7) are `bun <script>.ts` — the Renovate hooks
+  // are TypeScript run via bun (AGENTS.md "Scripts: TypeScript over bash"); bun
+  // is on the runner PATH.
   allowedCommands: [
     "^bun tools/renovate/refresh-toolchain-hashes\\.ts$",
     "^bun install --lockfile-only$",
@@ -131,5 +140,6 @@
     "^bun tools/renovate/refresh-fod-hashes\\.ts$",
     "^bun tools/renovate/refresh-go-overlay\\.ts$",
     "^bun tools/renovate/refresh-devenv-lock\\.ts$",
+    "^bun tools/renovate/refresh-agent-image-nixpkgs\\.ts$",
   ],
 }
diff --git a/tools/renovate/config.json5 b/tools/renovate/config.json5
index 47eede70..351c00e7 100644
--- a/tools/renovate/config.json5
+++ b/tools/renovate/config.json5
@@ -253,6 +253,63 @@
       currentValueTemplate: "main",
       datasourceTemplate: "git-refs",
     },
+    {
+      // ── devenv nixpkgs channel: agent base image ──
+      // The agent base image resolves the same rolling channel the root dev
+      // shell does (agent-image/devenv.yaml `inputs.nixpkgs.url =
+      // github:cachix/devenv-nixpkgs/rolling`), so its concrete rev lives only
+      // in agent-image/devenv.lock — and until this manager existed nothing
+      // moved it: it only advanced when someone relocked by hand, while the
+      // three sibling pins (root channel, root fork, agent-image fork) all
+      // tracked. This manager surfaces it as a git-refs digest so Renovate
+      // opens a reviewable branch, and the coupled packageRule below relocks
+      // the file properly on that branch.
+      //
+      // WHAT THIS REV GOVERNS. It resolves the image's toolchain closure:
+      // agent-image/toolchain.nix overlays the repo's own vendored bun, but
+      // `pkgs.cacert`, `pkgs.devenv`, and `getent` come straight from this pin
+      // — and agent-image/entrypoint.nix's FOD builder takes
+      // `nativeBuildInputs = [ pkgs.bun ]` from it too, which is why the rule
+      // below must also refresh that `outputHash` (see its note).
+      //
+      // WHY NOT JUST WIDEN THE ROOT CHANNEL MANAGER'S managerFilePatterns. RD-1
+      // unifies the devenv SOURCE across the two scopes but deliberately does
+      // NOT reconcile the two locks — each tracks the channel on its OWN
+      // cadence, and the two revs are legitimately skewed today. A widened
+      // pattern would collapse both files into ONE dep carrying two
+      // conflicting digests. So this is a second manager over the second file,
+      // and its `depNameTemplate` is DISTINCT
+      // (`cachix/devenv-nixpkgs-agent-image`, not the upstream slug) so the two
+      // rules are independently governed and, crucially, land in DIFFERENT
+      // groups/branches — the same distinct-name fencing idiom the agent-image
+      // FORK manager above and the `postgres-stack` manager below use. The
+      // lockFileMaintenance-is-unimplementable reasoning on the fork managers
+      // applies verbatim here.
+      //
+      // Anchor: `"repo": "devenv-nixpkgs"` immediately followed by `"rev"`.
+      // devenv writes alphabetized keys inside each `locked` block (…owner,
+      // repo, rev, type…), so this pair is unique in the file — the `original`
+      // block repeats `"repo": "devenv-nixpkgs"` but is followed by `"ref"`,
+      // never `"rev"`, so the regex cannot mis-bind. The trailing `-nixpkgs`
+      // also keeps it off the `"devenv"` fork node the manager above owns (and
+      // that manager's closing `"devenv",` quote+comma keeps it off this one).
+      // The inner `nixpkgs-src` node (upstream NixOS/nixpkgs) is deliberately
+      // NOT matched: the relock refreshes it from this outer rev.
+      // config.test.ts pins the extraction against the real lock.
+      customType: "regex",
+      // The interior slash is escaped so the whole value reads unambiguously as
+      // a `/…/`-delimited regex, matching the agent-image fork manager above
+      // (behaviourally identical under Renovate's parseRegexMatch;
+      // config.test.ts pins the literal).
+      managerFilePatterns: ["/^agent-image\\/devenv\\.lock$/"],
+      matchStrings: [
+        "\"repo\": \"devenv-nixpkgs\",\\s*\"rev\": \"(?<currentDigest>[a-f0-9]{40})\"",
+      ],
+      depNameTemplate: "cachix/devenv-nixpkgs-agent-image",
+      packageNameTemplate: "https://github.com/cachix/devenv-nixpkgs",
+      currentValueTemplate: "rolling",
+      datasourceTemplate: "git-refs",
+    },
     {
       // ── bun toolchain pin ──
       // tools/toolchain/versions/bun.nix pins the vendored bun version; the native
@@ -779,9 +836,85 @@
       groupName: "devenv fork (agent-image)",
       schedule: ["before 4am"],
       minimumReleaseAge: null,
+      // The FOD refresh rides LAST, after the relock: `agent-image/devenv.lock`
+      // is a declared trigger of the `agent-image/entrypoint.nix` entry (it
+      // supplies that consumer's `pkgs.bun`), so a branch that commits this lock
+      // must recompute the pin against the WRITTEN lock, not the still-at-base
+      // one. `agent-image/entrypoint.nix` is listed because fileFilters is an
+      // INCLUDE allowlist over what Renovate commits: without it the refreshed
+      // pin would be computed and then silently dropped.
+      postUpgradeTasks: {
+        commands: [
+          "bun tools/renovate/refresh-devenv-lock.ts",
+          "bun tools/renovate/refresh-fod-hashes.ts",
+        ],
+        fileFilters: ["agent-image/devenv.lock", "agent-image/entrypoint.nix"],
+        executionMode: "branch",
+      },
+    },
+    {
+      // ── devenv nixpkgs channel currency: agent base image ──
+      // The agent-image sibling of the root channel rule above, scoped by the
+      // DISTINCT depName its manager stamps
+      // (`cachix/devenv-nixpkgs-agent-image`) and carrying its OWN groupName.
+      // Both properties are load-bearing: the distinct name keeps the two
+      // channel rules independently governed, and the distinct groupName is
+      // what puts the two locks on independent cadences (RD-1: unify the
+      // source, do NOT reconcile the locks) AND guarantees the branch-mode
+      // tasks never contend for one branch's single task slot. The rollup
+      // cannot capture this dep regardless — its update type is `digest` and
+      // the rollup admits only patch/minor. `minimumReleaseAge: null` for the
+      // same git-refs-carries-no-release-age reason as its siblings: a strict
+      // cooldown would peg the digest permanently `pending` and cut zero PRs
+      // (the RIG-1220 silent-no-updates shape), and the compensating control is
+      // the mandatory human review of the PR before merge (no automerge is
+      // configured). Daily, in the same before-4am-ET window the daily cron
+      // lands in — matching the root channel rule's cadence, since `rolling`
+      // moves near-daily.
+      matchManagers: ["custom.regex"],
+      matchDepNames: ["cachix/devenv-nixpkgs-agent-image"],
+      groupName: "devenv nixpkgs channel (agent-image)",
+      schedule: ["before 4am"],
+      minimumReleaseAge: null,
+      // ── The relock task. ──
+      // A SEPARATE script from the root channel's lockstep, deliberately: that
+      // one's tail is root-only (eval biome from the resolved raw nixpkgs,
+      // rewrite the biome catalog pin, re-resolve bun.lock, lockstep
+      // flake.nix/flake.lock), and NEITHER coupling exists in this scope —
+      // agent-image/devenv.nix is `packages = [ ]` (it bakes nothing into a
+      // dev shell; the devenv exists only to express the container) and there
+      // is no agent-image/flake.nix. This script relocks the channel input in
+      // agent-image/ under that lock's OWN devenv, then refreshes the FOD hash.
+      //
+      // WHY THE FOD REFRESH IS PRESENT HERE (unlike the root channel rule, which
+      // documents its exemption): this rev resolves the bun that
+      // agent-image/entrypoint.nix's FOD builder uses (`nativeBuildInputs = [
+      // pkgs.bun ]`), and that install tree IS what its `outputHash`
+      // content-addresses. So a channel advance here can move the hash with no
+      // manifest change at all — left stale, the image build fails
+      // `hash mismatch in fixed-output derivation`.
+      //
+      // `executionMode: "branch"` runs it once after the digest update is
+      // applied; safe because this dep never shares a branch (its own groupName
+      // above), so it owns 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 self-gates on the
+      // versions/*.nix pins + go.mod/bun.lock and would be a no-op here anyway
+      // — but note its FOD leg is exactly what this script re-does in step 3,
+      // which is why the refresh must be wired here rather than relied upon
+      // from the evicted slot. fileFilters is an INCLUDE allowlist — Renovate
+      // commits ONLY files matching it — so it names EXACTLY the two files this
+      // task writes: the lock (the relock) and entrypoint.nix (the FOD hash).
+      // Omit the latter and Renovate would run the refresh but silently DROP
+      // it, shipping a channel bump whose outputHash never moved.
+      //
+      // Self-hosted bot config MUST allow the command:
+      //   allowedCommands: [… , "^bun tools/renovate/refresh-agent-image-nixpkgs\\.ts$"]
+      // see tools/renovate/bot-config.json5 (config.test.ts pins the two
+      // together).
       postUpgradeTasks: {
-        commands: ["bun tools/renovate/refresh-devenv-lock.ts"],
-        fileFilters: ["agent-image/devenv.lock"],
+        commands: ["bun tools/renovate/refresh-agent-image-nixpkgs.ts"],
+        fileFilters: ["agent-image/devenv.lock", "agent-image/entrypoint.nix"],
         executionMode: "branch",
       },
     },
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index 97803d7e..63102cde 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -200,7 +200,7 @@ 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 six DISTINCT
+	// entry's `^…$` IS the security property. Compass declares seven DISTINCT
 	// commands across the task sites (the FOD-hash refresh rides FIVE sites — see
 	// the per-site enumeration on the count test below — so it appears five times
 	// in the declared list but needs only one allowlist entry; the devenv-fork
@@ -209,26 +209,31 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 	// distinct command must be permitted, every entry must be used, and no entry may
 	// be an unanchored substring rule. RIG-3100 added the fifth: the go↔go-overlay
 	// lockstep on the go pin's solo branch. RIG-2815 added the sixth: the
-	// devenv-fork relock on each devenv lock's solo branch.
+	// devenv-fork relock on each devenv lock's solo branch. The seventh is the
+	// agent-image devenv-nixpkgs CHANNEL relock — the fourth devenv pin, on its
+	// own solo branch, with its own script because the root channel script's
+	// biome/catalog/bun.lock/flake tail has no counterpart in that scope.
 	const commands = allDeclaredCommands();
 	const distinctCommands = [...new Set(commands)];
 	const allowed = bot.allowedCommands ?? [];
 
-	test("declares six DISTINCT postUpgrade commands and six allowlist entries", () => {
-		expect(distinctCommands).toHaveLength(6);
-		expect(allowed).toHaveLength(6);
+	test("declares seven DISTINCT postUpgrade commands and seven allowlist entries", () => {
+		expect(distinctCommands).toHaveLength(7);
+		expect(allowed).toHaveLength(7);
 	});
 
-	test("the fod-hash refresh is declared at all five task sites", () => {
+	test("the fod-hash refresh is declared at all six task sites", () => {
 		// The command must ride every task shape that can own a bump able to move a
 		// pinned FOD, because a rule-level task REPLACES the top-level one on its
-		// branch. The five sites, all carrying the refresh:
+		// branch. The six sites, all carrying the refresh:
 		//   1. top-level (branch mode)      — gomod + bun/TypeScript-first branches
 		//   2. devenv-nixpkgs channel rule  — the channel moves pkgs.bun
 		//   3. devenv fork (root) rule      — relocks devenv.lock, a declared trigger
 		//   4. go ↔ go-overlay lockstep     — relocks devenv.lock likewise
 		//   5. workspaces.catalog rule      — update mode, eviction-proof
-		// Sites 3 and 4 carry it fail-safe: each relocks ONE non-nixpkgs input, so
+		//   6. devenv fork (agent-image)    — relocks agent-image/devenv.lock, a
+		//                                     declared trigger of the same pin
+		// Sites 3, 4 and 6 carry it fail-safe: each relocks ONE non-nixpkgs input, so
 		// neither moves pkgs.bun today — but each writes a declared trigger of the
 		// entrypoint.nix entry, so the coupling holds at file granularity and the
 		// refresh's write is a no-op when nothing moved (the gate itself fires on
@@ -237,7 +242,7 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 		// this file is what keeps that coverage property true for future sites: it
 		// derives from FOD_ENTRIES that any site declaring a trigger must run the
 		// refresh LAST and name the pin's file.
-		expect(commands.filter((c) => c === FOD_COMMAND)).toHaveLength(5);
+		expect(commands.filter((c) => c === FOD_COMMAND)).toHaveLength(6);
 		const topLevel = cfg.postUpgradeTasks?.commands ?? [];
 		expect(topLevel).toContain(FOD_COMMAND);
 		const catalogRule = cfg.packageRules.find(
@@ -278,10 +283,11 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 		).toBe(false);
 	});
 
-	test("permits exactly the six RIG-2432/RIG-3100/RIG-2815 commands", () => {
+	test("permits exactly the seven declared commands", () => {
 		expect(distinctCommands.sort()).toEqual(
 			[
 				"bun install --lockfile-only",
+				"bun tools/renovate/refresh-agent-image-nixpkgs.ts",
 				"bun tools/renovate/refresh-devenv-lock.ts",
 				"bun tools/renovate/refresh-devenv-nixpkgs.ts",
 				"bun tools/renovate/refresh-fod-hashes.ts",
@@ -617,11 +623,10 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 		lock: string;
 		groupName: string;
 		patternLiteral: string;
-		// The rule's WHOLE declared task, pinned literally per scope. The two
-		// diverge: the root lock (devenv.lock) is a declared trigger of the
-		// entrypoint.nix FOD entry, so that rule must also carry the FOD refresh
-		// and name the FOD file; the agent-image lock is not a declared trigger
-		// (a separately-filed gap), so its task stays relock-only.
+		// The rule's WHOLE declared task, pinned literally per scope. Both locks are
+		// declared triggers of the entrypoint.nix FOD entry — each supplies a
+		// `pkgs.bun` to one of that file's two importers — so both rules carry the
+		// FOD refresh and name the FOD file.
 		taskCommands: string[];
 		taskFileFilters: string[];
 	}[] = [
@@ -640,8 +645,11 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 			lock: "agent-image/devenv.lock",
 			groupName: "devenv fork (agent-image)",
 			patternLiteral: "/^agent-image\\/devenv\\.lock$/",
-			taskCommands: [RELOCK],
-			taskFileFilters: ["agent-image/devenv.lock"],
+			taskCommands: [RELOCK, FOD_COMMAND],
+			taskFileFilters: [
+				"agent-image/devenv.lock",
+				"agent-image/entrypoint.nix",
+			],
 		},
 	];
 	const managerFor = (depName: string) =>
@@ -867,6 +875,183 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 	});
 });
 
+describe("tools/renovate devenv nixpkgs channel: agent base image", () => {
+	// The fourth devenv pin. Three of the four (root channel, root fork,
+	// agent-image fork) were tracked; agent-image's CHANNEL rev was governed by
+	// no manager at all, so it only advanced when someone relocked by hand. This
+	// manager + rule pair gives it the same solo-branched, self-relocking shape
+	// as its siblings.
+	//
+	// Found by the dep it stamps, never by index or a file-pattern substring:
+	// TWO managers now pattern-match agent-image/devenv.lock (this one and the
+	// fork manager), so a pattern-based finder would be order-dependent.
+	const REFRESH = "bun tools/renovate/refresh-agent-image-nixpkgs.ts";
+	const DEP = "cachix/devenv-nixpkgs-agent-image";
+	const LOCK = "agent-image/devenv.lock";
+	const GROUP = "devenv nixpkgs channel (agent-image)";
+	const manager = cfg.customManagers?.find((m) => m.depNameTemplate === DEP);
+	const rule = cfg.packageRules.find((r) => r.matchDepNames?.includes(DEP));
+
+	test("declares a git-refs regex manager scoped to the agent-image lock", () => {
+		expect(manager).toBeDefined();
+		expect(manager?.customType).toBe("regex");
+		expect(manager?.datasourceTemplate).toBe("git-refs");
+		// Same upstream channel repo as the root manager; only the depName
+		// differs, which is what keeps the two rules independently governed and
+		// in separate branches.
+		expect(manager?.packageNameTemplate).toBe(
+			"https://github.com/cachix/devenv-nixpkgs",
+		);
+		expect(manager?.currentValueTemplate).toBe("rolling");
+
+		// Pin the LITERAL first (a Renovate delimiter-semantics drift then fails
+		// as a changed literal rather than silently changing what the re-parse
+		// below tests), then re-parse it behaviourally. The escaped interior
+		// slash matches the agent-image fork manager's literal.
+		expect(manager?.managerFilePatterns).toEqual([
+			"/^agent-image\\/devenv\\.lock$/",
+		]);
+		const delimited = /^\/(.*)\/$/.exec(
+			manager?.managerFilePatterns?.[0] as string,
+		);
+		expect(delimited).not.toBeNull();
+		const re = new RegExp(delimited?.[1] as string);
+		expect(re.test(LOCK)).toBe(true);
+		// NEVER the root lock: a loose pattern would collapse the two
+		// independently-cadenced scopes into one dep carrying two conflicting
+		// digests.
+		expect(re.test("devenv.lock")).toBe(false);
+		expect(re.test(`a/${LOCK}`)).toBe(false); // anchored, no arbitrary prefix
+	});
+
+	// The matchString must recover EXACTLY ONE 40-hex rev from the REAL
+	// agent-image lock, and it must be the OUTER channel rev
+	// (nodes.nixpkgs.locked.rev) — not the inner nixpkgs-src rev the relock
+	// refreshes from it, not the devenv FORK rev the sibling manager owns, and
+	// not the `original` block (which repeats `"repo": "devenv-nixpkgs"` but is
+	// followed by `"ref"`, never `"rev"` — the whole anchor-uniqueness argument).
+	test("matchString extracts the channel rev from the real agent-image lock", () => {
+		const lockText = readFileSync(join(repoRoot, LOCK), "utf8");
+		const matchString = manager?.matchStrings?.[0];
+		expect(matchString).toBeDefined();
+		const matches = [
+			...lockText.matchAll(new RegExp(matchString as string, "g")),
+		];
+		expect(matches).toHaveLength(1);
+		const rev = matches[0]?.groups?.currentDigest;
+		expect(rev).toMatch(/^[a-f0-9]{40}$/);
+		const parsed = JSON.parse(lockText);
+		expect(rev).toBe(parsed.nodes.nixpkgs.locked.rev);
+		expect(rev).not.toBe(parsed.nodes["nixpkgs-src"].locked.rev);
+		expect(rev).not.toBe(parsed.nodes.devenv.locked.rev);
+	});
+
+	// And it must not bind the ROOT lock at all — the manager's file pattern is
+	// the only thing scoping it, so assert the two locks really do carry
+	// DIFFERENT channel revs today (RD-1: unify the source, do NOT reconcile the
+	// locks) and that this manager's dep is the agent-image one.
+	test("the two scopes' channel revs are read independently, not reconciled", () => {
+		const agent = JSON.parse(readFileSync(join(repoRoot, LOCK), "utf8"));
+		const root = JSON.parse(
+			readFileSync(join(repoRoot, "devenv.lock"), "utf8"),
+		);
+		// Both are real 40-hex channel revs…
+		expect(agent.nodes.nixpkgs.locked.rev).toMatch(/^[a-f0-9]{40}$/);
+		expect(root.nodes.nixpkgs.locked.rev).toMatch(/^[a-f0-9]{40}$/);
+		// …and nothing in the config compares them: each scope has its own
+		// manager, so a skew is legitimate rather than a drift to fix. (This
+		// test states the property; it deliberately does NOT assert inequality,
+		// which would fail the day the two happen to coincide.)
+		const channelManagers = (cfg.customManagers ?? []).filter((m) =>
+			m.matchStrings?.some((s) => s.includes("devenv-nixpkgs")),
+		);
+		expect(channelManagers).toHaveLength(2);
+		expect(
+			new Set(channelManagers.map((m) => m.managerFilePatterns?.[0])).size,
+		).toBe(2);
+	});
+
+	// Solo-branched, scheduled, cooldown-nulled — its siblings' shape. The
+	// groupName must be UNIQUE to this rule: it is what makes the branch-mode
+	// relock task safe (one branch-mode task slot per branch, so the dep must own
+	// its branch) AND what keeps the two channel pins on independent cadences.
+	test("the rule is solo-grouped, scheduled, and cooldown-exempt", () => {
+		expect(rule).toBeDefined();
+		expect(rule?.matchManagers).toContain("custom.regex");
+		expect(rule?.groupName).toBe(GROUP);
+		expect(cfg.packageRules.filter((r) => r.groupName === GROUP)).toHaveLength(
+			1,
+		);
+		expect(rule?.schedule?.length).toBeGreaterThan(0);
+		// A git-refs digest on a moving branch HEAD carries no release age, so the
+		// repo-wide strict cooldown would peg it permanently `pending` and cut
+		// zero PRs (the RIG-1220 silent-no-updates shape).
+		expect(rule?.minimumReleaseAge).toBeNull();
+	});
+
+	// Branch-mode task over EXACTLY the two files the script writes. fileFilters
+	// is an INCLUDE allowlist — Renovate commits ONLY listed files — so dropping
+	// entrypoint.nix would run the FOD refresh and silently discard it, shipping
+	// a channel bump whose outputHash never moved (`hash mismatch in
+	// fixed-output derivation` on the image build), and dropping the lock would
+	// discard the relock itself.
+	test("the postUpgradeTask is branch-mode over the lock AND the FOD file", () => {
+		const task = rule?.postUpgradeTasks;
+		expect(task?.executionMode).toBe("branch");
+		expect(task?.commands).toEqual([REFRESH]);
+		expect(task?.fileFilters).toEqual([LOCK, "agent-image/entrypoint.nix"]);
+	});
+
+	// A SEPARATE script from the root channel lockstep, deliberately: the root
+	// script's tail (biome eval, catalog pin, bun.lock, flake lockstep) has no
+	// counterpart in this scope. Assert the two rules do NOT share a command, so
+	// a future "simplification" that points this rule at the root script — which
+	// would relock the ROOT lock on an agent-image branch — fails here.
+	test("does NOT reuse the root channel refresher", () => {
+		expect(rule?.postUpgradeTasks?.commands).not.toContain(
+			"bun tools/renovate/refresh-devenv-nixpkgs.ts",
+		);
+		const declaring = cfg.packageRules.filter((r) =>
+			r.postUpgradeTasks?.commands?.includes(REFRESH),
+		);
+		expect(declaring).toHaveLength(1);
+		expect(
+			bot.allowedCommands?.filter((a) => new RegExp(a).test(REFRESH)),
+		).toEqual(["^bun tools/renovate/refresh-agent-image-nixpkgs\\.ts$"]);
+	});
+
+	// The two locks must never land in ONE branch, and this digest must never
+	// fold into the TypeScript rollup (which also matches custom.regex) — either
+	// would put two branch-mode tasks on one branch, where Renovate builds only
+	// one and the other pin ships bumped-but-unrelocked. Replay the real
+	// last-match-wins packageRule semantics.
+	test("the digest resolves to its own solo branch, not the TS rollup", () => {
+		const group = resolveGroupName({
+			manager: "custom.regex",
+			fileName: LOCK,
+			depName: DEP,
+			updateType: "digest",
+		});
+		expect(group).toBe(GROUP);
+		expect(group).not.toBe("TypeScript dependencies");
+	});
+
+	// …and it is a DIFFERENT branch from the root channel pin and from the
+	// agent-image FORK pin, the two rules it is most likely to be collapsed into.
+	test("its group differs from the root channel and agent-image fork groups", () => {
+		const groups = [
+			GROUP,
+			cfg.packageRules.find((r) =>
+				r.matchDepNames?.includes("cachix/devenv-nixpkgs"),
+			)?.groupName,
+			cfg.packageRules.find((r) =>
+				r.matchDepNames?.includes("RigelBuild/devenv-agent-image"),
+			)?.groupName,
+		];
+		expect(new Set(groups).size).toBe(3);
+	});
+});
+
 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.
@@ -1436,16 +1621,16 @@ describe("tools/renovate FOD trigger coverage (every task site, derived from FOD
 	test("the coupled (site, entry) set has its expected shape (guard is not vacuous)", () => {
 		// The guard below iterates `coupled`, so a set that emptied or thinned out
 		// would leave it passing while checking nothing. A bare `> 0` cannot see
-		// the thinning: all four pairs today bind the SAME entry
-		// (agent-image/entrypoint.nix, whose triggers are bun.lock and
-		// devenv.lock), so renaming just ONE of that entry's two triggers
-		// dissolves the coupling at three of the four sites while the fourth keeps
+		// the thinning: all six pairs today bind the SAME entry
+		// (agent-image/entrypoint.nix, whose triggers are bun.lock, devenv.lock and
+		// agent-image/devenv.lock), so renaming just ONE of that entry's triggers
+		// dissolves the coupling at some sites while the rest keep
 		// the count positive. Pinning the exact count catches a partial trigger
 		// rename, or a fileFilters edit, that dissolves any single pairing. It does
 		// NOT check WHICH sites are coupled — the per-site describes above pin
 		// that — only that the population has not shrunk or grown. A newly coupled
 		// site is a deliberate edit: update this number in the same change.
-		expect(coupled.length).toBe(4);
+		expect(coupled.length).toBe(6);
 		expect(taskSites.length).toBeGreaterThan(0);
 	});
 
@@ -1482,6 +1667,31 @@ describe("tools/renovate FOD trigger coverage (every task site, derived from FOD
 		`recomputed and then silently DROPPED, and the bump lands with ` +
 		`the stale pin exactly as if no refresh ran.`;
 
+	// A command that refreshes the FOD pin IN-PROCESS rather than by shelling
+	// FOD_COMMAND. The guard's job is to ensure a site committing a trigger
+	// recomputes the pin; a script that imports the refresher and drives the same
+	// table satisfies that as completely as the standalone command, and adding the
+	// command beside it would pay a SECOND faked-pin realise (a full FOD cache
+	// miss plus a networked bun install) to rewrite a value already correct. Each
+	// entry is listed with the call site that makes it true, so this stays a
+	// per-script statement of fact and never a blanket exemption.
+	const IN_PROCESS_REFRESHERS: Record<string, string> = {
+		// refresh-agent-image-nixpkgs.ts: relocks the agent-image channel, then
+		// awaits the FOD refresh over that scope's entries.
+		"bun tools/renovate/refresh-agent-image-nixpkgs.ts": "refreshEntry",
+	};
+
+	test("every declared in-process refresher really drives the FOD table", async () => {
+		// Guards the exemption itself: the claim above is only sound while each
+		// listed script genuinely calls the refresher, so read the source and check.
+		for (const [command, symbol] of Object.entries(IN_PROCESS_REFRESHERS)) {
+			const script = command.replace(/^bun /, "");
+			const source = await Bun.file(join(repoRoot, script)).text();
+			const calls = new RegExp(`\\b(await\\s+)?${symbol}\\s*\\(`).test(source);
+			expect(calls, `${script} must call ${symbol}()`).toBe(true);
+		}
+	});
+
 	// Every way a single (site, entry) pairing can fail the coupling: the refresh
 	// missing, the refresh not last, or a file the pin needs missing from the
 	// include allowlist.
@@ -1496,12 +1706,18 @@ describe("tools/renovate FOD trigger coverage (every task site, derived from FOD
 		const context =
 			`${label} declares FOD trigger(s) ${named.join(", ")} for the pin in ` +
 			`${entry.file}`;
-		const fodIndex = commands.indexOf(FOD_COMMAND);
 		const found: string[] = [];
-		if (fodIndex === -1) {
+		// A site refreshes the pin either by shelling FOD_COMMAND — which must run
+		// LAST, after whatever wrote the trigger — or by running a script that
+		// drives the same table in-process, which orders the two itself.
+		const inProcess = commands.filter((c) => c in IN_PROCESS_REFRESHERS);
+		const fodIndex = commands.indexOf(FOD_COMMAND);
+		if (fodIndex !== -1) {
+			if (fodIndex !== commands.length - 1) {
+				found.push(refreshNotLast(context, fodIndex + 1, commands.length));
+			}
+		} else if (inProcess.length === 0) {
 			found.push(missingRefresh(context));
-		} else if (fodIndex !== commands.length - 1) {
-			found.push(refreshNotLast(context, fodIndex + 1, commands.length));
 		}
 		for (const required of [entry.file, ...(entry.mirrorFiles ?? [])]) {
 			if (!covers(filters, required)) {
diff --git a/tools/renovate/refresh-agent-image-nixpkgs.core.ts b/tools/renovate/refresh-agent-image-nixpkgs.core.ts
new file mode 100644
index 00000000..7f13e637
--- /dev/null
+++ b/tools/renovate/refresh-agent-image-nixpkgs.core.ts
@@ -0,0 +1,81 @@
+// Pure decision core for refresh-agent-image-nixpkgs.ts.
+//
+// Split out from the entry point so the load-bearing read — which nixpkgs
+// channel rev the agent base image's devenv lock currently pins — is
+// unit-testable without a devenv runner, a network, or a git tree. The entry
+// point owns the shell-outs (the base diff, the `nix run <fork flakeref> --
+// update nixpkgs` relock, the FOD refresh); this file owns the parse. NO
+// shell-outs, NO fs beyond text passed in.
+//
+// Deliberately its own module rather than a reuse of
+// refresh-devenv-nixpkgs.core.ts's `channelNixpkgsRev`: that module's throws are
+// named for the ROOT channel task and its scope's coupling story (biome catalog,
+// bun.lock, flake.nix), none of which exists here. A fail-loud script's value is
+// its diagnosis, so each scope names itself — the same per-script-core
+// convention refresh-devenv-lock.core.ts and refresh-go-overlay.core.ts follow.
+
+/**
+ * The agent base image's devenv lock, repo-root-relative: the file the
+ * customManager rewrites and this task's self-gate trigger. INDEPENDENT of the
+ * root `devenv.lock` — RD-1 unifies the devenv SOURCE across the two scopes but
+ * deliberately does NOT reconcile the two locks, so the two nixpkgs channel
+ * revs are legitimately skewed and are never compared here.
+ */
+export const AGENT_IMAGE_LOCK = "agent-image/devenv.lock";
+
+/**
+ * The directory to run the relock from. devenv resolves devenv.yaml/devenv.lock
+ * relative to its cwd, so the cwd IS the scope selector — relocking from the
+ * repo root would rewrite the ROOT lock, which this rule's `fileFilters` cannot
+ * commit, leaving the agent-image rev bump shipped unrelocked.
+ */
+export const AGENT_IMAGE_DIR = "agent-image";
+
+/**
+ * The devenv input name this task re-resolves — `inputs.nixpkgs.url =
+ * github:cachix/devenv-nixpkgs/rolling` in agent-image/devenv.yaml. Naming the
+ * single input (rather than a bare `devenv update`) keeps the relock off every
+ * other input in the lock, so the PR's diff stays the channel advance the branch
+ * is about.
+ */
+export const NIXPKGS_INPUT = "nixpkgs";
+
+/**
+ * The devenv-nixpkgs CHANNEL rev the agent base image resolved, read from the
+ * lock's outer `nixpkgs` node (`nodes.nixpkgs.locked.rev`) — the SAME field the
+ * customManager's matchString surfaces as a git-refs digest. DISTINCT from the
+ * transitive `nixpkgs-src` node (upstream NixOS/nixpkgs), which the relock
+ * refreshes from this outer rev and which this function must never return.
+ *
+ * Read before and after the relock so the advance is observable in the task
+ * log, and so a lock-shape change fails the task loudly rather than reporting a
+ * bogus rev. Parsed as JSON (devenv.lock is JSON), narrowing with `in`/`typeof`
+ * at each level so every access is actually checked — the lock is
+ * external-boundary data and no schema validator is in the repo.
+ */
+export function agentImageNixpkgsRev(devenvLockText: string): string {
+	let lock: unknown;
+	try {
+		lock = JSON.parse(devenvLockText);
+	} catch (error) {
+		throw new Error(
+			`refresh-agent-image-nixpkgs: ${AGENT_IMAGE_LOCK} is not valid JSON: ${String(error)}`,
+		);
+	}
+	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.nixpkgs;
+		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-agent-image-nixpkgs: could not read a 40-hex nixpkgs channel rev from ` +
+				`${AGENT_IMAGE_LOCK} (nodes.nixpkgs.locked.rev) — devenv lock shape may have changed.`,
+		);
+	}
+	return rev;
+}
diff --git a/tools/renovate/refresh-agent-image-nixpkgs.test.ts b/tools/renovate/refresh-agent-image-nixpkgs.test.ts
new file mode 100644
index 00000000..12e5e996
--- /dev/null
+++ b/tools/renovate/refresh-agent-image-nixpkgs.test.ts
@@ -0,0 +1,381 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { chmod, mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { $ } from "bun";
+import {
+	AGENT_IMAGE_DIR,
+	AGENT_IMAGE_LOCK,
+	agentImageNixpkgsRev,
+	NIXPKGS_INPUT,
+} from "./refresh-agent-image-nixpkgs.core.ts";
+import { FOD_ENTRIES } from "./refresh-fod-hashes.ts";
+
+// Unit tests for the pure core of refresh-agent-image-nixpkgs.ts: reading the
+// devenv-nixpkgs CHANNEL rev out of the agent base image's devenv lock, and the
+// scope geometry the relock depends on. No devenv / network / git — that
+// shell-out lives in the entry point and runs for real on the PR's own branch.
+// These assert what a wrong line would silently corrupt: relocking the wrong
+// scope (whose write the rule's two-file fileFilters then discards), or reading
+// the fork / inner-nixpkgs rev instead of the channel rev.
+
+const repoRoot = join(import.meta.dir, "..", "..");
+
+// A lock with the same node AMBIGUITY the real one has: an outer `nixpkgs`
+// channel node, its transitive `nixpkgs-src` (upstream NixOS/nixpkgs), and the
+// `devenv` fork node — so a reader that grabbed the wrong node passes nothing.
+function agentImageLock(
+	channelRev: string,
+	innerRev: string,
+	forkRev: string,
+): string {
+	return `${JSON.stringify(
+		{
+			nodes: {
+				devenv: {
+					locked: {
+						lastModified: 3,
+						narHash: "sha256-FORK",
+						owner: "RigelBuild",
+						repo: "devenv",
+						rev: forkRev,
+						type: "github",
+					},
+					original: { owner: "RigelBuild", repo: "devenv", type: "github" },
+				},
+				nixpkgs: {
+					inputs: { "nixpkgs-src": "nixpkgs-src" },
+					locked: {
+						lastModified: 1,
+						narHash: "sha256-CHANNEL",
+						owner: "cachix",
+						repo: "devenv-nixpkgs",
+						rev: channelRev,
+						type: "github",
+					},
+					original: {
+						owner: "cachix",
+						ref: "rolling",
+						repo: "devenv-nixpkgs",
+						type: "github",
+					},
+				},
+				"nixpkgs-src": {
+					flake: false,
+					locked: {
+						lastModified: 2,
+						narHash: "sha256-INNER",
+						owner: "NixOS",
+						repo: "nixpkgs",
+						rev: innerRev,
+						type: "github",
+					},
+				},
+				root: { inputs: { devenv: "devenv", nixpkgs: "nixpkgs" } },
+			},
+			root: "root",
+			version: 7,
+		},
+		null,
+		2,
+	)}\n`;
+}
+
+const CHANNEL_REV = "1111111111111111111111111111111111111111";
+const INNER_REV = "2222222222222222222222222222222222222222";
+const FORK_REV = "3333333333333333333333333333333333333333";
+
+describe("agent-image scope geometry", () => {
+	// The cwd IS the scope selector — devenv resolves devenv.yaml/devenv.lock
+	// relative to it — so the relock directory must be the directory the lock
+	// lives in. A mismatch would relock the ROOT lock while this rule's
+	// fileFilters names the agent-image one, so Renovate would commit nothing
+	// and the rev bump would ship unrelocked.
+	test("the relock cwd is the directory holding the lock", () => {
+		expect(AGENT_IMAGE_LOCK.startsWith(`${AGENT_IMAGE_DIR}/`)).toBe(true);
+		expect(AGENT_IMAGE_LOCK.slice(AGENT_IMAGE_DIR.length + 1)).toBe(
+			"devenv.lock",
+		);
+	});
+
+	// The single named input, not a bare `devenv update`: relocking every input
+	// would bloat the PR's diff past the channel advance the branch is about.
+	test("the relocked input is the channel input alone", () => {
+		expect(NIXPKGS_INPUT).toBe("nixpkgs");
+	});
+
+	// Ground truth: the lock the config's manager governs must exist at this
+	// path and actually pin a 40-hex channel rev.
+	test("the real lock exists and pins a 40-hex channel rev", () => {
+		const text = readFileSync(join(repoRoot, AGENT_IMAGE_LOCK), "utf8");
+		expect(agentImageNixpkgsRev(text)).toMatch(/^[a-f0-9]{40}$/);
+	});
+
+	// The rev read here is the one the FOD refresh hangs off: the channel
+	// resolves the bun entrypoint.nix's builder uses, so the FOD table must gate
+	// that entry on this lock. If the table and this task disagree, the entry
+	// point throws rather than shipping a possibly-stale outputHash — assert the
+	// agreement here too so the drift fails in a unit test, not on a branch.
+	test("the FOD entry for entrypoint.nix is gated on this lock", () => {
+		const entry = FOD_ENTRIES.find(
+			(e) => e.file === "agent-image/entrypoint.nix",
+		);
+		expect(entry).toBeDefined();
+		expect(entry?.triggers).toContain(AGENT_IMAGE_LOCK);
+		// And still on bun.lock — the manifest trigger that already existed; this
+		// task ADDS a cause, it does not replace one.
+		expect(entry?.triggers).toContain("bun.lock");
+	});
+});
+
+describe("agentImageNixpkgsRev", () => {
+	test("reads the outer channel rev", () => {
+		expect(
+			agentImageNixpkgsRev(agentImageLock(CHANNEL_REV, INNER_REV, FORK_REV)),
+		).toBe(CHANNEL_REV);
+	});
+
+	// The three-node ambiguity is the whole risk: `nixpkgs-src` is the upstream
+	// nixpkgs the channel resolves TO (refreshed from the outer rev by the
+	// relock, never tracked), and `devenv` is the fork pin a sibling manager
+	// owns. Reading either would log a bogus advance and, worse, make the
+	// byte-identical guard reason about the wrong field.
+	test("reads neither the inner nixpkgs-src rev nor the devenv fork rev", () => {
+		const rev = agentImageNixpkgsRev(
+			agentImageLock(CHANNEL_REV, INNER_REV, FORK_REV),
+		);
+		expect(rev).not.toBe(INNER_REV);
+		expect(rev).not.toBe(FORK_REV);
+	});
+
+	// Fail loud on a lock-shape change rather than silently reading wrong: the
+	// lock is external-boundary data, and a task that cannot name the rev it is
+	// moving must not proceed to a relock.
+	test("throws when the nixpkgs node is absent", () => {
+		const noNode = JSON.stringify({ nodes: { root: {} }, root: "root" });
+		expect(() => agentImageNixpkgsRev(noNode)).toThrow(
+			/could not read a 40-hex nixpkgs channel rev/,
+		);
+	});
+
+	test("throws when the rev is not 40-hex", () => {
+		expect(() =>
+			agentImageNixpkgsRev(agentImageLock("abc123", INNER_REV, FORK_REV)),
+		).toThrow(/could not read a 40-hex nixpkgs channel rev/);
+	});
+
+	test("throws with a named diagnosis on invalid JSON", () => {
+		expect(() => agentImageNixpkgsRev("not json")).toThrow(/is not valid JSON/);
+	});
+
+	// The error must name THIS task, not a sibling: a fail-loud script's value is
+	// its diagnosis, and a message reading `refresh-devenv-nixpkgs` on an
+	// agent-image branch sends the reader to the wrong scope.
+	test("its diagnoses name this task and this lock", () => {
+		expect(() => agentImageNixpkgsRev("not json")).toThrow(
+			/refresh-agent-image-nixpkgs/,
+		);
+		expect(() => agentImageNixpkgsRev("not json")).toThrow(
+			/agent-image\/devenv\.lock/,
+		);
+	});
+});
+
+// ── Entry-point tests: the SHIPPED script, end to end, offline ──────────────
+//
+// Everything above is pure. The branches that decide whether a channel bump
+// ships CORRECTLY live in the entry point: the self-gate against the base ref,
+// the base-ref resolution ladder, the byte-identical guard, and the argv/cwd of
+// the relock. Those are the lines a plausible bug hides in — an inverted
+// comparison, a wrong cwd, a swallowed failure — so they run here against a
+// throwaway git repo with a stub `nix` first on PATH. No network, no devenv,
+// no real nix; git is the real binary.
+
+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 SCRIPT_REL = "tools/renovate/refresh-agent-image-nixpkgs.ts";
+const RELOCKED_CHANNEL_REV = "4444444444444444444444444444444444444444";
+const STUB_SRI = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";
+
+// The stub logs its cwd and argv, then writes a RELOCKED lock only when the
+// post-`--` args are exactly `update nixpkgs`. So a regression that dropped the
+// separator, or named another input, writes nothing and fails through BEHAVIOUR
+// (the byte-identical guard fires) rather than only through an argv assertion.
+const STUB_NIX = `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = "build" ]; then
+  echo "error: hash mismatch in fixed-output derivation '/nix/store/x-compass-agent-node-modules-0.1.0.drv':" >&2
+  echo "         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" >&2
+  echo "            got:    ${STUB_SRI}" >&2
+  exit 1
+fi
+if [ "\${1:-}" = "run" ]; then
+  echo "$PWD" >> "$REPO_ROOT/.update-cwds"
+  echo "$@" >> "$REPO_ROOT/.update-args"
+  if [ -f "$REPO_ROOT/.force-noop" ]; then exit 0; fi
+  if [ -f "$REPO_ROOT/.force-fail" ]; then
+    echo "stub nix: forced relock failure" >&2
+    exit 1
+  fi
+  shift 2
+  if [ "\${1:-}" != "--" ]; then exit 0; fi
+  shift
+  if [ "\${1:-}" != "update" ] || [ "\${2:-}" != "nixpkgs" ]; then exit 0; fi
+  cat > devenv.lock <<'LOCK'
+${agentImageLock(RELOCKED_CHANNEL_REV, INNER_REV, FORK_REV)}
+LOCK
+fi
+exit 0
+`;
+
+// A stub `bun` is NOT used: the real bun runs the shipped script. But the FOD
+// refresh the script drives at the end shells `nix build`, which the stub above
+// answers with exit 0 and no `got:` line — so the FOD leg is neutralised by
+// pointing the table's triggers at files this fixture never changes. What these
+// tests cover is the relock half; the FOD half has its own suite.
+async function buildEntryRepo(): Promise<string> {
+	const repo = await mkdtemp(join(tmpdir(), "rig3365-"));
+	await mkdir(join(repo, "tools", "renovate"), { recursive: true });
+	await mkdir(join(repo, "tools", "toolchain", "devenv-cli"), {
+		recursive: true,
+	});
+	await mkdir(join(repo, AGENT_IMAGE_DIR), { recursive: true });
+	await mkdir(join(repo, "stubbin"), { recursive: true });
+
+	// Ship the REAL script and every module it imports, so the shipped file runs
+	// unmodified.
+	for (const rel of [
+		SCRIPT_REL,
+		"tools/renovate/refresh-agent-image-nixpkgs.core.ts",
+		"tools/renovate/refresh-fod-hashes.ts",
+		"tools/toolchain/devenv-cli/core.ts",
+	]) {
+		await Bun.write(
+			join(repo, rel),
+			await readFile(join(repoRoot, rel), "utf8"),
+		);
+	}
+
+	await Bun.write(
+		join(repo, AGENT_IMAGE_LOCK),
+		agentImageLock(CHANNEL_REV, INNER_REV, FORK_REV),
+	);
+
+	// The FOD leg runs after the relock, so the pin file and both vehicles have
+	// to exist. The stub answers `nix build` by printing a got: line for the
+	// fragment, which is what recompute parses the real value out of.
+	await Bun.write(
+		join(repo, "agent-image", "entrypoint.nix"),
+		`{ pkgs, lib }:\n  outputHash = "${STUB_SRI}";\n`,
+	);
+	// The single realise vehicle this scope's refresh drives.
+	await mkdir(join(repo, "guest-image"), { recursive: true });
+	await Bun.write(join(repo, "guest-image", "default.nix"), "{ }\n");
+	await Bun.write(join(repo, "stubbin", "nix"), STUB_NIX);
+	await chmod(join(repo, "stubbin", "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();
+	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;
+}
+
+// The rev-only rewrite the customManager performs: it moves the channel rev and
+// NOTHING else, so narHash still describes the base rev — the inconsistent state
+// the relock exists to repair.
+async function applyChannelBump(repo: string, rev: string) {
+	const bumped = agentImageLock(rev, INNER_REV, FORK_REV);
+	await Bun.write(join(repo, AGENT_IMAGE_LOCK), bumped);
+}
+
+async function runScript(repo: string, baseBranch = "main") {
+	return await $`bun ${SCRIPT_REL}`
+		.cwd(repo)
+		.env({
+			...HERMETIC_ENV,
+			PATH: `${join(repo, "stubbin")}:${process.env.PATH}`,
+			RENOVATE_BASE_BRANCH: baseBranch,
+			REPO_ROOT: repo,
+		})
+		.quiet()
+		.nothrow();
+}
+
+describe("tools/renovate/refresh-agent-image-nixpkgs.ts entry point", () => {
+	let repo: string;
+	beforeEach(async () => {
+		repo = await buildEntryRepo();
+	});
+	afterEach(async () => {
+		await rm(repo, { recursive: true, force: true });
+	});
+
+	// The self-gate: this rule's branch is the only one that should relock, so a
+	// branch whose lock matches base must no-op WITHOUT invoking nix. Without it,
+	// every unrelated branch would pay a relock and could commit a drive-by pin.
+	test("no-ops without invoking nix when the lock matches base", async () => {
+		const res = await runScript(repo);
+		expect(res.exitCode).toBe(0);
+		expect(existsSync(join(repo, ".update-args"))).toBe(false);
+		expect(res.stdout.toString() + res.stderr.toString()).toContain(
+			"nothing to do",
+		);
+	});
+
+	// A relock that leaves the lock byte-identical means the rev moved but the
+	// narHash never re-resolved: shipping that is the silent-drift failure, so it
+	// must be LOUD.
+	test("fails when the relock leaves the lock byte-identical", async () => {
+		await applyChannelBump(repo, RELOCKED_CHANNEL_REV);
+		await Bun.write(join(repo, ".force-noop"), "");
+		const res = await runScript(repo);
+		expect(res.exitCode).not.toBe(0);
+	});
+
+	// A failing relock must not exit 0 — Renovate would commit the rev-only bump
+	// and the branch would carry a lock describing the wrong rev.
+	test("fails when the relock command itself fails", async () => {
+		await applyChannelBump(repo, RELOCKED_CHANNEL_REV);
+		await Bun.write(join(repo, ".force-fail"), "");
+		const res = await runScript(repo);
+		expect(res.exitCode).not.toBe(0);
+	});
+
+	// An unresolvable base ref must not read as "nothing changed" — that would
+	// turn a broken environment into a silent skip.
+	test("fails with a named error when the base ref does not resolve", async () => {
+		const res = await runScript(repo, "no-such-branch");
+		expect(res.exitCode).not.toBe(0);
+		expect(res.stderr.toString() + res.stdout.toString()).toMatch(
+			/no-such-branch/,
+		);
+	});
+
+	// The relock must run IN agent-image/ (cwd is devenv's scope selector) and
+	// name this scope's own fork rev — relocking from root's devenv would write
+	// this lock with the wrong tool.
+	test("relocks in the agent-image dir via this scope's own fork rev", async () => {
+		await applyChannelBump(repo, RELOCKED_CHANNEL_REV);
+		const res = await runScript(repo);
+		expect(res.exitCode).toBe(0);
+		const cwds = (await readFile(join(repo, ".update-cwds"), "utf8")).trim();
+		expect(cwds.endsWith(`/${AGENT_IMAGE_DIR}`)).toBe(true);
+		const args = (await readFile(join(repo, ".update-args"), "utf8")).trim();
+		expect(args).toContain(`-- update ${NIXPKGS_INPUT}`);
+		expect(args).toContain(FORK_REV);
+	});
+});
diff --git a/tools/renovate/refresh-agent-image-nixpkgs.ts b/tools/renovate/refresh-agent-image-nixpkgs.ts
new file mode 100644
index 00000000..9cbdddd9
--- /dev/null
+++ b/tools/renovate/refresh-agent-image-nixpkgs.ts
@@ -0,0 +1,278 @@
+// Renovate postUpgradeTask: relock the agent base image's devenv lock at a new
+// devenv-nixpkgs CHANNEL rev, then refresh the FOD hash that relock can move.
+//
+// Context. Compass carries TWO independent devenv scopes, and each pins BOTH a
+// `cachix/devenv-nixpkgs` channel rev and a `RigelBuild/devenv` fork rev:
+// the root dev shell (devenv.yaml/devenv.lock) and the agent base image
+// (agent-image/devenv.yaml + agent-image/devenv.lock). Three of those four pins
+// were tracked; the agent-image CHANNEL rev was not, so it only ever moved when
+// someone relocked by hand. This task is the fourth pin's relock, riding the
+// customManager + packageRule pair that surfaces it as a git-refs digest
+// (config.json5). RD-1 unifies the devenv SOURCE but deliberately does NOT
+// reconcile the two locks, so the two channel revs are legitimately skewed and
+// are never compared: each is governed on its OWN cadence, one manager + one
+// rule + one branch per pin.
+//
+// ── WHY THIS IS A SEPARATE SCRIPT FROM refresh-devenv-nixpkgs.ts ──
+// That script relocks the ROOT channel and then does root-only lockstep work,
+// none of whose couplings exist in this scope:
+//
+//   * It evals `biome` from the resolved raw nixpkgs and rewrites the biome
+//     CATALOG pin in package.json, then re-resolves bun.lock. That exists
+//     because the ROOT dev shell BAKES biome from the channel (devenv.nix) and
+//     the parity story requires baked==catalog. agent-image bakes nothing into
+//     a shell: `agent-image/devenv.nix` is `packages = [ ]` — that devenv exists
+//     only to express the container — so there is no baked tool to mirror and no
+//     manifest to rewrite.
+//   * It locksteps the repo-root `flake.nix` (`inputs.nixpkgs.url` hard-codes
+//     the channel rev) and re-locks flake.lock, because the flake-parity gate
+//     reds CI on the skew. There is NO `agent-image/flake.nix` — the image is
+//     not expressed as a flake — so there is nothing to lockstep.
+//
+// So this task does the relock and NOTHING of that: no biome eval, no catalog
+// pin, no bun.lock, no flake work. Widening the root script to take a scope
+// would put the whole root-only tail behind a conditional on a path two live
+// Renovate rules already depend on, for no shared behaviour beyond the relock
+// itself.
+//
+// ── WHAT THIS REV GOVERNS, AND THE HAZARD IT CARRIES ──
+// The agent-image channel rev resolves the image's toolchain closure:
+// `agent-image/toolchain.nix` overlays the repo's own vendored bun, but
+// `pkgs.cacert`, `pkgs.devenv`, and `getent` come straight from this pin — and
+// `agent-image/entrypoint.nix`'s FOD builder takes `nativeBuildInputs =
+// [ pkgs.bun ]` from it too.
+//
+// That last one is why this task refreshes the FOD hash. entrypoint.nix carries
+// a SINGLE `outputHash` literal over the installed `node_modules` tree, and it
+// is realised through TWO nixpkgs revs: `agent-image/devenv.nix` imports
+// entrypoint.nix with AGENT-IMAGE's `pkgs`, while `guest-image/default.nix`
+// imports the SAME file with ROOT's `pkgs` (a divergence that file documents as
+// deliberate). One hash for two builders is safe only while both revs resolve to
+// a bun producing a byte-identical install tree.
+//
+// The refresh has a REACH LIMIT worth stating plainly, because it is not what
+// the coupling suggests. refresh-fod-hashes.ts realises exactly one vehicle,
+// `guest-image/default.nix`, and that vehicle takes ROOT's `pkgs`. Nothing in
+// the repo builds `agent-image/devenv.nix`. So on a branch that moves ONLY the
+// agent-image channel, the recomputed SRI is derived through root's bun and
+// equals the committed value: the step is a correct, cheap no-op rewrite rather
+// than a verification of this scope's builder. It is wired anyway so the pin is
+// recomputed whenever the shared hash's inputs move for any reason, and so the
+// coupling is declared where a reader looks for it. The consequence to keep in
+// view: if the two channel revs diverge onto bun versions with different install
+// trees, this hash stays right for guest-image and is silently wrong for the
+// agent image, and that break surfaces on the agent-image OCI build.
+//
+// Steps:
+//   1. Self-gate — exit 0 unless agent-image/devenv.lock differs from the base
+//      branch, so it's a cheap no-op on every unrelated Renovate branch (mirrors
+//      refresh-devenv-lock.ts's gate).
+//   2. Relock — `nix run <this lock's own fork flakeref> -- update nixpkgs`, run
+//      in agent-image/, re-resolves the channel input and rewrites the whole
+//      lock (narHash + lastModified + the transitive nixpkgs-src node), not just
+//      the rev the regex bumped. Networked, but light: it re-locks inputs, it
+//      does NOT build the image.
+//   3. FOD refresh — recompute agent-image/entrypoint.nix's `outputHash` through
+//      refresh-fod-hashes.ts's own machinery (its exported table entry +
+//      refreshEntry), so there is ONE realise-and-parse implementation rather
+//      than a second copy that drifts from its got:-attribution and
+//      restore-on-failure discipline.
+//
+// Invoked by the agent-image channel packageRule's postUpgradeTasks
+// (config.json5) as `bun tools/renovate/refresh-agent-image-nixpkgs.ts`,
+// allowlisted in bot-config.json5. Requires `nix` + `bun` + network on the
+// runner PATH, and a writable HOME (bot-config `customEnvVariables.HOME`, which
+// devenv needs for its state dir). It needs NO ambient/PATH `devenv`: the task
+// SELF-PROVISIONS the scope-correct devenv CLI by `nix run`-ing the fork
+// flakeref read out of the very lock it is about to relock, so this lock is
+// written by the devenv version IT pins. An ambient devenv would relock
+// agent-image under the ROOT lock's devenv version (the two fork revs differ by
+// design under RD-1). That mirrors refresh-devenv-lock.ts and every other
+// agent-image devenv site in the tree.
+//
+// That `nix run` also depends on the runner's nix.conf naming the devenv +
+// cachix SUBSTITUTERS and their trusted public keys — the fork's `#devenv`
+// closure is not on cache.nixos.org and nix ignores the fork flake's own
+// `nixConfig.extra-substituters` non-interactively, so without those caches the
+// realise cold-compiles the Nix fork + full closure from source and can exhaust
+// the runner. They are provided by .github/workflows/renovate.yml's
+// `extra_nix_config` block, NOT by anything in this file; config.test.ts asserts
+// that block still names both caches + keys.
+//
+// Exit codes:
+//   0 - the lock was relocked and the FOD hash refreshed (or a no-op branch: the
+//       lock does not differ from base).
+//   1 - a step failed (the relock itself, a lock-shape change, a relock that
+//       wrote nothing, an unresolvable base ref, or the FOD realise).
+//
+// What a non-zero exit actually BUYS — do NOT overclaim it. It does NOT abort
+// the Renovate branch: the failure is caught in Renovate's post-upgrade command
+// runner, pushed onto `artifactErrors`, and execution continues, so Renovate
+// commits the regex-bumped lock regardless. Nor could this script repair the
+// tree instead — Renovate's `prepareCommit` resets hard and re-writes the files
+// from its in-memory `updatedPackageFiles`, which is where the regex rev-bump
+// lives. What the non-zero exit DOES buy is a red `renovate/artifacts` commit
+// status plus the PR's mandatory human review (compass configures NO automerge).
+// The full source-verified argument is in refresh-devenv-lock.ts's header.
+
+import { readFileSync } from "node:fs";
+import { $ } from "bun";
+import { devenvSource, flakeref } from "../toolchain/devenv-cli/core.ts";
+import {
+	AGENT_IMAGE_DIR,
+	AGENT_IMAGE_LOCK,
+	agentImageNixpkgsRev,
+	NIXPKGS_INPUT,
+} from "./refresh-agent-image-nixpkgs.core.ts";
+import { FOD_ENTRIES, refreshEntry } from "./refresh-fod-hashes.ts";
+
+// The FOD whose `outputHash` this scope's bun realises. Resolved from
+// refresh-fod-hashes.ts's SHIPPED table (by the file it pins) rather than
+// restated here, so a table edit that moves or renames the entry fails LOUD at
+// this lookup instead of silently skipping the refresh — the half-refreshed PR
+// this step exists to prevent.
+const ENTRYPOINT_NIX = "agent-image/entrypoint.nix";
+function agentImageFodEntry() {
+	const entry = FOD_ENTRIES.find((e) => e.file === ENTRYPOINT_NIX);
+	if (!entry) {
+		throw new Error(
+			`refresh-agent-image-nixpkgs: no FOD_ENTRIES entry pins ${ENTRYPOINT_NIX} — ` +
+				"refresh-fod-hashes.ts's table moved, so this relock cannot refresh the outputHash " +
+				"its new bun may have invalidated. Refusing to ship a possibly-stale FOD pin.",
+		);
+	}
+	// The entry must ALSO be gated on this lock, or a real Renovate run of
+	// refresh-fod-hashes.ts on this branch would no-op while we refresh here —
+	// two sites disagreeing about what invalidates the pin.
+	if (!entry.triggers.includes(AGENT_IMAGE_LOCK)) {
+		throw new Error(
+			`refresh-agent-image-nixpkgs: the ${ENTRYPOINT_NIX} FOD entry does not list ` +
+				`${AGENT_IMAGE_LOCK} among its triggers, so refresh-fod-hashes.ts no longer agrees ` +
+				"that an agent-image channel relock can move that outputHash. Reconcile the table " +
+				"with this task before shipping.",
+		);
+	}
+	return entry;
+}
+
+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 the agent-image lock changing vs the base branch. ──
+	// `RENOVATE_BASE_BRANCH` is a LOCAL/test override ONLY — Renovate does not
+	// set it (and could not hand it to a child process through the
+	// postUpgradeTask env allowlist anyway); in production this resolves to
+	// `main`. The read is kept identical to the sibling refresh tasks so they
+	// share one convention.
+	const baseBranch = process.env.RENOVATE_BASE_BRANCH || "main";
+	// Prefer the remote-tracking ref (matches the sibling refresh tasks); fall
+	// back to the bare branch name when origin/<base> is absent (a local run).
+	const resolves = async (ref: string): Promise<boolean> =>
+		(await $`git rev-parse --verify -q ${ref}`.nothrow().quiet()).exitCode ===
+		0;
+	const remoteRef = `origin/${baseBranch}`;
+	let baseRef: string;
+	if (await resolves(remoteRef)) {
+		baseRef = remoteRef;
+	} else if (await resolves(baseBranch)) {
+		baseRef = baseBranch;
+	} else {
+		// Fail LOUD with a named diagnosis rather than letting the `git diff`
+		// below surface a raw git error: an unresolvable base means the changed-set
+		// is UNKNOWN, which must never be read as "the lock did not change" and
+		// skipped green.
+		throw new Error(
+			`refresh-agent-image-nixpkgs: base ref does not resolve — neither \`${remoteRef}\` nor ` +
+				`\`${baseBranch}\` names a commit in this repo, so whether ${AGENT_IMAGE_LOCK} changed ` +
+				"cannot be computed. Refusing to guess (an unresolvable base must not read as " +
+				"'nothing changed').",
+		);
+	}
+	const lockUnchanged =
+		(
+			await $`git diff --quiet ${baseRef} -- ${AGENT_IMAGE_LOCK}`
+				.nothrow()
+				.quiet()
+		).exitCode === 0;
+	if (lockUnchanged) {
+		console.log(
+			`refresh-agent-image-nixpkgs: ${AGENT_IMAGE_LOCK} unchanged vs ${baseRef}; nothing to do.`,
+		);
+		return 0;
+	}
+
+	// Resolve the FOD entry BEFORE the relock: a table drift must fail the task
+	// without having networked or rewritten the lock, so the branch is left in
+	// the state Renovate handed it rather than half-processed.
+	const fodEntry = agentImageFodEntry();
+
+	// ── Step 2: relock the channel input in the agent-image scope. ──
+	// The regex update moved only the rev string, leaving the lock's narHash /
+	// lastModified (and the transitive nixpkgs-src node) describing the OLD rev.
+	// `devenv update nixpkgs`, run in agent-image/, re-resolves the input and
+	// rewrites the whole lock consistently.
+	const before = readFileSync(AGENT_IMAGE_LOCK, "utf8");
+	// Provision the SCOPE-CORRECT devenv CLI from this lock's OWN content:
+	// `before` is what Renovate wrote to disk before this task ran, so the lock
+	// gets written by the very devenv version it pins. Mirrors ci.yml's
+	// `nix run "$src" -- <subcommand>` idiom.
+	const src = flakeref(devenvSource(before));
+	// Read the pre-relock rev BEFORE the log, so a malformed pre-relock lock
+	// throws with a clean diagnosis rather than mid-log-line.
+	const beforeRev = agentImageNixpkgsRev(before);
+	console.log(
+		`refresh-agent-image-nixpkgs: ${AGENT_IMAGE_LOCK} changed vs ${baseRef}; relocking the ` +
+			`'${NIXPKGS_INPUT}' input in ${AGENT_IMAGE_DIR}/ via ${src} (was ${beforeRev}) ...`,
+	);
+	await $`nix run ${src} -- update ${NIXPKGS_INPUT}`.cwd(AGENT_IMAGE_DIR);
+
+	const after = readFileSync(AGENT_IMAGE_LOCK, "utf8");
+	// A relock that wrote NOTHING is the silent half-relock this task exists to
+	// surface: the rev the regex bumped would still sit beside the base lock's
+	// narHash. Any real re-resolution rewrites narHash + lastModified, so
+	// byte-identical content means the relock did not actually run.
+	if (after === before) {
+		throw new Error(
+			`refresh-agent-image-nixpkgs: \`devenv update ${NIXPKGS_INPUT}\` left ${AGENT_IMAGE_LOCK} ` +
+				"byte-identical — the regex-bumped rev still sits beside the base lock's narHash. " +
+				"Exiting non-zero to red the `renovate/artifacts` status; note that Renovate still " +
+				"commits the regex bump (a postUpgradeTask exit does not abort the branch), so the " +
+				"human review gate is what keeps this half-relock from merging.",
+		);
+	}
+	// Shape guard: the relocked file must still pin a 40-hex channel rev (throws
+	// otherwise).
+	console.log(
+		`refresh-agent-image-nixpkgs: ${AGENT_IMAGE_LOCK} relocked — '${NIXPKGS_INPUT}' now at ${agentImageNixpkgsRev(after)}.`,
+	);
+
+	// ── Step 3: recompute the shared FOD hash. ──
+	// entrypoint.nix's `outputHash` content-addresses the installed node_modules
+	// tree, and a stale value fails the image build with `hash mismatch in
+	// fixed-output derivation`. This realises the build vehicle against a faked
+	// pin and writes back the SRI nix reports — refresh-fod-hashes.ts's own
+	// machinery, unchanged, so got:-attribution and restore-on-failure are shared
+	// rather than re-implemented. It fails loud if the build reports no `got:`.
+	//
+	// Expect a no-op on an agent-image-channel-only branch: the vehicle is
+	// guest-image/default.nix, which resolves through ROOT's pkgs, so it cannot
+	// see this scope's bun move (the header's REACH LIMIT). Recomputing anyway
+	// keeps the pin correct whenever the shared hash's inputs do move, and costs
+	// one realise.
+	console.log(
+		`refresh-agent-image-nixpkgs: recomputing the ${fodEntry.file} outputHash (vehicle resolves through root's pkgs; a no-op unless the shared inputs moved) ...`,
+	);
+	await refreshEntry(fodEntry);
+
+	console.log("refresh-agent-image-nixpkgs: done.");
+	return 0;
+}
+
+if (import.meta.main) {
+	process.exit(await main());
+}
diff --git a/tools/renovate/refresh-fod-hashes.ts b/tools/renovate/refresh-fod-hashes.ts
index 4ce807c9..4f24bcb6 100755
--- a/tools/renovate/refresh-fod-hashes.ts
+++ b/tools/renovate/refresh-fod-hashes.ts
@@ -126,7 +126,24 @@ export const FOD_ENTRIES: FodEntry[] = [
 		file: "agent-image/entrypoint.nix",
 		marker: 'outputHash = "sha256-',
 		drvFragment: "node-modules",
-		triggers: ["bun.lock", "devenv.lock"],
+		// `bun.lock` moves the installed tree's version set, and it is the trigger
+		// that actually moves this pin today. `devenv.lock` is the ROOT scope's
+		// channel pin: `guest-image/default.nix` imports entrypoint.nix with root's
+		// `pkgs`, so that lock supplies this FOD's `nativeBuildInputs = [ pkgs.bun ]`
+		// on the vehicle realised below. `agent-image/devenv.lock` is declared
+		// beside them because it moves the BUILDER in the OTHER consumer:
+		// `agent-image/devenv.nix` imports the SAME entrypoint.nix with the
+		// agent-image scope's own `pkgs`.
+		//
+		// Note the asymmetry this table cannot express. The vehicle realised below
+		// is `guest-image/default.nix`, so a relock of the agent-image channel alone
+		// recomputes a value derived through ROOT's bun, which will equal the
+		// committed one: the refresh is correct but cannot observe that consumer.
+		// The trigger is declared here so the coupling sits where a reader looks for
+		// it; the agent-image builder is verified by the image build, not by this
+		// refresh. All three paths are repo-root-relative, as the gate's `git diff`
+		// pathspec expects.
+		triggers: ["bun.lock", "devenv.lock", "agent-image/devenv.lock"],
 	},
 ];
 
@@ -239,6 +256,36 @@ async function recompute(entry: FodEntry, origText: string): Promise<string> {
 	}
 }
 
+// Refresh ONE entry's pin (and its mirrors) in place: read the current text,
+// recompute the SRI by realising the vehicle against a faked pin, write the real
+// value back, then propagate it to every declared mirror. This is the per-entry
+// body of main()'s gated loop, factored out so a scope-specific refresher can
+// drive a single FOD directly — refresh-agent-image-nixpkgs.ts calls it after its
+// own relock, having already established (by its own base diff) that the
+// agent-image entry's trigger moved. Extracting it keeps ONE realise-and-parse
+// implementation: a second copy would drift from the got:-attribution and
+// restore-on-failure discipline above.
+export async function refreshEntry(entry: FodEntry): Promise<void> {
+	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}`);
+	for (const mirror of entry.mirrorFiles ?? []) {
+		const mirrorText = await Bun.file(mirror).text();
+		await Bun.write(
+			mirror,
+			rewriteInlineHash(mirrorText, entry.marker, got, mirror),
+		);
+		console.log(`renovate-fod: ${mirror} (mirror) -> ${got}`);
+	}
+}
+
 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
@@ -282,24 +329,7 @@ async function main(): Promise<void> {
 	}
 
 	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}`);
-		for (const mirror of entry.mirrorFiles ?? []) {
-			const mirrorText = await Bun.file(mirror).text();
-			await Bun.write(
-				mirror,
-				rewriteInlineHash(mirrorText, entry.marker, got, mirror),
-			);
-			console.log(`renovate-fod: ${mirror} (mirror) -> ${got}`);
-		}
+		await refreshEntry(entry);
 	}
 
 	console.log("renovate-fod: FOD hashes refreshed.");