@rightkit/release 0.6.13 → 0.6.15

package/build-ownership.mjs

@@ -44,11 +44,12 @@
 //         unreadable stat: the process is held. Residual on POSIX, stated plainly: a descendant that started a
 //         new session, dropped the variable, runs outside the snapshot directory, names it in no argument AND holds no file in it
 //         open or mapped at the instant the nets sample it (it reads between samples) is invisible; a sampled net cannot prove
-//         such a process will not read next. (On macOS an Apple platform binary no longer escapes that way: hidden means held
-//         after the baseline unless lineage clears it.) Another user's unreadable processes are
+//         such a process will not read next. (On macOS a hidden-environment process is attributed by no start time: it is reported in
+//         the output and never held; rightkit#1313.) Another user's unreadable processes are
 //         skipped on the premise that they cannot read this user's managed root.
 //       Any host: a reboot after the record was written ends every process it covered.
-//   - if a broker request may have been submitted, `rustright snapshot-lease status` reports REAPED for that snapshot & handle.
+//   - if a carried (snapshot-bound) request was sent under the handle (`broker.submitted`, set only just before such a send; an uncarried
+//     probe or an installed carrier map never sets it), `rustright snapshot-lease status` reports REAPED for that snapshot & handle.
 // Any other answer (alive, a probe that fails or is unsupported, ACTIVE, UNKNOWN, a record or holder state that cannot be read)
 // is busy: never a reclaim. The same rules decide a normal release: the record is removed only when nothing but the gate itself
 // is left; otherwise it stays, and the next gate reclaims it once the survivors are gone.
@@ -64,12 +65,17 @@ import { spawn as spawnDetachedDefault, spawnSync } from "./background-process.m
 import { managedRuntimeClient } from "./managed-cargo.mjs";
 import { resolveManagedRoots } from "./managed-roots.mjs";
 import { requireManagedRoot } from "./managed-root-guard.mjs";
+import { OWNERSHIP_ENV, OWNERSHIP_FILE_ENV, OwnershipBusy, holds, markBrokerSubmit, markBrokerUnsent, markCarriedSend, markLockFile } from "./ownership-mark.mjs";
+
+// The mark itself lives in a leaf module (ownership-mark.mjs): snapshot-broker.mjs records carried sends through it, and importing this
+// file from there would close a cycle (this file -> managed-cargo -> cargo-target-shim -> snapshot-broker).
+export { OWNERSHIP_ENV, OWNERSHIP_FILE_ENV, OwnershipBusy, markCarriedSend, markLockFile };
 
 export const OWNERSHIP_SCHEMA = "rightkit.build-ownership/1";
 export const HOLDER_SCHEMA = "rightkit.build-ownership-holder/1";
-export const OWNERSHIP_ENV = "RIGHTKIT_BUILD_OWNERSHIP";
 /** The owner record's path, exported beside the handle so every process under the ownership records detached children there. */
-export const OWNERSHIP_FILE_ENV = "RIGHTKIT_BUILD_OWNERSHIP_FILE";
+/** GB-85: how long a successful stage's release waits for every submission under its handle to be durably complete (the broker's own bounded `--wait-ms`, never a poll of the build). */
+export const RELEASE_LEASE_WAIT_MS = 15_000;
 export const LEASE_STATUS_SCHEMA = "rustright.snapshot-lease-status.v1";
 const LEASE_STATES = new Set(["ACTIVE", "REAPED", "UNKNOWN"]);
 // A start time read from `ps` (or /proc/<pid>/stat) is never late, only early: ps prints whole seconds (up to 1 s early), and on
@@ -83,9 +89,6 @@ const START_SLACK_MS = 3000;
 const SAME_START_MS = 3000;
 const sameStart = (a, b) => Number.isFinite(a) && Number.isFinite(b) && Math.abs(a - b) <= SAME_START_MS;
 
-export class OwnershipBusy extends Error {
-  constructor(message, detail = {}) { super(message); this.code = "busy"; this.detail = detail; }
-}
 
 /** The directory beside the host's snapshots (or beside any injected root) that holds the owner record. */
 export const OWNERSHIP_DIRNAME = "build-ownership";
@@ -867,10 +870,22 @@ export function readHolder(file) {
 /**
  * RustRight's lease state for a snapshot & ownership handle (`rustright snapshot-lease status`). Anything but a well-formed
  * answer is UNKNOWN: a missing client, a failed or unknown command, a schema or state the gate does not know.
+ *
+ * The answer is read exactly as the broker writes it (BROKER-CONTRACT section 16, GB-23 and GB-85): `{ type, schema, state, snapshot, ownership, members, waitedMs, waitTimedOut }`.
+ * `members` is one row per submission under the handle and `state` is only their aggregate (ACTIVE while any is held, REAPED only with at least one member and every member REAPED, else
+ * UNKNOWN); a state that is not the aggregate of its own rows is a contradiction, never a result. A wait was asked with `--wait-ms` (clamped to 30000): the answer then always carries
+ * `waitedMs` (a count) and `waitTimedOut` (a boolean, true exactly when the state is not REAPED at the bound). A timeout is UNKNOWN with the reason; the gate never polls and never resubmits.
+ * The result carries `members`, `waitedMs` and `waitTimedOut` for the callers that account by name.
  */
-export function brokerLeaseState({ snapshot, handle, env = process.env, platform = process.platform, spawn = spawnSync, client = managedRuntimeClient(env, platform) }) {
+export function brokerLeaseState({ snapshot, handle, env = process.env, platform = process.platform, spawn = spawnSync, client = managedRuntimeClient(env, platform), waitMs = 0 }) {
   if (!client) return { state: "UNKNOWN", why: "no RustRight client on this host" };
-  const r = run(spawn, client, ["snapshot-lease", "status", "--snapshot", snapshot, "--ownership", handle], env);
+  // GB-85: `--wait-ms N` makes the broker answer as soon as every submission under the handle is durably complete (REAPED), or at the bound with the state it has
+  // (waitTimedOut: true). A client that predates the option answers with a usage error: the plain query is then made, never a guess.
+  const clamp = (wait) => Math.min(Math.trunc(wait), 30_000);
+  const ask = (wait) => run(spawn, client, ["snapshot-lease", "status", "--snapshot", snapshot, "--ownership", handle, ...(wait > 0 ? ["--wait-ms", String(clamp(wait))] : [])], env);
+  let waited = Number.isFinite(waitMs) && waitMs > 0 ? waitMs : 0;
+  let r = ask(waited);
+  if (waited > 0 && r.status !== 0 && !r.error && /wait-ms|unknown|unexpected|unrecognized|usage/i.test(String(r.stderr ?? ""))) { waited = 0; r = ask(0); }
   if (r.error || r.status !== 0) return { state: "UNKNOWN", why: `rustright snapshot-lease status: ${r.error?.message ?? (String(r.stderr ?? "").trim().split(/\r?\n/).pop() || `exit ${r.status}`)}` };
   let answer = null;
   try { answer = JSON.parse(String(r.stdout ?? "").trim().split(/\r?\n/).pop()); } catch { answer = null; }
@@ -878,7 +893,25 @@ export function brokerLeaseState({ snapshot, handle, env = process.env, platform
   // The answer must echo what was asked (RustRight echoes `snapshot` as received and `ownership` as the handle): another pair's answer,
   // or no echo at all, binds nothing to this owner, so it is UNKNOWN and the record is held.
   if (answer.snapshot !== snapshot || answer.ownership !== handle) return { state: "UNKNOWN", why: `the lease status does not echo the queried snapshot and ownership handle (${JSON.stringify(answer.snapshot ?? null)}, ${JSON.stringify(answer.ownership ?? null)})` };
-  return { state: answer.state, why: `rustright snapshot-lease status: ${answer.state}` };
+  const unknown = (why) => ({ state: "UNKNOWN", why: `rustright snapshot-lease status: ${why}`, ...(Array.isArray(answer.members) ? { members: answer.members } : {}) });
+  // GB-23: `members` is one row per submission the broker knows under the handle ({handle, state, spawned, refused?, job?}); the answer's own state is only the aggregate.
+  const covers = (h) => h === handle || String(h).startsWith(`${handle}#`);
+  if (!Array.isArray(answer.members)) return unknown("the answer carries no members list (one row per submission under the handle), so no submission can be accounted for by name");
+  if (answer.members.some((m) => !m || typeof m.handle !== "string" || !covers(m.handle) || !LEASE_STATES.has(m.state))) return { state: "UNKNOWN", why: `the lease status carries members that are not submissions under ${handle}` };
+  const rows = answer.members;
+  const aggregate = rows.some((m) => m.state === "ACTIVE") ? "ACTIVE" : rows.length > 0 && rows.every((m) => m.state === "REAPED") ? "REAPED" : "UNKNOWN";
+  if (answer.state !== aggregate) return unknown(`the answer says ${answer.state} but its ${rows.length} member row(s) aggregate to ${aggregate} (REAPED needs at least one member and every member REAPED): it contradicts itself, so it is not read`);
+  // GB-85: waitedMs is a count and waitTimedOut a boolean; both are always sent by a broker that takes a wait, and are required once a wait was asked.
+  const hasWaited = answer.waitedMs !== undefined; const hasTimedOut = answer.waitTimedOut !== undefined;
+  if (hasWaited && !(Number.isInteger(answer.waitedMs) && answer.waitedMs >= 0)) return unknown(`waitedMs is not a non-negative integer (${JSON.stringify(answer.waitedMs)})`);
+  if (hasTimedOut && typeof answer.waitTimedOut !== "boolean") return unknown(`waitTimedOut is not a boolean (${JSON.stringify(answer.waitTimedOut)})`);
+  if (waited > 0 && (!hasWaited || !hasTimedOut)) return unknown(`a wait of ${clamp(waited)} ms was asked but the answer carries no ${!hasWaited ? "waitedMs" : "waitTimedOut"}`);
+  const timedOut = answer.waitTimedOut === true;
+  if (timedOut && (waited <= 0 || answer.state === "REAPED")) return unknown(`waitTimedOut is true although ${waited <= 0 ? "no wait was asked" : "the state is REAPED"}: it contradicts itself`);
+  if (waited > 0 && answer.state !== "REAPED" && !timedOut) return unknown(`the state is ${answer.state} after a wait without waitTimedOut: it contradicts itself`);
+  const timing = { ...(hasWaited ? { waitedMs: answer.waitedMs } : {}), ...(hasTimedOut ? { waitTimedOut: answer.waitTimedOut } : {}) };
+  if (timedOut) return { state: "UNKNOWN", why: `rustright snapshot-lease status: still ${answer.state} after waiting ${answer.waitedMs} ms (waitTimedOut); ownership stays UNKNOWN`, members: rows, ...timing };
+  return { state: answer.state, why: `rustright snapshot-lease status: ${answer.state}`, members: rows, ...timing };
 }
 
 function publish(target, text) {
@@ -933,7 +966,7 @@ function coveredMember(m, owner, { byPid, own }) {
  * Whether the work `owner` covers, other than the process `self` (the live gate at release, null at reclaim), is proven gone.
  * Returns the proofs, or throws a reason that is busy.
  */
-function coveredWorkGone(owner, { probe, lease, file, selfPid = null }) {
+function coveredWorkGone(owner, { probe, lease, file, selfPid = null, waitMs = 0 }) {
   const proofs = [];
   let rebooted = false;
   // A reboot is only a question for a dead owner; a live gate releasing its own record has not outlived one.
@@ -1024,30 +1057,72 @@ function coveredWorkGone(owner, { probe, lease, file, selfPid = null }) {
         proofs.push(`no process has a working directory, executable, open or mapped file or argument inside or naming ${owner.snapshot}`);
       }
     }
-    // macOS: a process whose environment `ps eww` does not show is held after the anchor unless its lineage clears it (row 5.24a).
+    // macOS: a process whose environment `ps eww` does not show cannot be attributed to this ownership by the token net. Start time plus a
+    // hidden environment is no attribution (rightkit#1313: an unrelated same-user process started during the run held every later gate), so
+    // such a process is REPORTED here and never held. Only lineage the gate recorded (tracked child groups and intents above), the exact
+    // ownership token, an actual snapshot user, and the broker lease hold a release.
     if (typeof probe.hiddenHolders === "function") {
       let hidden;
-      try { hidden = probe.hiddenHolders({ owner, anchorMs: skipBefore, recorded }); } catch (e) { throw new Error(`processes whose environment is hidden cannot be classified (${e.message})`); }
-      if (hidden) {
-        const others = hidden.filter((h) => h.pid !== selfPid);
-        if (others.length) {
-          const shown = others.slice(0, 8);
-          throw new Error(`${others.length} process(es) may still be this ownership's work (hidden environment, held after the anchor unless its lineage clears it): ${shown.map((h) => `${h.pid}: ${h.why}`).join("; ")}${others.length > shown.length ? `; and ${others.length - shown.length} more (pids ${others.slice(shown.length).map((h) => h.pid).join(", ")})` : ""}`);
-        }
-        proofs.push("every live process of this user whose environment is hidden started before the anchor or descends from a process that did");
+      try { hidden = probe.hiddenHolders({ owner, anchorMs: skipBefore, recorded }); } catch { hidden = null; }
+      const others = (hidden ?? []).filter((h) => h.pid !== selfPid);
+      if (others.length) {
+        const shown = others.slice(0, 8);
+        proofs.push(`reported, not held: ${others.length} unattributed process(es) of this user with a hidden environment started after the anchor (no recorded lineage, token or snapshot use): ${shown.map((h) => `${h.pid}: ${h.why}`).join("; ")}${others.length > shown.length ? `; and ${others.length - shown.length} more (pids ${others.slice(shown.length).map((h) => h.pid).join(", ")})` : ""}`);
       }
     }
   } else if (!rebooted) {
     throw new Error(`the record names no containment (${JSON.stringify(c)})`);
   }
   if (owner.broker?.submitted) {
-    const status = lease({ snapshot: owner.snapshot, handle: owner.handle });
-    if (status.state !== "REAPED") throw new Error(`broker work may exist under this handle and its lease is ${status.state} (${status.why})`);
-    proofs.push(`broker lease for ${owner.handle} is REAPED`);
+    // Every submission under this handle must be accounted for by NAME, never by the bare handle (GB-21, GB-23, GB-85). The bare handle answers REAPED when at least one
+    // member completed and none is held (rustright snapshot.rs `status`), so it proves only that no lease is held now: a completed sibling never stands in for an
+    // unknown submission. Each recorded sub-handle (broker.handles, recorded before its send) is asked by its exact name and must be one of
+    //   - REAPED, as a member of that answer (a durable completion; `spawned: false` for a refusal that ran nothing), or
+    //   - UNSENT: the gate itself proved, under the record's lock, that its client never started (broker.unsent), AND the broker holds nothing under it (UNKNOWN, no members).
+    // An UNKNOWN or ACTIVE one, an ambiguous send, a start that may have run, keeps the record; nothing is counted complete on the absence of a completion.
+    const handles = [...new Set(Array.isArray(owner.broker.handles) ? owner.broker.handles : [])];
+    const unsent = owner.broker.unsent && typeof owner.broker.unsent === "object" ? owner.broker.unsent : {};
+    const waitOptions = waitMs > 0 ? { waitMs } : {};
+    const settled = (sub) => unsent[sub] && typeof unsent[sub].reason === "string";
+    const everyUnsent = handles.length > 0 && handles.every(settled);
+    const status = lease({ snapshot: owner.snapshot, handle: owner.handle, ...waitOptions });
+    if (status.state === "ACTIVE" || (status.state !== "REAPED" && !everyUnsent)) throw new Error(`broker work may exist under this handle and its lease is ${status.state} (${status.why})`);
+    if (status.state === "REAPED") proofs.push(`broker lease for ${owner.handle} is REAPED`);
+    // GB-23: the answer's own member rows account for each recorded sub-handle too: a recorded one that the broker lists and does not list REAPED keeps ownership, whatever the aggregate said.
+    if (Array.isArray(status.members)) for (const sub of handles) { const row = status.members.find((m) => m.handle === sub); if (row && row.state !== "REAPED") throw new Error(`the broker lists sub-handle ${sub} as ${row.state} among the members of ${owner.handle}`); }
+    let neverStarted = 0;
+    for (const sub of handles) {
+      if (typeof sub !== "string" || !sub.startsWith(`${owner.handle}#`) || sub.length <= owner.handle.length + 1) throw new Error(`the record lists ${JSON.stringify(sub)}, which is not a sub-handle of ${owner.handle}`);
+      const one = lease({ snapshot: owner.snapshot, handle: sub, ...waitOptions });
+      const member = Array.isArray(one.members) ? one.members.find((m) => m.handle === sub) : null;
+      if (one.state === "REAPED") {
+        if (Array.isArray(one.members) && !(member && member.state === "REAPED")) throw new Error(`the broker answers REAPED for ${sub} but lists no completed submission under that name`);
+        continue;
+      }
+      if (settled(sub) && one.state === "UNKNOWN" && Array.isArray(one.members) && one.members.length === 0) { proofs.push(`${sub} never started (${unsent[sub].reason}) and the broker holds nothing under it`); neverStarted += 1; continue; }
+      throw new Error(`broker work may exist under sub-handle ${sub} and its lease is ${one.state} (${one.why})`);
+    }
+    if (handles.length) proofs.push(neverStarted === 0 ? `broker lease for each of ${handles.length} sub-handle(s) is REAPED` : `every one of ${handles.length} sub-handle(s) is accounted for: ${handles.length - neverStarted} REAPED, ${neverStarted} proven never started`);
   }
   return proofs;
 }
 
+/**
+ * Whether the claimant a standing `.reclaim` body names is `"dead"` (proven), `"live"` or `"unknown"`. The body is the claimant's own owner record, so the same identity
+ * rules as the record's judge apply: another host or an unreadable body is unknown; a reboot since the claimant started, a gone pid, or a pid that now runs a process that
+ * started at another time is dead; the same process still alive is live.
+ */
+export function judgeClaimant(text, { probe, host }) {
+  let rec = null; try { rec = JSON.parse(text ?? ""); } catch { rec = null; }
+  if (rec?.schema !== OWNERSHIP_SCHEMA || typeof rec.handle !== "string" || !Number.isInteger(rec.pid) || rec.pid <= 0 || rec.pid > 0x7fffffff || !Number.isFinite(rec.startedMs)) return "unknown";
+  if (rec.host !== host) return "unknown";
+  try { const boot = probe.bootTime?.(); if (Number.isFinite(boot) && rec.startedMs < boot) return "dead"; } catch { /* the pid proof below decides */ }
+  let now; try { now = probe.identity(rec.pid); } catch { return "unknown"; }
+  if (!now.alive) return "dead";
+  if (!Number.isFinite(now.startedMs)) return "unknown";
+  return sameStart(now.startedMs, rec.startedMs) ? "live" : "dead";
+}
+
 /**
  * Why the record `observed` may be reclaimed (`{ owner, proofs }`), or an OwnershipBusy throw naming what is still live or
  * unknown. Pure apart from the probes.
@@ -1072,7 +1147,7 @@ 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
- * `{ handle, file, joined, reclaimed, owner, markBrokerSubmit(), held(), release() }`. Throws OwnershipBusy while another build
+ * `{ 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.
  */
 export function acquireBuildOwnership({
@@ -1109,7 +1184,7 @@ export function acquireBuildOwnership({
       if (!live.alive || (Number.isFinite(owner.startedMs) && Number.isFinite(live.startedMs) && !sameStart(live.startedMs, owner.startedMs))) {
         throw new OwnershipBusy(`build ownership ${file}: ${OWNERSHIP_ENV}=${inherited} names a record whose owner pid ${owner.pid} is no longer the process that took it; a nested gate joins only a live owner's record`);
       }
-      return { handle: inherited, file, joined: true, reclaimed: null, owner, markBrokerSubmit: () => markBrokerSubmit(file, inherited), held: () => holds(file, inherited), release: () => ({ released: false, joined: true }) };
+      return { handle: inherited, file, joined: true, reclaimed: null, owner, markBrokerSubmit: (callHandle) => markBrokerSubmit(file, inherited, callHandle), markBrokerUnsent: (callHandle, reason) => markBrokerUnsent(file, inherited, callHandle, reason), held: () => holds(file, inherited), release: () => ({ released: false, joined: true }) };
     }
     throw new OwnershipBusy(`build ownership ${file}: ${OWNERSHIP_ENV}=${inherited} is not the current owner; a nested gate never takes ownership of its own`);
   }
@@ -1145,12 +1220,13 @@ export function acquireBuildOwnership({
     if (!holds(file, handle)) return { released: false, why: "no longer the owner" };
     let proofs;
     // The record as it is now (a broker submit may have been marked since it was written).
-    try { proofs = coveredWorkGone(JSON.parse(readText(file)), { probe, lease, file, selfPid: process.pid }); }
+    try { proofs = coveredWorkGone(JSON.parse(readText(file)), { probe, lease, file, selfPid: process.pid, waitMs: RELEASE_LEASE_WAIT_MS }); }
     catch (e) { return { released: false, why: `left for the next gate to reclaim: ${e.message}` }; }
     finally { if (exportEnv && process.env[OWNERSHIP_ENV] === handle) { delete process.env[OWNERSHIP_ENV]; delete process.env[OWNERSHIP_FILE_ENV]; } }
     // Only a release that proved zero readers leaves the marker; a held one leaves none (and keeps the record).
     writeCleanMarker(file, record);
     fs.rmSync(file, { force: true });
+    fs.rmSync(markLockFile(file), { force: true });
     fs.rmSync(childrenDir(file, handle), { recursive: true, force: true });
     return { released: true, proofs };
   };
@@ -1173,7 +1249,7 @@ export function acquireBuildOwnership({
       catch (e) { if (holds(file, handle)) fs.rmSync(file, { force: true }); throw new OwnershipBusy(`build ownership ${file}: the containment could not be recorded (${e.code ?? e.message}: ${e.message})`); }
     }
     if (exportEnv) { process.env[OWNERSHIP_ENV] = handle; process.env[OWNERSHIP_FILE_ENV] = file; }
-    return { handle, file, joined: false, reclaimed, owner: record, contained: platform === "win32" ? record.containment.contained === true : true, markBrokerSubmit: () => markBrokerSubmit(file, handle), held: () => holds(file, handle), release };
+    return { handle, file, joined: false, reclaimed, owner: record, contained: platform === "win32" ? record.containment.contained === true : true, markBrokerSubmit: (callHandle) => markBrokerSubmit(file, handle, callHandle), markBrokerUnsent: (callHandle, reason) => markBrokerUnsent(file, handle, callHandle, reason), held: () => holds(file, handle), release };
   };
   if (publish(file, body)) return done(null);
   const observed = readText(file);
@@ -1185,16 +1261,27 @@ export function acquireBuildOwnership({
   record.freeHost = false;
   const reclaimBody = JSON.stringify(record);
   const reclaim = `${file}.reclaim`;
-  if (!publish(reclaim, reclaimBody)) throw new OwnershipBusy(`build ownership ${file} is being reclaimed by another process (remove ${reclaim} only if no gate is running)`);
+  // GB-56: a `.reclaim` already there is judged by the identity its body carries (the claimant's owner record: pid, start, host, boot), never taken for a live claimant on its
+  // existence alone. A claimant PROVEN dead (its pid is gone, the pid now runs a process that started at another time, or the host rebooted since) is removed, compare-by-content,
+  // and the claim retried once; a live, unreadable or unprovable claimant keeps the lock. Bounded: one retry, so two reclaimers never loop.
+  if (!publish(reclaim, reclaimBody)) {
+    const standing = readText(reclaim);
+    const verdict = judgeClaimant(standing, { probe, host: os.hostname() });
+    if (verdict === "dead" && readText(reclaim) === standing) { fs.rmSync(reclaim, { force: true }); }
+    if (verdict !== "dead" || !publish(reclaim, reclaimBody)) throw new OwnershipBusy(`build ownership ${file} is being reclaimed by another process (${verdict === "dead" ? "its claim was dropped but another gate took it first" : verdict === "live" ? "a live gate holds the reclaim claim" : "the reclaim claim cannot be proven dead"}: remove ${reclaim} only if no gate is running)`);
+  }
   try {
+    hooks.afterClaim?.(reclaim);
     if (readText(file) !== observed) throw new OwnershipBusy(`build ownership ${file} changed before it could be reclaimed`);
     fs.rmSync(file, { force: true });
+    fs.rmSync(markLockFile(file), { force: true });
     fs.rmSync(holderFile(file, judged.owner.handle), { force: true });
     fs.rmSync(holderScriptFile(holderFile(file, judged.owner.handle)), { force: true });
     fs.rmSync(childrenDir(file, judged.owner.handle), { recursive: true, force: true });
     if (!publish(file, reclaimBody)) throw new OwnershipBusy(`build ownership ${file} was taken by another process`);
   } finally {
-    fs.rmSync(reclaim, { force: true });
+    // Token-checked: only this reclaim's own claim is removed (a successor's claim, published after this one was judged dead, stays).
+    if (readText(reclaim) === reclaimBody) fs.rmSync(reclaim, { force: true });
   }
   return done({ from: judged.owner.handle, pid: judged.owner.pid, proofs: judged.proofs });
 }
@@ -1209,23 +1296,4 @@ function rewriteRecord(file, handle, change) {
   try { fs.renameSync(tmp, file); } finally { fs.rmSync(tmp, { force: true }); }
 }
 
-function holds(file, handle) {
-  try { return JSON.parse(fs.readFileSync(file, "utf8")).handle === handle; } catch { return false; }
-}
 
-/**
- * Records, before the first broker submit, that broker work may exist under this handle; from then on the record is reclaimed
- * only on the broker's REAPED. Replaces the record atomically and only while it is still this handle's.
- */
-function markBrokerSubmit(file, handle) {
-  const text = readText(file);
-  let owner = null; try { owner = JSON.parse(text ?? ""); } catch { owner = null; }
-  if (owner?.handle !== handle) throw new OwnershipBusy(`build ownership ${file} is no longer held by ${handle}; no broker request may be submitted`);
-  if (owner.broker?.submitted) return owner;
-  const next = { ...owner, broker: { ...(owner.broker ?? {}), submitted: true, at: new Date().toISOString() } };
-  const tmp = `${file}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(next), { flag: "wx", mode: 0o600 });
-  try { fs.renameSync(tmp, file); } finally { fs.rmSync(tmp, { force: true }); }
-  if (!holds(file, handle)) throw new OwnershipBusy(`build ownership ${file} changed while recording a broker submit`);
-  return next;
-}

package/build-release.mjs

@@ -55,6 +55,7 @@ import { ANDROID_RECEIPT_NAME, androidSealEntry, validateAndroidTarget, verifyAn
 import { IOS_RECEIPT_NAME, iosSealEntry, verifyIosReceipt } from "./ios-package-recipe.mjs";
 import { expandIosPackageTarget } from "./package-recipe-targets.mjs";
 import { assertUpdaterKeyId, assertUpdaterSignature, isSuiteUpdaterApp, resolveUpdaterTrust } from "./github-updater-release.mjs";
+import { platformDirOf } from "./platform-dir.mjs";
 
 // The iOS lane's own packaging code, kept out of the win/mac fingerprint for the same reason as the Android one.
 const IOS_PIPELINE_FINGERPRINT = createHash("sha256")
@@ -266,7 +267,7 @@ try {
     : collectToolVersions(config.packageManager ?? "pnpm", appRoot);
   const inputHashes = hashInputs(requiredInputs);
   const releaseId = `${config.app}-${config.version}-${shortCommit}`;
-  const platformDir = platform === "win" ? "windows" : platform === "android" ? "android" : platform === "ios" ? "ios" : "mac";
+  const platformDir = platformDirOf(platform);
   const stateRoot = path.join(vaultRoot, "state", releaseId, platformDir);
   const signingIdentity = platform === "win" ? {
     contract: target.signingContract ?? "<missing>",
@@ -611,7 +612,7 @@ async function admit() {
     throw error;
   }
   // A fresh build asks the registries once, here; a resume or a re-run over a sealed release reuses its recorded snapshot instead.
-  const platformName = platform === "win" ? "windows" : platform;
+  const platformName = platformDirOf(platform);
   const sealed = config?.app && config?.version
     && existsSync(path.join(repoRoot, ".right-release", "sealed", `${config.app}-${config.version}-${commit.slice(0, 8)}`, platformName, "release-manifest.json"));
   const reuse = Boolean(resumeFrom) || Boolean(sealed);

package/cache-command.mjs

@@ -30,13 +30,18 @@ export async function runCacheCommand(args = process.argv.slice(2), { env = proc
   const [command, ...rest] = args;
   const json = rest.includes("--json");
   const platform = platformFrom(env);
-  const cacheRoot = resolveSharedCacheRoot({ platform, env });
+  // GB-65: the broker-owned route is decided BEFORE the Cache V2 root is resolved. A broker Mac sets no RIGHT_RELEASE_CACHE_ROOT (the broker
+  // owns the target), and resolving the unused root first threw for all three commands before the intended skip. Arguments are still
+  // validated, and nothing is inspected, migrated or pruned on this route.
   if (BROKER_GATED_COMMANDS.has(command) && isBrokerHost(env)) {
-    const result = { schema: 1, command, cacheRoot, brokerManaged: true, skipped: true, message: BROKER_MANAGED_MESSAGE };
+    rejectUnknown(rest.filter((value, i) => !(command === "migrate" && (value === "--config" || rest[i - 1] === "--config"))), new Set(command === "status" ? ["--json"] : ["--json", "--dry-run", "--apply"]));
+    if (command !== "status" && rest.includes("--dry-run") && rest.includes("--apply")) throw new Error(`cache ${command} accepts either --dry-run or --apply`);
+    const result = { schema: 1, command, cacheRoot: null, brokerManaged: true, skipped: true, message: BROKER_MANAGED_MESSAGE };
     if (json) stdout(JSON.stringify(result));
     else stdout(BROKER_MANAGED_MESSAGE);
     return result;
   }
+  const cacheRoot = resolveSharedCacheRoot({ platform, env });
   if (command === "status") {
     rejectUnknown(rest, new Set(["--json"]));
     const snapshot = inspectCache({ cacheRoot });

package/candidate-build-receipt.mjs

@@ -0,0 +1,96 @@
+// GB-73 (BROKER-CONTRACT section 16): the candidate build receipt the gate writes from its SNAPSHOT build, which RustRight's installer takes instead of a clean primary checkout:
+//   rustright-install stage|cutover ... --candidate-receipt <file> --candidate-receipt-sha256 <digest>
+// where the file is exactly
+//   { "schema": "rustright.candidate-build-receipt.v1", "commit", "tree", "source": "snapshot", "artifacts": { "broker", "client" } }
+// (full lowercase commit and tree ids, the sha256 of the broker and client binaries being installed). The installer accepts it only when the file hashes to the DIGEST THE GATE RECORDED (the
+// digest comes from the gate's record, never from the file), the commit is the asked-for one, the tree is that commit's own tree in the checkout's object database, the artifact digests are the
+// ones being installed and the commit is on origin/main; a tampered receipt, a wrong tree, other binaries and an off-origin commit each refuse before effects. So this module writes the receipt
+// deterministically, records its digest apart from it, hands the installer its two arguments, and verifies a receipt the way the installer does before the gate hands it on.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "./atomic-write.mjs";
+
+export const CANDIDATE_RECEIPT_SCHEMA = "rustright.candidate-build-receipt.v1";
+export const CANDIDATE_RECORD_SCHEMA = "rightkit.candidate-receipt-record/1";
+export const CANDIDATE_RECEIPT_FILE = "candidate-build-receipt.json";
+export const CANDIDATE_RECORD_FILE = "candidate-build-receipt.record.json";
+const OBJECT_ID = /^[0-9a-f]{40}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+const sha256 = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** The receipt object for a snapshot build of `commit` (whose tree is `tree`): exactly RustRight's fields, in a fixed order. Refuses anything that is not a full lowercase id or digest. */
+export function buildCandidateReceipt({ commit, tree, brokerSha256, clientSha256 }) {
+  const problems = [];
+  if (!OBJECT_ID.test(commit ?? "")) problems.push("commit must be a full lowercase object id");
+  if (!OBJECT_ID.test(tree ?? "")) problems.push("tree must be a full lowercase object id");
+  if (!DIGEST.test(brokerSha256 ?? "")) problems.push("the broker artifact digest must be 64 lowercase hex characters");
+  if (!DIGEST.test(clientSha256 ?? "")) problems.push("the client artifact digest must be 64 lowercase hex characters");
+  if (problems.length) throw Object.assign(new Error(`the candidate build receipt cannot be written: ${problems.join("; ")}`), { code: "RK_CANDIDATE_RECEIPT_INVALID" });
+  return { schema: CANDIDATE_RECEIPT_SCHEMA, commit, tree, source: "snapshot", artifacts: { broker: brokerSha256, client: clientSha256 } };
+}
+
+/** The bytes the receipt is written as and hashed over: its JSON, one line, a final newline. */
+export const candidateReceiptBytes = (receipt) => Buffer.from(`${JSON.stringify(receipt)}\n`, "utf8");
+
+/** The digest of one built artifact (a regular file), or a typed refusal. */
+export function artifactDigest(file, { readFile = fs.readFileSync, stat = fs.statSync } = {}) {
+  if (typeof file !== "string" || !path.isAbsolute(file)) throw Object.assign(new Error(`the artifact ${JSON.stringify(file)} must be an absolute path`), { code: "RK_CANDIDATE_RECEIPT_INVALID" });
+  let meta; try { meta = stat(file); } catch (e) { throw Object.assign(new Error(`the artifact ${file} cannot be read (${e.code ?? e.message})`), { code: "RK_CANDIDATE_RECEIPT_INVALID" }); }
+  if (!meta.isFile()) throw Object.assign(new Error(`the artifact ${file} is not a regular file`), { code: "RK_CANDIDATE_RECEIPT_INVALID" });
+  return sha256(readFile(file));
+}
+
+/**
+ * Writes the receipt and, apart from it, the gate's record of its digest, into `dir` (created, owner-only, each written atomically). Returns the record: `{ schema, file, sha256, commit, tree,
+ * artifacts, recordFile }`. A directory that already holds a receipt for other bytes is refused: a candidate's receipt is written once.
+ */
+export function writeCandidateReceipt({ dir, receipt, now = Date.now(), write = writeFileAtomic, read = (f) => fs.readFileSync(f), exists = fs.existsSync }) {
+  const file = path.join(dir, CANDIDATE_RECEIPT_FILE); const recordFile = path.join(dir, CANDIDATE_RECORD_FILE);
+  const bytes = candidateReceiptBytes(receipt);
+  if (exists(file) && sha256(read(file)) !== sha256(bytes)) throw Object.assign(new Error(`${file} already holds a different candidate build receipt; a candidate's receipt is written once`), { code: "RK_CANDIDATE_RECEIPT_EXISTS" });
+  write(file, bytes, { mode: 0o600 });
+  const record = { schema: CANDIDATE_RECORD_SCHEMA, file, sha256: sha256(bytes), commit: receipt.commit, tree: receipt.tree, artifacts: { ...receipt.artifacts }, recordedAt: new Date(now).toISOString() };
+  write(recordFile, Buffer.from(`${JSON.stringify(record)}\n`, "utf8"), { mode: 0o600 });
+  return { ...record, recordFile };
+}
+
+/** The installer's two arguments for a receipt record: the file and the digest the GATE recorded. */
+export function candidateReceiptArgs(record) {
+  if (!record || typeof record.file !== "string" || !DIGEST.test(record.sha256 ?? "")) throw Object.assign(new Error("a candidate receipt record names its file and its sha256"), { code: "RK_CANDIDATE_RECEIPT_INVALID" });
+  return ["--candidate-receipt", record.file, "--candidate-receipt-sha256", record.sha256];
+}
+
+/**
+ * Whether the receipt at `file` is acceptable for installing `commit` / `tree` with the binaries whose digests are `brokerSha256` and `clientSha256`, judged as RustRight's installer judges it
+ * (provenance.rs): the file hashes to `expectedSha256` (the gate's recorded digest, never a value read from the file), it is exactly {schema, commit, tree, source, artifacts:{broker, client}} with the
+ * v1 schema and source "snapshot", the commit and tree are the asked-for ones and the artifact digests are the ones being installed. Returns the problems; none means acceptable. (That the commit is on
+ * origin/main and the tree is the commit's own is the installer's check, in the checkout's object database.)
+ */
+export function candidateReceiptProblems({ file, expectedSha256, commit, tree, brokerSha256, clientSha256, readFile = fs.readFileSync }) {
+  let bytes; try { bytes = readFile(file); } catch (e) { return [`the receipt ${file} cannot be read (${e.code ?? e.message})`]; }
+  const problems = [];
+  if (!DIGEST.test(expectedSha256 ?? "")) return ["the gate's recorded digest is missing or malformed"];
+  if (sha256(bytes) !== expectedSha256) problems.push(`the file hashes to ${sha256(bytes)}, not the digest the gate recorded (${expectedSha256}): it was changed after it was written`);
+  let doc; try { doc = JSON.parse(Buffer.from(bytes).toString("utf8")); } catch { return [...problems, "the receipt is not JSON"]; }
+  if (!isObject(doc) || Object.keys(doc).sort().join() !== "artifacts,commit,schema,source,tree") problems.push("the receipt is not exactly {schema, commit, tree, source, artifacts}");
+  if (doc?.schema !== CANDIDATE_RECEIPT_SCHEMA) problems.push(`the schema is ${JSON.stringify(doc?.schema)}, not ${CANDIDATE_RECEIPT_SCHEMA}`);
+  if (doc?.source !== "snapshot") problems.push(`the source is ${JSON.stringify(doc?.source)}, not "snapshot"`);
+  if (doc?.commit !== commit) problems.push(`the receipt is for commit ${String(doc?.commit).slice(0, 12)}, not ${String(commit).slice(0, 12)}`);
+  if (doc?.tree !== tree) problems.push(`the receipt names tree ${String(doc?.tree).slice(0, 12)}, not the commit's ${String(tree).slice(0, 12)}`);
+  const artifacts = doc?.artifacts;
+  if (!isObject(artifacts) || Object.keys(artifacts).sort().join() !== "broker,client") problems.push("artifacts is not exactly {broker, client}");
+  else {
+    if (artifacts.broker !== brokerSha256) problems.push("the broker binary being installed is not the one the receipt names");
+    if (artifacts.client !== clientSha256) problems.push("the client binary being installed is not the one the receipt names");
+  }
+  return problems;
+}
+
+/** The gate's record read back (never the receipt's own digest): `{ record }` or `{ problem }`. */
+export function readCandidateRecord(recordFile, { readFile = fs.readFileSync } = {}) {
+  let doc; try { doc = JSON.parse(readFile(recordFile, "utf8")); } catch (e) { return { problem: `the candidate receipt record ${recordFile} cannot be read (${e.code ?? e.message})` }; }
+  if (doc?.schema !== CANDIDATE_RECORD_SCHEMA || typeof doc.file !== "string" || !DIGEST.test(doc.sha256 ?? "") || !OBJECT_ID.test(doc.commit ?? "") || !OBJECT_ID.test(doc.tree ?? "")) return { problem: `${recordFile} is not a ${CANDIDATE_RECORD_SCHEMA}` };
+  return { record: doc };
+}

package/candidate-receipt-command.mjs

@@ -0,0 +1,29 @@
+// `rightkit-gate candidate-receipt --commit <full sha> --broker <file> --client <file> [--out <dir>]` (GB-73): writes the candidate build receipt (candidate-build-receipt.mjs) for the
+// binaries a gate SNAPSHOT build of that commit produced, records its digest apart from it, and prints one JSON line with the record and the installer's two arguments
+// (`--candidate-receipt <file> --candidate-receipt-sha256 <digest>`). The commit's tree is read from the repository the gate runs in; the artifact digests are computed here, never taken from a flag.
+import path from "node:path";
+import { gateRunsRoot } from "./managed-roots.mjs";
+import { artifactDigest, buildCandidateReceipt, candidateReceiptArgs, writeCandidateReceipt } from "./candidate-build-receipt.mjs";
+
+export const CANDIDATE_RECEIPT_USAGE = "usage: rightkit-gate candidate-receipt --commit <full lowercase sha> --broker <broker binary> --client <client binary> [--out <dir>]   (the binaries a gate snapshot build of that commit produced)";
+
+export async function candidateReceiptCommand(o, args, { artifact = artifactDigest, write = writeCandidateReceipt } = {}) {
+  const take = (name) => { const i = args.indexOf(name); return i < 0 ? undefined : args[i + 1]; };
+  const known = new Set(["--commit", "--broker", "--client", "--out"]);
+  const stray = args.filter((a, i) => (a.startsWith("--") ? !known.has(a) : !known.has(args[i - 1] ?? "")));
+  const commit = take("--commit"); const broker = take("--broker"); const client = take("--client");
+  if (stray.length || !commit || !broker || !client) { o.err(`rightkit-gate: ${CANDIDATE_RECEIPT_USAGE}`); return 2; }
+  const fail = (e) => { o.err(`rightkit-gate: ${e.code ?? "RK_CANDIDATE_RECEIPT_INVALID"}: ${e.message}`); return 1; };
+  let record;
+  try {
+    const resolved = o.spawn("git", ["rev-parse", "--verify", "--quiet", `${commit}^{tree}`], { cwd: o.cwd, encoding: "utf8", env: o.env });
+    const tree = String(resolved?.stdout ?? "").trim();
+    if (resolved?.status !== 0 || !/^[0-9a-f]{40}$/.test(tree)) throw Object.assign(new Error(`the commit ${commit} is not in this repository, so its tree cannot be read`), { code: "RK_CANDIDATE_RECEIPT_INVALID" });
+    const receipt = buildCandidateReceipt({ commit, tree, brokerSha256: artifact(broker), clientSha256: artifact(client) });
+    const out = take("--out") ?? path.join(gateRunsRoot({ env: o.env, platform: o.platform, home: o.env.HOME || o.env.USERPROFILE || undefined }), "candidate-receipts", commit);
+    if (!path.isAbsolute(out)) throw Object.assign(new Error(`--out ${out} must be an absolute directory`), { code: "RK_CANDIDATE_RECEIPT_INVALID" });
+    record = write({ dir: out, receipt });
+  } catch (e) { return fail(e); }
+  o.out(JSON.stringify({ ...record, installerArgs: candidateReceiptArgs(record) }));
+  return 0;
+}

package/cargo-contract.mjs

@@ -2,7 +2,7 @@ import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
-import { directPlatform, managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
+import { directPlatform, linuxBrokerDeclared, managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
 
 const SKIP_DIRECTORIES = new Set([".audit", ".cache", ".git", ".claude", ".right-release", ".worktrees", "node_modules", "target", "vendor"]);
 const CRATES_IO_SOURCES = new Set([
@@ -30,8 +30,9 @@ export function managedCargoShimOnPath(env = process.env, platform = process.pla
 }
 
 export function brokerManagedHost(env = process.env, platform = process.platform, exists = existsSync) {
-  if (directPlatform(platform)) return false; // Linux is never broker-managed, whatever socket or control root the env names
-  return Boolean(managedRuntimeClient(env, platform, exists)) || Boolean(env.RIGHTKIT_BUILD_BROKER_SOCKET) || managedCargoShimOnPath(env, platform, exists);
+  // A Linux host is broker-managed only through its explicit declared route (managed-cargo linuxBrokerDeclared), whatever socket or control root the env names.
+  if (directPlatform(platform)) return linuxBrokerDeclared(env, platform);
+  return Boolean(managedRuntimeClient(env, platform, exists)) || Boolean(env.RUSTRIGHT_BUILD_BROKER_SOCKET || env.RIGHTKIT_BUILD_BROKER_SOCKET) || managedCargoShimOnPath(env, platform, exists);
 }
 
 export function isolatedCargoMetadataEnv(cargoHome, env = process.env, platform = process.platform, exists = existsSync) {

package/cargo-ledger.mjs

@@ -48,7 +48,7 @@ export function readLedger(dir, token) {
   const entries = [...byId.values()];
   for (const e of entries) {
     if (OK_STATUSES.includes(e.status)) continue;
-    const call = `cargo ${(e.argv ?? []).join(" ")}`.trim();
+    const call = `${e.adapter ?? "cargo"} ${(e.argv ?? []).join(" ")}`.trim();
     problems.push(e.status === "pending" ? `${call} (from ${e.cwd}) never completed: the wrapper recorded it and no outcome, so it is unverified` : `${call} (from ${e.cwd}) was ${e.status}${e.code ? ` (${e.code})` : ""}${e.message ? `: ${e.message}` : ""}`);
   }
   return { entries, problems };

package/cargo-license-notices.mjs

@@ -6,7 +6,7 @@
 //   legal: { cargoNotices: { output: "legal/THIRD_PARTY_CARGO_LICENSES.html", template: "legal/about.hbs",
 //                            config?: "legal/about.toml", manifestPath?: "src-tauri/Cargo.toml", features?: ["a"], allFeatures?: true } }
 //
-// `output`, `template`, `config` and `manifestPath` are app-relative and may not leave the app. The run is `cargo about generate --locked
+// `output`, `template`, `config` and `manifestPath` are app-relative and may not leave the app. The run is `cargo about generate --frozen
 // --fail [--config <config>] [--manifest-path <path>] [--all-features | --features a,b] <template>`; cargo-about writes the rendered
 // appendix to stdout, which is normalised to LF and one trailing newline so the same lockfile always produces the same bytes. `--fail`
 // makes an unaccepted license or an unresolved clarification an error instead of a warning. `--check` writes nothing and exits 1 when
@@ -43,7 +43,7 @@ export function resolveCargoNoticeOptions(config, flags = {}) {
 /** The `cargo about` argument list (after the managed client adds `cargo`). */
 export function cargoAboutArgs(options) {
   return [
-    "about", "generate", "--locked", "--fail",
+    "about", "generate", "--frozen", "--fail",
     ...(options.config ? ["--config", options.config] : []),
     ...(options.manifestPath ? ["--manifest-path", options.manifestPath] : []),
     ...(options.allFeatures ? ["--all-features"] : options.features.length ? ["--features", options.features.join(",")] : []),