@rightkit/release 0.6.15 → 0.6.20

package/build-release.mjs

@@ -46,7 +46,7 @@ import { collectSwiftToolVersions, planSwiftBuild } from "./swift-build-context.
 import { planIosNativeBuild, resolveIosBuildContext } from "./ios-build-context.mjs";
 import { packageCommandOptional, requiredBuildExecutables, resolveProjectType, targetUsesMsix } from "./project-type.mjs";
 import { buildPathPrefix, collectPreflight, formatPreflight, preflightFailures } from "./preflight.mjs";
-import { acquireHeavyWorkSlot, heavyCommandEnvironment, summarizePreBrokerWaits, terminateProcessTree } from "./heavy-command.mjs";
+import { acquireRunHeavySlot, heavyCommandEnvironment, summarizePreBrokerWaits, terminateProcessTree, withLocalHeavySlot } from "./heavy-command.mjs";
 import { processGroupCpuSeconds } from "./process-liveness.mjs";
 import { cancelAndReapManagedRequest, firstManagedRequestId, releaseProgressLimits } from "./progress-control.mjs";
 import { beginArtifactLease, completeArtifactLease, materializeArtifacts, retainArtifacts, resolveArtifactDir, resolveManagedRoot } from "./artifact-storage.mjs";
@@ -171,6 +171,8 @@ let child = null;
 let suiteSlot;
 let cacheLease;
 let heavySlot;
+// The run's slot decision (heavySlotDecision): on a broker host the run holds no slot and takes one only around its own local steps (runLocalStep).
+let heavyDecisionOfRun = null;
 let interrupted;
 let requestActiveRunStop = null;
 
@@ -385,19 +387,43 @@ try {
       delete env[name];
     }
   }
-  // A split's Cargo target is the one the gate bound and handed this process (row 7.09, R-T1): Cache V2's shared target does not replace it, or
-  // the bound target the seal reads would not be the one Cargo wrote.
-  if (splitSource && !managedCargoTarget && typeof process.env.CARGO_TARGET_DIR === "string" && path.isAbsolute(process.env.CARGO_TARGET_DIR)) env.CARGO_TARGET_DIR = process.env.CARGO_TARGET_DIR;
+  // A split's Cargo environment is the one the gate bound and handed this process (row 7.09, R-T1): Cache V2's target, cargo home and compiler wrapper
+  // do not replace it, or the bound target the seal reads would not be the one Cargo wrote, and a prepare step that re-runs a build the compile stage
+  // already staged (stage-sidecar) would resolve crates from another cargo home (`--frozen` cannot fetch them) and rebuild the staged bytes
+  // (HeardRight Windows package, 2026-11-01: STAGE_SIDECAR_CATALOG_UNREADABLE, then "a staged entry is immutable for the door run").
+  if (splitSource && !managedCargoTarget) {
+    for (const name of ["CARGO_HOME", "RUSTC_WRAPPER", "SCCACHE_DIR", "SCCACHE_BASEDIRS", "SCCACHE_CACHE_SIZE", "SCCACHE_IGNORE_SERVER_IO_ERROR"]) {
+      if (typeof process.env[name] === "string" && process.env[name] !== "") env[name] = process.env[name];
+      else delete env[name];
+    }
+    // The target only when the gate bound one process-wide: with several workspaces on a direct POSIX host the gate's per-call wrapper binds
+    // each and hands no CARGO_TARGET_DIR, and the target bridge below still needs Cache V2's.
+    if (typeof process.env.CARGO_TARGET_DIR === "string" && path.isAbsolute(process.env.CARGO_TARGET_DIR)) env.CARGO_TARGET_DIR = process.env.CARGO_TARGET_DIR;
+  }
   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 !== "shared" && !commandExists("sccache")) delete env.RUSTC_WRAPPER;
-  if (process.env.RIGHTSUITE_HEAVY_WORK_OWNER !== "1") heavySlot = acquireHeavyWorkSlot();
+  // The host-wide heavy-work slot (rightkit#1367 step 2). A direct host takes it for the whole run. On a broker host every hook the build runs (cargo, SwiftPM, xcodebuild,
+  // pnpm, node, QA) goes through build-launch and becomes a broker job, which the broker's scheduler and resource budget admit: no slot and no memory/CPU wait for the run.
+  // What this process runs itself, outside build-launch, is local work the broker never sees: today its own `pnpm install` (prepare, below), which takes the slot around just
+  // that step (runLocalStep). A child of a skipped slot is not told it has one (no RIGHTSUITE_HEAVY_WORK_OWNER), so a heavy-command it starts takes its own. The worker's
+  // signing, notarization and disk-image steps (sign-macos, notarize-macos, dmg-build) are not builds and hold no slot on a broker host.
+  const { decision: heavyDecision, slot: runSlot } = acquireRunHeavySlot({ env: process.env, brokerHost: brokerManagedHost(process.env) });
+  heavyDecisionOfRun = heavyDecision;
+  if (runSlot) heavySlot = runSlot;
+  else if (heavyDecision.skipReason) {
+    delete env.RIGHTSUITE_HEAVY_WORK_OWNER;
+    console.error(`[right-release] heavy-work slot not held for the run (${heavyDecision.skipReason})`);
+  }
+  // The shared-cache suite slot (acquireSuiteBuildSlot, below) is one-at-a-time per cache layout, not a build count of the broker's. It runs only in cache mode "shared", which a
+  // broker host never has: a Cargo build there is forced to "broker" (managedCargoTarget above) and SwiftPM and native iOS plans are always "legacy" (swift-build-context,
+  // ios-build-context). So on a broker host it is skipped, with no exception; a direct host keeps it.
   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 });
   }
   // Pre-broker wait attribution: every layer, ms, and blocker identity (Step 1 instrumentation).
-  const preBrokerWaits = summarizePreBrokerWaits({ heavySlot, suiteSlot, heavyOwnerInherited: process.env.RIGHTSUITE_HEAVY_WORK_OWNER === "1" });
+  const preBrokerWaits = summarizePreBrokerWaits({ heavySlot, suiteSlot, heavyOwnerInherited: heavyDecision.inherited, heavySkipped: heavyDecision.skipReason });
   console.error(`[right-release] pre-broker waits: ${preBrokerWaits.summary}`);
   throwIfInterrupted();
   const managedRoot = resolveManagedRoot({ env: process.env });
@@ -540,7 +566,7 @@ try {
           if (linked.action === "moved-aside") console.error(`[right-release] hosted CI: moved existing ${targetLink} aside to ${linked.aside}`);
         }
         // A Cargo-less native iOS app installs Node dependencies only when it has a package.json.
-        if (nativeIos ? hasPackageJson : resolveProjectType({ appRoot, config, target }) !== "swiftpm" || config.packageManager) await runProgress(config.packageManager ?? "pnpm", ["install", "--frozen-lockfile"], appRoot, env, cacheTarget, path.join(stateRoot, "stall-install.log"));
+        if (nativeIos ? hasPackageJson : resolveProjectType({ appRoot, config, target }) !== "swiftpm" || config.packageManager) await runLocalStep(() => runProgress(config.packageManager ?? "pnpm", ["install", "--frozen-lockfile"], appRoot, heavyDecisionOfRun?.localSteps ? { ...env, RIGHTSUITE_HEAVY_WORK_OWNER: "1" } : env, cacheTarget, path.join(stateRoot, "stall-install.log")));
       },
       build: async () => {
         throwIfInterrupted();
@@ -917,6 +943,12 @@ function collectToolVersions(packageManager, probeDir = process.cwd()) {
   };
 }
 
+/** On a broker host: the heavy-work slot, held around just the local step `run` (the release's own `pnpm install`), never around broker jobs. Elsewhere `run` runs as it is (the run holds the slot or inherits it). */
+function runLocalStep(run) {
+  const outer = heavySlot;
+  return withLocalHeavySlot(heavyDecisionOfRun, run, { onSlot: (slot) => { heavySlot = slot ?? outer; } });
+}
+
 async function runProgress(cmd, runArgs, cwd, env, watchDir, diagnosticPath = null, { livenessOwnerTimeoutMs = null } = {}) {
   const { inactivityMs, absoluteMs } = releaseProgressLimits(env, { livenessOwnerTimeoutMs });
   let lastProgress = Date.now();

package/cargo-contract.mjs

@@ -2,7 +2,7 @@ import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
-import { directPlatform, linuxBrokerDeclared, managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
+import { directPlatform, gateNoBroker, linuxBrokerDeclared, managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
 
 const SKIP_DIRECTORIES = new Set([".audit", ".cache", ".git", ".claude", ".right-release", ".worktrees", "node_modules", "target", "vendor"]);
 const CRATES_IO_SOURCES = new Set([
@@ -30,6 +30,9 @@ export function managedCargoShimOnPath(env = process.env, platform = process.pla
 }
 
 export function brokerManagedHost(env = process.env, platform = process.platform, exists = existsSync) {
+  // A gate run under Adrian's recorded no-broker exception runs Cargo directly (managed-cargo gateNoBroker): the broker owns no
+  // target or cache for it, so nothing may drop the target the gate pinned, whatever RustRight is installed.
+  if (gateNoBroker(env)) return false;
   // A Linux host is broker-managed only through its explicit declared route (managed-cargo linuxBrokerDeclared), whatever socket or control root the env names.
   if (directPlatform(platform)) return linuxBrokerDeclared(env, platform);
   return Boolean(managedRuntimeClient(env, platform, exists)) || Boolean(env.RUSTRIGHT_BUILD_BROKER_SOCKET || env.RIGHTKIT_BUILD_BROKER_SOCKET) || managedCargoShimOnPath(env, platform, exists);

package/cargo-guard.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 
 import { resolveSharedCacheRoot, resolveStableRoot } from "./cache-policy.mjs";
 import { brokerManagedHost } from "./cargo-contract.mjs";
+import { brokerClientRoute } from "./managed-cargo.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"]);
@@ -137,16 +138,25 @@ export function resolveManagedCargoShim({ env = process.env, platform = process.
   const win = platform === "win32" || platform === "win";
   const delimiter = win ? ";" : ":";
   const agentBin = /(?:^|[\\/])(?:\.rightkit-managed|rightkitmanagedagent|rightkit[\\/]build-control)[\\/]agent-bin[\\/]?$/i;
+  // Every extension cargo-contract.mjs managedCargoShimOnPath accepts (PATHEXT, else .COM;.EXE;.BAT;.CMD), so a shim that predicate sees is a shim this finds.
+  const extensions = win ? String(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((extension) => extension.toLowerCase()) : [""];
   for (const directory of String(env.PATH ?? "").split(delimiter).filter(Boolean)) {
     if (!agentBin.test(directory)) continue;
-    for (const name of win ? ["cargo.exe", "cargo.cmd"] : ["cargo"]) {
-      const candidate = path.join(directory, name);
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `cargo${extension}`);
       if (exists(candidate)) return candidate;
     }
   }
   return null;
 }
 
+/**
+ * The broker's own client for a broker host whose cargo shim is not on PATH (a Dell socket or managed client with no agent-bin directory, a non-login shell, the declared
+ * Linux route): the shared route managed-cargo.mjs runCargoSync takes (`brokerClientRoute`): `{ client, env }`, run as `<client> cargo <args>`; `{ refusal }` when the declared
+ * route is invalid or the Mac's socket is unavailable; null when no client is reachable.
+ */
+export const resolveBrokerClientRoute = brokerClientRoute;
+
 function pathApi(platform) {
   return platform === "win32" || platform === "win" ? path.win32 : path.posix;
 }
@@ -229,7 +239,7 @@ function spawnCargo(command, args, env) {
   });
 }
 
-export async function runCargoGuard(args, { env = process.env, policyOptions = {}, resolveCargo = resolveRealCargo, resolveRustc = resolveRealRustc, runHeavy = runHeavyCommand, runLight = spawnCargo, resolveShim = resolveManagedCargoShim, isBrokerHost = brokerManagedHost } = {}) {
+export async function runCargoGuard(args, { env = process.env, policyOptions = {}, resolveCargo = resolveRealCargo, resolveRustc = resolveRealRustc, runHeavy = runHeavyCommand, runLight = spawnCargo, resolveShim = resolveManagedCargoShim, resolveClientRoute = resolveBrokerClientRoute, isBrokerHost = brokerManagedHost } = {}) {
   assertComputePolicyAllowsCargo(args, { ...policyOptions, env });
   // On a broker-managed host the build broker owns the toolchain, cache, and
   // quotas. Resolving the real Cargo here and running it via runHeavy would
@@ -240,8 +250,18 @@ export async function runCargoGuard(args, { env = process.env, policyOptions = {
   if (isBrokerHost(env)) {
     const shim = resolveShim({ env });
     if (shim) return runLight(shim, args, env);
-    // No shim found despite a broker signal: fall through to legacy resolution
-    // rather than silently dropping the guard.
+    // No shim on PATH (a Dell socket or managed client with no agent-bin, a non-login shell, the declared Linux route): hand the call to the managed or declared runtime
+    // client, the client brokerManagedHost resolves, as `<client> cargo <args>`. Running the real cargo here would be a build outside the broker, which neither counts nor
+    // admits it (the heavy-work slot is not taken on a broker host, rightkit#1367 step 2), so a call that guards (a build) is refused when no client is reachable.
+    // Only a command that guards (a build) goes to the client; a light command (fmt, metadata, --version, ...) builds nothing and runs the real cargo as it always did.
+    if (shouldGuardCargo(args)) {
+      const route = resolveClientRoute({ env });
+      if (route && !route.refusal) return runLight(route.client, ["cargo", ...args], route.env);
+      console.error(route?.refusal
+        ? `cargo-guard: this machine is broker-managed and no broker shim is on PATH, and the RustRight client route is refused (${route.refusal}); refusing to run cargo outside the broker. Start or repair the broker, then run again.`
+        : "cargo-guard: this machine is broker-managed but neither the broker's cargo shim nor a RustRight client was found; refusing to run cargo outside the broker. Start or repair the broker, then run again.");
+      return 1;
+    }
   }
   const cargo = resolveCargo({ env });
   if (shouldGuardCargo(args)) {

package/cargo-target-shim.mjs

@@ -28,7 +28,7 @@
 // overridden the value the gate passed: a residual of the trusted per-user model, not refused (map 7.12).
 import fs from "node:fs";
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { spawnSync } from "./background-process.mjs";
 import { spawnBrokerClient } from "./broker-client.mjs";
 import { fileURLToPath } from "node:url";
@@ -158,9 +158,25 @@ export function decideCargoInvocation({ args, cwd, env, map, locate, realpath =
  * Broker mode (`broker: { checkoutDirs, section }`, the Mac): `checkoutDirs` is the gate's { [cargoDir]: absolute path of that
  * workspace in the primary checkout } (the snapshot-to-checkout map, the only source of a request's primaryCwd) and `section` the
  * public part of the gate's snapshot broker (brokerSection). `realCargo` then only runs `version` and `help`; it may be null.
+ *
+ * Windows, broker mode only (rightkit#1350, rustright#215): a child started without a shell finds only an .exe, so `bin/cargo.exe` is a
+ * byte copy of the live RustRight client (`broker.section.client`) and `bin/gate-trampoline.json` beside it pins node, this module and the
+ * map by path and sha256. The client finds that sidecar beside its own executable and runs `node <module> --map <map> -- <args>` and
+ * nothing else (gate-trampoline mode). The client must answer `trampoline-capability` with the schema and the copy must hash to it before
+ * the sidecar is written; the client's digest is part of the identity, and so is the run's ownership handle (broker section), so two live
+ * runs never share a wrapper directory. A direct Windows host still has no wrapper.
  */
-export function installCargoShim({ base, snapshotRoot, targetDirs, broker = null, realCargo, node = process.execPath, platform = process.platform, realpath = (p) => fs.realpathSync.native(p), onDir = () => {}, write = (file, text, mode) => fs.writeFileSync(file, text, { mode }) }) {
-  if (platform === "win32") throw Object.assign(new Error("the runtime cargo wrapper needs a POSIX host: a Windows child finds only an .exe on PATH"), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+export const TRAMPOLINE_SCHEMA = "rustright.gate-trampoline/1";
+const sha256File = (file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+const probeTrampoline = (exe) => {
+  const r = spawnSync(exe, ["trampoline-capability"], { encoding: "utf8", windowsHide: true });
+  return r.status === 0 ? String(r.stdout ?? "").trim() : `exit ${r.status ?? r.signal ?? r.error?.message}`;
+};
+export function installCargoShim({ base, snapshotRoot, targetDirs, broker = null, realCargo, node = process.execPath, platform = process.platform, realpath = (p) => fs.realpathSync.native(p), onDir = () => {}, write = (file, text, mode) => fs.writeFileSync(file, text, { mode }), copyFile = (from, to) => fs.copyFileSync(from, to), hashFile = sha256File, probe = probeTrampoline }) {
+  if (platform === "win32" && !broker) throw Object.assign(new Error("the runtime cargo wrapper needs a POSIX host or a Windows broker host: a Windows child finds only an .exe on PATH"), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+  const trampoline = platform === "win32";
+  if (trampoline && (typeof broker.section?.client !== "string" || !path.win32.isAbsolute(broker.section.client))) throw Object.assign(new Error(`a Windows broker wrapper needs the absolute RustRight client (${JSON.stringify(broker.section?.client)})`), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+  const clientSha256 = trampoline ? hashFile(broker.section.client) : null;
   const mode = broker ? "broker" : "direct";
   if (mode === "direct" && (typeof realCargo !== "string" || !path.isAbsolute(realCargo))) throw Object.assign(new Error(`no absolute cargo to wrap (${JSON.stringify(realCargo)})`), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
   if (mode === "broker" && ((realCargo !== null && realCargo !== undefined && !path.isAbsolute(realCargo)) || !broker.section || !broker.checkoutDirs)) throw Object.assign(new Error("a broker wrapper needs the gate's checkout map and broker section"), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
@@ -171,12 +187,15 @@ export function installCargoShim({ base, snapshotRoot, targetDirs, broker = null
   const identityHash = createHash("sha256").update(JSON.stringify({ realCargo: realCargo ?? null, node, workspaces: sorted, ...(broker ? { mode, section: broker.section } : {}) })).update(fs.readFileSync(self));
   // The broker half of the wrapper is part of its identity: any change to the code that carries and verifies a call is another wrapper.
   if (broker) for (const name of ["snapshot-broker.mjs", "snapshot-request.mjs", "snapshot-metadata.mjs", "provenance-verify.mjs", "cargo-ledger.mjs"]) identityHash.update(fs.readFileSync(new URL(`./${name}`, import.meta.url)));
+  if (trampoline) identityHash.update(`\0client:${clientSha256}`);
   const identity = identityHash.digest("hex");
   const dir = path.join(base, `rk-cargo-shim-${identity.slice(0, 16)}`);
   const bin = path.join(dir, "bin");
-  const shim = path.join(bin, "cargo");
+  const shim = path.join(bin, trampoline ? "cargo.exe" : "cargo");
   const mapFile = path.join(dir, "cargo-target-map.json");
-  const ledgerDir = path.join(dir, "ledger");
+  // The wrapper directory is identity-keyed and outlives a killed run, so each install gets its own ledger: a dead run's
+  // pending record is never read as this run's call.
+  const ledgerDir = path.join(dir, `ledger-${process.pid}-${randomBytes(6).toString("hex")}`);
   // The caller learns the directory before anything is written into it (its cleanup owns it from here), and a failed install removes
   // what it wrote before it throws.
   onDir(dir);
@@ -188,7 +207,17 @@ export function installCargoShim({ base, snapshotRoot, targetDirs, broker = null
     const sentinel = mode === "broker" || Object.keys(sorted).length > 1 ? path.join(dir, "unbound") : null;
     const section = broker ? { ...broker.section, sentinel } : null;
     put(mapFile, `${JSON.stringify({ schema: SHIM_MAP_SCHEMA, mode, identity, realCargo: realCargo ?? null, shim, ledgerDir, workspaces: sorted, ...(section ? { broker: section } : {}) }, null, 2)}\n`, 0o644);
-    put(shim, `#!/bin/sh\nexec ${quote(node)} ${quote(self)} --map ${quote(mapFile)} -- "$@"\n`, 0o755);
+    if (trampoline) {
+      // The probe asks the client under its own name: a copy named cargo.exe is a managed cargo shim to RustRight (shims.rs), which would send the
+      // probe to the broker as a cargo request instead of answering it.
+      const answer = probe(broker.section.client);
+      if (answer !== TRAMPOLINE_SCHEMA) throw Object.assign(new Error(`the RustRight client ${broker.section.client} has no gate-trampoline mode (trampoline-capability answered ${JSON.stringify(answer)}, not ${TRAMPOLINE_SCHEMA}); install a RustRight runtime with rustright#215`), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+      copyFile(broker.section.client, shim);
+      const copied = hashFile(shim);
+      if (copied !== clientSha256) throw Object.assign(new Error(`the copy ${shim} hashes to ${copied}, not the client's ${clientSha256}`), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+      const pin = (file) => ({ path: file, sha256: hashFile(file) });
+      put(path.join(bin, "gate-trampoline.json"), `${JSON.stringify({ schema: TRAMPOLINE_SCHEMA, node: pin(node), module: pin(self), map: pin(mapFile) }, null, 2)}\n`, 0o644);
+    } else put(shim, `#!/bin/sh\nexec ${quote(node)} ${quote(self)} --map ${quote(mapFile)} -- "$@"\n`, 0o755);
     return { dir, bin, shim, mapFile, ledgerDir, mode, workspaces: sorted, identity, sentinel };
   } catch (error) {
     fs.rmSync(dir, { recursive: true, force: true });
@@ -230,12 +259,32 @@ export function locateWorkspaceByWalk(manifestPath, cwd, { read = (f) => fs.read
 }
 
 /** The wrapper itself: `cargo-target-shim.mjs --map <file> -- <cargo args>`. Returns the exit status. */
+/** The wrapper's own reader of its map file (runShim reads it through this): throws when the file is unreadable or is another schema. */
+export function readShimMap(file) {
+  const map = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (map?.schema !== SHIM_MAP_SCHEMA) throw new Error(`schema ${JSON.stringify(map?.schema)}`);
+  return map;
+}
+
+/**
+ * The per-call wrapper this process runs under, from its environment: CARGO names the wrapper (`<dir>/bin/cargo`) and the map it reads
+ * is `<dir>/cargo-target-map.json`. Returns the map only for a direct-mode wrapper whose own `shim` is that CARGO (a stale or foreign CARGO
+ * is no wrapper), else null. `map.workspaces` is { [real snapshot workspace]: the checkout's target directory }.
+ */
+export function shimMapOfEnv(env = process.env, { read = readShimMap } = {}) {
+  const cargo = env?.CARGO;
+  if (typeof cargo !== "string" || !path.isAbsolute(cargo)) return null;
+  let map;
+  try { map = read(path.join(path.dirname(path.dirname(cargo)), "cargo-target-map.json")); } catch { return null; }
+  return map?.mode === "direct" && map.shim === cargo && map.workspaces && typeof map.workspaces === "object" ? map : null;
+}
+
 export function runShim(argv, { env = process.env, cwd = process.cwd(), spawn = spawnSync, err = (m) => process.stderr.write(`${m}\n`) } = {}) {
   const sep = argv.indexOf("--");
   const mapAt = argv.indexOf("--map");
   if (mapAt < 0 || sep < 0 || mapAt > sep) { err("rightkit-gate: RK_CARGO_SHIM_ERROR: usage: cargo-target-shim.mjs --map <file> -- <cargo args>"); return SHIM_REFUSAL_STATUS; }
   let map;
-  try { map = JSON.parse(fs.readFileSync(argv[mapAt + 1], "utf8")); if (map?.schema !== SHIM_MAP_SCHEMA) throw new Error(`schema ${JSON.stringify(map?.schema)}`); }
+  try { map = readShimMap(argv[mapAt + 1]); }
   catch (error) { err(`rightkit-gate: RK_CARGO_SHIM_ERROR: the cargo target map cannot be read (${error.message}); nothing ran`); return SHIM_REFUSAL_STATUS; }
   const words = argv.slice(sep + 1);
   const token = env[SCAN_TOKEN_ENV];

package/clippy-route.mjs

@@ -1,7 +1,7 @@
 // The Clippy route: `rightkit-gate clippy [<cargo clippy args>]` (GATE-CONTRACT §1 "Clippy route & batching", E13 to E15; item 8 of
 // the joint plan, rows 8.1 to 8.16 of the signed map). A gate-owned destination for a request such as
 // `cargo clippy --workspace --all-targets -- -D warnings`: it builds HEAD's commit (never the checkout) from the gate-owned
-// snapshot, under the host's build ownership, after FULL class A (D8-2), and stops after diagnostics. It has no stage chain, runs no
+// snapshot, under the repository's build ownership, after FULL class A (D8-2), and stops after diagnostics. It has no stage chain, runs no
 // package, sign, publish or release stage, and writes nothing a door receipt, qualification or the full gate could take as stage
 // evidence (row 8.5).
 //
@@ -28,7 +28,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { resolveExecutor as defaultResolveExecutor } from "./gate-executor.mjs";
-import { directPlatform } from "./managed-cargo.mjs";
+import { directPlatform, realCargoOf } from "./managed-cargo.mjs";
 import { defaultSpawnAsync, sidecarBoundCrate } from "./deterministic-scans.mjs";
 import { gateStateDir } from "./gate-stages.mjs";
 import { ProvenanceError, verifyAttributionDetail } from "./provenance-verify.mjs";
@@ -362,11 +362,12 @@ export async function clippyCommand(o, args, deps = {}) {
   const snap = deps.snapshot ?? await import("./snapshot.mjs");
   const sc = deps.snapshotCheck ?? await import("./snapshot-check.mjs");
   const ownershipApi = deps.ownership ?? await import("./build-ownership.mjs");
-  let selected; let snapshotsAt; let snapshotDir;
+  let selected; let snapshotsAt; let snapshotDir; let repoKey;
   try {
     selected = snap.resolveCommit(root, "HEAD");
     snapshotsAt = o.snapshotRoot ?? snap.snapshotRoot({ platform: o.platform, env: o.env });
-    snapshotDir = path.join(snapshotsAt, snap.repositoryOf(root).key);
+    repoKey = snap.repositoryOf(root).key;
+    snapshotDir = path.join(snapshotsAt, repoKey);
   } catch (e) { o.err(`${tag} cannot select HEAD's commit: ${e.message}; nothing ran`); return REFUSED_EXIT; }
 
   // The output directory is the checkout's, resolved by the gate (row 8.12): a caller's CARGO_TARGET_DIR that points into the snapshot would
@@ -399,9 +400,9 @@ export async function clippyCommand(o, args, deps = {}) {
   if (preBound.length) { o.err(sidecarRefusal(tag, preBound, "read from the commit")); resultLine(o, tag, { result: "BLOCKED", code: ROUTE_CODES.sidecarBound, blockedOn: ["item7:7.05"], bound: preBound, launched: false }); return BLOCKED; }
 
   const timings = {}; const lap = (name, since) => { timings[name] = Date.now() - since; };
-  // Build ownership first (E6): held from before the sync until the diagnostics are written. A busy host runs nothing and syncs nothing.
+  // Build ownership first (E6): held from before the sync until the diagnostics are written. A busy repository runs nothing and syncs nothing.
   let own;
-  try { own = (deps.acquireOwnership ?? ownershipApi.acquireBuildOwnership)({ file: ownershipApi.ownershipFile({ platform: o.platform, beside: o.snapshotRoot }), stage: "clippy", snapshot: snapshotDir, commit: selected.commit, platform: o.platform, env: o.env }); }
+  try { own = (deps.acquireOwnership ?? ownershipApi.acquireBuildOwnership)({ file: ownershipApi.ownershipFile({ platform: o.platform, beside: o.snapshotRoot, repository: repoKey }), stage: "clippy", snapshot: snapshotDir, commit: selected.commit, platform: o.platform, env: o.env }); }
   catch (e) { if (e.code !== "busy" && e.code !== "refused") throw e; o.err(`${tag} BLOCKED: ${e.message}; ${e.code === "refused" ? "nothing ran, nothing created" : "the route never re-syncs a snapshot another request holds; nothing ran"}`); return BLOCKED; }
   o.out(`${tag} build ownership ${own.joined ? "joined" : "held"} ${own.handle}`);
   const abort = o.abort ?? new AbortController();
@@ -432,7 +433,7 @@ export async function clippyCommand(o, args, deps = {}) {
     // The snapshot's working directory for the request, and the Cargo workspace it names, resolved from the commit's own manifests.
     const snapCwd = relCwd ? path.join(synced.path, ...relCwd.split("/")) : synced.path;
     if (!fs.existsSync(snapCwd)) { o.err(`${tag} BLOCKED: the working directory ${relCwd} is not in commit ${synced.commit.slice(0, 12)}; run from a directory the commit holds; nothing compiled`); return BLOCKED; }
-    const realCargo = which("cargo").find((c) => path.isAbsolute(c));
+    const realCargo = realCargoOf(which("cargo"));
     if (!realCargo) { o.err(`${tag} BLOCKED: no cargo on PATH to wrap for the snapshot compile; nothing compiled`); return BLOCKED; }
     const located = o.spawn("cargo", ["locate-project", "--workspace", "--message-format", "plain", ...(parsed.manifestPath ? ["--manifest-path", parsed.manifestPath] : [])], { cwd: snapCwd, env: o.env });
     if (failed(located) || !path.isAbsolute(text(located).trim())) { o.err(`${tag} BLOCKED: the request's Cargo workspace cannot be resolved in the snapshot (${why(located) || "no manifest"}); nothing compiled`); return BLOCKED; }

package/crate-graph.mjs

@@ -2,7 +2,11 @@
 // closure and Cargo.lock dependency closure. Pure TOML parsing (smol-toml); nothing shells out to cargo.
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { parse } from "smol-toml";
+import { createRequire } from "node:module";
+// smol-toml loads on first parse, not at import: CI jobs whose closure reaches this module without installing
+// @rightkit/release dependencies (publish.yml crates pack, bind) never parse TOML here (rightkit#1341).
+let smolTomlParse;
+const parse = (text) => (smolTomlParse ??= createRequire(import.meta.url)("smol-toml").parse)(text);
 
 const DEP_TABLES = ["dependencies", "build-dependencies", "dev-dependencies"];
 

package/credential-provider.mjs

@@ -0,0 +1,174 @@
+// The OS credential provider (`rightkit-credentials`, crates/rightkit-credentials) that updater signing runs, obtained the one sanctioned way: the gate's
+// tool route (`rightkit-gate --to tool --unit cargo:rightkit-credentials`, tool-build.mjs), never a PATH binary on a Mac or Windows host. It is the
+// pattern of qa-runner.mjs:
+//
+//   record   `<managed data root>/credential-provider/<mac|win>/record.json`, `{schema, platform, providers: {<version>: {path, sha256, version}}, enrolledAt}`,
+//            and the binary at `<managed data root>/credential-provider/<platform>/<version>/rightkit-credentials[.exe]`: a COPY the enrol operation made, so a
+//            later `cargo clean` cannot change what signing executes. Outside every repository and snapshot.
+//   enrol    `enrollCredentialProvider`: the gate-built file of the crate's committed version (>= MIN_PROVIDER_VERSION). A second enrolment of the same
+//            version is a rotation and needs `rotate`.
+//   use      `resolveCredentialProvider`: the NEWEST enrolled version; its file must still be a regular file inside the managed directory whose sha256 IS
+//            the recorded one. Anything else is a typed refusal naming the sanctioned install.
+//
+// The binary has NO `--version` (its CLI is `status|set|delete|ensure-key|exec`; any other first word, with no `--namespace`, answers
+// `{"ok":false,"error":"invalid --namespace: required"}` and exits 1). So the version is not attested by the binary: it is the version of the commit the gate built
+// it from (the tool route passes the crate's committed version), bound to the copy by its sha256. What enrolment does check is that the file is this CLI
+// (the identity probe below), which is a regular executable that touches no credential store.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { resolveManagedRoots } from "./managed-roots.mjs";
+
+export const CREDENTIAL_PROVIDER_SCHEMA = "rightkit.credential-provider/1";
+export const CREDENTIAL_PROVIDER_DIR = "credential-provider";
+export const CREDENTIAL_PROVIDER_PLATFORMS = Object.freeze(["mac", "win"]);
+export const MIN_PROVIDER_VERSION = "0.2.2";
+/** The one sanctioned way to install the provider; every refusal names it. */
+export const CREDENTIAL_PROVIDER_INSTALL = "rightkit-gate --to tool --unit cargo:rightkit-credentials";
+const HOST_PLATFORM = { darwin: "mac", win32: "win" };
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export class CredentialProviderError extends Error {
+  constructor(code, message) { super(message); this.name = "CredentialProviderError"; this.code = code; }
+}
+const fail = (code, message) => { throw new CredentialProviderError(code, message); };
+
+/** The provider platform of a `process.platform` value, or null when the host has no managed provider (Linux, CI). */
+export const providerPlatformOf = (hostPlatform) => HOST_PLATFORM[hostPlatform] ?? null;
+export const providerExecutableName = (platform) => (platform === "win" ? "rightkit-credentials.exe" : "rightkit-credentials");
+
+const parse = (version) => { const m = SEMVER.exec(String(version ?? "")); return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null; };
+const compare = (a, b) => { for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] - b[i]; return 0; };
+const checkPlatform = (platform) => { if (!CREDENTIAL_PROVIDER_PLATFORMS.includes(platform)) fail("RK_CRED_PROVIDER_PLATFORM", `platform must be ${CREDENTIAL_PROVIDER_PLATFORMS.join(" or ")}, not ${JSON.stringify(platform)}`); };
+const checkDataRoot = (dataRoot) => { if (!dataRoot || !path.isAbsolute(dataRoot)) fail("RK_CRED_PROVIDER_ROOT", "the managed data root must be an absolute path"); };
+const checkVersion = (version) => {
+  const v = parse(version);
+  if (!v) fail("RK_CRED_PROVIDER_VERSION", `${JSON.stringify(version)} is not a rightkit-credentials version (major.minor.patch)`);
+  if (compare(v, parse(MIN_PROVIDER_VERSION)) < 0) fail("RK_CRED_PROVIDER_VERSION", `rightkit-credentials ${version} is below ${MIN_PROVIDER_VERSION}, the first release with the \`exec\` child-environment command updater signing needs`);
+};
+
+export const credentialProviderDir = ({ dataRoot, platform }) => { checkDataRoot(dataRoot); checkPlatform(platform); return path.join(dataRoot, CREDENTIAL_PROVIDER_DIR, platform); };
+export const credentialProviderRecordFile = (args) => path.join(credentialProviderDir(args), "record.json");
+export const credentialProviderFile = ({ dataRoot, platform, version }) => path.join(credentialProviderDir({ dataRoot, platform }), String(version), providerExecutableName(platform));
+
+const sha256OfFile = (file) => crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+const isInside = (child, parent) => { const rel = path.relative(parent, child); return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel); };
+
+/** The identity probe: with no arguments the CLI answers a JSON refusal naming `--namespace` and exits 1, and reads no store. A file that answers anything else is not rightkit-credentials. */
+function assertIsCredentialCli(file, spawn) {
+  const run = spawn(file, [], { encoding: "utf8", windowsHide: true, timeout: 30000, stdio: ["ignore", "pipe", "pipe"] });
+  let answer = null;
+  try { answer = JSON.parse(String(run?.stdout ?? "").trim()); } catch { /* not JSON */ }
+  if (run?.status !== 1 || answer?.ok !== false || !String(answer?.error ?? "").includes("--namespace")) {
+    fail("RK_CRED_PROVIDER_IDENTITY", `${file} did not answer like rightkit-credentials (exit ${run?.status ?? run?.error?.message ?? "none"}, ${JSON.stringify(String(run?.stdout ?? "").slice(0, 80))}); it has no --version, so its identity is its refusal of a call with no --namespace`);
+  }
+}
+
+function readRecord({ dataRoot, platform }) {
+  const file = credentialProviderRecordFile({ dataRoot, platform });
+  let meta;
+  try { meta = fs.lstatSync(file); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (meta.isSymbolicLink() || !meta.isFile()) fail("RK_CRED_PROVIDER_RECORD", `${file} is not a regular file`);
+  if (process.platform !== "win32" && (meta.mode & 0o022)) fail("RK_CRED_PROVIDER_RECORD", `${file} is writable by group or others`);
+  let record;
+  try { record = JSON.parse(fs.readFileSync(file, "utf8")); } catch (error) { fail("RK_CRED_PROVIDER_RECORD", `${file} is not JSON (${error.message})`); }
+  if (record?.schema !== CREDENTIAL_PROVIDER_SCHEMA || record.platform !== platform || record.providers === null || typeof record.providers !== "object" || Array.isArray(record.providers)) {
+    fail("RK_CRED_PROVIDER_RECORD", `${file} is not a ${CREDENTIAL_PROVIDER_SCHEMA} record for ${platform}`);
+  }
+  return { file, record };
+}
+
+/**
+ * Enrols a gate-built rightkit-credentials (`binary`, an absolute path) of `version`: a COPY under the managed directory, its sha256 recorded. Enrols on the
+ * host whose platform it is (the bytes are executed here for the identity probe). Returns `{ file, runnerFile, providerFile, entry, rotated }`.
+ */
+export function enrollCredentialProvider({ dataRoot, platform, binary, version, rotate = false, spawn = spawnSync, hostPlatform = process.platform, now = () => new Date() }) {
+  checkPlatform(platform);
+  if (HOST_PLATFORM[hostPlatform] !== platform) fail("RK_CRED_PROVIDER_PLATFORM", `a ${platform} provider is enrolled on a ${platform} host (this is ${hostPlatform}): its bytes are executed to check what they are`);
+  checkVersion(version);
+  const target = credentialProviderFile({ dataRoot, platform, version });
+  if (!binary || !path.isAbsolute(String(binary))) fail("RK_CRED_PROVIDER_PATH", "the provider must be named by an absolute path");
+  let source; let meta;
+  try { source = fs.realpathSync.native(binary); meta = fs.statSync(source); } catch (error) { fail("RK_CRED_PROVIDER_PATH", `the provider ${binary} cannot be resolved (${error.code ?? error.message})`); }
+  if (!meta.isFile()) fail("RK_CRED_PROVIDER_PATH", `${source} is not a regular file`);
+  // The execute bit is the real file system's, so it is read only where that file system has one (never on Windows, whatever host is simulated).
+  if (platform !== "win" && process.platform !== "win32" && (meta.mode & 0o111) === 0) fail("RK_CRED_PROVIDER_PATH", `${source} is not executable`);
+  assertIsCredentialCli(source, spawn);
+  const existing = readRecord({ dataRoot, platform });
+  const had = existing?.record.providers?.[version] ?? null;
+  if (had && !rotate) fail("RK_CRED_PROVIDER_EXISTS", `${existing.file} already enrols rightkit-credentials ${version} (sha256 ${String(had.sha256).slice(0, 12)}); replacing it is a rotation (pass rotate)`);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const staging = `${target}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.copyFileSync(source, staging, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(staging, 0o755);
+    assertIsCredentialCli(staging, spawn);
+    fs.renameSync(staging, target);
+  } finally { fs.rmSync(staging, { force: true }); }
+  const entry = { path: target, sha256: sha256OfFile(target), version };
+  const record = { schema: CREDENTIAL_PROVIDER_SCHEMA, platform, providers: { ...(existing?.record.providers ?? {}), [version]: entry }, enrolledAt: now().toISOString() };
+  const file = credentialProviderRecordFile({ dataRoot, platform });
+  const tmp = `${file}.${crypto.randomUUID()}.tmp`;
+  try { fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 }); fs.renameSync(tmp, file); } finally { fs.rmSync(tmp, { force: true }); }
+  return { file, runnerFile: target, providerFile: target, entry, rotated: Boolean(had) };
+}
+
+/**
+ * The enrolled provider: the NEWEST recorded version, `{ file, sha256, version, source: "managed" }`, or a typed refusal. The file the record names must be the
+ * managed copy (inside the managed directory, not a link) and its bytes must still hash to the recorded sha256. It is never executed here and there is no
+ * fallback: a missing enrolment names the install.
+ */
+export function resolveCredentialProvider({ dataRoot, platform }) {
+  checkPlatform(platform);
+  const read = readRecord({ dataRoot, platform });
+  const versions = Object.keys(read?.record.providers ?? {}).filter((v) => parse(v)).sort((a, b) => compare(parse(b), parse(a)));
+  if (!versions.length) fail("RK_CRED_PROVIDER_MISSING", `OS credential provider unavailable: rightkit-credentials >=${MIN_PROVIDER_VERSION} is not enrolled for ${platform} (${credentialProviderRecordFile({ dataRoot, platform })}); install it with \`${CREDENTIAL_PROVIDER_INSTALL}\``);
+  const version = versions[0];
+  const entry = read.record.providers[version];
+  const expected = credentialProviderFile({ dataRoot, platform, version });
+  if (entry.version !== version || !SHA256.test(String(entry.sha256)) || entry.path !== expected) fail("RK_CRED_PROVIDER_RECORD", `${read.file}: the entry for ${version} is malformed or names a file other than ${expected}`);
+  let meta;
+  try { meta = fs.lstatSync(expected); } catch (error) { fail("RK_CRED_PROVIDER_MISSING", `OS credential provider unavailable: the enrolled rightkit-credentials ${version} is gone (${expected}: ${error.code ?? error.message}); install it again with \`${CREDENTIAL_PROVIDER_INSTALL}\``); }
+  if (meta.isSymbolicLink() || !meta.isFile()) fail("RK_CRED_PROVIDER_RECORD", `${expected} is not a regular file`);
+  if (!isInside(fs.realpathSync.native(expected), fs.realpathSync.native(path.join(dataRoot, CREDENTIAL_PROVIDER_DIR)))) fail("RK_CRED_PROVIDER_RECORD", `${expected} resolves outside ${path.join(dataRoot, CREDENTIAL_PROVIDER_DIR)}`);
+  const actual = sha256OfFile(expected);
+  if (actual !== entry.sha256) fail("RK_CRED_PROVIDER_DIGEST", `the enrolled rightkit-credentials ${version} at ${expected} has sha256 ${actual}, not the recorded ${entry.sha256}; it changed after enrolment, so it is not run (install it again with \`${CREDENTIAL_PROVIDER_INSTALL}\`, then rotate)`);
+  return { file: expected, sha256: actual, version, source: "managed" };
+}
+
+/**
+ * The provider updater signing runs on a host: the enrolled one on a Mac or Windows host (its managed data root, `hostPlatform` decides), the bare PATH name
+ * only where no managed data root exists (Linux, CI). Returns `{ file, managed }`; a managed host with no usable enrolment throws the typed refusal.
+ */
+export function updaterCredentialProvider({ env = process.env, hostPlatform = process.platform, dataRoot, resolve = resolveCredentialProvider } = {}) {
+  const platform = providerPlatformOf(hostPlatform);
+  if (!platform) return { file: "rightkit-credentials", managed: false };
+  return { file: resolve({ dataRoot: dataRoot ?? resolveManagedRoots({ env, platform: hostPlatform }).dataRoot, platform }).file, managed: true };
+}
+
+/** `node credential-provider.mjs enroll --platform mac|win --binary <built rightkit-credentials> --version <v> [--data-root <dir>] [--rotate]` or `show`. */
+export function main(argv, { out = (m) => process.stdout.write(`${m}\n`), err = (m) => process.stderr.write(`${m}\n`), env = process.env, spawn, program = "credential-provider.mjs" } = {}) {
+  const [command, ...rest] = argv;
+  const opt = (name) => { const i = rest.indexOf(name); return i < 0 ? undefined : rest[i + 1]; };
+  try {
+    const platform = opt("--platform") ?? HOST_PLATFORM[process.platform];
+    const dataRoot = opt("--data-root") ?? resolveManagedRoots({ env }).dataRoot;
+    if (command === "enroll") {
+      const r = enrollCredentialProvider({ dataRoot, platform, binary: opt("--binary") && path.resolve(opt("--binary")), version: opt("--version"), rotate: rest.includes("--rotate"), ...(spawn ? { spawn } : {}) });
+      out(`enrolled rightkit-credentials ${r.entry.version} for ${platform} (sha256 ${r.entry.sha256}) at ${r.providerFile}${r.rotated ? " (rotation)" : ""}`);
+      return 0;
+    }
+    if (command === "show") {
+      const read = readRecord({ dataRoot, platform });
+      out(read ? JSON.stringify(read.record) : "no enrolment");
+      return read ? 0 : 1;
+    }
+    err(`usage: ${program} enroll --platform mac|win --binary <built rightkit-credentials> --version <v> [--data-root <dir>] [--rotate]\n       ${program} show [--platform mac|win] [--data-root <dir>]`);
+    return 2;
+  } catch (error) { err(`${error.code ?? "error"}: ${error.message}`); return 1; }
+}
+
+if (process.argv[1] && (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })()) process.exit(main(process.argv.slice(2)));