@rightkit/release 0.6.16 → 0.6.20

package/gate-stages.mjs

@@ -54,6 +54,8 @@ export const STAGE_SOURCES = Object.freeze({
   "unit:compile": { compiles: true, packages: false, source: "snapshot" },
   "unit:package": { compiles: true, packages: true, source: "snapshot" },
   "unit:qualify": { compiles: false, packages: false, source: "snapshot" },
+  // `--to tool --unit <selector>` (tool-build.mjs): builds one named tool binary from the commit's snapshot and enrols it; it packages and uploads nothing.
+  "unit:tool": { compiles: true, packages: false, source: "snapshot" },
   "unit:release": { compiles: false, packages: false, source: "publisher", basis: "a unit release is dispatched to the trusted publisher (releaseUnit); it compiles nothing here" },
 });
 
@@ -228,10 +230,39 @@ export function compileKeyOf(env = {}) {
   return sha256(JSON.stringify(picked));
 }
 
-/** What a passed compile stage records about its outputs: the directories, their census and the key of the compile environment. */
-export function compileOutputsRecord({ dirs = [], env = {}, census = outputCensus }) {
+/** The profile directory a gate compile writes (the dev profile; the install route reads its binaries there). */
+export const COMPILE_PROFILE_DIR = "debug";
+
+/** How `binaries` was chosen: only the bin targets the compile built in that directory (a consumer requires this marker). */
+export const BUILT_BINARIES_SCHEMA = "built-bin-targets/1";
+
+/**
+ * The sha256 of each binary this compile built (rustright#209 item 5): for every output directory, the files `<dir>/debug/<bin>[.exe]` of the
+ * bin targets the compile built there (`builtBins`, { [dir]: [bin target name] }: the units whose scans ran `cargo build -p <crate>` in that
+ * directory's workspace, so each binary was rebuilt or proven fresh by Cargo for this commit). Any other file in `debug/`, a stale binary of a
+ * removed or renamed target or of a package this run did not build, is never recorded. A census proves nothing once truncated (a broker
+ * workspace target is tens of GB, past OUTPUT_CENSUS_LIMIT); a consumer that installs a binary needs only that binary's bytes to be the compile's.
+ * A target whose file is missing is recorded with `sha256: null`. Sorted by directory, then name.
+ */
+export function compiledBinaries(builtBins = {}, { platform = process.platform, stat = (f) => fs.statSync(f), readFile = (f) => fs.readFileSync(f) } = {}) {
+  const out = [];
+  for (const dir of Object.keys(builtBins ?? {}).filter((d) => typeof d === "string" && d).sort()) {
+    for (const bin of [...new Set(builtBins[dir] ?? [])].sort()) {
+      const name = `${bin}${platform === "win32" ? ".exe" : ""}`;
+      const file = path.join(dir, COMPILE_PROFILE_DIR, name);
+      let info = null;
+      try { info = stat(file); } catch { info = null; }
+      out.push(info?.isFile?.() ? { dir, name, size: info.size, sha256: sha256(readFile(file)) } : { dir, name, size: null, sha256: null });
+    }
+  }
+  return out;
+}
+
+/** What a passed compile stage records about its outputs: the directories, their census, the built binaries' digests and the key of the compile environment. */
+export function compileOutputsRecord({ dirs = [], env = {}, builtBins = null, census = outputCensus, binaries = compiledBinaries }) {
   const c = census(dirs);
-  return { dirs: c.dirs, entries: c.entries, digest: c.digest, truncated: c.truncated, key: compileKeyOf(env) };
+  const known = builtBins && typeof builtBins === "object" ? Object.fromEntries(Object.entries(builtBins).filter(([dir]) => c.dirs.includes(dir))) : null;
+  return { dirs: c.dirs, entries: c.entries, digest: c.digest, truncated: c.truncated, ...(known ? { binaries: binaries(known), binariesOf: BUILT_BINARIES_SCHEMA } : {}), key: compileKeyOf(env) };
 }
 
 /**

package/gradle-lock.mjs

@@ -0,0 +1,206 @@
+// File-only Gradle dependency-locking check (class A scan `gradle-lock`). Gradle resolves dependencies at build time, so a build with no
+// committed lock can drift between hosts; with a lock, a stale one fails here instead of inside the compile. This module reads committed
+// files and executes nothing (no Gradle, no wrapper). It checks DIRECT dependencies only: each project directory that declares dependencies
+// must have its own gradle.lockfile (or legacy gradle/dependency-locks/*.lockfile), and every literal direct dependency (build.gradle[.kts]
+// strings and the libs.versions.toml entries the build references) must have a locked version at or above the declared one. Dynamic or
+// interpolated versions are checked for presence only; a declaration that cannot be read literally is a finding, never a silent pass.
+const NOT_SET_UP = "Gradle dependency locking is not set up: run ./gradlew dependencies --write-locks and commit gradle.lockfile";
+const join = (dir, f) => (dir === "" || dir === "." ? f : `${dir}/${f}`);
+const SKIP_DIRS = new Set([".git", ".gradle", "build", "node_modules", ".idea", "out", "target", ".build"]);
+const BUILD_FILE = /^build\.gradle(\.kts)?$/;
+export const GRADLE_BUILD_FILE = /(^|\/)(build|settings)\.gradle(\.kts)?$/;
+
+// ---- versions -------------------------------------------------------------------------------------------------------------
+const tokensOf = (v) => String(v).split(/[.\-_+]/).filter((t) => t !== "");
+const RELEASE_WORDS = new Set(["final", "ga", "release", "sp"]);
+/** Gradle-like version order (approximate): numeric segments by value, qualifiers below the plain release. */
+export function compareGradleVersions(a, b) {
+  const x = tokensOf(a); const y = tokensOf(b);
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const p = x[i]; const q = y[i];
+    if (p === undefined) return /^\d+$/.test(q) ? (Number(q) === 0 ? 0 : -1) : RELEASE_WORDS.has(q.toLowerCase()) ? 0 : 1;
+    if (q === undefined) return /^\d+$/.test(p) ? (Number(p) === 0 ? 0 : 1) : RELEASE_WORDS.has(p.toLowerCase()) ? 0 : -1;
+    const pn = /^\d+$/.test(p); const qn = /^\d+$/.test(q);
+    if (pn && qn) { if (Number(p) !== Number(q)) return Number(p) < Number(q) ? -1 : 1; continue; }
+    if (pn !== qn) return pn ? 1 : -1;
+    if (p.toLowerCase() !== q.toLowerCase()) return p.toLowerCase() < q.toLowerCase() ? -1 : 1;
+  }
+  return 0;
+}
+const isDynamic = (v) => v === null || v === undefined || /[+[\](),]|^latest\.|\$/.test(v);
+
+// ---- lockfiles ------------------------------------------------------------------------------------------------------------
+/** Map "group:artifact" -> Set of locked versions, from gradle.lockfile text (`g:a:v=config,config`; comments and `empty=` ignored). */
+export function parseLockfile(text, into = new Map()) {
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("empty=")) continue;
+    const m = /^([^:=\s]+):([^:=\s]+):([^=\s]+)=/.exec(line);
+    if (!m) continue;
+    const key = `${m[1]}:${m[2]}`;
+    if (!into.has(key)) into.set(key, new Set());
+    into.get(key).add(m[3]);
+  }
+  return into;
+}
+
+// ---- libs.versions.toml (the literal shapes Gradle documents; no TOML library needed) -------------------------------------
+function stripTomlComment(line) {
+  let inStr = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === '"' && line[i - 1] !== "\\") inStr = !inStr;
+    else if (c === "#" && !inStr) return line.slice(0, i);
+  }
+  return line;
+}
+const tomlStr = (s) => { const m = /^"((?:[^"\\]|\\.)*)"$/.exec(String(s).trim()); return m ? m[1] : null; };
+function inlineFields(body) {
+  // `key = "v"`, `key.ref = "v"`, `key = { ref = "v" }` inside one inline table (one level of nesting).
+  const out = {}; const re = /([A-Za-z_][\w.-]*)\s*=\s*("(?:[^"\\]|\\.)*"|\{[^}]*\})/g; let m;
+  while ((m = re.exec(body))) {
+    if (m[2].startsWith("{")) { for (const [k, v] of Object.entries(inlineFields(m[2].slice(1, -1)))) out[`${m[1]}.${k}`] = v; } else out[m[1]] = tomlStr(m[2]);
+  }
+  return out;
+}
+/** { versions, libraries: Map(alias -> { module, version, line }), bundles: Map(name -> [alias]), problems: [{ line, text }] } */
+export function parseCatalog(text) {
+  const versions = {}; const libraries = new Map(); const bundles = new Map(); const problems = []; const refs = [];
+  let section = null;
+  String(text).split(/\r?\n/).forEach((raw, i) => {
+    const line = stripTomlComment(raw).trim();
+    if (!line) return;
+    const sec = /^\[([\w.-]+)\]$/.exec(line);
+    if (sec) { section = sec[1]; return; }
+    const kv = /^([A-Za-z_][\w.-]*)\s*=\s*(.*)$/.exec(line);
+    if (!kv) return;
+    const [, key, value] = kv; const n = i + 1;
+    if (section === "versions") {
+      const s = tomlStr(value);
+      if (s !== null) versions[key] = s;
+      else if (value.startsWith("{")) { const f = inlineFields(value.slice(1, value.lastIndexOf("}"))); versions[key] = f.strictly ?? f.require ?? f.prefer ?? null; if (versions[key] === null) problems.push({ line: n, text: `version ${key} has no strictly/require/prefer literal` }); }
+      else problems.push({ line: n, text: `version ${key} is not a literal the checker reads` });
+    } else if (section === "libraries") {
+      const s = tomlStr(value);
+      if (s !== null) {
+        const p = s.split(":");
+        if (p.length >= 2 && p.length <= 3) libraries.set(key, { module: `${p[0]}:${p[1]}`, version: p[2] ?? null, line: n });
+        else problems.push({ line: n, text: `library ${key} is not group:artifact[:version]` });
+      } else if (value.startsWith("{")) {
+        const f = inlineFields(value.slice(1, value.lastIndexOf("}")));
+        const module = f.module ?? (f.group && f.name ? `${f.group}:${f.name}` : null);
+        if (!module) { problems.push({ line: n, text: `library ${key} has no module or group/name` }); return; }
+        const ref = f["version.ref"] ?? f["version.ref"] ?? null;
+        const direct = f.version ?? f["version.strictly"] ?? f["version.require"] ?? f["version.prefer"] ?? null;
+        const lib = { module, version: direct, line: n };
+        if (ref !== null) refs.push([lib, ref]);
+        libraries.set(key, lib);
+      } else problems.push({ line: n, text: `library ${key} is not a literal the checker reads` });
+    } else if (section === "bundles") {
+      const members = [...value.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+      bundles.set(key, members);
+    }
+  });
+  for (const [lib, ref] of refs) {
+    if (Object.hasOwn(versions, ref)) lib.version = versions[ref];
+    else problems.push({ line: lib.line, text: `library ${lib.module} references version ${ref}, which [versions] does not define` });
+  }
+  return { versions, libraries, bundles, problems };
+}
+const aliasKey = (a) => a.replace(/[-_.]/g, ".").toLowerCase();
+
+// ---- build files ----------------------------------------------------------------------------------------------------------
+const CONFIG = "(?:api|implementation|compileOnly|runtimeOnly|compile|runtime|annotationProcessor|kapt|ksp|coreLibraryDesugaring|lintChecks|lintPublish|[a-z][A-Za-z]*(?:Implementation|Api|CompileOnly|RuntimeOnly|AnnotationProcessor|Kapt|Ksp|Compile|Runtime))";
+const DEP_LINE = new RegExp(`^\\s*(${CONFIG})\\b\\s*\\(?\\s*(?:platform\\(\\s*|enforcedPlatform\\(\\s*)?(.*)$`);
+function stripGradleComments(text) {
+  return String(text).replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).split("\n").map((l) => l.replace(/(^|[^:"'\w])\/\/.*$/, "$1")).join("\n");
+}
+/** [{ line, config, kind: "gav"|"alias"|"bundle"|"unreadable", group, name, version, alias, text }] from a build.gradle[.kts]'s dependency lines. */
+export function parseBuildDependencies(source) {
+  const out = [];
+  stripGradleComments(source).split("\n").forEach((l, i) => {
+    const m = DEP_LINE.exec(l);
+    if (!m) return;
+    const line = i + 1; const config = m[1]; let rest = m[2].trim();
+    if (/^(project|files|fileTree|gradleApi|localGroovy|gradleKotlinDsl)\b/.test(rest) || rest.startsWith("{") || rest === "") return;
+    let r;
+    if ((r = /^["']([^"':\s]+):([^"':\s]+)(?::([^"':\s]*))?["']/.exec(rest))) { out.push({ line, config, kind: "gav", group: r[1], name: r[2], version: r[3] ?? null }); return; }
+    if ((r = /^group\s*[:=]\s*["']([^"']+)["']\s*,\s*name\s*[:=]\s*["']([^"']+)["'](?:\s*,\s*version\s*[:=]\s*["']([^"']+)["'])?/.exec(rest))) { out.push({ line, config, kind: "gav", group: r[1], name: r[2], version: r[3] ?? null }); return; }
+    if ((r = /^libs\.bundles\.([\w.]+?)(?:\.get\(\))?\s*\)*\s*$/.exec(rest))) { out.push({ line, config, kind: "bundle", alias: r[1] }); return; }
+    if ((r = /^libs\.((?!plugins\.|versions\.)[\w.]+?)(?:\.get\(\))?\s*\)*\s*$/.exec(rest))) { out.push({ line, config, kind: "alias", alias: r[1] }); return; }
+    if ((r = /^kotlin\(\s*["']([\w.-]+)["']/.exec(rest))) { out.push({ line, config, kind: "gav", group: "org.jetbrains.kotlin", name: `kotlin-${r[1]}`, version: null }); return; }
+    out.push({ line, config, kind: "unreadable", text: rest.slice(0, 70) });
+  });
+  return out;
+}
+
+/** null when `locked` (Set) holds the dependency at or above `version`; else why not. Dynamic versions need only presence. */
+function lockedProblem(locked, version) {
+  if (!locked || locked.size === 0) return "has no locked version";
+  if (isDynamic(version)) return null;
+  return [...locked].some((v) => compareGradleVersions(v, version) >= 0) ? null : `is locked at ${[...locked].join(", ")}, below the declared ${version}`;
+}
+
+/**
+ * Findings for the Gradle build rooted at `dir` ("." for the repository root). `read(file)` / `exists(file)` take repo-relative paths;
+ * `list(dir) -> [{ name, isDir }]` lists a directory.
+ */
+export function gradleLockProblems({ dir, read, exists, list }) {
+  const out = [];
+  const catalogFile = join(dir, "gradle/libs.versions.toml");
+  let catalog = null;
+  if (exists(catalogFile)) { catalog = parseCatalog(read(catalogFile)); out.push(...catalog.problems.map((p) => `${catalogFile}:${p.line}: ${p.text}`)); }
+  const builds = [];
+  const walk = (d, depth) => {
+    let entries = [];
+    try { entries = list(d); } catch { return; }
+    for (const e of entries) {
+      if (e.isDir) { if (depth < 6 && !SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) walk(join(d, e.name), depth + 1); } else if (BUILD_FILE.test(e.name)) builds.push(join(d, e.name));
+    }
+  };
+  walk(dir, 0);
+  for (const file of builds.sort()) {
+    const deps = parseBuildDependencies(read(file));
+    if (!deps.length) continue;
+    const projectDir = file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : ".";
+    const lockFile = join(projectDir, "gradle.lockfile");
+    const locks = new Map(); let any = false;
+    if (exists(lockFile)) { parseLockfile(read(lockFile), locks); any = true; }
+    const legacy = join(projectDir, "gradle/dependency-locks");
+    try { for (const e of list(legacy)) if (!e.isDir && e.name.endsWith(".lockfile")) { parseLockfile(read(`${legacy}/${e.name}`), locks); any = true; } } catch { /* no legacy lock directory */ }
+    if (!any) { out.push(`${file}: ${deps.length} declared ${deps.length === 1 ? "dependency" : "dependencies"} and no ${lockFile}: ${NOT_SET_UP}`); continue; }
+    const expand = [];
+    for (const d of deps) {
+      const at = `${file}:${d.line}`;
+      if (d.kind === "unreadable") { out.push(`${at}: ${d.config} dependency cannot be read literally (${d.text})`); continue; }
+      if (d.kind === "gav") {
+        if (/\$|\{/.test(d.group + d.name)) { out.push(`${at}: ${d.config} dependency group or name is interpolated, which cannot be read literally`); continue; }
+        expand.push({ at, module: `${d.group}:${d.name}`, version: d.version });
+        continue;
+      }
+      if (!catalog) { out.push(`${at}: ${d.config} uses libs.${d.alias} but ${catalogFile} does not exist`); continue; }
+      if (d.kind === "bundle") {
+        const key = [...catalog.bundles.keys()].find((k) => aliasKey(k) === aliasKey(d.alias));
+        if (!key) { out.push(`${at}: libs.bundles.${d.alias} is not in ${catalogFile} [bundles]`); continue; }
+        for (const a of catalog.bundles.get(key)) { const lib = catalog.libraries.get(a); if (lib) expand.push({ at, module: lib.module, version: lib.version, via: `libs.bundles.${d.alias}` }); else out.push(`${at}: bundle ${key} names ${a}, which [libraries] does not define`); }
+        continue;
+      }
+      const key = [...catalog.libraries.keys()].find((k) => aliasKey(k) === aliasKey(d.alias));
+      if (!key) { out.push(`${at}: libs.${d.alias} is not in ${catalogFile} [libraries]`); continue; }
+      const lib = catalog.libraries.get(key);
+      expand.push({ at, module: lib.module, version: lib.version, via: `libs.${d.alias}` });
+    }
+    for (const e of expand) {
+      const why = lockedProblem(locks.get(e.module), e.version);
+      if (why) out.push(`${e.at}: ${e.module}${e.version ? `:${e.version}` : ""}${e.via ? ` (${e.via})` : ""} ${why} in ${lockFile}`);
+    }
+  }
+  return out;
+}
+
+/** Repo-relative Gradle build root for a changed file: the nearest ancestor with settings.gradle[.kts], else the nearest with build.gradle[.kts]. */
+export function gradleOwnerOf(file, { exists, ancestorDirs }) {
+  const dirs = ancestorDirs(file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : ".").reverse();
+  const has = (d, names) => names.some((n) => exists(join(d, n)));
+  return dirs.find((d) => has(d, ["settings.gradle", "settings.gradle.kts"])) ?? dirs.find((d) => has(d, ["build.gradle", "build.gradle.kts"])) ?? null;
+}

package/heavy-command.mjs

@@ -221,12 +221,43 @@ function spawnOwnerWatcher(details) {
   watcher.unref();
 }
 
-export function summarizePreBrokerWaits({ heavySlot, suiteSlot, heavyOwnerInherited = false } = {}) {
+/**
+ * Whether `right-release build` takes the host-wide heavy-work slot for the whole run (rightkit#1367 step 2). On a broker host every compile, Swift and
+ * xcodebuild step, pnpm and node step goes through build-launch and becomes a broker job (Cargo, SwiftPM, native iOS alike), so the broker's scheduler and
+ * resource budget admit the work: no slot for the run and no memory or CPU wait. What the release runs itself, outside build-launch, is local work the broker
+ * never sees (`localSteps`: its own `pnpm install`); the caller takes the slot around just those steps. A direct host takes the slot for the whole run. A
+ * parent that already owns one (RIGHTSUITE_HEAVY_WORK_OWNER=1) is inherited, never taken twice.
+ * @returns {{ take: boolean, localSteps: boolean, inherited: boolean, skipReason: string | null }}
+ */
+export function heavySlotDecision({ env = process.env, brokerHost = false } = {}) {
+  if (env.RIGHTSUITE_HEAVY_WORK_OWNER === "1") return { take: false, localSteps: false, inherited: true, skipReason: null };
+  if (brokerHost) return { take: false, localSteps: true, inherited: false, skipReason: "broker host: build-launch makes the build steps broker jobs, which the broker's scheduler admits; the slot is held only around the release's own local steps" };
+  return { take: true, localSteps: false, inherited: false, skipReason: null };
+}
+
+/** The slot decision and the slot it asks for, in one step: what a release run takes before it starts. `acquire` is a seam for tests. */
+export function acquireRunHeavySlot({ env = process.env, brokerHost = false, acquire = acquireHeavyWorkSlot, ...options } = {}) {
+  const decision = heavySlotDecision({ env, brokerHost });
+  return { decision, slot: decision.take ? acquire(options) : null };
+}
+
+/**
+ * Runs the local step `run` holding the heavy-work slot when the decision says the run holds none but has local steps (a broker host: its own `pnpm install` is a process
+ * the broker never sees); otherwise `run` runs as it is (the run holds the slot, or inherits one). `onSlot(slot)` is told when the slot is taken and `onSlot(null)` when it ends.
+ */
+export async function withLocalHeavySlot(decision, run, { acquire = acquireHeavyWorkSlot, onSlot = () => {}, ...options } = {}) {
+  if (!decision?.localSteps) return run(null);
+  const slot = acquire(options);
+  onSlot(slot);
+  try { return await run(slot); } finally { slot.release(); onSlot(null); }
+}
+
+export function summarizePreBrokerWaits({ heavySlot, suiteSlot, heavyOwnerInherited = false, heavySkipped = null } = {}) {
   const heavy = heavySlot?.waits ?? null;
   const suite = suiteSlot?.waits ?? null;
   const layers = [
     heavy ? { layer: "heavy-work-slot", ms: (heavy.slotWaitMs ?? 0) + (heavy.resourceWaitMs ?? 0), slotWaitMs: heavy.slotWaitMs ?? 0, resourceWaitMs: heavy.resourceWaitMs ?? 0, blockers: heavy.slotBlockers ?? [], resourceBlockers: heavy.resourceBlockers ?? [] }
-      : { layer: "heavy-work-slot", ms: 0, skipped: heavyOwnerInherited ? "slot owned by parent heavy-command" : "not acquired" },
+      : { layer: "heavy-work-slot", ms: 0, skipped: heavyOwnerInherited ? "slot owned by parent heavy-command" : heavySkipped ?? "not acquired" },
     suite ? { layer: "suite-build-slot", ms: suite.waitMs ?? 0, blockers: suite.blockers ?? [] } : { layer: "suite-build-slot", ms: 0, skipped: "inactive (non-shared cache mode)" },
   ];
   const totalMs = layers.reduce((sum, layer) => sum + layer.ms, 0);

package/linux-artifacts.mjs

@@ -91,7 +91,8 @@ export function packLinuxArtifacts({ root, archive, app, version, commit, split,
   const names = archive.include.map((item) => path.basename(item));
   const dup = names.find((n, i) => names.indexOf(n) !== i);
   if (dup) throw new Error(`linux artifacts: two include entries share the base name ${dup}; the archive is flat`);
-  const tar = run("tar", ["-czf", target, ...archive.include.flatMap((item) => ["-C", path.join(root, path.dirname(item)), path.basename(item)])], { stdio: "inherit" });
+  // The archive is named relative to the working directory, and `-C` directories use forward slashes: a GNU tar (Git for Windows) reads `C:\\...` before the first colon as `host:path` and fails.
+  const tar = run("tar", ["-czf", file, ...archive.include.flatMap((item) => ["-C", path.resolve(root, path.dirname(item)).replaceAll("\\", "/"), path.basename(item)])], { cwd: outDir, stdio: "inherit" });
   if (tar.status !== 0) throw new Error(`linux artifacts: tar failed (${tar.status})`);
   const bytes = fs.readFileSync(target);
   const entry = { file, sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.length, glibc };

package/linux-setup.mjs

@@ -0,0 +1,106 @@
+// Idempotent Linux host provisioning for apps gated by `rightkit-gate` (rightkit#1365): reads the app's pins, installs Node
+// (official tarball into ~/.local), pnpm (corepack, else npm into ~/.local), Rust (rustup), then fills the pnpm store for every
+// committed lockroot with `pnpm fetch` against a throwaway virtual store, so an existing node_modules is never cleared.
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+
+const EXACT = /^\d+\.\d+\.\d+$/;
+
+export function readPins(root, read = (p) => (existsSync(p) ? readFileSync(p, "utf8") : null)) {
+  const pkgText = read(join(root, "package.json"));
+  const pkg = pkgText ? JSON.parse(pkgText) : {};
+  const nodeFile = read(join(root, ".node-version"))?.trim().replace(/^v/, "");
+  const node = nodeFile || String(pkg.engines?.node ?? "").trim() || null;
+  const pm = /^pnpm@(\d+\.\d+\.\d+)/.exec(pkg.packageManager ?? "");
+  const tomlText = read(join(root, "rust-toolchain.toml"));
+  const rust = tomlText ? (parseToml(tomlText).toolchain?.channel ?? null) : null;
+  return { node, pnpm: pm ? pm[1] : null, rust };
+}
+
+// "26.8.x" / "26.8" / "26" / "^26.8.0" / "26.8.1" -> newest matching release in the nodejs.org index (array of {version}).
+export function resolveNodeVersion(spec, index) {
+  if (!spec) return null;
+  const clean = spec.replace(/^[v^~=]+/, "").replace(/\.x\b/g, "").replace(/\.\*/g, "");
+  if (EXACT.test(clean)) return clean;
+  const m = /^(\d+)(?:\.(\d+))?/.exec(clean);
+  if (!m) throw new Error(`cannot resolve Node pin ${JSON.stringify(spec)}`);
+  const found = index.map((e) => e.version.replace(/^v/, "")).filter((v) => {
+    const [a, b] = v.split(".");
+    return a === m[1] && (m[2] === undefined || b === m[2]);
+  }).sort((x, y) => x.split(".").map(Number).reduce((d, n, i) => d || n - Number(y.split(".")[i]), 0) * -1);
+  if (!found.length) throw new Error(`no Node release matches ${JSON.stringify(spec)}`);
+  return found[0];
+}
+
+export function nodeArch(arch = process.arch) {
+  const a = { x64: "x64", arm64: "arm64", arm: "armv7l" }[arch];
+  if (!a) throw new Error(`unsupported CPU architecture ${arch}`);
+  return a;
+}
+
+export function findLockroots(root, readDir = (d) => readdirSync(d, { withFileTypes: true })) {
+  const out = [];
+  const walk = (dir) => {
+    const entries = readDir(dir);
+    if (entries.some((e) => e.isFile() && e.name === "pnpm-lock.yaml")) out.push(relative(root, dir) || ".");
+    for (const e of entries) {
+      if (e.isDirectory() && !["node_modules", ".git", "target"].includes(e.name) && !e.name.startsWith(".")) walk(join(dir, e.name));
+    }
+  };
+  walk(root);
+  return out.sort();
+}
+
+// run(cmd, args, opts) -> {status, stdout}; fetchText(url) -> string. Both injectable so the plan is testable offline.
+export function setup({ root, home = homedir(), arch = process.arch, run, fetchText, log = () => {}, env = process.env, dryRun = false } = {}) {
+  root = resolve(root);
+  const pins = readPins(root);
+  const bin = join(home, ".local", "bin");
+  const steps = [];
+  const sh = (cmd, args, opts = {}) => {
+    steps.push([cmd, ...args].join(" "));
+    if (dryRun) return { status: 0, stdout: "" };
+    const r = run(cmd, args, { cwd: root, ...opts, env: { ...env, ...opts.env, PATH: `${bin}:${join(home, ".cargo", "bin")}:${opts.env?.PATH ?? env.PATH ?? ""}` } });
+    if (r.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed (${r.status})`);
+    return r;
+  };
+  const probe = (cmd, args) => { try { return (run(cmd, args, { cwd: root, env: { ...env, PATH: `${bin}:${join(home, ".cargo", "bin")}:${env.PATH ?? ""}` } }).stdout ?? "").trim(); } catch { return ""; } };
+
+  if (pins.node) {
+    const exact = EXACT.test(pins.node.replace(/^v/, ""));
+    const version = dryRun && !exact ? null : resolveNodeVersion(pins.node, exact ? [] : JSON.parse(fetchText("https://nodejs.org/dist/index.json")));
+    if (dryRun && !version) steps.push(`(install Node ${pins.node})`);
+    if (version && probe("node", ["--version"]) !== `v${version}`) {
+      const name = `node-v${version}-linux-${nodeArch(arch)}`;
+      const dest = join(home, ".local");
+      log(`Node ${version}`);
+      sh("sh", ["-c", `set -e; mkdir -p "${dest}/lib" "${bin}"; cd "$(mktemp -d)"; curl -fsSLO https://nodejs.org/dist/v${version}/${name}.tar.xz; curl -fsSL https://nodejs.org/dist/v${version}/SHASUMS256.txt | grep " ${name}.tar.xz$" | sha256sum -c -; rm -rf "${dest}/lib/${name}"; tar -xJf ${name}.tar.xz -C "${dest}/lib"; for b in node npm npx corepack; do [ -e "${dest}/lib/${name}/bin/$b" ] && ln -sfn "${dest}/lib/${name}/bin/$b" "${bin}/$b"; done`]);
+    }
+  }
+  if (pins.pnpm && probe("pnpm", ["--version"]) !== pins.pnpm) {
+    log(`pnpm ${pins.pnpm}`);
+    if (dryRun || probe("corepack", ["--version"])) {
+      sh("corepack", ["enable", "--install-directory", bin]);
+      sh("corepack", ["prepare", `pnpm@${pins.pnpm}`, "--activate"]);
+    } else sh("npm", ["install", "-g", `pnpm@${pins.pnpm}`, "--prefix", join(home, ".local")]);
+  }
+  if (pins.rust) {
+    if (!probe("rustup", ["--version"])) {
+      log("rustup");
+      sh("sh", ["-c", "curl -fsSL https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain none --no-modify-path"]);
+    }
+    log(`Rust ${pins.rust}`);
+    sh("rustup", ["toolchain", "install", "--profile", "minimal"]); // reads rust-toolchain.toml from the app root
+  }
+  const lockroots = findLockroots(root);
+  for (const lr of lockroots) {
+    const dir = resolve(root, lr);
+    log(`pnpm store: ${lr}`);
+    // The throwaway virtual store keeps `pnpm fetch` from touching the root's node_modules.
+    const vstore = dryRun ? join(tmpdir(), "rk-vstore") : mkdtempSync(join(tmpdir(), "rk-vstore-"));
+    try { sh("pnpm", ["fetch", "--virtual-store-dir", vstore], { cwd: dir }); } finally { if (!dryRun) rmSync(vstore, { recursive: true, force: true }); }
+  }
+  return { pins, lockroots, steps };
+}

package/local-publish.mjs

@@ -35,9 +35,11 @@ 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";
 export const LOCAL_WIN32_HOST_POLICY_REASON = "Adrian 2026-10-14 local-build grant (.rightkit-local-build.json); published from the Windows host, the macOS run is not part of this receipt";
-// The hosts `--local` accepts and the host policy each records in the evidence.
-export const LOCAL_HOST_POLICIES = Object.freeze({ darwin: "darwin-only", win32: "win32-only" });
-const localHostPolicyReason = (platform) => (platform === "win32" ? LOCAL_WIN32_HOST_POLICY_REASON : LOCAL_HOST_POLICY_REASON);
+export const LOCAL_LINUX_HOST_POLICY_REASON = "GATE-CONTRACT Linux direct origin (GB-29, rightkit#1341): compiled and qualified locally with no broker; the macOS and Windows qualification is the publish run's own native verify jobs";
+// The hosts `--local` accepts and the host policy each records in the evidence. A Linux direct origin records "linux-direct": it is
+// not a single-host policy (isDarwinOnlyPolicy / isWin32OnlyPolicy stay false), so both native hosts are still required on CI.
+export const LOCAL_HOST_POLICIES = Object.freeze({ darwin: "darwin-only", win32: "win32-only", linux: "linux-direct" });
+const localHostPolicyReason = (platform) => (platform === "win32" ? LOCAL_WIN32_HOST_POLICY_REASON : platform === "linux" ? LOCAL_LINUX_HOST_POLICY_REASON : LOCAL_HOST_POLICY_REASON);
 const STEP_TIMEOUT_MS = 30 * 60 * 1000;
 
 export class LocalPublishError extends Error {
@@ -407,12 +409,15 @@ function testEnv(deps, isAssetGated) {
   return { ...inherited, RIGHTKIT_REQUIRE_ASSETS: isAssetGated ? "0" : "1", RIGHTKIT_ISOLATED_CHECKOUT: "1", CARGO_TERM_COLOR: "never" };
 }
 
-function assertLocalHost(deps, workspaceRoot, kind) {
+function assertLocalHost(deps, workspaceRoot, kind, { qualifyOnly = false, unit = null } = {}) {
   const platform = deps.platform ?? process.platform;
   if (!(deps.localBuildGranted ?? localBuildGranted)(workspaceRoot)) refuse(`--local needs the local-build grant: a committed ${LOCAL_BUILD_FILE} (allow "build-test-publish") naming this repository at ${workspaceRoot}`);
-  if (!Object.hasOwn(LOCAL_HOST_POLICIES, platform)) refuse(`--local publishes from the Mac only (host policy: darwin-only) or from Windows (host policy: win32-only); this host is ${platform}`);
-  // The npm path reads the registry token from the macOS Keychain and ships a Developer-ID-signed helper: Mac only.
-  if (kind === "npm" && platform !== "darwin") refuse(`publish npm --local needs the macOS Keychain npm token and runs on the Mac only; Windows publishes crates (publish cargo --local); this host is ${platform}`);
+  if (!Object.hasOwn(LOCAL_HOST_POLICIES, platform)) refuse(`--local runs on the Mac (host policy: darwin-only), Windows (host policy: win32-only) or a Linux direct origin (linux-direct); this host is ${platform}`);
+  // The npm upload reads the registry token from the macOS Keychain: Mac only.
+  // A Linux direct origin only qualifies (no token; the upload is publish.yml, GB-29), so it may qualify every npm package, @rightkit/release
+  // included: its Developer-ID-signed helper is built and signed hosted (publish.yml build-swap/sign-swap), never on the origin.
+  const linuxNpmQualify = platform === "linux" && qualifyOnly;
+  if (kind === "npm" && platform !== "darwin" && !linuxNpmQualify) refuse(`publish npm --local needs the macOS Keychain npm token and runs on the Mac only; Windows publishes crates (publish cargo --local); this host is ${platform}`);
   return platform;
 }
 
@@ -582,7 +587,8 @@ async function* publishUnitStages(parsed, deps, batch) {
 
 
   // 1. Preconditions, fail closed.
-  const platform = assertLocalHost(deps, workspaceRoot, kind);
+  const platform = assertLocalHost(deps, workspaceRoot, kind, { qualifyOnly: parsed.qualifyOnly, unit: parsed.unit });
+  if (platform === "linux" && !parsed.qualifyOnly) refuse("a Linux direct origin qualifies only (--qualify-only); the upload is publish.yml with admission=direct (GB-29, rightkit#1341)");
   if (parsed.qualifyOnly && fs.existsSync(parsed.bundleDir)) refuse(`qualification bundle already exists: ${parsed.bundleDir}`);
   const dir = kind === "npm" ? `packages/${unit.slice("@rightkit/".length)}` : `crates/${unit}`;
   const unitPath = path.join(workspaceRoot, dir);
@@ -691,7 +697,8 @@ async function* publishUnitStages(parsed, deps, batch) {
   const cleanup = () => fs.rmSync(scratch, { recursive: true, force: true });
   try {
     let artifactFile; const packCommands = [];
-    if (kind === "npm" && unit === SWAP_HELPER_PACKAGE) {
+    if (kind === "npm" && unit === SWAP_HELPER_PACKAGE && platform !== "linux") {
+      // A Linux direct origin skips this: it packs without the helper and the hosted sign-swap job binds the sealed one.
       // #258: the package ships a Developer-ID-signed bin/darwin/rightkit-swap; build, sign and verify it before packing (fails closed). The
       // helper and its signing receipt are written into the unit's own directory of the snapshot (packages/release/bin/darwin, both ignored by
       // packages/release/.gitignore): declared stage outputs of this stage, recorded by the gate's stage-output ledger (stage-ledger.mjs) like
@@ -782,7 +789,10 @@ async function* publishUnitStages(parsed, deps, batch) {
     fs.mkdirSync(path.dirname(evidencePath), { recursive: true });
     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, artifactBytes: fs.readFileSync(artifactFile) };
+    // The gate reads source identity through the same git the stages use (a unit snapshot has no .git; sourceGit answers for its commit).
+    // A Linux direct origin only ever qualifies (GB-29): its bundle proves the Linux run, and the upload's own native jobs prove Mac and Windows.
+    const gateOptions = { kind, name: unit, version, packagePath: unitPath, evidencePath, artifactBytes: fs.readFileSync(artifactFile),
+      ...(deps.git ? { git: deps.git } : {}), ...(platform === "linux" && parsed.qualifyOnly ? { directLinux: true } : {}) };
     (deps.enforceGate ?? enforcePublicationGate)(gateOptions, { write: (line) => log(line.replace(/\n$/, "")) });
 
     if (parsed.qualifyOnly) {
@@ -824,6 +834,7 @@ async function runLocalPublishBatch(parsed, deps) {
   const readJson = deps.readJson ?? defaultReadJson;
   const run = deps.run ?? defaultRunAsync;
   const platform = assertLocalHost(deps, workspaceRoot, "cargo");
+  if (platform === "linux") refuse("a Linux direct origin qualifies one unit at a time; batch publish runs on the Mac or Windows (GB-29, rightkit#1341)");
 
   // 1. The crate list and its dependency layers.
   const requested = parsed.batch.file ? parseCrateLayers((deps.readText ?? ((file) => fs.readFileSync(file, "utf8")))(parsed.batch.file)) : [parsed.batch.crates];

package/local-qualify.mjs

@@ -31,7 +31,8 @@ import zlib from "node:zlib";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { managedRuntimeClient, spawnCollect } from "./managed-cargo.mjs";
-import { planScans, runScans } from "./deterministic-scans.mjs";
+import { defaultSpawnAsync, planScans, runScans } from "./deterministic-scans.mjs";
+import { createBrokerLive } from "./broker-admission.mjs";
 import { pathDependencyDirs, readCargoPackage } from "./crate-graph.mjs";
 import { deriveCrateLayers } from "./local-publish.mjs";
 import { RUNTIME_BUDGET_CRATES } from "./runtime-budget-crates.mjs";
@@ -409,10 +410,15 @@ async function localScanRecord({ root, commit, crates, jobs, scratch, deps, log
     // Repository-level scans (workflows, YAML) plus every scan of the units, each in its own crate workspace (lock, deny, audit); other crates and npm packages stay out of scope.
     const files = tracked.filter((file) => (!file.startsWith("crates/") && !file.startsWith("packages/")) || unitDirs.some((dir) => file.startsWith(dir)));
     const crateFeatures = (deps.readJson ?? defaultReadJson)(path.join(repo, "ci", "gate.config.json"))?.rust ?? {};
-    const plan = (deps.planScans ?? planScans)({ changed: files, contentRoot: repo, liveRoot: root, includeTests: false, localCompile: true, cargoCommand: detectCargoCommand(deps), crateFeatures, readBytes: (file) => fs.readFileSync(file) });
+    const hostCommand = detectCargoCommand(deps);
+    const plan = (deps.planScans ?? planScans)({ changed: files, contentRoot: repo, liveRoot: root, includeTests: false, localCompile: true, cargoCommand: hostCommand, crateFeatures, readBytes: (file) => fs.readFileSync(file) });
     const observedTools = modules.observeToolVersions();
     log(`[local-qualify] scans: ${plan.scans.length} planned over ${files.length} files (class A, then class B through the broker)`);
-    const result = await (deps.runScans ?? runScans)(plan, { classes: ["A", "B"], jobs: Math.max(1, Number(jobs ?? 4) || 4), onResult: (row, progress) => log(`[local-qualify] scan [${progress.done}/${progress.total}] ${row.status.padEnd(7)} ${row.id}`) });
+    // detectCargoCommand above accepts only `rustright` or the managed shim on PATH, so this is always a broker host: the broker orders the carried class B scans (rightkit#1367 step 2).
+    // The client the live reader asks through: the managed runtime client, else the `rustright` the scans themselves run through.
+    const client = managedRuntimeClient(deps.env ?? process.env, deps.platform ?? process.platform) ?? (hostCommand[0] === "rustright" ? "rustright" : null);
+    const brokerLive = client ? createBrokerLive({ client, env: deps.env ?? process.env, spawn: defaultSpawnAsync, platform: deps.platform ?? process.platform }) : null;
+    const result = await (deps.runScans ?? runScans)(plan, { classes: ["A", "B"], jobs: Math.max(1, Number(jobs ?? 4) || 4), brokerHost: true, ...(brokerLive ? { brokerLive } : {}), onResult: (row, progress) => log(`[local-qualify] scan [${progress.done}/${progress.total}] ${row.status.padEnd(7)} ${row.id}`) });
     // Every unit is bound to its own crate workspace lock (#1285): crates/<x>/Cargo.lock, no root lock.
     const cargoLocks = Object.fromEntries([...crates].sort().map((name) => [name, { path: `crates/${name}/Cargo.lock`, sha256: sha256(fs.readFileSync(path.join(root, "crates", name, "Cargo.lock"))) }]));
     return modules.buildLocalScanRecord({ result, planned: plan.scans, sourceCommit: commit, headCommit: commit, cargoLocks, observedTools, units: crates, files: files.length });