@rightkit/release 0.6.16 → 0.6.21

package/bin/rightkit-linux-setup.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// rightkit-linux-setup [--root <app>] [--dry-run]: provision a Linux host (cloud container, VM, WSL2) for `rightkit-host-gate`.
+import { spawnSync } from "../background-process.mjs";
+import { setup } from "../linux-setup.mjs";
+
+const args = process.argv.slice(2);
+if (args.includes("--version")) { console.log("rightkit-linux-setup (@rightkit/release)"); process.exit(0); }
+if (process.platform !== "linux") { console.error("rightkit-linux-setup runs on Linux only"); process.exit(2); }
+const at = args.indexOf("--root");
+const run = (cmd, a, o) => spawnSync(cmd, a, { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"], ...o });
+const fetchText = (url) => { const r = run("curl", ["-fsSL", url]); if (r.status !== 0) throw new Error(`fetch ${url} failed`); return r.stdout; };
+try {
+  const r = setup({ root: at >= 0 ? args[at + 1] : process.cwd(), run, fetchText, dryRun: args.includes("--dry-run"), log: (m) => console.error(`[linux-setup] ${m}`) });
+  if (args.includes("--dry-run")) console.log(r.steps.join("\n"));
+} catch (e) { console.error(`rightkit-linux-setup: ${e.message}`); process.exit(1); }

package/broker-admission.mjs

@@ -0,0 +1,184 @@
+// The live place of a carried scan in the broker's queue (rightkit#1367 step 2).
+//
+// The broker, not the gate, decides how many builds run (Adrian, 2026-11-01), so a carried scan can wait in the broker's queue. That wait is not the
+// scan's own run, so the scan's run limit is a stopwatch that does not tick while the broker holds every request of the scan QUEUED. The gate asks the
+// broker (`rustright status <id>`: BROKER-CONTRACT BR7 reports live broker state in every status answer, state QUEUED until a permit is held, then RUNNING)
+// about the requests the scan has made. It gives queue time no allowance of its own: how long a job may stay queued is the broker's rule (BR7 reports a queued job past
+// its deadline with the holder that blocks it). The one bound the gate does add is a wall-clock ceiling (QUEUED_CEILING_FACTOR x the scan's limit) that is not a build
+// count: a safety stop for a wedged broker queue (the broker's job deadlines are off by default, so nothing else would end a scan stuck QUEUED).
+//
+// What the client does not offer: its operation deadline (RUSTRIGHT_OPERATION_DEADLINE_MS, client.rs, BROKER-CONTRACT GB-52) is an absolute deadline from the
+// client's start, so it would charge queue time to the scan. A watched scan therefore sends no operation deadline; at the end of its own run time the gate
+// cancels the requests by id (`rustright cancel <id>`) and stops the process tree only after a short grace.
+//
+// Fail closed: a request the gate cannot read (no request id yet, a status that fails or is malformed, a state other than QUEUED) is counted as running, so
+// an unreadable broker never makes a scan immortal.
+import fs from "node:fs";
+import { spawnBrokerClient } from "./broker-client.mjs";
+import { diagnoseControlReply } from "./broker-wire.mjs";
+import { readRequestRef } from "./snapshot-request.mjs";
+
+/** How long a cancelled carried scan may take to end by itself before its process tree is stopped. */
+export const CARRIED_CANCEL_GRACE_MS = 15_000;
+/** How often the gate asks the broker for the state of its requests (the first read comes after 1 s, then every 5 s). */
+export const ADMISSION_POLL_MS = 5_000;
+const FIRST_POLL_MS = 1_000;
+/** How many `rustright status` reads the gate has in flight at once, however many scans it watches. */
+export const STATUS_POLL_CONCURRENCY = 2;
+/**
+ * A watched scan is stopped when its WALL-CLOCK time (run time plus queue time) reaches its own run limit times this factor. It is a safety stop for a wedged broker queue,
+ * not a count: the broker decides how many builds run and in what order, and its job deadlines are off by default, so without this a scan stuck QUEUED would wait forever.
+ */
+export const QUEUED_CEILING_FACTOR = 4;
+
+/**
+ * A run stopwatch: `onExpire` fires once, when `limitMs` of RUNNING time has passed. `pause()` stops it (the scan is queued at the broker) and `resume()`
+ * restarts it with the time left; `stop()` ends it for good. Time spent paused is `queuedMs`.
+ * With `ceilingMs` (a wall-clock bound that includes the paused time) `onCeiling` fires once when it passes before the stopwatch expired or stopped, and `ceilingHit` is true.
+ */
+export function createRunClock({ limitMs, onExpire, ceilingMs = null, onCeiling = () => {}, setTimer = setTimeout, clearTimer = clearTimeout, now = Date.now }) {
+  let remaining = Math.max(0, Number(limitMs) || 0);
+  let handle = null; let since = 0; let pausedAt = null; let ceilingHandle = null;
+  let expired = false; let stopped = false; let queuedMs = 0; let ceilingHit = false;
+  const clearCeiling = () => { if (ceilingHandle !== null) { clearTimer(ceilingHandle); ceilingHandle = null; } };
+  const arm = () => {
+    since = now();
+    handle = setTimer(() => { handle = null; expired = true; clearCeiling(); onExpire(); }, remaining);
+  };
+  arm();
+  if (ceilingMs !== null && Number.isFinite(ceilingMs) && ceilingMs > 0) {
+    ceilingHandle = setTimer(() => {
+      ceilingHandle = null;
+      if (stopped || expired) return;
+      ceilingHit = true; expired = true;
+      if (handle !== null) { clearTimer(handle); handle = null; }
+      if (pausedAt !== null) { queuedMs += now() - pausedAt; pausedAt = null; }
+      onCeiling();
+    }, ceilingMs);
+    ceilingHandle?.unref?.();
+  }
+  return {
+    pause() { if (stopped || expired || handle === null) return; clearTimer(handle); handle = null; remaining = Math.max(0, remaining - (now() - since)); pausedAt = now(); },
+    resume() { if (stopped || expired || handle !== null) return; if (pausedAt !== null) { queuedMs += now() - pausedAt; pausedAt = null; } arm(); },
+    stop() { if (handle !== null) { clearTimer(handle); handle = null; } clearCeiling(); if (pausedAt !== null) { queuedMs += now() - pausedAt; pausedAt = null; } stopped = true; },
+    get expired() { return expired; },
+    get ceilingHit() { return ceilingHit; },
+    get queuedMs() { return queuedMs + (pausedAt !== null ? now() - pausedAt : 0); },
+    get running() { return handle !== null; },
+    get remainingMs() { return handle !== null ? Math.max(0, remaining - (now() - since)) : remaining; },
+  };
+}
+
+/** The live state word (`QUEUED`, `RUNNING`, ...) of one `rustright status` reply, or null when it is not a valid STATUS of this request. */
+export function brokerStateOf(stdout, requestId) {
+  let doc;
+  try { doc = JSON.parse(String(stdout)); } catch { return null; }
+  const diagnosis = diagnoseControlReply(doc, requestId);
+  return diagnosis.kind === "live" || diagnosis.kind === "terminal" ? diagnosis.state : null;
+}
+
+/**
+ * The gate's reader of the broker's live state, through the RustRight client with an ASYNCHRONOUS spawn (nothing here blocks the gate's event loop):
+ * `state(id)` is the request's state word or null; `cancel(id)` is `rustright cancel <id>`.
+ */
+export function createBrokerLive({ client, env = process.env, spawn, platform = process.platform }) {
+  const call = async (args) => {
+    try {
+      const r = await spawnBrokerClient(spawn, client, args, { encoding: "utf8", env, timeout: 30_000, maxBuffer: 1 << 24, windowsHide: true }, { platform });
+      return r && !r.error ? r : null;
+    } catch { return null; }
+  };
+  return {
+    async state(requestId) { const r = await call(["status", requestId]); return r ? brokerStateOf(r.stdout, requestId) : null; },
+    async cancel(requestId) { await call(["cancel", requestId]); },
+  };
+}
+
+/** The request ids the reference files name (a file not written yet, or already removed, names none). */
+export function requestIdsOf(files) {
+  const ids = [];
+  for (const file of files) {
+    try { if (fs.existsSync(file)) ids.push(readRequestRef(file).requestId); } catch { /* not a complete reference yet */ }
+  }
+  return [...new Set(ids)];
+}
+
+/**
+ * ONE reader of the broker's live state per gate run, shared by every watched scan (rightkit#1367 step 2): a scan registers a member (`ids()` lists its request ids, `apply(states)` takes
+ * the answers) and the poller asks for each distinct id with at most `concurrency` reads in flight, the first read `firstMs` after the first member arrives and then every `intervalMs`
+ * while any member is registered. Passes never overlap. `pass(extra)` is one read pass (a member not registered can be passed in `extra`; tests use it). Status reads go to the client
+ * directly: they are not builds and are never recorded as such.
+ */
+export function createStatusPoller({ live, intervalMs = ADMISSION_POLL_MS, firstMs = Math.min(FIRST_POLL_MS, intervalMs), concurrency = STATUS_POLL_CONCURRENCY, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const members = new Set();
+  let timer = null; let tail = Promise.resolve(); let passes = 0;
+  const width = Math.max(1, Math.trunc(Number(concurrency)) || 1);
+  async function readAll(extra) {
+    const snapshot = [...new Set([...members, ...extra])];
+    const wanted = [...new Set(snapshot.flatMap((m) => m.ids()))];
+    const states = new Map();
+    const queue = [...wanted];
+    await Promise.all(Array.from({ length: Math.min(width, queue.length) }, async () => {
+      while (queue.length) {
+        const id = queue.shift();
+        states.set(id, await Promise.resolve().then(() => live.state(id)).catch(() => null));
+      }
+    }));
+    for (const member of snapshot) if (members.has(member) || extra.includes(member)) member.apply(member.ids().map((id) => (states.has(id) ? states.get(id) : null)));
+  }
+  function pass(extra = []) {
+    passes += 1;
+    const run = tail.then(() => readAll(extra));
+    tail = run.catch(() => {}).finally(() => { passes -= 1; });
+    return run;
+  }
+  const schedule = (ms) => {
+    timer = setTimer(() => { timer = null; pass().catch(() => {}).finally(() => { if (members.size > 0 && timer === null) schedule(intervalMs); }); }, ms);
+    timer?.unref?.();
+  };
+  return {
+    pass,
+    /** Resolves when the passes started so far have ended. */
+    idle: () => tail,
+    /** Adds a member; returns the function that removes it. The poller stops its own timer when no member is left. */
+    register(member) {
+      members.add(member);
+      if (timer === null && passes === 0) schedule(firstMs);
+      return () => { members.delete(member); if (members.size === 0 && timer !== null) { clearTimer(timer); timer = null; } };
+    },
+    get members() { return members.size; },
+  };
+}
+
+/**
+ * Watches the requests one scan makes and keeps its `clock` honest: paused while every request the scan has is QUEUED at the broker, running otherwise.
+ * `refFiles()` lists the request reference files (RUSTRIGHT_REQUEST_ID_FILE, written by the client at submit) the scan's carried calls have; `live` is a
+ * createBrokerLive (or any object with `state(id)` and `cancel(id)`). The reads come from a shared `poller` (createStatusPoller, one per gate run); with none a private one is made
+ * from `live`. `poll()` is one pass (tests call it directly) and resolves to this scan's states; `start()` registers with the poller until `stop()`.
+ * `cancelKnown()` cancels, by id, every request seen so far.
+ */
+export function watchBrokerAdmission({ clock, refFiles, live, poller = null, intervalMs = ADMISSION_POLL_MS, firstMs = Math.min(FIRST_POLL_MS, intervalMs), setTimer = setTimeout, clearTimer = clearTimeout }) {
+  let stopped = false; let unregister = null; let last = [];
+  const known = new Set();
+  const own = poller ?? createStatusPoller({ live, intervalMs, firstMs, setTimer, clearTimer });
+  const member = {
+    ids() { const ids = requestIdsOf(refFiles()); for (const id of ids) known.add(id); return ids; },
+    apply(states) {
+      last = states;
+      if (stopped) return;
+      if (states.length === 0) { clock.resume(); return; }
+      if (states.every((state) => state === "QUEUED")) clock.pause(); else clock.resume();
+    },
+  };
+  return {
+    async poll() { if (stopped) return null; await own.pass([member]); return last; },
+    done: () => own.idle(),
+    start() { if (!stopped && unregister === null) unregister = own.register(member); },
+    stop() { stopped = true; if (unregister) { unregister(); unregister = null; } },
+    known: () => [...known],
+    async cancelKnown() {
+      for (const id of requestIdsOf(refFiles())) known.add(id);
+      await Promise.allSettled([...known].map((id) => live.cancel(id)));
+    },
+  };
+}

package/broker-wire.mjs

@@ -33,11 +33,22 @@ export function overCapProblem(event) {
   return null;
 }
 
+/** The broker's event types are upper-case words (`RESULT`, `JOB_EVENT`, `FRAME_OVER_CAP`, ...). */
+const PROTOCOL_TYPE = /^[A-Z][A-Z0-9_]*$/;
+
+/** Whether one line body is a broker protocol frame: a JSON object whose `type` is a protocol event type. */
+function isProtocolFrame(body) {
+  try {
+    const value = JSON.parse(body);
+    return value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.type === "string" && PROTOCOL_TYPE.test(value.type);
+  } catch { return false; }
+}
+
 /**
  * Parses captured client output as RustRight's client reads the wire: every complete newline-terminated frame is drained and checked against the limit FIRST, and
  * only then is the one incomplete frame still waiting for its newline bounded (a frame already at the limit without a newline cannot fit it). A limit-sized frame
  * followed by the start of the next one in the same read is valid. Returns `{ frames: [text], overCap: [event], error: string | null }`; lines that are not JSON
- * objects (cargo's own output) are kept as frames and never judged.
+ * objects with a protocol `type` (cargo's own output, JSON included) are kept as frames and never judged.
  */
 export function drainFrames(text, limit = MAX_BROKER_LINE_BYTES) {
   const frames = []; const overCap = [];
@@ -47,8 +58,9 @@ export function drainFrames(text, limit = MAX_BROKER_LINE_BYTES) {
     if (at < 0) break;
     const line = rest.subarray(0, at + 1);
     rest = rest.subarray(at + 1);
-    const protocolLike = line[0] === 0x7b; // `{`: a protocol frame; a tool's own long output line is not a wire frame and is never judged here
-    if (protocolLike && line.length > limit) return { frames, overCap, error: `a frame of ${line.length} bytes (newline included) exceeds the ${limit}-byte limit` };
+    // Only a protocol frame is judged: a JSON object whose `type` names a protocol event. A tool's own output line is never a wire frame, even when it is
+    // JSON: `cargo metadata` prints its whole document as one `{"packages":...}` line, megabytes on a large workspace (rightkit#1351).
+    if (line.length > limit && line[0] === 0x7b && isProtocolFrame(line.subarray(0, line.length - 1).toString("utf8"))) return { frames, overCap, error: `a frame of ${line.length} bytes (newline included) exceeds the ${limit}-byte limit` };
     const body = line.subarray(0, line.length - 1).toString("utf8");
     frames.push(body);
     if (body.startsWith("{")) { try { const event = JSON.parse(body); if (overCapProblem(event)) overCap.push(event); } catch { /* not a protocol frame */ } }

package/build-launch.mjs

@@ -41,6 +41,7 @@ import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveExecutor } from "./gate-executor.mjs";
+import { gateNoBroker } from "./managed-cargo.mjs";
 import { resolveExecutable } from "./admission-host.mjs";
 import { CARRIED_CARGO_MAP_ENV as CARRIED_MAP_ENV, carriedCargoMapOf, runCarriedAdapter } from "./carried-cargo.mjs";
 import { spawnSync } from "./background-process.mjs";
@@ -176,7 +177,9 @@ export function buildLaunch(command, args = [], host = {}) {
   const lookup = (cmd) => { const found = resolveExecutable(cmd, { env, hostPlatform: platform, exists: exists ?? (() => false) }); return found ? [found] : []; };
   // A snapshot stage never installs into the snapshot (the gate did): the step is a logged no-op, on every host.
   if (snapshotInstallSkip(command, args, env)) return { command: process.execPath, args: [CARRIED_ADAPTER_RUN, "--skip-install", ...args.map(String)] };
-  const executor = resolveExecutor({ env, platform, exists, which: host.which ?? lookup, readFile: host.readFile ?? ((file) => readFileSync(file, "utf8")) });
+  // Inside a gate run outside the broker by Adrian's recorded exception (managed-cargo.mjs NO_BROKER_ENV, set only for that live door run's
+  // children), a child step (web-build's tsc, a native helper) takes the same direct route as the gate's own cargo children, not a refusal.
+  const executor = resolveExecutor({ env, platform, exists, which: host.which ?? lookup, readFile: host.readFile ?? ((file) => readFileSync(file, "utf8")), forceDirect: gateNoBroker(env) });
   if (executor.kind === "refuse") refuse(`${name(command)} ${args.join(" ")}: ${executor.problem}`);
   // A direct (Linux) host: the real toolchain, RustRight shim directories off PATH (`env`, to merge into the launch env); a configured
   // `rustright cargo|rustc|rustdoc …` runs that tool directly; any other `rustright` command has no direct form and is refused.

package/build-ownership.mjs

@@ -1,10 +1,12 @@
-// Host-wide build ownership (docs/GATE-CONTRACT.md §1 "Commit-only build", "Broker lease"; joint plan step 4, G1).
+// Per-repository build ownership (docs/GATE-CONTRACT.md §1 "Commit-only build", "Broker lease"; joint plan step 4, G1; rightkit#1367).
 //
-// The gate acquires the host's build ownership BEFORE it syncs a snapshot and holds it until the stage completes, so no other
-// request can replace a snapshot while anything reads it. One owner per host, at ONE fixed location per host (`ownershipFile`:
-// `<managed root>/build-ownership/owner.json` on Mac & Dell, `~/.local/state/rightkit/build-ownership/owner.json` on Linux), never
-// derived from the snapshot root or from an environment variable: builds are one per host, and the snapshot's own sync lock only
-// covers the sync itself. The directory is mode 0700 and refused when group- or other-accessible (`ensureOwnershipDir`).
+// The gate acquires the build ownership of the repository it is building BEFORE it syncs that repository's snapshot and holds it
+// until the stage completes, so no other request can replace that snapshot while anything reads it. One owner per repository, at
+// one fixed location per repository (`ownershipFile`: `<managed root>/build-ownership/<repository key>/owner.json` on Mac & Dell,
+// `~/.local/state/rightkit/build-ownership/<repository key>/owner.json` on Linux), where the key is the snapshot directory's own
+// key (`snapshot.repositoryOf(root).key`); never derived from the snapshot root or from an environment variable. Two repositories
+// never contend: how many builds run, and in what order, is the broker's alone. The snapshot's own sync lock only covers the sync
+// itself. `build-ownership/` and each repository directory are mode 0700 and refused when group- or other-accessible (`ensureOwnershipDir`).
 //
 // The owner record is written whole (create-exclusive) and names a fresh handle (the `ownership.handle` a broker request carries),
 // the gate's pid & start identity, the stage, snapshot & commit, how the gate's children are contained, and whether a broker
@@ -93,31 +95,36 @@ const sameStart = (a, b) => Number.isFinite(a) && Number.isFinite(b) && Math.abs
 /** The directory beside the host's snapshots (or beside any injected root) that holds the owner record. */
 export const OWNERSHIP_DIRNAME = "build-ownership";
 
+/** A repository key is one path segment: the snapshot directory's name (a hex digest), never a path. */
+const REPOSITORY_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
 /**
- * Where the host's one owner record lives (GC:24 "the host's build ownership"; GC:52 "host-wide build ownership"; item 5 row 5.17):
- * ONE fixed location per host, independent of the snapshot root and of every environment variable. Two gates whose environments
- * choose different snapshot roots (XDG_STATE_HOME, a configured root) must still contend for one record, so nothing here reads
- * `process.env`, and nothing derives from where snapshots live.
- *   Mac & Dell: `<managed root>/build-ownership/owner.json` (the host's fixed managed root, `/Volumes/D/.rightkit-managed`,
- *     `D:\.rightkit-managed`).
- *   Linux (WSL2 included): `<account home>/.local/state/rightkit/build-ownership/owner.json`, the account home taken from the
- *     passwd database (`os.userInfo()`), never from $HOME.
- * `home` replaces the Linux account home and `beside` replaces the whole location (`<dirname(beside)>/build-ownership/owner.json`);
+ * Where a repository's owner record lives (GC:24 "the repository's build ownership"; item 5 row 5.17): ONE fixed location per
+ * repository, independent of the snapshot root and of every environment variable. Two gates for the same repository whose
+ * environments choose different snapshot roots (XDG_STATE_HOME, a configured root) must still contend for one record, so nothing
+ * here reads `process.env`, and nothing derives from where snapshots live. The only input besides the platform is `repository`,
+ * the repository key the snapshot directory uses (`snapshot.repositoryOf(root).key`); it is required.
+ *   Mac & Dell: `<managed root>/build-ownership/<repository key>/owner.json` (the host's fixed managed root,
+ *     `/Volumes/D/.rightkit-managed`, `D:\.rightkit-managed`).
+ *   Linux (WSL2 included): `<account home>/.local/state/rightkit/build-ownership/<repository key>/owner.json`, the account home
+ *     taken from the passwd database (`os.userInfo()`), never from $HOME.
+ * `home` replaces the Linux account home and `beside` replaces the whole location (`<dirname(beside)>/build-ownership/<key>/owner.json`);
  * both are injection points for fixtures and tests only. A production caller passes neither: the root a caller derived from the
  * environment must never be passed as `beside`, because that is the defect this row removes.
  */
-export function ownershipFile({ platform = process.platform, home, beside } = {}) {
+export function ownershipFile({ platform = process.platform, home, beside, repository } = {}) {
+  if (typeof repository !== "string" || !REPOSITORY_KEY.test(repository)) throw new TypeError(`ownershipFile: repository must be the repository key (one path segment), not ${JSON.stringify(repository)}`);
   const paths = platform === "win32" ? path.win32 : path.posix;
   if (beside !== undefined) {
     if (typeof beside !== "string" || beside === "") throw new TypeError(`ownershipFile: beside must be a path (${JSON.stringify(beside)})`);
-    return paths.join(paths.dirname(beside), OWNERSHIP_DIRNAME, "owner.json");
+    return paths.join(paths.dirname(beside), OWNERSHIP_DIRNAME, repository, "owner.json");
   }
-  if (platform === "darwin" || platform === "win32") return paths.join(resolveManagedRoots({ env: {}, platform, home: "" }).dataRoot, OWNERSHIP_DIRNAME, "owner.json");
+  if (platform === "darwin" || platform === "win32") return paths.join(resolveManagedRoots({ env: {}, platform, home: "" }).dataRoot, OWNERSHIP_DIRNAME, repository, "owner.json");
   let base = home;
   if (base === undefined) {
-    try { base = os.userInfo().homedir; } catch (e) { throw new OwnershipBusy(`build ownership: this account's home directory cannot be read (${e.message}), so the host's owner record has no location`); }
+    try { base = os.userInfo().homedir; } catch (e) { throw new OwnershipBusy(`build ownership: this account's home directory cannot be read (${e.message}), so the repository's owner record has no location`); }
   }
-  return paths.join(base, ".local", "state", "rightkit", OWNERSHIP_DIRNAME, "owner.json");
+  return paths.join(base, ".local", "state", "rightkit", OWNERSHIP_DIRNAME, repository, "owner.json");
 }
 
 /**
@@ -140,13 +147,15 @@ function guardManagedRoot(file, { platform, managedRoot, device }) {
 }
 
 /**
- * Creates the ownership directory mode 0700 (one level on Mac & Dell) and refuses an existing POSIX one that grants group or other access (item 5 row 5.22):
+ * Creates the ownership directory mode 0700 (one level per directory on Mac & Dell) and refuses an existing POSIX one that grants group or other access (item 5 row 5.22):
  * another user's unreadable process is skipped by the nets on the premise that it cannot read this user's managed root, and a
  * directory other users could write would let them forge or remove the record. Windows has no mode bits; its directory ACL is the
  * same trust the record itself has.
  */
 export function ensureOwnershipDir(dir, { platform = process.platform } = {}) {
-  // Mac & Dell: exactly ONE level, `build-ownership/` inside a managed root that already exists (decision D4: the gate never
+  // A repository directory sits inside `build-ownership/`, which gets the same mode rules (created first, then checked).
+  if (path.basename(path.dirname(dir)) === OWNERSHIP_DIRNAME) ensureOwnershipDir(path.dirname(dir), { platform });
+  // Mac & Dell: exactly ONE level per call, `build-ownership/` (then `<key>/`) inside a managed root that already exists (decision D4: the gate never
   // creates the managed root, and a recursive creation here would). Linux: the durable state directory under the account home is
   // created whole (GC:63).
   if (platform === "linux") fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -406,7 +415,7 @@ export function classifyHiddenProcesses({ procs, own = new Set(), uid, owner, re
  * The host's process facts the ownership rules rely on. Each answer is a fact or a throw; a throw means "unknown" and the
  * caller treats it as busy.
  */
-export function processProbe({ platform = process.platform, spawn = spawnSync, spawnHolder = spawnDetachedDefault, kill = process.kill.bind(process), readFile = fs.readFileSync, readdir = fs.readdirSync, readlink = fs.readlinkSync, exists: procExists = fs.existsSync, proc = "/proc", uid = process.getuid?.() } = {}) {
+export function processProbe({ platform = process.platform, spawn = spawnSync, spawnHolder = spawnDetachedDefault, kill = process.kill.bind(process), readFile = fs.readFileSync, readdir = fs.readdirSync, readlink = fs.readlinkSync, exists: procExists = fs.existsSync, proc = "/proc", uid = process.getuid?.(), sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) } = {}) {
   const exists = (pid) => {
     try { kill(pid, 0); return true; } catch (e) { if (e.code === "ESRCH") return false; if (e.code === "EPERM") return true; throw e; }
   };
@@ -556,6 +565,24 @@ export function processProbe({ platform = process.platform, spawn = spawnSync, s
     if (startMs + START_SLACK_MS < skipBefore) return;
     throw unknown(`it started at ${new Date(startMs).toISOString()}, not before the baseline ${new Date(skipBefore).toISOString()} (the later of the last clean release's acquisition and the snapshot root's birth, else this ownership's own acquisition)`);
   };
+  // A process in the middle of execve is briefly non-dumpable (its new address space has no dumpable flag until the exec commits), so
+  // /proc/<pid>/{environ,cwd,fd,...} answer EACCES for a few milliseconds while its comm is still the parent's (`node-MainThread`)
+  // and its start is the fork's. Under concurrent test shards or any busy host, a scan meets such a process: it is no reader and not
+  // unknown, only not yet readable. So a read that would HOLD (a young, unreadable, live process of this user) is retried, bounded
+  // (SETTLE_TRIES x SETTLE_MS), before the hold stands; a process that stays unreadable (really non-dumpable) is held exactly as
+  // before, and a process that is old, gone, a zombie or another user's is judged at once, with no wait.
+  const SETTLE_TRIES = 20; const SETTLE_MS = 25;
+  /** `{ value }` of `op`, or `{ skipped: true }` when its failure is a process no reader (`unreadable` returned); throws what `unreadable` throws once the retries are spent. */
+  const settled = (pid, skipBefore, op) => {
+    for (let attempt = 0; ; attempt++) {
+      try { return { value: op() }; }
+      catch (e) {
+        if (!GONE.has(e.code) && !["EACCES", "EPERM"].includes(e.code)) throw e;
+        try { unreadable(pid, e, skipBefore); return { skipped: true }; }
+        catch (held) { if (attempt >= SETTLE_TRIES) throw held; sleep(SETTLE_MS); }
+      }
+    }
+  };
   return {
     platform,
     /** `{ alive, startedMs, group }` from `ps` (C locale). */
@@ -600,8 +627,9 @@ export function processProbe({ platform = process.platform, spawn = spawnSync, s
         const needle = Buffer.from(`${token}\0`);
         const found = [];
         for (const pid of procPids()) {
-          let environ;
-          try { environ = readFile(`${proc}/${pid}/environ`); } catch (e) { unreadable(pid, e, skipBefore); continue; }
+          const got = settled(pid, skipBefore, () => readFile(`${proc}/${pid}/environ`));
+          if (got.skipped) continue;
+          const environ = got.value;
           if (Buffer.concat([environ, Buffer.from("\0")]).includes(needle)) found.push(pid);
         }
         return found;
@@ -694,7 +722,7 @@ export function processProbe({ platform = process.platform, spawn = spawnSync, s
         const targetOf = (file) => { try { return readlink(file); } catch (e) { if (GONE.has(e.code)) return null; throw e; } };
         for (const pid of procPids()) {
           if (own.has(pid)) continue;
-          try {
+          settled(pid, skipBefore, () => {
             for (const [link, how] of [["cwd", "working directory"], ["root", "root directory"], ["exe", "executable"]]) {
               const target = targetOf(`${proc}/${pid}/${link}`);
               if (target !== null && inside(target)) { add(pid, how); break; }
@@ -711,7 +739,7 @@ export function processProbe({ platform = process.platform, spawn = spawnSync, s
               let cmdline = ""; try { cmdline = String(readFile(`${proc}/${pid}/cmdline`, "utf8")); } catch (e) { if (!GONE.has(e.code)) throw e; }
               if (named(cmdline)) add(pid, "argument");
             }
-          } catch (e) { unreadable(pid, e, skipBefore); }
+          });
         }
         return found;
       }
@@ -755,7 +783,10 @@ export function spawnUnderOwnership(spawn, command, args, options = {}, { env =
   const handle = env[OWNERSHIP_ENV] ?? options?.env?.[OWNERSHIP_ENV];
   if (!options?.detached || platform === "win32" || !handle) return spawn(command, args, options);
   const merged = { ...(options.env ?? {}), ...env };
-  const dir = childrenDir(merged[OWNERSHIP_FILE_ENV] || ownershipFile({ platform }), handle);
+  // The handle names a per-repository record: its file variable is required, and there is no host-wide default to fall back to.
+  const ownedFile = merged[OWNERSHIP_FILE_ENV];
+  if (!ownedFile) throw new OwnershipBusy(`build ownership: ${OWNERSHIP_ENV} is set but ${OWNERSHIP_FILE_ENV} is not, so the repository's ownership record is unknown and the detached child is not started`);
+  const dir = childrenDir(ownedFile, handle);
   try { fs.mkdirSync(dir, { mode: 0o700 }); } catch (e) { if (e.code !== "EEXIST") throw e; } // the ownership directory exists while this gate holds it
   const intent = path.join(dir, `intent-${process.pid}-${crypto.randomUUID()}.json`);
   // The child's start lower bound is taken BEFORE it is created, so however long this process pauses before recording the
@@ -830,13 +861,13 @@ export function readRootBirth(root, bootId) {
  * reclaim, never a nested gate), before this sync's first write, its snapshots are deleted and the root is born anew, with this
  * boot's identity. Why that is sound: after a reboot no process of the old boot is alive, so the old root has no live readers; a
  * free host proves there is no current owner; and the fresh birth makes the strict rule apply only to processes that started after
- * it. Refused (the root stays as it was, strict) when: this process does not hold the only record, or the record is not a free-host
+ * it. Only this repository's own entries are deleted (see the body). Refused (the root stays as it was, strict) when: this process does not hold the only record, or the record is not a free-host
  * acquisition; this boot's identity cannot be read; the root is missing or is a link (a missing root is born by the sync); its birth
  * record is unreadable, or names THIS boot; or anything in the root is not a snapshot artifact (`<16 hex>`, `<16 hex>.lock`,
  * `.state.json`, `.staging`, or the birth record), because a root that is some other directory is never emptied.
  * Returns `{ migrated, why }`.
  */
-export function migrateBirthlessRoot(root, { env = process.env, file = env[OWNERSHIP_FILE_ENV], bootId = hostBootId() } = {}) {
+export function migrateBirthlessRoot(root, { env = process.env, file = env[OWNERSHIP_FILE_ENV], bootId = hostBootId(), hooks = {} } = {}) {
   const no = (why) => ({ migrated: false, why });
   const handle = env[OWNERSHIP_ENV];
   if (!handle || !file) return no("this process holds no build ownership");
@@ -857,9 +888,45 @@ export function migrateBirthlessRoot(root, { env = process.env, file = env[OWNER
   const birthName = path.basename(rootBirthFile(root));
   const stranger = entries.find((n) => n !== birthName && !/^[0-9a-f]{16}(\.[A-Za-z0-9._-]+)?$/.test(n));
   if (stranger !== undefined) return no(`${JSON.stringify(stranger)} in the root is not a snapshot artifact`);
-  try { for (const n of entries) fs.rmSync(path.join(root, n), { recursive: true, force: true }); }
-  catch (e) { return no(`the root could not be emptied (${e.code ?? e.message}); it stays without a baseline`); }
-  return recordRootBirth(root, { bootId }) ? { migrated: true, why: `${reason}; its snapshots were deleted and it was born anew in this boot` } : no("the new birth could not be recorded");
+  // The root is shared by every repository, and a free host for THIS repository says nothing about another one. So this
+  // migration removes only THIS repository's own entries (`<key>` and `<key>.*`: the lock, the state file, the staging directory)
+  // and never another repository's, under any condition: a second repository can take its snapshot between any check made here
+  // and any delete, so no check can make a cross-repository delete safe. The root's birth is written only while no other
+  // repository holds or reclaims ownership (a decision, checked again right before the write); otherwise the root stays without a
+  // baseline and strict. Another repository's snapshots in the root are left to that repository's own migration.
+  const mine = path.basename(path.dirname(file));
+  const others = otherHolder(file);
+  if (others) return no(others);
+  hooks.afterHolderCheck?.();
+  const own = entries.filter((n) => n === mine || n.startsWith(`${mine}.`));
+  try { for (const n of own) fs.rmSync(path.join(root, n), { recursive: true, force: true }); }
+  catch (e) { return no(`this repository's snapshot could not be removed (${e.code ?? e.message}); the root stays without a baseline`); }
+  const late = otherHolder(file);
+  if (late) return no(`${late}; this repository's snapshot entries were removed and the root's birth was not written`);
+  if (fs.existsSync(rootBirthFile(root))) { try { fs.rmSync(rootBirthFile(root), { force: true }); } catch (e) { return no(`the old birth record could not be replaced (${e.code ?? e.message})`); } }
+  return recordRootBirth(root, { bootId }) ? { migrated: true, why: `${reason}; this repository's snapshot (${own.length} entr${own.length === 1 ? "y" : "ies"}) was deleted and the root was born anew in this boot` } : no("the new birth could not be recorded");
+}
+
+/**
+ * Whether anything other than the repository owning `file` holds build ownership or is reclaiming it: another repository's owner
+ * record or standing reclaim claim, or an older gate's host-wide `build-ownership/owner.json` (which holds EVERY repository, live or
+ * not). Returns the reason, or null. A listing or read failure is a reason (fail closed).
+ */
+function otherHolder(file) {
+  try {
+    const parent = path.dirname(path.dirname(file)); const mine = path.basename(path.dirname(file));
+    for (const d of fs.readdirSync(parent, { withFileTypes: true })) {
+      if (!d.isDirectory()) {
+        if (d.name === "owner.json" || d.name.startsWith("owner.json.")) return `an older gate's host-wide record (${path.join(parent, d.name)}) stands`;
+        if (d.name.endsWith(".reclaim")) return "a reclaim claim stands under the ownership directory";
+        continue;
+      }
+      const names = fs.readdirSync(path.join(parent, d.name));
+      if (names.some((n) => n.endsWith(".reclaim"))) return `a reclaim claim stands for repository ${d.name}`;
+      if (d.name !== mine && names.includes("owner.json")) return `another repository (${d.name}) holds build ownership`;
+    }
+  } catch (e) { return `other repositories' ownership cannot be listed (${e.code ?? e.message})`; }
+  return null;
 }
 
 /** The holder's last report, or null when absent or unreadable. */
@@ -1025,6 +1092,12 @@ function coveredWorkGone(owner, { probe, lease, file, selfPid = null, waitMs = 0
       recorded.push({ group: entry.group, command: entry.command });
       let snapshot;
       try { snapshot = probe.groupSnapshot(entry.group); } catch (e) { throw new Error(`detached process group ${entry.group} cannot be listed (${e.message})`); }
+      // The entry is written after the spawn returns, so the group's own leader (pid == group) started before the file's mtime. A
+      // leader that started later is a new process that took the id: the kernel reuses a group id only once that group is empty.
+      let writtenMs = NaN;
+      try { writtenMs = fs.statSync(path.join(registry, name)).mtimeMs; } catch { /* unknown: judged as before */ }
+      const leader = snapshot.members.find((m) => m.pid === entry.group);
+      if (leader && Number.isFinite(writtenMs) && leader.startedMs > writtenMs + START_SLACK_MS) continue;
       const live = snapshot.members.filter((m) => m.pid !== selfPid && m.startedMs >= entry.startedMs - START_SLACK_MS).map((m) => m.pid);
       if (live.length) throw new Error(`detached process group ${entry.group} (${entry.command}) still has ${live.length} member(s): ${live.join(", ")}`);
     }
@@ -1146,12 +1219,12 @@ export function judgeOwner(observed, { file, probe, lease, host = os.hostname()
 }
 
 /**
- * Acquires the host's build ownership (or joins it, when RIGHTKIT_BUILD_OWNERSHIP names the current record). Returns
+ * Acquires a repository's build ownership (or joins it, when RIGHTKIT_BUILD_OWNERSHIP names the current record). Returns
  * `{ handle, file, joined, reclaimed, owner, markBrokerSubmit(callHandle), held(), release() }`. Throws OwnershipBusy while another build
- * owns the host, its liveness is unknown, or this gate cannot be contained.
+ * owns this repository, its liveness is unknown, or this gate cannot be contained.
  */
 export function acquireBuildOwnership({
-  file = ownershipFile(),
+  file,
   stage,
   snapshot,
   commit,
@@ -1166,9 +1239,19 @@ export function acquireBuildOwnership({
 } = {}) {
   // First, before the environment, the record or any write: the managed root exists (decision D4). `managedRoot` and `device` are
   // fixtures' seams; a production caller passes neither.
+  if (typeof file !== "string" || file === "") throw new TypeError("acquireBuildOwnership: file is required (the path ownershipFile returns for a repository key)");
   guardManagedRoot(file, { platform, managedRoot, device });
   ensureOwnershipDir(path.dirname(file), { platform });
   const inherited = env[OWNERSHIP_ENV];
+  // An older pinned gate on this host writes ONE host-wide record, `build-ownership/owner.json`, a plain file beside the repository
+  // directories. It holds every repository: this code never joins it, reclaims it or deletes it.
+  const olderFile = path.join(path.dirname(path.dirname(file)), "owner.json");
+  let older = null;
+  try { older = readText(olderFile); } catch (e) { throw new OwnershipBusy(`build ownership ${olderFile}: an older gate's host-wide record cannot be read (${e.code ?? e.message}); nothing runs while it may stand`); }
+  if (older !== null && inherited) {
+    let o = null; try { o = JSON.parse(older); } catch { o = null; }
+    if (o?.handle === inherited) throw new OwnershipBusy(`build ownership ${olderFile}: ${OWNERSHIP_ENV}=${inherited} names the host-wide record of an older gate; the parent is an older gate, and a nested gate never joins it`);
+  }
   if (inherited) {
     const current = readText(file);
     let owner = null; try { owner = JSON.parse(current ?? ""); } catch { owner = null; }
@@ -1188,6 +1271,12 @@ export function acquireBuildOwnership({
     }
     throw new OwnershipBusy(`build ownership ${file}: ${OWNERSHIP_ENV}=${inherited} is not the current owner; a nested gate never takes ownership of its own`);
   }
+  if (older !== null) {
+    // Judged exactly as the older code judged it, to word the refusal; never reclaimed from here, whatever the verdict.
+    try { judgeOwner(older, { file: olderFile, probe, lease }); }
+    catch (e) { if (!(e instanceof OwnershipBusy)) throw e; throw new OwnershipBusy(`${e.message}; this is an older gate's host-wide record and it holds every repository: let that gate finish or clear it (an older gate or a person), this gate does not`, e.detail ?? {}); }
+    throw new OwnershipBusy(`build ownership ${olderFile}: an older gate's host-wide record stands (its owner is gone, but only an older gate or a person clears it; this gate never reclaims it), and it holds every repository; nothing ran`);
+  }
   let me;
   try { me = probe.identity(process.pid); } catch (e) { throw new OwnershipBusy(`build ownership ${file}: this gate's own start identity cannot be read (${e.message})`); }
   if (!me.alive || !Number.isFinite(me.startedMs)) throw new OwnershipBusy(`build ownership ${file}: this gate's own start identity cannot be read`);