@rightkit/release 0.2.65 → 0.2.66

package/build-release.mjs

@@ -26,7 +26,8 @@ import { assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInpu
 import { commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, verifySealedRelease, watchProgress } from "./release-state.mjs";
 import { acquireCacheLease, acquireSuiteBuildSlot, applyCachePrune, assertWriteVolumeFloors, inspectCache, inspectWriteVolumes, markCacheEntrySuccessful, planCachePrune, readCachePolicy, resolveCacheLayout, resolveSharedCacheIdentity, resolveSharedCacheRoot } from "./cache-policy.mjs";
 import { createTargetBridge } from "./target-bridge.mjs";
-import { managedCargoShimOnPath } from "./cargo-contract.mjs";
+import { brokerManagedHost } from "./cargo-contract.mjs";
+import { resolveTargetRoot } from "./cargo-target.mjs";
 import { assertNsisInPlaceUpgradeContract } from "./nsis-upgrade-contract.mjs";
 import { buildPathPrefix, collectPreflight, formatPreflight, preflightFailures } from "./preflight.mjs";
 import { assertCleanSource } from "./source-gate.mjs";
@@ -174,13 +175,23 @@ try {
   // shells take the Cache V2 branch, bridge src-tauri/target into the release cache,
   // and then lose CARGO_TARGET_DIR to the broker's unconditional override — so the
   // app bundle landed in the broker workspace and packaging failed on an empty cache.
-  const managedCargoTarget = (process.env.RIGHTKIT_BUILD_BROKER_SOCKET || managedCargoShimOnPath(process.env))
-    ? resolveManagedCargoTarget(cargoToml)
-    : null;
+  const managedCargoTarget = brokerManagedHost(process.env) ? resolveTargetRoot(cargoToml) : null;
   const cacheIdentity = resolveSharedCacheIdentity({ cargoLockPath: cargoLock, cargoTomlPath: cargoToml, rustcVerbose: toolVersions.rustc, targetTriple: target.cargoTarget ?? target.targetTriple ?? target.rustTarget ?? toolVersions.rustHost, profile: target.profile ?? "release" });
   const cacheKey = hashFileText(JSON.stringify({ cache: cacheIdentity.fingerprint, signingIdentity })).slice(0, 16);
-  const cacheMode = process.env.RIGHT_RELEASE_CACHE_MODE ?? (platform === "mac" || platform === "win" ? "shared" : "legacy");
-  if (cacheMode !== "legacy" && cacheMode !== "shared") fail("RIGHT_RELEASE_CACHE_MODE must be legacy or shared");
+  const cacheModeRequested = process.env.RIGHT_RELEASE_CACHE_MODE ?? (platform === "mac" || platform === "win" ? "shared" : "legacy");
+  if (cacheModeRequested !== "legacy" && cacheModeRequested !== "shared") fail("RIGHT_RELEASE_CACHE_MODE must be legacy or shared");
+  // On a broker-managed host, Cache V2's lease/slot/prune/floor/mark chain is not
+  // running against the directory that will actually hold build output — the
+  // broker owns CARGO_TARGET_DIR unconditionally (see managedCargoTarget above).
+  // Leaving cacheMode at "shared" there ran that whole chain against an
+  // essentially unrelated cache root: acquireSuiteBuildSlot/acquireCacheLease
+  // guarded a lock nothing else respects, and assertWriteVolumeFloors could
+  // fail() the build outright on a volume that isn't where the real ~18 GB of
+  // output lives. Force broker so none of that machinery runs.
+  const cacheMode = managedCargoTarget ? "broker" : cacheModeRequested;
+  if (managedCargoTarget && cacheModeRequested === "shared") {
+    console.error("[right-release] broker-managed host: the build broker owns CARGO_TARGET_DIR; Cache V2 shared-cache lease/prune/floor checks skipped");
+  }
   const sharedCacheRoot = cacheMode === "shared" ? resolveSharedCacheRoot({ platform, env: process.env }) : undefined;
   const sharedLayout = cacheMode === "shared"
     ? resolveCacheLayout({ cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, fingerprint: cacheKey, kind: "release" })
@@ -216,9 +227,9 @@ try {
       delete env[name];
     }
   }
-  if (cacheMode === "legacy") delete env.RIGHT_RELEASE_CACHE_OWNER;
+  if (cacheMode !== "shared") 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 (cacheMode !== "shared" && !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 });
@@ -250,6 +261,7 @@ try {
     link: targetLink,
     target: managedCargoTarget ?? env.CARGO_TARGET_DIR,
     ownedRoot: path.dirname(managedCargoTarget ?? env.CARGO_TARGET_DIR),
+    brokerManaged: Boolean(managedCargoTarget),
   });
 
   const result = await targetBridge.run(async () => runBuildStateMachine({
@@ -285,7 +297,13 @@ try {
         throwIfInterrupted();
         const cacheTarget = managedCargoTarget ?? env.CARGO_TARGET_DIR;
         mkdirSync(cacheTarget, { recursive: true });
-        if (cacheMode === "shared") targetBridge.ensure();
+        // Broker-managed hosts route through the same target bridge as shared
+        // mode even though cacheMode is forced to "broker" above: the naive
+        // else-branch below fail()s outright when targetLink is a real
+        // directory, which is exactly the "corruption" misreading that nearly
+        // cost ~5.9 GB of warm broker intermediates. The bridge's brokerManaged
+        // flag already knows to leave a real directory untouched instead.
+        if (cacheMode === "shared" || managedCargoTarget) targetBridge.ensure();
         else if (!existsSync(targetLink)) symlinkSync(cacheTarget, targetLink, process.platform === "win32" ? "junction" : "dir");
         else if (realpathSync(targetLink) !== realpathSync(cacheTarget)) {
           fail(`primary checkout target exists and is not the release cache link: ${targetLink}`);
@@ -427,18 +445,6 @@ function collectToolVersions(packageManager) {
   }
 }
 
-function resolveManagedCargoTarget(manifestPath) {
-  if (!manifestPath) fail("managed release requires a Cargo.toml build input");
-  const output = commandOutputAt(
-    "cargo",
-    ["metadata", "--no-deps", "--offline", "--format-version", "1", "--manifest-path", manifestPath],
-    path.dirname(manifestPath),
-  );
-  const target = JSON.parse(output).target_directory;
-  if (!target || !path.isAbsolute(target)) fail("managed Cargo metadata returned no absolute target directory");
-  return target;
-}
-
 async function runProgress(cmd, runArgs, cwd, env, watchDir, diagnosticPath = null) {
   const inactivityMs = Number(process.env.RIGHT_RELEASE_STALL_MS ?? 10 * 60 * 1000);
   const absoluteMs = Number(process.env.RIGHT_RELEASE_ABSOLUTE_MS ?? 90 * 60 * 1000);

package/build-release.test.mjs

@@ -6,7 +6,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { parseCpuSeconds, processGroupCpuSeconds } from "./process-liveness.mjs";
-import { managedCargoShimOnPath } from "./cargo-contract.mjs";
+import { brokerManagedHost } from "./cargo-contract.mjs";
 
 const source = readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "build-release.mjs"), "utf8");
 const build = path.join(path.dirname(fileURLToPath(import.meta.url)), "build-release.mjs");
@@ -27,7 +27,7 @@ test("macOS and Windows builds default to Cache V2 while explicit legacy mode re
   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, /cacheModeRequested !== "legacy" && cacheModeRequested !== "shared"/);
   assert.match(source, /resolveSharedCacheRoot/);
   assert.match(source, /acquireSuiteBuildSlot/);
   assert.match(source, /acquireHeavyWorkSlot/);
@@ -74,7 +74,30 @@ test("shared Cache V2 target bridge is owned by a finally-cleaned lifecycle", ()
   // next build until someone deletes the link by hand.
   assert.match(source, /ownedRoot: path\.dirname\(managedCargoTarget \?\? env\.CARGO_TARGET_DIR\)/);
   assert.match(source, /targetBridge\.run\(.*runBuildStateMachine/s);
-  assert.match(source, /if \(cacheMode === "shared"\) targetBridge\.ensure\(\)/);
+  // A broker-managed host also routes through the bridge even though cacheMode
+  // is forced to "broker" there — its brokerManaged flag is what keeps a real
+  // (non-symlink) target directory from being treated as corruption.
+  assert.match(source, /if \(cacheMode === "shared" \|\| managedCargoTarget\) targetBridge\.ensure\(\)/);
+});
+
+test("a broker-managed host forces broker cacheMode so Cache V2's lease/prune/floor chain never runs against an unrelated volume", () => {
+  assert.match(
+    source,
+    /const cacheMode = managedCargoTarget \? "broker" : cacheModeRequested;/,
+  );
+  // Every Cache V2 lease/slot/prune/floor/mark call stays gated on cacheMode,
+  // never on cacheModeRequested directly, so forcing cacheMode to "broker" on a
+  // broker host is sufficient to skip all of them without a second gate.
+  for (const guarded of [
+    /acquireSuiteBuildSlot\(\{ layout: sharedLayout/,
+    /cacheLease = acquireCacheLease\(\{ layout: sharedLayout/,
+    /planCachePrune\(\{ snapshot, policy, protectedEntryIds: new Set\(\[sharedLayout\.id\]\) \}\)/,
+    /assertWriteVolumeFloors\(\{ volumes, policy,/,
+    /markCacheEntrySuccessful\(\{ layout: sharedLayout \}\)/,
+  ]) {
+    assert.match(source, guarded);
+  }
+  assert.doesNotMatch(source, /if \(cacheModeRequested === "shared"\) \{\s*\n\s*suiteSlot/);
 });
 
 test("Windows seal and cache identity bind the signing contract, config, and receipts", () => {
@@ -122,16 +145,17 @@ test("CPU sampling degrades to the old behaviour rather than inventing a verdict
 // bridged src-tauri/target into the release cache, and then lost CARGO_TARGET_DIR
 // to the broker's unconditional override. The app built into the broker workspace
 // and packaging failed on an empty cache before notarize/staple.
-const managedHostDetected = (env, platform, exists) =>
-  Boolean(env.RIGHTKIT_BUILD_BROKER_SOCKET || managedCargoShimOnPath(env, platform, exists));
+const managedHostDetected = (env, platform, exists) => brokerManagedHost(env, platform, exists);
 
 test("managed-host gate fires from the managed shim on PATH when no broker socket is exported", () => {
-  // The build gate is exactly the dual detection cargo-contract.mjs already uses.
+  // The build gate is exactly the shared brokerManagedHost predicate cargo-contract.mjs exports,
+  // so there is exactly one definition of "is this a broker-managed host" in the codebase.
   assert.match(
     source,
-    /const managedCargoTarget = \(process\.env\.RIGHTKIT_BUILD_BROKER_SOCKET \|\| managedCargoShimOnPath\(process\.env\)\)\n\s*\? resolveManagedCargoTarget\(cargoToml\)\n\s*: null;/,
+    /const managedCargoTarget = brokerManagedHost\(process\.env\) \? resolveTargetRoot\(cargoToml\) : null;/,
   );
-  assert.match(source, /import \{ managedCargoShimOnPath \} from "\.\/cargo-contract\.mjs";/);
+  assert.match(source, /import \{ brokerManagedHost \} from "\.\/cargo-contract\.mjs";/);
+  assert.match(source, /import \{ resolveTargetRoot \} from "\.\/cargo-target\.mjs";/);
 
   const shim = "/Volumes/D/.rightkit-managed/agent-bin/cargo";
   const exists = (candidate) => candidate === shim;
@@ -151,6 +175,23 @@ test("managed-host gate fires from the managed shim on PATH when no broker socke
   assert.equal(managedHostDetected({ PATH: `/usr/local/bin:${path.dirname(shim)}` }, "darwin", (c) => both.has(c)), false);
 });
 
+test("brokerManagedHost is the single shared predicate: env var alone, shim alone, both, or neither", () => {
+  const shim = "/Volumes/D/.rightkit-managed/agent-bin/cargo";
+  const exists = (candidate) => candidate === shim;
+
+  // Broker socket alone (login shell), no shim resolvable.
+  assert.equal(brokerManagedHost({ RIGHTKIT_BUILD_BROKER_SOCKET: "/managed/broker.sock", PATH: "/usr/bin" }, "darwin", () => false), true);
+  // Shim on PATH alone (agent/non-login shell), no socket exported.
+  assert.equal(brokerManagedHost({ PATH: `${path.dirname(shim)}:/usr/bin` }, "darwin", exists), true);
+  // Both signals present.
+  assert.equal(
+    brokerManagedHost({ RIGHTKIT_BUILD_BROKER_SOCKET: "/managed/broker.sock", PATH: `${path.dirname(shim)}:/usr/bin` }, "darwin", exists),
+    true,
+  );
+  // Neither signal: unmanaged host.
+  assert.equal(brokerManagedHost({ PATH: "/usr/bin:/usr/local/bin" }, "darwin", () => false), false);
+});
+
 test("the managed branch hands the Rust target directory to the broker while the unmanaged branch keeps Cache V2", () => {
   // Managed: CARGO_TARGET_DIR (and the rest of the Cache V2 environment) is deleted
   // from the child environment, so the broker's own override is the only one.
@@ -164,7 +205,9 @@ test("the managed branch hands the Rust target directory to the broker while the
   assert.match(source, /ownedRoot: path\.dirname\(managedCargoTarget \?\? env\.CARGO_TARGET_DIR\),/);
   // The managed target is read from crate metadata through the shim, which is what
   // makes the bridge target equal to the directory the broker actually builds into.
-  assert.match(source, /function resolveManagedCargoTarget\(manifestPath\)[\s\S]*?JSON\.parse\(output\)\.target_directory/);
+  // resolveTargetRoot (cargo-target.mjs) is the single shared implementation —
+  // build-release.mjs no longer defines its own copy.
+  assert.doesNotMatch(source, /function resolveManagedCargoTarget/);
   // Unmanaged (managedCargoTarget === null): Cache V2 still supplies CARGO_TARGET_DIR.
   assert.match(source, /\.\.\.releaseEnvironment\(\{ root: vaultRoot, cacheRoot: sharedCacheRoot,/);
 });

package/cache-command.mjs

@@ -13,12 +13,28 @@ import {
   resolveSharedCacheRoot,
 } from "./cache-policy.mjs";
 import { resolveReleaseLayout } from "./release-state.mjs";
+import { brokerManagedHost } from "./cargo-contract.mjs";
+
+// On a broker-managed host, CARGO_TARGET_DIR is not Cache V2's to own: the build
+// broker unconditionally overrides it to its own per-namespace workspace, so the
+// Cache V2 target layout under cacheRoot is legitimately empty (marker files only)
+// while the real ~18 GB of build output lives in the broker's workspace. Inspecting,
+// migrating, or pruning against that layout on a broker host reads real output as
+// missing/corrupt and can recommend destroying it — never phrase this as a problem.
+const BROKER_MANAGED_MESSAGE = "broker-managed host: the build broker owns CARGO_TARGET_DIR; Cache V2 target checks skipped";
+const BROKER_GATED_COMMANDS = new Set(["status", "prune", "migrate"]);
 
 export async function runCacheCommand(args = process.argv.slice(2), { env = process.env, stdout = console.log, stderr = console.error } = {}) {
   const [command, ...rest] = args;
   const json = rest.includes("--json");
   const platform = platformFrom(env);
   const cacheRoot = resolveSharedCacheRoot({ platform, env });
+  if (BROKER_GATED_COMMANDS.has(command) && brokerManagedHost(env)) {
+    const result = { schema: 1, command, cacheRoot, brokerManaged: true, skipped: true, message: BROKER_MANAGED_MESSAGE };
+    if (json) stdout(JSON.stringify(result));
+    else stdout(BROKER_MANAGED_MESSAGE);
+    return result;
+  }
   if (command === "status") {
     rejectUnknown(rest, new Set(["--json"]));
     const snapshot = inspectCache({ cacheRoot });

package/cache-command.test.mjs

@@ -9,8 +9,24 @@ import { fileURLToPath } from "node:url";
 const root = path.dirname(fileURLToPath(import.meta.url));
 const cli = path.join(root, "cli", "right-release.mjs");
 
+// This suite must exercise the non-broker cache-command path deterministically,
+// regardless of whether the machine running the tests is itself broker-managed
+// (this workspace's own agent shells are: the managed cargo shim sits on PATH).
+// Strip both broker signals from the inherited environment so "unmanaged host"
+// tests stay unmanaged; individual tests opt back into broker signals explicitly.
+function unmanagedEnv(base = process.env) {
+  const sanitized = { ...base };
+  delete sanitized.RIGHTKIT_BUILD_BROKER_SOCKET;
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  sanitized.PATH = String(base.PATH ?? "")
+    .split(delimiter)
+    .filter((entry) => !/(?:^|[/\\])(?:\.rightkit-managed|rightkitmanagedagent)[/\\]agent-bin$/i.test(entry))
+    .join(delimiter);
+  return sanitized;
+}
+
 function run(args, cacheRoot, env = {}) {
-  return spawnSync(process.execPath, [cli, "cache", ...args], { encoding: "utf8", env: { ...process.env, RIGHT_RELEASE_CACHE_ROOT: cacheRoot, ...env } });
+  return spawnSync(process.execPath, [cli, "cache", ...args], { encoding: "utf8", env: { ...unmanagedEnv(), RIGHT_RELEASE_CACHE_ROOT: cacheRoot, ...env } });
 }
 
 test("cache status has human and schema-stable JSON output", () => {
@@ -73,3 +89,30 @@ test("cache migrate uses the repository vault Cargo home, not an app-local looka
   assert.equal(readFileSync(path.join(cacheRoot, "cargo-home", "registry"), "utf8"), "vault");
   assert.equal(readFileSync(path.join(appCargoHome, "registry"), "utf8"), "app-local");
 });
+
+test("status, prune, and migrate short-circuit cleanly on a broker-managed host without proposing a repair", () => {
+  const cacheRoot = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const brokerEnv = { RIGHTKIT_BUILD_BROKER_SOCKET: "/managed/broker.sock" };
+
+  const status = run(["status", "--json"], cacheRoot, brokerEnv);
+  assert.equal(status.status, 0, status.stderr);
+  const statusBody = JSON.parse(status.stdout);
+  assert.equal(statusBody.brokerManaged, true);
+  assert.match(statusBody.message, /broker-managed host/);
+  assert.doesNotMatch(status.stdout + status.stderr, /warn|repair|corrupt/i);
+
+  const prune = run(["prune", "--dry-run", "--json"], cacheRoot, brokerEnv);
+  assert.equal(prune.status, 0, prune.stderr);
+  assert.equal(JSON.parse(prune.stdout).brokerManaged, true);
+
+  // migrate short-circuits before even requiring --config, since a broker host has
+  // nothing under Cache V2's target layout for it to migrate into.
+  const migrate = run(["migrate", "--json"], cacheRoot, brokerEnv);
+  assert.equal(migrate.status, 0, migrate.stderr);
+  assert.equal(JSON.parse(migrate.stdout).brokerManaged, true);
+
+  // Non-broker host: unchanged behaviour.
+  const unmanaged = run(["status", "--json"], cacheRoot);
+  assert.equal(unmanaged.status, 0, unmanaged.stderr);
+  assert.equal(JSON.parse(unmanaged.stdout).brokerManaged, undefined);
+});

package/cache-policy.mjs

@@ -30,21 +30,59 @@ export const CACHE_LOCK_ORDER = ["release", "suite-build-slot", "gc", "entry-lea
 
 const MARKER = ".rightkit-cache-entry.json";
 
-export function resolveSharedCacheRoot({ platform = process.platform, env = process.env, home = os.homedir(), xdgCacheHome } = {}) {
-  const override = env.RIGHT_RELEASE_CACHE_ROOT;
-  if (override) {
-    if (!isAbsoluteForPlatform(override, platform)) throw new Error("RIGHT_RELEASE_CACHE_ROOT must be an absolute path");
-    return resolveForPlatform(override, platform);
-  }
+export function resolveSharedCacheRoot({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
   if (platform === "darwin" || platform === "mac") {
+    const override = env.RIGHT_RELEASE_CACHE_ROOT;
+    if (override) {
+      if (!isAbsoluteForPlatform(override, platform)) throw new Error("RIGHT_RELEASE_CACHE_ROOT must be an absolute path");
+      return resolveForPlatform(override, platform);
+    }
     throw new Error("RIGHT_RELEASE_CACHE_ROOT is required on macOS; set it to external storage");
   }
+  return resolveStableRoot({
+    platform,
+    env,
+    home,
+    explicitOverride: env.RIGHT_RELEASE_CACHE_ROOT,
+    overrideName: "RIGHT_RELEASE_CACHE_ROOT",
+    win32EnvVar: "LOCALAPPDATA",
+    win32Segments: ["RightSuite", "Cache", "release"],
+    otherSegments: ["rightsuite", "release"],
+  });
+}
+
+// resolveStableRoot centralizes platform-native root derivation for both cache roots
+// (waste-tolerant, may split) and lock roots (must never split, or mutual exclusion
+// silently breaks). Route every such root through this one primitive.
+export function resolveStableRoot({
+  platform = process.platform,
+  env = process.env,
+  home = os.homedir(),
+  explicitOverride,
+  overrideName,
+  darwinSegments,
+  win32EnvVar = "LOCALAPPDATA",
+  win32Segments,
+  otherSegments,
+  otherBaseSegments = [".cache"],
+} = {}) {
+  if (explicitOverride) {
+    if (!isAbsoluteForPlatform(explicitOverride, platform)) throw new Error(`${overrideName} must be an absolute path`);
+    return resolveForPlatform(explicitOverride, platform);
+  }
   if (platform === "win32" || platform === "win") {
-    const local = env.LOCALAPPDATA;
-    if (!local || !isAbsoluteForPlatform(local, platform)) throw new Error("LOCALAPPDATA must be an absolute path for the RightSuite cache");
-    return path.win32.resolve(local, "RightSuite", "Cache", "release");
+    const local = env[win32EnvVar];
+    if (!local || !isAbsoluteForPlatform(local, platform)) throw new Error(`${win32EnvVar} must be an absolute path for RightSuite`);
+    return path.win32.resolve(local, ...win32Segments);
+  }
+  if (platform === "darwin" || platform === "mac") {
+    return path.posix.join(home, ...darwinSegments);
   }
-  return path.posix.resolve(xdgCacheHome || env.XDG_CACHE_HOME || path.posix.join(home, ".cache"), "rightsuite", "release");
+  // Never read a shell-profile-scoped variable (XDG_CACHE_HOME, XDG_CONFIG_HOME,
+  // npm_config_cache, etc.) as an implicit default here: those differ between login
+  // and non-login shells, so the same process can resolve to two different roots
+  // depending on how it was launched. Always derive from the OS home directory instead.
+  return path.posix.resolve(path.posix.join(home, ...otherBaseSegments), ...otherSegments);
 }
 
 export function resolveCacheLayout({ cacheRoot, platform, architecture, app, fingerprint, kind = "release" } = {}) {

package/cache-policy.test.mjs

@@ -27,6 +27,7 @@ import {
   resolveCacheLayout,
   resolveSharedCacheIdentity,
   resolveSharedCacheRoot,
+  resolveStableRoot,
 } from "./cache-policy.mjs";
 
 function root() { return path.join(os.tmpdir(), `rightkit-cache-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`); }
@@ -61,11 +62,52 @@ function migrationFixture() {
 test("cache roots are platform-native and overrides must be absolute", () => {
   assert.throws(() => resolveSharedCacheRoot({ platform: "mac", home: "/Users/test", env: {} }), /RIGHT_RELEASE_CACHE_ROOT is required/);
   assert.equal(resolveSharedCacheRoot({ platform: "win", env: { LOCALAPPDATA: "C:/Users/test/AppData/Local" } }), "C:\\Users\\test\\AppData\\Local\\RightSuite\\Cache\\release");
-  assert.equal(resolveSharedCacheRoot({ platform: "linux", home: "/home/test", xdgCacheHome: "/tmp/xdg", env: {} }), "/tmp/xdg/rightsuite/release");
+  assert.equal(resolveSharedCacheRoot({ platform: "linux", home: "/home/test", env: {} }), "/home/test/.cache/rightsuite/release");
   assert.equal(resolveSharedCacheRoot({ platform: "mac", env: { RIGHT_RELEASE_CACHE_ROOT: "/tmp/cache" } }), "/tmp/cache");
   assert.throws(() => resolveSharedCacheRoot({ platform: "mac", env: { RIGHT_RELEASE_CACHE_ROOT: "relative" } }), /absolute/i);
 });
 
+test("shared cache root ignores XDG_CACHE_HOME regardless of value", () => {
+  assert.equal(
+    resolveSharedCacheRoot({ platform: "linux", env: { XDG_CACHE_HOME: "/one/path" }, home: "/home/u" }),
+    resolveSharedCacheRoot({ platform: "linux", env: {}, home: "/home/u" }),
+  );
+  assert.equal(resolveSharedCacheRoot({ platform: "linux", env: { XDG_CACHE_HOME: "/one/path" }, home: "/home/u" }), "/home/u/.cache/rightsuite/release");
+  // resolveSharedCacheRoot no longer accepts an xdgCacheHome option; passing one has no effect.
+  assert.equal(
+    resolveSharedCacheRoot({ platform: "linux", env: {}, home: "/home/u", xdgCacheHome: "/should/be/ignored" }),
+    "/home/u/.cache/rightsuite/release",
+  );
+});
+
+test("resolveStableRoot: explicit override wins, win32 requires the env var, other platforms ignore arbitrary env", () => {
+  const opts = {
+    darwinSegments: ["Library", "Caches", "Example"],
+    win32Segments: ["Example"],
+    otherSegments: ["example"],
+  };
+  assert.equal(
+    resolveStableRoot({ ...opts, platform: "linux", explicitOverride: "/explicit/path", overrideName: "EXAMPLE_ROOT", env: { EXAMPLE_ROOT: "ignored-by-caller-arg" } }),
+    "/explicit/path",
+  );
+  assert.throws(
+    () => resolveStableRoot({ ...opts, platform: "linux", explicitOverride: "relative/path", overrideName: "EXAMPLE_ROOT" }),
+    /EXAMPLE_ROOT must be an absolute path/,
+  );
+  assert.throws(
+    () => resolveStableRoot({ ...opts, platform: "win32", env: {} }),
+    /LOCALAPPDATA must be an absolute path for RightSuite/,
+  );
+  assert.equal(
+    resolveStableRoot({ ...opts, platform: "win32", env: { LOCALAPPDATA: "C:/Users/test/AppData/Local" } }),
+    "C:\\Users\\test\\AppData\\Local\\Example",
+  );
+  assert.equal(
+    resolveStableRoot({ ...opts, platform: "linux", env: { XDG_CACHE_HOME: "/ignored", npm_config_cache: "/ignored" }, home: "/home/u" }),
+    "/home/u/.cache/example",
+  );
+});
+
 test("layout isolates app, platform, kind, and fingerprint", () => {
   const base = root();
   const release = layout(base);

package/cargo-contract.mjs

@@ -27,10 +27,14 @@ export function managedCargoShimOnPath(env = process.env, platform = process.pla
   return false;
 }
 
+export function brokerManagedHost(env = process.env, platform = process.platform, exists = existsSync) {
+  return Boolean(env.RIGHTKIT_BUILD_BROKER_SOCKET) || managedCargoShimOnPath(env, platform, exists);
+}
+
 export function isolatedCargoMetadataEnv(cargoHome, env = process.env, platform = process.platform, exists = existsSync) {
   const metadataEnv = { ...env };
   for (const name of CACHE_V2_ENVIRONMENT) delete metadataEnv[name];
-  if (metadataEnv.RIGHTKIT_BUILD_BROKER_SOCKET || managedCargoShimOnPath(metadataEnv, platform, exists)) return metadataEnv;
+  if (brokerManagedHost(metadataEnv, platform, exists)) return metadataEnv;
   return { ...metadataEnv, CARGO_HOME: cargoHome };
 }
 

package/cargo-guard.mjs

@@ -6,7 +6,8 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { resolveSharedCacheRoot } from "./cache-policy.mjs";
+import { resolveSharedCacheRoot, resolveStableRoot } from "./cache-policy.mjs";
+import { brokerManagedHost } from "./cargo-contract.mjs";
 import { runHeavyCommand } from "./heavy-command.mjs";
 
 const LIGHT_COMMANDS = new Set(["fmt", "metadata", "tree", "fetch", "search", "locate-project", "read-manifest", "help", "version", "--version", "-V"]);
@@ -34,7 +35,14 @@ export function computePolicyPath({ env = process.env, platform = process.platfo
     return path.win32.join(env.LOCALAPPDATA || path.win32.join(home, "AppData", "Local"), "RightSuite", "compute-policy.json");
   }
   if (platform === "darwin" || platform === "mac") return path.join(home, "Library", "Application Support", "RightSuite", "compute-policy.json");
-  return path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "rightsuite", "compute-policy.json");
+  const base = resolveStableRoot({
+    platform,
+    env,
+    home,
+    otherBaseSegments: [".config"],
+    otherSegments: ["rightsuite"],
+  });
+  return path.join(base, "compute-policy.json");
 }
 
 export function loadComputePolicy(options = {}) {
@@ -164,10 +172,18 @@ export function cargoCacheEnvironment(args, {
   const targetOption = args.find((value) => value.startsWith("--target-dir="));
   const targetIndex = args.findIndex((value) => value === "--target-dir");
   const explicitTarget = targetOption?.slice("--target-dir=".length) ?? (targetIndex >= 0 ? args[targetIndex + 1] : null);
-  if (explicitTarget) assertInsideCache(explicitTarget, cacheRoot, "--target-dir", { cwd, platform });
-  const targetDir = env.CARGO_TARGET_DIR
-    ? assertInsideCache(env.CARGO_TARGET_DIR, cacheRoot, "CARGO_TARGET_DIR", { cwd, platform })
-    : defaultTarget;
+  // On a broker-managed host, CARGO_TARGET_DIR is not this cache's to police: the
+  // build broker unconditionally overrides it to its own per-namespace workspace
+  // outside the shared cache root, so asserting it stays inside cacheRoot is a
+  // spurious failure, not a real violation. Pass the broker's own value through
+  // untouched instead of rejecting it.
+  const broker = brokerManagedHost(env, platform, exists);
+  if (explicitTarget && !broker) assertInsideCache(explicitTarget, cacheRoot, "--target-dir", { cwd, platform });
+  const targetDir = broker
+    ? (env.CARGO_TARGET_DIR ?? explicitTarget ?? defaultTarget)
+    : env.CARGO_TARGET_DIR
+      ? assertInsideCache(env.CARGO_TARGET_DIR, cacheRoot, "CARGO_TARGET_DIR", { cwd, platform })
+      : defaultTarget;
   const sccacheDir = env.SCCACHE_DIR
     ? assertInsideCache(env.SCCACHE_DIR, cacheRoot, "SCCACHE_DIR", { cwd, platform })
     : defaultSccache;

package/cargo-guard.test.mjs

@@ -2,7 +2,15 @@ import assert from "node:assert/strict";
 import path from "node:path";
 import test from "node:test";
 
-import { assertComputePolicyAllowsCargo, cargoCacheEnvironment, cargoProjectRoot, cargoSubcommand, checkHookInput, resolveRealCargo, resolveRealRustc, runCargoGuard, shellRunsCargoTest, shouldGuardCargo } from "./cargo-guard.mjs";
+import { assertComputePolicyAllowsCargo, cargoCacheEnvironment, cargoProjectRoot, cargoSubcommand, checkHookInput, computePolicyPath, resolveRealCargo, resolveRealRustc, runCargoGuard, shellRunsCargoTest, shouldGuardCargo } from "./cargo-guard.mjs";
+
+test("compute policy path ignores XDG_CONFIG_HOME regardless of value", () => {
+  assert.equal(
+    computePolicyPath({ platform: "linux", env: { XDG_CONFIG_HOME: "/one/path" }, home: "/home/u" }),
+    computePolicyPath({ platform: "linux", env: {}, home: "/home/u" }),
+  );
+  assert.equal(computePolicyPath({ platform: "linux", env: {}, home: "/home/u" }), path.join("/home/u/.config/rightsuite", "compute-policy.json"));
+});
 
 test("Cargo guard serializes compiling commands but bypasses inspection and formatting", () => {
   for (const args of [["build"], ["test"], ["check"], ["clippy"], ["nextest", "run"], ["clean"], ["+stable", "bench"]]) {
@@ -122,6 +130,30 @@ test("Cargo guard rejects cache bypasses and permits RightKit-owned cache paths"
   assert.equal(env.CARGO_TARGET_DIR, "/cache/test-targets/app");
 });
 
+test("Cargo guard passes a broker-owned CARGO_TARGET_DIR through instead of rejecting it", () => {
+  const base = { cwd: "/repo", platform: "mac", exists: () => false };
+  // Outside the shared cache root, which would be rejected on a non-broker host
+  // (see the previous test) — but the broker owns this value, not Cache V2.
+  const env = cargoCacheEnvironment(["test"], {
+    ...base,
+    env: { RIGHT_RELEASE_CACHE_ROOT: "/cache", RIGHTKIT_BUILD_BROKER_SOCKET: "/managed/broker.sock", CARGO_TARGET_DIR: "/broker/workspace/target" },
+  });
+  assert.equal(env.CARGO_TARGET_DIR, "/broker/workspace/target");
+
+  // Same for an explicit --target-dir outside the cache root.
+  const explicit = cargoCacheEnvironment(["test", "--target-dir", "/broker/workspace/target"], {
+    ...base,
+    env: { RIGHT_RELEASE_CACHE_ROOT: "/cache", RIGHTKIT_BUILD_BROKER_SOCKET: "/managed/broker.sock" },
+  });
+  assert.doesNotThrow(() => explicit);
+
+  // Non-broker host: unchanged, still rejects the cache bypass.
+  assert.throws(
+    () => cargoCacheEnvironment(["test"], { ...base, env: { RIGHT_RELEASE_CACHE_ROOT: "/cache", CARGO_TARGET_DIR: "/tmp/target" } }),
+    /CARGO_TARGET_DIR must stay inside/,
+  );
+});
+
 test("Cargo guard derives native Windows cache paths", () => {
   const env = cargoCacheEnvironment(["build"], {
     cwd: "D:\\Claude\\citadel", platform: "win", exists: (file) => file === "D:\\Claude\\citadel\\Cargo.toml",

package/cargo-target.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Resolves the Cargo target directory for a manifest by asking Cargo itself.
+//
+// `cargo metadata` is authoritative on BOTH broker-managed and unmanaged
+// hosts: through a managed shim it reports the broker's own workspace target
+// directory; without one it reports the local `target/` directory. LOCATING
+// the target directory therefore never needs broker detection — the metadata
+// command already reflects whichever host it runs on. `brokerManagedHost()`
+// (see cargo-contract.mjs) remains a separate, cache-policy-only decision:
+// whether Cache V2's lease/slot/prune/floor machinery should run at all, not
+// where the target directory lives.
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function resolveTargetRoot(manifestPath) {
+  if (!manifestPath) throw new Error("resolveTargetRoot requires a Cargo.toml manifest path");
+  let output;
+  try {
+    output = execFileSync(
+      "cargo",
+      ["metadata", "--offline", "--format-version", "1", "--no-deps", "--manifest-path", manifestPath],
+      { cwd: path.dirname(manifestPath), encoding: "utf8", maxBuffer: 64 * 1024 * 1024 },
+    );
+  } catch (error) {
+    throw new Error(`metadata failed for ${manifestPath}: ${error.message}`);
+  }
+  const { target_directory: directory } = JSON.parse(output);
+  if (typeof directory !== "string" || directory.length === 0 || !path.isAbsolute(directory)) {
+    throw new Error(`metadata for ${manifestPath} did not report an absolute target_directory`);
+  }
+  return path.resolve(directory);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  const manifestPath = process.argv[2];
+  if (!manifestPath) {
+    console.error("usage: cargo-target.mjs <path-to-Cargo.toml>");
+    process.exit(1);
+  }
+  try {
+    process.stdout.write(`${resolveTargetRoot(manifestPath)}\n`);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}

package/cargo-target.test.mjs

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { resolveTargetRoot } from "./cargo-target.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const cli = path.join(here, "cargo-target.mjs");
+
+// A fake `cargo` on PATH, ahead of the real one, so metadata success/failure
+// shapes are deterministic and don't depend on the host's actual crate graph.
+// It branches on a marker embedded in the manifest path so each test controls
+// its own outcome independently.
+function fakeCargoBin() {
+  const bin = mkdtempSync(path.join(os.tmpdir(), "rightkit-fake-cargo-"));
+  const script = path.join(bin, process.platform === "win32" ? "cargo.cmd" : "cargo");
+  const body = process.platform === "win32"
+    ? [
+      "@echo off",
+      "setlocal enabledelayedexpansion",
+      "set ARGS=%*",
+      "echo %ARGS% | findstr /C:\"fail-manifest\" >nul && (echo boom 1>&2 & exit /b 1)",
+      "echo %ARGS% | findstr /C:\"bad-target-manifest\" >nul && (echo {\"target_directory\":\"relative/target\"} & exit /b 0)",
+      "echo {\"target_directory\":\"" + path.join(bin, "target").replaceAll("\\", "\\\\") + "\"}",
+    ].join("\r\n")
+    : [
+      "#!/bin/sh",
+      'case "$*" in',
+      '  *fail-manifest*) echo boom 1>&2; exit 1 ;;',
+      '  *bad-target-manifest*) echo \'{"target_directory":"relative/target"}\'; exit 0 ;;',
+      `  *) echo '{"target_directory":"${path.join(bin, "target")}"}'; exit 0 ;;`,
+      "esac",
+    ].join("\n");
+  writeFileSync(script, body);
+  if (process.platform !== "win32") chmodSync(script, 0o755);
+  return bin;
+}
+
+function withFakeCargo(fn) {
+  const bin = fakeCargoBin();
+  const env = { ...process.env, PATH: `${bin}${path.delimiter}${process.env.PATH ?? ""}` };
+  return fn({ bin, env });
+}
+
+test("resolveTargetRoot returns the absolute target_directory Cargo metadata reports", () => {
+  withFakeCargo(({ bin, env }) => {
+    const manifestDir = mkdtempSync(path.join(os.tmpdir(), "rightkit-cargo-target-fixture-"));
+    const manifest = path.join(manifestDir, "Cargo.toml");
+    writeFileSync(manifest, "[package]\nname = \"fixture\"\nversion = \"0.0.0\"\n");
+    const previousPath = process.env.PATH;
+    process.env.PATH = env.PATH;
+    try {
+      const result = resolveTargetRoot(manifest);
+      assert.equal(result, path.resolve(path.join(bin, "target")));
+    } finally {
+      process.env.PATH = previousPath;
+    }
+  });
+});
+
+test("resolveTargetRoot fails closed, naming the manifest, when target_directory is not absolute", () => {
+  withFakeCargo(({ env }) => {
+    const manifestDir = mkdtempSync(path.join(os.tmpdir(), "rightkit-cargo-target-fixture-"));
+    const manifest = path.join(manifestDir, "bad-target-manifest-Cargo.toml");
+    writeFileSync(manifest, "[package]\nname = \"fixture\"\nversion = \"0.0.0\"\n");
+    const previousPath = process.env.PATH;
+    process.env.PATH = env.PATH;
+    try {
+      assert.throws(
+        () => resolveTargetRoot(manifest),
+        new RegExp(`metadata for .*bad-target-manifest-Cargo\\.toml did not report an absolute target_directory`),
+      );
+    } finally {
+      process.env.PATH = previousPath;
+    }
+  });
+});
+
+test("resolveTargetRoot fails closed, naming the manifest, when the metadata command exits non-zero", () => {
+  withFakeCargo(({ env }) => {
+    const manifestDir = mkdtempSync(path.join(os.tmpdir(), "rightkit-cargo-target-fixture-"));
+    const manifest = path.join(manifestDir, "fail-manifest-Cargo.toml");
+    writeFileSync(manifest, "[package]\nname = \"fixture\"\nversion = \"0.0.0\"\n");
+    const previousPath = process.env.PATH;
+    process.env.PATH = env.PATH;
+    try {
+      assert.throws(
+        () => resolveTargetRoot(manifest),
+        new RegExp(`metadata failed for .*fail-manifest-Cargo\\.toml`),
+      );
+    } finally {
+      process.env.PATH = previousPath;
+    }
+  });
+});
+
+test("resolveTargetRoot throws when no manifest path is given", () => {
+  assert.throws(() => resolveTargetRoot(), /resolveTargetRoot requires a Cargo.toml manifest path/);
+  assert.throws(() => resolveTargetRoot(""), /resolveTargetRoot requires a Cargo.toml manifest path/);
+});
+
+test("CLI mode writes only the resolved path to stdout on success", () => {
+  withFakeCargo(({ bin, env }) => {
+    const manifestDir = mkdtempSync(path.join(os.tmpdir(), "rightkit-cargo-target-fixture-"));
+    const manifest = path.join(manifestDir, "Cargo.toml");
+    writeFileSync(manifest, "[package]\nname = \"fixture\"\nversion = \"0.0.0\"\n");
+    const result = spawnSync(process.execPath, [cli, manifest], { encoding: "utf8", env });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout.trim(), path.resolve(path.join(bin, "target")));
+  });
+});
+
+test("CLI mode writes a message to stderr and exits 1 on failure", () => {
+  withFakeCargo(({ env }) => {
+    const manifestDir = mkdtempSync(path.join(os.tmpdir(), "rightkit-cargo-target-fixture-"));
+    const manifest = path.join(manifestDir, "fail-manifest-Cargo.toml");
+    writeFileSync(manifest, "[package]\nname = \"fixture\"\nversion = \"0.0.0\"\n");
+    const result = spawnSync(process.execPath, [cli, manifest], { encoding: "utf8", env });
+    assert.equal(result.status, 1);
+    assert.equal(result.stdout, "");
+    assert.match(result.stderr, /metadata failed for .*fail-manifest-Cargo\.toml/);
+  });
+});
+
+test("CLI mode requires a manifest argument", () => {
+  const result = spawnSync(process.execPath, [cli], { encoding: "utf8" });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /usage: cargo-target\.mjs/);
+});

package/cli/right-release.mjs

@@ -20,6 +20,7 @@ const commands = new Map([
   ["create-mac-updater", "create-mac-updater.mjs"],
   ["mirror-root-artifact", "mirror-root-artifact.mjs"],
   ["github", "github-release.mjs"],
+  ["cargo-target", "cargo-target.mjs"],
 ]);
 
 const args = process.argv.slice(2);

package/heavy-command.mjs

@@ -6,17 +6,23 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 
+import { resolveStableRoot } from "./cache-policy.mjs";
+
 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.posix.join(home, "Library", "Caches", "RightSuite", "heavy-work");
-  return path.posix.resolve(env.XDG_CACHE_HOME || path.posix.join(home, ".cache"), "rightsuite", "heavy-work");
+  return resolveStableRoot({
+    platform,
+    env,
+    home,
+    explicitOverride: env.RIGHTSUITE_HEAVY_WORK_ROOT,
+    overrideName: "RIGHTSUITE_HEAVY_WORK_ROOT",
+    darwinSegments: ["Library", "Caches", "RightSuite", "heavy-work"],
+    win32EnvVar: "LOCALAPPDATA",
+    win32Segments: ["RightSuite", "heavy-work"],
+    otherSegments: ["rightsuite", "heavy-work"],
+  });
 }
 
 export function heavyCommandEnvironment(env = process.env) {

package/heavy-command.test.mjs

@@ -26,6 +26,14 @@ test("heavy-work root is machine-wide rather than repository-local", () => {
   assert.equal(heavyWorkRoot({ platform: "win", env: { LOCALAPPDATA: "C:\\Users\\test\\AppData\\Local" } }), "C:\\Users\\test\\AppData\\Local\\RightSuite\\heavy-work");
 });
 
+test("heavy-work root ignores XDG_CACHE_HOME regardless of value", () => {
+  assert.equal(
+    heavyWorkRoot({ platform: "linux", env: { XDG_CACHE_HOME: "/one/path" }, home: "/home/u" }),
+    heavyWorkRoot({ platform: "linux", env: {}, home: "/home/u" }),
+  );
+  assert.equal(heavyWorkRoot({ platform: "linux", env: {}, home: "/home/u" }), "/home/u/.cache/rightsuite/heavy-work");
+});
+
 test("heavy commands default compiler and test concurrency to two", () => {
   const env = heavyCommandEnvironment({});
   assert.equal(env.CARGO_BUILD_JOBS, "2");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.65",
+  "version": "0.2.66",
   "description": "Portable Right Suite release CLI/SDK: native-host signed installers, updater artifacts, hardening, immutable GitHub Release upload, and add-on adoption.",
   "license": "MIT OR Apache-2.0",
   "type": "module",

package/preflight.mjs

@@ -21,6 +21,7 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { brokerManagedHost } from "./cargo-contract.mjs";
 
 export const PREFLIGHT_OK = "ok";
 export const PREFLIGHT_WARN = "warn";
@@ -186,11 +187,18 @@ export function collectPreflight({
     checks.push(
       !entry || entry.isSymbolicLink()
         ? ok("target-bridge", entry ? "src-tauri/target is a symbolic link" : "src-tauri/target is ready for the shared cache bridge")
-        : fail(
-            "target-bridge",
-            `${target} is a real directory; bridge setup will refuse it`,
-            `run right-release cache migrate --config ${JSON.stringify(configPath ?? path.join(appRoot, "right-release.config.mjs"))} --dry-run, then repeat with --apply before building`,
-          ),
+        // A real directory here is not corruption on a broker-managed host: the
+        // build broker owns CARGO_TARGET_DIR and this is its own output (or a
+        // leftover from before it took ownership), not Cache V2's bridge target.
+        // Recommending `cache migrate` here is how an agent nearly renamed ~5.9 GB
+        // of warm broker intermediates out from under it.
+        : brokerManagedHost(env)
+          ? ok("target-bridge", `${target} is a real directory; broker-managed host, left untouched`)
+          : fail(
+              "target-bridge",
+              `${target} is a real directory; bridge setup will refuse it`,
+              `run right-release cache migrate --config ${JSON.stringify(configPath ?? path.join(appRoot, "right-release.config.mjs"))} --dry-run, then repeat with --apply before building`,
+            ),
     );
   }
 

package/release-state.mjs

@@ -82,7 +82,7 @@ function watchDirectoryTree(root, onProgress, watchers, fallback, { watchFactory
 
 export function releaseEnvironment({ root, cacheRoot, platform, architecture, app, cacheKey, kind = "release", appRoot, mode = "legacy", env = process.env }) {
   if (kind !== "release" && kind !== "test") throw new Error(`invalid target kind: ${kind}`);
-  if (mode !== "legacy" && mode !== "shared") throw new Error(`invalid cache mode: ${mode}`);
+  if (mode !== "legacy" && mode !== "shared" && mode !== "broker") throw new Error(`invalid cache mode: ${mode}`);
   if (mode === "shared") {
     if (!cacheRoot || !platform || !architecture || !app || !cacheKey || !appRoot) throw new Error("shared release environment requires cacheRoot, platform, architecture, app, cacheKey, and appRoot");
     const layout = resolveCacheLayout({ cacheRoot, platform, architecture, app, fingerprint: cacheKey, kind });

package/release.test.mjs

@@ -134,21 +134,39 @@ function lockFixture() {
   return { dir, config };
 }
 
+// This suite must exercise the non-broker path deterministically regardless of
+// whether the machine running the tests is itself broker-managed (this
+// workspace's own agent shells are: the managed cargo shim sits on PATH).
+// Strip both broker signals from the inherited environment before spawning.
+function unmanagedEnv() {
+  const sanitized = { ...process.env };
+  delete sanitized.RIGHTKIT_BUILD_BROKER_SOCKET;
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  sanitized.PATH = String(process.env.PATH ?? "")
+    .split(delimiter)
+    .filter((entry) => !/(?:^|[/\\])(?:\.rightkit-managed|rightkitmanagedagent)[/\\]agent-bin$/i.test(entry))
+    .join(delimiter);
+  return sanitized;
+}
+
 function run(config, ...args) {
   return spawnSync(process.execPath, [release, "--config", config, "--platform", "win", "--dry-run", ...args], {
     encoding: "utf8",
+    env: unmanagedEnv(),
   });
 }
 
 function runRaw(config, ...args) {
   return spawnSync(process.execPath, [release, "--config", config, ...args], {
     encoding: "utf8",
+    env: unmanagedEnv(),
   });
 }
 
 function runDoctor(config, ...args) {
   return spawnSync(process.execPath, [cli, "doctor", "--config", config, "--platform", hostPlatform, ...args], {
     encoding: "utf8",
+    env: unmanagedEnv(),
   });
 }
 
@@ -284,6 +302,18 @@ test("doctor rejects a real src-tauri target before release work", () => {
   assert.match(`${result.stdout}\n${result.stderr}`, /target-bridge[\s\S]*real directory[\s\S]*cache migrate/i);
 });
 
+test("doctor accepts a real src-tauri target on a broker-managed host instead of proposing cache migrate", () => {
+  const config = fixture({ platform: hostPlatform });
+  mkdirSync(path.join(path.dirname(config), "src-tauri", "target"));
+  const result = spawnSync(process.execPath, [cli, "doctor", "--config", config, "--platform", hostPlatform], {
+    encoding: "utf8",
+    env: { ...unmanagedEnv(), RIGHTKIT_BUILD_BROKER_SOCKET: "/managed/broker.sock" },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(`${result.stdout}\n${result.stderr}`, /cache migrate/i);
+  assert.match(result.stdout, /target-bridge[\s\S]*broker-managed host, left untouched/i);
+});
+
 test("doctor permits unrelated dirt", () => {
   const config = fixture({ platform: hostPlatform });
   const root = path.dirname(config);

package/right-suite-contract.test.mjs

@@ -47,6 +47,24 @@ const macOnlyApps = [
   { key: "screenright", root: "tools/screenright", releaseFiles: ["scripts/release-package.mjs"] },
 ];
 
+// Consuming suite apps whose packaging/build scripts must resolve Cargo build
+// output from `cargo metadata`'s `target_directory`, never by reading
+// CARGO_TARGET_DIR (or a shell/PowerShell equivalent) directly to locate it.
+// This defect recurred three times across the suite (broker-managed hosts own
+// CARGO_TARGET_DIR, so a stale/wrong value silently reads the wrong tree).
+// rightsites and tools/screenright are intentionally out of scope here.
+const cargoTargetDirGuardApps = [
+  "coderight/apps/coderight-tauri",
+  "cutright/apps/studio",
+  "genright",
+  "heardright/tauri-app-next",
+  "mailright",
+  "membrane/apps/membrane-hub",
+  "orthic",
+  "scraperight",
+  "viewright",
+];
+
 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`);
@@ -468,12 +486,12 @@ test("RightKit exposes one current version manifest", () => {
     "@rightkit/legal": "0.3.0",
     "@rightkit/legal-ui": "0.1.1",
     "@rightkit/license": "0.1.6",
-    "@rightkit/release": "0.2.65",
+    "@rightkit/release": "0.2.66",
     "@rightkit/qa": "0.2.0",
   });
   assert.deepEqual(versions.legacyNpm, {
     "@rightkit/legal-ui": ["0.1.0"],
-    "@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", "0.2.51", "0.2.53", "0.2.54", "0.2.55", "0.2.56", "0.2.61", "0.2.62", "0.2.63", "0.2.64"],
+    "@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", "0.2.51", "0.2.53", "0.2.54", "0.2.55", "0.2.56", "0.2.61", "0.2.62", "0.2.63", "0.2.64", "0.2.65"],
     "@rightkit/qa": ["0.1.0"],
   });
   assert.ok(
@@ -769,6 +787,113 @@ function readCanonicalCrateVersions() {
   );
 }
 
+const CARGO_TARGET_DIR_GUARD_EXTENSIONS = new Set([".mjs", ".js", ".ts", ".sh", ".ps1"]);
+const CARGO_TARGET_DIR_GUARD_ALLOW_MARKER = /rightkit-allow-cargo-target-dir:\s*\S/;
+// Test/contract files assert *about* the CARGO_TARGET_DIR pattern (e.g. inside
+// a regex literal passed to assert.match/assert.doesNotMatch) rather than
+// locating build output with it; they are not packaging/build scripts.
+const CARGO_TARGET_DIR_GUARD_SKIP_BASENAME = /(?:^test-.*|\.test)\.(?:mjs|js|ts)$/;
+
+function cargoTargetDirGuardPatternFor(extension) {
+  if (extension === ".ps1") return /\$env:CARGO_TARGET_DIR\b/;
+  if (extension === ".sh") return /\$\{?CARGO_TARGET_DIR\b/;
+  return /process\.env(?:\.CARGO_TARGET_DIR\b|\[["']CARGO_TARGET_DIR["']\])/;
+}
+
+function findCargoTargetDirGuardFiles(root) {
+  const found = [];
+  const visit = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory() && ["node_modules", "target", "vendor", ".git", ".cache", ".right-release"].includes(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (entry.isFile() && CARGO_TARGET_DIR_GUARD_EXTENSIONS.has(path.extname(entry.name))) found.push(full);
+    }
+  };
+  const scriptsDir = path.join(root, "scripts");
+  if (existsSync(scriptsDir)) visit(scriptsDir);
+  for (const topLevel of ["package.sh", "package.ps1"]) {
+    const candidate = path.join(root, topLevel);
+    if (existsSync(candidate)) found.push(candidate);
+  }
+  return found;
+}
+
+test("consuming suite apps resolve Cargo build output from cargo metadata, never CARGO_TARGET_DIR directly", () => {
+  for (const appRoot of cargoTargetDirGuardApps) {
+    const root = path.join(workspace, appRoot);
+    if (!existsSync(root)) continue;
+    for (const filePath of findCargoTargetDirGuardFiles(root)) {
+      const basename = path.basename(filePath);
+      if (CARGO_TARGET_DIR_GUARD_SKIP_BASENAME.test(basename)) continue;
+      const extension = path.extname(filePath);
+      const pattern = cargoTargetDirGuardPatternFor(extension);
+      const lines = readFileSync(filePath, "utf8").split("\n");
+      const relativePath = path.relative(workspace, filePath);
+      lines.forEach((line, index) => {
+        if (!pattern.test(line)) return;
+        if (/^\s*(?:\/\/|#)/.test(line)) return; // prose describing the pattern, not code reading it
+        const previousLine = index > 0 ? lines[index - 1] : "";
+        const allowed = CARGO_TARGET_DIR_GUARD_ALLOW_MARKER.test(line) || CARGO_TARGET_DIR_GUARD_ALLOW_MARKER.test(previousLine);
+        assert.ok(
+          allowed,
+          `${relativePath}:${index + 1} reads CARGO_TARGET_DIR directly to locate Cargo build output: \`${line.trim()}\`\n`
+          + "resolve build output from `cargo metadata`'s `target_directory`; the environment is never authoritative for locating output.\n"
+          + "add a `rightkit-allow-cargo-target-dir: <reason>` marker on this line (or the line above) only if this use is not locating output.",
+        );
+      });
+    }
+  }
+});
+
+// The shared resolver helpers themselves must keep asking cargo metadata for
+// target_directory. Guarding only the wrong pattern's reintroduction is not
+// enough — gutting/deleting the correct implementation must also fail here.
+const cargoTargetRootHelpers = [
+  "coderight/apps/coderight-tauri/scripts/lib/target-root.mjs",
+  "heardright/tauri-app-next/scripts/lib/target-root.mjs",
+  "mailright/scripts/lib/target-root.mjs",
+  "orthic/scripts/lib/target-root.mjs",
+  "viewright/scripts/lib/target-root.mjs",
+  "membrane/apps/membrane-hub/scripts/lib/target-root.mjs",
+];
+
+test("shared target-root helpers still resolve build output via cargo metadata's target_directory", () => {
+  for (const helperPath of cargoTargetRootHelpers) {
+    const appRoot = path.join(workspace, helperPath.split("/scripts/lib/target-root.mjs")[0]);
+    if (!existsSync(appRoot)) continue;
+    const fullPath = path.join(workspace, helperPath);
+    assert.ok(existsSync(fullPath), `${helperPath} is missing; the app must keep its shared cargo-metadata target resolver`);
+    const source = readFileSync(fullPath, "utf8");
+    assert.match(source, /cargo/, `${helperPath} must invoke cargo`);
+    assert.match(source, /metadata/, `${helperPath} must call cargo metadata`);
+    assert.match(source, /target_directory/, `${helperPath} must read target_directory from cargo metadata's output`);
+  }
+});
+
+// After the app migration lands, every consuming app's target-root helper must
+// become a thin re-export of the shared tools/rightkit resolveTargetRoot
+// (cargo-target.mjs) rather than its own copy of the cargo-metadata call. Until
+// that migration lands, cargoTargetRootHelpers above still point at full local
+// implementations, so this stays skipped to avoid failing the still-unmigrated
+// app repos. Enable it once every app's target-root.mjs is a re-export shim.
+test("consuming app target-root helpers are thin re-export shims, not local resolver re-implementations", { skip: true }, () => {
+  const LOCAL_RESOLVER_PATTERN = /function\s+(?:cargoTargetRoot|resolveManagedCargoTarget)\s*\([^)]*\)\s*\{[^}]*cargo[^}]*metadata/s;
+  for (const helperPath of cargoTargetRootHelpers) {
+    const appRoot = path.join(workspace, helperPath.split("/scripts/lib/target-root.mjs")[0]);
+    if (!existsSync(appRoot)) continue;
+    const fullPath = path.join(workspace, helperPath);
+    if (!existsSync(fullPath)) continue;
+    const source = readFileSync(fullPath, "utf8");
+    assert.doesNotMatch(
+      source,
+      LOCAL_RESOLVER_PATTERN,
+      `${helperPath} must re-export @rightkit/release's resolveTargetRoot instead of reimplementing the cargo metadata call locally`,
+    );
+  }
+});
+
 test("Right Suite has no hosted workflow files", () => {
   for (const root of ["viewright", "scraperight", "heardright", "mailright", "coderight", "genright", "voiceright", "tools/rightkit"]) {
     const workflowDir = path.join(workspace, root, ".github", "workflows");

package/rightkit-versions.json

@@ -19,7 +19,7 @@
     "@rightkit/legal": "0.3.0",
     "@rightkit/legal-ui": "0.1.1",
     "@rightkit/license": "0.1.6",
-    "@rightkit/release": "0.2.65",
+    "@rightkit/release": "0.2.66",
     "@rightkit/qa": "0.2.0"
   },
   "legacyNpm": {
@@ -47,7 +47,8 @@
       "0.2.61",
       "0.2.62",
       "0.2.63",
-      "0.2.64"
+      "0.2.64",
+      "0.2.65"
     ],
     "@rightkit/qa": [
       "0.1.0"

package/target-bridge.mjs

@@ -9,12 +9,21 @@ import path from "node:path";
  *   fingerprint change — i.e. every Cargo.lock or version bump — left a stale
  *   link that hard-stopped the next build until someone deleted it by hand.
  *   Omit it to keep the strict refuse-everything behavior.
+ * @param brokerManaged True when a build broker owns CARGO_TARGET_DIR on this
+ *   host. A real (non-symlink) directory at `link` is then not corruption to
+ *   repair — it is the broker's own build output, or a leftover from before the
+ *   broker took ownership, and either way is not this bridge's to touch. The
+ *   non-broker path used to name that same directory "corrupt" and point at
+ *   `cache migrate`, which renames it away; on a broker host that came within
+ *   one step of moving ~5.9 GB of warm intermediates the broker still expects
+ *   to find in place. Leave it untouched instead.
  */
 export function createTargetBridge({
   link,
   target,
   ownedRoot,
   platform = process.platform,
+  brokerManaged = false,
   lstat = lstatSync,
   mkdir = mkdirSync,
   realpath = realpathSync,
@@ -29,6 +38,7 @@ export function createTargetBridge({
     ensure() {
       let entry = readEntry(link, lstat);
       if (entry && !entry.isSymbolicLink()) {
+        if (brokerManaged) return { created: false, link, target, brokerManaged: true };
         throw new Error(
           `primary checkout target is not a symbolic link; refusing to replace it: ${link}\n` +
             `  It is a real directory holding build output. Run right-release cache migrate before building.`,

package/target-bridge.test.mjs

@@ -160,6 +160,41 @@ test("rejecting a real target does not create the shared cache destination", ()
   assert.equal(existsSync(target), false);
 });
 
+test("broker-managed: a real target directory is left untouched instead of treated as corruption", async () => {
+  const fx = fixture();
+  mkdirSync(fx.link);
+  writeFileSync(path.join(fx.link, "user.txt"), "keep\n");
+  const result = await createTargetBridge({ ...fx, brokerManaged: true }).run(async (bridge) => bridge.ensure());
+  assert.equal(result.brokerManaged, true);
+  assert.equal(result.created, false);
+  // Nothing was removed, replaced, or relinked: the real directory and its
+  // content are exactly as they were, and no shared-cache destination was
+  // fabricated in its place.
+  assert.equal(readFileSync(path.join(fx.link, "user.txt"), "utf8"), "keep\n");
+  assert.equal(lstatSync(fx.link).isSymbolicLink(), false);
+});
+
+test("broker-managed: release() is a safe no-op after leaving a real target untouched", () => {
+  const fx = fixture();
+  mkdirSync(fx.link);
+  writeFileSync(path.join(fx.link, "user.txt"), "keep\n");
+  const bridge = createTargetBridge({ ...fx, brokerManaged: true });
+  bridge.ensure();
+  assert.equal(bridge.release(), false);
+  assert.equal(readFileSync(path.join(fx.link, "user.txt"), "utf8"), "keep\n");
+});
+
+test("broker-managed has no effect on the non-broker path: a symlink bridge still behaves exactly as before", async () => {
+  const fx = fixture();
+  const result = await createTargetBridge({ ...fx, brokerManaged: true }).run(async (bridge) => {
+    const ensured = bridge.ensure();
+    assert.equal(lstatSync(fx.link).isSymbolicLink(), true);
+    return ensured;
+  });
+  assert.equal(result.created, true);
+  assert.equal(result.brokerManaged, undefined);
+});
+
 test("cleanup is idempotent and reports process errors without masking a build failure", async () => {
   const fx = fixture();
   const bridge = createTargetBridge(fx);