From 635d54d79c05ac58a123166982973433f3b71412 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Fri, 4 Sep 2026 13:01:29 -0400
Subject: [PATCH 1/3] feat(renovate): track the RigelBuild/devenv fork in both
 devenv locks (RIG-2815)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Compass carries two independent devenv scopes — the root dev shell
(`devenv.lock`) and the agent base image (`agent-image/devenv.lock`) — and both
resolve the shared canonical fork `github:RigelBuild/devenv` at its default
branch. Nothing tracked either pin, so both drifted months behind the fork's
`main` until someone relocked by hand. This wires Renovate to keep both current
on a daily schedule (RIG-2546 T7).

### Mechanism

A `custom.regex` manager surfaces each lock's fork rev as a `git-refs` digest, and
a coupled packageRule opens a solo branch that runs a `postUpgradeTask` to relock
the file with `devenv update devenv`. One manager + one rule + one branch per lock
(RD-1 unifies the source but does not reconcile the two locks, so they stay on
independent cadences).

### Why not `lockFileMaintenance`

The obvious mechanism is unimplementable here, source-verified against the pinned
`renovate@44.46.2`:

- `lockFileMaintenance` is manager-scoped (`flatten.ts` gates on
  `manager.supportsLockFileMaintenance`); `custom.regex` exports neither that flag
  nor `updateArtifacts` (`modules/manager/custom/regex/index.ts`), so it is
  silently ignored — no branch, no error, no PR.
- The native `nix` manager supports maintenance but only over
  `lockFileNames = ['flake.lock']` (`modules/manager/nix/index.ts`), never
  `devenv.lock`.
- `postUpgradeTasks` are filtered off `lockFileMaintenance` branches entirely
  (`workers/repository/update/branch/execute-post-upgrade-commands.ts:387-400`), so
  even a maintenance-capable manager could not carry the relock.

A normal digest upgrade *does* carry `postUpgradeTasks`, which is exactly what the
regex-digest + task pairing buys — the same mechanism the devenv-nixpkgs channel
lockstep (`refresh-devenv-nixpkgs.ts`) already relies on. The manager and rule
comments carry this argument in full, prefixed DO NOT SIMPLIFY.

### Verification

- `moon run renovate:typecheck renovate:test` green — 148 pass / 0 fail (+26 new
  tests across the guard core, its orchestration harness, and the config coupling).
- Live `renovate@44.46.2 --dry-run=extract` against the working tree: both managers
  fire — `RigelBuild/devenv` extracts the root lock's rev, `RigelBuild/devenv-agent-image`
  the agent-image lock's, both as `git-refs` digests. The agent-image lock is behind
  the fork HEAD, so a relock PR would open now; the root lock is coincidentally current.
- The relock script's wrong-directory guard was red-checked (`.cwd(cwd)` → `.cwd(".")`
  turns the agent-image orchestration test red).

Spec-impact: none. Refs RIG-2815.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/bot-config.json5               |  12 +-
 tools/renovate/config.json5                   | 166 +++++++++++
 tools/renovate/config.test.ts                 | 202 +++++++++++++-
 tools/renovate/moon.yml                       |   3 +
 .../renovate/refresh-devenv-lock.core.test.ts | 130 +++++++++
 tools/renovate/refresh-devenv-lock.core.ts    | 120 ++++++++
 tools/renovate/refresh-devenv-lock.test.ts    | 261 ++++++++++++++++++
 tools/renovate/refresh-devenv-lock.ts         | 162 +++++++++++
 8 files changed, 1044 insertions(+), 12 deletions(-)
 create mode 100644 tools/renovate/refresh-devenv-lock.core.test.ts
 create mode 100644 tools/renovate/refresh-devenv-lock.core.ts
 create mode 100644 tools/renovate/refresh-devenv-lock.test.ts
 create mode 100644 tools/renovate/refresh-devenv-lock.ts

diff --git a/tools/renovate/bot-config.json5 b/tools/renovate/bot-config.json5
index 4e951f74..2b6005f0 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.)
   //
-  // Five entries, all load-bearing:
+  // Six 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
@@ -85,7 +85,14 @@
   //      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
+  //   6. the devenv-fork relock, which on either compass devenv lock's
+  //      fork-rev digest bump runs `devenv update devenv` in that lock's own
+  //      directory, rewriting the whole lock (narHash/lastModified + the
+  //      fork's transitive nodes) at the new rev rather than leaving the
+  //      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.
   allowedCommands: [
@@ -94,5 +101,6 @@
     "^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-devenv-lock\\.ts$",
   ],
 }
diff --git a/tools/renovate/config.json5 b/tools/renovate/config.json5
index 04617112..f9ab2216 100644
--- a/tools/renovate/config.json5
+++ b/tools/renovate/config.json5
@@ -178,6 +178,77 @@
       currentValueTemplate: "rolling",
       datasourceTemplate: "git-refs",
     },
+    {
+      // ── devenv fork rev: root dev shell (RIG-2815 / RIG-2546 T7) ──
+      // Both compass devenv scopes resolve the shared canonical fork
+      // `github:RigelBuild/devenv` at its DEFAULT BRANCH (devenv.yaml:52-56 —
+      // no ref, no rev), so the concrete rev lives only in devenv.lock and
+      // nothing moved it: both locks drifted months behind the fork's `main`
+      // until someone relocked by hand. This manager surfaces the root lock's
+      // fork rev as a git-refs digest so Renovate tracks it, and the coupled
+      // packageRule below relocks the file properly on the branch it opens.
+      //
+      // WHY A REGEX MANAGER + A postUpgradeTask, NOT `lockFileMaintenance` —
+      // DO NOT "SIMPLIFY" THIS. Source-verified against the pinned
+      // renovate@44.46.2: `lockFileMaintenance` is MANAGER-scoped
+      // (workers/repository/updates/flatten.ts gates it on
+      // `manager.supportsLockFileMaintenance`), and the `custom.regex` manager
+      // exports neither that flag nor an `updateArtifacts`
+      // (modules/manager/custom/regex/index.ts) — so the option is silently
+      // IGNORED for it: no branch, no error, no PR. The native `nix` manager
+      // DOES support maintenance but only over `lockFileNames =
+      // ['flake.lock']` (modules/manager/nix/index.ts), never devenv's own
+      // `devenv.lock` format. And postUpgradeTasks are FILTERED OFF
+      // lockFileMaintenance branches entirely
+      // (workers/repository/update/branch/execute-post-upgrade-commands.ts:387-400
+      // — a maintenance branch calls `updateArtifacts()` directly), so even a
+      // manager that supported maintenance could not carry the relock. A
+      // NORMAL digest upgrade does carry postUpgradeTasks, which is exactly
+      // what this pairing buys — the same mechanism the devenv-nixpkgs channel
+      // lockstep above already relies on.
+      //
+      // Anchor: `"repo": "devenv"` immediately followed by `"rev"`. devenv
+      // writes alphabetized keys inside `locked` (…owner, repo, rev, type…),
+      // so this pair is unique in the file — the `original` block repeats
+      // `"repo": "devenv"` but is followed by `"type"`, never `"rev"` (the
+      // input names no ref), so the regex cannot mis-bind. The closing
+      // `"devenv",` quote+comma also keeps it off the `"devenv-nixpkgs"` node
+      // the channel manager above owns. config.test.ts pins the extraction
+      // against the real devenv.lock.
+      customType: "regex",
+      managerFilePatterns: ["/^devenv\\.lock$/"],
+      matchStrings: [
+        "\"repo\": \"devenv\",\\s*\"rev\": \"(?<currentDigest>[a-f0-9]{40})\"",
+      ],
+      depNameTemplate: "RigelBuild/devenv",
+      packageNameTemplate: "https://github.com/RigelBuild/devenv",
+      currentValueTemplate: "main",
+      datasourceTemplate: "git-refs",
+    },
+    {
+      // ── devenv fork rev: agent base image (RIG-2815 / RIG-2546 T7) ──
+      // Same fork, same mechanism, SEPARATE scope: agent-image/devenv.lock is
+      // the agent base image's own devenv (agent-image/devenv.yaml:45-49). RD-1
+      // unifies the devenv SOURCE across the two scopes but deliberately does
+      // NOT reconcile the two locks — each tracks the fork on its own cadence —
+      // so this is a second manager over the second file rather than a widened
+      // managerFilePatterns on the one above. Its `depNameTemplate` is
+      // DISTINCT (`RigelBuild/devenv-agent-image`, not the upstream slug) so
+      // the two rules are independently governed and, crucially, land in
+      // DIFFERENT groups/branches — the distinct-name idiom the
+      // `postgres-stack` manager below already uses to fence a rule off its
+      // same-named sibling. The lockFileMaintenance-is-unimplementable
+      // reasoning on the root manager above applies verbatim here.
+      customType: "regex",
+      managerFilePatterns: ["/^agent-image/devenv\\.lock$/"],
+      matchStrings: [
+        "\"repo\": \"devenv\",\\s*\"rev\": \"(?<currentDigest>[a-f0-9]{40})\"",
+      ],
+      depNameTemplate: "RigelBuild/devenv-agent-image",
+      packageNameTemplate: "https://github.com/RigelBuild/devenv",
+      currentValueTemplate: "main",
+      datasourceTemplate: "git-refs",
+    },
     {
       // ── bun toolchain pin ──
       // tools/toolchain/versions/bun.nix pins the vendored bun version; the native
@@ -569,6 +640,101 @@
         executionMode: "branch",
       },
     },
+    {
+      // ── devenv fork currency: root dev shell (RIG-2815 / RIG-2546 T7) ──
+      // Solo branch for the root lock's devenv-fork digest, on the SAME shape
+      // as the devenv-nixpkgs rule above: its own groupName so it NEVER shares
+      // a branch with the "TypeScript dependencies" rollup (which also matches
+      // custom.regex) NOR with its agent-image sibling below. That isolation is
+      // what makes the branch-mode postUpgradeTask safe — Renovate builds
+      // exactly ONE branch-mode task per branch, so a dep that never shares a
+      // branch owns that single slot. It is also what keeps the two locks on
+      // INDEPENDENT cadences per RD-1 (unify the source, do NOT reconcile the
+      // locks): two groupNames, two branches, two PRs. The rollup can't capture
+      // this dep regardless — its update type is `digest` and the rollup admits
+      // only patch/minor.
+      matchManagers: ["custom.regex"],
+      matchDepNames: ["RigelBuild/devenv"],
+      groupName: "devenv fork (root)",
+      // DAILY, in the same before-4am-ET window the daily cron lands in (see
+      // `timezone` above) — matching the devenv-nixpkgs rule's cadence. The
+      // fork's `main` moves whenever the shared canonical devenv does, and both
+      // locks resolve it by default branch, so daily is what "keep current"
+      // means here.
+      schedule: ["before 4am"],
+      // The repo-wide `minimumReleaseAge` + `internalChecksFilter: "strict"`
+      // measures age from a release TIMESTAMP. A git-refs digest update to a
+      // moving branch HEAD carries no release-age metadata, so a strict
+      // cooldown treats it as permanently `pending` and the digest sits on the
+      // dashboard forever with zero PRs cut (the RIG-1220 silent-no-updates
+      // shape). Disable the cooldown for THIS rule only — SAME reason as the
+      // devenv-nixpkgs rule above; the window exists for the compromised-
+      // registry-release risk, which does not apply to our own fork.
+      minimumReleaseAge: null,
+      // ── The relock task. ──
+      // The regex update rewrites ONLY the rev string, leaving narHash /
+      // lastModified / the fork's transitive nodes describing the OLD rev. This
+      // task runs `devenv update devenv` in the repo root to rewrite the whole
+      // lock consistently at the fork's current HEAD.
+      //
+      // This pairing — regex digest + postUpgradeTask — is NOT a workaround to
+      // be simplified away: `lockFileMaintenance` cannot do this job. See the
+      // full source-verified argument on the manager (renovate@44.46.2:
+      // custom.regex exports no `updateArtifacts`/`supportsLockFileMaintenance`;
+      // the nix manager's maintenance covers flake.lock only; and
+      // postUpgradeTasks are filtered off maintenance branches per
+      // execute-post-upgrade-commands.ts:387-400). A normal digest upgrade
+      // carries postUpgradeTasks — a maintenance branch does not.
+      //
+      // `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 slot. 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. fileFilters is an
+      // INCLUDE allowlist — Renovate commits ONLY matching files — and the
+      // relock writes exactly this one lock, so it is the sole entry. Listing
+      // the agent-image lock here would be dead surface (that lock is the
+      // sibling rule's) and listing LESS would silent-drop the relock, shipping
+      // a rev bump whose narHash never moved.
+      //
+      // Self-hosted bot config MUST allow the command:
+      //   allowedCommands: [… , "^bun tools/renovate/refresh-devenv-lock\\.ts$"]
+      // see tools/renovate/bot-config.json5 (config.test.ts pins the two
+      // together). ONE command string serves both locks — the script self-gates
+      // on WHICH lock changed — so one allowlist entry covers both rules.
+      postUpgradeTasks: {
+        commands: ["bun tools/renovate/refresh-devenv-lock.ts"],
+        fileFilters: ["devenv.lock"],
+        executionMode: "branch",
+      },
+    },
+    {
+      // ── devenv fork currency: agent base image (RIG-2815 / RIG-2546 T7) ──
+      // The agent-image sibling of the rule above, scoped by the DISTINCT
+      // depName its manager stamps (`RigelBuild/devenv-agent-image`) and
+      // carrying its OWN groupName. Both properties are load-bearing: the
+      // distinct name keeps the two 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
+      // two branch-mode relock tasks never contend for one branch's single
+      // task slot. Same command as the root rule — the script decides which
+      // lock to relock from the branch diff and runs `devenv update devenv` in
+      // agent-image/ for this one — so one allowlist entry covers both.
+      // `minimumReleaseAge: null` for the same git-refs-carries-no-release-age
+      // reason, and the same lockFileMaintenance-is-unimplementable argument
+      // (see the manager) applies verbatim.
+      matchManagers: ["custom.regex"],
+      matchDepNames: ["RigelBuild/devenv-agent-image"],
+      groupName: "devenv fork (agent-image)",
+      schedule: ["before 4am"],
+      minimumReleaseAge: null,
+      postUpgradeTasks: {
+        commands: ["bun tools/renovate/refresh-devenv-lock.ts"],
+        fileFilters: ["agent-image/devenv.lock"],
+        executionMode: "branch",
+      },
+    },
     {
       // ── Go toolchain ↔ go-overlay lockstep (RIG-3100) ──
       // The go customManager (above) opens a solo branch that rewrites ONLY the
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index 47c66fbb..6c6c52d0 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -188,20 +188,23 @@ 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 five DISTINCT
+	// entry's `^…$` IS the security property. Compass declares six 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
+	// appears twice in the declared list but needs only one allowlist entry; the
+	// devenv-fork relock likewise rides BOTH devenv-fork rules under one command
+	// string, since the script self-gates on which lock changed); every
 	// distinct command must be permitted, every entry must be used, and no entry may
 	// be an unanchored substring rule. RIG-3100 added the fifth: the go↔go-overlay
-	// lockstep on the go pin's solo branch.
+	// lockstep on the go pin's solo branch. RIG-2815 added the sixth: the
+	// devenv-fork relock on each devenv lock's solo branch.
 	const commands = allDeclaredCommands();
 	const distinctCommands = [...new Set(commands)];
 	const allowed = bot.allowedCommands ?? [];
 
-	test("declares five DISTINCT postUpgrade commands and five allowlist entries", () => {
-		expect(distinctCommands).toHaveLength(5);
-		expect(allowed).toHaveLength(5);
+	test("declares six DISTINCT postUpgrade commands and six allowlist entries", () => {
+		expect(distinctCommands).toHaveLength(6);
+		expect(allowed).toHaveLength(6);
 	});
 
 	test("the fod-hash refresh is declared at BOTH task sites (top-level + catalog)", () => {
@@ -252,10 +255,11 @@ describe("tools/renovate postUpgradeTasks ↔ allowedCommands (RIG-2432)", () =>
 		).toBe(false);
 	});
 
-	test("permits exactly the five RIG-2432/RIG-3100 commands", () => {
+	test("permits exactly the six RIG-2432/RIG-3100/RIG-2815 commands", () => {
 		expect(distinctCommands.sort()).toEqual(
 			[
 				"bun install --lockfile-only",
+				"bun tools/renovate/refresh-devenv-lock.ts",
 				"bun tools/renovate/refresh-devenv-nixpkgs.ts",
 				"bun tools/renovate/refresh-fod-hashes.ts",
 				"bun tools/renovate/refresh-go-overlay.ts",
@@ -442,9 +446,12 @@ describe("tools/renovate root bun catalog manager", () => {
 
 describe("tools/renovate devenv nixpkgs lockstep", () => {
 	// The customManager surfacing devenv.lock's channel rev as a git-refs digest;
-	// find it by file pattern, not index.
-	const devenvManager = cfg.customManagers?.find((m) =>
-		m.managerFilePatterns?.some((p) => p.includes("devenv")),
+	// find it by the dep it stamps, not index — and NOT by file pattern alone:
+	// the RIG-2815 devenv-FORK managers also pattern-match a devenv lock, so a
+	// `includes("devenv")` finder would be ambiguous (order-dependent) between
+	// three managers over the same two files.
+	const devenvManager = cfg.customManagers?.find(
+		(m) => m.depNameTemplate === "cachix/devenv-nixpkgs",
 	);
 	const devenvRule = cfg.packageRules.find(
 		(r) => r.groupName === "devenv nixpkgs channel",
@@ -560,6 +567,181 @@ describe("tools/renovate devenv nixpkgs lockstep", () => {
 	});
 });
 
+describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
+	// Both compass devenv scopes resolve github:RigelBuild/devenv by DEFAULT
+	// BRANCH, so the concrete rev lives only in devenv.lock and nothing moved it
+	// until T7. Two customManagers surface the two locks' fork revs as git-refs
+	// digests, each paired with its own solo-branched packageRule carrying the
+	// relock postUpgradeTask. RD-1 keeps the two locks on INDEPENDENT cadences
+	// (unify the source, do NOT reconcile the locks), which is why this is two
+	// managers + two rules + two groupNames and not one widened pair.
+	//
+	// Found by the dep each stamps, never by index or a bare "devenv" file-pattern
+	// substring (the devenv-nixpkgs channel manager pattern-matches the same root
+	// lock).
+	const RELOCK = "bun tools/renovate/refresh-devenv-lock.ts";
+	const forkScopes: {
+		label: string;
+		depName: string;
+		lock: string;
+		groupName: string;
+	}[] = [
+		{
+			label: "root",
+			depName: "RigelBuild/devenv",
+			lock: "devenv.lock",
+			groupName: "devenv fork (root)",
+		},
+		{
+			label: "agent-image",
+			depName: "RigelBuild/devenv-agent-image",
+			lock: "agent-image/devenv.lock",
+			groupName: "devenv fork (agent-image)",
+		},
+	];
+	const managerFor = (depName: string) =>
+		cfg.customManagers?.find((m) => m.depNameTemplate === depName);
+	const ruleFor = (depName: string) =>
+		cfg.packageRules.find((r) => r.matchDepNames?.includes(depName));
+
+	test.each(forkScopes)(
+		"declares a git-refs regex manager for the $label lock's fork rev",
+		({ depName, lock }) => {
+			const manager = managerFor(depName);
+			expect(manager).toBeDefined();
+			expect(manager?.customType).toBe("regex");
+			expect(manager?.datasourceTemplate).toBe("git-refs");
+			// Both scopes point at the SAME fork repo (RD-1's unified source); only
+			// the depName differs, which is what keeps the two rules independently
+			// governed and in separate branches.
+			expect(manager?.packageNameTemplate).toBe(
+				"https://github.com/RigelBuild/devenv",
+			);
+			// The locks name no ref, so the tracked value is the default branch.
+			expect(manager?.currentValueTemplate).toBe("main");
+
+			// The file pattern must be ANCHORED to exactly this lock: a loose
+			// pattern would make the root manager extract from the agent-image lock
+			// too (or vice versa), collapsing the two independent scopes into one
+			// dep with two files and two conflicting digests.
+			const pattern = manager?.managerFilePatterns?.[0];
+			const delimited = /^\/(.*)\/$/.exec(pattern as string);
+			expect(delimited).not.toBeNull();
+			const re = new RegExp(delimited?.[1] as string);
+			expect(re.test(lock)).toBe(true);
+			expect(re.test("package.json")).toBe(false);
+			expect(re.test(`a/${lock}`)).toBe(false); // anchored, no arbitrary prefix
+			const otherLock = forkScopes.find((s) => s.lock !== lock)?.lock as string;
+			expect(re.test(otherLock)).toBe(false); // and never the sibling scope
+		},
+	);
+
+	// The matchString must recover EXACTLY ONE 40-hex rev from the REAL lock, and
+	// it must be the fork's own `nodes.devenv.locked.rev`. The anchor's whole
+	// safety argument is that `"repo": "devenv",` is followed by `"rev"` ONLY in
+	// the `locked` block — the `original` block repeats the repo but is followed
+	// by `"type"` (the input names no ref). Assert the uniqueness against ground
+	// truth so a devenv lock-format change fails HERE rather than silently
+	// binding to the wrong node (or to the `devenv-nixpkgs` node the channel
+	// manager owns).
+	test.each(forkScopes)(
+		"matchString extracts the fork rev from the real $label lock",
+		({ depName, lock }) => {
+			const lockText = readFileSync(join(repoRoot, lock), "utf8");
+			const matchString = managerFor(depName)?.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.devenv.locked.rev);
+			// Not the devenv-nixpkgs channel rev — a `"repo": "devenv"` prefix match
+			// against `"devenv-nixpkgs"` is the exact mis-bind the trailing quote in
+			// the anchor prevents.
+			expect(rev).not.toBe(parsed.nodes.nixpkgs?.locked?.rev);
+		},
+	);
+
+	// Solo-branched, scheduled, cooldown-nulled — the devenv-nixpkgs rule's 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 locks on independent cadences.
+	test.each(forkScopes)(
+		"the $label fork rule is solo-grouped, scheduled, and cooldown-exempt",
+		({ depName, groupName }) => {
+			const rule = ruleFor(depName);
+			expect(rule).toBeDefined();
+			expect(rule?.matchManagers).toContain("custom.regex");
+			expect(rule?.groupName).toBe(groupName);
+			expect(
+				cfg.packageRules.filter((r) => r.groupName === groupName),
+			).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 relock over exactly the ONE lock the rule governs. fileFilters
+	// is an INCLUDE allowlist — Renovate commits ONLY listed files — so naming
+	// the sibling lock would be dead surface and naming LESS would silent-drop
+	// the relock, shipping a rev bump whose narHash/lastModified never moved (the
+	// same silent-drop mode the FOD guard above documents).
+	test.each(forkScopes)(
+		"the $label relock postUpgradeTask is branch-mode over its lock alone",
+		({ depName, lock }) => {
+			const task = ruleFor(depName)?.postUpgradeTasks;
+			expect(task?.executionMode).toBe("branch");
+			expect(task?.fileFilters).toEqual([lock]);
+			expect(task?.commands).toEqual([RELOCK]);
+		},
+	);
+
+	// ONE command string serves both rules — the script self-gates on WHICH lock
+	// changed — so a single anchored allowlist entry covers both. This is the
+	// coupling the allowedCommands describe above counts; assert the two rules
+	// really do share the string rather than drifting into two near-identical
+	// scripts (which would silently need a second allowlist entry).
+	test("both fork rules declare the SAME relock command (one allowlist entry)", () => {
+		const declaring = cfg.packageRules.filter((r) =>
+			r.postUpgradeTasks?.commands?.includes(RELOCK),
+		);
+		expect(declaring).toHaveLength(2);
+		expect(
+			bot.allowedCommands?.filter((a) => new RegExp(a).test(RELOCK)),
+		).toEqual(["^bun tools/renovate/refresh-devenv-lock\\.ts$"]);
+	});
+
+	// The two locks must never land in ONE branch: two branch-mode relock tasks
+	// on a shared branch means Renovate builds only one and the other lock ships
+	// rev-bumped-but-unrelocked. Replay the real last-match-wins packageRule
+	// semantics for each scope's digest and assert each resolves to its own
+	// group, never the TypeScript rollup (which also matches custom.regex).
+	test.each(forkScopes)(
+		"the $label fork digest resolves to its own solo branch, not the TS rollup",
+		({ depName, lock, groupName }) => {
+			const group = resolveGroupName({
+				manager: "custom.regex",
+				fileName: lock,
+				depName,
+				updateType: "digest",
+			});
+			expect(group).toBe(groupName);
+			expect(group).not.toBe("TypeScript dependencies");
+		},
+	);
+
+	test("the two fork scopes carry DISTINCT groupNames (independent cadences)", () => {
+		const groups = forkScopes.map((s) => ruleFor(s.depName)?.groupName);
+		expect(new Set(groups).size).toBe(forkScopes.length);
+	});
+});
+
 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.
diff --git a/tools/renovate/moon.yml b/tools/renovate/moon.yml
index 6e3d4668..6f83bf5b 100644
--- a/tools/renovate/moon.yml
+++ b/tools/renovate/moon.yml
@@ -32,6 +32,9 @@ tasks:
       - '/package.json'
       - '/bunfig.toml'
       - '/devenv.lock'
+      # RIG-2815: the guard suite + the relock core's real-manifest tests read
+      # the agent-image devenv lock too, not just the root one.
+      - '/agent-image/devenv.lock'
       - '/.github/workflows/renovate.yml'
     options:
       # Never cache: the guard suite reads the live root package.json, bunfig,
diff --git a/tools/renovate/refresh-devenv-lock.core.test.ts b/tools/renovate/refresh-devenv-lock.core.test.ts
new file mode 100644
index 00000000..5496f40a
--- /dev/null
+++ b/tools/renovate/refresh-devenv-lock.core.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	changedDevenvLock,
+	DEVENV_LOCK_PATHS,
+	DEVENV_LOCK_SCOPES,
+	devenvForkLockedRev,
+} from "./refresh-devenv-lock.core.ts";
+
+// Unit tests for the pure decision core of refresh-devenv-lock.ts (RIG-2815):
+// deciding WHICH of the two devenv locks a Renovate branch touched, and reading
+// the RigelBuild/devenv fork rev out of a lock. No devenv / network / git —
+// that shell-out lives in the entry point and runs for real on the PR's own
+// branch. These assert the decisions a wrong line would silently corrupt:
+// relocking the wrong scope (whose write the rule's one-lock fileFilters then
+// discards), or reading a stale/wrong rev.
+
+const repoRoot = join(import.meta.dir, "..", "..");
+
+describe("DEVENV_LOCK_SCOPES", () => {
+	// The cwd IS the scope selector — devenv resolves devenv.yaml/devenv.lock
+	// relative to it — so each scope's cwd must be the directory its lock lives
+	// in. A mismatch would relock the OTHER scope's lock while the rule's
+	// fileFilters names this one, so Renovate would commit nothing and the rev
+	// bump would ship unrelocked.
+	test("every scope's relock cwd is the directory holding that scope's lock", () => {
+		for (const { lock, cwd } of Object.values(DEVENV_LOCK_SCOPES)) {
+			const dir = lock.includes("/")
+				? lock.slice(0, lock.lastIndexOf("/"))
+				: ".";
+			expect(cwd).toBe(dir);
+		}
+	});
+
+	// Ground truth: both locks the config's two managers govern must actually
+	// exist at these paths, and each must be a devenv lock pinning the fork.
+	test("both scope locks exist in the real tree and pin a 40-hex fork rev", () => {
+		expect(DEVENV_LOCK_PATHS).toEqual([
+			"devenv.lock",
+			"agent-image/devenv.lock",
+		]);
+		for (const lock of DEVENV_LOCK_PATHS) {
+			const text = readFileSync(join(repoRoot, lock), "utf8");
+			expect(devenvForkLockedRev(text)).toMatch(/^[a-f0-9]{40}$/);
+		}
+	});
+
+	// RD-1: unify the SOURCE, do NOT reconcile the locks. The two locks tracking
+	// the fork independently means their revs may legitimately differ — this test
+	// documents that they are read as separate scopes, never compared for
+	// equality anywhere in the task.
+	test("the two scopes are distinct files (independent cadences, not reconciled)", () => {
+		const locks = Object.values(DEVENV_LOCK_SCOPES).map((s) => s.lock);
+		expect(new Set(locks).size).toBe(locks.length);
+	});
+});
+
+describe("changedDevenvLock", () => {
+	const ROOT = "devenv.lock";
+	const AGENT = "agent-image/devenv.lock";
+
+	test("selects the root scope when only the root lock changed", () => {
+		expect(changedDevenvLock([ROOT])).toBe("root");
+	});
+
+	test("selects the agent-image scope when only that lock changed", () => {
+		expect(changedDevenvLock([AGENT])).toBe("agent-image");
+	});
+
+	// The self-gate: on every unrelated Renovate branch the task must be a cheap
+	// no-op, not a spurious relock. Dropping this gate would make the task
+	// re-lock (and network) on branches it has nothing to do with.
+	test("returns null when no devenv lock changed (the self-gate no-op)", () => {
+		expect(changedDevenvLock([])).toBeNull();
+		expect(changedDevenvLock(["package.json", "bun.lock"])).toBeNull();
+	});
+
+	// Paths are compared EXACTLY, as `git diff --name-only` emits them: a
+	// same-named lock elsewhere in the tree is not either governed scope, and
+	// treating it as one would relock a file no rule's fileFilters admits.
+	test("does not mistake a same-named lock elsewhere for a governed scope", () => {
+		expect(changedDevenvLock(["forks/devenv/devenv.lock"])).toBeNull();
+		expect(changedDevenvLock(["a/agent-image/devenv.lock"])).toBeNull();
+	});
+
+	// Fail loud on the shape the two distinct groupNames exist to prevent. Each
+	// rule's fileFilters names ONE lock, so a two-lock branch would have Renovate
+	// commit one relock and silently DISCARD the other — a PR that bumped a rev
+	// without relocking it. Better to die in-branch than ship that.
+	test("throws when BOTH locks changed (the groupName isolation broke)", () => {
+		expect(() => changedDevenvLock([ROOT, AGENT])).toThrow(
+			/2 devenv locks changed/,
+		);
+	});
+});
+
+describe("devenvForkLockedRev", () => {
+	// Real-manifest guard: the extraction must recover the fork rev from each
+	// checked-in lock, so a devenv lock-format change (the node moves/renames)
+	// fails HERE, loudly, instead of the task logging `undefined` and relocking
+	// blind.
+	test.each(["devenv.lock", "agent-image/devenv.lock"])(
+		"recovers the fork rev from the real %s",
+		(lock) => {
+			const text = readFileSync(join(repoRoot, lock), "utf8");
+			const rev = devenvForkLockedRev(text);
+			expect(rev).toMatch(/^[a-f0-9]{40}$/);
+			expect(rev).toBe(JSON.parse(text).nodes.devenv.locked.rev);
+		},
+	);
+
+	test("throws on invalid JSON", () => {
+		expect(() => devenvForkLockedRev("{not json")).toThrow(/not valid JSON/);
+	});
+
+	test("throws when the devenv node is absent", () => {
+		const noNode = JSON.stringify({
+			nodes: { nixpkgs: { locked: { rev: "x" } } },
+		});
+		expect(() => devenvForkLockedRev(noNode)).toThrow(/devenv fork rev/);
+	});
+
+	test("throws on a non-40-hex rev (shape drift)", () => {
+		const shortRev = JSON.stringify({
+			nodes: { devenv: { locked: { rev: "abc123" } } },
+		});
+		expect(() => devenvForkLockedRev(shortRev)).toThrow(/devenv fork rev/);
+	});
+});
diff --git a/tools/renovate/refresh-devenv-lock.core.ts b/tools/renovate/refresh-devenv-lock.core.ts
new file mode 100644
index 00000000..1fc30d11
--- /dev/null
+++ b/tools/renovate/refresh-devenv-lock.core.ts
@@ -0,0 +1,120 @@
+// Pure decision core for refresh-devenv-lock.ts (RIG-2815).
+//
+// Split out from the entry point so the two load-bearing decisions — WHICH of
+// the two devenv locks a Renovate branch touched, and which rev that lock
+// currently pins — are unit-testable without a devenv runner, a network, or a
+// git tree. Picking the wrong scope here would relock the WRONG lock file, and
+// the packageRule's `fileFilters` would then silently drop the write (it is an
+// INCLUDE allowlist naming exactly one lock), shipping a PR whose rev bump was
+// never followed by a real relock. The entry point owns the shell-outs (the
+// base diff, `devenv update devenv`); this file owns the decisions. NO
+// shell-outs, NO fs beyond text passed in.
+
+/**
+ * The two independently-locked devenv scopes in this repo. RD-1 unifies the
+ * devenv SOURCE (both `github:RigelBuild/devenv`) but deliberately does NOT
+ * reconcile the two locks — each tracks the fork on its own cadence, so each
+ * gets its own manager, its own packageRule, and its own branch.
+ */
+export type DevenvLockScope = "root" | "agent-image";
+
+/**
+ * Per-scope geometry: the repo-root-relative lock path (the file the
+ * customManager rewrites and this task's self-gate trigger) and the
+ * repo-root-relative directory to run `devenv update devenv` from. devenv
+ * resolves devenv.yaml/devenv.lock relative to its cwd, so the cwd IS the
+ * scope selector — `.` for the root dev shell, `agent-image` for the agent
+ * base image's own devenv.
+ */
+export const DEVENV_LOCK_SCOPES: Record<
+	DevenvLockScope,
+	{ readonly lock: string; readonly cwd: string }
+> = {
+	root: { lock: "devenv.lock", cwd: "." },
+	"agent-image": { lock: "agent-image/devenv.lock", cwd: "agent-image" },
+};
+
+/** Every scope's lock path, in scope order — the git-diff pathspec. */
+export const DEVENV_LOCK_PATHS: string[] = Object.values(
+	DEVENV_LOCK_SCOPES,
+).map((s) => s.lock);
+
+/**
+ * Which devenv lock this branch changed, decided from the paths a diff against
+ * the branch point reported.
+ *
+ * - Exactly one lock changed → that scope (the normal Renovate branch: one
+ *   manager, one rule, one lock).
+ * - No lock changed → `null`, the self-gate no-op. This is the common case:
+ *   the task rides one specific rule, but a maintainer copy-pasting it onto
+ *   another rule (or a manual run) must be a cheap no-op, not a spurious
+ *   relock.
+ * - BOTH locks changed → throws. The two rules carry distinct groupNames
+ *   precisely so they never share a branch, so this shape means an assumption
+ *   broke. Relocking both would be worse than useless: each rule's
+ *   `fileFilters` names ONE lock, so Renovate would commit one relock and
+ *   silently discard the other — a PR that bumped a rev without relocking it.
+ *   Fail loud instead.
+ *
+ * Paths are compared exactly (repo-root-relative, as `git diff --name-only`
+ * emits them), so an unrelated `foo/devenv.lock` can never be mistaken for
+ * either scope.
+ */
+export function changedDevenvLock(
+	changedPaths: readonly string[],
+): DevenvLockScope | null {
+	const changed = (Object.keys(DEVENV_LOCK_SCOPES) as DevenvLockScope[]).filter(
+		(scope) => changedPaths.includes(DEVENV_LOCK_SCOPES[scope].lock),
+	);
+	if (changed.length > 1) {
+		throw new Error(
+			`refresh-devenv-lock: ${changed.length} devenv locks changed vs the branch point ` +
+				`(${changed.map((s) => DEVENV_LOCK_SCOPES[s].lock).join(", ")}) — each packageRule's ` +
+				"fileFilters names exactly ONE lock, so a two-lock branch would commit one relock and " +
+				"silently drop the other. The two rules carry distinct groupNames so they never share a " +
+				"branch; this shape means that invariant broke.",
+		);
+	}
+	return changed[0] ?? null;
+}
+
+/**
+ * The concrete `github:RigelBuild/devenv` fork rev a devenv lock pins, read
+ * from its `devenv` node (`nodes.devenv.locked.rev`) — the SAME field the
+ * customManager's matchString surfaces as a git-refs digest. Read before and
+ * after the relock so the advance is observable in the task log, and so a
+ * relock that moved nothing fails loud rather than shipping a rev-only rewrite
+ * with a stale narHash. Parsed as JSON (devenv.lock is JSON), throwing loudly
+ * if the node or a 40-hex rev is absent — a lock-shape change must fail the
+ * task, never silently read the wrong rev.
+ */
+export function devenvForkLockedRev(devenvLockText: string): string {
+	let lock: unknown;
+	try {
+		lock = JSON.parse(devenvLockText);
+	} catch (error) {
+		throw new Error(
+			`refresh-devenv-lock: 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.devenv;
+		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-devenv-lock: could not read a 40-hex devenv fork rev from devenv.lock " +
+				"(nodes.devenv.locked.rev) — devenv lock shape may have changed.",
+		);
+	}
+	return rev;
+}
diff --git a/tools/renovate/refresh-devenv-lock.test.ts b/tools/renovate/refresh-devenv-lock.test.ts
new file mode 100644
index 00000000..2f298915
--- /dev/null
+++ b/tools/renovate/refresh-devenv-lock.test.ts
@@ -0,0 +1,261 @@
+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-devenv-lock.ts (RIG-2815).
+//
+// The pure decisions (which lock changed, the fork-rev read) are unit-tested in
+// refresh-devenv-lock.core.test.ts. This drives the SHIPPED entry point end to
+// end inside a throwaway git repo with a stub `devenv` on PATH, so the step
+// SEQUENCING is exercised offline + deterministically: self-gate → pick the
+// scope → relock in THAT scope's directory → verify the lock actually moved.
+// The real `devenv update devenv` runs for real against the workflow-built
+// devenv CLI on the PR's own branch; here it is stubbed so the failure mode
+// under test is the script's own control flow, not the network.
+//
+// The load-bearing assertion is the CWD one: the stub records the directory it
+// was invoked from, because relocking in the wrong directory would rewrite the
+// sibling scope's lock while the rule's one-lock `fileFilters` names this one —
+// so Renovate would commit nothing and the rev bump would ship unrelocked. A
+// cwd-agnostic stub would pass that bug green.
+
+// 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-devenv-lock.ts";
+const CORE_REL = "tools/renovate/refresh-devenv-lock.core.ts";
+const REAL_SCRIPT = join(import.meta.dir, "refresh-devenv-lock.ts");
+const REAL_CORE = join(import.meta.dir, "refresh-devenv-lock.core.ts");
+
+const ROOT_LOCK_REL = "devenv.lock";
+const AGENT_LOCK_REL = "agent-image/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",
+};
+
+// Three revs per scope: the base lock's, the one the regex update writes (a
+// rev-only rewrite — narHash still describes the base rev), and the one the
+// stubbed relock resolves.
+const BASE_REV = "1111111111111111111111111111111111111111";
+const BUMPED_REV = "2222222222222222222222222222222222222222";
+const RELOCKED_REV = "3333333333333333333333333333333333333333";
+
+// A minimal devenv lock carrying the `devenv` fork node the core reads
+// (nodes.devenv.locked.rev) plus the `original` block whose repeated
+// `"repo": "devenv"` (followed by `"type"`, never `"rev"`) is what makes the
+// config.json5 matchString anchor unique — kept here so the fixture has the
+// same ambiguity the real locks do.
+function devenvLock(rev: string, narHash: string): string {
+	return `${JSON.stringify(
+		{
+			nodes: {
+				devenv: {
+					locked: {
+						lastModified: 1,
+						narHash: `sha256-${narHash}`,
+						owner: "RigelBuild",
+						repo: "devenv",
+						rev,
+						type: "github",
+					},
+					original: {
+						owner: "RigelBuild",
+						repo: "devenv",
+						type: "github",
+					},
+				},
+				root: { inputs: { devenv: "devenv" } },
+			},
+			root: "root",
+			version: 7,
+		},
+		null,
+		2,
+	)}\n`;
+}
+
+// Stub `devenv`: on `devenv update devenv`, record the cwd it ran in and
+// rewrite ./devenv.lock (relative to that cwd — exactly how the real devenv
+// resolves the lock) to the RELOCKED rev with a fresh narHash, simulating a
+// real re-resolution. `.force-noop-relock` in the repo root instead makes it
+// exit 0 having written NOTHING, modelling a relock that did not move — the
+// half-relock the script must refuse. Offline.
+const STUB_DEVENV = `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = "update" ]; then
+  echo "$PWD" >> "$REPO_ROOT/.devenv-update-cwds"
+  echo "$@" >> "$REPO_ROOT/.devenv-update-args"
+  if [ -f "$REPO_ROOT/.force-noop-relock" ]; then
+    exit 0
+  fi
+  cat > devenv.lock <<'LOCK'
+${devenvLock(RELOCKED_REV, "CCCC")}
+LOCK
+fi
+exit 0
+`;
+
+async function buildRepo(): Promise<string> {
+	const repo = await mkdtemp(join(tmpdir(), "rig2815-"));
+	await mkdir(join(repo, "tools", "renovate"), { recursive: true });
+	await mkdir(join(repo, "agent-image"), { 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, ROOT_LOCK_REL), devenvLock(BASE_REV, "AAAA"));
+	await Bun.write(join(repo, AGENT_LOCK_REL), devenvLock(BASE_REV, "BBBB"));
+
+	await Bun.write(join(repo, "stubbin", "devenv"), STUB_DEVENV);
+	await chmod(join(repo, "stubbin", "devenv"), 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's regex update performs: it moves the
+// rev string and NOTHING else, so narHash still describes the base rev. This is
+// precisely the inconsistent state the relock task exists to repair.
+async function applyRegexBump(repo: string, lockRel: string, narHash: string) {
+	await Bun.write(join(repo, lockRel), devenvLock(BUMPED_REV, narHash));
+}
+
+// Run the shipped script as Renovate does: `bun tools/renovate/…ts`, cwd = repo
+// root, the stub first on PATH so no real 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",
+			REPO_ROOT: repo,
+		})
+		.quiet()
+		.nothrow();
+}
+
+describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
+	let repo: string;
+	beforeEach(async () => {
+		repo = await buildRepo();
+	});
+	afterEach(async () => {
+		if (repo) await rm(repo, { recursive: true, force: true });
+	});
+
+	// Self-gate: with neither lock changed vs base, the script is a cheap no-op —
+	// no relock, no network. Guards the gate against being dropped (an
+	// unconditional run would relock on EVERY Renovate branch).
+	test("is a no-op when neither devenv lock changed vs base", async () => {
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+		expect(res.stdout.toString()).toContain("nothing to do");
+		// devenv was never invoked.
+		expect(await Bun.file(join(repo, ".devenv-update-cwds")).exists()).toBe(
+			false,
+		);
+		expect(await readFile(join(repo, ROOT_LOCK_REL), "utf8")).toContain(
+			BASE_REV,
+		);
+	});
+
+	// The end-to-end happy path per scope, and the CWD assertion that is the
+	// whole point of two scopes: the relock must run in the changed lock's OWN
+	// directory (devenv resolves the lock relative to cwd), and must leave the
+	// SIBLING lock untouched — the rule's fileFilters admits only the one.
+	test.each([
+		{ label: "root", lockRel: ROOT_LOCK_REL, dir: ".", narHash: "AAAA" },
+		{
+			label: "agent-image",
+			lockRel: AGENT_LOCK_REL,
+			dir: "agent-image",
+			narHash: "BBBB",
+		},
+	])(
+		"relocks the $label lock in its own directory, leaving the sibling alone",
+		async ({ lockRel, dir, narHash }) => {
+			await applyRegexBump(repo, lockRel, narHash);
+
+			const res = await runRefresh(repo);
+			expect(res.exitCode).toBe(0);
+			expect(res.stdout.toString()).not.toContain("nothing to do");
+
+			// The relock re-resolved the input: the whole lock moved to the relocked
+			// rev, not merely the rev string the regex bumped.
+			const relocked = await readFile(join(repo, lockRel), "utf8");
+			expect(relocked).toContain(RELOCKED_REV);
+			expect(relocked).not.toContain(BUMPED_REV);
+			expect(res.stdout.toString()).toContain(`now at ${RELOCKED_REV}`);
+
+			// It ran `devenv update devenv` EXACTLY ONCE, in this scope's directory.
+			// A wrong cwd would rewrite the sibling's lock (which the rule cannot
+			// commit) and leave this one rev-bumped-but-unrelocked.
+			const cwds = (await readFile(join(repo, ".devenv-update-cwds"), "utf8"))
+				.trim()
+				.split("\n");
+			expect(cwds).toHaveLength(1);
+			expect(cwds[0]).toBe(dir === "." ? repo : join(repo, dir));
+			const args = (
+				await readFile(join(repo, ".devenv-update-args"), "utf8")
+			).trim();
+			// The SINGLE named input, not a bare `devenv update` (which would
+			// re-lock every input and bloat the PR's diff).
+			expect(args).toBe("update devenv");
+
+			// The sibling scope is untouched — the two locks are independent (RD-1).
+			const sibling =
+				lockRel === ROOT_LOCK_REL ? AGENT_LOCK_REL : ROOT_LOCK_REL;
+			expect(await readFile(join(repo, sibling), "utf8")).toContain(BASE_REV);
+		},
+	);
+
+	// Fail-loud: a relock that wrote NOTHING leaves the regex-bumped rev beside
+	// the base lock's narHash — the silent half-relock this task exists to
+	// prevent. It must die non-zero in-branch rather than ship it.
+	test("fails loud (exit≠0) when the relock leaves the lock byte-identical", async () => {
+		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
+		await Bun.write(join(repo, ".force-noop-relock"), "");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).not.toBe(0);
+		expect(res.stderr.toString()).toContain("byte-identical");
+	});
+
+	// Fail-loud: BOTH locks changed. The two rules carry distinct groupNames so
+	// they never share a branch; if that invariant ever breaks, relocking either
+	// one is wrong — each rule's fileFilters names ONE lock, so Renovate would
+	// commit one relock and silently drop the other. Die instead of guessing.
+	test("fails loud (exit≠0) when BOTH locks changed on one branch", async () => {
+		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
+		await applyRegexBump(repo, AGENT_LOCK_REL, "BBBB");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).not.toBe(0);
+		expect(res.stderr.toString()).toContain("devenv locks changed");
+		// And it relocked NEITHER — no partial write.
+		expect(await Bun.file(join(repo, ".devenv-update-cwds")).exists()).toBe(
+			false,
+		);
+	});
+});
diff --git a/tools/renovate/refresh-devenv-lock.ts b/tools/renovate/refresh-devenv-lock.ts
new file mode 100644
index 00000000..42c99d60
--- /dev/null
+++ b/tools/renovate/refresh-devenv-lock.ts
@@ -0,0 +1,162 @@
+// Renovate postUpgradeTask: relock a compass devenv lock at the new
+// RigelBuild/devenv fork rev (RIG-2815, RIG-2546 T7).
+//
+// Context. Compass carries TWO independent devenv scopes, both resolving the
+// shared canonical fork `github:RigelBuild/devenv` at its default branch:
+// the root dev shell (devenv.yaml/devenv.lock) and the agent base image
+// (agent-image/devenv.yaml + agent-image/devenv.lock). Nothing tracked either
+// pin, so both drifted behind the fork's `main` until someone relocked by
+// hand. RD-1 unifies the SOURCE but deliberately does NOT reconcile the two
+// locks, so each is governed on its OWN cadence: one customManager + one
+// packageRule + one branch per lock (config.json5).
+//
+// ── WHY THIS SCRIPT EXISTS AT ALL (do not "simplify" it to
+//    lockFileMaintenance) ──
+// The obvious mechanism — `lockFileMaintenance` on the lock files — is
+// UNIMPLEMENTABLE here. Source-verified against the pinned renovate@44.46.2:
+//
+//   * `lockFileMaintenance` is MANAGER-scoped: flatten.ts gates it on
+//     `manager.supportsLockFileMaintenance`. The `custom.regex` manager
+//     exports neither that flag nor an `updateArtifacts`
+//     (modules/manager/custom/regex/index.ts), so the option is silently
+//     IGNORED for it — no branch, no error, no PR.
+//   * The native `nix` manager does support it, but only over
+//     `lockFileNames = ['flake.lock']` (modules/manager/nix/index.ts) — never
+//     `devenv.lock`, which is devenv's own lock format, and compass has no
+//     root flake.nix for it to anchor on either.
+//   * And postUpgradeTasks do NOT run on lockFileMaintenance branches at all:
+//     they are filtered off them
+//     (workers/repository/update/branch/execute-post-upgrade-commands.ts:387-400)
+//     because a maintenance branch calls `updateArtifacts()` directly. So even
+//     a manager that supported maintenance could not carry this relock.
+//
+// A NORMAL digest upgrade DOES carry postUpgradeTasks. So the only mechanism
+// that works is the repo's own existing pattern (the devenv-nixpkgs channel
+// lockstep, refresh-devenv-nixpkgs.ts): a `custom.regex` manager surfaces the
+// fork rev as a git-refs digest so Renovate opens a reviewable branch that
+// rewrites the rev string, and this task — on that branch — makes the lock
+// genuinely consistent:
+//
+//   1. Self-gate — exit 0 unless a devenv lock differs from the base branch,
+//      so it's a cheap no-op on every unrelated Renovate branch (mirrors
+//      refresh-devenv-nixpkgs.ts's devenv.lock gate and
+//      refresh-go-overlay.ts's go.nix gate).
+//   2. Scope — decide WHICH lock the branch touched (root vs agent-image) and
+//      relock in that lock's own directory. devenv resolves
+//      devenv.yaml/devenv.lock relative to its cwd, so the cwd IS the scope
+//      selector. A two-lock branch fails loud: each rule's `fileFilters` names
+//      exactly ONE lock, so Renovate would commit one relock and silently drop
+//      the other.
+//   3. Relock — `devenv update devenv` re-resolves the fork input to its
+//      current `main` HEAD and rewrites the WHOLE lock (narHash + lastModified
+//      + the fork's transitive nodes), not just the rev the regex bumped. That
+//      whole-lock currency is the point: a rev-only rewrite leaves a narHash
+//      that does not match the rev it sits beside. Networked, but light: it
+//      re-locks inputs, it does NOT build the shell or the image.
+//
+// Design: docs/designs/repo/compass-renovate-migration.md (§T7), RD-1.
+//
+// Invoked by BOTH devenv-fork packageRules' postUpgradeTasks (config.json5) as
+// `bun tools/renovate/refresh-devenv-lock.ts` — one command string, so ONE
+// allowlist entry in bot-config.json5 covers both rules. Requires `devenv` +
+// `bun` + network on the runner PATH (the Renovate workflow builds the devenv
+// CLI from the root lock's own devenv node; there is no ambient devenv on
+// compass CI) and a writable HOME (bot-config `customEnvVariables.HOME`, which
+// devenv needs for its state dir).
+//
+// Exit codes:
+//   0 - the changed lock was relocked (or a no-op branch: neither lock differs
+//       from base).
+//   1 - a step failed (the relock itself, a lock-shape change, a relock that
+//       wrote nothing, or an unexpected two-lock branch) — fail loud, never
+//       ship a half-relocked lock.
+
+import { readFileSync } from "node:fs";
+import { $ } from "bun";
+import {
+	changedDevenvLock,
+	DEVENV_LOCK_PATHS,
+	DEVENV_LOCK_SCOPES,
+	devenvForkLockedRev,
+} from "./refresh-devenv-lock.core.ts";
+
+// The devenv input name, identical in both devenv.yaml files
+// (`inputs.devenv.url = github:RigelBuild/devenv`) — the input this task
+// re-resolves. 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 fork advance the branch is about.
+const DEVENV_INPUT = "devenv";
+
+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 a devenv lock changing vs the base branch. ──
+	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).
+	let baseRef = baseBranch;
+	if (
+		(
+			await $`git rev-parse --verify -q ${`origin/${baseBranch}`}`
+				.nothrow()
+				.quiet()
+		).exitCode === 0
+	) {
+		baseRef = `origin/${baseBranch}`;
+	}
+	const changedPaths = (
+		await $`git diff --name-only ${baseRef} -- ${DEVENV_LOCK_PATHS}`.text()
+	)
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0);
+
+	// ── Step 2: which lock? (throws loudly on a two-lock branch) ──
+	const scope = changedDevenvLock(changedPaths);
+	if (scope === null) {
+		console.log(
+			`refresh-devenv-lock: no devenv lock differs from ${baseRef}; nothing to do.`,
+		);
+		return 0;
+	}
+	const { lock, cwd } = DEVENV_LOCK_SCOPES[scope];
+
+	// ── Step 3: relock that scope at the fork's current HEAD. ──
+	// The regex update moved only the rev string, leaving the lock's narHash /
+	// lastModified (and the fork's transitive nodes) describing the OLD rev.
+	// `devenv update devenv`, run in this scope's directory, re-resolves the
+	// input and rewrites the whole lock consistently. Fail loud — a
+	// half-relocked lock must never ship.
+	const before = readFileSync(lock, "utf8");
+	console.log(
+		`refresh-devenv-lock: ${lock} changed vs ${baseRef}; relocking the ` +
+			`'${DEVENV_INPUT}' input in ${cwd}/ (was ${devenvForkLockedRev(before)}) ...`,
+	);
+	await $`devenv update ${DEVENV_INPUT}`.cwd(cwd);
+
+	const after = readFileSync(lock, "utf8");
+	// A relock that wrote NOTHING is the silent half-relock this task exists to
+	// prevent: 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 `devenv update` did not actually relock.
+	if (after === before) {
+		throw new Error(
+			`refresh-devenv-lock: \`devenv update ${DEVENV_INPUT}\` left ${lock} byte-identical — ` +
+				"the regex-bumped rev still sits beside the base lock's narHash. Refusing to ship a " +
+				"half-relocked lock.",
+		);
+	}
+	// Shape guard: the relocked file must still be a devenv lock pinning a
+	// 40-hex fork rev (throws otherwise).
+	console.log(
+		`refresh-devenv-lock: ${lock} relocked — '${DEVENV_INPUT}' now at ${devenvForkLockedRev(after)}. done.`,
+	);
+	return 0;
+}
+
+process.exit(await main());

From 4b9250759058e7f2ac4260ee1e7479b34db47cb6 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Fri, 4 Sep 2026 15:30:31 -0400
Subject: [PATCH 2/3] =?UTF-8?q?fix(renovate):=20apply=20T7=20review=20find?=
 =?UTF-8?q?ings=20=E2=80=94=20scope-correct=20devenv=20relock=20+=20accura?=
 =?UTF-8?q?te=20fail-loud=20(RIG-2815)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-1 review of PR #865 returned 2 high + 4 medium + 4 low. This additive
commit dispositions them; the structural H1 gap is filed as RIG-3253.

H2 (high) — the agent-image relock ran under the ROOT lock's devenv CLI
(renovate.yml provisions one PATH devenv from devenv.lock). refresh-devenv-lock.ts
now self-provisions the scope-correct devenv: `const src = flakeref(devenvSource(before))`
then `nix run ${src} -- update devenv` in the scope dir, reusing devenvSource/flakeref
from tools/toolchain/devenv-cli/core.ts (mirrors ci.yml:2058-2059). Each lock is now
written by the devenv version IT pins — the two revs differ by design (RD-1).

H1 (high) — the "fail-loud refuses to ship" comments/messages overclaimed. Verified
against renovate@44.46.2: a non-zero postUpgradeTask exit does NOT abort the branch
(execute-post-upgrade-commands.js:112-117 → artifactErrors; branch/index.js:408-417
reaches MANAGER_LOCKFILE_ERROR only in the releaseTimestamp arm, absent for a git-refs
digest; prepareCommit reset --hard re-writes the in-memory rev-bump). Corrected every
comment/message to state the real effect — a red renovate/artifacts status — and that
the fail-closed guarantee is that status + mandatory human review (no automerge). Throws
kept. Making renovate/artifacts a required check / adding a devenv-fork consistency CI
gate is the family-wide structural fix, filed as RIG-3253.

M1 — escape the interior slash in the agent-image managerFilePattern; pin the literal
in config.test.ts. M2 — loud named failure when neither origin/<base> nor <base>
resolves, instead of a raw git diff error; + fallback-direction and unresolvable-base
tests. M3 — nix test stub gates the lock write on the post-`--` args being exactly
`update devenv`; + fail-relock and corrupt-relock sentinel tests. M4 — correct the
minimumReleaseAge:null justification (mechanically inapplicable to a git-refs digest;
compensating control is human review). L1 isolation-chain comment; L2 readonly
DEVENV_LOCK_PATHS; L3 hoist beforeRev out of the log template.

moon run renovate:typecheck renovate:test → 152 pass / 0 fail (4 new tests). Biome
clean on touched files (2 pre-existing config.test.ts warnings, identical on main).
---
 tools/renovate/config.json5                |  36 ++-
 tools/renovate/config.test.ts              |  11 +-
 tools/renovate/refresh-devenv-lock.core.ts |  23 +-
 tools/renovate/refresh-devenv-lock.test.ts | 256 +++++++++++++++++----
 tools/renovate/refresh-devenv-lock.ts      | 118 +++++++---
 5 files changed, 356 insertions(+), 88 deletions(-)

diff --git a/tools/renovate/config.json5 b/tools/renovate/config.json5
index f9ab2216..374b8c6b 100644
--- a/tools/renovate/config.json5
+++ b/tools/renovate/config.json5
@@ -240,7 +240,10 @@
       // same-named sibling. The lockFileMaintenance-is-unimplementable
       // reasoning on the root manager above applies verbatim here.
       customType: "regex",
-      managerFilePatterns: ["/^agent-image/devenv\\.lock$/"],
+      // The interior slash is escaped so the whole value reads unambiguously as
+      // a `/…/`-delimited regex (behaviourally identical under Renovate's
+      // parseRegexMatch; config.test.ts pins the literal).
+      managerFilePatterns: ["/^agent-image\\/devenv\\.lock$/"],
       matchStrings: [
         "\"repo\": \"devenv\",\\s*\"rev\": \"(?<currentDigest>[a-f0-9]{40})\"",
       ],
@@ -650,9 +653,11 @@
       // exactly ONE branch-mode task per branch, so a dep that never shares a
       // branch owns that single slot. It is also what keeps the two locks on
       // INDEPENDENT cadences per RD-1 (unify the source, do NOT reconcile the
-      // locks): two groupNames, two branches, two PRs. The rollup can't capture
-      // this dep regardless — its update type is `digest` and the rollup admits
-      // only patch/minor.
+      // locks): two groupNames, two branches, two PRs. The isolation chain is
+      // groupName -> branchTopic -> branchName, so two distinct groupNames
+      // yield two distinct branch names (no need to re-derive it). The rollup
+      // can't capture this dep regardless — its update type is `digest` and the
+      // rollup admits only patch/minor.
       matchManagers: ["custom.regex"],
       matchDepNames: ["RigelBuild/devenv"],
       groupName: "devenv fork (root)",
@@ -668,14 +673,18 @@
       // cooldown treats it as permanently `pending` and the digest sits on the
       // dashboard forever with zero PRs cut (the RIG-1220 silent-no-updates
       // shape). Disable the cooldown for THIS rule only — SAME reason as the
-      // devenv-nixpkgs rule above; the window exists for the compromised-
-      // registry-release risk, which does not apply to our own fork.
+      // devenv-nixpkgs rule above. The cooldown is mechanically INAPPLICABLE to
+      // a git-refs digest (there is no release timestamp to age), so nulling it
+      // is not a risk judgement about the fork: the compensating control is the
+      // MANDATORY human review of the PR before merge (no automerge is
+      // configured — see the top of this file).
       minimumReleaseAge: null,
       // ── The relock task. ──
       // The regex update rewrites ONLY the rev string, leaving narHash /
       // lastModified / the fork's transitive nodes describing the OLD rev. This
-      // task runs `devenv update devenv` in the repo root to rewrite the whole
-      // lock consistently at the fork's current HEAD.
+      // task runs `nix run <the lock's own fork flakeref> -- update devenv` in
+      // the repo root to rewrite the whole lock consistently at the fork's
+      // current HEAD.
       //
       // This pairing — regex digest + postUpgradeTask — is NOT a workaround to
       // be simplified away: `lockFileMaintenance` cannot do this job. See the
@@ -719,10 +728,15 @@
       // (RD-1: unify the source, do NOT reconcile the locks) AND guarantees the
       // two branch-mode relock tasks never contend for one branch's single
       // task slot. Same command as the root rule — the script decides which
-      // lock to relock from the branch diff and runs `devenv update devenv` in
-      // agent-image/ for this one — so one allowlist entry covers both.
+      // lock to relock from the branch diff and, for this one, runs
+      // `nix run <agent-image/devenv.lock's OWN fork flakeref> -- update devenv`
+      // in agent-image/ (so this lock is written by the devenv version IT pins,
+      // never the root lock's) — so one allowlist entry covers both.
       // `minimumReleaseAge: null` for the same git-refs-carries-no-release-age
-      // reason, and the same lockFileMaintenance-is-unimplementable argument
+      // reason: the cooldown is mechanically inapplicable to a git-refs digest
+      // (no release timestamp to age), and the compensating control is the
+      // mandatory human review of the PR before merge (no automerge is
+      // configured). The same lockFileMaintenance-is-unimplementable argument
       // (see the manager) applies verbatim.
       matchManagers: ["custom.regex"],
       matchDepNames: ["RigelBuild/devenv-agent-image"],
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index 6c6c52d0..91797db6 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -585,18 +585,21 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 		depName: string;
 		lock: string;
 		groupName: string;
+		patternLiteral: string;
 	}[] = [
 		{
 			label: "root",
 			depName: "RigelBuild/devenv",
 			lock: "devenv.lock",
 			groupName: "devenv fork (root)",
+			patternLiteral: "/^devenv\\.lock$/",
 		},
 		{
 			label: "agent-image",
 			depName: "RigelBuild/devenv-agent-image",
 			lock: "agent-image/devenv.lock",
 			groupName: "devenv fork (agent-image)",
+			patternLiteral: "/^agent-image\\/devenv\\.lock$/",
 		},
 	];
 	const managerFor = (depName: string) =>
@@ -606,7 +609,7 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 
 	test.each(forkScopes)(
 		"declares a git-refs regex manager for the $label lock's fork rev",
-		({ depName, lock }) => {
+		({ depName, lock, patternLiteral }) => {
 			const manager = managerFor(depName);
 			expect(manager).toBeDefined();
 			expect(manager?.customType).toBe("regex");
@@ -624,6 +627,12 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 			// pattern would make the root manager extract from the agent-image lock
 			// too (or vice versa), collapsing the two independent scopes into one
 			// dep with two files and two conflicting digests.
+			//
+			// Pin the LITERAL first, then re-parse it behaviourally below. The
+			// literal assertion is what makes a Renovate delimiter-semantics drift
+			// (e.g. how an unescaped interior `/` is read) fail as a changed literal
+			// rather than silently changing what the re-parse below is testing.
+			expect(manager?.managerFilePatterns).toEqual([patternLiteral]);
 			const pattern = manager?.managerFilePatterns?.[0];
 			const delimited = /^\/(.*)\/$/.exec(pattern as string);
 			expect(delimited).not.toBeNull();
diff --git a/tools/renovate/refresh-devenv-lock.core.ts b/tools/renovate/refresh-devenv-lock.core.ts
index 1fc30d11..218b7d36 100644
--- a/tools/renovate/refresh-devenv-lock.core.ts
+++ b/tools/renovate/refresh-devenv-lock.core.ts
@@ -7,8 +7,8 @@
 // the packageRule's `fileFilters` would then silently drop the write (it is an
 // INCLUDE allowlist naming exactly one lock), shipping a PR whose rev bump was
 // never followed by a real relock. The entry point owns the shell-outs (the
-// base diff, `devenv update devenv`); this file owns the decisions. NO
-// shell-outs, NO fs beyond text passed in.
+// base diff, the `nix run <fork flakeref> -- update devenv` relock); this file
+// owns the decisions. NO shell-outs, NO fs beyond text passed in.
 
 /**
  * The two independently-locked devenv scopes in this repo. RD-1 unifies the
@@ -34,8 +34,12 @@ export const DEVENV_LOCK_SCOPES: Record<
 	"agent-image": { lock: "agent-image/devenv.lock", cwd: "agent-image" },
 };
 
-/** Every scope's lock path, in scope order — the git-diff pathspec. */
-export const DEVENV_LOCK_PATHS: string[] = Object.values(
+/**
+ * Every scope's lock path, in scope order — the git-diff pathspec. `readonly`
+ * for symmetry with the `readonly lock`/`readonly cwd` fields above; it still
+ * spreads into a `$`-template pathspec fine.
+ */
+export const DEVENV_LOCK_PATHS: readonly string[] = Object.values(
 	DEVENV_LOCK_SCOPES,
 ).map((s) => s.lock);
 
@@ -51,10 +55,13 @@ export const DEVENV_LOCK_PATHS: string[] = Object.values(
  *   relock.
  * - BOTH locks changed → throws. The two rules carry distinct groupNames
  *   precisely so they never share a branch, so this shape means an assumption
- *   broke. Relocking both would be worse than useless: each rule's
+ *   broke. Relocking either one would be worse than useless: each rule's
  *   `fileFilters` names ONE lock, so Renovate would commit one relock and
  *   silently discard the other — a PR that bumped a rev without relocking it.
- *   Fail loud instead.
+ *   Exit non-zero instead. That exit does NOT abort the branch (Renovate
+ *   commits the regex bump regardless); it reds the `renovate/artifacts`
+ *   status, and the human review gate is what stops the merge. See the
+ *   entry point's "what a non-zero exit actually buys" note.
  *
  * Paths are compared exactly (repo-root-relative, as `git diff --name-only`
  * emits them), so an unrelated `foo/devenv.lock` can never be mistaken for
@@ -72,7 +79,9 @@ export function changedDevenvLock(
 				`(${changed.map((s) => DEVENV_LOCK_SCOPES[s].lock).join(", ")}) — each packageRule's ` +
 				"fileFilters names exactly ONE lock, so a two-lock branch would commit one relock and " +
 				"silently drop the other. The two rules carry distinct groupNames so they never share a " +
-				"branch; this shape means that invariant broke.",
+				"branch; this shape means that invariant broke. Exiting non-zero reds the " +
+				"`renovate/artifacts` status — it does not abort the branch — so the mandatory human " +
+				"review of the PR is what keeps this shape from merging.",
 		);
 	}
 	return changed[0] ?? null;
diff --git a/tools/renovate/refresh-devenv-lock.test.ts b/tools/renovate/refresh-devenv-lock.test.ts
index 2f298915..71db2f4b 100644
--- a/tools/renovate/refresh-devenv-lock.test.ts
+++ b/tools/renovate/refresh-devenv-lock.test.ts
@@ -8,26 +8,42 @@ import { $ } from "bun";
 //
 // The pure decisions (which lock changed, the fork-rev read) are unit-tested in
 // refresh-devenv-lock.core.test.ts. This drives the SHIPPED entry point end to
-// end inside a throwaway git repo with a stub `devenv` on PATH, so the step
+// end inside a throwaway git repo with a stub `nix` on PATH, so the step
 // SEQUENCING is exercised offline + deterministically: self-gate → pick the
-// scope → relock in THAT scope's directory → verify the lock actually moved.
-// The real `devenv update devenv` runs for real against the workflow-built
-// devenv CLI on the PR's own branch; here it is stubbed so the failure mode
-// under test is the script's own control flow, not the network.
+// scope → relock in THAT scope's directory, under THAT scope's own devenv →
+// verify the lock actually moved. The real relock
+// (`nix run github:RigelBuild/devenv/<rev>#devenv -- update devenv`) runs for
+// real on the PR's own branch; here `nix` is stubbed so the failure mode under
+// test is the script's own control flow, not the network.
 //
-// The load-bearing assertion is the CWD one: the stub records the directory it
-// was invoked from, because relocking in the wrong directory would rewrite the
-// sibling scope's lock while the rule's one-lock `fileFilters` names this one —
-// so Renovate would commit nothing and the rev bump would ship unrelocked. A
-// cwd-agnostic stub would pass that bug green.
+// Two assertions are load-bearing:
+//   * the CWD one — the stub records the directory it was invoked from, because
+//     relocking in the wrong directory would rewrite the sibling scope's lock
+//     while the rule's one-lock `fileFilters` names this one, so Renovate would
+//     commit nothing and the rev bump would ship unrelocked; and
+//   * the FLAKEREF one — the stub records its full argv, and the rev inside the
+//     flakeref must be the CHANGED scope's OWN bumped rev. The script
+//     self-provisions the devenv CLI from the lock it is about to relock, so
+//     each scope is written by the devenv version IT pins; an ambient/PATH
+//     devenv would relock agent-image under the ROOT lock's devenv (the two
+//     revs differ by design — RD-1 unifies the source, not the locks).
+// A cwd-agnostic or argv-agnostic stub would pass both bugs green.
 
 // 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.
+// a re-implementation — together with the two modules it imports.
 const SCRIPT_REL = "tools/renovate/refresh-devenv-lock.ts";
 const CORE_REL = "tools/renovate/refresh-devenv-lock.core.ts";
+const DEVENV_CLI_CORE_REL = "tools/toolchain/devenv-cli/core.ts";
 const REAL_SCRIPT = join(import.meta.dir, "refresh-devenv-lock.ts");
 const REAL_CORE = join(import.meta.dir, "refresh-devenv-lock.core.ts");
+const REAL_DEVENV_CLI_CORE = join(
+	import.meta.dir,
+	"..",
+	"toolchain",
+	"devenv-cli",
+	"core.ts",
+);
 
 const ROOT_LOCK_REL = "devenv.lock";
 const AGENT_LOCK_REL = "agent-image/devenv.lock";
@@ -84,20 +100,71 @@ function devenvLock(rev: string, narHash: string): string {
 	)}\n`;
 }
 
-// Stub `devenv`: on `devenv update devenv`, record the cwd it ran in and
-// rewrite ./devenv.lock (relative to that cwd — exactly how the real devenv
-// resolves the lock) to the RELOCKED rev with a fresh narHash, simulating a
-// real re-resolution. `.force-noop-relock` in the repo root instead makes it
-// exit 0 having written NOTHING, modelling a relock that did not move — the
-// half-relock the script must refuse. Offline.
-const STUB_DEVENV = `#!/usr/bin/env bash
+// A lock whose devenv node carries a SHORT (non-40-hex) rev — what a corrupt
+// relock write looks like to the script's post-relock shape guard.
+const CORRUPT_LOCK = JSON.stringify({
+	nodes: {
+		devenv: {
+			locked: {
+				lastModified: 2,
+				narHash: "sha256-DDDD",
+				owner: "RigelBuild",
+				repo: "devenv",
+				rev: "abc123",
+				type: "github",
+			},
+		},
+		root: { inputs: { devenv: "devenv" } },
+	},
+	root: "root",
+	version: 7,
+});
+
+// Stub `nix`: the script relocks via
+// `nix run github:RigelBuild/devenv/<rev>#devenv -- update devenv`, so in bash
+// $1=`run`, $2=the flakeref, then `--`, then the devenv subcommand. On that
+// shape the stub records the cwd it ran in AND its full argv (so the tests can
+// assert both the scope directory and WHICH devenv the script provisioned),
+// then rewrites ./devenv.lock (relative to that cwd — exactly how the real
+// devenv resolves the lock) to the RELOCKED rev with a fresh narHash,
+// simulating a real re-resolution.
+//
+// Sentinel files in the repo root model the failure modes, so each is exercised
+// through the script's REAL control flow rather than a mocked seam:
+//   .force-noop-relock    → exit 0 having written NOTHING (a relock that did
+//                           not move — the half-relock the script must surface).
+//   .force-fail-relock    → exit 1 (the relock itself failed).
+//   .force-corrupt-relock → write a lock with a short rev (a lock-shape drift
+//                           the post-relock guard must catch).
+// And the write is gated on the post-`--` args being exactly `update devenv`:
+// any OTHER input name writes nothing, so a wrong-input regression fails
+// through BEHAVIOUR (the byte-identical guard fires), not merely an argv-log
+// assertion. Offline throughout.
+const STUB_NIX = `#!/usr/bin/env bash
 set -euo pipefail
-if [ "\${1:-}" = "update" ]; then
+if [ "\${1:-}" = "run" ]; then
   echo "$PWD" >> "$REPO_ROOT/.devenv-update-cwds"
   echo "$@" >> "$REPO_ROOT/.devenv-update-args"
   if [ -f "$REPO_ROOT/.force-noop-relock" ]; then
     exit 0
   fi
+  if [ -f "$REPO_ROOT/.force-fail-relock" ]; then
+    echo "stub nix: forced relock failure" >&2
+    exit 1
+  fi
+  # Drop \`run\` + the flakeref, then the \`--\` separator: what remains is the
+  # devenv subcommand the script asked for.
+  shift 2
+  if [ "\${1:-}" = "--" ]; then
+    shift
+  fi
+  if [ "\${1:-}" != "update" ] || [ "\${2:-}" != "devenv" ]; then
+    exit 0
+  fi
+  if [ -f "$REPO_ROOT/.force-corrupt-relock" ]; then
+    printf '%s' '${CORRUPT_LOCK}' > devenv.lock
+    exit 0
+  fi
   cat > devenv.lock <<'LOCK'
 ${devenvLock(RELOCKED_REV, "CCCC")}
 LOCK
@@ -108,18 +175,26 @@ exit 0
 async function buildRepo(): Promise<string> {
 	const repo = await mkdtemp(join(tmpdir(), "rig2815-"));
 	await mkdir(join(repo, "tools", "renovate"), { recursive: true });
+	await mkdir(join(repo, "tools", "toolchain", "devenv-cli"), {
+		recursive: true,
+	});
 	await mkdir(join(repo, "agent-image"), { recursive: true });
 	await mkdir(join(repo, "stubbin"), { recursive: true });
 
-	// Ship the REAL script + its core, so the SHIPPED file runs unmodified.
+	// Ship the REAL script + the modules it imports, so the SHIPPED file runs
+	// unmodified (including the devenv-cli resolvers it reuses for the flakeref).
 	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, DEVENV_CLI_CORE_REL),
+		await readFile(REAL_DEVENV_CLI_CORE, "utf8"),
+	);
 
 	await Bun.write(join(repo, ROOT_LOCK_REL), devenvLock(BASE_REV, "AAAA"));
 	await Bun.write(join(repo, AGENT_LOCK_REL), devenvLock(BASE_REV, "BBBB"));
 
-	await Bun.write(join(repo, "stubbin", "devenv"), STUB_DEVENV);
-	await chmod(join(repo, "stubbin", "devenv"), 0o755);
+	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();
@@ -140,21 +215,32 @@ async function applyRegexBump(repo: string, lockRel: string, narHash: string) {
 }
 
 // Run the shipped script as Renovate does: `bun tools/renovate/…ts`, cwd = repo
-// root, the stub first on PATH so no real devenv/network is touched. The real
-// `bun` runs the script itself; git stays the real binary.
-async function runRefresh(repo: string) {
+// root, the stub 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, baseBranch = "main") {
 	return await $`bun ${SCRIPT_REL}`
 		.cwd(repo)
 		.env({
 			...HERMETIC_ENV,
 			PATH: `${join(repo, "stubbin")}:${process.env.PATH}`,
-			RENOVATE_BASE_BRANCH: "main",
+			RENOVATE_BASE_BRANCH: baseBranch,
 			REPO_ROOT: repo,
 		})
 		.quiet()
 		.nothrow();
 }
 
+// The flakeref rev the script provisioned its devenv CLI from, read out of the
+// stub's argv log: `run github:<owner>/<repo>/<rev>#devenv -- update devenv`.
+async function provisionedRev(repo: string): Promise<string> {
+	const args = (
+		await readFile(join(repo, ".devenv-update-args"), "utf8")
+	).trim();
+	const rev = /^run github:RigelBuild\/devenv\/([a-f0-9]+)#devenv /.exec(args);
+	expect(rev).not.toBeNull();
+	return rev?.[1] as string;
+}
+
 describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 	let repo: string;
 	beforeEach(async () => {
@@ -171,7 +257,7 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 		const res = await runRefresh(repo);
 		expect(res.exitCode).toBe(0);
 		expect(res.stdout.toString()).toContain("nothing to do");
-		// devenv was never invoked.
+		// The relock was never invoked.
 		expect(await Bun.file(join(repo, ".devenv-update-cwds")).exists()).toBe(
 			false,
 		);
@@ -180,10 +266,11 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 		);
 	});
 
-	// The end-to-end happy path per scope, and the CWD assertion that is the
+	// The end-to-end happy path per scope, and the two assertions that are the
 	// whole point of two scopes: the relock must run in the changed lock's OWN
-	// directory (devenv resolves the lock relative to cwd), and must leave the
-	// SIBLING lock untouched — the rule's fileFilters admits only the one.
+	// directory (devenv resolves the lock relative to cwd) under the devenv that
+	// same lock pins, and must leave the SIBLING lock untouched — the rule's
+	// fileFilters admits only the one.
 	test.each([
 		{ label: "root", lockRel: ROOT_LOCK_REL, dir: ".", narHash: "AAAA" },
 		{
@@ -193,7 +280,7 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 			narHash: "BBBB",
 		},
 	])(
-		"relocks the $label lock in its own directory, leaving the sibling alone",
+		"relocks the $label lock in its own directory, under its own devenv, leaving the sibling alone",
 		async ({ lockRel, dir, narHash }) => {
 			await applyRegexBump(repo, lockRel, narHash);
 
@@ -208,9 +295,9 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 			expect(relocked).not.toContain(BUMPED_REV);
 			expect(res.stdout.toString()).toContain(`now at ${RELOCKED_REV}`);
 
-			// It ran `devenv update devenv` EXACTLY ONCE, in this scope's directory.
-			// A wrong cwd would rewrite the sibling's lock (which the rule cannot
-			// commit) and leave this one rev-bumped-but-unrelocked.
+			// It relocked EXACTLY ONCE, in this scope's directory. A wrong cwd would
+			// rewrite the sibling's lock (which the rule cannot commit) and leave
+			// this one rev-bumped-but-unrelocked.
 			const cwds = (await readFile(join(repo, ".devenv-update-cwds"), "utf8"))
 				.trim()
 				.split("\n");
@@ -221,7 +308,14 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 			).trim();
 			// The SINGLE named input, not a bare `devenv update` (which would
 			// re-lock every input and bloat the PR's diff).
-			expect(args).toBe("update devenv");
+			expect(args.endsWith(" -- update devenv")).toBe(true);
+
+			// H2 regression guard: the devenv CLI the script provisioned came from
+			// THIS scope's own lock — its flakeref rev is this lock's bumped rev,
+			// the fork HEAD the branch is moving to. Running under an ambient/PATH
+			// devenv (or the sibling scope's) would put a different rev here, which
+			// is exactly the cross-scope coupling this shape removes.
+			expect(await provisionedRev(repo)).toBe(BUMPED_REV);
 
 			// The sibling scope is untouched — the two locks are independent (RD-1).
 			const sibling =
@@ -232,21 +326,63 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 
 	// Fail-loud: a relock that wrote NOTHING leaves the regex-bumped rev beside
 	// the base lock's narHash — the silent half-relock this task exists to
-	// prevent. It must die non-zero in-branch rather than ship it.
-	test("fails loud (exit≠0) when the relock leaves the lock byte-identical", async () => {
+	// surface. The non-zero exit does NOT abort the Renovate branch (Renovate
+	// catches a postUpgradeTask failure and still commits the regex bump); it
+	// reds the `renovate/artifacts` status, and the human review gate is what
+	// stops the merge. So the resulting on-disk lock IS the unrepaired
+	// rev-bumped-but-not-relocked state — asserted below so the real contract is
+	// pinned, not the imagined "refuses to ship" one.
+	test("exits non-zero when the relock leaves the lock byte-identical, and the lock stays rev-bumped-but-unrelocked", async () => {
 		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
 		await Bun.write(join(repo, ".force-noop-relock"), "");
 
 		const res = await runRefresh(repo);
 		expect(res.exitCode).not.toBe(0);
 		expect(res.stderr.toString()).toContain("byte-identical");
+
+		// The rev moved (the regex bump) but the narHash did NOT — nothing on disk
+		// was repaired, and nothing could be: Renovate re-writes the file from its
+		// in-memory updatedPackageFiles after a reset --hard anyway.
+		const lock = await readFile(join(repo, ROOT_LOCK_REL), "utf8");
+		expect(lock).toContain(BUMPED_REV);
+		expect(lock).toContain("sha256-AAAA");
+		expect(lock).not.toContain(RELOCKED_REV);
+	});
+
+	// Fail-loud: the relock command itself failed. The script must surface that
+	// non-zero and NOT leave a bogus/half-written lock behind.
+	test("exits non-zero when the relock command fails, leaving no bogus lock", async () => {
+		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
+		await Bun.write(join(repo, ".force-fail-relock"), "");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).not.toBe(0);
+		// The lock is exactly the regex-bumped input the task was handed — the
+		// failed relock wrote nothing.
+		expect(await readFile(join(repo, ROOT_LOCK_REL), "utf8")).toBe(
+			devenvLock(BUMPED_REV, "AAAA"),
+		);
+	});
+
+	// Fail-loud: the relock wrote a lock whose devenv node no longer carries a
+	// 40-hex fork rev (a devenv lock-format drift). The post-relock shape guard
+	// must catch it rather than reporting a bogus "now at …".
+	test("exits non-zero when the relock writes a lock with no 40-hex fork rev", async () => {
+		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
+		await Bun.write(join(repo, ".force-corrupt-relock"), "");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).not.toBe(0);
+		expect(res.stderr.toString()).toContain("devenv fork rev");
+		expect(res.stdout.toString()).not.toContain("now at");
 	});
 
 	// Fail-loud: BOTH locks changed. The two rules carry distinct groupNames so
 	// they never share a branch; if that invariant ever breaks, relocking either
 	// one is wrong — each rule's fileFilters names ONE lock, so Renovate would
-	// commit one relock and silently drop the other. Die instead of guessing.
-	test("fails loud (exit≠0) when BOTH locks changed on one branch", async () => {
+	// commit one relock and silently drop the other. Exit non-zero instead of
+	// guessing.
+	test("exits non-zero when BOTH locks changed on one branch", async () => {
 		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
 		await applyRegexBump(repo, AGENT_LOCK_REL, "BBBB");
 
@@ -258,4 +394,46 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 			false,
 		);
 	});
+
+	// The base-ref fallback DIRECTION: with no `origin/<base>` remote-tracking
+	// ref (a local clone, or a runner that never fetched it), the gate must fall
+	// back to the bare branch name and still decide correctly — not error out
+	// and not silently read "nothing changed".
+	test("falls back to the bare base branch when origin/<base> is absent", async () => {
+		await $`git update-ref -d refs/remotes/origin/main`
+			.cwd(repo)
+			.env(HERMETIC_ENV)
+			.quiet();
+		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+		// The bare ref is what it diffed against…
+		expect(res.stdout.toString()).toContain("changed vs main;");
+		expect(res.stdout.toString()).not.toContain("origin/main");
+		// …and the relock still happened normally.
+		expect(await readFile(join(repo, ROOT_LOCK_REL), "utf8")).toContain(
+			RELOCKED_REV,
+		);
+	});
+
+	// Neither `origin/<base>` nor the bare `<base>` resolves: the changed set is
+	// UNKNOWN, so the script must fail with its OWN named diagnosis rather than
+	// letting a raw `git diff` error surface (and above all never read as
+	// "nothing changed" and skip green).
+	test("fails with a named error when the base ref does not resolve at all", async () => {
+		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
+
+		const res = await runRefresh(repo, "no-such-base");
+		expect(res.exitCode).not.toBe(0);
+		const stderr = res.stderr.toString();
+		expect(stderr).toContain("base ref does not resolve");
+		expect(stderr).toContain("origin/no-such-base");
+		// The named diagnosis, not a raw git error.
+		expect(stderr).not.toContain("unknown revision");
+		// And no relock was attempted on an unknown changed set.
+		expect(await Bun.file(join(repo, ".devenv-update-cwds")).exists()).toBe(
+			false,
+		);
+	});
 });
diff --git a/tools/renovate/refresh-devenv-lock.ts b/tools/renovate/refresh-devenv-lock.ts
index 42c99d60..3fdb1258 100644
--- a/tools/renovate/refresh-devenv-lock.ts
+++ b/tools/renovate/refresh-devenv-lock.ts
@@ -47,32 +47,61 @@
 //      selector. A two-lock branch fails loud: each rule's `fileFilters` names
 //      exactly ONE lock, so Renovate would commit one relock and silently drop
 //      the other.
-//   3. Relock — `devenv update devenv` re-resolves the fork input to its
-//      current `main` HEAD and rewrites the WHOLE lock (narHash + lastModified
-//      + the fork's transitive nodes), not just the rev the regex bumped. That
-//      whole-lock currency is the point: a rev-only rewrite leaves a narHash
-//      that does not match the rev it sits beside. Networked, but light: it
-//      re-locks inputs, it does NOT build the shell or the image.
+//   3. Relock — `nix run <this lock's own fork flakeref> -- update devenv`
+//      re-resolves the fork input to its current `main` HEAD and rewrites the
+//      WHOLE lock (narHash + lastModified + the fork's transitive nodes), not
+//      just the rev the regex bumped. That whole-lock currency is the point: a
+//      rev-only rewrite leaves a narHash that does not match the rev it sits
+//      beside. Networked, but light: it re-locks inputs, it does NOT build the
+//      shell or the image.
 //
 // Design: docs/designs/repo/compass-renovate-migration.md (§T7), RD-1.
 //
 // Invoked by BOTH devenv-fork packageRules' postUpgradeTasks (config.json5) as
 // `bun tools/renovate/refresh-devenv-lock.ts` — one command string, so ONE
-// allowlist entry in bot-config.json5 covers both rules. Requires `devenv` +
-// `bun` + network on the runner PATH (the Renovate workflow builds the devenv
-// CLI from the root lock's own devenv node; there is no ambient devenv on
-// compass CI) and a writable HOME (bot-config `customEnvVariables.HOME`, which
-// devenv needs for its state dir).
+// allowlist entry in bot-config.json5 covers both rules. 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 the root scope runs the root lock's devenv and the agent-image
+// scope runs agent-image's — the two revs differ by design under RD-1). That
+// mirrors every other agent-image devenv site in the tree (ci.yml:2058-2059)
+// and is what keeps the writer of a lock identical to the devenv version that
+// lock pins.
 //
 // Exit codes:
 //   0 - the changed lock was relocked (or a no-op branch: neither lock differs
 //       from base).
 //   1 - a step failed (the relock itself, a lock-shape change, a relock that
-//       wrote nothing, or an unexpected two-lock branch) — fail loud, never
-//       ship a half-relocked lock.
+//       wrote nothing, an unresolvable base ref, or an unexpected two-lock
+//       branch).
+//
+// What a non-zero exit actually BUYS — do NOT overclaim it (source-verified
+// against the pinned renovate@44.46.2):
+//   * It does NOT abort the Renovate branch. The failure is caught at
+//     execute-post-upgrade-commands.js:112-117, pushed onto `artifactErrors`,
+//     and execution CONTINUES. branch/index.js:408-417 reaches the
+//     MANAGER_LOCKFILE_ERROR throw only inside its `releaseTimestamp` arm, and
+//     a git-refs digest carries NO release timestamp — so this branch always
+//     falls through to `commitFilesToBranch` and Renovate commits the
+//     regex-bumped lock regardless.
+//   * Nor could the script repair the tree instead: `prepareCommit`
+//     (util/git/index.js:996-1035) does `git reset --hard` + `git clean -fd`
+//     and then RE-WRITES the files from Renovate's in-memory
+//     `updatedPackageFiles` — which is where the regex rev-bump lives. So
+//     nothing a postUpgradeTask does on disk can suppress that bump.
+//   * What the non-zero exit DOES buy is a red `renovate/artifacts` commit
+//     status (`setArtifactErrorStatus`, branch/index.js:452). The fail-CLOSED
+//     guarantee is that status being a required check, plus the PR's mandatory
+//     human review — compass configures NO automerge (config.json5:30).
+// So: fail loud → red `renovate/artifacts` status + the human review gate. The
+// branch is NOT auto-aborted (see the follow-up issue to make
+// `renovate/artifacts` a required check).
 
 import { readFileSync } from "node:fs";
 import { $ } from "bun";
+import { devenvSource, flakeref } from "../toolchain/devenv-cli/core.ts";
 import {
 	changedDevenvLock,
 	DEVENV_LOCK_PATHS,
@@ -96,18 +125,35 @@ async function main(): Promise<number> {
 	process.chdir(repoRoot);
 
 	// ── Step 1: self-gate on a devenv 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-devenv-nixpkgs.ts so the two tasks 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).
-	let baseRef = baseBranch;
-	if (
-		(
-			await $`git rev-parse --verify -q ${`origin/${baseBranch}`}`
-				.nothrow()
-				.quiet()
-		).exitCode === 0
-	) {
-		baseRef = `origin/${baseBranch}`;
+	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 (mirrors ci.yml's "Fail LOUD if the base
+		// ref does not resolve" gate): an unresolvable base means the changed-set
+		// is UNKNOWN, which must never be read as "no lock changed" and skipped
+		// green.
+		throw new Error(
+			`refresh-devenv-lock: base ref does not resolve — neither \`${remoteRef}\` nor ` +
+				`\`${baseBranch}\` names a commit in this repo, so the changed devenv-lock set ` +
+				"cannot be computed. Refusing to guess (an unresolvable base must not read as " +
+				"'nothing changed').",
+		);
 	}
 	const changedPaths = (
 		await $`git diff --name-only ${baseRef} -- ${DEVENV_LOCK_PATHS}`.text()
@@ -130,25 +176,37 @@ async function main(): Promise<number> {
 	// The regex update moved only the rev string, leaving the lock's narHash /
 	// lastModified (and the fork's transitive nodes) describing the OLD rev.
 	// `devenv update devenv`, run in this scope's directory, re-resolves the
-	// input and rewrites the whole lock consistently. Fail loud — a
-	// half-relocked lock must never ship.
+	// input and rewrites the whole lock consistently.
 	const before = readFileSync(lock, "utf8");
+	// Provision the SCOPE-CORRECT devenv CLI from this lock's OWN (regex-bumped)
+	// content: `before` is what Renovate wrote to disk before this task ran, so
+	// its pinned rev is the fork's target HEAD, and the lock therefore gets
+	// written by the very devenv version it pins. Using an ambient/PATH devenv
+	// instead would relock agent-image under the ROOT lock's devenv (the two
+	// revs differ by design — RD-1 unifies the source, not the locks). 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 the scope already known rather than mid-log-line.
+	const beforeRev = devenvForkLockedRev(before);
 	console.log(
 		`refresh-devenv-lock: ${lock} changed vs ${baseRef}; relocking the ` +
-			`'${DEVENV_INPUT}' input in ${cwd}/ (was ${devenvForkLockedRev(before)}) ...`,
+			`'${DEVENV_INPUT}' input in ${cwd}/ via ${src} (was ${beforeRev}) ...`,
 	);
-	await $`devenv update ${DEVENV_INPUT}`.cwd(cwd);
+	await $`nix run ${src} -- update ${DEVENV_INPUT}`.cwd(cwd);
 
 	const after = readFileSync(lock, "utf8");
 	// A relock that wrote NOTHING is the silent half-relock this task exists to
-	// prevent: the rev the regex bumped would still sit beside the base lock's
+	// 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 `devenv update` did not actually relock.
+	// byte-identical content means the relock did not actually run.
 	if (after === before) {
 		throw new Error(
 			`refresh-devenv-lock: \`devenv update ${DEVENV_INPUT}\` left ${lock} byte-identical — ` +
-				"the regex-bumped rev still sits beside the base lock's narHash. Refusing to ship a " +
-				"half-relocked lock.",
+				"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 be a devenv lock pinning a

From ec367d6812b69c904629a3e979f17aecb40bbd0f Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Fri, 4 Sep 2026 17:08:41 -0400
Subject: [PATCH 3/3] =?UTF-8?q?fix(renovate):=20apply=20T7=20R2=20review?=
 =?UTF-8?q?=20findings=20=E2=80=94=20relock=20timeout=20ceiling=20+=20subs?=
 =?UTF-8?q?tituter=20coupling=20guard=20(RIG-2815)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-2 review of the R1 fixes (0 high / 2 medium / 3 low) surfaced two
runtime-surface gaps introduced by the R1 relock rework, plus follow-on
review of these fixes (R3) hardened them:

- executionTimeout: 45 (bot-config.json5, globalOnly) so the fork-devenv
  relock — which cold-builds the fork `#devenv` from source, no binary
  cache — is not killed at Renovate's 15-min child-process default, which
  would leave the regex rev bump committed but the lock unrelocked. Comment
  states the knob's GLOBAL scope (raises the hang budget for every manager,
  accepted deliberately) and cites the fork's own ~4.5-min ubuntu-latest
  build. Pinned by a config.test.ts assertion (floor >= 30, mutation-killed
  on removal and on a lowered value).

- Substituter-coupling header note on refresh-devenv-lock.ts + a
  config.test.ts guard that renovate.yml's extra_nix_config still names both
  caches and both trusted keys on LIVE (comment-stripped) config lines, so a
  future trim — including a commented-out or narrated-away block — fails the
  test rather than silently wedging the nightly relock.

- Test hardening: a base-ref direction test where both origin/main and a
  stale local main resolve-and-differ (the prior test passed with the arms
  flipped); a mandatory `--` separator in the nix stub; and a matchStrings
  sync guard across the two fork managers.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 tools/renovate/bot-config.json5            | 26 ++++++++
 tools/renovate/config.test.ts              | 72 ++++++++++++++++++++++
 tools/renovate/refresh-devenv-lock.test.ts | 50 +++++++++++++--
 tools/renovate/refresh-devenv-lock.ts      | 12 ++++
 4 files changed, 156 insertions(+), 4 deletions(-)

diff --git a/tools/renovate/bot-config.json5 b/tools/renovate/bot-config.json5
index 2b6005f0..ab0fb6bc 100644
--- a/tools/renovate/bot-config.json5
+++ b/tools/renovate/bot-config.json5
@@ -48,6 +48,32 @@
     HOME: "/tmp/renovate-home",
   },
 
+  // GLOBAL child-process execution ceiling (RIG-2815 review M1). Renovate applies
+  // executionTimeout (config/options; default 15 min) in the shared exec path
+  // (util/exec getRawExecOptions) as the DEFAULT timeout for EVERY child process
+  // it creates — not just this task — so raising it also raises the hang budget
+  // for every other manager's artifact update. Accepted deliberately: the
+  // devenv-fork relock is the binding constraint and a wedged child is otherwise
+  // bounded by the CI job, not this knob. Why the relock needs the headroom: the
+  // relock (refresh-devenv-lock.ts) `nix run`s the fork flakeref read from the
+  // lock it is about to relock, and no fork rev is ever pushed to a binary cache
+  // for its `#devenv` output — the fork's only live CI gate (rigel-ci.yml) is
+  // pull-only by design, and the cache-pushing build.yml is gated to
+  // `github.repository_owner == 'cachix'` so it never runs on the fork. So every
+  // fork rev is a from-source Rust build of the devenv CLI + its closure before
+  // the relock even starts: the fork's own rigel-ci.yml measures `nix build
+  // .#devenv` at a consistent ~4.5 min on ubuntu-latest WITH the devenv
+  // substituter warm; the 15-min default leaves little headroom if a substituter
+  // is cold, degraded, or a rev lands before the fork's cache is populated —
+  // exactly when the from-source Nix-fork closure build dominates. On timeout the
+  // child is killed, the relock never runs, and Renovate still commits the regex
+  // rev bump (a postUpgradeTask exit does not abort the branch), i.e. the exact
+  // rev-bumped-but-unrelocked PR this task exists to prevent, arriving
+  // intermittently and rev-dependently. 45 min covers that tail. config.test.ts
+  // pins this so a default change or accidental removal fails closed rather than
+  // silently restoring the 15-min cliff.
+  executionTimeout: 45,
+
   // Allow ONLY the postUpgradeTasks commands tools/renovate/config.json5 declares.
   // postUpgradeTasks.commands are gated by this global allowlist (a repo config
   // can't self-authorize a command), and the `^…$` anchors pin each entry to
diff --git a/tools/renovate/config.test.ts b/tools/renovate/config.test.ts
index 91797db6..c6df3a45 100644
--- a/tools/renovate/config.test.ts
+++ b/tools/renovate/config.test.ts
@@ -64,6 +64,7 @@ const cfg = config as RenovateConfig;
 const bot = botConfig as {
 	allowedCommands?: string[];
 	customEnvVariables?: Record<string, string>;
+	executionTimeout?: number;
 };
 // tools/renovate/ → repo root is two levels up.
 const repoRoot = join(import.meta.dir, "..", "..");
@@ -749,6 +750,77 @@ describe("tools/renovate devenv fork currency (RIG-2815, RIG-2546 T7)", () => {
 		const groups = forkScopes.map((s) => ruleFor(s.depName)?.groupName);
 		expect(new Set(groups).size).toBe(forkScopes.length);
 	});
+
+	// M1 (RIG-2815 review): the relock `nix run`s the fork flakeref, and the fork
+	// publishes no binary cache, so every fork rev is a from-source devenv build
+	// before the relock runs — measured minutes, plausibly past Renovate's 15-min
+	// default executionTimeout on a cold 2-vCPU runner. A timeout kills the child,
+	// the relock never runs, and Renovate still commits the regex bump (the exact
+	// half-relock this task exists to prevent). Pin the raised ceiling so a
+	// default change or accidental removal fails HERE, not as a nightly relock
+	// silently timing out. globalOnly, so it lives in bot-config.
+	test("bot-config sets an executionTimeout covering a cold fork build", () => {
+		expect(typeof bot.executionTimeout).toBe("number");
+		// Comfortably above the 15-min default; a cold from-source fork build can
+		// exceed 15 min on a hosted runner.
+		expect(bot.executionTimeout).toBeGreaterThanOrEqual(30);
+	});
+
+	// M2 (RIG-2815 review): the relock's `nix run` depends on the runner's
+	// nix.conf naming the devenv + cachix substituters and their trusted keys —
+	// the fork's `#devenv` closure is not on cache.nixos.org and nix ignores the
+	// fork flake's own nixConfig non-interactively, so without these caches the
+	// realise cold-compiles the Nix fork from source and can exhaust the runner.
+	// Nothing in refresh-devenv-lock.ts provides them; renovate.yml's
+	// extra_nix_config does. Assert that block still names both caches + keys so
+	// trimming them there (e.g. once the PATH devenv-cli step is retired) fails a
+	// test rather than wedging the nightly relock. Same fail-closed posture as the
+	// self-pin workflow guard below (which already reads renovate.yml).
+	test("renovate.yml wires the substituters the relock nix run needs", () => {
+		const workflow = readFileSync(
+			join(repoRoot, ".github", "workflows", "renovate.yml"),
+			"utf8",
+		);
+		// Strip YAML comment lines before asserting, mirroring the self-pin
+		// workflow guard below (config.test.ts): a substituter that survives only
+		// in a commented-out or rationale-narrated block still leaves the runner
+		// without it, so the guard must read live config, not prose.
+		const liveConfig = workflow
+			.split("\n")
+			.filter((l) => !/^\s*#/.test(l))
+			.join("\n");
+		// Order-independent: both caches must sit on a LIVE extra-substituters
+		// line, in either order.
+		expect(
+			/^\s*extra-substituters = .*https:\/\/devenv\.cachix\.org/m.test(
+				liveConfig,
+			),
+		).toBe(true);
+		expect(liveConfig).toContain("https://cachix.cachix.org");
+		// Both trusted public keys must accompany their substituters on a live
+		// extra-trusted-public-keys line, or nix rejects the cached paths and
+		// falls back to a from-source build.
+		expect(
+			/^\s*extra-trusted-public-keys = .*devenv\.cachix\.org-1:/m.test(
+				liveConfig,
+			),
+		).toBe(true);
+		expect(liveConfig).toContain("cachix.cachix.org-1:");
+	});
+
+	// L3 (RIG-2815 review): the two fork managers carry the SAME matchStrings
+	// literal (RD-1 forbids reconciling the rules, and JSON5 has no anchor, so the
+	// duplication is deliberate). Nothing else pins that they stay in sync — each
+	// per-manager matchString test reads its own manager — so a one-sided edit
+	// would drift silently. Assert the two share one literal, mirroring the
+	// "same relock command" guard above.
+	test("both fork managers declare the IDENTICAL matchString literal", () => {
+		const literals = forkScopes.map(
+			(s) => managerFor(s.depName)?.matchStrings?.[0],
+		);
+		expect(literals.every((l) => typeof l === "string")).toBe(true);
+		expect(new Set(literals).size).toBe(1);
+	});
 });
 
 describe("tools/renovate go ↔ go-overlay lockstep (RIG-3100)", () => {
diff --git a/tools/renovate/refresh-devenv-lock.test.ts b/tools/renovate/refresh-devenv-lock.test.ts
index 71db2f4b..f1dfc52f 100644
--- a/tools/renovate/refresh-devenv-lock.test.ts
+++ b/tools/renovate/refresh-devenv-lock.test.ts
@@ -152,12 +152,17 @@ if [ "\${1:-}" = "run" ]; then
     echo "stub nix: forced relock failure" >&2
     exit 1
   fi
-  # Drop \`run\` + the flakeref, then the \`--\` separator: what remains is the
-  # devenv subcommand the script asked for.
+  # Drop \`run\` + the flakeref, then REQUIRE the \`--\` separator: real nix needs
+  # it to pass \`update devenv\` through to the devenv binary (without it, nix
+  # parses them as its OWN args). Enforcing it here means an argv missing \`--\`
+  # writes nothing, so a regression that dropped \`--\` from the script's template
+  # fails through BEHAVIOUR (the byte-identical guard fires), not only the
+  # endsWith argv assertion. What remains after the shift is the devenv subcommand.
   shift 2
-  if [ "\${1:-}" = "--" ]; then
-    shift
+  if [ "\${1:-}" != "--" ]; then
+    exit 0
   fi
+  shift
   if [ "\${1:-}" != "update" ] || [ "\${2:-}" != "devenv" ]; then
     exit 0
   fi
@@ -417,6 +422,43 @@ describe("tools/renovate/refresh-devenv-lock.ts relock (RIG-2815)", () => {
 		);
 	});
 
+	// The base-ref fallback DIRECTION under the case that actually exercises it:
+	// BOTH `origin/<base>` and the bare `<base>` resolve, but to DIFFERENT
+	// commits. Production always has both (Renovate fetches origin), and the two
+	// can diverge — a stale local `main` in the runner checkout vs the fetched
+	// `origin/main` the branch is really based on. The gate must diff against the
+	// REMOTE ref (as every sibling refresh script does); diffing the stale local
+	// ref would silently mis-compute the changed set. The `origin absent` test
+	// above cannot see this — with one ref deleted both orderings pick the same
+	// ref — so a flipped order would pass it while breaking here.
+	test("prefers origin/<base> over a stale local <base> when both resolve", async () => {
+		// Renovate wrote the regex bump to the working tree.
+		await applyRegexBump(repo, ROOT_LOCK_REL, "AAAA");
+		// Advance the LOCAL main ref onto a commit that already carries that bump,
+		// leaving origin/main at the baseline. Now both refs resolve but differ:
+		// origin/main (baseline) still sees the lock as changed and must relock; a
+		// stale local main (already bumped) would read "nothing changed" and skip.
+		await $`git add -A`.cwd(repo).env(HERMETIC_ENV).quiet();
+		await $`git commit -q -m stale-local-bump`
+			.cwd(repo)
+			.env(HERMETIC_ENV)
+			.quiet();
+
+		const res = await runRefresh(repo);
+		expect(res.exitCode).toBe(0);
+		// It diffed against the REMOTE ref, saw the lock changed, and relocked —
+		// the behaviour a flipped (bare-first) order would lose (it would read the
+		// already-bumped local main as unchanged and exit green with no relock).
+		expect(res.stdout.toString()).toContain("changed vs origin/main;");
+		expect(res.stdout.toString()).not.toContain("nothing to do");
+		expect(await Bun.file(join(repo, ".devenv-update-cwds")).exists()).toBe(
+			true,
+		);
+		expect(await readFile(join(repo, ROOT_LOCK_REL), "utf8")).toContain(
+			RELOCKED_REV,
+		);
+	});
+
 	// Neither `origin/<base>` nor the bare `<base>` resolves: the changed set is
 	// UNKNOWN, so the script must fail with its OWN named diagnosis rather than
 	// letting a raw `git diff` error surface (and above all never read as
diff --git a/tools/renovate/refresh-devenv-lock.ts b/tools/renovate/refresh-devenv-lock.ts
index 3fdb1258..ab1f2f31 100644
--- a/tools/renovate/refresh-devenv-lock.ts
+++ b/tools/renovate/refresh-devenv-lock.ts
@@ -70,6 +70,18 @@
 // and is what keeps the writer of a lock identical to the devenv version that
 // lock pins.
 //
+// That `nix run` also depends on the runner's nix.conf naming the devenv +
+// cachix SUBSTITUTERS and their trusted public keys (RIG-2815 review M2). The
+// fork's `#devenv` closure is not on cache.nixos.org (it pulls
+// `github:cachix/nix`), and nix ignores the fork flake's own
+// `nixConfig.extra-substituters` non-interactively (no `--accept-flake-config`),
+// so without those caches the realise cold-compiles the Nix fork + full closure
+// from source and can exhaust the runner. The caches are provided by
+// .github/workflows/renovate.yml's `extra_nix_config` block (which writes
+// /etc/nix/nix.conf on the runner, inherited by this child) — NOT by anything in
+// this file. config.test.ts asserts that block still names both caches + keys so
+// trimming them there fails a test rather than wedging a nightly relock.
+//
 // Exit codes:
 //   0 - the changed lock was relocked (or a no-op branch: neither lock differs
 //       from base).