@rightkit/release 0.6.13 → 0.6.14

package/unit-gate.mjs

@@ -2,13 +2,20 @@
 import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { locateBrokerClient, spawnBrokerClient } from "./broker-client.mjs";
+import { publicationRowProblem } from "./publication-outcomes.mjs";
 import { localBuildGranted } from "./execution-policy.mjs";
 import { readCargoPackage } from "./crate-graph.mjs";
 import { spawnSync as nodeSpawnSync } from "./background-process.mjs";
 import { endRun, startRun, stagesTo } from "./gate-stages.mjs";
-import { qualificationNonce } from "./provenance-verify.mjs";
+import { RIGHTKIT_REPOSITORY, buildDirectOrigin, directStageEvidence, verifyDirectOrigin } from "./direct-origin.mjs";
+import { exclusionsFor } from "./pack-digest.mjs";
+import { ATTEST_STAGE_NONCE_ENV, qualificationNonce } from "./provenance-verify.mjs";
+import { verifyQualificationReceipts } from "./qualification-verify.mjs";
 import { assignJobs, describeCommand, expectedStageCommands } from "./stage-commands.mjs";
+import { resolveManagedRoots } from "./managed-roots.mjs";
+import { controlPlaneProblem } from "./control-plane.mjs";
 
 const GH = process.platform === "win32" ? "C:\\Program Files\\GitHub CLI\\gh.exe" : "/opt/homebrew/bin/gh";
 const defaultRun = (cmd, args, options = {}) => nodeSpawnSync(cmd, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, ...options });
@@ -40,8 +47,10 @@ export function defaultStageCommands({ unit, root, platform, readJson = defaultR
   return expectedStageCommands({ kind: unit.kind, unit: unit.name, config: readJson(path.join(root, "ci", "gate.config.json")), manifest, platform });
 }
 
-export function readBrokerReceipt(id, { run = defaultRun } = {}) {
-  const r = run("rustright", ["status", id], { encoding: "utf8", timeout: 60_000 });
+export function readBrokerReceipt(id, { run = defaultRun, platform = process.platform, readFile, env = process.env, installed } = {}) {
+  // The client starts the one way every gate child starts it (broker-client.mjs): on Windows `rustright` is rustright.cmd, which node cannot
+  // spawn, so its target .exe is read from the shim and started directly.
+  const r = spawnBrokerClient(run, locateBrokerClient({ platform, env, probe: run, ...(installed ? { installed } : {}) }), ["status", id], { encoding: "utf8", timeout: 60_000, windowsHide: true, shell: false }, { platform, readFile });
   if (r.error || r.status !== 0) throw new Error(`the broker cannot report job ${id} (rustright status failed)`);
   let doc;
   try { doc = JSON.parse(r.stdout); } catch { throw new Error(`the broker's status of job ${id} is not JSON`); }
@@ -50,16 +59,35 @@ export function readBrokerReceipt(id, { run = defaultRun } = {}) {
   return { id, provenance: receipt.provenance };
 }
 /** `<bundle>/qualification.json`: the local stages that passed and the one artifact sha256 they bound, for the dispatcher. */
-export function writeQualification({ report, artifact, unit, commit, tree, runtime, executor, write = fs.writeFileSync }) {
+export function writeQualification({ report, artifact, unit, commit, tree, runtime, executor, directOrigin = null, write = fs.writeFileSync }) {
   for (const stage of ["check", "compile", "package", "qualify"]) if (report.stages?.[stage]?.ok !== true) throw new Error(`release needs stage ${stage} ok before it runs`);
   if (!artifact?.artifactFile || !/^[0-9a-f]{64}$/.test(artifact.artifactSha256 ?? "")) throw new Error("release needs the qualified artifact");
+  // An npm unit is bound hosted by its content digest (pack-digest.mjs), not by the archive's bytes; for @rightkit/release the local archive
+  // must also have held the swap helper and its signing receipt, the two entries that digest leaves out.
+  const content = {};
+  if (unit.kind === "npm") {
+    if (!/^[0-9a-f]{64}$/.test(artifact.contentSha256 ?? "")) throw new Error("release needs the qualified npm archive's content digest");
+    content.contentSha256 = artifact.contentSha256;
+    const excluded = exclusionsFor(unit.name);
+    if (excluded.length) {
+      if (!Array.isArray(artifact.contentExcluded) || [...artifact.contentExcluded].sort().join("\n") !== [...excluded].sort().join("\n")) throw new Error(`release needs the qualified ${unit.name} archive to hold ${excluded.join(" and ")}`);
+      content.contentExcluded = [...artifact.contentExcluded].sort();
+    }
+  }
   const receipt = { schema: QUALIFICATION_SCHEMA, unit: { kind: unit.kind, name: unit.name, version: unit.version }, commit, tree, runtime, executor: executor?.kind ?? null,
-    stages: Object.fromEntries(["check", "compile", "package", "qualify"].map((s) => [s, { ...report.stages[s] }])), artifactSha256: artifact.artifactSha256, writtenAt: new Date().toISOString() };
-  // The broker's signed receipts for the compile and package stages are what the hosted admission verifies; without them the
-  // booleans above are only this process's say-so.
-  for (const stage of ATTESTED_STAGES) {
-    const list = report.stages[stage].receipts;
-    if (!Array.isArray(list) || list.length < 1 || list.length > MAX_STAGE_RECEIPTS) throw new Error(`release needs 1 to ${MAX_STAGE_RECEIPTS} signed broker receipts of the ${stage} stage (found ${Array.isArray(list) ? list.length : "none"})`);
+    stages: Object.fromEntries(["check", "compile", "package", "qualify"].map((s) => [s, { ...report.stages[s] }])), artifactSha256: artifact.artifactSha256, ...content, writtenAt: new Date().toISOString() };
+  // GB-29: a direct Linux origin has no broker and so no signed receipts; it carries its direct-origin record instead (direct-origin.mjs), which the hosted side re-derives and never trusts
+  // by itself. Every other host owes the broker's signed receipts for the compile and package stages.
+  if (executor?.kind === "direct") {
+    if (!directOrigin) throw new Error("a direct origin's qualification needs its direct-origin record");
+    receipt.directOrigin = directOrigin;
+  } else {
+    // The broker's signed receipts for the compile and package stages are what the hosted admission verifies; without them the
+    // booleans above are only this process's say-so.
+    for (const stage of ATTESTED_STAGES) {
+      const list = report.stages[stage].receipts;
+      if (!Array.isArray(list) || list.length < 1 || list.length > MAX_STAGE_RECEIPTS) throw new Error(`release needs 1 to ${MAX_STAGE_RECEIPTS} signed broker receipts of the ${stage} stage (found ${Array.isArray(list) ? list.length : "none"})`);
+    }
   }
   if (JSON.stringify(receipt).length > MAX_QUALIFICATION_BYTES) throw new Error("the qualification receipt with its broker receipts exceeds the workflow dispatch input limit");
   const file = path.join(path.dirname(artifact.artifactFile), "qualification.json");
@@ -67,17 +95,93 @@ export function writeQualification({ report, artifact, unit, commit, tree, runti
   return file;
 }
 
+/**
+ * GB-07 (BROKER-CONTRACT section 16): the coordinator that dispatches and pre-flights a unit is the TRUSTED, INSTALLED one: the running gate's own `scripts/ci/rk-pipeline.mjs`, found from this
+ * module's own location (never from the `root` snapshot or the `checkout` the release was asked about, so a modified or planted coordinator there cannot change the candidate's logic) with the
+ * digest of its bytes, which the release reports. Throws when the gate has none beside it.
+ */
+export function trustedCoordinator({ moduleUrl = import.meta.url, exists = fs.existsSync, readFile = fs.readFileSync } = {}) {
+  const file = path.resolve(path.dirname(fileURLToPath(moduleUrl)), "..", "..", "scripts", "ci", "rk-pipeline.mjs");
+  if (!exists(file)) throw new Error(`the installed coordinator ${file} is not beside the running gate; dispatch and pre-flight run only the gate's own installed rk-pipeline (never one under the snapshot or the checkout), so nothing was started`);
+  return { file, sha256: createHash("sha256").update(readFile(file)).digest("hex") };
+}
+
+export { controlPlaneProblem };
+
+/**
+ * GB-07: the in-gate-process entry to the trusted, installed coordinator. The coordinator's own module is imported into THIS (the gate's) process, from the gate's own installed location
+ * (trustedCoordinator), and its `runPipeline` runs the canary, pre-flight, dispatch and watch as in-process calls over the explicit root, commit and qualification the release passes: no child
+ * process is started from a path under the snapshot or the checkout, and the coordinator derives no root from where it lives. `expectedSha256` is a registered pin (the digest the host enrolled for
+ * the installed coordinator); the file is hashed before and again after it is imported, so bytes that change under the gate are refused. A coordinator that sits inside the managed snapshots root
+ * or inside the source snapshot is refused (it would be the candidate's own bytes), and so is a module without the entry.
+ */
+export async function loadInGatePipeline({ coordinator = trustedCoordinator(), expectedSha256 = null, snapshotsRoot = null, root = null, pathApi = path, importModule = (url) => import(url), readFile = fs.readFileSync } = {}) {
+  const fold = (p) => { const r = pathApi.resolve(String(p)); return pathApi === path.win32 ? r.toLowerCase() : r; };
+  const inside = (child, parent) => { const rel = pathApi.relative(fold(parent), fold(child)); return rel === "" || (!rel.startsWith("..") && !pathApi.isAbsolute(rel)); };
+  if (!coordinator?.file || !/^[0-9a-f]{64}$/.test(coordinator.sha256 ?? "")) throw new Error("the in-gate coordinator needs its installed file and the sha256 of its bytes; nothing was started");
+  if (expectedSha256 !== null && coordinator.sha256 !== expectedSha256) throw new Error(`the installed coordinator ${coordinator.file} is ${coordinator.sha256.slice(0, 12)}, not the pinned ${String(expectedSha256).slice(0, 12)}; the gate runs only the coordinator the host registered, so nothing was started`);
+  for (const [where, parent] of [["the managed snapshots root", snapshotsRoot], ["the source snapshot", root]]) {
+    if (parent && inside(coordinator.file, parent)) throw new Error(`the coordinator ${coordinator.file} is inside ${where} ${parent}: it would be the candidate's own bytes, never the trusted installed coordinator; nothing was started`);
+  }
+  const digest = () => createHash("sha256").update(readFile(coordinator.file)).digest("hex");
+  if (digest() !== coordinator.sha256) throw new Error(`the installed coordinator ${coordinator.file} changed after its digest was taken; nothing was started`);
+  const loaded = await importModule(pathToFileURL(coordinator.file).href);
+  if (digest() !== coordinator.sha256) throw new Error(`the installed coordinator ${coordinator.file} changed while it was loaded; nothing was started`);
+  if (typeof loaded?.runPipeline !== "function") throw new Error(`the installed coordinator ${coordinator.file} has no in-gate entry (runPipeline); nothing was started`);
+  return { runPipeline: loaded.runPipeline, coordinator: { file: coordinator.file, sha256: coordinator.sha256 } };
+}
+
+/** The managed snapshots root of this host (`<data root>/snapshots`), or null when the host's roots cannot be resolved. */
+const managedSnapshotsRoot = ({ env, platform }) => { try { return (platform === "win32" ? path.win32 : path.posix).join(resolveManagedRoots({ env, platform }).dataRoot, "snapshots"); } catch { return null; } };
+
 const requireBrokerHost = (executor) => { if (executor?.kind !== "broker") throw new Error("unit release runs only on a broker-managed host (the hosted qualification is dispatched by the RustRight rightkit-dispatch adapter); a direct host has no gate-owned release route, so no upload was started"); };
 
-export async function releaseUnit({ unit, root, commit, executor, env, artifact, qualification, platform = process.platform, run = defaultRun, readJson = defaultReadJson, out = console.log, scratch = platform === "win32" ? "D:\\scratch" : "/Volumes/D/scratch", registryBytes = defaultRegistryBytes }) {
+export async function releaseUnit({ unit, root, checkout = root, commit, tree = null, coordinator = null, pipeline = null, executor, env, artifact, qualification, platform = process.platform, run = defaultRun, readJson = defaultReadJson, out = console.log, scratch = platform === "win32" ? "D:\\scratch" : "/Volumes/D/scratch", registryBytes = defaultRegistryBytes }) {
   requireBrokerHost(executor);
+  // GB-07: the source root and the control-plane checkout are apart, and the coordinator is the gate's own installed one.
+  const snapshotsRoot = managedSnapshotsRoot({ env, platform });
+  const apart = controlPlaneProblem({ root, checkout, snapshotsRoot, pathApi: platform === "win32" ? path.win32 : path.posix });
+  if (apart) throw new Error(`${apart}; nothing was started`);
+  // The coordinator runs in this process when the gate loaded its in-gate entry (`pipeline`, loadInGatePipeline: production); otherwise the installed file runs as a child process (the older route).
+  const installed = pipeline?.coordinator ?? coordinator ?? trustedCoordinator();
+  if (pipeline) {
+    if (typeof pipeline.runPipeline !== "function") throw new Error("the in-gate coordinator entry has no runPipeline; nothing was started");
+    const api = platform === "win32" ? path.win32 : path.posix;
+    const fold = (p) => { const r = api.resolve(String(p)); return platform === "win32" ? r.toLowerCase() : r; };
+    const inside = (child, parent) => { const rel = api.relative(fold(parent), fold(child)); return rel === "" || (!rel.startsWith("..") && !api.isAbsolute(rel)); };
+    if (snapshotsRoot && inside(installed.file, snapshotsRoot)) throw new Error(`the coordinator ${installed.file} is inside the managed snapshots root ${snapshotsRoot}: only the installed coordinator runs; nothing was started`);
+    if (inside(installed.file, root) && checkout !== root) throw new Error(`the coordinator ${installed.file} is inside the source snapshot ${root}: it would be the candidate's own bytes, never the trusted installed coordinator; nothing was started`);
+  }
   if (typeof qualification !== "string" || !fs.existsSync(qualification)) throw new Error("release needs the unit qualification receipt (written by the gate after the qualify stage); nothing is dispatched without it");
   const registry = unit.kind === "npm" ? "npm" : "crates";
-  const pipeline = path.join(root, "scripts", "ci", "rk-pipeline.mjs");
+  // rk-pipeline (the canary, the preflight rows, the dispatch) makes its broker calls as ROOT and ADAPTER requests, and the broker refuses any
+  // such request whose workspace is inside a managed snapshot (service.rs "a root request cannot run inside a managed snapshot"). So it runs from
+  // the PRIMARY CHECKOUT (`checkout`; `root` is the snapshot, which stays the source of the bytes that were qualified). rk-preflight proves the
+  // commit itself: it refuses a checkout whose tracked files are modified, and every row reads HEAD's committed bytes (resolveRowWorkspace
+  // compares each consumer manifest with `git show <sha>`); rk-pipeline dispatch pins HEAD to origin/main. Here HEAD must also be the
+  // qualified commit, or the pre-flight and the dispatch would prove another commit than the one that was packaged.
+  if (checkout !== root) {
+    const head = run("git", ["rev-parse", "HEAD"], { cwd: checkout, encoding: "utf8" });
+    if (head.status !== 0 || String(head.stdout ?? "").trim() !== commit) throw new Error(`the primary checkout ${checkout} is not at the qualified commit ${commit.slice(0, 12)} (HEAD ${String(head.stdout ?? "").trim().slice(0, 12) || "unreadable"}); the release runs rk-pipeline from the checkout, so it proves nothing else, and nothing was started`);
+  }
+  // GB-07: the coordinator judges the primary checkout (the broker refuses a root request whose workspace is inside a managed snapshot), and the candidate's logic is protected as well: HEAD is the
+  // qualified commit (above) AND the checkout holds exactly that commit's bytes: no tracked file modified and nothing untracked under scripts/ci or packages/release (an untracked sibling is
+  // importable), checked BEFORE the first coordinator step starts. A modified or newer coordinator in the live checkout therefore can never stand in for the candidate's own.
+  if (checkout !== root) {
+    const dirty = run("git", ["status", "--porcelain", "--", "scripts/ci", "packages/release"], { cwd: checkout, encoding: "utf8" });
+    const tracked = run("git", ["status", "--porcelain", "--untracked-files=no"], { cwd: checkout, encoding: "utf8" });
+    const changed = [dirty, tracked].map((r) => (r.status === 0 ? String(r.stdout ?? "").trim() : null));
+    if (changed.some((c) => c === null)) throw new Error(`the primary checkout ${checkout} cannot be read for modified coordinator files; nothing is dispatched`);
+    const lines = [...new Set(changed.flatMap((c) => c.split("\n").filter(Boolean)))];
+    if (lines.length) throw new Error(`the primary checkout ${checkout} holds modified or untracked files (${lines.slice(0, 4).map((l) => l.trim()).join("; ")}${lines.length > 4 ? "; ..." : ""}); the coordinator that dispatches ${unit.name} must be exactly the qualified commit ${commit.slice(0, 12)}'s bytes, so nothing is dispatched`);
+  }
   const stateFile = platform === "win32" ? "D:\\scratch\\rk-pipeline\\state.json" : "/Volumes/D/scratch/rk-pipeline/state.json";
-  const step = (label, args, { accept = [0], acceptWhen = null } = {}) => {
+  const stepRun = pipeline
+    ? (args) => pipeline.runPipeline({ argv: args, root: checkout, env, platform, stateFile })
+    : (args) => run(process.execPath, [installed.file, ...args], { cwd: checkout, env, stdio: ["ignore", "pipe", "pipe"] });
+  const step = async (label, args, { accept = [0], acceptWhen = null } = {}) => {
     out(`rightkit-gate: [release] ${label}`);
-    const r = run(process.execPath, [pipeline, ...args], { cwd: root, env, stdio: ["ignore", "pipe", "pipe"] });
+    const r = await stepRun(args);
     const accepted = r.status === 0 || (accept.includes(r.status) && (!acceptWhen || acceptWhen(r)));
     if (!accepted) {
       const said = `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`.split("\n").map((l) => l.trim()).filter((l) => l && !l.includes("note:")).slice(-4).join(" | ");
@@ -85,21 +189,30 @@ export async function releaseUnit({ unit, root, commit, executor, env, artifact,
     }
     return r;
   };
+  // The candidate's identity is explicit: the commit and tree the gate qualified and the artifact digest it packaged (never read from files under the checkout). A dispatch record for the commit is the
+  // call's own only when it names the same tree and the same artifact digest; one that names another, or none, is ambiguous and never adopted.
+  const identity = { tree, artifactSha256: artifact?.artifactSha256 ?? null };
   const findDispatch = () => {
     const found = Object.values(readJson(stateFile).dispatches ?? {}).filter((d) => d.unit === unit.name && d.sha === commit && d.registry === registry);
     if (found.length > 1) throw new Error(`${found.length} dispatch records for ${unit.name} at ${commit.slice(0, 12)} in rk-pipeline state; reconcile before any retry`);
-    return found[0];
+    const [record] = found;
+    if (record) {
+      if (identity.tree !== null && record.tree === undefined || identity.artifactSha256 !== null && record.artifactSha256 === undefined) throw new Error(`the dispatch record of ${unit.name} at ${commit.slice(0, 12)} names no tree or artifact digest (no identity), so it cannot be reconciled with this candidate; reconcile rk-pipeline state by hand`);
+      if (identity.tree !== null && record.tree !== identity.tree) throw new Error(`the dispatch record of ${unit.name} at ${commit.slice(0, 12)} names tree ${String(record.tree).slice(0, 12)}, not the candidate's ${identity.tree.slice(0, 12)}; reconcile rk-pipeline state by hand`);
+      if (identity.artifactSha256 !== null && record.artifactSha256 !== identity.artifactSha256) throw new Error(`the dispatch record of ${unit.name} at ${commit.slice(0, 12)} names artifact digest ${String(record.artifactSha256).slice(0, 12)}, not the candidate's ${identity.artifactSha256.slice(0, 12)}; reconcile rk-pipeline state by hand`);
+    }
+    return record;
   };
   // The pipeline canary (rk-release-canary: the candidate's `right-release doctor` against every app on both hosts, versus the
   // registry's version) runs before the pre-flight. rk-pipeline exits 2 both for "no pipeline canary for this unit" and for any
   // internal error, so 2 is accepted only when it says the former (reviewer, 2026-10-27); a canary error never reads as no canary.
-  step(`pipeline canary of ${unit.name} (doctor on every app, both hosts, candidate vs registry)`, ["canary", unit.name],
+  await step(`pipeline canary of ${unit.name} (doctor on every app, both hosts, candidate vs registry)`, ["canary", unit.name, "--sha", commit],
     { accept: [2], acceptWhen: (r) => /no pipeline canary for this unit/.test(`${r.stdout ?? ""}\n${r.stderr ?? ""}`) });
-  step(`local pre-flight of ${unit.name} through the broker`, ["preflight", unit.name, "--registry", registry]);
-  step(`broker-admitted hosted qualification dispatch of ${unit.name} at ${commit.slice(0, 12)}`, ["dispatch", unit.name, "--registry", registry, "--qualification", qualification]);
+  await step(`local pre-flight of ${unit.name} through the broker`, ["preflight", unit.name, "--registry", registry, "--sha", commit]);
+  await step(`broker-admitted hosted qualification dispatch of ${unit.name} at ${commit.slice(0, 12)}`, ["dispatch", unit.name, "--registry", registry, "--sha", commit, "--qualification", qualification]);
   const dispatched = findDispatch();
   if (!dispatched?.runId || !dispatched.runAttempt) throw new Error(`no dispatch record with a run for ${unit.name} at ${commit.slice(0, 12)}; nothing is claimed (reconcile rk-pipeline state before any retry)`);
-  step(`waiting for publish.yml run ${dispatched.runId}, its publish-direct upload run and the registry`, ["watch", "--wait"]);
+  await step(`waiting for publish.yml run ${dispatched.runId}, its publish-direct upload run and the registry`, ["watch", "--wait"]);
   const done = findDispatch();
   if (done?.status !== "published" || done.version !== unit.version || !done.uploadRunId) throw new Error(`${unit.name}: the watch ended without a published record (${done?.status ?? "none"}${done?.conclusion ? `: ${done.conclusion}` : ""}); nothing is claimed`);
   const receipt = readPublicationReceipt({ uploadRunId: done.uploadRunId, runId: done.runId, runAttempt: done.runAttempt, run, env, scratch });
@@ -116,7 +229,10 @@ export async function releaseUnit({ unit, root, commit, executor, env, artifact,
   const rows = (receipt.receipts ?? []).filter((r) => r.unit === unit.name && r.version === unit.version);
   if (rows.length !== 1) throw new Error(`${unit.name}@${unit.version}: the publication receipt holds ${rows.length} row(s) for this unit; exactly one is required`);
   const [row] = rows;
-  if (row.published !== true || row.registryVerified !== true || row.outcome !== "published" || !/^[0-9a-f]{64}$/.test(row.sha256 ?? "")) throw new Error(`${unit.name}@${unit.version}: the publication receipt of upload run ${done.uploadRunId} records no verified publication (${row.outcome})`);
+  // The shared success definition (publication-outcomes.mjs, GB-45): `published` and the uploader's verified reconciliation of an earlier attempt's
+  // identical bytes (`published-by-earlier-attempt`) are both success; the registry readback below still has to serve the receipt's own hash.
+  const rowProblem = publicationRowProblem(row);
+  if (rowProblem) throw new Error(`${unit.name}@${unit.version}: the publication receipt of upload run ${done.uploadRunId} records no verified publication (${row.outcome}): ${rowProblem}`);
   // Read the registry back independently of the upload run: npm's dist.shasum (sha1) and the served tarball's sha256 (the receipt
   // row carries sha256 + sha1, not the sha512 integrity); crates: the sparse index cksum (sha256).
   const served = await registryBytes({ unit, registry, run, env, expected: row, scratch });
@@ -126,6 +242,7 @@ export async function releaseUnit({ unit, root, commit, executor, env, artifact,
     registry, runId: done.runId, runAttempt: done.runAttempt, requestId: done.requestId ?? null, uploadRunId: done.uploadRunId,
     hostedSha256: row.sha256, hostedSha1: row.sha1 ?? null, registryVerified: true,
     localArtifactSha256: artifact?.artifactSha256 ?? null, hostedEqualsLocal: artifact ? artifact.artifactSha256 === row.sha256 : null,
+    coordinator: installed,
   };
 }
 
@@ -217,7 +334,7 @@ export function knownRedEntry({ unit, root, platform, toRelease = false, readTex
  * ({ start(stage), end(stage) } returning true or false) is the door's ledger verify around each stage (7.08); `envExtra` carries the
  * Cargo output pin. Without `source` every behavior is the checkout route's, unchanged.
  */
-export async function runUnitGate({ selector, to, root, commonDir, commit, tree, executor, env, platform, check, source = null, stageGuard = null, envExtra = {}, loadOwner = () => import("./local-publish.mjs"), out = console.log, err = console.error, releaser = null, resolve = resolveUnit, writeReport, fetchReceipt = readBrokerReceipt, stageCommands = defaultStageCommands, readKnownRed }) {
+export async function runUnitGate({ selector, to, root, commonDir, commit, tree, executor, env, platform, check, source = null, stageGuard = null, envExtra = {}, loadOwner = () => import("./local-publish.mjs"), out = console.log, err = console.error, releaser = null, loadPipeline = loadInGatePipeline, resolve = resolveUnit, writeReport, fetchReceipt = readBrokerReceipt, stageCommands = defaultStageCommands, readKnownRed, verifyReceipts = verifyQualificationReceipts, selfGit = null }) {
   const stages = stagesTo(to);
   if (!stages) { err(`rightkit-gate: invalid unit stage ${to}`); return 2; }
   let unit;
@@ -229,7 +346,8 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
       if (red) { err(`rightkit-gate: BLOCKED: ${selector} is listed in ci/known-red.json for ${red.host} (${red.key}: ${red.reason}); a known-red unit is not compiled, packaged, qualified or published. Fix the defect and remove the entry first`); return 1; }
     } catch (error) { err(`rightkit-gate: BLOCKED: ${error.message}`); return 1; }
   }
-  const scratch = platform === "win32" ? "D:\\scratch" : "/Volumes/D/scratch";
+  // GB-29: a Linux origin has no managed volume; its scratch is the gate's own state directory (XDG state), never a Mac path.
+  const scratch = platform === "win32" ? "D:\\scratch" : platform === "linux" ? path.join(env.XDG_STATE_HOME || path.join(env.HOME || "/tmp", ".local", "state"), "rightkit", "scratch") : "/Volumes/D/scratch";
   const bundle = path.join(scratch, `rk-unit-${randomBytes(12).toString("hex")}`);
   const argv = ["--local", unit.kind === "npm" ? "--package" : "--crate", unit.name, "--workspace", root, "--qualify-only", "--bundle", bundle];
   const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
@@ -238,21 +356,44 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
   const report = { schema: "rightkit.unit-gate-report/1", unit, commit, tree, runtime, executor: executor.kind, stages: {} };
   const save = () => { if (writeReport) writeReport(report); };
   let state, owner, artifact, currentStage, checkTier = null;
-  // A run headed to release has its compile and package broker jobs sent with a nonce bound to this commit, tree, unit and stage
-  // (RIGHTKIT_ATTEST_NONCE), so each job's signed receipt can be verified hosted for exactly that and nothing else.
-  const attested = stages.includes("release") && executor?.kind === "broker";
+  // A broker-host run that reaches the qualify stage (--to qualify, or --to release) has its compile and package jobs attested: a pnpm job
+  // is sent the stage nonce, a carried Cargo call a nonce derived from it, both bound to this commit, tree, unit and stage, so each job's
+  // signed receipt can be verified hosted for exactly that and nothing else. `--to qualify` is the sanctioned no-upload route to that
+  // evidence: it writes the qualification and verifies it locally exactly as the hosted admission will, and stops there.
+  const attested = stages.includes("qualify") && executor?.kind === "broker";
+  // GB-29: a direct Linux origin has no broker to attest its stages; it records its own direct-origin evidence (direct-origin.mjs), verified locally as the hosted side will.
+  const directLinux = stages.includes("qualify") && executor?.kind === "direct" && platform === "linux";
+  const directStages = {};
+  const directQualification = () => {
+    const registry = unit.kind === "npm" ? "npm" : "crates";
+    const record = buildDirectOrigin({ repository: RIGHTKIT_REPOSITORY, commit, tree, unit, registry, platform, artifact: { artifactSha256: artifact.artifactSha256, contentSha256: artifact.contentSha256 }, stages: directStages });
+    verifyDirectOrigin(record, { repository: RIGHTKIT_REPOSITORY, commit, tree, unit, registry, ...(unit.kind === "npm" ? { contentSha256: artifact.contentSha256 } : { artifactSha256: artifact.artifactSha256 }) });
+    return writeQualification({ report, artifact, unit, commit, tree, runtime, executor, directOrigin: record });
+  };
   const stageEnv = async (stage, action) => {
     const run = startRun({ commonDir, commit, tree, stage });
-    const nonce = attested && ATTESTED_STAGES.includes(stage) ? { RIGHTKIT_ATTEST_NONCE: qualificationNonce({ commit, tree, unit: `${unit.kind}:${unit.name}`, stage }) } : {};
+    const nonce = attested && ATTESTED_STAGES.includes(stage) ? { [ATTEST_STAGE_NONCE_ENV]: qualificationNonce({ commit, tree, unit: `${unit.kind}:${unit.name}`, stage }) } : {};
     try { return await action({ ...env, ...envExtra, ...nonce, ...run.env }); } finally { endRun(run); }
   };
+  // The hosted admission's own verification of the qualification's receipts, run here against the commit before anything is dispatched
+  // (or, for --to qualify, before the run reports success): what it would refuse, this refuses first, naming why.
+  const gitAt = selfGit ?? ((...args) => {
+    const r = defaultRun("git", args, { cwd: source?.checkout ?? root });
+    if (r.error || r.status !== 0) throw new Error(`git ${args[0]} failed`);
+    return r.stdout;
+  });
+  const selfCheck = (file) => {
+    try { verifyReceipts(fs.readFileSync(file, "utf8"), { sha: commit, git: gitAt }); }
+    catch (error) { throw new Error(`the local check of the qualification's signed broker receipts failed; the hosted admission would refuse it, so nothing is dispatched: ${String(error.message).replace(/^publication admission refused: /, "")}`); }
+  };
   const receipts = {};
   const collectReceipts = (stage, ids) => {
     if (!attested || !ATTESTED_STAGES.includes(stage)) return;
     // Every job of the stage is fetched; the stage owes a signed receipt for EVERY command it runs (hosted admission requires the same),
     // so a missing one fails here, before any dispatch, naming it. Jobs that are none of the stage's commands are not carried.
     const fetched = [...new Set(ids ?? [])].map((id) => fetchReceipt(id));
-    const { assigned, missing } = assignJobs(stageCommands({ unit, root, platform })[stage], fetched.map((r) => ({ id: r.id, payload: r.provenance.payload })));
+    // A carried cargo command is bound to the directory of the primary checkout it ran in (source.checkout; stage-commands.mjs requestIs).
+    const { assigned, missing } = assignJobs(stageCommands({ unit, root, platform })[stage], fetched.map((r) => ({ id: r.id, payload: r.provenance.payload })), { checkout: source?.checkout ?? null });
     if (missing.length) throw new Error(`the ${stage} stage's ${describeCommand(missing[0])} has no broker job receipt (${missing.length} required command(s) missing)`);
     receipts[stage] = fetched.filter((r) => assigned.has(r.id));
   };
@@ -277,21 +418,50 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
         if (checkTier !== "release" && await check("release") !== 0) throw new Error("release-tier check failed");
         const qualified = await stageEnv(stage, (runEnv) => owner.qualifyLocalUnit(state, { env: runEnv }));
         verifyArtifact(qualified);
-        if (!qualified.qualifiedOnly || !qualified.evidencePath || qualified.artifactSha256 !== artifact.artifactSha256) throw new Error("qualification did not bind the packaged artifact");
+        if (!qualified.qualifiedOnly || !qualified.evidencePath || qualified.artifactSha256 !== artifact.artifactSha256 || qualified.contentSha256 !== artifact.contentSha256) throw new Error("qualification did not bind the packaged artifact");
         artifact = qualified;
       }
       let released = null;
       if (stage === "release") {
         // The qualification receipt the dispatcher carries to publish.yml: the hosted run is bound to these bytes and stages.
+        if (directLinux) {
+          // GB-29: the direct-origin qualification is written and verified exactly as the hosted side will. Dispatching it needs the publish workflow's `direct` admission input, which is the
+          // reserved publication authorization (GC-T22): nothing is dispatched from a direct host until that input exists.
+          const written = directQualification();
+          throw new Error(`RK_DIRECT_RELEASE_HELD: the direct-origin qualification ${written} was written and verified; the committed publish workflow admits \`broker\` only, and adding \`direct\` is the reserved publication authorization (GATE-CONTRACT GC-T22, GC-L01), so nothing was dispatched`);
+        }
         requireBrokerHost(executor); // a direct host has no broker receipts to carry: refuse for that reason, not for the missing receipts
         const qualification = writeQualification({ report, artifact, unit, commit, tree, runtime, executor });
-        released = await stageEnv(stage, (runEnv) => (releaser ?? releaseUnit)({ unit, root, commit, executor, env: runEnv, artifact, qualification, platform, out }));
+        selfCheck(qualification);
+        // GB-07: the default release runs the trusted installed coordinator IN this process (loadInGatePipeline: pinned to the gate's own installed bytes, never a file under the snapshot or the checkout);
+        // a coordinator that cannot be loaded starts nothing. An injected releaser (a test, or another route) owns its own coordinator.
+        released = await stageEnv(stage, async (runEnv) => (releaser ?? releaseUnit)({ unit, root, checkout: source?.checkout ?? root, commit, tree, executor, env: runEnv, artifact, qualification, platform, out,
+          ...(releaser ? {} : { pipeline: await loadPipeline({ root: source ? root : null, snapshotsRoot: managedSnapshotsRoot({ env: runEnv, platform }), pathApi: platform === "win32" ? path.win32 : path.posix }) }) }));
       }
       if (stageGuard && !(await stageGuard.end(stage))) throw new Error(`RK_CHECK_ERROR: the ${stage} stage's result covers no known bytes (a snapshot byte changed, or a write is outside the ledger)`);
-      report.stages[stage] = { ok: true, ...(stage === "package" || stage === "qualify" ? { artifactFile: artifact.artifactFile, artifactSha256: artifact.artifactSha256 } : {}), ...(receipts[stage] ? { receipts: receipts[stage] } : {}), ...(released ?? {}) };
+      if (directLinux && (stage === "compile" || stage === "package")) {
+        // The stage guard confirmed the snapshot was the commit's bytes at start and at exit; without one a direct origin has no such evidence and records none.
+        if (!stageGuard) throw new Error(`a direct Linux origin needs the snapshot stage guard to evidence the ${stage} stage (RK_DIRECT_ORIGIN_REFUSED)`);
+        let command = `${stage} ${unit.kind}:${unit.name}`;
+        try { command = (stageCommands({ unit, root, platform })[stage] ?? []).map(describeCommand).join("; ") || command; } catch { /* the stage name alone identifies the command */ }
+        directStages[stage] = directStageEvidence({ stage, commit, tree, command, ...(stage === "package" ? { outputSha256: artifact.artifactSha256 } : {}) });
+      }
+      report.stages[stage] = { ok: true, ...(stage === "package" || stage === "qualify" ? { artifactFile: artifact.artifactFile, artifactSha256: artifact.artifactSha256, ...(artifact.contentSha256 ? { contentSha256: artifact.contentSha256 } : {}) } : {}), ...(receipts[stage] ? { receipts: receipts[stage] } : {}), ...(released ?? {}) };
       save();
       out(`rightkit-gate: [${stage}] ${unit.kind}:${unit.name} passed`);
     }
+    if (directLinux && !stages.includes("release")) {
+      currentStage = "qualify";
+      const qualification = directQualification();
+      out(`rightkit-gate: [qualify] ${unit.kind}:${unit.name} direct-origin qualification ${qualification} verified locally; nothing was dispatched`);
+    }
+    if (attested && !stages.includes("release")) {
+      // --to qualify on a broker host: the qualification is written beside the artifact and verified as the hosted run will, and no upload exists.
+      currentStage = "qualify";
+      const qualification = writeQualification({ report, artifact, unit, commit, tree, runtime, executor });
+      selfCheck(qualification);
+      out(`rightkit-gate: [qualify] ${unit.kind}:${unit.name} qualification ${qualification} verified locally; nothing was dispatched`);
+    }
     return 0;
   } catch (error) {
     if (currentStage) { report.stages[currentStage] = { ok: false }; save(); }

package/web-build.mjs

@@ -75,8 +75,8 @@ export function runWebBuild(steps, { appRoot, env = process.env, dryRun = false,
     log(`${dryRun ? "[dry-run] " : ""}${[invocation.cmd, ...invocation.args].join(" ")}`);
     if (dryRun) continue;
     // A web build is a build: through the one door (build-launch.mjs), a broker job on a managed host.
-    const target = door(invocation.cmd, invocation.args, { env: invocation.env, cwd: invocation.cwd, exists: existsSync });
-    const result = spawnSyncFn(target.command, target.args, { cwd: invocation.cwd, env: invocation.env, stdio: "inherit" });
+    const target = door(invocation.cmd, invocation.args, { env: invocation.env, stepEnv: step.env, cwd: invocation.cwd, exists: existsSync });
+    const result = spawnSyncFn(target.command, target.args, { cwd: invocation.cwd, env: target.env ? { ...invocation.env, ...target.env } : invocation.env, stdio: "inherit" });
     if (result.error) throw result.error;
     if (result.status !== 0) return result.status ?? 1;
   }

package/win-package-recipe.mjs

@@ -19,6 +19,9 @@ import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
+import { buildLaunch, BUILD_LAUNCH_REFUSED } from "./build-launch.mjs";
+import { doorRefusal } from "./door.mjs";
+import { resolveCommand } from "./development.mjs";
 import { verifyNsisEmbeddedBinary } from "./nsis-payload.mjs";
 import { resolveArtifactPath, splitArtifactContext } from "./release-artifact-path.mjs";
 import { signingReceiptPath } from "./signing-receipts.mjs";
@@ -160,8 +163,23 @@ function sha256File(file, read) {
 export function defaultWinPackageDeps({ appRoot, target, env }) {
   const runSync = (command, args, options) => spawnSync(command, args, options);
   const spawn = (command, args, options) => {
-    const shell = process.platform === "win32" && !/\.(?:exe|com)$/i.test(command);
-    return runSync(command, args, { ...options, shell, stdio: "inherit" });
+    // `pnpm` and `node` start as argv arrays under this very node (resolveCommand: the pnpm CLI file, never the pnpm.cmd shim), with no shell: a
+    // shell would re-quote `tauri --config <json>` and let an argument inject (L8). Only a command resolved to something else keeps the old
+    // rule (a shell for anything that is not an .exe or .com on Windows).
+    const direct = command === "pnpm" || command === "node";
+    // GB-28 (BR11): a compile-capable step takes the one door (build-launch.mjs) first. On a broker-managed host that is a carried adapter job
+    // (or a refusal, before anything starts); on a direct host it is the plain command, resolved to its argv form below. Nothing here reaches
+    // the shared toolchain around the door.
+    let launch = { command, args };
+    if (direct) {
+      const stepEnv = options?.env ?? env;
+      let planned;
+      try { planned = buildLaunch(command, args, { env: stepEnv, cwd: options?.cwd ?? appRoot, exists: existsSync }); }
+      catch (error) { if (error?.code === BUILD_LAUNCH_REFUSED) return { error, status: null, signal: null, stdout: "", stderr: String(error.message) }; throw error; }
+      launch = planned.command === command ? { ...resolveCommand(command, args, { root: options?.cwd ?? appRoot, env: stepEnv }), ...(planned.env ? { env: planned.env } : {}) } : planned;
+    }
+    const shell = !direct && process.platform === "win32" && !/\.(?:exe|com)$/i.test(command);
+    return runSync(launch.command, launch.args, { ...options, ...(launch.env ? { env: { ...(options?.env ?? env), ...launch.env } } : {}), shell, windowsHide: true, stdio: "inherit" });
   };
   const receiptFor = (phase) => signingReceiptPath({ appRoot, target, platform: "win", phase, stateRoot: env.RIGHT_RELEASE_STATE_ROOT });
   return {
@@ -219,6 +237,12 @@ function locate(declared, { env, fs, split = false }) {
 export function runWinPackageRecipe({ appRoot, config = {}, target, deps = {} } = {}) {
   const plan = validateWinPackage({ appRoot, config, target });
   const env = deps.env ?? process.env;
+  // GB-28 (GATE one entry): this exported helper is not a door of its own. With its real effects (no injected spawn) it refuses, before any
+  // compile, unless a live door run launched it; a dry run and the fakes a test injects start nothing real.
+  if (!deps.spawn && deps.dryRun !== true) {
+    const refusal = (deps.doorRefusal ?? doorRefusal)({ cwd: plan.appRoot, env, command: "win-package-recipe" });
+    if (refusal) throw new WinPackageConfigError([refusal]);
+  }
   const base = defaultWinPackageDeps({ appRoot: plan.appRoot, target, env });
   const d = { ...base, ...deps, env, fs: { ...base.fs, ...(deps.fs ?? {}) } };
   const { fs } = d;