@rightkit/release 0.6.12 → 0.6.14

package/broker-client.mjs

@@ -0,0 +1,106 @@
+// The one rule for starting the RustRight client (`rustright`), used by every gate and child spawn of it.
+//
+// On Windows the client is found on PATH as the managed agent shim, `rustright.cmd`. Node refuses to start a .cmd or .bat without
+// `shell: true` (the CVE-2024-27980 hardening: EINVAL), and a shell would re-quote the JSON arguments, which breaks the signed
+// argvSha256 or lets an argument inject. So on win32 the shim is never spawned: its target executable is read from the shim itself,
+// which must be EXACTLY the installed shape below, and that .exe is spawned directly with the argv array, `shell: false`, and the
+// environment the shim would have made (RUSTRIGHT_MANAGED_AGENT_SHIM and RIGHTKIT_MANAGED_AGENT_SHIM removed). A shim of any other
+// shape is refused with RK_BROKER_CLIENT_UNRESOLVED; there is no shell fallback. POSIX is unchanged: the client is spawned as given.
+import fs from "node:fs";
+import path from "node:path";
+import { managedRuntimeClient } from "./managed-roots.mjs";
+import { currentInterfaceEnv, legacyInterfaceNamesIn } from "./rustright-names.mjs";
+
+export const BROKER_CLIENT_UNRESOLVED = "RK_BROKER_CLIENT_UNRESOLVED";
+export const AGENT_SHIM_MARKER = "rustright.build-control.agent-shims.install.v1";
+/** The variables the shim clears before it starts the runtime. */
+export const AGENT_SHIM_ENV = Object.freeze(["RUSTRIGHT_MANAGED_AGENT_SHIM", "RIGHTKIT_MANAGED_AGENT_SHIM"]);
+
+export class BrokerClientError extends Error {
+  constructor(message) { super(message); this.name = "BrokerClientError"; this.code = BROKER_CLIENT_UNRESOLVED; }
+}
+
+const SHIM_EXE = /^[A-Za-z]:\\[^"%\r\n<>|&^!*?]+\.exe$/i;
+const SHIM_LINES = [
+  /^@echo off$/i,
+  new RegExp(`^rem ${AGENT_SHIM_MARKER.replaceAll(".", "\\.")}$`),
+  /^setlocal$/i,
+  /^set "RUSTRIGHT_MANAGED_AGENT_SHIM="$/i,
+  /^set "RIGHTKIT_MANAGED_AGENT_SHIM="$/i,
+  /^"([^"\r\n]+)" %\*$/,
+  /^exit \/b %ERRORLEVEL%$/i,
+];
+
+/** The shim's target executable from the shim's text, or a BrokerClientError. The shim must match the installed format exactly. */
+export function parseAgentShim(text, shimPath = "the shim") {
+  const lines = String(text).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  if (!lines.some((l) => l === `rem ${AGENT_SHIM_MARKER}`)) throw new BrokerClientError(`${shimPath} is not a RustRight agent shim (no ${AGENT_SHIM_MARKER} marker); it is not started through a shell`);
+  if (lines.length !== SHIM_LINES.length || !SHIM_LINES.every((re, i) => re.test(lines[i]))) throw new BrokerClientError(`${shimPath} has a shape other than the installed RustRight agent shim; it is not started through a shell`);
+  const exe = SHIM_LINES[5].exec(lines[5])[1];
+  if (!SHIM_EXE.test(exe)) throw new BrokerClientError(`${shimPath} names ${JSON.stringify(exe)}, which is not an absolute .exe path without shell metacharacters`);
+  return exe;
+}
+
+/**
+ * The client as it is spawned: `{ file, shim }`. POSIX, and any win32 client that is not a .cmd/.bat, is returned as given (`shim: false`).
+ * A win32 .cmd/.bat is resolved to the executable its shim names (`shim: true`), or refused.
+ */
+export function resolveBrokerClient(client, { platform = process.platform, readFile = (f) => fs.readFileSync(f, "utf8") } = {}) {
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(String(client))) return { file: client, shim: false };
+  let text;
+  try { text = readFile(client); } catch (e) { throw new BrokerClientError(`${client} cannot be read to find the RustRight client (${e.message})`); }
+  return { file: parseAgentShim(text, client), shim: true };
+}
+
+/** `env` without the shim's own variables (case-insensitive: Windows environments are). */
+export function withoutAgentShimEnv(env) {
+  const out = { ...env };
+  for (const key of Object.keys(out)) if (AGENT_SHIM_ENV.includes(key.toUpperCase())) delete out[key];
+  return out;
+}
+
+/**
+ * Spawn the client: `spawn(file, args, options)` with the resolved file. A shim target is started with `shell: false` and the shim's
+ * environment; anything else keeps the caller's options untouched. A refused client returns a spawn-shaped `{ error }` (code
+ * RK_BROKER_CLIENT_UNRESOLVED) and nothing is started.
+ */
+export function spawnBrokerClient(spawn, client, args, options = {}, { platform = process.platform, readFile } = {}) {
+  let resolved;
+  try { resolved = resolveBrokerClient(client, { platform, readFile }); } catch (error) { return { error, status: null, signal: null, stdout: "", stderr: "" }; }
+  // GB-09: every outbound client call carries the current RUSTRIGHT_* spelling of the interface names only (a legacy RIGHTKIT_* one is translated, never sent).
+  const baseEnv = options.env ?? process.env;
+  const env = legacyInterfaceNamesIn(baseEnv).length ? currentInterfaceEnv(baseEnv) : options.env;
+  if (!resolved.shim) return spawn(resolved.file, args, env === options.env ? options : { ...options, env });
+  return spawn(resolved.file, args, { ...options, shell: false, env: withoutAgentShimEnv(env ?? process.env) });
+}
+
+/**
+ * The client as PATH names it. POSIX: the bare name `rustright` (the shim is an executable file). win32: the first absolute path `where`
+ * lists for it (the managed `rustright.cmd` shim or an .exe), so resolveBrokerClient can read the shim; none found leaves the bare name,
+ * which the caller's spawn then fails on, as it did. `probe` is a synchronous spawn `(file, args, options)`; it is called on win32 only.
+ */
+export function locateBrokerClient({ platform = process.platform, env = process.env, probe, installed = managedRuntimeClient } = {}) {
+  if (platform !== "win32") return "rustright";
+  // GB-08 (BR11/B31): the installed runtime's own .exe is the client wherever it exists, so a PATH that exposes the `rustright.cmd` shim first
+  // (or a stale one) never decides what starts; PATH is consulted only when no installed runtime is found.
+  let runtime;
+  try { runtime = typeof installed === "function" ? installed(env, platform) : undefined; } catch { runtime = undefined; }
+  if (typeof runtime === "string" && /\.exe$/i.test(runtime) && path.win32.isAbsolute(runtime)) return runtime;
+  if (typeof probe !== "function") throw new BrokerClientError("locating the RustRight client on win32 needs a synchronous spawn (`probe`)");
+  const r = probe("where", ["rustright"], { encoding: "utf8", env, windowsHide: true, shell: false, timeout: 20_000 });
+  const found = String(r?.stdout ?? "").split(/\r?\n/).map((l) => l.trim()).filter((l) => path.win32.isAbsolute(l));
+  return found.find((l) => /\.(cmd|bat)$/i.test(l)) ?? found.find((l) => /\.exe$/i.test(l)) ?? "rustright";
+}
+
+/**
+ * `{ command, args, options }` to hand to ANY spawn (synchronous or not) for `command`: anything but the bare `rustright` is returned
+ * as given; `rustright` is located (locateBrokerClient) and resolved (resolveBrokerClient), so a win32 `.cmd` shim becomes its .exe
+ * target with `shell: false` and the shim's environment. Throws BrokerClientError for a shim that is not the installed shape.
+ */
+export function brokerClientInvocation(command, args, options = {}, { platform = process.platform, probe, readFile, installed } = {}) {
+  if (command !== "rustright") return { command, args, options };
+  const client = locateBrokerClient({ platform, env: options.env, probe, ...(installed ? { installed } : {}) });
+  const resolved = resolveBrokerClient(client, { platform, readFile });
+  if (!resolved.shim) return { command: resolved.file, args, options };
+  return { command: resolved.file, args, options: { ...options, shell: false, env: withoutAgentShimEnv(options.env ?? process.env) } };
+}

package/broker-exception.mjs

@@ -0,0 +1,211 @@
+// The records Adrian's decisions live in, read by the gate from the COMMIT being built (never the working tree), and the repository rules
+// they serve. Three records, one identity test:
+//
+//  1. .rightkit/broker-exceptions.json (Adrian, 2026-10-31): the one documented exception to "the broker is mandatory on Mac and Dell": a
+//     build through the gate WITHOUT the broker, only when Adrian expressly asked or approved it, recorded in the repository being built.
+//     The gate refuses unless the id exists, is unexpired when it carries a date, names this host and, in RightKit, covers every selected unit.
+//
+//       { schema: 1, exceptions: [ { id, approvedBy: "Adrian", quote, issue, units?, hosts, expires? } ] }
+//       units: "rust:<crate>" | "npm:<package>" | "*" (all units; only when his words say all). hosts: "mac" | "dell".
+//       RightKit only: `units` names what the exception covers; a run with no unit selector (a whole door run) selects every unit, so only a
+//       record whose units are ["*"] covers it. Every other repository is built whole (one fixed build definition, below): a broker exception
+//       there needs no `units` and covers the repository's run (#1325, Adrian: "the only exception is RightKit, where the unit has to be mentioned").
+//       expires (optional): ISO date. Absent = no date: the exception lasts for what he asked for (Adrian, 2026-10-31: "exception lasts for what i
+//       asked for, till the time it's published"), which `hosts`, `units` (RightKit) and his quote bound. Present = validated and enforced as ever.
+//
+//  2. ci/all-units-exceptions.json (RightKit only, #1325): "all units" in RightKit is Adrian's exception, never a default. RightKit's door names
+//     its unit on every run: one `--unit`, a unit list written for that run (`--units-file`), or every unit with `--all-units-exception <id>`.
+//
+//       { exceptions: [ { id, approvedBy: "Adrian", quote, issue, expires? } ] }   (the file CI's dispatch reads, minus its mandatory expiry)
+//
+//  3. ci/gate.config.json `cargoWorkspaces` (every repository but RightKit, #1325): the fixed, committed build definition. It lists every Cargo
+//     workspace of the repository; a gate run builds all of them and nothing is chosen per run. The gate refuses a commit with no list (and prints
+//     the exact list it discovered, to commit), and a commit whose discovered workspaces (discoverRustWorkspaces) differ from the list, missing or
+//     extra. No grace period and no generated list.
+//
+//       ci/gate.config.json = { ..., "cargoWorkspaces": [ "<workspace directory, '.' for the root>", ... ] }   (the lock of each is <directory>/Cargo.lock)
+//
+// RightKit is told apart by the repository identity `check` already uses for RightKit's own rules: the commit holds
+// packages/release/package.json named @rightkit/release (isRightKitIdentity). Never a path guess.
+export const BROKER_EXCEPTIONS_FILE = ".rightkit/broker-exceptions.json";
+export const BROKER_EXCEPTION_SCHEMA = 1;
+export const OUTSIDE_BROKER_NOTE = "outside the broker by exception";
+export const ALL_UNITS_EXCEPTIONS_FILE = "ci/all-units-exceptions.json";
+export const CARGO_WORKSPACE_LIST_FILE = "ci/gate.config.json";
+export const CARGO_WORKSPACE_LIST_KEY = "cargoWorkspaces";
+export const RIGHTKIT_IDENTITY_FILE = "packages/release/package.json";
+export const RIGHTKIT_IDENTITY_NAME = "@rightkit/release";
+
+export const BROKER_EXCEPTION_ERRORS = Object.freeze({
+  usage: "RK_BROKER_EXCEPTION_USAGE",
+  missing: "RK_BROKER_EXCEPTION_MISSING",
+  invalid: "RK_BROKER_EXCEPTION_INVALID",
+  expired: "RK_BROKER_EXCEPTION_EXPIRED",
+  host: "RK_BROKER_EXCEPTION_HOST",
+  unit: "RK_BROKER_EXCEPTION_UNIT",
+});
+
+export const ALL_UNITS_ERRORS = Object.freeze({
+  usage: "RK_ALL_UNITS_USAGE",
+  missing: "RK_ALL_UNITS_MISSING",
+  invalid: "RK_ALL_UNITS_INVALID",
+  expired: "RK_ALL_UNITS_EXPIRED",
+});
+
+export const CARGO_WORKSPACE_LIST_ERRORS = Object.freeze({
+  missing: "RK_CARGO_WORKSPACE_LIST_MISSING",
+  invalid: "RK_CARGO_WORKSPACE_LIST_INVALID",
+  differs: "RK_CARGO_WORKSPACE_LIST_DIFFERS",
+});
+
+const HOSTS = Object.freeze(["mac", "dell"]);
+const UNIT = /^(?:\*|rust:[A-Za-z0-9][A-Za-z0-9_-]*|npm:(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*)$/;
+const DATE = /^\d{4}-\d{2}-\d{2}(?:T[0-9:.]+(?:Z|[+-]\d{2}:\d{2}))?$/;
+
+const refuse = (code, message) => Object.assign(new Error(`${code}: ${message}`), { code });
+
+/** True when `packageJsonText` is the package.json of RightKit's own release package: the identity of the RightKit repository. */
+export function isRightKitIdentity(packageJsonText) {
+  try { return JSON.parse(String(packageJsonText))?.name === RIGHTKIT_IDENTITY_NAME; } catch { return false; }
+}
+
+/** The exception host name for a Node platform: Mac and Dell (Windows) only; every other host is not an exception host. */
+export function exceptionHostOf(platform = process.platform) {
+  return platform === "darwin" ? "mac" : platform === "win32" ? "dell" : null;
+}
+
+/** `cargo:rightkit-x` / `npm:@rightkit/x` selectors of `--unit` as record unit names; null for no selector (whole run). */
+export function unitsOfSelector(selector) {
+  if (selector === undefined || selector === null) return ["*"];
+  const cargo = /^cargo:(rightkit-[a-z0-9-]+)$/.exec(selector);
+  if (cargo) return [`rust:${cargo[1]}`];
+  if (/^npm:@rightkit\/[a-z0-9-]+$/.test(selector)) return [selector];
+  return [String(selector)];
+}
+
+function expiryOf(value) {
+  const at = Date.parse(/T/.test(value) ? value : `${value}T23:59:59.999Z`);
+  return Number.isNaN(at) ? null : at;
+}
+
+/** What every record entry states: an id, Adrian's approval, his words and the issue that records the decision. Null when it does. */
+function statedProblem(entry, { issueIsUrl }) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return "not an object";
+  if (typeof entry.id !== "string" || !entry.id) return "id is required";
+  if (entry.approvedBy !== "Adrian") return 'approvedBy must be "Adrian"';
+  if (typeof entry.quote !== "string" || !entry.quote.trim()) return "quote (his exact words) is required";
+  if (issueIsUrl ? typeof entry.issue !== "string" || !/^https:\/\/\S+$/.test(entry.issue) : typeof entry.issue !== "string" || !entry.issue.trim()) return issueIsUrl ? "issue must be an https URL" : "issue is required";
+  return null;
+}
+
+/** `expires` is optional: absent means no date. Anything present must be an ISO date (null, "" and a malformed value are refused, never read as absent). */
+const expiryProblem = (entry) => (Object.hasOwn(entry, "expires") && (typeof entry.expires !== "string" || !DATE.test(entry.expires) || expiryOf(entry.expires) === null) ? "expires, when present, must be an ISO date" : null);
+
+function checkEntry(entry, { inRightKit }) {
+  const bad = (what) => refuse(BROKER_EXCEPTION_ERRORS.invalid, `exception ${JSON.stringify(entry?.id)} in ${BROKER_EXCEPTIONS_FILE}: ${what}`);
+  const stated = statedProblem(entry, { issueIsUrl: true });
+  if (stated) throw bad(stated);
+  // `units` bounds an exception in RightKit only. Elsewhere it is optional (a repository is built whole) and, when a record states it, is still
+  // read as a unit list so a typo is not silently accepted; it never narrows what a repository's run is covered for.
+  if ((inRightKit || Object.hasOwn(entry, "units")) && (!Array.isArray(entry.units) || !entry.units.length || !entry.units.every((u) => typeof u === "string" && UNIT.test(u)))) throw bad('units must be a non-empty list of "rust:<crate>", "npm:<package>" or "*"');
+  if (!Array.isArray(entry.hosts) || !entry.hosts.length || !entry.hosts.every((h) => HOSTS.includes(h))) throw bad(`hosts must be a non-empty list of ${HOSTS.join(", ")}`);
+  const dated = expiryProblem(entry);
+  if (dated) throw bad(dated);
+  return entry;
+}
+
+/**
+ * Judge `--no-broker <id>`. `record` is the text of the committed record (null when the commit holds none). `inRightKit` is the repository
+ * identity of the commit (isRightKitIdentity; true unless the caller says otherwise, the stricter reading). Returns the exception (frozen, with
+ * the host and the units this run selected) or throws an error carrying a typed `code`.
+ */
+export function authorizeNoBroker({ id, record, platform = process.platform, units = ["*"], now = Date.now(), inRightKit = true }) {
+  if (typeof id !== "string" || !id || id.startsWith("--")) throw refuse(BROKER_EXCEPTION_ERRORS.usage, "--no-broker needs the exception id");
+  if (record === null || record === undefined) throw refuse(BROKER_EXCEPTION_ERRORS.missing, `the selected commit holds no ${BROKER_EXCEPTIONS_FILE}; the broker stays mandatory`);
+  let parsed;
+  try { parsed = JSON.parse(record); } catch (error) { throw refuse(BROKER_EXCEPTION_ERRORS.invalid, `${BROKER_EXCEPTIONS_FILE} is not JSON: ${error.message}`); }
+  if (parsed?.schema !== BROKER_EXCEPTION_SCHEMA || !Array.isArray(parsed.exceptions)) throw refuse(BROKER_EXCEPTION_ERRORS.invalid, `${BROKER_EXCEPTIONS_FILE} must be { schema: ${BROKER_EXCEPTION_SCHEMA}, exceptions: [...] }`);
+  const matches = parsed.exceptions.filter((e) => e?.id === id);
+  if (!matches.length) throw refuse(BROKER_EXCEPTION_ERRORS.missing, `${BROKER_EXCEPTIONS_FILE} has no exception ${JSON.stringify(id)}; the broker stays mandatory`);
+  if (matches.length > 1) throw refuse(BROKER_EXCEPTION_ERRORS.invalid, `exception id ${JSON.stringify(id)} appears more than once in ${BROKER_EXCEPTIONS_FILE}`);
+  const entry = checkEntry(matches[0], { inRightKit });
+  if (entry.expires !== undefined && now > expiryOf(entry.expires)) throw refuse(BROKER_EXCEPTION_ERRORS.expired, `exception ${id} expired ${entry.expires}`);
+  const host = exceptionHostOf(platform);
+  if (!host || !entry.hosts.includes(host)) throw refuse(BROKER_EXCEPTION_ERRORS.host, `exception ${id} names ${entry.hosts.join(", ")}; this host is ${host ?? platform}`);
+  if (inRightKit && !entry.units.includes("*")) {
+    const uncovered = units.filter((u) => !entry.units.includes(u));
+    if (uncovered.length) throw refuse(BROKER_EXCEPTION_ERRORS.unit, `exception ${id} covers ${entry.units.join(", ")}; not ${uncovered.join(", ")}${units.includes("*") ? " (a run with no --unit selects every unit and needs units [\"*\"])" : ""}`);
+  }
+  // Outside RightKit the run is the whole repository, whatever units the record happens to list.
+  const covered = inRightKit ? [...entry.units] : ["*"];
+  return Object.freeze({ exceptionId: entry.id, quote: entry.quote, issue: entry.issue, units: covered, selectedUnits: [...units], host, expires: entry.expires ?? null, inRightKit, note: OUTSIDE_BROKER_NOTE });
+}
+
+/** The line a run under an exception prints (and the receipt records the same fields). */
+export function describeBrokerException(x) {
+  return `exceptionId=${x.exceptionId} host=${x.host} units=${x.units.join(",")} issue=${x.issue} quote=${JSON.stringify(x.quote)}: ${x.note}`;
+}
+
+/**
+ * Judge `--all-units-exception <id>`: RightKit's whole-repository door run, which is Adrian's exception and never a default. `record` is the
+ * text of the commit's ci/all-units-exceptions.json (null when it holds none). Same fields as CI's dispatch reads (id, approvedBy "Adrian", quote,
+ * issue); `expires` is optional and honoured when present. Returns the exception (frozen) or throws an error carrying a typed `code`.
+ */
+export function authorizeAllUnits({ id, record, now = Date.now() }) {
+  if (typeof id !== "string" || !id || id.startsWith("--")) throw refuse(ALL_UNITS_ERRORS.usage, "--all-units-exception needs the exception id");
+  if (record === null || record === undefined) throw refuse(ALL_UNITS_ERRORS.missing, `the selected commit holds no ${ALL_UNITS_EXCEPTIONS_FILE}; an all-units run is Adrian's exception`);
+  let parsed;
+  try { parsed = JSON.parse(record); } catch (error) { throw refuse(ALL_UNITS_ERRORS.invalid, `${ALL_UNITS_EXCEPTIONS_FILE} is not JSON: ${error.message}`); }
+  if (!Array.isArray(parsed?.exceptions)) throw refuse(ALL_UNITS_ERRORS.invalid, `${ALL_UNITS_EXCEPTIONS_FILE} must be { exceptions: [...] }`);
+  const matches = parsed.exceptions.filter((e) => e?.id === id);
+  if (!matches.length) throw refuse(ALL_UNITS_ERRORS.missing, `${ALL_UNITS_EXCEPTIONS_FILE} has no exception ${JSON.stringify(id)}; an all-units run is Adrian's exception`);
+  if (matches.length > 1) throw refuse(ALL_UNITS_ERRORS.invalid, `exception id ${JSON.stringify(id)} appears more than once in ${ALL_UNITS_EXCEPTIONS_FILE}`);
+  const entry = matches[0];
+  const problem = statedProblem(entry, { issueIsUrl: false }) ?? expiryProblem(entry);
+  if (problem) throw refuse(ALL_UNITS_ERRORS.invalid, `exception ${JSON.stringify(id)} in ${ALL_UNITS_EXCEPTIONS_FILE}: ${problem}`);
+  if (entry.expires !== undefined && now > expiryOf(entry.expires)) throw refuse(ALL_UNITS_ERRORS.expired, `exception ${id} expired ${entry.expires}`);
+  return Object.freeze({ exceptionId: entry.id, quote: entry.quote, issue: entry.issue, expires: entry.expires ?? null });
+}
+
+/** The line an all-units run prints. */
+export function describeAllUnitsException(x) {
+  return `exceptionId=${x.exceptionId} issue=${x.issue} quote=${JSON.stringify(x.quote)}: every unit of RightKit, by exception`;
+}
+
+/** A directory the build definition may name: `.` or a plain repository-relative path (no empty, `.` or `..` segment, no backslash, drive or NUL). */
+const plainWorkspaceDir = (d) => typeof d === "string" && d.length > 0 && (d === "." || d.split("/").every((seg) => seg !== "" && seg !== "." && seg !== ".." && !/[\\:\0]/.test(seg)));
+
+/**
+ * The fixed build definition of a repository that is not RightKit: compare the Cargo workspaces the commit holds (`discovered`, the
+ * `cargoDir` of each discoverRustWorkspaces workspace) with the committed list: the `cargoWorkspaces` array of the commit's ci/gate.config.json
+ * (`record` is that file's text, null when the commit holds none). Equal sets pass; a repository with no Cargo workspace needs no list. A
+ * commit with workspaces and no list throws, and the message carries the exact list the gate discovered, ready to commit (no grace period, no
+ * generated file). A list that differs throws too, naming what is missing from it and what it names that the commit does not hold, and the
+ * list that would agree. Returns { workspaces, listed } (frozen).
+ */
+export function checkCargoWorkspaceList({ discovered, record }) {
+  const found = [...new Set(discovered)].sort();
+  const snippet = `"${CARGO_WORKSPACE_LIST_KEY}": ${JSON.stringify(found)}`;
+  let parsed; let unreadable = "";
+  if (record !== null && record !== undefined) {
+    try { parsed = JSON.parse(record); } catch (error) { unreadable = ` (${CARGO_WORKSPACE_LIST_FILE} is not valid JSON: ${error.message})`; }
+  }
+  if (parsed === undefined || parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || !Object.hasOwn(parsed, CARGO_WORKSPACE_LIST_KEY)) {
+    if (!found.length) return Object.freeze({ workspaces: [], listed: false });
+    throw refuse(CARGO_WORKSPACE_LIST_ERRORS.missing, `the commit holds ${found.length} Cargo workspace(s) and ${CARGO_WORKSPACE_LIST_FILE} names none${unreadable}; every repository but RightKit commits one fixed build definition listing every Cargo workspace, and a run builds all of them. The gate discovered exactly these; commit them in ${CARGO_WORKSPACE_LIST_FILE}: ${snippet}`);
+  }
+  const listed = parsed[CARGO_WORKSPACE_LIST_KEY];
+  if (!Array.isArray(listed) || !listed.every(plainWorkspaceDir)) throw refuse(CARGO_WORKSPACE_LIST_ERRORS.invalid, `${CARGO_WORKSPACE_LIST_FILE} ${CARGO_WORKSPACE_LIST_KEY} must be an array of workspace directories ("." for the root, otherwise a plain repository-relative path), e.g. ${snippet}`);
+  const sorted = [...listed].sort();
+  const duplicate = sorted.find((d, i) => i > 0 && d === sorted[i - 1]);
+  if (duplicate !== undefined) throw refuse(CARGO_WORKSPACE_LIST_ERRORS.invalid, `${CARGO_WORKSPACE_LIST_FILE} ${CARGO_WORKSPACE_LIST_KEY} names the workspace ${JSON.stringify(duplicate)} more than once`);
+  const unlisted = found.filter((d) => !sorted.includes(d));
+  const absent = sorted.filter((d) => !found.includes(d));
+  if (unlisted.length || absent.length) {
+    const parts = [];
+    if (unlisted.length) parts.push(`the commit holds ${unlisted.join(", ")} which the list does not name`);
+    if (absent.length) parts.push(`the list names ${absent.join(", ")} which the commit does not hold`);
+    throw refuse(CARGO_WORKSPACE_LIST_ERRORS.differs, `${CARGO_WORKSPACE_LIST_FILE} ${CARGO_WORKSPACE_LIST_KEY} and the commit's Cargo workspaces differ: ${parts.join("; ")}; the build definition and the repository must agree before anything runs. The list that agrees: ${snippet}`);
+  }
+  return Object.freeze({ workspaces: sorted, listed: true });
+}

package/broker-handshake.mjs

@@ -0,0 +1,160 @@
+// GB-51 / GB-62 (BROKER-CONTRACT section 16, "HANDSHAKE.capabilities"): the gate receives the broker's HANDSHAKE itself and reads the capability list from it.
+//
+// `rustright doctor --json` reports the same list (`.broker.capabilities`), but through the client; a gate that plans a native tool or `cargo ndk` from a list it was handed second-hand has
+// not seen what the broker advertised. This module speaks the one request the client's own health probe sends (`STATUS runtime-health-probe`, a by-id request the front gate answers with
+// the HANDSHAKE as its FIRST event whatever else it says, GB-75), reads that first event, and parses it strictly. The runtime identity the request carries is the manifest beside the
+// installed client (`runtime-manifest.json`, the file the client itself reads); the endpoint is the one RustRight's discovery names (managed-roots.mjs discoverBrokerSocket: the
+// explicit variable, the config's pipe on Windows, `broker.sock` of a managed control root elsewhere). A list is advertised only by a handshake that was received, and the gate plans only
+// against the names it carries: capability names are compared exactly, never by prefix or case.
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { resolveBrokerClient } from "./broker-client.mjs";
+import { discoverBrokerSocket } from "./managed-roots.mjs";
+
+/** `rustright_protocol::BUILD_CONTROL_PROTOCOL`: carried in every request envelope. */
+export const BUILD_CONTROL_PROTOCOL = "rustright.build-control.client.v2";
+/** The id of the client's own health probe (`rustright-cli` doctor: PROBE_ID); a by-id request, so it is not held to the exact runtime digest. */
+export const HANDSHAKE_PROBE_ID = "runtime-health-probe";
+export const RUNTIME_MANIFEST_FILE = "runtime-manifest.json";
+export const RUNTIME_MANIFEST_SCHEMA = "rustright.build-control.runtime.v2";
+const LEGACY_RUNTIME_MANIFEST_SCHEMA = "rightkit.build-control.runtime.v2";
+/** A client accepts at most 1 MiB per line (rustright-protocol MAX_BROKER_LINE_BYTES). */
+export const MAX_HANDSHAKE_LINE_BYTES = 1 << 20;
+export const HANDSHAKE_TIMEOUT_MS = 20_000;
+
+const isDigest = (v) => typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** The runtime identity of a parsed object (`schema` current or legacy, a version, both digests lowercase 64-hex), as RustRight's `RuntimeIdentity::new` validates it. */
+function normalizeIdentity(raw) {
+  if (!isObject(raw) || ![RUNTIME_MANIFEST_SCHEMA, LEGACY_RUNTIME_MANIFEST_SCHEMA].includes(raw.schema) || typeof raw.version !== "string" || raw.version === "" || !isDigest(raw.clientDigest) || !isDigest(raw.brokerDigest)) return null;
+  return { schema: RUNTIME_MANIFEST_SCHEMA, version: raw.version, clientDigest: raw.clientDigest, brokerDigest: raw.brokerDigest };
+}
+
+/** The runtime identity a `runtime-manifest.json` text holds: `{ ok: true, identity }` or `{ ok: false, problem }`. */
+export function parseRuntimeIdentity(text) {
+  let doc;
+  try { doc = JSON.parse(text); } catch { return { ok: false, problem: "the runtime manifest is not JSON" }; }
+  const identity = normalizeIdentity(doc);
+  return identity ? { ok: true, identity } : { ok: false, problem: "the runtime manifest is not a runtime identity (schema, version, clientDigest and brokerDigest are required)" };
+}
+
+/**
+ * The broker's HANDSHAKE event (a line of JSON or the parsed object) as `{ ok: true, capabilities, runtime }` or `{ ok: false, problem }`. `capabilities` is additive on the wire: absent means the broker
+ * advertises none (a broker that predates it), which is an answer; a present value must be an array of non-empty strings, each once, or the handshake is refused (a name that is not a string is no
+ * name, and a list that repeats itself is not read).
+ */
+export function parseHandshake(input) {
+  let event = input;
+  if (typeof input === "string") { try { event = JSON.parse(input); } catch { return { ok: false, problem: "the broker's first reply line is not JSON" }; } }
+  if (!isObject(event) || typeof event.type !== "string") return { ok: false, problem: "the broker's first reply is not a HANDSHAKE event (it has no type)" };
+  if (event.type !== "HANDSHAKE") return { ok: false, problem: `the broker's first event is ${event.type}, not the HANDSHAKE (every reply begins with it, GB-75): its capabilities were not received` };
+  const runtime = normalizeIdentity(event.runtime);
+  if (!runtime) return { ok: false, problem: "the broker's HANDSHAKE carries no valid runtime identity" };
+  let capabilities = [];
+  if (Object.hasOwn(event, "capabilities")) {
+    const list = event.capabilities;
+    if (!Array.isArray(list)) return { ok: false, problem: "the broker's HANDSHAKE capabilities must be an array of strings" };
+    for (const [i, name] of list.entries()) {
+      if (typeof name !== "string") return { ok: false, problem: `the broker's HANDSHAKE capabilities[${i}] is not a string` };
+      if (name === "") return { ok: false, problem: `the broker's HANDSHAKE capabilities[${i}] is empty` };
+    }
+    if (new Set(list).size !== list.length) return { ok: false, problem: "the broker's HANDSHAKE lists a capability twice: a list that repeats itself is not read" };
+    capabilities = [...list];
+  }
+  return { ok: true, capabilities, runtime };
+}
+
+/**
+ * Receives the broker's HANDSHAKE: connects to `endpoint` (a Unix socket path or a Windows pipe name, through `connect`, `net.connect` by default), sends the client's own health probe with `identity`
+ * and parses the FIRST event of the reply. Resolves, never rejects: `{ ok: true, capabilities, runtime }` or `{ ok: false, problem }` (no endpoint, refused, closed, silent for `timeoutMs`, an
+ * oversized line, anything but the HANDSHAKE first, a malformed list).
+ */
+export function readBrokerHandshake({ endpoint, identity, connect = (target) => net.connect({ path: target }), timeoutMs = HANDSHAKE_TIMEOUT_MS, maxLineBytes = MAX_HANDSHAKE_LINE_BYTES }) {
+  return new Promise((resolve) => {
+    let settled = false; let connected = false; let buffer = Buffer.alloc(0); let conn = null; let timer = null;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      try { conn?.destroy(); } catch { /* already gone */ }
+      resolve(result);
+    };
+    const problem = (text) => finish({ ok: false, problem: text });
+    try { conn = connect(endpoint); } catch (error) { problem(`cannot connect to the broker at ${endpoint} (${error?.code ?? error?.message ?? error})`); return; }
+    timer = setTimeout(() => problem(`the broker at ${endpoint} sent no HANDSHAKE within ${timeoutMs} ms`), timeoutMs);
+    conn.on("connect", () => {
+      connected = true;
+      try { conn.write(`${JSON.stringify({ type: "STATUS", protocol: BUILD_CONTROL_PROTOCOL, runtime: identity, id: HANDSHAKE_PROBE_ID })}\n`); } catch (error) { problem(`cannot send the probe to the broker at ${endpoint} (${error?.message ?? error})`); }
+    });
+    conn.on("data", (chunk) => {
+      if (settled) return;
+      buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))]);
+      const at = buffer.indexOf(0x0a);
+      if (at < 0) { if (buffer.length > maxLineBytes) problem(`the broker's first line exceeds ${maxLineBytes} bytes`); return; }
+      if (at + 1 > maxLineBytes) { problem(`the broker's first line exceeds ${maxLineBytes} bytes`); return; }
+      finish(parseHandshake(buffer.subarray(0, at).toString("utf8")));
+    });
+    conn.on("error", (error) => problem(connected ? `the broker connection at ${endpoint} failed before its HANDSHAKE (${error?.code ?? error?.message ?? error})` : `cannot connect to the broker at ${endpoint} (${error?.code ?? error?.message ?? error})`));
+    conn.on("close", () => problem(`the broker at ${endpoint} closed before its HANDSHAKE`));
+    conn.on("end", () => problem(`the broker at ${endpoint} closed before its HANDSHAKE`));
+  });
+}
+
+const isPipe = (endpoint) => /^\\\\\.\\pipe\\/i.test(String(endpoint));
+
+/**
+ * The broker's HANDSHAKE as the gate receives it: the installed `client` (an absolute path; a Windows .cmd shim resolves to its .exe), the runtime identity of its manifest, the endpoint RustRight's
+ * discovery names, and the handshake read from it. A Unix endpoint must be a socket the current user owns (a planted file or another user's socket is not the broker). `{ ok, capabilities, runtime }`
+ * or `{ ok: false, problem }`.
+ */
+export async function queryBrokerHandshake(o, { client = o?.client } = {}) {
+  const platform = o?.platform ?? process.platform;
+  const env = o?.env ?? process.env;
+  const read = o?.readFile ?? ((file) => fs.readFileSync(file, "utf8"));
+  if (typeof client !== "string" || !client) return { ok: false, problem: "the RustRight client is not on PATH, so its runtime identity cannot be read to receive the broker's HANDSHAKE" };
+  let exe;
+  try { exe = resolveBrokerClient(client, { platform, readFile: read }).file; } catch (error) { return { ok: false, problem: `the RustRight client cannot be resolved (${error.message})` }; }
+  let real = exe;
+  if (platform !== "win32") { try { real = (o?.realpath ?? fs.realpathSync.native)(exe); } catch { real = exe; } }
+  const paths = platform === "win32" ? path.win32 : path.posix;
+  const manifest = paths.join(paths.dirname(real), RUNTIME_MANIFEST_FILE);
+  let text;
+  try { text = read(manifest); } catch (error) { return { ok: false, problem: `cannot read the runtime manifest ${manifest} beside the client (${error?.message ?? error}), so the HANDSHAKE probe has no identity to carry` }; }
+  const identity = parseRuntimeIdentity(text);
+  if (!identity.ok) return { ok: false, problem: `${manifest}: ${identity.problem}` };
+  let endpoint;
+  try { endpoint = (o?.discoverEndpoint ?? discoverBrokerSocket)(env, { platform, exists: fs.existsSync }); } catch (error) { return { ok: false, problem: `the broker endpoint cannot be discovered (${error.message})` }; }
+  if (!endpoint) return { ok: false, problem: "no broker endpoint is configured (no explicit socket variable and no broker.sock under a managed control root)" };
+  if (platform !== "win32" && !isPipe(endpoint)) {
+    try {
+      const stat = (o?.lstat ?? fs.lstatSync)(endpoint);
+      const uid = typeof (o?.uid ?? process.getuid?.()) === "number" ? (o?.uid ?? process.getuid()) : null;
+      if (!stat.isSocket()) return { ok: false, problem: `${endpoint} is not a socket, so it is not the broker's endpoint` };
+      if (uid !== null && stat.uid !== uid) return { ok: false, problem: `${endpoint} is owned by another user (uid ${stat.uid}), so it is not this user's broker` };
+    } catch (error) { return { ok: false, problem: `cannot connect to the broker at ${endpoint} (${error?.code ?? error?.message ?? error})` }; }
+  }
+  return readBrokerHandshake({ endpoint, identity: identity.identity, ...(o?.connectBroker ? { connect: o.connectBroker } : {}), ...(o?.handshakeTimeoutMs ? { timeoutMs: o.handshakeTimeoutMs } : {}) });
+}
+
+/**
+ * The two views of the broker's advertised capabilities: `doctor` (`rustright doctor --json` through the client, `{ ok, capabilities } | { ok: false, problem }`) and `handshake` (received by the gate,
+ * `{ ok, capabilities, runtime } | { ok: false, problem } | null` when none was asked). Both answering must agree exactly (a disagreement refuses, naming each side's extra names: a broker that
+ * restarted between the reads, or a doctor that does not report what the broker said, plans nothing); one answering plans from it with the other's problem kept beside it; neither refuses
+ * with both reasons. `null` handshake leaves the doctor's state untouched.
+ */
+export function mergeCapabilityViews({ doctor, handshake }) {
+  if (handshake === null || handshake === undefined) return doctor;
+  const d = doctor?.ok === true, h = handshake.ok === true;
+  if (d && h) {
+    const fromDoctor = new Set(doctor.capabilities), fromHandshake = new Set(handshake.capabilities);
+    const onlyDoctor = [...fromDoctor].filter((c) => !fromHandshake.has(c)), onlyHandshake = [...fromHandshake].filter((c) => !fromDoctor.has(c));
+    if (onlyDoctor.length || onlyHandshake.length) {
+      return { ok: false, problem: `\`rustright doctor --json\` and the broker's HANDSHAKE disagree about what it advertises (only the doctor lists: ${onlyDoctor.join(", ") || "none"}; only the HANDSHAKE lists: ${onlyHandshake.join(", ") || "none"}); nothing is planned from either` };
+    }
+    return { ok: true, capabilities: [...handshake.capabilities], via: "handshake+doctor" };
+  }
+  if (h) return { ok: true, capabilities: [...handshake.capabilities], via: "handshake", doctorProblem: doctor?.problem ?? "the doctor did not answer" };
+  if (d) return { ok: true, capabilities: [...doctor.capabilities], via: "doctor", handshakeProblem: handshake.problem };
+  return { ok: false, problem: `${doctor?.problem ?? "the doctor did not answer"}; and the HANDSHAKE could not be received: ${handshake.problem}` };
+}

package/broker-pins.mjs

@@ -10,6 +10,11 @@
 // Never read here: the broker's control root, its runtime manifest, `attestation/key.json` (it holds the SECRET key), an environment
 // variable, a flag, the snapshot or a receipt. A missing record in any repository but RightKit refuses the snapshot compile; nothing
 // is enrolled automatically.
+//
+// Platforms: darwin and win32 (every build on those hosts goes through the broker) and linux (a broker is ALLOWED on Linux, never
+// required: GATE-CONTRACT "Linux needs no broker, but a broker is allowed on Linux"). A Linux host with no declared broker stays direct
+// and never reaches this file; only the declared route (managed-cargo.mjs, RIGHTKIT_LINUX_BROKER_*) loads pins, and there the enrolled
+// record decides: the running-gate fallback for linux is null unless ci/rk-pipeline.json carries `attestation.linux`.
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -28,10 +33,12 @@ const fail = (code, message) => { throw new BrokerPinsError(code, message); };
 const sha256 = (data) => crypto.createHash("sha256").update(data).digest("hex");
 const HEX = /^(?:[0-9a-f]{2})+$/;
 
+export const BROKER_PLATFORMS = Object.freeze(["darwin", "win32", "linux"]);
+
 /** The pin record of one platform under the managed data root. */
 export const pinsFile = ({ dataRoot, platform = process.platform }) => {
   if (!dataRoot || !path.isAbsolute(dataRoot)) fail("RK_BROKER_PINS_ROOT", "the managed data root must be an absolute path");
-  if (!["darwin", "win32"].includes(platform)) fail("RK_BROKER_PINS_PLATFORM", `${platform} is not a broker host (darwin and win32 only)`);
+  if (!BROKER_PLATFORMS.includes(platform)) fail("RK_BROKER_PINS_PLATFORM", `${platform} is not a broker host (${BROKER_PLATFORMS.join(", ")} only)`);
   return path.join(dataRoot, PINS_DIR, `broker-${platform}.json`);
 };
 
@@ -72,10 +79,12 @@ const git = (spawn, cwd, args) => {
 };
 
 /**
- * RightKit's own pins, from the revision of the running gate: the repository that holds `gateFile` and its HEAD commit, only when
- * that repository IS the checkout being compiled (RightKit itself). Null when the gate is not run from a RightKit checkout.
+ * The parsed `ci/rk-pipeline.json` of the running gate's own revision: the repository that holds `gateFile` and its HEAD commit, only when
+ * that repository IS the checkout being compiled (RightKit itself). Null when the gate is not run from a RightKit checkout or the file is absent;
+ * a revision that cannot be read, or a file that is not the pipeline schema, is a refusal. Never the working tree, the selected commit or the snapshot.
+ * `{ pipeline, revision }`. Shared by the pins fallback below and the scan-tool policy fallback (scan-tool-enrolment.mjs).
  */
-export function readGateRevisionPins({ gateFile, checkout, platform = process.platform, spawn = spawnSync, realpath = (p) => fs.realpathSync.native(p) }) {
+export function readGateRevisionPipeline({ gateFile, checkout, spawn = spawnSync, realpath = (p) => fs.realpathSync.native(p) }) {
   const here = path.dirname(gateFile);
   const top = git(spawn, here, ["rev-parse", "--show-toplevel"]);
   if (!top) return null;
@@ -89,9 +98,19 @@ export function readGateRevisionPins({ gateFile, checkout, platform = process.pl
   let pipeline;
   try { pipeline = JSON.parse(String(blob.stdout)); } catch (e) { fail("RK_BROKER_PINS_INVALID", `${PIPELINE_FILE} at the gate's revision ${revision.slice(0, 12)} is not JSON (${e.message})`); }
   if (pipeline?.schema !== PIPELINE_SCHEMA) fail("RK_BROKER_PINS_INVALID", `${PIPELINE_FILE} at the gate's revision is not ${PIPELINE_SCHEMA}`);
-  const entry = pipeline.attestation?.[platform];
+  return { pipeline, revision };
+}
+
+/**
+ * RightKit's own pins, from the revision of the running gate: `attestation.<platform>` of readGateRevisionPipeline. Null when the gate is
+ * not run from a RightKit checkout or the file carries no entry for the platform (linux has none unless the file adds `attestation.linux`).
+ */
+export function readGateRevisionPins({ gateFile, checkout, platform = process.platform, spawn = spawnSync, realpath = (p) => fs.realpathSync.native(p) }) {
+  const read = readGateRevisionPipeline({ gateFile, checkout, spawn, realpath });
+  if (!read) return null;
+  const entry = read.pipeline.attestation?.[platform];
   if (!entry) return null;
-  return { ...validatePins(entry, `${PIPELINE_FILE} (${platform}) at the gate's revision ${revision.slice(0, 12)}`), source: "rk-pipeline", revision };
+  return { ...validatePins(entry, `${PIPELINE_FILE} (${platform}) at the gate's revision ${read.revision.slice(0, 12)}`), source: "rk-pipeline", revision: read.revision };
 }
 
 /**
@@ -128,7 +147,7 @@ export function enrollBrokerPins({ dataRoot, platform = process.platform, host,
   return { file, record, rotated: Boolean(existing) };
 }
 
-/** `node broker-pins.mjs enroll --platform <darwin|win32> --data-root <dir> --host H --key-id K --public-key P --broker-digest D [--rotate]` or `show`. */
+/** `node broker-pins.mjs enroll --platform <darwin|win32|linux> --data-root <dir> --host H --key-id K --public-key P --broker-digest D [--rotate]` or `show`. */
 export function main(argv, { out = (m) => process.stdout.write(`${m}\n`), err = (m) => process.stderr.write(`${m}\n`) } = {}) {
   const [command, ...rest] = argv;
   const opt = (name) => { const i = rest.indexOf(name); return i < 0 ? undefined : rest[i + 1]; };
@@ -144,7 +163,7 @@ export function main(argv, { out = (m) => process.stdout.write(`${m}\n`), err =
       out(pins ? JSON.stringify(pins) : "no enrollment");
       return pins ? 0 : 1;
     }
-    err("usage: broker-pins.mjs enroll|show --platform <darwin|win32> --data-root <dir> [--host H --key-id K --public-key P --broker-digest D [--rotate]]");
+    err("usage: broker-pins.mjs enroll|show --platform <darwin|win32|linux> --data-root <dir> [--host H --key-id K --public-key P --broker-digest D [--rotate]]");
     return 2;
   } catch (e) { err(`${e.code ?? "error"}: ${e.message}`); return 1; }
 }