@rightkit/release 0.6.6 → 0.6.7

package/disk-report.mjs

@@ -0,0 +1,129 @@
+import { lstatSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathSize, platformKey, scratchOwner, scratchRoots } from "./disk-policy.mjs";
+
+// The daily `disk.report` line of disk-hygiene.jsonl. Pulse's Storage card reads it: the field names below are a contract
+// (frozen in disk-report.test.mjs). Pure apart from `measureScratchUnits`.
+
+const UNIT_LIMIT = 50;
+const GROWER_LIMIT = 10;
+
+export { scratchOwner };
+
+/** True when the last report is from another UTC day than `now` (or there is none). */
+export function reportDue({ lastReportTs, now }) {
+  const last = Date.parse(lastReportTs ?? "");
+  if (!Number.isFinite(last)) return true;
+  return new Date(last).toISOString().slice(0, 10) !== new Date(now).toISOString().slice(0, 10);
+}
+
+/** One du per child of every scratch root (daily only: the hourly pass never sizes anything). */
+export function measureScratchUnits({ policy, platform = process.platform, env = process.env, home = os.homedir(), size = (p) => pathSize(p, { platform }) } = {}) {
+  const units = [];
+  for (const root of scratchRoots(policy, { platform, env, home })) {
+    let names = [];
+    try { names = readdirSync(root); } catch { continue; }
+    for (const name of names) {
+      const full = path.join(root, name);
+      try { if (lstatSync(full).isSymbolicLink()) continue; } catch { continue; }
+      units.push({ name, path: full, bytes: size(full) });
+    }
+  }
+  return units;
+}
+
+const round = (n, places = 2) => Math.round(n * 10 ** places) / 10 ** places;
+
+// bytes per category: the outermost writers on the agent volume (a writer nested in another counts once) plus what no writer
+// holds. The identity is  sum(categories) - overlapBytes = usedBytes: du sums allocated bytes per writer, so APFS clones and hard links
+// can make the writers add up to MORE than the volume's used bytes. Then `overlapBytes` = writers - used (the double-counted bytes),
+// `unmanaged` is 0 and no category is scaled; otherwise `overlapBytes` is 0 and `unmanaged` = used - writers. The change in used
+// bytes between two reports is therefore  sum(delta.categories) - delta.overlapBytes.
+function categoriesOf(check, agentUnmanaged, usedBytes) {
+  const categories = {};
+  const add = (name, bytes) => { categories[name] = (categories[name] ?? 0) + bytes; };
+  for (const w of agentUnmanaged ? agentUnmanaged.writers ?? [] : check.writers ?? []) add(w.category ?? w.id, w.bytes ?? 0);
+  const writerBytes = Object.values(categories).reduce((a, b) => a + b, 0);
+  categories.unmanaged = Math.max(0, usedBytes - writerBytes);
+  return { categories, overlapBytes: Math.max(0, writerBytes - usedBytes) };
+}
+
+const sumDelta = (now, before) => {
+  const out = {};
+  for (const name of new Set([...Object.keys(now), ...Object.keys(before)])) out[name] = (now[name] ?? 0) - (before[name] ?? 0);
+  return out;
+};
+
+/** The report line for a finished full pass. `check` is the `checkDisk` result after the pass, `previous` the last
+ * `disk.report` event (or null), `scratchUnits` the result of `measureScratchUnits`. */
+export function buildDiskReport({ check, previous = null, now, policy, scratchUnits = [], moved = 0, purged = 0, host = os.hostname() }) {
+  const floors = check.floors ?? [check.floor];
+  // The report describes the agent volume. When one is flagged and cannot be read there is no lead: never another volume's numbers
+  // under its name (a day of internal-drive bytes next to a day of D: bytes makes a delta of terabytes). Policies that flag no
+  // agent volume at all report their first readable floor.
+  const lead = floors.some((f) => f.agentVolume) ? floors.find((f) => f.agentVolume && !f.absent) ?? null : floors.find((f) => !f.absent) ?? null;
+  const agentUnmanaged = lead ? (check.unmanaged ?? []).find((u) => u.floor === (lead.id ?? lead.label)) ?? (check.unmanaged ?? [])[0] ?? null : null;
+  const usedBytes = lead ? lead.totalBytes - lead.freeBytes : null;
+  const { categories, overlapBytes } = lead ? categoriesOf(check, agentUnmanaged, usedBytes) : { categories: null, overlapBytes: null };
+
+  const units = {};
+  const owners = {};
+  for (const w of check.writers ?? []) if (w.bytes > 0) units[w.id] = (units[w.id] ?? 0) + w.bytes;
+  const scratchByOwner = {};
+  for (const u of scratchUnits) {
+    units[`scratch/${u.name}`] = u.bytes;
+    owners[`scratch/${u.name}`] = scratchOwner(u.name);
+    scratchByOwner[scratchOwner(u.name)] = (scratchByOwner[scratchOwner(u.name)] ?? 0) + u.bytes;
+  }
+  const kept = Object.entries(units).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, UNIT_LIMIT);
+  const compact = Object.fromEntries(kept);
+
+  let delta = null;
+  let growers = [];
+  const hours = previous ? Math.max(0, (now - Date.parse(previous.ts)) / 3600_000) : 0;
+  // No delta unless both reports describe the agent volume: a report without one (null sizes) is no baseline, and neither is this one.
+  const comparable = lead && previous && Number.isFinite(previous.usedBytes) && previous.categories && typeof previous.categories === "object";
+  if (comparable && Number.isFinite(hours)) {
+    delta = { hours: round(hours), usedBytes: usedBytes - previous.usedBytes, categories: sumDelta(categories, previous.categories), overlapBytes: overlapBytes - (previous.overlapBytes ?? 0) };
+    growers = Object.entries(compact)
+      .map(([id, bytes]) => ({ id, bytes, deltaBytes: bytes - (previous.units?.[id] ?? 0), owner: owners[id] ?? null }))
+      .filter((g) => g.deltaBytes > 0)
+      .sort((a, b) => b.deltaBytes - a.deltaBytes || a.id.localeCompare(b.id))
+      .slice(0, GROWER_LIMIT);
+  }
+
+  const budgetsOver = (check.writers ?? []).filter((w) => w.over).map((w) => ({ id: w.id, bytes: w.bytes, capBytes: w.capBytes }));
+  for (const [prefix, capBytes] of Object.entries(policy.scratchPrefixCaps ?? {})) {
+    if ((scratchByOwner[prefix] ?? 0) > capBytes) budgetsOver.push({ id: `scratch:${prefix}`, bytes: scratchByOwner[prefix], capBytes });
+  }
+
+  // What the data in flight occupies at steady state: a day's growth lives as scratch, then in holding, then the daily pass
+  // that finally purges it.
+  const growthBytesPerDay = delta ? Math.round((Math.max(0, delta.usedBytes) / Math.max(delta.hours, 1)) * 24) : 0;
+  const daysParked = (policy.scratchStaleDays ?? policy.unknownStaleDays ?? 3) + (policy.holdingDays ?? 3) + 1;
+
+  return {
+    ts: new Date(now).toISOString(),
+    event: "disk.report",
+    schema: 1,
+    platform: check.platform ?? platformKey(),
+    host,
+    freeBytes: lead?.freeBytes ?? null,
+    usedBytes,
+    totalBytes: lead?.totalBytes ?? null,
+    floors: floors.map((f) => ({ id: f.id ?? f.label, freeBytes: f.absent ? null : f.freeBytes, softBytes: f.absent ? null : f.thresholdBytes, hardBytes: f.hardFreeBytes ?? null, warn: f.warn })),
+    categories,
+    delta,
+    units: compact,
+    growers,
+    budgetsOver,
+    unmanagedBytes: categories ? categories.unmanaged : null,
+    overlapBytes,
+    uncoveredTopLevel: (agentUnmanaged?.uncoveredTopLevel ?? []).map((e) => e.name),
+    scratchByOwner,
+    steadyState: { growthBytesPerDay, daysParked, estimateBytes: growthBytesPerDay * daysParked },
+    movedBytes: moved,
+    purgedBytes: purged,
+  };
+}

package/door-policy.mjs

@@ -0,0 +1,228 @@
+// The one-door policy for agents (Adrian, 2026-10-25): one way to build, through rightkit-gate. An agent's shell command that builds,
+// checks, tests, packages or releases an app any other way is denied with the door to use instead. Deterministic and offline: it reads
+// only the command text. `rustright cargo ...` is allowed (the broker admits a compile only after class A); `rightkit-gate ...` is the
+// door. The same policy runs on every host: through the repository's .claude/settings.json (rightkit-gate install-hook), so a cloud
+// session without the broker is held to it too.
+import path from "node:path";
+
+const CARGO_COMPILES = new Set(["build", "b", "check", "c", "clippy", "test", "t", "run", "r", "bench", "doc", "d", "rustc", "install", "tauri"]);
+const TAURI_BUILDS = new Set(["build", "dev", "bundle", "android", "ios"]);
+// right-release commands that build, package, sign, qualify or ship (CHECKED_COMMANDS "commit" in app-check.mjs).
+const RELEASE_COMMANDS = new Set(["dev", "test", "stage-sidecar", "release", "build", "package", "qa", "upload", "publish", "publish-update", "github", "sign-windows", "sign-updater", "create-mac-updater", "web-build", "swift-package", "recipe-build", "sign-candidate"]);
+const RUNNERS = new Set(["pnpm", "npm", "npx", "yarn", "bunx", "pnpx"]);
+const SHELLS = new Set(["bash", "sh", "zsh", "dash", "fish", "pwsh", "powershell", "cmd"]);
+// cargo's global options that take a value (`cargo -C dir build`, `cargo --config k=v test`): the value is not the subcommand.
+const CARGO_VALUE_OPTIONS = new Set(["-C", "--config", "--color", "-Z", "--manifest-path"]);
+const WRAPPERS = new Set(["env", "command", "exec", "time", "nice", "nohup", "sudo", "timeout"]);
+// Shell reserved words and grouping that can precede a command in the same simple command (`if true; then cargo build; fi`,
+// `{ cargo build; }`, `f() { cargo build; }`, `! cargo test`): they are skipped, never taken for the command.
+const KEYWORDS = new Set(["if", "then", "elif", "else", "fi", "do", "done", "while", "until", "{", "}", "!", "function"]);
+const DOOR_TOOLS = new Set(["cargo", "tauri", "right-release"]);
+
+/** Splits a shell command into simple commands (on ; && || | and newlines), each an argv of words. Quotes are respected. */
+export function simpleCommands(command) {
+  return pipedCommands(command).map((c) => c.argv);
+}
+
+/**
+ * simpleCommands, each with `piped` (the argv whose output it reads through a single `|`, or null), `pipesOut` (its output goes
+ * through `|`), `after` (the separator before it: "start", ";", "&&", "||", "|", "&") and `scope` (the nesting of subshells and
+ * if/while/until/for/case/{ } blocks it stands in). An assignment reaches a later command for certain only in the same scope.
+ */
+function pipedCommands(command) {
+  const out = []; let words = []; let word = ""; let quote = null; let has = false; let pipe = false; let sep = "start";
+  const stack = []; let next = 0;
+  const OPEN = { if: "fi", while: "done", until: "done", for: "done", case: "esac", "{": "}" };
+  const flushWord = () => { if (has) { words.push(word); word = ""; has = false; } };
+  const flushCmd = (nextSep = ";") => {
+    flushWord();
+    if (words.length) {
+      // Block words change the scope: a closing word belongs to the inner scope it closes, an opening word to the one it opens.
+      let w = 0;
+      while (w < words.length && ["fi", "done", "esac", "}"].includes(words[w]) && stack.length) { stack.pop(); w++; }
+      const scope = stack.map((b) => b.id).join("/");
+      if (pipe && out.length) out[out.length - 1].pipesOut = true;
+      out.push({ argv: words, piped: pipe && out.length ? out[out.length - 1].argv : null, pipesOut: false, after: sep, scope });
+      for (; w < words.length; w++) if (OPEN[words[w]] && (w === 0 || ["then", "do", "else", "elif", "{", "!", "time"].includes(words[w - 1]) || OPEN[words[w - 1]])) stack.push({ id: next++, kind: words[w] });
+      for (const x of words) if (["fi", "done", "esac", "}"].includes(x) && x !== words[0] && stack.length) stack.pop();
+    }
+    words = []; pipe = nextSep === "|"; sep = nextSep;
+  };
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (quote) { if (ch === quote) quote = null; else if (ch === "\\" && quote === '"' && i + 1 < command.length) { word += command[++i]; } else word += ch; has = true; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; has = true; continue; }
+    if (ch === "\\" && i + 1 < command.length) { word += command[++i]; has = true; continue; }
+    if (ch === "|" && command[i + 1] === "|") { flushCmd("||"); i++; continue; }
+    if (ch === "&" && command[i + 1] === "&") { flushCmd("&&"); i++; continue; }
+    if (ch === "|") { flushCmd("|"); continue; }
+    if (ch === "(") { flushCmd(";"); stack.push({ id: next++, kind: "(" }); continue; }
+    // In a case block, `)` ends a pattern; otherwise it closes a subshell.
+    if (ch === ")") { const top = stack[stack.length - 1]; flushCmd(";"); if (top && top.kind !== "case" && stack.length) stack.pop(); continue; }
+    if (ch === ";" || ch === "\n" || ch === "&") { flushCmd(ch === "&" ? "&" : ";"); continue; }
+    if (/\s/.test(ch)) { flushWord(); continue; }
+    word += ch; has = true;
+  }
+  flushCmd();
+  return out;
+}
+
+const base = (word) => path.basename(String(word ?? "")).replace(/\.(exe|cmd|bat|mjs|js)$/i, "");
+
+function stripWrappers(argv) {
+  let a = [...argv];
+  for (;;) {
+    while (a.length && KEYWORDS.has(a[0])) a = a.slice(1);
+    while (a.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(a[0])) a = a.slice(1);
+    if (a.length && KEYWORDS.has(a[0])) continue;
+    if (a.length && WRAPPERS.has(base(a[0]))) { const w = base(a[0]); a = a.slice(1); while (a.length && a[0].startsWith("-")) a = a.slice(a[0] === "-u" || a[0] === "-n" ? 2 : 1); if (w === "timeout" && a.length && /^\d/.test(a[0])) a = a.slice(1); continue; }
+    return a;
+  }
+}
+
+/** The violation a single argv is, or null. */
+/** argv without its redirections (`>/dev/null`, `2>&1`, `> out.txt`, `<in`): they are not arguments of the command. */
+function withoutRedirects(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (/^(\d*|&)(>>?|<)(&\d*)?$/.test(argv[i])) { i++; continue; }
+    if (/^(\d*|&)(>>?|<)/.test(argv[i])) continue;
+    out.push(argv[i]);
+  }
+  return out;
+}
+
+function argvViolation(argv, depth = 0, stdin = null) {
+  let a = stripWrappers(withoutRedirects(argv));
+  if (!a.length) return null;
+  let tool = base(a[0]);
+  // A command string handed to another shell (`bash -c "cargo build"`, `eval "..."`) is judged as the command it is.
+  if (depth < 4 && (SHELLS.has(tool.toLowerCase()) || tool === "eval")) {
+    const flag = a.findIndex((w, i) => i > 0 && /^(-c|\/c|-Command|-command)$/.test(w));
+    const script = tool === "eval" ? a.slice(1).join(" ") : flag > 0 ? a.slice(flag + 1).join(" ") : null;
+    return script ? doorViolation(script, depth + 1) : null;
+  }
+  if (tool === "xargs" && a.length > 1) {
+    const inner = a.slice(1).filter((w) => !w.startsWith("-"));
+    // xargs appends what it reads to the command. Read from a literal `echo`/`printf`, the words are known and judged with it;
+    // read from anything else, a door tool, a package runner or node is denied, since the text cannot say what it will run.
+    const echoed = stdin && ["echo", "printf"].includes(base(stdin[0])) ? stdin.slice(base(stdin[0]) === "printf" ? 2 : 1).filter((w) => !/^-[neE]+$/.test(w)).flatMap((w) => w.split(/\s+/).filter(Boolean)) : null;
+    if (echoed) return argvViolation([...inner, ...echoed], depth + 1);
+    if (DOOR_TOOLS.has(base(inner[0])) || RUNNERS.has(base(inner[0])) || base(inner[0]) === "node") { const v = argvViolation(inner, depth + 1); return v ?? `${base(inner[0])} (arguments from xargs)`; }
+    return argvViolation(inner, depth + 1);
+  }
+  // pnpm/npx/yarn [exec|dlx] <tool> ...: judge the tool it runs.
+  if (RUNNERS.has(tool)) {
+    let rest = a.slice(1).filter((w, i, all) => !(w.startsWith("-") || (i > 0 && ["--filter", "-F", "--dir", "-C", "--prefix"].includes(all[i - 1]))));
+    if (["exec", "dlx", "x"].includes(rest[0])) rest = rest.slice(1);
+    if (rest[0] === "run" || rest[0] === "run-script") return null; // the apps have no scripts; a script name is not a tool
+    if (!rest.length) return null;
+    a = rest; tool = base(a[0]);
+  }
+  if (tool === "rightkit-gate" || tool === "rustright") return null;
+  if (tool === "tauri" && TAURI_BUILDS.has(a[1])) return `tauri ${a[1]}`;
+  if (tool === "cargo") {
+    let sub = null;
+    for (let i = 1; i < a.length; i++) {
+      if (CARGO_VALUE_OPTIONS.has(a[i])) { i++; continue; }
+      if (!a[i].startsWith("-") && !a[i].startsWith("+")) { sub = a[i]; break; }
+    }
+    if (sub === "tauri" && TAURI_BUILDS.has(a[a.indexOf("tauri") + 1])) return `cargo tauri ${a[a.indexOf("tauri") + 1]}`;
+    if (sub && CARGO_COMPILES.has(sub) && sub !== "tauri") return `cargo ${sub}`;
+    return null;
+  }
+  const releaseArgs = tool === "right-release" ? a.slice(1) : tool === "node" && a[1] && /right-release(\.mjs)?$/.test(a[1]) ? a.slice(2) : null;
+  if (releaseArgs) {
+    // A flag first (`right-release --platform mac`) is `build`; `cargo-target` and `dmg build` compile too.
+    if (releaseArgs[0]?.startsWith("-") && !["-h", "--help", "-v", "--version"].includes(releaseArgs[0])) return "right-release build";
+    if (RELEASE_COMMANDS.has(releaseArgs[0])) return `right-release ${releaseArgs[0]}`;
+    if (releaseArgs[0] === "cargo-target") return "right-release cargo-target";
+    if (["dmg", "addon"].includes(releaseArgs[0]) && releaseArgs[1] === "build") return `right-release ${releaseArgs[0]} build`;
+  }
+  // The build engine called directly.
+  if (tool === "node" && a[1] && /(^|[\/])(build-release|release|upload-release|publish-update)\.mjs$/.test(a[1])) return "right-release build";
+  return null;
+}
+
+/** The bodies of `$(...)` and backtick substitutions in `command`, outside single quotes (they run inside double quotes too). */
+export function substitutions(command) {
+  return splitSubstitutions(command).bodies;
+}
+
+/** { bodies, rest }: the substitution bodies, and `command` with each substitution replaced by a placeholder word. */
+function splitSubstitutions(command) {
+  const out = []; let quote = null; let rest = ""; let from = 0;
+  const cut = (start, end, body) => { out.push(body); rest += `${command.slice(from, start)}_SUBST_`; from = end; };
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (quote === "'") { if (ch === "'") quote = null; continue; }
+    if (ch === "\\") { i++; continue; }
+    if (ch === "'" && quote !== '"') { quote = "'"; continue; }
+    if (ch === '"') { quote = quote === '"' ? null : '"'; continue; }
+    if (ch === "`") { const end = command.indexOf("`", i + 1); if (end < 0) { cut(i, command.length, command.slice(i + 1)); break; } cut(i, end + 1, command.slice(i + 1, end)); i = end; continue; }
+    if (ch === "$" && command[i + 1] === "(" && command[i + 2] !== "(") {
+      let depth = 0; let j = i + 1;
+      // A `case` arm's pattern ends in an unmatched `)` (`$(case x in x) cargo build;; esac)`): it does not close the substitution.
+      const openCases = (to) => (command.slice(i + 2, to).match(/\bcase\b/g) ?? []).length - (command.slice(i + 2, to).match(/\besac\b/g) ?? []).length;
+      for (; j < command.length; j++) { if (command[j] === "(") depth++; else if (command[j] === ")" && depth === 1 && openCases(j) > 0) continue; else if (command[j] === ")" && --depth === 0) break; }
+      cut(i, j + 1, command.slice(i + 2, j)); i = j;
+    }
+  }
+  return { bodies: out, rest: rest + command.slice(from) };
+}
+
+/** The first way `command` builds outside the door, or null. */
+export function doorViolation(command, depth = 0) {
+  if (typeof command !== "string" || !command.trim()) return null;
+  const { bodies, rest } = splitSubstitutions(command);
+  if (depth < 4) for (const inner of bodies) { const v = doorViolation(inner, depth + 1); if (v) return v; }
+  // Variables set in the command (`T=cargo; $T build`, `export T=cargo`) are substituted where they stand in command position; a
+  // command word that is a variable the command does not set cannot be read from the text, so it is denied rather than guessed.
+  const vars = {};
+  const commands = pipedCommands(rest);
+  for (const [index, { argv, piped, pipesOut, after, scope }] of commands.entries()) {
+    let a = argv;
+    // `time` is a reserved word in bash too: `time T=cargo` assigns.
+    while (a.length && (KEYWORDS.has(a[0]) || a[0] === "time" || (a[0] === "-p" && argv[0] === "time"))) a = a.slice(1);
+    while (a.length && ["export", "declare", "local", "readonly", "typeset"].includes(a[0])) a = a.slice(1).filter((w) => !w.startsWith("-"));
+    const assigns = []; while (a.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(a[0])) { assigns.push(a[0]); a = a.slice(1); }
+    // Certain only when it runs in this shell unconditionally: not a pipeline element, not after && or ||, not backgrounded.
+    // (`true && T=x` and `false || T=x` always run it; any other condition cannot be decided from the text.)
+    const prev = commands[index - 1]?.argv;
+    const decided = prev?.length === 1 && ((after === "&&" && prev[0] === "true") || (after === "||" && prev[0] === "false"));
+    const sure = !piped && !pipesOut && (after === "start" || after === ";" || decided);
+    if (!a.length) { for (const w of assigns) { const k = w.slice(0, w.indexOf("=")); vars[k] = { value: w.slice(k.length + 1), sure, scope }; } continue; }
+    const head = stripWrappers(a);
+    const ref = /^\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))$/.exec(head[0] ?? "");
+    if (ref) {
+      const name = ref[1] ?? ref[2];
+      if (!(name in vars)) return `\$${name} (a command the text does not name)`;
+      // An assignment that may not have reached this command (a pipeline element, a subshell, another block, after && or ||) may
+      // leave the variable empty, and then its arguments are the command: both readings are judged.
+      const set = vars[name];
+      if (!set.sure || !(scope === set.scope || scope.startsWith(`${set.scope}/`) || set.scope === "")) {
+        const empty = argvViolation(head.slice(1), 0, piped ? stripWrappers(withoutRedirects(piped)) : null);
+        if (empty) return empty;
+      }
+      a = [...set.value.split(/\s+/).filter(Boolean), ...head.slice(1)];
+    }
+    const v = argvViolation(a, 0, piped ? stripWrappers(withoutRedirects(piped)) : null);
+    if (v) return v;
+  }
+  return null;
+}
+
+export function doorDenial(violation) {
+  const stage = /^right-release (dev|test)$/.test(violation) ? violation.slice("right-release ".length) : /^(cargo )?tauri dev$/.test(violation) ? "dev"
+    : /^right-release (upload|publish|publish-update|github)$/.test(violation) ? "release" : /^right-release qa$/.test(violation) ? "qualify" : /^right-release /.test(violation) || /^(cargo )?tauri (build|bundle|android|ios)$/.test(violation) ? "package" : "compile";
+  return `[HOOK:one-door:block]\nWhy: \`${violation}\` builds outside the one door. Every check, compile, test, package and release goes through rightkit-gate, class A first.\nRequired: rightkit-gate --to ${stage}${stage === "package" || stage === "qualify" || stage === "release" ? " --platform mac|win" : ""}${stage === "dev" || stage === "test" ? " -- <arguments>" : ""}${stage === "release" ? " --tier patch|update" : ""} (on a machine with the RustRight broker, \`rustright cargo ...\` is also admitted: the broker runs class A first).`;
+}
+
+/** Claude Code PreToolUse decision for one hook input. */
+export function claudeDoorDecision(input) {
+  const command = input?.tool_input?.command ?? input?.tool_input?.cmd ?? input?.command ?? null;
+  const violation = doorViolation(typeof command === "string" ? command : "");
+  return violation
+    ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: doorDenial(violation) } }
+    : {};
+}

package/gate-executor.mjs

@@ -0,0 +1,30 @@
+// The executor behind the one door (Adrian, 2026-10-25): rightkit-gate chooses it, never the caller.
+//   broker  - `rustright` is on PATH, or the first `cargo` is the broker's managed shim: every cargo call goes through the broker.
+//   refuse  - a broker-managed machine (Mac/Dell markers, broker socket, managed agent-bin) whose broker cannot be reached from here:
+//             the gate never compiles around it.
+//   direct  - any other host (a throwaway cloud container, a CI runner): cargo runs directly, through the same gates and stages.
+import { brokerManagedHost, managedCargoShimOnPath } from "./cargo-contract.mjs";
+
+export const EXECUTOR_KINDS = Object.freeze(["broker", "refuse", "direct"]);
+
+/**
+ * @param {{ env?: object, platform?: string, exists?: (p: string) => boolean, which: (cmd: string) => string[], readFile: (p: string) => string }} o
+ * @returns {{ kind: "broker" | "refuse" | "direct", cargo: string[] | null, problem?: string }}
+ */
+export function resolveExecutor({ env = process.env, platform = process.platform, exists, which, readFile }) {
+  if (which("rustright").length) return { kind: "broker", cargo: ["rustright", "cargo"] };
+  const first = which("cargo")[0];
+  if (first) {
+    try { if (readFile(first).includes("cargo-guard.mjs")) return { kind: "broker", cargo: ["cargo"] }; } catch { /* unreadable: not the shim */ }
+  }
+  // RustRight's own agent-bin `cargo` shim first on PATH: plain `cargo` already goes through the broker.
+  if (managedCargoShimOnPath(env, platform, exists)) return { kind: "broker", cargo: ["cargo"] };
+  if (brokerManagedHost(env, platform, exists)) {
+    return {
+      kind: "refuse",
+      cargo: null,
+      problem: "this machine is broker-managed (RustRight) but `rustright` is not reachable from this shell; start or repair the broker, then run again. The gate never compiles around the broker",
+    };
+  }
+  return { kind: "direct", cargo: ["cargo"] };
+}

package/gate-stages.mjs

@@ -0,0 +1,110 @@
+// The stages behind the one door (Adrian, 2026-10-25): rightkit-gate --to <stage> runs every stage up to <stage>, in order, for the
+// commit at HEAD, and stops at the first that fails. Class A always runs first. The stages reuse the existing owners instead of
+// reimplementing them: the gate's own scans for check/compile, `right-release` for package (source QA, then the build that seals the
+// exact artifact set), installed QA on that sealed set, and upload of that same sealed set. Those right-release commands refuse to
+// run unless a live door run launched them (requireDoorRun), so there is no side door into a stage.
+//
+// Run token: <git common dir>/rightkit-gate/runs/<nonce>.json { pid, commit, tree, stage } while a door run is active; the child gets
+// RK_GATE_RUN=<nonce>. Receipt: <git common dir>/rightkit-gate/receipts/<commit>.json, machine-owned, binding the commit and tree to
+// the executor, toolchain, lockfile digests, gate digest, each stage's result and the sealed manifest digest (the bytes that were
+// packaged, qualified and released). Nobody edits these by hand; the door writes them and reads them.
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const STAGES = Object.freeze(["check", "compile", "package", "qualify", "release"]);
+export const RECEIPT_SCHEMA = "rightkit.gate-receipt/1";
+export const RUN_ENV = "RK_GATE_RUN";
+
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+
+/** The stages a run to `target` covers, in order; null when `target` is not a stage. */
+export function stagesTo(target) {
+  const i = STAGES.indexOf(target);
+  return i < 0 ? null : STAGES.slice(0, i + 1);
+}
+
+/** The door's state directory under the repository's git common dir. */
+export function gateStateDir(commonDir) {
+  return path.join(commonDir, "rightkit-gate");
+}
+
+/** Starts a door run: writes the run file and returns { nonce, file, env }. The caller removes it with endRun. */
+export function startRun({ commonDir, commit, tree, stage, pid = process.pid, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
+  const nonce = randomBytes(16).toString("hex");
+  const dir = path.join(gateStateDir(commonDir), "runs");
+  mkdir(dir, { recursive: true });
+  const file = path.join(dir, `${nonce}.json`);
+  write(file, `${JSON.stringify({ pid, commit, tree, stage, startedAt: new Date().toISOString() })}\n`);
+  return { nonce, file, env: { [RUN_ENV]: nonce } };
+}
+
+export function endRun(run, rm = fs.rmSync) {
+  if (run?.file) rm(run.file, { force: true });
+}
+
+/**
+ * Whether this process was launched by a live door run for `commit`. Returns null when it was, else the refusal message. A run file
+ * whose pid is gone, or that names another commit, is no run.
+ */
+export function requireDoorRun({ env = process.env, commonDir, commit, readFile = (f) => fs.readFileSync(f, "utf8"), alive = pidAlive, command = "this command" }) {
+  const nonce = env[RUN_ENV];
+  const refusal = `${command} runs only through the one door: rightkit-gate --to <check|compile|package|qualify|release> (it runs class A first, then every stage in order)`;
+  if (!nonce || !/^[0-9a-f]{32}$/.test(nonce)) return refusal;
+  let run;
+  try { run = JSON.parse(readFile(path.join(gateStateDir(commonDir), "runs", `${nonce}.json`))); } catch { return `${refusal}; RK_GATE_RUN names no live door run`; }
+  if (!alive(run.pid)) return `${refusal}; the door run that launched it has ended`;
+  if (commit && run.commit !== commit) return `${refusal}; the door run is for ${String(run.commit).slice(0, 12)}, HEAD is ${commit.slice(0, 12)}`;
+  return null;
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+/** Reads the receipt for `commit`, or a fresh one bound to it. */
+export function readReceipt({ commonDir, commit, readFile = (f) => fs.readFileSync(f, "utf8") }) {
+  try {
+    const r = JSON.parse(readFile(path.join(gateStateDir(commonDir), "receipts", `${commit}.json`)));
+    if (r.schema === RECEIPT_SCHEMA && r.commit === commit) return r;
+  } catch { /* none yet */ }
+  return null;
+}
+
+export function writeReceipt({ commonDir, receipt, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
+  const dir = path.join(gateStateDir(commonDir), "receipts");
+  mkdir(dir, { recursive: true });
+  write(path.join(dir, `${receipt.commit}.json`), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+
+/**
+ * The inputs a receipt binds besides the commit: the tree id, each lockfile's digest, the gate's own digest and the toolchain versions.
+ * A receipt from an earlier run counts for a stage only when every one of these is unchanged.
+ */
+export function bindingOf({ tree, lockFiles = {}, gateFile, readFile = (f) => fs.readFileSync(f), toolchain = {}, executor }) {
+  let gate = null;
+  try { gate = sha256(readFile(gateFile)); } catch { /* unreadable: no binding, nothing reused */ }
+  return { tree, locks: Object.fromEntries(Object.entries(lockFiles).map(([k, v]) => [k, sha256(v)]).sort(([a], [b]) => a.localeCompare(b))), gate, toolchain, executor };
+}
+
+export function sameBinding(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Same source: tree, lockfiles and gate digest equal (the host's toolchain and executor may differ). */
+export function sameSource(a, b) {
+  return Boolean(a && b) && a.tree === b.tree && a.gate === b.gate && JSON.stringify(a.locks) === JSON.stringify(b.locks);
+}
+
+/** The sealed release directory build-release wrote for `commit` on `platform`: { id, manifest, digest } or null. */
+export function sealedFor({ root, commit, platform, readdir = fs.readdirSync, readFile = (f) => fs.readFileSync(f) }) {
+  const base = path.join(root, ".right-release", "sealed");
+  let ids = [];
+  try { ids = readdir(base).filter((id) => id.endsWith(`-${commit.slice(0, 8)}`)); } catch { return null; }
+  for (const id of ids.sort()) {
+    const file = path.join(base, id, platform, "release-manifest.json");
+    try { const bytes = readFile(file); return { id, manifest: file, digest: sha256(bytes) }; } catch { /* not this platform */ }
+  }
+  return null;
+}

package/github-updater-release.mjs

@@ -5,12 +5,14 @@
 // key file), sealed, and re-verified by `verifyPublicationRelease`. This module only turns the same
 // `platforms` map the r2 lane builds ({ <platform>: { signature, url } }) into a Tauri v2 static `latest.json`
 // and uploads it, with the bundles and their `.sig` files, as assets of the GitHub release `v<version>`, so
-// `https://github.com/<owner>/<repo>/releases/latest/download/latest.json` resolves. It adds no key and no trust root.
+// `https://github.com/<owner>/<repo>/releases/latest/download/latest.json` resolves. It adds no key and no trust root:
+// a Right Suite app's updater keys come from the Right Suite contract (`resolveUpdaterTrust`), never from the app's config.
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { PublicationError, digestBytes, readVerifiedArtifact, verifyArtifactFile } from "./publication-artifacts.mjs";
 import { inspectRemoteAsset, runCommand } from "./github-release.mjs";
+import { RIGHT_SUITE_APP_KEYS, RIGHT_SUITE_UPDATER_PUBLIC_KEYS, RIGHT_SUITE_UPDATER_SIGNING_KEY_ID } from "./suite-api.generated.mjs";
 
 const REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const SEMVER_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
@@ -18,7 +20,7 @@ const SEMVER_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z
 const ASSET_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,199}$/;
 // Tauri v2 updater platform keys: <os>-<arch>, optionally <os>-<arch>-<installer>.
 const PLATFORM_RE = /^(?:windows|darwin|linux)-(?:x86_64|aarch64|i686|armv7)(?:-(?:nsis|msi|app|appimage|deb|rpm))?$/;
-const KEY_ID_RE = /^[0-9A-F]{16}$/;
+export const UPDATER_KEY_ID_RE = /^[0-9A-F]{16}$/;
 
 export const LATEST_JSON_NAME = "latest.json";
 
@@ -72,7 +74,7 @@ function parseMinisignSignature(signatureText) {
       if (bytes.toString("base64") !== text) throw new Error("invalid base64");
       return bytes;
     };
-    const envelope = decode(String(signatureText).trim());
+    const envelope = decode(String(signatureText).replace(/^[ \t\n\f\r]+|[ \t\n\f\r]+$/g, ""));
     const text = new TextDecoder("utf-8", { fatal: true }).decode(envelope);
     const lines = text.split(/\r?\n/);
     if (lines.at(-1) === "") lines.pop();
@@ -122,8 +124,8 @@ export function verifyMinisignSignature(bytes, signatureText, publicKeyText) {
 }
 
 /**
- * Require a cryptographically valid minisign signature over `bytes` under the declared public key.
- * The key-id check (`assertUpdaterKeyId`) is supplementary only; this is the seal/upload gate.
+ * Require a cryptographically valid minisign signature over `bytes` under `publicKeyText` (for a suite app, the
+ * contract key `resolveUpdaterTrust` returns). The key-id check (`assertUpdaterKeyId`) names the wrong key; this is the seal/upload gate.
  */
 export function assertUpdaterSignature(bytes, signatureText, publicKeyText, label = "updater signature") {
   if (!verifyMinisignSignature(bytes, signatureText, publicKeyText)) {
@@ -131,10 +133,48 @@ export function assertUpdaterSignature(bytes, signatureText, publicKeyText, labe
   }
 }
 
-/** Refuses a signature made by any key other than the configured suite key id (distribution.updaterKeyId). */
-export function assertUpdaterKeyId(signatureText, expectedKeyId, label = "updater signature") {
+// Case-insensitively: release config accepts app names in any case, and a different spelling must not move the trust root out of the contract.
+export const isSuiteUpdaterApp = (app) => typeof app === "string" && RIGHT_SUITE_APP_KEYS.includes(app.toLowerCase());
+
+/**
+ * The updater trust a sealed signature is checked against: `{ keyId, publicKey, suite }`. `now` is unix seconds and `keys` the
+ * accepted-key list, both injectable for tests.
+ *
+ * A Right Suite app (RIGHT_SUITE_APP_KEYS) takes its key from the contract so a config cannot swap the trust root: the key id is
+ * the configured `distribution.updaterKeyId` or else the contract's signing key, it must be a listed, unexpired key, and a declared
+ * public key must be that key's exact contract text. Any other app (Ember has its own updater key) keeps the declared key as the
+ * only trust root and the key id stays optional.
+ */
+export function resolveUpdaterTrust({ app, configuredPublicKey, configuredKeyId, now = Math.floor(Date.now() / 1000), keys = RIGHT_SUITE_UPDATER_PUBLIC_KEYS } = {}) {
+  if (!isSuiteUpdaterApp(app)) {
+    if (typeof configuredPublicKey !== "string" || !configuredPublicKey.trim()) {
+      throw new PublicationError("PUBLICATION_SIGNATURE_UNVERIFIABLE", `updater public key is required to verify updater artifacts: ${app ?? "this app"} is not a Right Suite app and declares no updater public key (distribution.updaterPublicKey); refusing an unverified signature`);
+    }
+    return { keyId: configuredKeyId, publicKey: configuredPublicKey, suite: false };
+  }
+  const keyId = configuredKeyId ?? RIGHT_SUITE_UPDATER_SIGNING_KEY_ID;
+  const accepted = UPDATER_KEY_ID_RE.test(keyId) ? keys.find((key) => key.kid === keyId) : undefined;
+  if (!accepted) {
+    throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", `updater key ${JSON.stringify(keyId)} is not an updater key in the Right Suite contract (key ids are 16 upper-case hex digits; accepted: ${keys.map((key) => key.kid).join(", ")}); omit distribution.updaterKeyId to use the signing key`);
+  }
+  if (accepted.notAfterUnix != null && accepted.notAfterUnix <= now) {
+    throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", `updater key ${keyId} ended${accepted.notAfter ? ` (notAfter ${accepted.notAfter})` : ""} in the Right Suite contract and is no longer accepted`);
+  }
+  const declared = configuredPublicKey !== undefined && configuredPublicKey !== null && !(typeof configuredPublicKey === "string" && !configuredPublicKey.trim());
+  if (declared && configuredPublicKey !== accepted.publicKey) {
+    throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", `the declared updater public key is not the Right Suite contract key for ${keyId}; suite apps do not declare their own`);
+  }
+  return { keyId, publicKey: accepted.publicKey, suite: true };
+}
+
+/**
+ * Refuses a signature made by any key other than `expectedKeyId`. Pass `trust.keyId` from `resolveUpdaterTrust`. An undefined id
+ * is a no-op only for an app outside the Right Suite; with `app` set to a suite app the id is resolved and enforced even when omitted.
+ */
+export function assertUpdaterKeyId(signatureText, expectedKeyId, label = "updater signature", { app, now, keys } = {}) {
+  if (isSuiteUpdaterApp(app)) expectedKeyId = resolveUpdaterTrust({ app, configuredKeyId: expectedKeyId, now, keys }).keyId;
   if (expectedKeyId === undefined) return;
-  if (!KEY_ID_RE.test(expectedKeyId)) throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", "distribution.updaterKeyId must be 16 upper-case hex digits");
+  if (!UPDATER_KEY_ID_RE.test(expectedKeyId)) throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", "distribution.updaterKeyId must be 16 upper-case hex digits");
   const actual = updaterSignatureKeyId(signatureText);
   if (actual !== expectedKeyId) throw new PublicationError("PUBLICATION_SIGNATURE_KEY_MISMATCH", `${label} was not made by updater key ${expectedKeyId} (found ${actual ?? "unreadable"})`);
 }