@rightkit/release 0.2.49 → 0.2.51

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, terminateProcessTree } 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) {
@@ -354,7 +364,16 @@ async function runProgress(cmd, runArgs, cwd, env, watchDir) {
   let lastMtime = Math.max(...watchDirs.map(newestMtime));
   const started = Date.now();
   await new Promise((resolve, reject) => {
-    child = spawn(cmd, runArgs, { cwd, env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true, shell: process.platform === "win32" });
+    child = spawn(cmd, runArgs, { cwd, env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true, shell: process.platform === "win32", detached: process.platform !== "win32" });
+    try {
+      if (child.pid && heavySlot) heavySlot.trackChild(child.pid, cmd);
+    } catch (error) {
+      child.once("error", () => {});
+      if (child.pid) killTree(child.pid);
+      child = null;
+      reject(error);
+      return;
+    }
     const closeWatchers = watchProgress(watchDirs, () => { lastProgress = Date.now(); });
     for (const [stream, output] of [[child.stdout, process.stdout], [child.stderr, process.stderr]]) {
       stream.on("data", (chunk) => { lastProgress = Date.now(); output.write(chunk); });
@@ -454,9 +473,7 @@ function runChecked(cmd, runArgs, cwd, env = process.env) {
 }
 
 function killTree(pid) {
-  if (!pid) return;
-  if (process.platform === "win32") spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
-  else { try { process.kill(-pid, "SIGTERM"); } catch { try { process.kill(pid, "SIGTERM"); } catch { /* gone */ } } }
+  terminateProcessTree(pid);
 }
 
 function writeJson(file, value) {

package/build-release.test.mjs

@@ -7,15 +7,22 @@ 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, /heavySlot\.trackChild/);
+  assert.match(source, /detached: process\.platform !== "win32"/);
   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/cargo-guard.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { runHeavyCommand } from "./heavy-command.mjs";
+
+const LIGHT_COMMANDS = new Set(["fmt", "metadata", "tree", "fetch", "search", "locate-project", "read-manifest", "help", "version", "--version", "-V"]);
+const GLOBAL_OPTIONS_WITH_VALUE = new Set(["--color", "--config", "-Z"]);
+
+export function cargoSubcommand(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value.startsWith("+") || value.startsWith("--color=") || value.startsWith("--config=")) continue;
+    if (GLOBAL_OPTIONS_WITH_VALUE.has(value)) { index += 1; continue; }
+    if (value.startsWith("-Z")) continue;
+    if (!value.startsWith("-") || value === "--version" || value === "-V") return value;
+  }
+  return null;
+}
+
+export function shouldGuardCargo(args) {
+  const command = cargoSubcommand(args);
+  return command !== null && !LIGHT_COMMANDS.has(command);
+}
+
+export function resolveRealCargo({ env = process.env, run = spawnSync } = {}) {
+  if (env.RIGHTSUITE_REAL_CARGO) return path.resolve(env.RIGHTSUITE_REAL_CARGO);
+  const rustup = process.platform === "win32" ? "rustup.exe" : "rustup";
+  const result = run(rustup, ["which", "cargo"], { encoding: "utf8", windowsHide: true });
+  const cargo = String(result.stdout ?? "").trim();
+  if (result.status !== 0 || !cargo) throw new Error(`cargo-guard could not resolve real Cargo: ${String(result.stderr ?? "").trim()}`);
+  return path.resolve(cargo);
+}
+
+function spawnCargo(command, args, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env, stdio: "inherit", windowsHide: true });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+  });
+}
+
+export async function runCargoGuard(args, { env = process.env, resolveCargo = resolveRealCargo, runHeavy = runHeavyCommand, runLight = spawnCargo } = {}) {
+  const cargo = resolveCargo({ env });
+  if (shouldGuardCargo(args)) return runHeavy(["--", cargo, ...args], { env });
+  return runLight(cargo, args, env);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runCargoGuard(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => { console.error(`cargo-guard: ${error.message}`); process.exitCode = 1; });
+}

package/cargo-guard.test.mjs

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { cargoSubcommand, resolveRealCargo, runCargoGuard, shouldGuardCargo } from "./cargo-guard.mjs";
+
+test("Cargo guard serializes compiling commands but bypasses inspection and formatting", () => {
+  for (const args of [["build"], ["test"], ["check"], ["clippy"], ["nextest", "run"], ["clean"], ["+stable", "bench"]]) {
+    assert.equal(shouldGuardCargo(args), true, args.join(" "));
+  }
+  for (const args of [["fmt", "--check"], ["metadata"], ["tree"], ["fetch"], ["--version"], []]) {
+    assert.equal(shouldGuardCargo(args), false, args.join(" "));
+  }
+  assert.equal(cargoSubcommand(["+stable", "test"]), "test");
+  assert.equal(shouldGuardCargo(["--color", "always", "fmt"]), false);
+  assert.equal(shouldGuardCargo(["--config", "net.git-fetch-with-cli=true", "check"]), true);
+  assert.equal(shouldGuardCargo(["-Z", "unstable-options", "fmt"]), false);
+});
+
+test("Cargo guard resolves real Cargo through rustup or explicit override", () => {
+  assert.equal(resolveRealCargo({ env: { RIGHTSUITE_REAL_CARGO: "/opt/toolchain/cargo" } }), "/opt/toolchain/cargo");
+  const calls = [];
+  const cargo = resolveRealCargo({ env: {}, run: (command, args) => { calls.push([command, args]); return { status: 0, stdout: "/real/cargo\n" }; } });
+  assert.equal(cargo, "/real/cargo");
+  assert.deepEqual(calls[0][1], ["which", "cargo"]);
+});
+
+test("Cargo guard routes heavy and light commands without recursion", async () => {
+  const calls = [];
+  const options = {
+    env: { TEST: "1" },
+    resolveCargo: () => "/real/cargo",
+    runHeavy: async (args, config) => { calls.push(["heavy", args, config.env]); return 0; },
+    runLight: async (command, args, env) => { calls.push(["light", command, args, env]); return 0; },
+  };
+  assert.equal(await runCargoGuard(["test"], options), 0);
+  assert.equal(await runCargoGuard(["fmt", "--check"], options), 0);
+  assert.deepEqual(calls[0], ["heavy", ["--", "/real/cargo", "test"], options.env]);
+  assert.deepEqual(calls[1], ["light", "/real/cargo", ["fmt", "--check"], options.env]);
+});

package/heavy-command.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, 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;
+const SELF = fileURLToPath(import.meta.url);
+
+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 heavyChildDetached({ slot, platform = process.platform } = {}) {
+  return Boolean(slot) && platform !== "win32" && platform !== "win";
+}
+
+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 (error) { return error?.code === "EPERM"; }
+}
+
+function processGroupAlive(pid) {
+  try { process.kill(-Number(pid), 0); return true; } catch (error) { return error?.code === "EPERM"; }
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function readOwner(lockDir) {
+  try {
+    const owner = JSON.parse(readFileSync(path.join(lockDir, "owner.json"), "utf8"));
+    try { return { ...owner, ...JSON.parse(readFileSync(path.join(lockDir, "child.json"), "utf8")) }; } catch { return owner; }
+  } catch { return null; }
+}
+
+function writeTrackedChild(lockDir, owner, child) {
+  const file = path.join(lockDir, "child.json");
+  const temporary = path.join(lockDir, `.child-${owner.token}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(child)}\n`, { mode: 0o600 });
+  renameSync(temporary, file);
+}
+
+export function processStartedAt(pid, { platform = process.platform, run = spawnSync } = {}) {
+  if (!Number.isInteger(Number(pid)) || Number(pid) <= 0) return null;
+  const result = platform === "win32" || platform === "win"
+    ? run("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", `(Get-Process -Id ${Number(pid)} -ErrorAction Stop).StartTime.ToUniversalTime().ToString('o')`], { encoding: "utf8", windowsHide: true })
+    : run("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) return null;
+  const value = Date.parse(String(result.stdout ?? "").trim());
+  return Number.isFinite(value) ? value : null;
+}
+
+export function terminateProcessTree(pid, { platform = process.platform, run = spawnSync, kill = process.kill, treeAlive = processGroupAlive, pause = sleep } = {}) {
+  if (!Number.isInteger(Number(pid)) || Number(pid) <= 0) return;
+  if (platform === "win32" || platform === "win") {
+    run("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    return;
+  }
+  try { kill(-Number(pid), "SIGTERM"); } catch { try { kill(Number(pid), "SIGTERM"); } catch { return; } }
+  pause(500);
+  if (treeAlive(pid)) { try { kill(-Number(pid), "SIGKILL"); } catch { try { kill(Number(pid), "SIGKILL"); } catch { /* gone */ } } }
+}
+
+export async function watchOwnedProcessTree(
+  { root, token, ownerPid, childPid, childStartedAtMs },
+  { alive = processAlive, startedAt = processStartedAt, terminate = terminateProcessTree, pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {},
+) {
+  const lockDir = path.join(root, "slot");
+  while (alive(ownerPid)) {
+    if (readOwner(lockDir)?.token !== token) return false;
+    await pause(500);
+  }
+  const owner = readOwner(lockDir);
+  if (owner?.token !== token || Number(owner.childPid) !== Number(childPid)) return false;
+  if (alive(childPid)) {
+    const observedStart = startedAt(childPid);
+    if (!Number.isFinite(observedStart) || Math.abs(observedStart - Number(childStartedAtMs)) > 2000) {
+      throw new Error(`watcher found reused child pid ${childPid}; refusing termination`);
+    }
+    terminate(childPid);
+  }
+  releaseOwned(lockDir, token);
+  return true;
+}
+
+function spawnOwnerWatcher(details) {
+  const payload = Buffer.from(JSON.stringify(details)).toString("base64url");
+  const watcher = spawn(process.execPath, [SELF, "--watch-owner-base64", payload], {
+    detached: true, env: process.env, stdio: "ignore", windowsHide: true,
+  });
+  watcher.once("error", () => {
+    const observedStart = processStartedAt(details.childPid);
+    if (Number.isFinite(observedStart) && Math.abs(observedStart - Number(details.childStartedAtMs)) <= 2000) {
+      terminateProcessTree(details.childPid);
+    }
+  });
+  watcher.unref();
+}
+
+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),
+  processStartedAt: startedAt = processStartedAt, terminate = terminateProcessTree, startWatcher = spawnOwnerWatcher,
+} = {}) {
+  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) {
+        if (owner?.childPid && alive(owner.childPid)) {
+          const observedStart = startedAt(owner.childPid);
+          if (!Number.isFinite(observedStart) || Math.abs(observedStart - Number(owner.childStartedAtMs)) > 2000) {
+            throw new Error(`dead heavy-work owner pid ${owner.pid}; tracked child pid ${owner.childPid} identity changed; refusing to kill or admit`);
+          }
+          log(`reaping owned process tree pid ${owner.childPid} after owner pid ${owner.pid} exited`);
+          terminate(owner.childPid);
+        }
+        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,
+    trackChild(childPid, childCommand = "") {
+      const owner = readOwner(lockDir);
+      if (owner?.token !== token) throw new Error("heavy-work slot ownership changed before child tracking");
+      const childStartedAtMs = startedAt(childPid);
+      if (!Number.isFinite(childStartedAtMs)) {
+        if (!alive(childPid)) return false;
+        throw new Error(`heavy-work could not verify child pid ${childPid} start time`);
+      }
+      writeTrackedChild(lockDir, owner, { childPid: Number(childPid), childCommand: String(childCommand), childStartedAtMs });
+      startWatcher({ root, token, ownerPid: Number(pid), childPid: Number(childPid), childStartedAtMs });
+      return true;
+    },
+    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), slot); } finally { slot.release(); }
+}
+
+function spawnAttached(command, args, env, slot) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: process.cwd(), env, stdio: "inherit", windowsHide: true, detached: heavyChildDetached({ slot }) });
+    try {
+      if (child.pid && slot) slot.trackChild(child.pid, command);
+    } catch (error) {
+      child.once("error", () => {});
+      if (child.pid) terminateProcessTree(child.pid);
+      reject(error);
+      return;
+    }
+    const handlers = new Map(["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => [signal, () => {
+      if (child.pid) terminateProcessTree(child.pid);
+      process.exitCode = signal === "SIGINT" ? 130 : 143;
+    }]));
+    for (const [signal, handler] of handlers) process.once(signal, handler);
+    const cleanup = () => { for (const [signal, handler] of handlers) process.removeListener(signal, handler); };
+    child.once("error", (error) => { cleanup(); reject(error); });
+    child.once("exit", (code, signal) => { cleanup(); resolve(code ?? (signal ? 1 : 0)); });
+  });
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === SELF) {
+  const args = process.argv.slice(2);
+  const task = args[0] === "--watch-owner-base64"
+    ? watchOwnedProcessTree(JSON.parse(Buffer.from(args[1] || "", "base64url").toString("utf8"))).then(() => 0)
+    : runHeavyCommand(args);
+  task.then((code) => { process.exitCode = code; }).catch((error) => { console.error(`heavy-command: ${error.message}`); process.exitCode = 1; });
+}

package/heavy-command.test.mjs

@@ -0,0 +1,164 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, readFileSync, 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,
+  heavyChildDetached,
+  heavyCommandEnvironment,
+  heavyWorkRoot,
+  parseMacResourceSnapshot,
+  parseWindowsResourceSnapshot,
+  resourceBlockers,
+  runHeavyCommand,
+  systemResourceSnapshot,
+  terminateProcessTree,
+  watchOwnedProcessTree,
+} 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("only the slot owner creates a new POSIX process group", () => {
+  assert.equal(heavyChildDetached({ slot: {}, platform: "mac" }), true);
+  assert.equal(heavyChildDetached({ slot: null, platform: "mac" }), false);
+  assert.equal(heavyChildDetached({ slot: {}, platform: "win" }), false);
+});
+
+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("owned process-tree termination targets a POSIX group or Windows task tree", () => {
+  const signals = [];
+  terminateProcessTree(202, { platform: "mac", kill: (pid, signal) => signals.push([pid, signal]), treeAlive: () => true, pause: () => {} });
+  assert.deepEqual(signals, [[-202, "SIGTERM"], [-202, "SIGKILL"]]);
+  const calls = [];
+  terminateProcessTree(303, { platform: "win", run: (command, args) => calls.push([command, args]) });
+  assert.deepEqual(calls, [["taskkill", ["/PID", "303", "/T", "/F"]]]);
+});
+
+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();
+});
+
+test("dead slot owner reaps its recorded matching child tree", () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), "rightsuite-heavy-owned-"));
+  const killed = [];
+  const options = {
+    root, snapshot: () => ({ freePercent: 50, thermalLimited: false }), log: () => {},
+    alive: (pid) => pid === 202,
+    processStartedAt: (pid) => pid === 202 ? 1234 : null,
+    terminate: (pid) => killed.push(pid),
+    startWatcher: () => {},
+  };
+  const first = acquireHeavyWorkSlot({ ...options, pid: 101 });
+  first.trackChild(202, "cargo");
+  assert.equal(JSON.parse(readFileSync(path.join(root, "slot", "child.json"), "utf8")).childPid, 202);
+  const replacement = acquireHeavyWorkSlot({ ...options, pid: 404 });
+  assert.deepEqual(killed, [202]);
+  replacement.release();
+});
+
+test("dead slot owner refuses to kill a reused child PID", () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), "rightsuite-heavy-reused-"));
+  let observedStart = 1234;
+  const options = {
+    root, snapshot: () => ({ freePercent: 50, thermalLimited: false }), log: () => {},
+    alive: (pid) => pid === 202,
+    processStartedAt: (pid) => pid === 202 ? observedStart : null,
+    terminate: () => assert.fail("reused PID must not be terminated"),
+    startWatcher: () => {},
+  };
+  const first = acquireHeavyWorkSlot({ ...options, pid: 101 });
+  first.trackChild(202, "cargo");
+  observedStart = 5678;
+  assert.throws(() => acquireHeavyWorkSlot({ ...options, pid: 404 }), /identity changed/);
+  first.release();
+});
+
+test("detached watcher reaps an owned child as soon as its owner disappears", async () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), "rightsuite-heavy-watch-"));
+  const lockDir = path.join(root, "slot");
+  mkdirSync(lockDir);
+  writeFileSync(path.join(lockDir, "owner.json"), JSON.stringify({ pid: 101, token: "owned" }));
+  writeFileSync(path.join(lockDir, "child.json"), JSON.stringify({ childPid: 202, childStartedAtMs: 1234 }));
+  const killed = [];
+  const result = await watchOwnedProcessTree(
+    { root, token: "owned", ownerPid: 101, childPid: 202, childStartedAtMs: 1234 },
+    { alive: (pid) => pid === 202, startedAt: () => 1234, terminate: (pid) => killed.push(pid), pause: async () => {} },
+  );
+  assert.equal(result, true);
+  assert.deepEqual(killed, [202]);
+  assert.equal(existsSync(lockDir), false);
+});

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.51",
   "description": "Portable Right Suite release CLI/SDK: signed installers, updater artifacts, patch/update routing, hardening, R2 publish, and RightApps registration.",
   "type": "module",
   "bin": {

package/release-invocation.mjs

@@ -16,7 +16,16 @@ function canonical(file) {
 
 export function assertPrimaryReleaseCheckout(repoRoot) {
   const worktrees = git(repoRoot, ["worktree", "list", "--porcelain"]);
-  const primary = worktrees.match(/^worktree (.+)$/m)?.[1];
+  const gitDir = git(repoRoot, ["rev-parse", "--git-dir"]).trim();
+  const configured = spawnSync("git", ["config", "--path", "--get", "core.worktree"], {
+    cwd: repoRoot, encoding: "utf8", windowsHide: true,
+  });
+  const primary = resolvePrimaryWorktree({
+    repoRoot,
+    worktrees,
+    gitDir,
+    coreWorktree: configured.status === 0 ? configured.stdout.trim() : "",
+  });
   if (!primary) throw new Error("unable to resolve the primary Git worktree");
   if (canonical(repoRoot) !== canonical(primary)) {
     throw new Error(`right-release must be invoked from the primary Git worktree: ${primary}`);
@@ -25,6 +34,16 @@ export function assertPrimaryReleaseCheckout(repoRoot) {
   if (branch.status !== 0) throw new Error("right-release requires a branch-attached primary Git checkout; detached HEAD is forbidden");
 }
 
+export function resolvePrimaryWorktree({ repoRoot, worktrees, gitDir, coreWorktree }) {
+  const listed = worktrees.match(/^worktree (.+)$/m)?.[1];
+  if (!listed) return undefined;
+  const resolvedGitDir = path.resolve(repoRoot, gitDir);
+  if (path.resolve(listed) === resolvedGitDir && coreWorktree) {
+    return path.resolve(resolvedGitDir, coreWorktree);
+  }
+  return listed;
+}
+
 export function resolveConfiguredBuildInputs(config, target, label = "release config") {
   const configured = target?.buildInputs ?? config?.buildInputs;
   if (!Array.isArray(configured?.include) || configured.include.length === 0) {

package/release-invocation.test.mjs

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { resolvePrimaryWorktree } from "./release-invocation.mjs";
+
+test("resolves a submodule primary worktree from core.worktree", () => {
+  assert.equal(resolvePrimaryWorktree({
+    repoRoot: "/suite/membrane",
+    worktrees: "worktree /suite/.git/modules/membrane\nHEAD abc\n",
+    gitDir: "/suite/.git/modules/membrane",
+    coreWorktree: "../../../membrane",
+  }), "/suite/membrane");
+});
+
+test("preserves an ordinary primary worktree", () => {
+  assert.equal(resolvePrimaryWorktree({
+    repoRoot: "/suite/app",
+    worktrees: "worktree /suite/app\nHEAD abc\n",
+    gitDir: "/suite/app/.git",
+    coreWorktree: "",
+  }), "/suite/app");
+});

package/right-suite-contract.test.mjs

@@ -36,6 +36,13 @@ const apps = [
   { key: "coderight", root: "coderight/apps/coderight-tauri", tauri: "src-tauri/tauri.conf.json", releaseFiles: ["scripts/mac-dmg.mjs"] },
 ];
 
+// ScreenRight is intentionally a macOS-only AppKit consumer. It has no Tauri
+// manifest or Windows target, so keep it in an explicit registry lane rather
+// than manufacturing unsupported platform entries.
+const macOnlyApps = [
+  { key: "screenright", root: "tools/screenright", releaseFiles: ["scripts/release-package.mjs"] },
+];
+
 function assertReleasePackageScripts(scripts, label) {
   for (const platform of ["mac", "win"]) {
     assert.equal(scripts[`release:build:${platform}`], `right-release build --platform ${platform}`, `${label} must use the tier-neutral ${platform} build entry point`);
@@ -442,10 +449,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.51",
   });
   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", "0.2.50"],
   });
   assert.ok(
     new Set([versions.npm["@rightkit/release"], ...versions.legacyNpm["@rightkit/release"]]).has("0.2.42"),
@@ -608,6 +615,45 @@ for (const app of apps) {
   });
 }
 
+for (const app of macOnlyApps) {
+  test(`${app.key} follows the macOS-only AppKit Right Release contract`, async () => {
+    const root = path.join(workspace, app.root);
+    const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+    assert.equal(pkg.scripts["release:doctor"], "right-release doctor");
+    assert.equal(pkg.scripts["release:build:mac"], "right-release build --platform mac");
+    assert.equal(pkg.scripts["release:upload:patch:mac"], "right-release upload --platform mac --tier patch");
+    assert.equal(pkg.scripts["release:build:win"], undefined, `${app.key} must not fake a Windows target`);
+    assert.equal(pkg.scripts["release:upload:patch:win"], undefined, `${app.key} must not fake a Windows target`);
+    assert.equal(pkg.scripts["release:upload:update:mac"], undefined, `${app.key} must not expose ungated feature-update upload`);
+    assert.equal(pkg.scripts["release:upload:update:win"], undefined);
+
+    const config = (await import(`${pathToFileURL(path.join(root, "right-release.config.mjs"))}?mac-only=${Date.now()}`)).default;
+    assert.equal(config.app, app.key);
+    assert.deepEqual(Object.keys(config.targets), ["mac"]);
+    assert.equal(config.targets.mac.signed, true);
+    assert.deepEqual(config.targets.mac.publish, {
+      cmd: "right-release",
+      args: ["publish-update", "--config", "right-release.config.mjs", "--platform", "mac"],
+    });
+    assert.equal(config.targets.mac.updater.artifacts.length, 1);
+    const updater = config.targets.mac.updater.artifacts[0];
+    assert.equal(updater.platform, "darwin-aarch64");
+    assert.match(updater.file, /\.dmg$/);
+    assert.equal(updater.signature, `${updater.file}.sig`);
+    assert.equal(updater.key, `${app.key}/updates/mac/current/ScreenRight.dmg`);
+    assertBuildInputs(config, config.targets.mac, `${app.key} mac`);
+    assertMacPackageEntry(config.targets.mac.package, pkg.scripts, app.key);
+    assert.ok(config.targets.mac.installer.artifacts.length >= 1);
+    assert.ok(config.checks.includes("legal:check"), `${app.key} must gate generated legal notices`);
+    assert.deepEqual(config.deps, { workdirs: ["."] });
+    assert.equal(existsSync(path.join(root, "src-tauri", "tauri.conf.json")), false, `${app.key} must not invent a Tauri manifest`);
+    for (const releaseFile of app.releaseFiles) {
+      const source = readFileSync(path.join(root, releaseFile), "utf8");
+      assert.match(source, /mirror-root-artifact/);
+    }
+  });
+}
+
 test("HeardRight and ScrapeRight expose one locked ASR promotion adapter contract", async () => {
   const heard = (await import(`${pathToFileURL(path.join(workspace, "heardright/tauri-app-next/right-release.config.mjs"))}?asr=${Date.now()}`)).default;
   const scrape = (await import(`${pathToFileURL(path.join(workspace, "scraperight/right-release.config.mjs"))}?asr=${Date.now()}`)).default;

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.51"
   },
   "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", "0.2.50"]
   },
   "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);
 }