@rightkit/release 0.2.49 → 0.2.50

package/build-release.mjs

@@ -26,6 +26,8 @@ import { acquireCacheLease, acquireSuiteBuildSlot, applyCachePrune, assertWriteV
 import { createTargetBridge } from "./target-bridge.mjs";
 import { assertNsisInPlaceUpgradeContract } from "./nsis-upgrade-contract.mjs";
 import { buildPathPrefix, collectPreflight, formatPreflight, preflightFailures } from "./preflight.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
+import { acquireHeavyWorkSlot, heavyCommandEnvironment } from "./heavy-command.mjs";
 
 /** Assemble preflight inputs from the app's own files (mirrors release.mjs). */
 function buildPreflight({ config, configPath, appRoot, repoRoot, platform }) {
@@ -79,11 +81,11 @@ if (relativeConfig.startsWith("../")) fail("release config must live inside the
 const appRoot = path.dirname(configPath);
 const layout = resolveReleaseLayout({ repoRoot, configPath });
 const vaultRoot = layout.vaultRoot;
-mkdirSync(path.join(vaultRoot, "locks"), { recursive: true });
-const lock = acquireLock(path.join(vaultRoot, "locks", `${platform}.lock.json`));
+let lock;
 let child = null;
 let suiteSlot;
 let cacheLease;
+let heavySlot;
 let interrupted;
 
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
@@ -97,6 +99,12 @@ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
 try {
   throwIfInterrupted();
   const commit = git(repoRoot, ["rev-parse", "HEAD"]);
+  assertCleanSource({
+    status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]),
+    commandId: "right-release build",
+  });
+  mkdirSync(path.join(vaultRoot, "locks"), { recursive: true });
+  lock = acquireLock(path.join(vaultRoot, "locks", `${platform}.lock.json`));
   const shortCommit = commit.slice(0, 8);
   const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
   if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
@@ -143,7 +151,7 @@ try {
   // Perl first so the build behaves the same from any shell.
   const pathPrefix = buildPathPrefix({ platform });
   const env = {
-    ...process.env,
+    ...heavyCommandEnvironment(process.env),
     ...releaseEnvironment({ root: vaultRoot, cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, cacheKey, kind: "release", appRoot, mode: cacheMode }),
     ...(pathPrefix ? { PATH: `${pathPrefix}${path.delimiter}${process.env.PATH ?? ""}` } : {}),
     RIGHT_RELEASE_REPO_ROOT: layout.repoRoot,
@@ -152,6 +160,7 @@ try {
   if (cacheMode === "legacy") delete env.RIGHT_RELEASE_CACHE_OWNER;
   if (cacheMode === "shared" && env.RIGHT_RELEASE_CACHE_OWNER !== "rightkit-v2") fail("shared cache ownership token was not configured");
   if (cacheMode === "legacy" && !commandExists("sccache")) delete env.RUSTC_WRAPPER;
+  if (process.env.RIGHTSUITE_HEAVY_WORK_OWNER !== "1") heavySlot = acquireHeavyWorkSlot();
   if (cacheMode === "shared") {
     suiteSlot = acquireSuiteBuildSlot({ layout: sharedLayout, pid: process.pid, argv: process.argv, waitMs: Number(process.env.BUILD_GUARD_WAIT_SECS ?? 900) * 1000 });
     cacheLease = acquireCacheLease({ layout: sharedLayout, pid: process.pid, argv: process.argv });
@@ -254,7 +263,8 @@ try {
 } finally {
   cacheLease?.release();
   suiteSlot?.release();
-  lock.release();
+  heavySlot?.release();
+  lock?.release();
 }
 
 function hashInputs(files) {

package/build-release.test.mjs

@@ -7,15 +7,20 @@ import { fileURLToPath } from "node:url";
 const source = readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "build-release.mjs"), "utf8");
 
 test("macOS and Windows builds default to Cache V2 while explicit legacy mode remains available", () => {
+  assert.match(source, /assertCleanSource/);
+  assert.match(source, /right-release build/);
   assert.match(source, /RIGHT_RELEASE_CACHE_MODE/);
   assert.match(source, /platform === "mac" \|\| platform === "win" \? "shared" : "legacy"/);
   assert.match(source, /cacheMode !== "legacy" && cacheMode !== "shared"/);
   assert.match(source, /resolveSharedCacheRoot/);
   assert.match(source, /acquireSuiteBuildSlot/);
+  assert.match(source, /acquireHeavyWorkSlot/);
+  assert.match(source, /heavyCommandEnvironment/);
   assert.match(source, /acquireCacheLease/);
   assert.match(source, /markCacheEntrySuccessful/);
   assert.match(source, /RIGHT_RELEASE_CACHE_OWNER/);
   assert.match(source, /suiteSlot\?\.release\(\)/);
+  assert.match(source, /heavySlot\?\.release\(\)/);
   assert.match(source, /cacheLease\?\.release\(\)/);
   assert.doesNotMatch(source, /process\.exit\(signal/);
   assert.match(source, /throwIfInterrupted/);

package/cache-command.mjs

@@ -58,7 +58,7 @@ export async function runCacheCommand(args = process.argv.slice(2), { env = proc
 
 function output(value, json, stdout) {
   if (json) stdout(JSON.stringify(value));
-  else if (value.command === "status") stdout(`RightKit cache root: ${value.cacheRoot}\nTargets: ${value.targetBytes} bytes\nFree: ${(value.cacheFreeBytes / 1024 ** 3).toFixed(1)} GiB\nLeases: ${value.entries.filter((entry) => entry.leased).length}`);
+  else if (value.command === "status") stdout(`RightKit cache root: ${value.cacheRoot}\nTargets: ${value.targetBytes} bytes\nBackups: ${value.backupBytes} bytes\nFree: ${(value.cacheFreeBytes / 1024 ** 3).toFixed(1)} GiB\nLeases: ${value.entries.filter((entry) => entry.leased).length}`);
   else stdout(`RightKit cache ${value.command}: ${value.dryRun ? "dry-run" : "applied"}\nRoot: ${value.cacheRoot}\nCandidates: ${(value.candidateIds ?? value.plan?.candidateIds ?? []).join(", ") || "none"}\nReclaimed: ${value.reclaimedBytes ?? 0} bytes`);
   return value;
 }

package/cache-command.test.mjs

@@ -19,6 +19,7 @@ test("cache status has human and schema-stable JSON output", () => {
   const json = run(["status", "--json"], cacheRoot);
   assert.equal(human.status, 0, human.stderr);
   assert.match(human.stdout, /RightKit cache root:/);
+  assert.match(human.stdout, /Backups: 0 bytes/);
   assert.equal(json.status, 0, json.stderr);
   assert.equal(JSON.parse(json.stdout).schema, 1);
 });

package/cache-policy.mjs

@@ -24,6 +24,7 @@ export const DEFAULT_TARGET_MAX_BYTES = 12 * 1024 ** 3;
 export const DEFAULT_SCCACHE_MAX_BYTES = 32 * 1024 ** 3;
 export const DEFAULT_DESIRED_FREE_BYTES = 60 * 1024 ** 3;
 export const DEFAULT_HARD_FREE_BYTES = 25 * 1024 ** 3;
+export const DEFAULT_BACKUP_RETENTION_DAYS = 7;
 // Any build holds release -> suite slot -> GC -> entry lease; prune holds only GC.
 export const CACHE_LOCK_ORDER = ["release", "suite-build-slot", "gc", "entry-lease"];
 
@@ -84,6 +85,7 @@ export function readCachePolicy(env = process.env) {
     sccacheMaxBytes: readPositive(env.RIGHT_RELEASE_SCCACHE_MAX_BYTES, DEFAULT_SCCACHE_MAX_BYTES),
     desiredFreeBytes: readPositive(env.RIGHT_RELEASE_DESIRED_FREE_BYTES, DEFAULT_DESIRED_FREE_BYTES),
     hardFreeBytes: readPositive(env.RIGHT_RELEASE_HARD_FREE_BYTES, DEFAULT_HARD_FREE_BYTES),
+    backupRetentionDays: readPositive(env.RIGHT_RELEASE_BACKUP_RETENTION_DAYS, DEFAULT_BACKUP_RETENTION_DAYS),
   };
 }
 
@@ -197,7 +199,7 @@ export function markCacheEntrySuccessful({ layout, now = new Date() } = {}) {
 
 export function inspectCache({ cacheRoot, statfs = statfsSync, now = new Date() } = {}) {
   const root = readonlyRoot(cacheRoot);
-  if (!root) return { cacheRoot: path.resolve(cacheRoot), entries: [], targetBytes: 0, cacheFreeBytes: 0, device: undefined, inspectedAt: iso(now) };
+  if (!root) return { cacheRoot: path.resolve(cacheRoot), entries: [], backups: [], targetBytes: 0, backupBytes: 0, cacheFreeBytes: 0, device: undefined, inspectedAt: iso(now) };
   const entries = [];
   for (const kind of ["targets", "test-targets"]) {
     const kindRoot = path.join(root, kind);
@@ -215,8 +217,16 @@ export function inspectCache({ cacheRoot, statfs = statfsSync, now = new Date()
       entries.push({ id: marker.id, dir, marker, bytes: directoryBytes(dir), leased: live, lease: live ? lease : null });
     }
   }
+  const backups = [];
+  for (const namespace of BACKUP_NAMESPACES) {
+    const namespaceRoot = path.join(root, namespace);
+    for (const entry of safeDirEntries(namespaceRoot)) {
+      const stat = lstatSync(entry.path);
+      backups.push({ id: `backup:${namespace}:${entry.name}`, namespace, name: entry.name, dir: entry.path, bytes: directoryBytes(entry.path), mtimeMs: stat.mtimeMs });
+    }
+  }
   const fs = statfs(root, { bigint: false });
-  return { cacheRoot: root, entries, targetBytes: entries.filter((x) => x.marker.kind === "release").reduce((sum, x) => sum + x.bytes, 0), cacheFreeBytes: freeBytes(fs), device: fs.dev ?? safeDevice(root), inspectedAt: iso(now) };
+  return { cacheRoot: root, entries, backups, targetBytes: entries.filter((x) => x.marker.kind === "release").reduce((sum, x) => sum + x.bytes, 0), backupBytes: backups.reduce((sum, x) => sum + x.bytes, 0), cacheFreeBytes: freeBytes(fs), device: fs.dev ?? safeDevice(root), inspectedAt: iso(now) };
 }
 
 export function inspectWriteVolumes({ repoRoot, vaultRoot, cacheRoot, statfs = statfsSync } = {}) {
@@ -253,6 +263,10 @@ export function planCachePrune({ snapshot, policy = readCachePolicy(), protected
   let bytes = snapshot.targetBytes ?? 0;
   let free = snapshot.cacheFreeBytes ?? Infinity;
   const selected = [];
+  const backupCutoff = new Date(snapshot.inspectedAt ?? Date.now()).getTime() - policy.backupRetentionDays * 86_400_000;
+  for (const entry of snapshot.backups ?? []) {
+    if (entry.mtimeMs < backupCutoff) selected.push({ id: entry.id, dir: entry.dir, bytes: entry.bytes, reason: "expired-backup" });
+  }
   for (const entry of candidates) {
     if (bytes <= policy.targetMaxBytes && free >= policy.desiredFreeBytes) break;
     selected.push({ id: entry.id, dir: entry.dir, bytes: entry.bytes, reason: bytes > policy.targetMaxBytes ? "target-cap" : "free-space" });
@@ -426,10 +440,18 @@ function acquireAtomicLock(file, payload, label, now) {
 function releaseFor(file, payload) { let released = false; return { release() { if (released) return; released = true; const current = readJson(file); if (current?.pid === payload.pid && current?.createdAt === payload.createdAt) safeUnlink(file); } }; }
 function touchEntry(layout, now) { const entry = readJson(layout.markerPath); if (!validEntry(entry, layout)) throw new Error(`invalid cache entry marker: ${layout.markerPath}`); entry.lastUsedAt = iso(now); atomicJson(layout.markerPath, entry); }
 function defaultSleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+const BACKUP_NAMESPACES = ["recovery", "manual-backups", "dev-target-backups", "legacy-backups"];
 function safePruneCandidate(root, candidate) {
   if (!candidate?.dir || path.resolve(candidate.dir) === root) return false;
   if (!existsSync(candidate.dir) || lstatSync(candidate.dir).isSymbolicLink()) return false;
-  const dir = realpathSync(candidate.dir); const targets = [path.join(root, "targets"), path.join(root, "test-targets")];
+  const dir = realpathSync(candidate.dir);
+  if (candidate.id?.startsWith("backup:")) {
+    const [, namespace, name] = candidate.id.split(":");
+    if (!BACKUP_NAMESPACES.includes(namespace) || !name || path.basename(dir) !== name) return false;
+    const backupRoot = path.join(root, namespace);
+    try { return path.dirname(dir) === backupRoot && realpathSync(backupRoot) === backupRoot; } catch { return false; }
+  }
+  const targets = [path.join(root, "targets"), path.join(root, "test-targets")];
   const targetRoot = targets.find((item) => { try { assertLexicalInside(item, dir); return true; } catch { return false; } });
   if (!targetRoot) return false;
   try {

package/cache-policy.test.mjs

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -8,6 +8,7 @@ import { once } from "node:events";
 
 import {
   CACHE_SCHEMA,
+  DEFAULT_BACKUP_RETENTION_DAYS,
   DEFAULT_DESIRED_FREE_BYTES,
   DEFAULT_HARD_FREE_BYTES,
   DEFAULT_SCCACHE_MAX_BYTES,
@@ -17,6 +18,7 @@ import {
   applyCachePrune,
   assertWriteVolumeFloors,
   ensureCacheEntry,
+  inspectCache,
   inspectWriteVolumes,
   markCacheEntrySuccessful,
   migrateLegacyCache,
@@ -80,6 +82,30 @@ test("policy defaults are the approved target, compiler, desired and hard limits
   assert.equal(policy.sccacheMaxBytes, DEFAULT_SCCACHE_MAX_BYTES);
   assert.equal(policy.desiredFreeBytes, DEFAULT_DESIRED_FREE_BYTES);
   assert.equal(policy.hardFreeBytes, DEFAULT_HARD_FREE_BYTES);
+  assert.equal(policy.backupRetentionDays, DEFAULT_BACKUP_RETENTION_DAYS);
+});
+
+test("pruning expires only old direct backup directories", () => {
+  const base = root();
+  const old = path.join(base, "manual-backups", "old-target");
+  const recent = path.join(base, "recovery", "recent-target");
+  const outside = root();
+  mkdirSync(old, { recursive: true }); writeFileSync(path.join(old, "artifact"), "old");
+  mkdirSync(recent, { recursive: true }); writeFileSync(path.join(recent, "artifact"), "recent");
+  mkdirSync(outside, { recursive: true });
+  mkdirSync(path.join(base, "legacy-backups"), { recursive: true });
+  symlinkSync(outside, path.join(base, "legacy-backups", "escape"));
+  utimesSync(old, new Date("2026-07-01T00:00:00Z"), new Date("2026-07-01T00:00:00Z"));
+  utimesSync(recent, new Date("2026-08-07T00:00:00Z"), new Date("2026-08-07T00:00:00Z"));
+  const snapshot = inspectCache({ cacheRoot: base, now: new Date("2026-08-08T00:00:00Z"), statfs: () => ({ bavail: 100, bsize: 1 }) });
+  assert.deepEqual(snapshot.backups.map((entry) => entry.id).sort(), ["backup:manual-backups:old-target", "backup:recovery:recent-target"]);
+  const plan = planCachePrune({ snapshot, policy: { ...readCachePolicy({}), targetMaxBytes: 1, desiredFreeBytes: 0 } });
+  assert.deepEqual(plan.candidateIds, ["backup:manual-backups:old-target"]);
+  const result = applyCachePrune({ plan, cacheRoot: base, dryRun: false });
+  assert.deepEqual(result.removedIds, ["backup:manual-backups:old-target"]);
+  assert.equal(existsSync(old), false);
+  assert.equal(existsSync(recent), true);
+  assert.equal(existsSync(outside), true);
 });
 
 test("entry metadata is atomic, complete, and updates success only after requested", () => {

package/heavy-command.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+
+const GB = 1024 ** 3;
+
+export function heavyWorkRoot({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  if (env.RIGHTSUITE_HEAVY_WORK_ROOT) return path.resolve(env.RIGHTSUITE_HEAVY_WORK_ROOT);
+  if (platform === "win32" || platform === "win") {
+    if (!env.LOCALAPPDATA) throw new Error("LOCALAPPDATA is required for the RightSuite heavy-work guard");
+    return path.win32.resolve(env.LOCALAPPDATA, "RightSuite", "heavy-work");
+  }
+  if (platform === "darwin" || platform === "mac") return path.join(home, "Library", "Caches", "RightSuite", "heavy-work");
+  return path.resolve(env.XDG_CACHE_HOME || path.join(home, ".cache"), "rightsuite", "heavy-work");
+}
+
+export function heavyCommandEnvironment(env = process.env) {
+  return {
+    ...env,
+    CARGO_BUILD_JOBS: env.CARGO_BUILD_JOBS || env.BUILD_GUARD_CARGO_JOBS || "2",
+    RUST_TEST_THREADS: env.RUST_TEST_THREADS || env.BUILD_GUARD_TEST_THREADS || "2",
+    RIGHTSUITE_HEAVY_WORK_OWNER: "1",
+  };
+}
+
+export function parseMacResourceSnapshot({ memory = "", swap = "", thermal = "" } = {}) {
+  const freePercent = Number(memory.match(/memory free percentage:\s*(\d+(?:\.\d+)?)%/i)?.[1]);
+  const swapMatch = swap.match(/total\s*=\s*([\d.]+)M\s+used\s*=\s*([\d.]+)M/i);
+  const speedLimit = Number(thermal.match(/CPU_Speed_Limit\s*=\s*(\d+)/i)?.[1]);
+  const warning = Number(thermal.match(/(?:thermal|performance) warning level\s*[:=]\s*(\d+)/i)?.[1]);
+  return {
+    freePercent: Number.isFinite(freePercent) ? freePercent : null,
+    swapTotalBytes: swapMatch ? Number(swapMatch[1]) * 1024 ** 2 : null,
+    swapUsedBytes: swapMatch ? Number(swapMatch[2]) * 1024 ** 2 : null,
+    thermalLimited: Number.isFinite(speedLimit) ? speedLimit < 100 : Number.isFinite(warning) ? warning > 0 : false,
+  };
+}
+
+export function parseWindowsResourceSnapshot({ system = "", fallbackTotalBytes = os.totalmem(), fallbackFreeBytes = os.freemem() } = {}) {
+  let parsed = {};
+  try { parsed = JSON.parse(String(system).trim().replace(/^\uFEFF/, "")); } catch { /* use Node memory fallback */ }
+  const totalMemoryBytes = Number(parsed.TotalBytes) > 0 ? Number(parsed.TotalBytes) : Number(fallbackTotalBytes);
+  const freeMemoryBytes = Number(parsed.FreeBytes) >= 0 ? Number(parsed.FreeBytes) : Number(fallbackFreeBytes);
+  const cpuLoadPercent = parsed.CpuLoadPercent === null || parsed.CpuLoadPercent === undefined ? null : Number(parsed.CpuLoadPercent);
+  return {
+    freePercent: totalMemoryBytes > 0 ? Math.round((freeMemoryBytes / totalMemoryBytes) * 1000) / 10 : null,
+    totalMemoryBytes,
+    freeMemoryBytes,
+    cpuLoadPercent: Number.isFinite(cpuLoadPercent) ? cpuLoadPercent : null,
+    thermalLimited: false,
+  };
+}
+
+export function systemResourceSnapshot({ platform = process.platform, run = spawnSync, totalmem = os.totalmem, freemem = os.freemem } = {}) {
+  if (platform === "win32" || platform === "win") {
+    const script = "$os=Get-CimInstance Win32_OperatingSystem;$cpu=(Get-CimInstance Win32_Processor|Measure-Object LoadPercentage -Average).Average;[pscustomobject]@{TotalBytes=[double]$os.TotalVisibleMemorySize*1024;FreeBytes=[double]$os.FreePhysicalMemory*1024;CpuLoadPercent=[double]$cpu}|ConvertTo-Json -Compress";
+    const result = run("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf8", windowsHide: true });
+    return { platform, ...parseWindowsResourceSnapshot({ system: result.status === 0 ? result.stdout : "", fallbackTotalBytes: totalmem(), fallbackFreeBytes: freemem() }) };
+  }
+  if (platform !== "darwin" && platform !== "mac") return { platform, freePercent: null, thermalLimited: false };
+  const output = (command, args) => {
+    const result = run(command, args, { encoding: "utf8", windowsHide: true });
+    return result.status === 0 ? String(result.stdout ?? result.stderr ?? "") : "";
+  };
+  return {
+    platform,
+    ...parseMacResourceSnapshot({
+      memory: output("memory_pressure", ["-Q"]),
+      swap: output("sysctl", ["vm.swapusage"]),
+      thermal: output("pmset", ["-g", "therm"]),
+    }),
+  };
+}
+
+export function resourceBlockers(snapshot, { minFreePercent = 15, maxCpuLoadPercent = 90 } = {}) {
+  const blockers = [];
+  if (snapshot.freePercent !== null && snapshot.freePercent < minFreePercent) {
+    blockers.push(`memory free ${snapshot.freePercent}% < ${minFreePercent}%`);
+  }
+  if (Number.isFinite(snapshot.cpuLoadPercent) && snapshot.cpuLoadPercent > maxCpuLoadPercent) {
+    blockers.push(`CPU load ${snapshot.cpuLoadPercent}% > ${maxCpuLoadPercent}%`);
+  }
+  if (snapshot.thermalLimited) blockers.push("macOS reports thermal/performance limiting");
+  return blockers;
+}
+
+export function formatResourceSnapshot(snapshot) {
+  const fields = [];
+  if (snapshot.freePercent !== null) fields.push(`memory-free=${snapshot.freePercent}%`);
+  if (Number.isFinite(snapshot.swapUsedBytes) && Number.isFinite(snapshot.swapTotalBytes)) {
+    fields.push(`swap=${(snapshot.swapUsedBytes / GB).toFixed(1)}/${(snapshot.swapTotalBytes / GB).toFixed(1)}GiB`);
+  }
+  if (Number.isFinite(snapshot.cpuLoadPercent)) fields.push(`cpu-load=${snapshot.cpuLoadPercent}%`);
+  if (snapshot.platform === "darwin" || snapshot.platform === "mac" || snapshot.thermalLimited) {
+    fields.push(`thermal=${snapshot.thermalLimited ? "limited" : "ok"}`);
+  }
+  return fields.join(" ");
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(Number(pid)) || Number(pid) <= 0) return false;
+  try { process.kill(Number(pid), 0); return true; } catch { return false; }
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function readOwner(lockDir) {
+  try { return JSON.parse(readFileSync(path.join(lockDir, "owner.json"), "utf8")); } catch { return null; }
+}
+
+export function acquireHeavyWorkSlot({
+  root = heavyWorkRoot(), pid = process.pid, argv = process.argv, waitMs = Number(process.env.BUILD_GUARD_WAIT_SECS ?? 900) * 1000,
+  pollMs = 1000, alive = processAlive, pause = sleep, snapshot = systemResourceSnapshot,
+  minFreePercent = Number(process.env.BUILD_GUARD_MIN_MEMORY_FREE_PERCENT ?? 15), log = (message) => console.error(`[heavy-work] ${message}`),
+  maxCpuLoadPercent = Number(process.env.BUILD_GUARD_MAX_CPU_LOAD_PERCENT ?? 90),
+} = {}) {
+  mkdirSync(root, { recursive: true });
+  const lockDir = path.join(root, "slot");
+  const token = randomUUID();
+  const started = Date.now();
+  let lastReport = 0;
+  for (;;) {
+    try {
+      mkdirSync(lockDir);
+      const fd = openSync(path.join(lockDir, "owner.json"), "wx");
+      writeFileSync(fd, `${JSON.stringify({ schema: 1, pid: Number(pid), token, argv: [...argv], createdAt: new Date().toISOString() })}\n`);
+      closeSync(fd);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const owner = readOwner(lockDir);
+      const incompleteAge = (() => { try { return Date.now() - statSync(lockDir).mtimeMs; } catch { return 0; } })();
+      if (owner ? !alive(owner.pid) : incompleteAge > 10_000) {
+        rmSync(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() - started >= waitMs) throw new Error(`heavy-work slot timed out after ${waitMs}ms; holder pid ${owner?.pid ?? "starting"}`);
+      if (Date.now() - lastReport >= 10_000) { log(`waiting for pid ${owner?.pid ?? "starting"}`); lastReport = Date.now(); }
+      pause(Math.min(pollMs, Math.max(1, waitMs - (Date.now() - started))));
+    }
+  }
+
+  for (;;) {
+    const current = snapshot();
+    const blockers = resourceBlockers(current, { minFreePercent, maxCpuLoadPercent });
+    if (blockers.length === 0) {
+      log(`admitted ${formatResourceSnapshot(current)} jobs=${heavyCommandEnvironment().CARGO_BUILD_JOBS}`);
+      break;
+    }
+    if (Date.now() - started >= waitMs) {
+      releaseOwned(lockDir, token);
+      throw new Error(`resource admission timed out: ${blockers.join(", ")}`);
+    }
+    if (Date.now() - lastReport >= 10_000) { log(`resource wait: ${blockers.join(", ")}`); lastReport = Date.now(); }
+    pause(Math.min(5000, Math.max(1, waitMs - (Date.now() - started))));
+  }
+  return { root, release: () => releaseOwned(lockDir, token) };
+}
+
+function releaseOwned(lockDir, token) {
+  const owner = readOwner(lockDir);
+  if (owner?.token === token) rmSync(lockDir, { recursive: true, force: true });
+}
+
+export async function runHeavyCommand(args, { env = process.env } = {}) {
+  let command;
+  let commandArgs;
+  if (args[0] === "--shell-base64") {
+    const source = Buffer.from(args[1] || "", "base64").toString("utf8");
+    const shell = process.platform === "win32" ? (env.SHELL || "bash") : (env.SHELL || "/bin/zsh");
+    command = shell; commandArgs = ["-lc", source];
+  } else {
+    const separator = args.indexOf("--");
+    const values = separator >= 0 ? args.slice(separator + 1) : args;
+    [command, ...commandArgs] = values;
+  }
+  if (!command) throw new Error("heavy-command: expected -- <command> or --shell-base64 <value>");
+  if (env.RIGHTSUITE_HEAVY_WORK_OWNER === "1") return spawnAttached(command, commandArgs, env);
+  const slot = acquireHeavyWorkSlot();
+  try { return await spawnAttached(command, commandArgs, heavyCommandEnvironment(env)); } finally { slot.release(); }
+}
+
+function spawnAttached(command, args, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: process.cwd(), env, stdio: "inherit", windowsHide: true });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+  });
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runHeavyCommand(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => { console.error(`heavy-command: ${error.message}`); process.exitCode = 1; });
+}

package/heavy-command.test.mjs

@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdtempSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  acquireHeavyWorkSlot,
+  formatResourceSnapshot,
+  heavyCommandEnvironment,
+  heavyWorkRoot,
+  parseMacResourceSnapshot,
+  parseWindowsResourceSnapshot,
+  resourceBlockers,
+  runHeavyCommand,
+  systemResourceSnapshot,
+} from "./heavy-command.mjs";
+
+test("heavy-work root is machine-wide rather than repository-local", () => {
+  assert.equal(heavyWorkRoot({ platform: "mac", home: "/Users/test", env: {} }), "/Users/test/Library/Caches/RightSuite/heavy-work");
+  assert.equal(heavyWorkRoot({ platform: "win", env: { LOCALAPPDATA: "C:\\Users\\test\\AppData\\Local" } }), "C:\\Users\\test\\AppData\\Local\\RightSuite\\heavy-work");
+});
+
+test("heavy commands default compiler and test concurrency to two", () => {
+  const env = heavyCommandEnvironment({});
+  assert.equal(env.CARGO_BUILD_JOBS, "2");
+  assert.equal(env.RUST_TEST_THREADS, "2");
+  assert.equal(env.RIGHTSUITE_HEAVY_WORK_OWNER, "1");
+  assert.equal(heavyCommandEnvironment({ CARGO_BUILD_JOBS: "3", RUST_TEST_THREADS: "1" }).CARGO_BUILD_JOBS, "3");
+});
+
+test("mac resource parser reports memory, swap and thermal limiting", () => {
+  const snapshot = parseMacResourceSnapshot({
+    memory: "System-wide memory free percentage: 9%",
+    swap: "vm.swapusage: total = 8192.00M used = 7750.62M free = 441.38M",
+    thermal: "CPU_Speed_Limit = 70",
+  });
+  assert.equal(snapshot.freePercent, 9);
+  assert.equal(Math.round(snapshot.swapUsedBytes / 1024 ** 2), 7751);
+  assert.equal(snapshot.thermalLimited, true);
+  assert.deepEqual(resourceBlockers(snapshot), ["memory free 9% < 15%", "macOS reports thermal/performance limiting"]);
+});
+
+test("Windows admission uses physical memory and CPU load with a Node memory fallback", () => {
+  const snapshot = parseWindowsResourceSnapshot({
+    system: JSON.stringify({ TotalBytes: 16 * 1024 ** 3, FreeBytes: 4 * 1024 ** 3, CpuLoadPercent: 94 }),
+  });
+  assert.equal(snapshot.freePercent, 25);
+  assert.equal(snapshot.cpuLoadPercent, 94);
+  assert.deepEqual(resourceBlockers(snapshot), ["CPU load 94% > 90%"]);
+
+  const fallback = parseWindowsResourceSnapshot({ system: "not-json", fallbackTotalBytes: 8 * 1024 ** 3, fallbackFreeBytes: 2 * 1024 ** 3 });
+  assert.equal(fallback.freePercent, 25);
+  assert.equal(fallback.cpuLoadPercent, null);
+});
+
+test("Windows resource snapshot queries PowerShell without requiring optional modules", () => {
+  const calls = [];
+  const snapshot = systemResourceSnapshot({
+    platform: "win",
+    run: (command, args) => { calls.push({ command, args }); return { status: 0, stdout: '{"TotalBytes":8589934592,"FreeBytes":1073741824,"CpuLoadPercent":42}' }; },
+    totalmem: () => 1,
+    freemem: () => 1,
+  });
+  assert.equal(calls[0].command, "powershell.exe");
+  assert.deepEqual(calls[0].args.slice(0, 3), ["-NoLogo", "-NoProfile", "-NonInteractive"]);
+  assert.equal(snapshot.freePercent, 12.5);
+  assert.equal(snapshot.cpuLoadPercent, 42);
+  assert.equal(snapshot.thermalLimited, false);
+  assert.equal(formatResourceSnapshot(snapshot), "memory-free=12.5% cpu-load=42%");
+});
+
+test("nested heavy command preserves ownership without another slot", async () => {
+  const code = await runHeavyCommand(["--", process.execPath, "-e", "process.exit(0)"], { env: { ...process.env, RIGHTSUITE_HEAVY_WORK_OWNER: "1" } });
+  assert.equal(code, 0);
+});
+
+test("slot serializes contenders and removes stale owners", () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), "rightsuite-heavy-"));
+  const quiet = () => {};
+  const snapshot = () => ({ freePercent: 50, swapUsedBytes: 0, swapTotalBytes: 0, thermalLimited: false });
+  const first = acquireHeavyWorkSlot({ root, pid: 101, alive: (pid) => pid === 101, snapshot, log: quiet });
+  assert.throws(
+    () => acquireHeavyWorkSlot({ root, pid: 202, waitMs: 1, pollMs: 1, alive: (pid) => pid === 101, pause: () => {}, snapshot, log: quiet }),
+    /holder pid 101/,
+  );
+  first.release();
+
+  const lockDir = path.join(root, "slot");
+  mkdirSync(lockDir);
+  writeFileSync(path.join(lockDir, "owner.json"), JSON.stringify({ pid: 303, token: "stale" }));
+  const replacement = acquireHeavyWorkSlot({ root, pid: 404, alive: () => false, snapshot, log: quiet });
+  replacement.release();
+});

package/model-promote.mjs

@@ -4,7 +4,7 @@ import { createReadStream } from "node:fs";
 import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import {
@@ -13,6 +13,7 @@ import {
 } from "./runtime-artifact-manifest.mjs";
 import { loadReleaseToken } from "./release-token.mjs";
 import { registerRightAppsRelease } from "./rightapps-register.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
 
 export const RUNTIME_ARTIFACT_TRUSTED_KEY_ID = "rightkit-runtime-artifacts-2026-07";
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
@@ -24,6 +25,8 @@ export async function promoteRuntimeArtifact(input, deps = {}) {
   const register = deps.register;
   const { config } = input;
   assertPromotionConfig(config);
+  if (!input.verification) throw new Error("release source identity is required");
+  assertCleanSource({ status: input.verification.status, commandId: "right-release model promote" });
   if (input.authority !== "heardright") throw new Error("model promotion authority must be heardright");
   if (input.keyId !== RUNTIME_ARTIFACT_TRUSTED_KEY_ID) throw new Error(`untrusted runtime artifact key id: ${input.keyId}`);
   if (!input.privateKey) throw new Error("runtime artifact signing key is required");
@@ -134,6 +137,7 @@ async function main() {
     evidenceFile: path.resolve(configRoot, raw.evidence.file),
     config,
     dryRun: args.dryRun,
+    verification: readVerificationEvidence(args, configRoot),
   }, runtime);
   const manifest = result.envelope.manifest;
   console.log(`${args.dryRun ? "[dry-run] " : ""}runtime artifact promotion validated`);
@@ -161,6 +165,9 @@ Options:
   --signing-key-file <pem>  Override the protected PEM path
   --key-id <id>             Must equal ${RUNTIME_ARTIFACT_TRUSTED_KEY_ID}
 
+Promotion runs only from a clean checkout, so the promoted artifact binds to an
+exact commit.
+
 Signing key inputs (never printed): RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY or
 RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE. Windows defaults to
 %APPDATA%/RightKit/runtime-artifact-signing-key.pem. Live promotion also uses
@@ -187,6 +194,19 @@ function parseArgs(args) {
   return { authority, config, signingKeyFile, keyId, dryRun };
 }
 
+function readVerificationEvidence(args, cwd) {
+  return {
+    candidateCommit: git(cwd, ["rev-parse", "HEAD"]),
+    status: git(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]),
+  };
+}
+
+function git(cwd, args) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) throw new Error(`git ${args.join(" ")} failed`);
+  return result.stdout.trim();
+}
+
 async function fileMetadata(file) {
   const info = await stat(file);
   if (!info.isFile() || info.size <= 0) throw new Error(`promotion input is not a nonempty file: ${file}`);

package/model-promote.test.mjs

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { createHash, generateKeyPairSync } from "node:crypto";
+import { createHash, generateKeyPairSync, sign } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
@@ -14,11 +14,17 @@ import {
   promoteRuntimeArtifact,
   runtimeArtifactUploadEnv,
 } from "./model-promote.mjs";
-
 const { privateKey } = generateKeyPairSync("ed25519");
 const artifactDigest = "a".repeat(64);
 const evidenceDigest = "b".repeat(64);
 const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const candidateCommit = "a".repeat(40);
+
+// Source identity as build/upload/promote read it: the exact commit, plus the
+// porcelain status that must be empty for the promotion to run.
+function verificationFixture(commit = candidateCommit, status = "") {
+  return { candidateCommit: commit, status };
+}
 
 function request(overrides = {}) {
   return {
@@ -59,6 +65,7 @@ function request(overrides = {}) {
         },
       },
     },
+    verification: verificationFixture(),
     ...overrides,
   };
 }
@@ -92,6 +99,25 @@ test("dry-run validates and signs without invoking process or network boundaries
   assert.equal(result.envelope.signature.algorithm, "Ed25519");
 });
 
+test("model promotion refuses a dirty working tree", async () => {
+  const events = [];
+  const verification = verificationFixture(candidateCommit, " M packages/release/model-promote.mjs\0");
+  await assert.rejects(
+    promoteRuntimeArtifact(request({ verification, dryRun: true }), boundaries(events)),
+    /clean working tree/,
+  );
+  assert.deepEqual(events, []);
+});
+
+test("model promotion requires source identity", async () => {
+  const events = [];
+  await assert.rejects(
+    promoteRuntimeArtifact(request({ verification: undefined, dryRun: true }), boundaries(events)),
+    /source identity is required/,
+  );
+  assert.deepEqual(events, []);
+});
+
 test("never registers or publishes a pointer after immutable upload failure", async () => {
   const events = [];
   const deps = boundaries(events);
@@ -169,7 +195,7 @@ test("model promote help documents the portable config and secure key inputs", (
   assert.match(result.stdout, /RIGHTAPPS_RELEASE_TOKEN/);
 });
 
-test("portable CLI dry-run validates real files and signs without network mutation or secret output", async () => {
+test("portable CLI promotes from a clean checkout, refuses a dirty one, and rejects injected trust flags", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "rightkit-model-promote-test-"));
   try {
     const artifact = Buffer.from("tiny model fixture");
@@ -181,6 +207,10 @@ test("portable CLI dry-run validates real files and signs without network mutati
       writeFile(path.join(root, "evidence.json"), evidence),
       writeFile(path.join(root, "key.pem"), keyPem, { mode: 0o600 }),
     ]);
+    spawnSync("git", ["init"], { cwd: root, encoding: "utf8" });
+    spawnSync("git", ["add", "."], { cwd: root, encoding: "utf8" });
+    const committed = spawnSync("git", ["-c", "user.name=fixture", "-c", "user.email=fixture@example.invalid", "commit", "-m", "fixture"], { cwd: root, encoding: "utf8" });
+    assert.equal(committed.status, 0, committed.stderr);
     const config = {
       artifact: {
         file: "model.onnx",
@@ -195,17 +225,31 @@ test("portable CLI dry-run validates real files and signs without network mutati
       manifest: request().config.manifest,
     };
     await writeFile(path.join(root, "promotion.json"), JSON.stringify(config));
+    spawnSync("git", ["add", "."], { cwd: root, encoding: "utf8" });
+    spawnSync("git", ["-c", "user.name=fixture", "-c", "user.email=fixture@example.invalid", "commit", "-m", "config"], { cwd: root, encoding: "utf8" });
 
-    const result = spawnSync(process.execPath, [
+    const promoteArgs = [
       path.join(packageRoot, "cli/right-release.mjs"), "model", "promote",
       "--authority", "heardright",
       "--config", path.join(root, "promotion.json"),
       "--signing-key-file", path.join(root, "key.pem"),
       "--dry-run",
-    ], { cwd: root, encoding: "utf8", windowsHide: true });
+    ];
+    const result = spawnSync(process.execPath, promoteArgs, { cwd: root, encoding: "utf8", windowsHide: true });
     assert.equal(result.status, 0, result.stderr);
-    assert.match(result.stdout, /\[dry-run\] runtime artifact promotion validated/);
-    assert.match(result.stdout, /upload immutable object -> register signed envelope -> replace stable pointer/);
+
+    await writeFile(path.join(root, "untracked.txt"), "dirty");
+    const dirty = spawnSync(process.execPath, promoteArgs, { cwd: root, encoding: "utf8", windowsHide: true });
+    assert.equal(dirty.status, 1);
+    assert.match(dirty.stderr, /clean working tree/);
+
+    const attacker = spawnSync(process.execPath, [
+      path.join(packageRoot, "cli/right-release.mjs"), "model", "promote",
+      "--authority", "heardright", "--config", path.join(root, "promotion.json"),
+      "--verification-public-key", path.join(root, "verification-public.pem"),
+    ], { cwd: root, encoding: "utf8", windowsHide: true });
+    assert.equal(attacker.status, 1);
+    assert.match(attacker.stderr, /unknown model promote argument: --verification-public-key/);
     assert.doesNotMatch(`${result.stdout}${result.stderr}`, /BEGIN PRIVATE KEY/);
     assert.doesNotMatch(`${result.stdout}${result.stderr}`, /Uploading|POST https:/);
   } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.49",
+  "version": "0.2.50",
   "description": "Portable Right Suite release CLI/SDK: signed installers, updater artifacts, patch/update routing, hardening, R2 publish, and RightApps registration.",
   "type": "module",
   "bin": {

package/right-suite-contract.test.mjs

@@ -442,10 +442,10 @@ test("RightKit exposes one current version manifest", () => {
     "@rightkit/legal": "0.3.0",
     "@rightkit/legal-ui": "0.1.0",
     "@rightkit/license": "0.1.6",
-    "@rightkit/release": "0.2.49",
+    "@rightkit/release": "0.2.50",
   });
   assert.deepEqual(versions.legacyNpm, {
-    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46"],
+    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46", "0.2.49"],
   });
   assert.ok(
     new Set([versions.npm["@rightkit/release"], ...versions.legacyNpm["@rightkit/release"]]).has("0.2.42"),

package/rightkit-versions.json

@@ -1,6 +1,6 @@
 {
   "schema": 1,
-  "packageManager": "pnpm@11.17.0",
+  "packageManager": "pnpm@11.18.0",
   "npm": {
     "@rightkit/legal": "0.2.0",
     "@rightkit/license": "0.1.5",
@@ -15,10 +15,10 @@
     "@rightkit/legal": "0.3.0",
     "@rightkit/legal-ui": "0.1.0",
     "@rightkit/license": "0.1.6",
-    "@rightkit/release": "0.2.49"
+    "@rightkit/release": "0.2.50"
   },
   "legacyNpm": {
-    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46"]
+    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46", "0.2.49"]
   },
   "cargo": {
     "rightkit-license": "0.1.2",

package/source-gate.mjs

@@ -0,0 +1,19 @@
+// Release source gate.
+//
+// A build or upload may only run from a clean checkout, so every sealed artifact
+// binds to an exact commit that exists in history rather than to whatever happened
+// to be in the working tree. Upload separately re-checks that the sealed manifest's
+// commit still matches HEAD, so the pair pins source identity end to end.
+//
+// This replaces the r7 verification-ticket / admin-broker layer removed in 578d7ac5.
+// That layer defended against a hostile local admin, which is not a threat here; the
+// real risk is shipping stale, dirty, or untested source. Distribution trust still
+// comes from OS code signing, notarization, and the Tauri updater key — untouched.
+
+export function assertCleanSource({ status, commandId = "release" }) {
+  if (typeof status !== "string") throw new Error("release source status is required");
+  if (status.length !== 0) {
+    const files = status.split("\0").filter(Boolean).map((entry) => entry.slice(3)).slice(0, 10);
+    throw new Error(`${commandId} requires a clean working tree; commit or stash first:\n${files.map((file) => `- ${file}`).join("\n")}`);
+  }
+}

package/source-gate.test.mjs

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { assertCleanSource } from "./source-gate.mjs";
+
+test("a clean status passes the gate", () => {
+  assert.doesNotThrow(() => assertCleanSource({ status: "", commandId: "right-release build" }));
+});
+
+test("a dirty status names the command and the offending files", () => {
+  assert.throws(
+    () => assertCleanSource({ status: " M src/main.rs\0?? notes.txt\0", commandId: "right-release build" }),
+    (error) => {
+      assert.match(error.message, /right-release build requires a clean working tree/);
+      assert.match(error.message, /- src\/main\.rs/);
+      assert.match(error.message, /- notes\.txt/);
+      return true;
+    },
+  );
+});
+
+test("a missing status is refused rather than treated as clean", () => {
+  assert.throws(() => assertCleanSource({ commandId: "right-release upload" }), /status is required/);
+  assert.throws(() => assertCleanSource({ status: null }), /status is required/);
+});

package/standalone-clone-verify.test.mjs

@@ -16,9 +16,9 @@ test("standalone verifier clones, installs, doctors from a nested app root, and
   const fixtureRoot = mkdtempSync(path.join(tmpdir(), "rightkit-standalone-fixture-"));
   t.after(() => rmSync(fixtureRoot, { recursive: true, force: true }));
   const source = path.join(fixtureRoot, "source");
-  const outsideSentinel = path.join(fixtureRoot, "keep.txt");
+  const outsideForge = path.join(fixtureRoot, "keep.txt");
   mkdirSync(path.join(source, "apps", "desktop"), { recursive: true });
-  writeFileSync(outsideSentinel, "keep", "utf8");
+  writeFileSync(outsideForge, "keep", "utf8");
   writeFileSync(path.join(source, "apps", "desktop", "package.json"), JSON.stringify({
     name: "standalone-fixture",
     private: true,
@@ -44,7 +44,7 @@ test("standalone verifier clones, installs, doctors from a nested app root, and
   assert.equal(result.apps[0].doctor.status, 0);
   assert.match(result.apps[0].doctor.stdout, /fixture doctor passed/);
   assert.equal(existsSync(result.workRoot), false, "generated clone tree must be removed");
-  assert.equal(readFileSync(outsideSentinel, "utf8"), "keep", "cleanup must not escape the generated tree");
+  assert.equal(readFileSync(outsideForge, "utf8"), "keep", "cleanup must not escape the generated tree");
   assert.deepEqual(JSON.parse(readFileSync(evidencePath, "utf8")).apps.map(({ key }) => key), ["fixture"]);
 });
 

package/upload-release.mjs

@@ -6,6 +6,7 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
 import { runUploadStateMachine, verifySealedRelease } from "./release-state.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const PUBLISH_UPDATE = path.join(TOOL_ROOT, "publish-update.mjs");
@@ -36,9 +37,15 @@ if (platform !== "win" && platform !== "mac") fail("--platform must be win or ma
 
 const repoRoot = git(process.cwd(), ["rev-parse", "--show-toplevel"]);
 assertPrimaryReleaseCheckout(repoRoot);
+const candidateCommit = git(repoRoot, ["rev-parse", "HEAD"]);
+assertCleanSource({
+  status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]),
+  commandId: "right-release upload",
+});
 const platformDir = platform === "win" ? "windows" : "mac";
 const sealedDir = path.join(repoRoot, ".right-release", "sealed", releaseId, platformDir);
 const sealed = verifySealedRelease(sealedDir);
+if (sealed.manifest.commit !== candidateCommit) fail("sealed release was built from a different commit than the current checkout");
 const stateRoot = path.join(repoRoot, ".right-release", "state", releaseId, platformDir);
 const backupRoot = path.join(stateRoot, "rollback", tier);
 const verifiedMarker = path.join(stateRoot, `verified-${tier}.json`);
@@ -212,7 +219,7 @@ function writeJson(file, value) {
 }
 
 function usage(code) {
-  console.log("usage: right-release upload --release <sealed-id> --platform win|mac --tier patch|update");
+  console.log("usage: right-release upload --release <sealed-id> --platform win|mac --tier patch|update [--dry-run]");
   process.exit(code);
 }