@rightkit/release 0.6.8 → 0.6.10

package/local-publish.mjs

@@ -13,6 +13,7 @@
 // all-features check, packaging, gate, publish and registry readback, and writes its own evidence file. Crates
 // of one dependency layer publish concurrently (bounded); layer N+1 starts only after every layer-N crate is
 // visible in the registry index with the verified checksum.
+import { buildLaunch } from "./build-launch.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
@@ -28,6 +29,7 @@ import { refuseHostUpload } from "./host-upload-refusal.mjs";
 import { pathDependencyDirs, readCargoPackage } from "./crate-graph.mjs";
 import { recordPublished, stageSourceVersions, workspaceFeedOptions } from "./rightkit-sync.mjs";
 import { prepareSwapHelper, SWAP_HELPER_CARGO_ARGS, SWAP_HELPER_PACKAGE } from "./swap-helper-bundle.mjs";
+import { requireDoorRun, gateStateDir } from "./gate-stages.mjs";
 
 export const LOCAL_OPERATOR = "agent (local-build grant)";
 export const LOCAL_HOST_POLICY_REASON = "Adrian 2026-10-14 local-build grant (.rightkit-local-build.json); Windows covered by the next CI run";
@@ -46,6 +48,12 @@ export const DEFAULT_CONCURRENCY = 4;
 const MAX_CONCURRENCY = 8;
 const CRATE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const JOBS_SUBCOMMANDS = new Set(["test", "clippy", "check", "package"]);
+// The argv of the broker jobs a unit's compile and package stages launch. Built here, once, for the stages themselves and for
+// stage-commands.mjs, which derives what a qualification's signed receipts must show (the hosted admission and the gate share it).
+export const qualifyFmtArgs = (unit) => ["fmt", "-p", unit, "--check"];
+export const npmPackArgs = (packDir, scratch) => ["--dir", packDir, "pack", "--pack-destination", scratch];
+export const cargoPackageArgs = (unit, qualifyOnly) => ["package", "--locked", ...(qualifyOnly ? [] : ["--no-verify"]), "-p", unit];
+export const CARGO_METADATA_ARGS = Object.freeze(["metadata", "--offline", "--format-version", "1", "--no-deps"]);
 export function withCargoJobs(args, jobs) {
   return jobs !== undefined && JOBS_SUBCOMMANDS.has(args[0])
     ? [args[0], "--jobs", String(jobs), ...args.slice(1)] : args;
@@ -121,8 +129,8 @@ export function parseLocalPublishArgs(kind, argv, cwd = process.cwd()) {
     if (arg === "--local") local = true;
     else if (arg === flag) unit = argv[++i];
     else if (arg === "--workspace") workspace = argv[++i];
-    else if (kind === "cargo" && arg === "--qualify-only") qualifyOnly = true;
-    else if (kind === "cargo" && arg === "--bundle") bundle = argv[++i];
+    else if (arg === "--qualify-only") qualifyOnly = true;
+    else if (arg === "--bundle") bundle = argv[++i];
     // Same meaning as publish.yml's allow_ignored: this unit may have ignored tests; the count is recorded.
     else if (arg === "--allow-ignored") allowIgnored = true;
     else if (kind === "cargo" && arg === "--crates") crates = crateList(argv[++i], "--crates");
@@ -414,6 +422,19 @@ function assertLocalHost(deps, workspaceRoot, kind) {
 
 // Host uploads are retired: only --qualify-only (no upload) runs. The upload engine below is kept for direct calls in
 // tests; no CLI path reaches it (see host-upload-refusal.mjs).
+/** One door: a publish engine entry (the CLI's `publish <kind> --local`, or a direct call of the engine) runs only inside a
+ * live rightkit-gate door run for the workspace's HEAD (RK_GATE_RUN; gate-stages requireDoorRun). The unit stages
+ * (compileLocalUnit and its successors) never pass through here: they are the gate's own path and carry their own door. */
+export function requireEngineDoor(parsed, { env = process.env, git = defaultGit, command = "right-release publish --local" } = {}) {
+  const root = parsed.workspaceRoot;
+  const common = git(["rev-parse", "--git-common-dir"], root);
+  const commit = git(["rev-parse", "HEAD"], root);
+  if (!common || !/^[0-9a-f]{40}$/.test(commit ?? "")) refuse(`${command} runs only inside a rightkit-gate door run of a git checkout (no HEAD or common dir in ${root})`);
+  const denial = requireDoorRun({ env, commonDir: path.resolve(root, common), commit, command });
+  if (denial) refuse(denial);
+  return { commit, commonDir: path.resolve(root, common) };
+}
+
 export async function runLocalPublish(kind, argv, deps = {}) {
   const parsed = parseLocalPublishArgs(kind, argv, deps.cwd);
   if (!parsed.qualifyOnly) refuseHostUpload(`right-release publish ${kind} --local`);
@@ -422,10 +443,69 @@ export async function runLocalPublish(kind, argv, deps = {}) {
 
 export async function runLocalPublishUploadEngine(kind, argv, deps = {}) {
   const parsed = parseLocalPublishArgs(kind, argv, deps.cwd);
+  (deps.requireDoor ?? requireEngineDoor)(parsed, { env: deps.env ?? process.env, command: `right-release publish ${kind} --local` });
   if (parsed.batch) return runLocalPublishBatch(parsed, deps);
   return publishUnit(parsed, deps, null);
 }
 
+// Stage state never leaves this process: persisted receipts are reports, not authority to skip unit tests.
+const unitStages = new WeakMap();
+function assertUnitDoor(root, stage, env, identity) {
+  const commit = defaultGit(["rev-parse", "HEAD"], root);
+  const tree = defaultGit(["rev-parse", "HEAD^{tree}"], root);
+  const common = defaultGit(["rev-parse", "--git-common-dir"], root);
+  if (!/^[0-9a-f]{40}$/.test(commit ?? "") || !/^[0-9a-f]{40}$/.test(tree ?? "") || !common) refuse("cannot bind unit stage to HEAD and tree");
+  if (identity && (identity.commit !== commit || identity.tree !== tree)) refuse("unit stage HEAD or tree changed");
+  const dirty = defaultGit(["status", "--porcelain", "--untracked-files=no"], root);
+  if (dirty === null || dirty !== "") refuse("unit stage requires a clean tracked checkout");
+  const commonDir = path.resolve(root, common);
+  const denial = requireDoorRun({ env, commonDir, commit, command: `unit ${stage}` });
+  if (denial) refuse(denial);
+  let run;
+  try { run = JSON.parse(fs.readFileSync(path.join(gateStateDir(commonDir), "runs", `${env.RK_GATE_RUN}.json`), "utf8")); } catch { refuse("cannot read the unit door run"); }
+  if (run.stage !== stage || run.tree !== tree) refuse(`unit ${stage} needs its own live door run for this tree`);
+  return { commit, tree };
+}
+
+export async function compileLocalUnit(kind, argv, { env = process.env } = {}) {
+  const parsed = parseLocalPublishArgs(kind, argv);
+  if (!parsed.qualifyOnly || parsed.batch) refuse("unit stages require one --qualify-only unit and a new bundle");
+  const identity = assertUnitDoor(parsed.workspaceRoot, "compile", env);
+  const runner = publishUnitStages(parsed, { env }, null);
+  try {
+    const step = await runner.next();
+    if (step.done || step.value?.stage !== "compile") refuse("unit compile did not complete");
+    assertUnitDoor(parsed.workspaceRoot, "compile", env, identity);
+    const state = Object.freeze({});
+    unitStages.set(state, { runner, parsed, identity, stage: "compile", compileRequests: [...(step.value.brokerRequests ?? [])] });
+    return state;
+  } catch (error) { await runner.return(); throw error; }
+}
+
+async function advanceLocalUnit(state, expected, stage, env) {
+  const entry = unitStages.get(state);
+  if (!entry || entry.stage !== expected) refuse(`unit ${stage} requires this process's completed ${expected} stage`);
+  entry.stage = "running";
+  try {
+    assertUnitDoor(entry.parsed.workspaceRoot, stage, env, entry.identity);
+    const step = await entry.runner.next(env);
+    if (stage === "package" ? step.done || step.value?.stage !== "package" : !step.done || !step.value?.qualifiedOnly) refuse(`unit ${stage} did not complete`);
+    assertUnitDoor(entry.parsed.workspaceRoot, stage, env, entry.identity);
+    entry.stage = stage;
+    if (stage === "qualify") unitStages.delete(state);
+    return step.value;
+  } catch (error) { unitStages.delete(state); await entry.runner.return(); throw error; }
+}
+
+export const packageLocalUnit = (state, { env = process.env } = {}) => advanceLocalUnit(state, "compile", "package", env);
+export const qualifyLocalUnit = (state, { env = process.env } = {}) => advanceLocalUnit(state, "package", "qualify", env);
+/** The broker request ids of this process's completed compile stage (the package stage's ride on its result). */
+export const localUnitCompileRequests = (state) => [...(unitStages.get(state)?.compileRequests ?? [])];
+export async function closeLocalUnit(state) {
+  const entry = unitStages.get(state);
+  if (entry) { unitStages.delete(state); await entry.runner.return(); }
+}
+
 /**
  * Qualify and publish ONE unit. `batch` (cargo batch mode only) is `{ head, tree, receipt, commands }`: the
  * batch-level fmt, secret scan and clippy already ran at `head`/`tree`, so this unit skips its own clippy and
@@ -433,11 +513,31 @@ export async function runLocalPublishUploadEngine(kind, argv, deps = {}) {
  * publish and the registry readback) runs for this unit exactly as in single mode.
  */
 async function publishUnit(parsed, deps, batch) {
+  const runner = publishUnitStages(parsed, deps, batch);
+  let result;
+  do { result = await runner.next(); } while (!result.done);
+  return result.value;
+}
+
+async function* publishUnitStages(parsed, deps, batch) {
   const log = deps.log ?? ((line) => process.stdout.write(`${line}\n`));
   const { kind, unit, allowIgnored, workspaceRoot } = parsed;
   const git = deps.git ?? defaultGit;
   const readJson = deps.readJson ?? defaultReadJson;
-  const run = deps.run ?? (batch ? defaultRunAsync : defaultRun);
+  // Every broker job a stage launches prints `rustright: request <id>`; the unit gate fetches those jobs' signed receipts, so the ids
+  // are collected here per stage and handed over at each stage yield (compile, then package). Nothing about what runs changes.
+  const brokerRequests = [];
+  const noteBrokerRequests = (result) => { for (const [, id] of `${result?.stdout ?? ""}\n${result?.stderr ?? ""}`.matchAll(/^rustright: request ([0-9a-f-]{36})/gm)) if (!brokerRequests.includes(id)) brokerRequests.push(id); return result; };
+  const launch = deps.run ?? (batch ? defaultRunAsync : defaultRun);
+  // Every pnpm step goes through the one door for build and test launches (build-launch.mjs): a rightkit-pnpm broker job on a
+  // managed host (refused, never run directly, when the broker is unreachable), direct on a host without one. A run headed to release
+  // then also has the signed receipt each stage owes (stage-commands.mjs). Other commands (cargo is already a broker job) are unchanged.
+  const run = (command, args, options) => {
+    const target = command === "pnpm" ? buildLaunch(command, args, { env: options?.env ?? process.env, platform: deps.platform ?? process.platform, exists: fs.existsSync }) : { command, args };
+    const result = launch(target.command, target.args, options);
+    return typeof result?.then === "function" ? result.then(noteBrokerRequests) : noteBrokerRequests(result);
+  };
+
 
   // 1. Preconditions, fail closed.
   const platform = assertLocalHost(deps, workspaceRoot, kind);
@@ -465,9 +565,21 @@ async function publishUnit(parsed, deps, batch) {
     const tree = git(["rev-parse", "HEAD^{tree}"], workspaceRoot);
     if (tree !== batch.tree) refuse(`${unit}: HEAD tree ${tree} differs from the batch tree ${batch.tree}`);
   }
-  const dirty = git(["status", "--porcelain", "--", dir, ...GATE_CONFIG_FILES, ...(parsed.qualifyOnly ? ["Cargo.toml", "Cargo.lock"] : [])], workspaceRoot);
+  const feedPath = "packages/release/rightkit-versions.json";
+  const guardedPaths = [dir, ...GATE_CONFIG_FILES, ...(parsed.qualifyOnly && kind === "cargo" ? ["Cargo.toml", "Cargo.lock"] : []), ...(parsed.qualifyOnly && kind === "npm" ? [feedPath] : [])];
+  const dirty = git(["status", "--porcelain", "--", ...guardedPaths], workspaceRoot);
   if (dirty === null) refuse(`cannot read git status for ${dir}`);
   if (dirty !== "") refuse(`tree is not clean for ${dir} or the gate config (${GATE_CONFIG_FILES.join(", ")}); commit first:\n${dirty}`);
+  if (parsed.qualifyOnly && kind === "npm") {
+    const feedFile = path.join(workspaceRoot, feedPath);
+    if (unit === "@rightkit/release" && !fs.existsSync(feedFile)) refuse(`${unit}: committed ${feedPath} is required before packing`);
+    if (fs.existsSync(feedFile)) {
+      const committedFeed = git(["show", `HEAD:${feedPath}`], workspaceRoot);
+      if (committedFeed === null || committedFeed !== fs.readFileSync(feedFile, "utf8").trim()) refuse(`${feedPath} must match the committed HEAD before qualification`);
+      const feed = readJson(feedFile) ?? refuse(`cannot read ${feedPath}`);
+      if (feed.stagedNpm?.[unit] !== version && feed.registry?.npm?.[unit] !== version) refuse(`${unit}@${version}: stage the version in ${feedPath} and commit it before qualification`);
+    }
+  }
   if (await (deps.registryHas ?? defaultRegistryHas)({ kind, name: unit, version })) refuse(`${unit}@${version} is already on the ${kind === "npm" ? "npm" : "crates.io"} registry; bump the version`);
   log(`[right-release] local publish ${kind}:${unit}@${version} at ${head.slice(0, 12)} (local-build grant, ${LOCAL_HOST_POLICIES[platform]} policy)`);
 
@@ -484,10 +596,10 @@ async function publishUnit(parsed, deps, batch) {
     if (consumerDirty === null) refuse(`cannot read git status for the consumer rows of ${unit}`);
     if (consumerDirty !== "") refuse(`tree is not clean for the consumer rows of ${unit}; commit first:\n${consumerDirty}`);
   }
-  if (parsed.qualifyOnly) {
+  if (parsed.qualifyOnly && kind === "cargo") {
     const violations = (deps.scanSecrets ?? scanCrateForSecrets)(unitPath);
     if (violations.length) refuse(`qualification secret scan rejected: ${violations.join(", ")}`);
-    plan.steps.unshift({ command: "cargo", args: ["fmt", "-p", unit, "--check"], test: false });
+    plan.steps.unshift({ command: "cargo", args: qualifyFmtArgs(unit), test: false });
   }
   const modules = await (deps.loadWorkspaceModules ?? defaultLoadWorkspaceModules)(workspaceRoot);
   const { ResultScanner, TEST_COMMAND, judgeUnit } = modules.results;
@@ -496,7 +608,7 @@ async function publishUnit(parsed, deps, batch) {
   // written reason in ci/gate.config.json (rust.<crate>.allowIgnored). The count stays in the evidence.
   const configReason = kind === "cargo" && typeof gateConfig?.rust?.[unit]?.allowIgnored === "string" ? gateConfig.rust[unit].allowIgnored.trim() : "";
   const ignoredAllowed = Boolean(allowIgnored || parsed.allowIgnoredUnits?.includes(unit) || configReason);
-  const steps = parsed.qualifyOnly ? [{ command: `scanCrateForSecrets ${dir}`, ok: true }] : [];
+  const steps = parsed.qualifyOnly && kind === "cargo" ? [{ command: `scanCrateForSecrets ${dir}`, ok: true }] : [];
   for (const step of plan.steps) {
     const commandText = `${step.command} ${step.args.join(" ")}`;
     log(`[right-release] ${plan.id}: ${commandText}`);
@@ -519,39 +631,54 @@ async function publishUnit(parsed, deps, batch) {
   if (verdict.status === "fail" || steps.some((s) => s.failed > 0)) refuse(`${plan.id} not qualified: ${verdict.problems.join("; ") || "failed tests reported"}`);
   if (!(verdict.executed > 0)) refuse(`${plan.id} executed no test`);
   log(`[right-release] ${plan.id}: ${verdict.executed} passed, 0 failed, ${verdict.skipped} skipped, ${verdict.ignored} ignored${isAssetGated ? " (asset-gated: RIGHTKIT_REQUIRE_ASSETS=0, skips recorded)" : ""}`);
+  const packageEnv = yield { stage: "compile", kind, name: unit, version, commit: head, brokerRequests: brokerRequests.splice(0) };
+  if (packageEnv) Object.assign(env, testEnv({ env: packageEnv }, isAssetGated));
 
   // 3. Pack the artifact and hash it.
-  const scratch = fs.mkdtempSync(path.join(deps.tmpdir ?? os.tmpdir(), "rk-local-publish-"));
+  // An npm pack is a broker job whose --dir and --pack-destination the adapter accepts only under the host's scratch root, so it
+  // packs there (the workspace rule for run output) rather than in the OS temp directory.
+  const scratchRoot = deps.tmpdir ?? (kind === "npm" ? (platform === "win32" ? "D:\\scratch" : "/Volumes/D/scratch") : os.tmpdir());
+  const scratch = fs.mkdtempSync(path.join(scratchRoot, "rk-local-publish-"));
   const cleanup = () => fs.rmSync(scratch, { recursive: true, force: true });
   try {
     let artifactFile; const packCommands = [];
+    let packDir = dir;
     if (kind === "npm" && unit === SWAP_HELPER_PACKAGE) {
+      if (parsed.qualifyOnly) {
+        // Signing writes its binary and receipt. Keep both in the pack copy, never the source checkout.
+        packDir = path.join(scratch, "package-source");
+        fs.cpSync(unitPath, packDir, { recursive: true, filter: (source) => path.basename(source) !== "node_modules" });
+      }
       // #258: the package ships a Developer-ID-signed bin/darwin/rightkit-swap; build, sign and verify it before packing (fails closed).
-      try { (deps.prepareSwapHelper ?? prepareSwapHelper)({ workspaceRoot, packageDir: unitPath, platform, run, env, log }); }
+      try { (deps.prepareSwapHelper ?? prepareSwapHelper)({ workspaceRoot, packageDir: parsed.qualifyOnly ? packDir : unitPath, platform, run, env, log }); }
       catch (error) { refuse(`${error.code ? `[${error.code}] ` : ""}${error.message}`); }
       packCommands.push(`rustright cargo ${SWAP_HELPER_CARGO_ARGS.join(" ")} && codesign --verify --strict bin/darwin/rightkit-swap`);
     }
     if (kind === "npm") {
       // The feed a tarball ships must list the version it ships with (#319): stage it before packing.
       const feedFile = path.join(workspaceRoot, "packages", "release", "rightkit-versions.json");
-      if (fs.existsSync(feedFile)) await withVersionsLock(() => (deps.stageSourceVersions ?? stageSourceVersions)([{ registry: "npm", name: unit, version }], { file: feedFile, root: workspaceRoot, log }));
-      const args = ["--dir", dir, "pack", "--pack-destination", scratch];
+      if (!parsed.qualifyOnly && fs.existsSync(feedFile)) await withVersionsLock(() => (deps.stageSourceVersions ?? stageSourceVersions)([{ registry: "npm", name: unit, version }], { file: feedFile, root: workspaceRoot, log }));
+      // The tarball goes to an empty `pack` directory inside the scratch directory: the adapter takes --pack-destination only as a
+      // child of a scratch directory (never the scratch directory itself) and refuses one that already holds a tarball.
+      const packOut = path.join(scratch, "pack");
+      fs.mkdirSync(packOut);
+      const args = npmPackArgs(packDir, packOut);
       packCommands.push(`pnpm ${args.join(" ")}`);
       const packed = await run("pnpm", args, { cwd: workspaceRoot, env });
       if (packed.error || packed.status !== 0) refuse(`pnpm pack failed for ${unit}\n${tail(`${packed.stdout ?? ""}\n${packed.stderr ?? ""}`)}`);
-      artifactFile = path.join(scratch, tarballName(unit, version));
+      artifactFile = path.join(packOut, tarballName(unit, version));
       if (!fs.existsSync(artifactFile)) refuse(`pnpm pack did not produce ${path.basename(artifactFile)}`);
       const checked = modules.checkNpmTarball({ file: artifactFile, name: unit, version, dir, spawn: deps.spawnSync ?? spawnSync });
       if (checked.problems.length) refuse(`${unit}: packed tarball refused:\n  - ${checked.problems.join("\n  - ")}`);
     } else {
       // A combined publish verifies once in `cargo publish`; detached qualification verifies here before
       // its evidence leaves this host, so the publishing host can reuse that exact archive's proof.
-      const packageArgs = ["package", "--locked", ...(parsed.qualifyOnly ? [] : ["--no-verify"]), "-p", unit];
+      const packageArgs = cargoPackageArgs(unit, parsed.qualifyOnly);
       packCommands.push(`cargo ${packageArgs.join(" ")}`);
       const packed = await run("cargo", withCargoJobs(packageArgs, parsed.jobs), { cwd: workspaceRoot, env });
       if (packed.error || packed.status !== 0) refuse(`cargo package failed for ${unit}\n${tail(`${packed.stdout ?? ""}\n${packed.stderr ?? ""}`)}`);
       if (parsed.qualifyOnly) steps.push({ command: `cargo ${packageArgs.join(" ")}`, ok: true });
-      const metadataArgs = ["metadata", "--offline", "--format-version", "1", "--no-deps"];
+      const metadataArgs = [...CARGO_METADATA_ARGS];
       const meta = await runCargoReadOnly(metadataArgs, { cwd: workspaceRoot, env }, (_command, args, settings) => run("cargo", args, settings),
         (failed) => log(`[right-release] offline Cargo metadata missed cache; retrying online once\n${failed.stdout ?? ""}${failed.stderr ? `\n${failed.stderr}` : ""}`));
       const actualMetadataArgs = meta.usedOfflineFallback ? metadataArgs.filter((arg) => arg !== "--offline") : metadataArgs;
@@ -565,6 +692,16 @@ async function publishUnit(parsed, deps, batch) {
       if (!fs.existsSync(artifactFile)) refuse(`cargo package did not produce ${artifactFile}`);
     }
     const artifactSha256 = sha256(fs.readFileSync(artifactFile));
+    if (parsed.qualifyOnly && (git(["rev-parse", "HEAD"], workspaceRoot) !== head || git(["status", "--porcelain", "--", ...guardedPaths], workspaceRoot) !== "")) refuse("qualification inputs changed while preparing the artifact; no bundle was created");
+    if (parsed.qualifyOnly) {
+      fs.mkdirSync(parsed.bundleDir, { recursive: false });
+      const bundledArtifact = path.join(parsed.bundleDir, path.basename(artifactFile));
+      fs.copyFileSync(artifactFile, bundledArtifact, fs.constants.COPYFILE_EXCL);
+      if (sha256(fs.readFileSync(bundledArtifact)) !== artifactSha256) refuse("qualification archive changed while copying");
+      artifactFile = bundledArtifact;
+      yield { stage: "package", kind, name: unit, version, commit: head, artifactFile, artifactSha256, brokerRequests: brokerRequests.splice(0) };
+      if (sha256(fs.readFileSync(artifactFile)) !== artifactSha256) refuse("qualification archive changed after packaging");
+    }
 
     // 4. Evidence in the normal schema, then the EXISTING gate.
     const commands = [...plan.steps.map((s) => `${s.command} ${s.args.join(" ")}`), ...packCommands, ...(batch ? batch.commands : [])];
@@ -583,23 +720,21 @@ async function publishUnit(parsed, deps, batch) {
         steps: steps.map(({ command, ok, executed, failed, ignored, skipped, binaries }) => ({ command, ok, ...(executed === undefined ? {} : { executed, failed, ignored, skipped, binaries }) })),
       }],
     };
-    const evidencePath = path.resolve(defaultEvidencePath(workspaceRoot, kind, unit));
+    // A qualification writes its evidence beside the bytes, in the bundle: the tracked release-evidence/gate file is the record of a
+    // host publish, and rewriting it would dirty the checkout the unit door guards (the first `--to release --unit` run stopped
+    // there, 2026-10-27). Never overwrite a bundle's evidence.
+    const evidencePath = parsed.qualifyOnly ? path.join(parsed.bundleDir, "gate.json") : path.resolve(defaultEvidencePath(workspaceRoot, kind, unit));
     fs.mkdirSync(path.dirname(evidencePath), { recursive: true });
-    fs.writeFileSync(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`);
+    fs.writeFileSync(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`, { flag: parsed.qualifyOnly ? "wx" : "w" });
     log(`[right-release] wrote ${evidencePath} (artifact sha256 ${artifactSha256})`);
-    const gateOptions = { kind, name: unit, version, packagePath: unitPath, evidencePath };
+    const gateOptions = { kind, name: unit, version, packagePath: unitPath, evidencePath, artifactBytes: fs.readFileSync(artifactFile) };
     (deps.enforceGate ?? enforcePublicationGate)(gateOptions, { write: (line) => log(line.replace(/\n$/, "")) });
 
     if (parsed.qualifyOnly) {
-      // Keep bytes and their normal gate evidence together outside the checkout. Never overwrite a bundle.
-      fs.mkdirSync(parsed.bundleDir, { recursive: false });
-      const bundledArtifact = path.join(parsed.bundleDir, path.basename(artifactFile));
-      const bundledEvidence = path.join(parsed.bundleDir, "gate.json");
-      fs.copyFileSync(artifactFile, bundledArtifact, fs.constants.COPYFILE_EXCL);
-      if (sha256(fs.readFileSync(bundledArtifact)) !== artifactSha256) refuse("qualification archive changed while copying");
-      fs.copyFileSync(evidencePath, bundledEvidence, fs.constants.COPYFILE_EXCL);
-      log(`[right-release] qualified ${unit}@${version}; bundle ${parsed.bundleDir}; publish cargo --crate ${unit} --from-evidence ${bundledEvidence}`);
-      return { kind, name: unit, version, commit: head, artifactSha256, evidencePath: bundledEvidence, artifactFile: bundledArtifact, qualifiedOnly: true };
+      // Bytes and evidence stay together outside the checkout.
+      const bundledEvidence = evidencePath;
+      log(`[right-release] qualified ${unit}@${version}; bundle ${parsed.bundleDir}${kind === "cargo" ? `; publish cargo --crate ${unit} --from-evidence ${bundledEvidence}` : ""}`);
+      return { kind, name: unit, version, commit: head, artifactSha256, evidencePath: bundledEvidence, artifactFile, qualifiedOnly: true };
     }
 
     // 5. The EXISTING publish path.

package/managed-cargo.mjs

@@ -1,11 +1,51 @@
 import { discoverBrokerSocket, managedControlCandidates, resolveManagedRoots } from './managed-roots.mjs';
 import { randomUUID } from "node:crypto";
 import { homedir, userInfo } from "node:os";
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { spawn as spawnProcess, spawnSync } from "./background-process.mjs";
 
+/**
+ * Linux, and any host that is neither Mac nor Windows, never uses the RustRight broker: WSL2, a VM, a cloud or CI runner, Linux hosted on
+ * the Dell (GATE-CONTRACT §1 "One entry"; joint plan step 4). Every managed-cargo helper follows this one policy, whatever control-root,
+ * socket or PATH entries the environment carries.
+ */
+export const directPlatform = (platform = process.platform) => platform !== "darwin" && platform !== "win32";
+
+const MANAGED_AGENT_BIN = /(?:^|\/)(?:\.rightkit-managed|rightkitmanagedagent|rightkit\/build-control)\/agent-bin\/?$/i;
+function fileHead(file) {
+  let fd = null;
+  try { fd = openSync(file, "r"); const b = Buffer.alloc(4096); const n = readSync(fd, b, 0, 4096, 0); return b.subarray(0, n).toString("latin1"); }
+  catch { return ""; } finally { if (fd !== null) try { closeSync(fd); } catch { /* closed */ } }
+}
+
+/**
+ * On a direct (Linux) host: PATH without the directories whose `cargo` is a RustRight shim (the managed agent-bin, a configured
+ * RIGHTKIT_MANAGED_AGENT_BIN, or a script that routes through the broker, read 4 KiB at most), and the first real cargo left on it.
+ * Plain `cargo` then can only be a real toolchain; with none, a cargo launch fails as missing, never through a shim.
+ */
+export function directCargoPath({ env = process.env, exists = existsSync, readHead = fileHead } = {}) {
+  const configured = env.RIGHTKIT_MANAGED_AGENT_BIN ? path.posix.resolve(env.RIGHTKIT_MANAGED_AGENT_BIN) : null;
+  const kept = []; const dropped = []; let cargo = null;
+  for (const dir of String(env.PATH ?? "").split(":").filter(Boolean)) {
+    const candidate = path.posix.join(dir, "cargo");
+    const isShim = exists(candidate) && (MANAGED_AGENT_BIN.test(dir) || (configured && path.posix.resolve(dir) === configured) || /cargo-guard\.mjs|rustright/i.test(readHead(candidate)));
+    if (isShim) { dropped.push(dir); continue; }
+    kept.push(dir);
+    if (!cargo && exists(candidate)) cargo = candidate;
+  }
+  return { path: kept.join(":"), dropped, cargo };
+}
+
+/** `env` for a direct host: PATH without RustRight shim directories. Unchanged on Mac and Windows. */
+export function directCargoEnv(env = process.env, platform = process.platform, exists = existsSync) {
+  if (!directPlatform(platform)) return env;
+  const direct = directCargoPath({ env, exists });
+  return direct.dropped.length ? { ...env, PATH: direct.path } : env;
+}
+
 export function managedRuntimeClient(env = process.env, platform = process.platform, exists = existsSync) {
+  if (directPlatform(platform)) return undefined;
   const roots = managedControlCandidates({ env, platform });
   const paths = platform === 'win32' ? path.win32 : path.posix;
   // runtime-current ships the native `rustright` client.
@@ -54,7 +94,8 @@ export function acquireManagedRunLease({ command, env = process.env, platform =
   return { path: file, release() { rmSync(file, { force: true }); } };
 }
 
-export function managedHost(env) {
+export function managedHost(env, platform = process.platform) {
+  if (directPlatform(platform)) return false; // Linux is never broker-managed (directPlatform), whatever the env names
   return Boolean(env.RIGHTKIT_BUILD_BROKER_SOCKET)
     || /(?:^|[;:])[^;:]*[/\\](?:\.rightkit-managed|rightkitmanagedagent|rightkit[/\\]build-control)[/\\]agent-bin(?:[;:]|$)/i.test(String(env.PATH ?? ""));
 }
@@ -75,9 +116,10 @@ export function runCargoSync(args, options = {}, { platform = process.platform,
   }
   // The Mac never falls back to direct Cargo, except on GitHub Actions runners, which have no
   // RightKit runtime and use the toolchain's cargo (release-candidate signing jobs).
-  const hostedCi = env.GITHUB_ACTIONS === 'true' && !managedHost(env);
-  if ((platform === 'darwin' && !hostedCi) || (managedHost(env) && platform === 'win32')) return unavailable('installed RightKit runtime client is unavailable for managed Cargo metadata');
-  return spawn("cargo", args, options);
+  const hostedCi = env.GITHUB_ACTIONS === 'true' && !managedHost(env, platform);
+  if ((platform === 'darwin' && !hostedCi) || (managedHost(env, platform) && platform === 'win32')) return unavailable('installed RightKit runtime client is unavailable for managed Cargo metadata');
+  // A direct (Linux) host runs the real toolchain: RustRight shim directories are taken off PATH first.
+  return spawn("cargo", args, directPlatform(platform) ? { ...options, env: directCargoEnv(env, platform, exists) } : options);
 }
 
 function unavailable(message) {

package/managed-root-guard.mjs

@@ -0,0 +1,34 @@
+// The managed-root guard (item 5, signed item5-sage-decisions-2.md D4 rule 1): the gate never creates the host's managed root, and on
+// the Mac never accepts one on the boot volume. It lives here, not in snapshot.mjs, because build-ownership.mjs guards the root as the
+// FIRST action of an acquisition and snapshot.mjs already imports build-ownership.mjs. snapshot.mjs re-exports both names.
+import fs from "node:fs";
+
+export class SnapshotError extends Error {
+  /** `code` is "mismatch" (the snapshot is not the commit's tree), "busy" (another sync holds it), "refused" (the commit cannot be
+   * materialised exactly, or the root is not one a snapshot may live in: a gitlink, an unsafe path, a link out of the snapshot, a
+   * missing managed root, an open-mode root, an unknown revision) or "error" (could not run). `reason`, when present, names the
+   * refusal: "gitlink", "unknown-revision", "managed-root-missing", "managed-root-on-boot-volume", "root-open-mode",
+   * "root-not-owned", "root-parent-missing". */
+  constructor(code, message, reason) { super(message); this.code = code; if (reason) this.reason = reason; }
+}
+
+const lstat = (p) => { try { return fs.lstatSync(p, { bigint: true }); } catch (e) { if (e.code === "ENOENT" || e.code === "ENOTDIR") return null; throw e; } };
+const deviceOf = (p) => fs.statSync(p, { bigint: true }).dev;
+
+/**
+ * The managed root must already exist (the gate never creates it) and, on the Mac, live on another device than `/`: with the volume
+ * unmounted, `/Volumes/D/.rightkit-managed` made on the boot volume (by anything) would otherwise hold the snapshots. Volume identity
+ * and the disk floor for the broker's own writes are the broker's (BC B16). Throws SnapshotError("refused") with a named reason.
+ */
+export function requireManagedRoot(managedRoot, { platform = process.platform, device = deviceOf } = {}) {
+  const st = lstat(managedRoot);
+  if (!st) throw new SnapshotError("refused", `the managed root ${managedRoot} does not exist: the gate never creates it (the volume may be unmounted); nothing was written`, "managed-root-missing");
+  if (!st.isDirectory()) throw new SnapshotError("refused", `the managed root ${managedRoot} is not a plain directory (a link is never followed)`, "managed-root-missing");
+  if (platform === "darwin") {
+    let here; let boot;
+    try { here = device(managedRoot); boot = device("/"); }
+    catch (e) { throw new SnapshotError("error", `cannot read the device of the managed root ${managedRoot} or of /: ${e.message}`); }
+    if (here === boot) throw new SnapshotError("refused", `the managed root ${managedRoot} is on the same device as / (the boot volume): a snapshot there would not be on the managed volume (is the volume mounted?)`, "managed-root-on-boot-volume");
+  }
+  return managedRoot;
+}