@rightkit/release 0.6.13 → 0.6.14

package/lock-identity.mjs

@@ -0,0 +1,138 @@
+// Process identity for the build-ownership submit lock (ownership-mark.mjs): pid + start time + boot id. A LEAF module (node builtins and
+// background-process.mjs only) because ownership-mark.mjs is imported by snapshot-broker.mjs and build-ownership.mjs, which cannot import
+// each other. build-ownership.mjs keeps the full process probe for the ownership record; this is the minimum the lock needs, with the same
+// meaning: a holder is dead only when its pid is gone, or the pid now runs a process that started at another time, or the host rebooted.
+import fs from "node:fs";
+import { spawnSync } from "./background-process.mjs";
+
+/** Two start times of one pid are one process when they agree to within this (ps prints whole seconds). Same figure as build-ownership.mjs. */
+export const LOCK_SAME_START_MS = 3000;
+
+/** An absolute path for a system tool (a child of the gate may hold no PATH): the first candidate that exists, else the bare name. */
+const systemTool = (name, candidates) => candidates.find((c) => { try { return fs.statSync(c).isFile(); } catch { return false; } }) ?? name;
+const PS = () => systemTool("ps", ["/bin/ps", "/usr/bin/ps"]);
+const SYSCTL = () => systemTool("sysctl", ["/usr/sbin/sysctl", "/sbin/sysctl"]);
+const PERL = () => systemTool("perl", ["/usr/bin/perl"]);
+const run = (spawn, command, args, env = {}) => spawn(command, args, { encoding: "utf8", env: { ...process.env, ...env }, timeout: 30_000, maxBuffer: 1 << 20 });
+
+/** This boot's identity (Linux boot_id, macOS kern.bootsessionuuid); null where it cannot be read (Windows, a failure). */
+export function lockBootId({ platform = process.platform, readFile = fs.readFileSync, spawn = spawnSync } = {}) {
+  try {
+    if (platform === "linux") { const id = String(readFile("/proc/sys/kernel/random/boot_id", "utf8")).trim(); return /^[0-9a-f-]{16,}$/i.test(id) ? id : null; }
+    if (platform === "darwin") {
+      const r = run(spawn, SYSCTL(), ["-n", "kern.bootsessionuuid"]);
+      const id = String(r.stdout ?? "").trim();
+      return !r.error && r.status === 0 && /^[0-9a-f-]{16,}$/i.test(id) ? id : null;
+    }
+  } catch { /* unknown */ }
+  return null;
+}
+
+/**
+ * `{ alive, startedMs }` for `pid`; throws when it cannot be established (the caller then treats the holder as live: fail closed).
+ * Unix: kill(pid, 0) for existence, `ps -o lstart=` for the start. Windows: this process from its time origin, another from Get-Process.
+ */
+export function lockProcessIdentity(pid, { platform = process.platform, spawn = spawnSync, kill = process.kill.bind(process) } = {}) {
+  if (pid === process.pid && platform === "win32") return { alive: true, startedMs: Math.round(performance.timeOrigin) };
+  let exists = true;
+  try { kill(pid, 0); } catch (e) { if (e.code === "ESRCH") exists = false; else if (e.code !== "EPERM") throw e; }
+  if (!exists) return { alive: false, startedMs: null };
+  if (platform === "win32") {
+    const script = `$p = Get-Process -Id ${Number(pid)} -ErrorAction SilentlyContinue; if ($p) { 'START:' + ([DateTimeOffset]$p.StartTime).ToUnixTimeMilliseconds() } else { 'GONE' }`;
+    const r = run(spawn, "powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")]);
+    if (r.error || r.status !== 0) throw new Error(`powershell: ${r.error?.message ?? `exit ${r.status}`}`);
+    const out = String(r.stdout ?? "").trim();
+    if (out === "GONE") return { alive: false, startedMs: null };
+    const m = /START:(\d+)/.exec(out);
+    if (!m) throw new Error(`cannot read the start time of pid ${pid}`);
+    return { alive: true, startedMs: Number(m[1]) };
+  }
+  const r = run(spawn, PS(), ["-o", "lstart=", "-p", String(pid)], { LC_ALL: "C", LANG: "C" });
+  if (r.error) throw new Error(`ps: ${r.error.message}`);
+  const text = String(r.stdout ?? "").trim();
+  if (text === "") { if (r.status === 1) return { alive: false, startedMs: null }; throw new Error(`ps gave no start time for pid ${pid}`); }
+  const startedMs = Date.parse(text.replace(/\s+/g, " "));
+  if (!Number.isFinite(startedMs)) throw new Error(`cannot read the start time of pid ${pid} (${text})`);
+  return { alive: true, startedMs };
+}
+
+/** This process's identity as a lock holder records it. Cached: a process's start never changes. */
+let cachedSelf = null;
+export function selfLockIdentity(options = {}) {
+  if (options.fresh !== true && cachedSelf) return cachedSelf;
+  const id = lockProcessIdentity(process.pid, options);
+  const self = { pid: process.pid, startedMs: id.startedMs, bootId: lockBootId(options) };
+  if (options.fresh !== true) cachedSelf = self;
+  return self;
+}
+
+// ---- the gate's identity as RustRight reads it (BROKER-CONTRACT section 16, GB-76) ----
+// The carrier owner record names the gate by `{ pid, startTimeMs }`, and the broker judges it with `rustright_process::identity_state`: the recorded start time must EQUAL what RustRight reads
+// for that pid (Same), or the pid is `Reused`. The lock identity above tolerates a few seconds; this does not, so it computes RustRight's own figure on each platform:
+//   Linux    `/proc/<pid>/stat` field 22 (start ticks since boot) and `/proc/stat` btime: `btime * 1000 + ticks * 1000 / CLK_TCK` (integer division)
+//   macOS    the process's kernel start timeval (kinfo_proc's first field, `sysctl -b kern.proc.pid.<pid>`: int64 seconds, int32 microseconds), `(sec * 1e6 + usec) / 1000` floored
+//   Windows  GetProcessTimes' creation time as UNIX milliseconds (`Process.StartTime`, floored to a millisecond)
+// `null` when the figure cannot be read: the owner record then carries null and the broker keeps the carrier for ever (unverifiable), never retires it.
+
+/** Linux: the start time in epoch ms from a `/proc/<pid>/stat` text, `/proc/stat` text and CLK_TCK, or null. The command name may hold spaces and parentheses: fields count from the LAST `)`. */
+export function linuxStartTimeMs(stat, procStat, hz) {
+  const close = String(stat).lastIndexOf(")");
+  if (close < 0) return null;
+  const ticks = Number(String(stat).slice(close + 1).trim().split(/\s+/)[19]);
+  const boot = Number(/^btime\s+(\d+)/m.exec(String(procStat))?.[1]);
+  if (!Number.isInteger(ticks) || ticks < 0 || !Number.isInteger(boot) || !Number.isFinite(hz) || hz <= 0) return null;
+  return boot * 1000 + Math.floor((ticks * 1000) / hz);
+}
+
+/** macOS: the start time in epoch ms from the bytes `sysctl -b kern.proc.pid.<pid>` prints (the start timeval leads kinfo_proc), or null. */
+export function darwinStartTimeMs(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.length < 12) return null;
+  const sec = bytes.readBigInt64LE(0); const usec = bytes.readInt32LE(8);
+  if (sec <= 0n || usec < 0 || usec >= 1_000_000) return null;
+  return Number((sec * 1_000_000n + BigInt(usec)) / 1000n);
+}
+
+/** Prints the `kinfo_proc` row of the pid in $ARGV[0] (sysctl [CTL_KERN=1, KERN_PROC=14, KERN_PROC_PID=1, pid] through SYS___sysctl, 202), or exits 1 printing nothing. */
+const DARWIN_KINFO_PERL = [
+  'my $mib = pack("i4", 1, 14, 1, $ARGV[0]); my $buf = "\\0" x 1024; my $len = pack("Q", 1024);',
+  "syscall(202, $mib, 4, $buf, $len, 0, 0) == 0 or exit 1;",
+  'binmode STDOUT; print substr($buf, 0, unpack("Q", $len));',
+].join(" ");
+
+/** `pid`'s start time as RustRight's `start_time_ms` reads it, or null when it cannot be read (gone, denied, an unknown platform). `readFile`, `spawn` and `hz` are seams for a simulated host. */
+export function processStartTimeMs(pid, { platform = process.platform, readFile = fs.readFileSync, spawn = spawnSync, hz = null } = {}) {
+  try {
+    if (!Number.isInteger(pid) || pid <= 0) return null;
+    if (platform === "linux") {
+      let clock = hz;
+      if (clock === null) { const r = run(spawn, "getconf", ["CLK_TCK"]); const n = Number(String(r.stdout ?? "").trim()); clock = !r.error && r.status === 0 && Number.isInteger(n) && n > 0 ? n : 100; }
+      return linuxStartTimeMs(readFile(`/proc/${pid}/stat`, "utf8"), readFile("/proc/stat", "utf8"), clock);
+    }
+    if (platform === "darwin") {
+      const options = { env: { ...process.env, LC_ALL: "C" }, timeout: 30_000, maxBuffer: 1 << 20 };
+      const read = (r) => (r.error || r.status !== 0 ? null : darwinStartTimeMs(Buffer.isBuffer(r.stdout) ? r.stdout : Buffer.from(String(r.stdout ?? ""), "latin1")));
+      const named = read(spawn(SYSCTL(), ["-b", `kern.proc.pid.${pid}`], options));
+      if (named !== null) return named;
+      // macOS 27's sysctl(8) no longer resolves `kern.proc.pid.<pid>` by name ("unknown oid"), so the row is read through the numeric MIB
+      // [CTL_KERN, KERN_PROC, KERN_PROC_PID, pid] (the one RustRight reads, rustright-process macos.rs) by the system perl: the same bytes, the same figure.
+      return read(spawn(PERL(), ["-e", DARWIN_KINFO_PERL, String(pid)], options));
+    }
+    if (platform === "win32") {
+      const script = `$p = Get-Process -Id ${Number(pid)} -ErrorAction SilentlyContinue; if ($p) { 'START:' + ([DateTimeOffset]$p.StartTime).ToUnixTimeMilliseconds() } else { 'GONE' }`;
+      const r = run(spawn, "powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")]);
+      if (r.error || r.status !== 0) return null;
+      const m = /START:(\d+)/.exec(String(r.stdout ?? ""));
+      return m ? Number(m[1]) : null;
+    }
+  } catch { /* unreadable: null */ }
+  return null;
+}
+
+/** This process's own start time as RustRight reads it. Cached: a process's start never changes. A null (unreadable) is retried on the next call. */
+let cachedSelfStart = null;
+export function selfStartTimeMs(options = {}) {
+  if (options.fresh !== true && cachedSelfStart !== null) return cachedSelfStart;
+  const ms = processStartTimeMs(process.pid, options);
+  if (options.fresh !== true && ms !== null) cachedSelfStart = ms;
+  return ms;
+}

package/managed-cargo.mjs

@@ -1,9 +1,10 @@
-import { discoverBrokerSocket, managedControlCandidates, resolveManagedRoots } from './managed-roots.mjs';
-import { randomUUID } from "node:crypto";
+import { discoverBrokerSocket, managedControlCandidates, managedRuntimeClient, resolveManagedRoots } from './managed-roots.mjs';
+import { createHash, randomUUID } from "node:crypto";
 import { homedir, userInfo } from "node:os";
-import { closeSync, existsSync, mkdirSync, openSync, readSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { spawn as spawnProcess, spawnSync } from "./background-process.mjs";
+import { CARRIER_MISSING_CODE, carriedCargoMapOf, runCarriedCargo } from "./carried-cargo.mjs";
 
 /**
  * Linux, and any host that is neither Mac nor Windows, never uses the RustRight broker: WSL2, a VM, a cloud or CI runner, Linux hosted on
@@ -12,6 +13,103 @@ import { spawn as spawnProcess, spawnSync } from "./background-process.mjs";
  */
 export const directPlatform = (platform = process.platform) => platform !== "darwin" && platform !== "win32";
 
+/**
+ * The optional Linux broker route (Adrian, 2026-10-31: "linux normally not needing broker" is not "broker not allowed on linux"). Linux stays direct
+ * unless the host DECLARES a broker, explicitly and only through these variables; a RustRight client on PATH, a socket name in the older broker
+ * variables or a shim directory never activates it. A declared route is validated here, once, for every caller (the executor, managed-cargo's
+ * carried seam and its client route, the gate entry): an invalid or unreachable declared broker REFUSES, it never falls back to direct cargo.
+ *   RIGHTKIT_LINUX_BROKER_CLIENT        absolute path of the installed RustRight client (`rustright`)
+ *   RIGHTKIT_LINUX_BROKER_SOCKET        absolute path of the broker's endpoint (the unix socket the client talks to)
+ *   RIGHTKIT_LINUX_BROKER_CLIENT_SHA256 REQUIRED: the client's pinned SHA-256 (runtime identity); absent or different refuses
+ */
+export const LINUX_BROKER_CLIENT_ENV = "RIGHTKIT_LINUX_BROKER_CLIENT";
+export const LINUX_BROKER_SOCKET_ENV = "RIGHTKIT_LINUX_BROKER_SOCKET";
+export const LINUX_BROKER_CLIENT_SHA256_ENV = "RIGHTKIT_LINUX_BROKER_CLIENT_SHA256";
+export const LINUX_BROKER_ROUTE = "linux-broker";
+export const LINUX_BROKER_REFUSAL = "RK_LINUX_BROKER_UNAVAILABLE";
+
+/** True when this Linux (direct-platform) host declared a broker route, valid or not. Presence of any declaring variable counts, so a half-written declaration refuses. */
+export const linuxBrokerDeclared = (env = process.env, platform = process.platform) =>
+  directPlatform(platform) && [LINUX_BROKER_CLIENT_ENV, LINUX_BROKER_SOCKET_ENV, LINUX_BROKER_CLIENT_SHA256_ENV].some((name) => env?.[name] !== undefined);
+
+/** A host that compiles direct: a direct platform that declared no broker route. */
+export const directHost = (platform = process.platform, env = process.env) => directPlatform(platform) && !linuxBrokerDeclared(env, platform);
+
+const sha256Cache = new Map();
+const LINUX_ROUTE_FS = Object.freeze({
+  realpath: (p) => realpathSync.native(p),
+  stat: (p) => statSync(p),
+  uid: () => (typeof process.getuid === "function" ? process.getuid() : -1),
+  digest: (real, meta) => {
+    const key = `${real}\0${meta.dev}\0${meta.ino}\0${meta.size}\0${meta.mtimeMs}`;
+    if (!sha256Cache.has(key)) sha256Cache.set(key, createHash("sha256").update(readFileSync(real)).digest("hex"));
+    return sha256Cache.get(key);
+  },
+});
+
+/** Why an installed path is not trusted, or null: every directory on it, and the entry itself, belongs to root or to the gate's user and is not group- or world-writable (a root-owned sticky directory such as /tmp excepted). */
+function untrustedChain(real, ops, uid, { entryMode = true } = {}) {
+  const parts = real.split("/").filter(Boolean);
+  let at = "";
+  for (let i = -1; i < parts.length; i += 1) {
+    if (i >= 0) at = `${at}/${parts[i]}`;
+    const here = at || "/";
+    const last = i === parts.length - 1;
+    let meta;
+    try { meta = ops.stat(here); } catch (e) { return `${here} cannot be inspected (${e.code ?? e.message})`; }
+    if (meta.uid !== 0 && meta.uid !== uid) return `${here} is owned by uid ${meta.uid}, neither root nor the gate's user`;
+    // A shared sticky directory owned by root (/tmp) lets nobody replace another user's entry, so only it may stay writable.
+    const stickyShared = !last && meta.uid === 0 && (meta.mode & 0o1000) !== 0;
+    if ((!last || entryMode) && (meta.mode & 0o022) !== 0 && !stickyShared) return `${here} is group- or world-writable`;
+  }
+  return null;
+}
+
+/**
+ * Resolve the declared Linux broker route: `{ declared: false }` (the direct default), `{ declared: true, ok: false, code, problem }` (refuse) or
+ * `{ declared: true, ok: true, client, socket, clientSha256 }`. Judged: the client is an absolute, regular, executable file reached through a
+ * root- or gate-user-owned chain that nobody else can write, and matches the required pinned digest; the endpoint is an absolute unix
+ * socket on such a chain (the broker authenticates its peers itself); and no other broker endpoint is named in the environment. Whether the broker
+ * behind the socket answers, and what it advertises, is asked of the real client by the gate's capability handshake, which refuses the route.
+ * `fsOps` is for tests of the judging only (stat/realpath/uid/digest over a described tree); it is never an alternative broker.
+ */
+export function resolveLinuxBrokerRoute({ env = process.env, platform = process.platform, fsOps } = {}) {
+  if (!linuxBrokerDeclared(env, platform)) return { declared: false };
+  const ops = { ...LINUX_ROUTE_FS, ...fsOps };
+  const refuse = (problem) => ({ declared: true, ok: false, code: LINUX_BROKER_REFUSAL, problem: `${LINUX_BROKER_REFUSAL}: the declared Linux broker route cannot be used: ${problem}; nothing compiled and cargo never runs direct around a declared broker` });
+  const absolute = (name) => {
+    const value = env[name];
+    if (typeof value !== "string" || !value) return { problem: `${name} is ${value === undefined ? "not set" : "empty"} (a declared route needs both ${LINUX_BROKER_CLIENT_ENV} and ${LINUX_BROKER_SOCKET_ENV})` };
+    if (!path.posix.isAbsolute(value) || value.split("/").includes("..") || value.includes("\0")) return { problem: `${name} must be an absolute path with no '..' (got ${JSON.stringify(value.slice(0, 120))})` };
+    return { value };
+  };
+  const uid = ops.uid();
+  const c = absolute(LINUX_BROKER_CLIENT_ENV); if (c.problem) return refuse(c.problem);
+  const k = absolute(LINUX_BROKER_SOCKET_ENV); if (k.problem) return refuse(k.problem);
+  let client; let clientMeta;
+  try { client = ops.realpath(c.value); clientMeta = ops.stat(client); } catch (e) { return refuse(`the client ${c.value} cannot be resolved (${e.code ?? e.message})`); }
+  if (!clientMeta.isFile?.()) return refuse(`the client ${client} is not a regular file`);
+  if ((clientMeta.mode & 0o111) === 0) return refuse(`the client ${client} is not executable`);
+  const clientProblem = untrustedChain(client, ops, uid);
+  if (clientProblem) return refuse(`the client is not trusted: ${clientProblem}`);
+  let socket; let socketMeta;
+  try { socket = ops.realpath(k.value); socketMeta = ops.stat(socket); } catch (e) { return refuse(`the broker endpoint ${k.value} does not exist or cannot be inspected (${e.code ?? e.message}); the broker is not running here`); }
+  if (!socketMeta.isSocket?.()) return refuse(`the broker endpoint ${socket} is not a unix socket`);
+  const socketProblem = untrustedChain(socket, ops, uid, { entryMode: false });
+  if (socketProblem) return refuse(`the broker endpoint is not trusted: ${socketProblem}`);
+  for (const other of ["RUSTRIGHT_BUILD_BROKER_SOCKET", "RIGHTKIT_BUILD_BROKER_SOCKET"]) {
+    if (typeof env[other] === "string" && env[other] !== "" && env[other] !== k.value && env[other] !== socket) return refuse(`${other} names another endpoint (${env[other]}); one route is declared, so the choice is ambiguous`);
+  }
+  let clientSha256;
+  try { clientSha256 = ops.digest(client, clientMeta); } catch (e) { return refuse(`the client ${client} cannot be read for its identity (${e.code ?? e.message})`); }
+  // The pin is REQUIRED (root decision, 2026-10-31): a declaration without the client's digest, or with another one, is refused.
+  const pinned = env[LINUX_BROKER_CLIENT_SHA256_ENV];
+  if (pinned === undefined || pinned === "") return refuse(`${LINUX_BROKER_CLIENT_SHA256_ENV} is not set (the declared client's SHA-256 is required; the client ${client} has ${clientSha256})`);
+  if (!/^[0-9a-f]{64}$/i.test(String(pinned))) return refuse(`${LINUX_BROKER_CLIENT_SHA256_ENV} is not a SHA-256 digest`);
+  if (String(pinned).toLowerCase() !== clientSha256) return refuse(`the client ${client} has digest ${clientSha256}, not the pinned ${String(pinned).toLowerCase()}`);
+  return { declared: true, ok: true, client, socket, clientSha256 };
+}
+
 const MANAGED_AGENT_BIN = /(?:^|\/)(?:\.rightkit-managed|rightkitmanagedagent|rightkit\/build-control)\/agent-bin\/?$/i;
 function fileHead(file) {
   let fd = null;
@@ -24,53 +122,32 @@ function fileHead(file) {
  * RIGHTKIT_MANAGED_AGENT_BIN, or a script that routes through the broker, read 4 KiB at most), and the first real cargo left on it.
  * Plain `cargo` then can only be a real toolchain; with none, a cargo launch fails as missing, never through a shim.
  */
-export function directCargoPath({ env = process.env, exists = existsSync, readHead = fileHead } = {}) {
-  const configured = env.RIGHTKIT_MANAGED_AGENT_BIN ? path.posix.resolve(env.RIGHTKIT_MANAGED_AGENT_BIN) : null;
+export function directCargoPath({ env = process.env, exists = existsSync, readHead = fileHead, platform = process.platform } = {}) {
+  // `platform` only matters for a forced direct run on Windows (a recorded broker exception): ";" separators, backslash paths, cargo.exe.
+  const win = platform === "win32";
+  const norm = (d) => (win ? String(d).replaceAll("\\", "/") : d);
+  const configured = env.RIGHTKIT_MANAGED_AGENT_BIN ? path.posix.resolve(norm(env.RIGHTKIT_MANAGED_AGENT_BIN)) : null;
   const kept = []; const dropped = []; let cargo = null;
-  for (const dir of String(env.PATH ?? "").split(":").filter(Boolean)) {
-    const candidate = path.posix.join(dir, "cargo");
-    const isShim = exists(candidate) && (MANAGED_AGENT_BIN.test(dir) || (configured && path.posix.resolve(dir) === configured) || /cargo-guard\.mjs|rustright/i.test(readHead(candidate)));
+  for (const dir of String(env.PATH ?? "").split(win ? ";" : ":").filter(Boolean)) {
+    const candidates = win ? ["cargo.exe", "cargo.cmd", "cargo.bat", "cargo"].map((n) => path.win32.join(dir, n)) : [path.posix.join(dir, "cargo")];
+    const found = candidates.find((c) => exists(c));
+    const isShim = Boolean(found) && (MANAGED_AGENT_BIN.test(norm(dir)) || (configured && path.posix.resolve(norm(dir)) === configured) || /cargo-guard\.mjs|rustright/i.test(readHead(found)));
     if (isShim) { dropped.push(dir); continue; }
     kept.push(dir);
-    if (!cargo && exists(candidate)) cargo = candidate;
+    if (!cargo && found) cargo = found;
   }
-  return { path: kept.join(":"), dropped, cargo };
+  return { path: kept.join(win ? ";" : ":"), dropped, cargo };
 }
 
-/** `env` for a direct host: PATH without RustRight shim directories. Unchanged on Mac and Windows. */
+/** `env` for a direct host: PATH without RustRight shim directories. Unchanged on Mac, Windows and a declared Linux broker route. */
 export function directCargoEnv(env = process.env, platform = process.platform, exists = existsSync) {
-  if (!directPlatform(platform)) return env;
+  if (!directHost(platform, env)) return env; // Mac, Windows, and a Linux host that declared a broker route (no direct cargo there)
   const direct = directCargoPath({ env, exists });
   return direct.dropped.length ? { ...env, PATH: direct.path } : env;
 }
 
-export function managedRuntimeClient(env = process.env, platform = process.platform, exists = existsSync) {
-  if (directPlatform(platform)) return undefined;
-  const roots = managedControlCandidates({ env, platform });
-  const paths = platform === 'win32' ? path.win32 : path.posix;
-  // runtime-current ships the native `rustright` client.
-  for (const root of roots) {
-    const client = paths.join(root, "runtime-current", platform === 'win32' ? "rustright.exe" : "rustright");
-    if (exists(client)) return client;
-  }
-  // RustRight's own install (2026-10-17 cutover): the Mac agent-bin shims exec this client directly.
-  if (platform === 'darwin') {
-    const client = path.posix.join(env.HOME || homedir(), 'Library', 'Application Support', 'RustRight', 'runtime', 'rustright');
-    if (exists(client)) return client;
-    // Broker-managed HOME may point at a build home; the installed native client belongs to the OS account.
-    const accountClient = path.posix.join(userInfo().homedir, 'Library', 'Application Support', 'RustRight', 'runtime', 'rustright');
-    if (exists(accountClient)) return accountClient;
-  }
-  // RustRight's own install on Windows (2026-10-18 cutover): the runtime moved out of the control root to
-  // <drive>\.rustright\runtime, beside the control root's drive, and runtime-current was retired.
-  if (platform === 'win32') {
-    for (const root of roots) {
-      const client = path.win32.join(path.win32.parse(root).root, '.rustright', 'runtime', 'rustright.exe');
-      if (exists(client)) return client;
-    }
-  }
-  return undefined;
-}
+// The installed-runtime client lookup lives in managed-roots.mjs (a leaf module, so broker-client.mjs can use it without an import cycle).
+export { managedRuntimeClient };
 
 /** Command line that runs the managed client: the native rustright client runs directly. */
 export function managedRuntimeCommand(client, args) {
@@ -95,18 +172,44 @@ export function acquireManagedRunLease({ command, env = process.env, platform =
 }
 
 export function managedHost(env, platform = process.platform) {
-  if (directPlatform(platform)) return false; // Linux is never broker-managed (directPlatform), whatever the env names
-  return Boolean(env.RIGHTKIT_BUILD_BROKER_SOCKET)
+  // Linux is broker-managed only through the explicit declared route (linuxBrokerDeclared), whatever else the env names.
+  if (directPlatform(platform)) return linuxBrokerDeclared(env, platform);
+  return Boolean(env.RUSTRIGHT_BUILD_BROKER_SOCKET || env.RIGHTKIT_BUILD_BROKER_SOCKET)
     || /(?:^|[;:])[^;:]*[/\\](?:\.rightkit-managed|rightkitmanagedagent|rightkit[/\\]build-control)[/\\]agent-bin(?:[;:]|$)/i.test(String(env.PATH ?? ""));
 }
 
-export function runCargoSync(args, options = {}, { platform = process.platform, exists = existsSync, spawn = spawnSync } = {}) {
+/**
+ * The carried seam (rightkit#1301): on a broker host, a call made by a child of a snapshot door stage, which the gate started with the
+ * stage's carrier map in its environment, goes through that carrier (carried-cargo.mjs: one signed, ledgered request per call, from the
+ * manifest's directory, output directory from the receipt). A map that cannot be read refuses the call; it is never run uncarried.
+ * A direct Linux host never has a carrier; a Linux host that declared a broker route has the same one. A call made with no carrier in its environment keeps the managed client route as before; refusing a
+ * carrier-less compile that comes from a snapshot stage is RustRight's side (rightkit#1301 step 3).
+ */
+function carriedSeam(args, options, { platform, spawn }) {
+  if (directHost(platform, options.env ?? process.env)) return null;
+  const carried = carriedCargoMapOf(options.env ?? process.env);
+  if (!carried) return null;
+  if (carried.error) return { status: 101, signal: null, stdout: "", stderr: `rightkit-gate: ${CARRIER_MISSING_CODE}: ${carried.error}\n`, error: Object.assign(new Error(`${CARRIER_MISSING_CODE}: ${carried.error}`), { code: CARRIER_MISSING_CODE }) };
+  return runCarriedCargo(args, options, { map: carried.map, spawn });
+}
+
+export function runCargoSync(args, options = {}, { platform = process.platform, exists = existsSync, spawn = spawnSync, fsOps } = {}) {
   const env = options.env ?? process.env;
+  const seam = carriedSeam(args, options, { platform, spawn });
+  if (seam) return seam;
+  // A Linux host that declared a broker route: every call goes to the validated client at the declared endpoint, or is refused. Never direct.
+  const linux = resolveLinuxBrokerRoute({ env, platform, fsOps });
+  if (linux.declared) {
+    if (!linux.ok) return unavailable(linux.problem);
+    const result = spawn(linux.client, ["cargo", ...args], { ...options, env: { ...env, RUSTRIGHT_BUILD_BROKER_SOCKET: linux.socket } });
+    if (result.status !== 0 && /RK_BROKER_UNAVAILABLE|RightKit broker (?:unavailable|endpoint is not configured)/i.test(String(result.stderr ?? ''))) return { ...result, error: unavailable(String(result.stderr).trim()).error };
+    return result;
+  }
   const client = managedRuntimeClient(env, platform, exists);
   if (client) {
     const socket = discoverBrokerSocket(env, { platform, exists });
     if (platform === 'darwin' && (!socket || !exists(socket))) return unavailable('RightKit broker socket is unavailable');
-    const childEnv = socket ? { ...env, RIGHTKIT_BUILD_BROKER_SOCKET: socket } : env;
+    const childEnv = socket ? { ...env, RUSTRIGHT_BUILD_BROKER_SOCKET: socket } : env;
     const invocation = managedRuntimeCommand(client, ["cargo", ...args]);
     const result = spawn(invocation.command, invocation.args, { ...options, env: childEnv });
     if (platform === 'darwin' && result.status !== 0 && /RK_BROKER_UNAVAILABLE|RightKit broker (?:unavailable|endpoint is not configured)/i.test(String(result.stderr ?? ''))) {
@@ -155,6 +258,8 @@ export function spawnCollect(command, args, options = {}, { spawnAsync = spawnPr
   });
 }
 
+const carriedSeamActive = (args, options, { platform = process.platform } = {}) => !directHost(platform, options.env ?? process.env) && Boolean(carriedCargoMapOf(options.env ?? process.env));
+
 /**
  * Async twin of `runCargoSync`: the same client, broker-socket and darwin-never-direct selection (it asks
  * `runCargoSync` to choose, with a spawn that only records the invocation), then runs the chosen invocation
@@ -163,12 +268,14 @@ export function spawnCollect(command, args, options = {}, { spawnAsync = spawnPr
  */
 export async function runCargoAsync(args, options = {}, deps = {}) {
   const { spawnAsync = spawnCollect, ...syncDeps } = deps;
+  // A carried call (a snapshot stage's) is verified in process: it runs whole, then resolves.
+  if (carriedSeamActive(args, options, syncDeps)) return runCargoSync(args, options, syncDeps);
   let chosen;
   const probe = runCargoSync(args, options, { ...syncDeps, spawn: (command, commandArgs, commandOptions) => { chosen = { command, args: commandArgs, options: commandOptions }; return { status: 0, stdout: "", stderr: "" }; } });
   if (!chosen) return probe;
   const result = await spawnAsync(chosen.command, chosen.args, chosen.options);
   const platform = syncDeps.platform ?? process.platform;
-  if (platform === 'darwin' && result.status !== 0 && /RK_BROKER_UNAVAILABLE|RightKit broker (?:unavailable|endpoint is not configured)/i.test(String(result.stderr ?? ''))) {
+  if ((platform === 'darwin' || linuxBrokerDeclared(options.env ?? process.env, platform)) && result.status !== 0 && /RK_BROKER_UNAVAILABLE|RightKit broker (?:unavailable|endpoint is not configured)/i.test(String(result.stderr ?? ''))) {
     return { ...result, error: unavailable(String(result.stderr).trim()).error };
   }
   return result;

package/managed-roots.mjs

@@ -1,15 +1,41 @@
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
 import { posix, win32 } from 'node:path';
+import path from 'node:path';
 
-/** RIGHTKIT_MANAGED_ROOT remains a data-root override for existing release callers. */
-export function resolveManagedRoots({ env = process.env, platform = process.platform, home = homedir(), controlRoot, dataRoot } = {}) {
+/**
+ * The value of `RUSTRIGHT_<name>`, else of its legacy `RIGHTKIT_<name>` spelling (empty is unset). The same precedence as RustRight's resolver
+ * (rustright-config managed_roots.rs `env_named`): a current name always wins over the legacy one it replaces, so a stale legacy variable can never override it.
+ */
+export const envNamed = (env, name) => {
+  for (const key of [`RUSTRIGHT_${name}`, `RIGHTKIT_${name}`]) if (typeof env?.[key] === 'string' && env[key] !== '') return env[key];
+  return undefined;
+};
+
+/**
+ * The managed roots (GB-63: ONE resolver, the shape of RustRight's `rustright-config::managed_roots`, exercised against its shared fixtures). The data root is `DATA_ROOT`,
+ * `MANAGED_ROOT`, `EXTERNAL_ROOT` (RUSTRIGHT_ names first, then the legacy RIGHTKIT_ ones), else the legacy root; the control root is `CONTROL_ROOT`, else the platform default.
+ * `runtimeCurrent` (the wire key, kept for compatibility) is `<control>/runtime`, the one fixed live runtime directory; the installer's own runtime sits at its final RustRight
+ * path, `runtimeRoot` (`RUSTRIGHT_RUNTIME_ROOT`, else RustRight's per-platform default) and `liveRuntime` = `<runtimeRoot>/runtime`, which supersedes it.
+ *
+ * `legacyRoot` is the pre-rename Mac/Windows location the shared fixtures pin on every platform; it is never a default for a host that is neither: a Linux (or
+ * other) host that names no data root gets `<home>/.local/state/rightkit` (the account's own state directory, where its runs, snapshots and build-ownership record
+ * already live), never `/Volumes/D/.rightkit-managed`, a Mac volume that a Linux gate would otherwise create as root. Everything else is RustRight's order:
+ * the data root is named by the same env, `controlRoot` = `dataRoot` off Mac, so a host that names its roots (every declared Linux broker, whose installer sets
+ * RUSTRIGHT_DATA_ROOT / RUSTRIGHT_CONTROL_ROOT) resolves exactly as `rustright-config::managed_roots` does. RustRight resolves a host with NO environment the same
+ * way (rustright 07829c05, pinned in the shared fixtures as "linux no-env defaults to the account state directory"). The broker's answering roots, not either
+ * resolver's guess, say where a running broker keeps its state.
+ */
+export function resolveManagedRoots({ env = process.env, platform = process.platform, home = homedir(), controlRoot, dataRoot, runtimeRoot } = {}) {
   const paths = platform === 'win32' ? win32 : posix;
   const legacyRoot = platform === 'win32' ? 'D:\\.rightkit-managed' : '/Volumes/D/.rightkit-managed';
-  dataRoot ??= env.RIGHTKIT_DATA_ROOT || env.RIGHTKIT_MANAGED_ROOT || env.RIGHTKIT_EXTERNAL_ROOT || legacyRoot;
-  controlRoot ??= env.RIGHTKIT_CONTROL_ROOT || (platform === 'darwin'
+  const managedPlatform = platform === 'darwin' || platform === 'win32';
+  dataRoot ??= envNamed(env, 'DATA_ROOT') || envNamed(env, 'MANAGED_ROOT') || envNamed(env, 'EXTERNAL_ROOT') || (managedPlatform ? legacyRoot : paths.join(home, '.local', 'state', 'rightkit'));
+  controlRoot ??= envNamed(env, 'CONTROL_ROOT') || (platform === 'darwin'
     ? paths.join(home, 'Library', 'Application Support', 'RightKit', 'build-control') : dataRoot);
-  return Object.freeze({ controlRoot, dataRoot, legacyRoot, runtimeCurrent: paths.join(controlRoot, 'runtime-current'),
+  runtimeRoot ??= envNamed(env, 'RUNTIME_ROOT') || (platform === 'darwin' ? paths.join(home, 'Library', 'Application Support', 'RustRight') : platform === 'win32' ? 'D:\\.rustright' : controlRoot);
+  return Object.freeze({ controlRoot, dataRoot, legacyRoot, runtimeCurrent: paths.join(controlRoot, 'runtime'), runtimeRoot, liveRuntime: paths.join(runtimeRoot, 'runtime'),
     configPath: paths.join(controlRoot, 'config.json'), socket: platform === 'win32' ? null : paths.join(controlRoot, 'broker.sock'),
     logs: paths.join(controlRoot, 'logs'), agentBin: paths.join(controlRoot, 'agent-bin'),
     agentPolicy: paths.join(controlRoot, 'agent-policy'), ownershipInstall: paths.join(controlRoot, 'ownership-install'),
@@ -18,22 +44,114 @@ export function resolveManagedRoots({ env = process.env, platform = process.plat
       : paths.join(controlRoot, 'signing-agent') });
 }
 
+/**
+ * Where a gate run keeps evidence that must not live in the repository (failing scans' complete output, the direct executor's
+ * diagnostics): RIGHTKIT_SCRATCH_ROOT, else `<data root>/runs`. A managed Mac or Windows host has a data root, and so does any host
+ * that names one in the environment. A direct (Linux and other) host with none used to fall to the Mac data volume,
+ * `/Volumes/D/.rightkit-managed/runs`, and create it; its data root now defaults to the account's own state directory
+ * (resolveManagedRoots: `~/.local/state/rightkit`), beside the snapshots and the build-ownership record, so its runs are `~/.local/state/rightkit/runs`.
+ */
+export function gateRunsRoot({ env = process.env, platform = process.platform, home = homedir() } = {}) {
+  if (env.RIGHTKIT_SCRATCH_ROOT) return env.RIGHTKIT_SCRATCH_ROOT;
+  return (platform === 'win32' ? win32 : posix).join(resolveManagedRoots({ env, platform, home }).dataRoot, 'runs');
+}
+
 export function managedControlCandidates(options = {}) {
   const platform = options.platform ?? process.platform;
   if (!['darwin', 'win32'].includes(platform)) {
     const env = options.env ?? process.env;
-    return [...new Set([options.controlRoot, env.RIGHTKIT_CONTROL_ROOT, options.dataRoot, env.RIGHTKIT_DATA_ROOT, env.RIGHTKIT_MANAGED_ROOT, env.RIGHTKIT_EXTERNAL_ROOT, options.clientRoot].filter(Boolean))];
+    return [...new Set([options.controlRoot, envNamed(env, 'CONTROL_ROOT'), options.dataRoot, envNamed(env, 'DATA_ROOT'), envNamed(env, 'MANAGED_ROOT'), envNamed(env, 'EXTERNAL_ROOT'), options.clientRoot].filter(Boolean))];
   }
   const roots = resolveManagedRoots(options);
   return [...new Set([roots.controlRoot, roots.dataRoot, options.clientRoot, roots.legacyRoot].filter(Boolean))];
 }
 
-export function discoverBrokerSocket(env = process.env, { exists = existsSync, ...options } = {}) {
-  if (typeof env.RIGHTKIT_BUILD_BROKER_SOCKET === 'string' && env.RIGHTKIT_BUILD_BROKER_SOCKET) return env.RIGHTKIT_BUILD_BROKER_SOCKET;
-  if ((options.platform ?? process.platform) === 'win32') return undefined;
-  for (const root of managedControlCandidates({ ...options, env })) {
+/** The pipe RustRight's installer enforces, and the pre-rename one still named by processes started before the cutover (which means the same broker). */
+export const CANONICAL_WINDOWS_PIPE = '\\\\.\\pipe\\rustright-broker';
+export const LEGACY_WINDOWS_PIPE = '\\\\.\\pipe\\rightkit-build-control';
+
+/** The `windowsPipe` an installed broker config names (config.json of the first candidate root that has a valid one); a pre-rename name maps to the canonical pipe; anything but `\\.\pipe\<name>` is ignored. */
+export function configuredWindowsPipe(roots, readFile = (file) => readFileSync(file, 'utf8')) {
+  for (const root of roots) {
+    let pipe;
+    try { pipe = JSON.parse(readFile(win32.join(root, 'config.json')))?.windowsPipe; } catch { continue; }
+    if (typeof pipe !== 'string' || !pipe.startsWith('\\\\.\\pipe\\')) continue;
+    const name = pipe.slice('\\\\.\\pipe\\'.length);
+    if (!name || /[\\/]/.test(name)) continue;
+    return pipe.toLowerCase() === LEGACY_WINDOWS_PIPE.toLowerCase() ? CANONICAL_WINDOWS_PIPE : pipe;
+  }
+  return undefined;
+}
+
+/**
+ * The broker endpoint, in RustRight's order (GB-63): an explicit `RUSTRIGHT_BUILD_BROKER_SOCKET` (else the legacy spelling) is authoritative (on Windows the pre-rename pipe means
+ * the canonical one); on Unix the first existing `broker.sock` among the candidate roots; on Windows there is no socket file but there is always an endpoint: the pipe the installed
+ * config names (a custom or migrated name is never ignored), else the canonical pipe, so a Windows shell with no environment still reaches the broker.
+ */
+export function discoverBrokerSocket(env = process.env, { exists = existsSync, readFile, ...options } = {}) {
+  const platform = options.platform ?? process.platform;
+  const explicit = envNamed(env, 'BUILD_BROKER_SOCKET');
+  if (explicit) return platform === 'win32' && explicit.toLowerCase() === LEGACY_WINDOWS_PIPE.toLowerCase() ? CANONICAL_WINDOWS_PIPE : explicit;
+  const candidates = managedControlCandidates({ ...options, env });
+  if (platform === 'win32') return configuredWindowsPipe(candidates, readFile) ?? CANONICAL_WINDOWS_PIPE;
+  for (const root of candidates) {
     const socket = posix.join(root, 'broker.sock');
     if (exists(socket)) return socket;
   }
   return undefined;
 }
+
+// The declared Linux broker route's variables (owner: managed-cargo.mjs, which imports this leaf module and so cannot be imported here; its names are spelled
+// once more because a cycle would break the leaf property broker-client.mjs relies on). The route is opt-in and declared explicitly, never inferred.
+const LINUX_DECLARATION = Object.freeze({ client: 'RIGHTKIT_LINUX_BROKER_CLIENT', socket: 'RIGHTKIT_LINUX_BROKER_SOCKET', sha256: 'RIGHTKIT_LINUX_BROKER_CLIENT_SHA256' });
+const sha256OfFile = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
+const declaredAbsolute = (value) => typeof value === 'string' && posix.isAbsolute(value) && !value.split('/').includes('..') && !value.includes('\0');
+
+/**
+ * The client of a Linux host's DECLARED broker route (RIGHTKIT_LINUX_BROKER_CLIENT / _SOCKET / _CLIENT_SHA256), which is the one client the gate's executor
+ * (managed-cargo resolveLinuxBrokerRoute) drives: the same variables, the same absolute-path rule, the same required SHA-256 pin, the same refusal of another named
+ * endpoint, and the executor's real path. A host that declared nothing stays direct and has no client (undefined, as before); a declaration that is incomplete,
+ * names a client that is absent, is not the pinned bytes, or sits beside another endpoint also yields undefined here, never a different client: the typed refusal
+ * (RK_LINUX_BROKER_UNAVAILABLE, with its reason) is the executor's. The owner-and-writability walk of the path is the executor's too; this lookup is for callers
+ * that only need to find the client the declared route uses, and anything that RUNS a scan or a build goes through the executor's validated `client`.
+ * A RustRight client on PATH, a shim directory or a managed root never makes a Linux host a broker host.
+ */
+function declaredLinuxBrokerClient(env, exists, { realpath = (file) => realpathSync.native(file), digest = sha256OfFile } = {}) {
+  const named = (name) => (typeof env?.[name] === 'string' ? env[name] : undefined);
+  if (!Object.values(LINUX_DECLARATION).some((name) => named(name) !== undefined)) return undefined;
+  const client = named(LINUX_DECLARATION.client); const socket = named(LINUX_DECLARATION.socket); const pinned = named(LINUX_DECLARATION.sha256);
+  if (!declaredAbsolute(client) || !declaredAbsolute(socket) || !/^[0-9a-f]{64}$/i.test(pinned ?? '') || !exists(client)) return undefined;
+  const real = (file) => { try { return realpath(file); } catch { return file; } };
+  for (const other of ['RUSTRIGHT_BUILD_BROKER_SOCKET', 'RIGHTKIT_BUILD_BROKER_SOCKET']) {
+    const value = named(other);
+    if (value !== undefined && value !== '' && value !== socket && real(value) !== real(socket)) return undefined; // two endpoints: ambiguous, so none
+  }
+  const resolved = real(client);
+  try { if (digest(resolved).toLowerCase() !== pinned.toLowerCase()) return undefined; } catch { return undefined; }
+  return resolved;
+}
+
+/**
+ * The installed RustRight client, selected in ONE order everywhere (doctor, carry, status, lease and dispatch all call this): the live runtime at its final RustRight path
+ * (`<runtimeRoot>/runtime`), the control root's `runtime` (the shared fixtures' `runtimeCurrent`), and only then the legacy `runtime-current` link of a host not yet cut over. The
+ * Windows client is the native `rustright.exe`, never a `.cmd` shim; the caller probes the exact client returned before it marks any work (snapshot-broker.mjs clientStartable).
+ */
+export function managedRuntimeClient(env = process.env, platform = process.platform, exists = existsSync, ops = {}) {
+  if (platform !== 'darwin' && platform !== 'win32') return declaredLinuxBrokerClient(env, exists, ops); // a direct (Linux) host has a broker client only by declaring one
+  const paths = platform === 'win32' ? path.win32 : path.posix;
+  const exe = platform === 'win32' ? 'rustright.exe' : 'rustright';
+  const home = env.HOME || env.USERPROFILE || homedir();
+  const roots = managedControlCandidates({ env, platform, home });
+  const configured = resolveManagedRoots({ env, platform, home });
+  const ordered = [paths.join(configured.liveRuntime, exe)];
+  for (const root of roots) ordered.push(paths.join(root, 'runtime', exe));
+  for (const root of roots) ordered.push(paths.join(root, 'runtime-current', exe)); // the pre-cutover link: last, never preferred over the live runtime
+  if (platform === 'darwin') {
+    ordered.push(path.posix.join(home, 'Library', 'Application Support', 'RustRight', 'runtime', 'rustright'));
+    // Broker-managed HOME may point at a build home; the installed native client belongs to the OS account.
+    ordered.push(path.posix.join(userInfo().homedir, 'Library', 'Application Support', 'RustRight', 'runtime', 'rustright'));
+  } else {
+    for (const root of roots) ordered.push(path.win32.join(path.win32.parse(root).root, '.rustright', 'runtime', 'rustright.exe'));
+  }
+  return ordered.find((client) => exists(client));
+}

package/media-sidecar-catalog.mjs

@@ -10,7 +10,7 @@ import { runCargoSync } from "./managed-cargo.mjs";
 const invalid = (code, message) => Object.assign(new Error(message), { code });
 
 export function cargoFfmpegCrate(manifestPath, { run = runCargoSync } = {}) {
-  const result = run(["metadata", "--offline", "--format-version", "1", "--manifest-path", manifestPath], {
+  const result = run(["metadata", "--frozen", "--format-version", "1", "--manifest-path", manifestPath], {
     cwd: path.dirname(manifestPath),
     encoding: "utf8",
     maxBuffer: 256 * 1024 * 1024,