@rightkit/release 0.6.5 → 0.6.7

package/bin/rightkit-gate.mjs

@@ -3,7 +3,7 @@
 // "local deterministic checks ... mandatory for all builds"). Runs from the pre-push hook that `rightkit-gate install-hook`
 // writes, so it never depends on an agent remembering. Every applicable scan for the pushed change runs through the one
 // scan module (../deterministic-scans.mjs); Rust units come from `cargo metadata` (one run per Cargo workspace), npm units from
-// pnpm-workspace.yaml, so the layout is the repository's own. CI still compiles, lints and tests everything.
+// the pnpm roots' workspace files, so the layout is the repository's own. CI still compiles, lints and tests everything.
 //
 // Layout it covers (nothing is partly covered silently):
 //   - Rust: every tracked Cargo.toml that is a workspace root or a standalone package not inside another workspace is its own Cargo
@@ -12,8 +12,11 @@
 //     workspace's own Cargo.lock, and ci/gate.config.json `rust` may key its feature sets by `<cargoDir>:<crate>` or by the plain crate
 //     name. A tracked Cargo.toml that is not a member and cannot stand alone, a member that is untracked or ignored, and an untracked
 //     Cargo.toml are skipped with a note on the first lines of the run, never silently.
-//   - npm: the pnpm-workspace.yaml globs over tracked package.json files; when that file is absent, has no `packages:` or declares ".",
-//     the root package.json is a unit too (tsc, eslint and test rows like any package).
+//   - npm: every pnpm root (discoverPnpmRoots: the repository root, and any tracked directory with a pnpm-lock.yaml or pnpm-workspace.yaml
+//     beside a package.json, outside node_modules) has its own units: the pnpm-workspace.yaml globs over tracked package.json files; when that
+//     file is absent, has no `packages:` or declares ".", the root's package.json is a unit too. pnpm-lockfile and pnpm-audit run once per
+//     root in its directory (`pnpm-lockfile:<root>` below the repository root), and each unit gets tsc, the linter it configures (eslint
+//     or biome, by config file) and its tests like any package. A unit of a root below the repository root is named from its directory.
 //
 // Release evidence for a PRODUCT repository (an app): the pin's "a release qualified locally on both hosts" is the app's own
 // `right-release` release QA run on both hosts (docs/CI.md "Release evidence for an app"). `right-release qualify cargo` qualifies
@@ -25,20 +28,31 @@
 //                                             run the gate (default base origin/main); --plan prints the scans and runs none;
 //                                             --no-cache (or RK_GATE_CACHE=0) reruns every scan
 //   rightkit-gate check [--repo <dir>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]
-//                                             the offline app check (../app-check.mjs): committed files only, no network, compile or
-//                                             broker, every finding in one run. Exit 0 pass, 1 findings, 2 could not run
+//                                             the deterministic stage: the app check (../app-check.mjs), then every class A scan
+//                                             (lockfiles, cargo-deny/audit, secrets, licences, manifests, workflow lint, syntax) over the
+//                                             whole tree of the commit, not a diff. Nothing compiles; without a broker class A uses
+//                                             plain cargo for metadata/deny/audit only. The RustRight broker runs this before it admits
+//                                             any compile. --list/--print-baseline/--only show the app check alone. Exit 0 pass,
+//                                             1 findings, 2 could not run
 //   rightkit-gate install-hook [--force]      write .githooks/pre-push and set core.hooksPath. core.hooksPath hides .git/hooks, so the
 //                                             pre-push hook runs the repository's own .git/hooks/pre-push first, then `rightkit-gate
 //                                             check --commit HEAD`, then the gate; every other hook present in .git/hooks gets a
 //                                             .githooks/<name> trampoline that runs it; the hook finds the gate binary in the root
-//                                             node_modules/.bin, then any workspace package's, then pnpm exec. Where @rightkit/release is
+//                                             node_modules/.bin, then any workspace package's (each package that declares @rightkit/release by
+//                                             name when the root does not declare it), then pnpm exec, then node at a stable path inside the
+//                                             repository (hookGatePlan: from the declarations, never from what is installed). Where @rightkit/release is
 //                                             installed it also writes the advisory ownership pre-commit step (`right-release hooks install`
 //                                             is an alias of this command)
 //
 // From the pre-push hook, git's ref lines arrive on stdin: the commit being pushed must be the checked-out HEAD (broker scans
 // read the live checkout), and the remote's current commit is the diff base. To push an earlier commit of the local stack,
 // check it out first (a detached HEAD is fine), push HEAD:<branch>, return.
-// ci/gate.config.json `rust` (optional) sets per-crate feature sets, exactly as CI's gate reads it.
+// The executor is chosen by the gate, never the caller (gate-executor.mjs resolveExecutor): the RustRight broker where this machine
+// has it (`rustright` on PATH, or its managed cargo shim), a refusal on a broker-managed machine whose broker is unreachable, and
+// direct cargo on any other host (a cloud container, a CI runner). Every host runs the same gates in the same order (app rules, class A,
+// the compile scans); an unmanaged host is never told to find a broker. The pre-push hook judges every pushed ref.
+// ci/gate.config.json `rust` (optional) sets per-crate feature sets, exactly as CI's gate reads it; `npm.<unit>` sets `quietTests` and
+// `requiresBroker: { "reason": "..." }` (a test the package scripts do not show reaching the broker: node -e, node scripts, sh -c, pnpm --dir).
 // Result cache: a passing class B scan is reused only when its scan id, command, tool version, environment and input digest
 // (the gated commit's git object ids for the crate's workspace closure, the shared build inputs, ci/gate.config.json and every
 // path the closure's sources include from outside their crate; the whole HEAD tree for Rust tests unless ci/gate.config.json
@@ -53,18 +67,22 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { WORKSPACE_RUST_FILE, ancestorConfigChanged, ancestorDirsOf, canonicalJson, defaultSpawn, digestScanSet, fileScanCache, metadataArgs, planScans, runScans, scanDeferrals, scanFailures } from "../deterministic-scans.mjs";
+import { BIOME_CONFIG_FILES, ESLINT_CONFIG_FILES, WORKSPACE_RUST_FILE, ancestorConfigChanged, ancestorDirsOf, canonicalJson, defaultSpawn, digestScanSet, fileScanCache, findRustfmt, metadataArgs, planScans, runScans, scanDeferrals, scanFailures } from "../deterministic-scans.mjs";
 import { changedLockNames, parseLock, reach } from "../lock-graph.mjs";
+import { resolveExecutor } from "../gate-executor.mjs";
+import { bindingOf, endRun, readReceipt, RECEIPT_SCHEMA, sameBinding, sameSource, sealedFor, stagesTo, startRun, STAGES, writeReceipt } from "../gate-stages.mjs";
+import { spawnSync as spawnInherit } from "../background-process.mjs";
 
 const ZERO = /^0+$/;
-const GRANT_FILE = ".rightkit-local-build.json";
 const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const posix = (p) => String(p).replaceAll("\\", "/");
 const text = (r) => String(r?.stdout ?? "");
 const failed = (r) => !r || Boolean(r.error) || r.status !== 0;
 const why = (r) => String(r?.error?.message ?? r?.stderr ?? "").trim().split(/\r?\n/).slice(-3).join(" | ");
 
-const USAGE = `usage: rightkit-gate [--base <ref>] [--plan] [--no-cache] [--pre-push] | rightkit-gate install-hook [--force] | rightkit-gate check [--repo <dir>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>] | --version`;
+// A green `check --only` view: app rules passed but no class A scan ran. Distinct from 0 so no caller can admit it as a full check.
+export const PARTIAL_EXIT = 3;
+const USAGE = `usage: rightkit-gate --to check|compile|package|qualify|release [--platform mac|win] [--tier patch|update] [--receipt-in <file>] [--receipt-out <file>] | rightkit-gate --to dev|test [-- <right-release args>] | rightkit-gate stage --platform mac|win [--tier patch|update] | rightkit-gate [--base <ref>] [--plan] [--no-cache] [--pre-push] | rightkit-gate install-hook [--force] | rightkit-gate check [--repo <dir>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>] | --version`;
 
 // ---- pure helpers (exported for tests) ----------------------------------------------------------------------
 
@@ -115,31 +133,77 @@ const unitName = (pkgName, dir) => {
   return SAFE_NAME.test(n) ? n : dir === "." ? "root" : dir.replace(/\//g, "-");
 };
 
+// The bounds of the pnpm root walk. A lock deeper than this is a buried fixture, not an app; more roots than this is refused, because covering
+// some of them would hide the rest.
+const PNPM_ROOT_MAX_DEPTH = 6;
+const PNPM_ROOT_MAX_COUNT = 64;
+
+/** Tracked files with exactly this name (a lister that ignores the name is filtered here). */
+const trackedNamed = (tracked, name) => tracked(name).map(posix).filter((p) => path.posix.basename(p) === name);
+
+/**
+ * The pnpm roots of the repository, sorted: "." when the repository root holds a pnpm-workspace.yaml or a package.json, and every other
+ * tracked directory (outside node_modules, at most 6 levels deep) that holds a pnpm-lock.yaml or a pnpm-workspace.yaml beside a
+ * package.json. A repository such as CodeRight (apps/coderight-tauri and apps/coderight-web, each with its own lock, nothing at the root) has
+ * two; a plain repository has "." only. A walk over the tracked files, never the file system: nothing in node_modules or untracked is a root.
+ */
+export function discoverPnpmRoots({ root, tracked, exists }) {
+  const manifestDirs = new Set(trackedNamed(tracked, "package.json").map((p) => path.posix.dirname(p)));
+  const roots = new Set();
+  if (exists(path.join(root, "pnpm-workspace.yaml")) || exists(path.join(root, "package.json"))) roots.add(".");
+  for (const file of [...trackedNamed(tracked, "pnpm-lock.yaml"), ...trackedNamed(tracked, "pnpm-workspace.yaml")]) {
+    const dir = path.posix.dirname(file);
+    const parts = dir.split("/");
+    if (dir === "." || parts.includes("node_modules") || parts.length > PNPM_ROOT_MAX_DEPTH || !manifestDirs.has(dir)) continue;
+    roots.add(dir);
+  }
+  if (roots.size > PNPM_ROOT_MAX_COUNT) throw new Error(`${roots.size} pnpm roots (the gate covers at most ${PNPM_ROOT_MAX_COUNT}, and covering some would hide the rest)`);
+  return [...roots].sort();
+}
+
 /**
- * npm units: pnpm-workspace.yaml globs over tracked package.json files, else the root package.json. The root package.json is a
- * unit as well when the workspace file is absent, has no `packages:` (or an empty one) or declares "." (or "./"); with a
- * `packages:` list that does not name the root it is only the workspace's own manifest and is not a unit.
+ * npm units, per pnpm root (discoverPnpmRoots). Within a root: pnpm-workspace.yaml globs over the tracked package.json files, else the root's
+ * own package.json. The root package.json is a unit as well when the workspace file is absent, has no `packages:` (or an empty one) or declares
+ * "." (or "./"); with a `packages:` list that does not name the root it is only the workspace's own manifest and is not a unit. A directory
+ * belongs to the deepest root that holds it. The repository root's units are named from their package names (`@scope/x` -> `scope-x`, a
+ * collision falls back to the directory) and carry no `root`, exactly as in a repository with one root. The units of any other root are named
+ * from their directory (`apps/coderight-web` -> `apps-coderight-web`), so their scan ids carry the root path, and carry `root`.
  */
 export function discoverNpmUnits({ root, tracked, readFile, exists }) {
-  let dirs;
-  const workspaceFile = path.join(root, "pnpm-workspace.yaml");
-  if (exists(workspaceFile)) {
-    const globs = parseWorkspaceGlobs(readFile(workspaceFile));
-    const inc = globs.filter((g) => !g.startsWith("!")).map(globToRegExp);
-    const exc = globs.filter((g) => g.startsWith("!")).map((g) => globToRegExp(g.slice(1)));
-    const positive = globs.filter((g) => !g.startsWith("!"));
-    const rootDeclared = positive.length === 0 || positive.some((g) => g === "." || g === "./");
-    dirs = tracked("package.json").map((p) => path.posix.dirname(p)).filter((d) => (d === "." ? rootDeclared : inc.some((r) => r.test(d))) && !exc.some((r) => r.test(d)));
-  } else dirs = exists(path.join(root, "package.json")) ? ["."] : [];
-  dirs = [...new Set(dirs)].sort();
-  const rows = dirs.map((dir) => {
+  const roots = discoverPnpmRoots({ root, tracked, exists });
+  const manifestDirs = [...new Set(trackedNamed(tracked, "package.json").map((p) => path.posix.dirname(p)))];
+  const within = (rootDir, dir) => (rootDir === "." ? dir : dir === rootDir ? "." : dir.startsWith(`${rootDir}/`) ? dir.slice(rootDir.length + 1) : null);
+  const joined = (rootDir, rel) => (rootDir === "." ? rel : rel === "." ? rootDir : `${rootDir}/${rel}`);
+  const ownerOf = (dir) => roots.reduce((best, r) => (within(r, dir) !== null && (best === null || r.length > best.length) ? r : best), null);
+  const found = new Map();
+  for (const rootDir of roots) {
+    let dirs;
+    const workspaceFile = path.join(root, joined(rootDir, "pnpm-workspace.yaml"));
+    if (exists(workspaceFile)) {
+      const globs = parseWorkspaceGlobs(readFile(workspaceFile));
+      const inc = globs.filter((g) => !g.startsWith("!")).map(globToRegExp);
+      const exc = globs.filter((g) => g.startsWith("!")).map((g) => globToRegExp(g.slice(1)));
+      const positive = globs.filter((g) => !g.startsWith("!"));
+      const rootDeclared = positive.length === 0 || positive.some((g) => g === "." || g === "./");
+      dirs = manifestDirs.map((d) => within(rootDir, d)).filter((rel) => rel !== null && (rel === "." ? rootDeclared : inc.some((r) => r.test(rel))) && !exc.some((r) => r.test(rel))).map((rel) => joined(rootDir, rel));
+    } else dirs = exists(path.join(root, joined(rootDir, "package.json"))) ? [rootDir] : [];
+    for (const dir of dirs) if (ownerOf(dir) === rootDir) found.set(dir, rootDir);
+  }
+  const rows = [...found.keys()].sort().map((dir) => {
     let manifest;
     try { manifest = JSON.parse(readFile(path.join(root, dir, "package.json")).replace(/^/, "")); } catch (e) { throw new Error(`${dir}/package.json: ${e.message}`); }
-    return { dir, name: unitName(manifest.name, dir) };
+    const rootDir = found.get(dir);
+    return { dir, root: rootDir, name: rootDir === "." ? unitName(manifest.name, dir) : dir.replace(/\//g, "-") };
   });
   const count = new Map();
   for (const r of rows) count.set(r.name, (count.get(r.name) ?? 0) + 1);
-  return rows.map((r) => ({ name: count.get(r.name) > 1 ? unitName("", r.dir === "." ? "root" : r.dir) : r.name, dir: r.dir }));
+  const named = rows.map((r) => ({ ...r, name: count.get(r.name) > 1 && r.root === "." ? unitName("", r.dir === "." ? "root" : r.dir) : r.name }));
+  const taken = new Set();
+  for (const r of named) {
+    if (taken.has(r.name)) throw new Error(`two npm units are named ${r.name} (${r.dir}); rename one of the packages`);
+    taken.add(r.name);
+  }
+  return named.map((r) => ({ name: r.name, dir: r.dir, ...(r.root === "." ? {} : { root: r.root }) }));
 }
 
 const dirOfManifest = (m) => path.posix.dirname(m);
@@ -205,13 +269,56 @@ export function manifestTables(text) {
   return tables;
 }
 
+/**
+ * The value text of `key` in the top-level table `table` of a manifest read by manifestTables (everything from the `=` on), whether it is
+ * written under `[table]` or as the dotted root key `table.key = ...`; null when absent. No value parsing: tomlString and tomlStrings read it.
+ */
+export function tomlValue(tables, table, key) {
+  const esc = (x) => x.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+  const own = tables.get(table) ?? "";
+  const inTable = new RegExp(`^[ \\t]*${esc(key)}[ \\t]*=[ \\t]*`, "m").exec(own);
+  if (inTable) return own.slice(inTable.index + inTable[0].length);
+  const root = tables.get("preamble") ?? "";
+  const dotted = new RegExp(`^[ \\t]*${esc(table)}\\.${esc(key)}[ \\t]*=[ \\t]*`, "m").exec(root);
+  return dotted ? root.slice(dotted.index + dotted[0].length) : null;
+}
+
+/** True when the manifest has the top-level table `name`: as `[name]`, as a `[name.sub]` table, or as dotted root keys `name.key = ...`. */
+export const hasTomlTable = (tables, name) => tables.has(name) || [...tables.keys()].some((k) => k.startsWith(`${name}.`)) || new RegExp(`^[ \\t]*${name.replace(/\W/g, "\\$&")}\\.`, "m").test(tables.get("preamble") ?? "");
+
+/** The string a TOML value starts with ("basic" or 'literal'); null when the value is not a string. */
+export function tomlString(value) {
+  const m = /^(?:"((?:[^"\\\n]|\\.)*)"|'([^'\n]*)')/.exec(String(value ?? ""));
+  return m ? (m[1] !== undefined ? m[1].replace(/\\(.)/g, "$1") : m[2]) : null;
+}
+
+/**
+ * The strings of the TOML array a value starts with: "basic" and 'literal' strings, across lines, with `#` comments (and any `]` in
+ * them or in a string) skipped. [] when the value is not an array.
+ */
+export function tomlStrings(value) {
+  const s = String(value ?? "");
+  if (s[0] !== "[") return [];
+  const out = [];
+  for (let i = 1; i < s.length;) {
+    const c = s[i];
+    if (c === "]") break;
+    if (c === "#") { while (i < s.length && s[i] !== "\n") i += 1; continue; }
+    if (c === '"' || c === "'") {
+      let j = i + 1; let v = "";
+      while (j < s.length && s[j] !== c && s[j] !== "\n") { if (c === '"' && s[j] === "\\" && j + 1 < s.length) { v += s[j + 1]; j += 2; } else { v += s[j]; j += 1; } }
+      out.push(v); i = j + 1; continue;
+    }
+    i += 1;
+  }
+  return out;
+}
+
 /** The repository-relative directories a workspace manifest `exclude`s (`[workspace] exclude = [...]`); [] when none or unreadable. */
 export function workspaceExcludes(readFile, root, cargoDir) {
   let text;
   try { text = readFile(path.join(root, cargoDir === "." ? "Cargo.toml" : `${cargoDir}/Cargo.toml`)); } catch { return []; }
-  const body = manifestTables(text).get("workspace") ?? "";
-  const list = /^\s*exclude\s*=\s*\[([\s\S]*?)\]/m.exec(body)?.[1] ?? "";
-  return [...list.matchAll(/"([^"]+)"/g)].map((m) => posix(m[1]).replace(/\/+$/, "")).map((d) => (cargoDir === "." ? d : `${cargoDir}/${d}`));
+  return tomlStrings(tomlValue(manifestTables(text), "workspace", "exclude")).map((d) => posix(d).replace(/\/+$/, "")).map((d) => (cargoDir === "." ? d : `${cargoDir}/${d}`));
 }
 
 // The manifest tables whose every effect on a build is also written into Cargo.lock: a changed source ([patch.*]) and workspace
@@ -254,8 +361,10 @@ export function manifestChangeIsLockReflected(before, after) {
  * A member whose Cargo.toml is not tracked (untracked or ignored) is dropped into `skipped`, as are `untracked()` manifests.
  * Returns { present, workspaces: [{ cargoDir, units }], units, cargoDir, skipped: [{ manifest, why }] }; `units` is every workspace's
  * [{ name, crate, dir, publish, cargoDir }] and `cargoDir` the first workspace's (the repository root's when it has one).
+ * `metadata(dir)` (optional) replaces the cargo call with a reader of the same { cargoDir, members } shape (extra fields are ignored): the
+ * deferred pre-push gate passes manifestWorkspaceMetadata where no broker can run cargo.
  */
-export function discoverRustWorkspaces({ root, spawn, cargoCommand, tracked, untracked = () => [], realpath = fs.realpathSync, fixtures = [], readFile = (f) => fs.readFileSync(f, "utf8") }) {
+export function discoverRustWorkspaces({ root, spawn, cargoCommand, tracked, untracked = () => [], realpath = fs.realpathSync, fixtures = [], readFile = (f) => fs.readFileSync(f, "utf8"), metadata = null }) {
   const manifests = tracked("Cargo.toml");
   const trackedSet = new Set(manifests);
   const locks = new Set(tracked("Cargo.lock"));
@@ -283,7 +392,7 @@ export function discoverRustWorkspaces({ root, spawn, cargoCommand, tracked, unt
       if (!locks.has(`${dir}/Cargo.lock`)) { skipped.push({ manifest: m, why: `below the Cargo workspace ${parent.cargoDir} with no committed Cargo.lock, so its build is not reproducible; gated through the consumer rows of the crate it exercises` }); continue; }
     }
     let found;
-    try { found = workspaceMetadata({ root, spawn, cargoCommand, dir, realpath }); } catch (e) {
+    try { found = metadata ? metadata(dir) : workspaceMetadata({ root, spawn, cargoCommand, dir, realpath }); } catch (e) {
       if (!parent) throw e;
       skipped.push({ manifest: m, why: `below the Cargo workspace ${parent.cargoDir} but not one of its members, and cargo refuses it on its own (${String(e.message).replace(/^cargo metadata failed: /, "").replace(/ \(in [^)]*\)$/, "")})` });
       continue;
@@ -306,6 +415,27 @@ export function discoverRustWorkspaces({ root, spawn, cargoCommand, tracked, unt
   return { present: true, workspaces, units, cargoDir: workspaces[0]?.cargoDir ?? ".", skipped };
 }
 
+// ---- pre-push input and lock scope ------------------------------------------------------------------------
+
+/**
+ * git's pre-push stdin: one "<local ref> <local sha> <remote ref> <remote sha>" per line, the four fields joined by single ASCII spaces.
+ * Git forbids an ASCII space in a ref name but allows Unicode whitespace (U+00A0, U+2003, U+3000, ...), so the split is on " " alone: a
+ * whitespace split would cut such a ref into extra fields and the line would vanish. Blank lines are skipped; any other line that is not
+ * four non-empty fields is returned in `malformed` ({ number, line }), never dropped. Returns { lines: [{ localRef, localSha, remoteRef,
+ * remoteSha }], malformed }.
+ */
+export function parsePushLines(stdin) {
+  const lines = []; const malformed = [];
+  String(stdin ?? "").split("\n").forEach((raw, index) => {
+    const line = raw.replace(/\r$/, "");
+    if (line === "") return;
+    const f = line.split(" ");
+    if (f.length !== 4 || f.some((x) => x === "")) { malformed.push({ number: index + 1, line }); return; }
+    lines.push({ localRef: f[0], localSha: f[1], remoteRef: f[2], remoteSha: f[3] });
+  });
+  return { lines, malformed };
+}
+
 /**
  * The crates a lock-reflected workspace change reaches (the lock graph CI's selection uses): a Cargo.lock change, a vendor/ change
  * (the vendored crate is a lock package), and a workspace manifest change confined to the tables the lock also records
@@ -351,8 +481,18 @@ export function lockScope({ changed, cargoDir = ".", unitNames, showBase, readLo
  * gate binary is the root node_modules/.bin/rightkit-gate, else any workspace package's (up to three levels down: tauri-app-next,
  * apps/*, packages/*), else `pnpm exec rightkit-gate`, else node with a package-relative path when pnpm is absent; the line it
  * chose is printed once. No absolute path is written: everything is resolved from git at run time.
+ *
+ * `packages` (default none) is the multi-root form: the repository-relative directories of the packages that declare @rightkit/release when the
+ * repository root does not declare it (CutRight's apps/cutright, HeardRight's tauri-app-next). Each one's node_modules/.bin/rightkit-gate is tried
+ * right after the root's (the glob above stops three levels down), and the pnpm fallback runs in the first of them (`pnpm --dir <package> exec`;
+ * pnpm at the root of such a repository has no rightkit-gate to run). With none, the text is exactly what 0.6.4 and 0.6.5 wrote
+ * (fixtures/published-gate-hooks.json holds its digest, and a repository whose root installs the package must keep getting it, byte for byte,
+ * or the committed hook of every app copied from the template stops being "already current"). `nodePath` and every package are written into
+ * a shell script: installHook passes only plain relative paths (hookGatePlan).
  */
-export function hookText(nodePath) {
+export function hookText(nodePath, packages = []) {
+  const bins = packages.map((dir) => ` ${dir}/node_modules/.bin/rightkit-gate`).join("");
+  const pnpmExec = packages.length ? `pnpm --dir ${packages[0]} exec rightkit-gate` : "pnpm exec rightkit-gate";
   return `#!/bin/sh
 # Mandatory local check and gate before every push (rightkit-gate install-hook). Never bypass with --no-verify.
 cd "$(git rev-parse --show-toplevel)" || exit 1
@@ -365,17 +505,17 @@ if [ -x "$own" ]; then
   echo "rightkit-gate: running $own" >&2
   "$own" "$@" < "$stdin" || exit $?
 fi
-# The gate binary: the root install, any workspace package's install, then pnpm exec.
+# The gate binary: the root install, ${packages.length ? "the install of each package that declares @rightkit/release, any other workspace package's install, then pnpm exec in the first of them" : "any workspace package's install, then pnpm exec"}.
 found=""
-for bin in node_modules/.bin/rightkit-gate */node_modules/.bin/rightkit-gate */*/node_modules/.bin/rightkit-gate */*/*/node_modules/.bin/rightkit-gate; do
+for bin in node_modules/.bin/rightkit-gate${bins} */node_modules/.bin/rightkit-gate */*/node_modules/.bin/rightkit-gate */*/*/node_modules/.bin/rightkit-gate; do
   if [ -x "$bin" ]; then found="$bin"; break; fi
 done
 if [ -n "$found" ]; then
   echo "rightkit-gate: using $found" >&2
   rightkit_gate() { "$found" "$@"; }
 elif command -v pnpm >/dev/null 2>&1; then
-  echo "rightkit-gate: using pnpm exec rightkit-gate" >&2
-  rightkit_gate() { pnpm exec rightkit-gate "$@"; }
+  echo "rightkit-gate: using ${pnpmExec}" >&2
+  rightkit_gate() { ${pnpmExec} "$@"; }
 else
   echo "rightkit-gate: using node ${nodePath}" >&2
   rightkit_gate() { node "${nodePath}" "$@"; }
@@ -405,7 +545,6 @@ exit 0
 // names are chained; anything else is reported and skipped, never interpolated.
 const HOOK_FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 const chainableHook = (name) => !name.endsWith(".sample") && HOOK_FILE_NAME.test(name);
-
 // ---- result cache inputs ------------------------------------------------------------------------------------
 
 // The build inputs that change how every crate compiles, relative to the Cargo workspace root, plus the gate's own config.
@@ -568,7 +707,7 @@ const plainRelative = (p) => typeof p === "string" && p !== "" && !path.posix.is
  *   when declared. Without a declaration, a closure source that navigates out of its crate at run time without a literal path
  *   (externalInputs `leavesCrate`: workspace root, current_dir, a bare "..", the manifest directory's parent) keys the scan on the
  *   whole HEAD tree, since its tests may read anything.
- * - An npm package scan (test:npm, tsc, eslint) keys on the package's workspace closure (its `workspace:` dependencies,
+ * - An npm package scan (test:npm, tsc, eslint, biome) keys on the package's workspace closure (its `workspace:` dependencies,
  *   transitively, by package name) and the root npm inputs; test:scripts-ci on scripts/, ci/, .github/, packages/release and the
  *   root install graph. Every other class B scan (generated-docs, swift-build) uses the whole tree.
  * - Class A: cargo-deny, cargo-audit, pnpm-audit, pnpm-lockfile and advisory-exceptions are never cached (live answers); rustfmt,
@@ -577,6 +716,9 @@ const plainRelative = (p) => typeof p === "string" && p !== "" && !path.posix.is
  */
 // Root npm inputs every package scan reads: the install graph and the shared tool configuration.
 const SHARED_NPM_INPUTS = ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", ".npmrc", "tsconfig.json", "tsconfig.base.json", "eslint.config.js", "eslint.config.mjs", ".eslintrc.json", "biome.json", "vitest.config.ts", "vitest.config.mjs", "vitest.workspace.ts"];
+// ESLint and Biome look their configuration up from the package directory through every ancestor. A config in an ancestor directory (or of another
+// name than the shared list above) is part of a package's key only when the commit has it, so a repository without one keeps the key it had.
+const LINT_CONFIG_NAMES = [...ESLINT_CONFIG_FILES, ...BIOME_CONFIG_FILES];
 // The gate's own test suite reads the CI scripts, the gate config and the release package it imports from.
 const SCRIPTS_CI_INPUTS = ["scripts", "ci", ".github", "packages/release", "package.json", "pnpm-lock.yaml"];
 
@@ -597,7 +739,7 @@ export function buildCacheDigest({ objectId, headTree, rustUnits = [], npmUnits
   };
   let npmByPkgName = null;
   const npmClosure = (unit) => {
-    if (npmByPkgName === null) { npmByPkgName = new Map(); for (const u of npmUnits) { const m = npmManifest(u); if (m?.name) npmByPkgName.set(m.name, u); } }
+    if (npmByPkgName === null) { npmByPkgName = new Map(); for (const u of npmUnits) { const m = npmManifest(u); if (m?.name) npmByPkgName.set(`${u.root ?? "."}\0${m.name}`, u); } }
     const seen = new Map([[unit.name, unit]]); const stack = [unit]; let unresolved = false;
     while (stack.length) {
       const u = stack.pop(); const m = npmManifest(u);
@@ -605,7 +747,7 @@ export function buildCacheDigest({ objectId, headTree, rustUnits = [], npmUnits
       for (const section of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
         for (const [name, spec] of Object.entries(m[section] ?? {})) {
           if (!/^(workspace:|link:|file:)/.test(String(spec))) continue;
-          const dep = npmByPkgName.get(name);
+          const dep = npmByPkgName.get(`${u.root ?? "."}\0${name}`);
           if (!dep) { unresolved = true; continue; }
           if (!seen.has(dep.name)) { seen.set(dep.name, dep); stack.push(dep); }
         }
@@ -613,6 +755,18 @@ export function buildCacheDigest({ objectId, headTree, rustUnits = [], npmUnits
     }
     return { members: [...seen.values()].sort((a, b) => (a.name < b.name ? -1 : 1)), unresolved };
   };
+  // The npm inputs shared by a set of units: the repository root's (always, null when absent: the key a one-root repository has always had),
+  // the same files of every other pnpm root the units belong to, and the linter configuration of their ancestor directories that the commit has.
+  const sharedNpmInputs = (members) => {
+    const required = new Set(SHARED_NPM_INPUTS); const optional = new Set();
+    for (const m of members) {
+      if ((m.root ?? ".") !== ".") for (const p of SHARED_NPM_INPUTS) required.add(inWs(m.root, p));
+      for (const dir of ancestorDirsOf(m.dir)) if (dir !== m.dir) for (const f of LINT_CONFIG_NAMES) optional.add(inWs(dir, f));
+    }
+    const nested = [...required].filter((p) => !SHARED_NPM_INPUTS.includes(p)).sort();
+    const extra = [...optional].filter((p) => !required.has(p)).sort();
+    return [...SHARED_NPM_INPUTS, ...nested].map((p) => [p, idOf(p)]).concat(extra.map((p) => [p, idOf(p)]).filter(([, id]) => id !== null && id !== undefined));
+  };
   // A unit belongs to the Cargo workspace it names (rustUnits[].cargoDir, else the global one) and is a package of that workspace's
   // own lock under its crate name (rustUnits[].crate, else its name); its closure never crosses into another workspace.
   const wsOf = (u) => u.cargoDir ?? cargoDir;
@@ -667,11 +821,11 @@ export function buildCacheDigest({ objectId, headTree, rustUnits = [], npmUnits
       if (!unit) {
         if (typeof readBlob !== "function") return whole();
         // npm package scans: the package's workspace closure plus the root npm inputs.
-        const npmMatch = /^(test:npm|tsc|eslint):(.+)$/.exec(scan.id);
+        const npmMatch = /^(test:npm|tsc|eslint|biome):(.+)$/.exec(scan.id);
         if (npmMatch && npmByUnit.has(npmMatch[2])) {
           const { members, unresolved } = npmClosure(npmByUnit.get(npmMatch[2]));
           if (unresolved) return whole();
-          return canonicalJson({ kind: "npm", id: scan.id, members: members.map((m) => [m.name, m.dir, idOf(m.dir)]), shared: SHARED_NPM_INPUTS.map((p) => [p, idOf(p)]) });
+          return canonicalJson({ kind: "npm", id: scan.id, members: members.map((m) => [m.name, m.dir, idOf(m.dir)]), shared: sharedNpmInputs(members) });
         }
         if (scan.id === "test:scripts-ci") return canonicalJson({ kind: "dirs", id: scan.id, inputs: SCRIPTS_CI_INPUTS.map((p) => [p, idOf(p)]) });
         return whole();
@@ -765,36 +919,67 @@ export function quietLeaseLane(o, { tag = "rightkit-gate:", reason = "rightkit-g
   };
 }
 
-// ---- command resolution -------------------------------------------------------------------------------------
 
-// Cargo only through the broker: `rustright cargo`, or a `cargo` on PATH that is the managed shim (it runs cargo-guard.mjs).
-function resolveCargoCommand(o) {
-  const which = (cmd) => {
-    const r = o.spawn(o.platform === "win32" ? "where" : "which", [cmd]);
-    return failed(r) ? [] : text(r).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-  };
-  if (which("rustright").length) return ["rustright", "cargo"];
-  const first = which("cargo")[0];
-  if (first) { try { if (o.readFile(first).includes("cargo-guard.mjs")) return ["cargo"]; } catch { /* unreadable: not the shim */ } }
-  return null;
-}
 
 // ---- install-hook -------------------------------------------------------------------------------------------
 
-/** The first tracked package.json (or the root one when git cannot list) that declares @rightkit/release, or is that package itself. */
-function releaseProvider(o, root, git) {
+/**
+ * The tracked package.json files (the root one when git cannot list) that matter to the hook: `provider` is the first that declares
+ * @rightkit/release or is that package itself, `declaring` the directories of every one that declares it ("." for the root; the package itself is
+ * not one: it installs nothing of itself).
+ */
+function releasePackages(o, root, git) {
   let files = ["package.json"];
   const listed = git("ls-files", "-z", "--", ":(glob)**/package.json");
   if (!failed(listed)) files = text(listed).split("\0").filter(Boolean).map(posix);
+  let provider = null; const declaring = [];
   for (const file of files) {
     const abs = path.join(root, file);
     if (!o.exists(abs)) continue;
     let manifest;
     try { manifest = JSON.parse(o.readFile(abs).replace(/^\uFEFF/, "")); } catch { continue; }
-    if (manifest?.name === "@rightkit/release") return file;
-    for (const section of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) if (manifest?.[section] && Object.hasOwn(manifest[section], "@rightkit/release")) return file;
+    if (manifest?.name === "@rightkit/release") { provider ??= file; continue; }
+    if (["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"].some((section) => manifest?.[section] && Object.hasOwn(manifest[section], "@rightkit/release"))) {
+      provider ??= file;
+      declaring.push(path.posix.dirname(file));
+    }
   }
-  return null;
+  return { provider, declaring: [...new Set(declaring)].sort() };
+}
+
+// Where a package installs the gate, below its own directory. pnpm links it there for a package that declares @rightkit/release, so the path is the
+// same for every version (node_modules/.pnpm/@rightkit+release@x.y.z/... is the store copy it points at, and goes stale with each bump).
+const GATE_IN_PACKAGE = "node_modules/@rightkit/release/bin/rightkit-gate.mjs";
+// What may be written into the committed shell script: a plain relative path of letters, digits and _ - . @ + /, no `..`, no `.` segment, no
+// leading dash (it would read as an option of `pnpm --dir`).
+const HOOK_PATH_SEGMENT = /^(?!\.{1,2}$)[A-Za-z0-9_@.+-]+$/;
+export const hookPathIsPlain = (value) => typeof value === "string" && value !== "" && !value.startsWith("-") && value.split("/").every((segment) => HOOK_PATH_SEGMENT.test(segment));
+
+/**
+ * What the pre-push hook is told about where the gate lives: { nodePath, packages, unsafe }. `nodePath` is the last resort the hook runs with
+ * node, `packages` the extra directories hookText searches (multi-root form), `unsafe` the declaring packages whose directory cannot be written
+ * into a shell script. `declaring` is releasePackages(...).declaring; `gateFile` is where this gate runs from.
+ *
+ * A function of what the repository's package.json files declare, never of what is installed: the same tree gives the same hook on a fresh
+ * clone, an exports checkout, after `pnpm install` and after a version bump, so `install-hook` (a `prepare` script) never meets a hook it
+ * wrote earlier as one that "already exists and differs". It takes no `exists`, so that cannot creep back in. Always a stable,
+ * version-independent path relative to the repository, never one outside it, absolute, or inside the pnpm store:
+ *   1. The root declares @rightkit/release (whatever else does): its link and no extra packages, the hook 0.6.4 and 0.6.5 wrote (Pulse declares
+ *      it at the root and in hub/; RightKit itself at the root).
+ *   2. Only packages declare it (CutRight's apps/cutright, HeardRight's tauri-app-next): the link of the first of them in sorted order, whichever is
+ *      installed, and every one of them is searched.
+ *   3. No package.json declares it (a checkout of the package itself that nothing depends on), or only under a directory the hook cannot name: if
+ *      this gate runs from inside the repository and not from a node_modules, its path from the root, else the root's link, never a path
+ *      outside the repository. This is the one case that reads where the gate runs from, because the repository says nothing.
+ */
+export function hookGatePlan({ root, gateFile, declaring }) {
+  const plain = declaring.filter((d) => d !== "." && hookPathIsPlain(d));
+  const unsafe = declaring.filter((d) => d !== "." && !hookPathIsPlain(d));
+  if (declaring.includes(".")) return { nodePath: GATE_IN_PACKAGE, packages: [], unsafe };
+  if (plain.length) return { nodePath: `${plain[0]}/${GATE_IN_PACKAGE}`, packages: plain, unsafe };
+  const relative = posix(path.relative(root, gateFile));
+  const inside = relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative) && !relative.split("/").includes("node_modules") && hookPathIsPlain(relative);
+  return { nodePath: inside ? relative : GATE_IN_PACKAGE, packages: [], unsafe };
 }
 
 // The advisory ownership pre-commit step (`right-release hooks install`, ownership-hooks.mjs) runs the pinned @rightkit/release, so
@@ -806,9 +991,10 @@ async function installHook(o, root, force) {
   const git = (...a) => o.spawn("git", a, { cwd: root });
   const hooksDir = path.join(root, ".githooks");
   const hookPath = path.join(hooksDir, "pre-push");
-  const installed = "node_modules/@rightkit/release/bin/rightkit-gate.mjs";
-  const nodePath = o.exists(path.join(root, installed)) ? installed : posix(path.relative(root, fileURLToPath(import.meta.url)));
-  const wanted = hookText(nodePath);
+  const { provider, declaring } = releasePackages(o, root, git);
+  const { nodePath, packages, unsafe } = hookGatePlan({ root, gateFile: o.gateFile, declaring });
+  if (unsafe.length) o.err(`rightkit-gate: WARNING: the pre-push hook does not look for the gate in ${unsafe.join(", ")}: not a plain directory name (letters, digits and _ - . @ + only, with / between); it still finds a root or workspace install by glob.`);
+  const wanted = hookText(nodePath, packages);
   const hasHook = o.exists(hookPath);
   const current = hasHook ? o.readFile(hookPath).replace(/\r\n/g, "\n") : null;
   if (hasHook && current !== wanted && !force) {
@@ -869,30 +1055,276 @@ async function installHook(o, root, force) {
     if (failed(set)) { o.err(`rightkit-gate: git config core.hooksPath failed: ${why(set)}`); return 2; }
     done.push(`set core.hooksPath to .githooks${existingPath ? ` (was ${existingPath})` : ""}`);
   }
+  // The agent side of the one door: a Claude Code PreToolUse hook in the repository's .claude/settings.json runs door-policy.mjs on every
+  // shell command, on every host (the broker-less cloud included), and denies any build that does not go through rightkit-gate.
+  const agentHookFile = "node_modules/@rightkit/release/bin/rightkit-agent-hook.mjs";
+  const agentHook = o.exists(path.join(root, agentHookFile)) ? agentHookFile : posix(path.relative(root, fileURLToPath(new URL("./rightkit-agent-hook.mjs", import.meta.url))));
+  const settingsPath = path.join(root, ".claude", "settings.json");
+  let settings = {};
+  if (o.exists(settingsPath)) { try { settings = JSON.parse(o.readFile(settingsPath)); } catch { o.err("rightkit-gate: .claude/settings.json is not JSON; the agent hook was not added"); settings = null; } }
+  if (settings) {
+    const command = `node ${agentHook}`;
+    const pre = Array.isArray(settings.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+    const has = pre.some((entry) => (entry.hooks ?? []).some((h) => typeof h.command === "string" && h.command.includes("rightkit-agent-hook")));
+    if (has) done.push(".claude/settings.json agent hook already present");
+    else {
+      settings.hooks = { ...(settings.hooks ?? {}), PreToolUse: [...pre, { matcher: "Bash", hooks: [{ type: "command", command }] }] };
+      try { o.mkdir(path.dirname(settingsPath), { recursive: true }); } catch { /* exists */ }
+      o.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+      done.push("added the one-door agent hook to .claude/settings.json (commit it)");
+    }
+  }
   for (const line of done) o.out(`rightkit-gate: ${line}`);
   const chained = own.length ? own.map((name) => (name === "pre-push" ? "pre-push (run first, then the gate)" : name)) : [];
   o.out(`rightkit-gate: chained hooks from .git/hooks: ${chained.length ? chained.join(", ") : "none"}${own.includes("pre-push") ? "" : "; the pre-push hook still runs .git/hooks/pre-push first if one appears later"}`);
   if (!ownership) o.out(`rightkit-gate: no ownership pre-commit step: ${PINNED_CLI} is not installed here; install @rightkit/release, then run install-hook again`);
   const files = [".githooks/pre-push", ...trampolines.map((t) => `.githooks/${t.name}`)];
-  o.out(`rightkit-gate: commit the hooks with executable mode (git add --chmod=+x ${files.join(" ")}); the pre-push hook finds rightkit-gate in node_modules/.bin of the repository root, else of any workspace package, else through \`pnpm exec\`.`);
-  const provider = releaseProvider(o, root, git);
+  o.out(`rightkit-gate: commit the hooks with executable mode (git add --chmod=+x ${files.join(" ")}); the pre-push hook finds rightkit-gate in node_modules/.bin of the repository root, ${packages.length ? `else of ${packages.join(", ")} (the packages that declare @rightkit/release), else of any workspace package, else through \`pnpm --dir ${packages[0]} exec\`` : "else of any workspace package, else through \`pnpm exec\`"}.`);
   if (!provider) o.err("rightkit-gate: WARNING: no package.json in this repository depends on @rightkit/release, so the pre-push hook cannot find the rightkit-gate binary; add @rightkit/release as a devDependency of the root or of a workspace package and install.");
   else o.out(`rightkit-gate: @rightkit/release is declared in ${provider}`);
   return 0;
 }
 
+// ---- the stages: rightkit-gate --to <stage> --------------------------------------------------------------------------------
+
+/**
+ * Runs every stage up to `--to`, in order, for HEAD: check (class A), compile (the whole gate over every file), then, through the existing
+ * owners, package (source QA, then `right-release build`, which seals the exact artifact set), qualify (installed QA on that sealed set)
+ * and release (`right-release upload` of that same sealed set). Stops at the first stage that fails. check and compile are reused from
+ * the receipt only when every bound input is unchanged; the right-release stages run under a live door run, so they refuse any other
+ * caller (gate-stages.mjs requireDoorRun).
+ */
+async function runStages(o, args, root, git, io) {
+  const option = (name) => { const i = args.indexOf(name); return i < 0 ? undefined : args[i + 1]; };
+  const tag = "rightkit-gate:";
+  const to = option("--to");
+  if (to === "dev" || to === "test") return await runWorktreeCompile(o, args, root, git, io, to);
+  const stages = stagesTo(to);
+  if (!stages) { o.err(`${tag} --to must be one of ${STAGES.join(", ")}`); return 2; }
+  const platform = option("--platform");
+  const tier = option("--tier");
+  if (stages.includes("package") && !["mac", "win"].includes(platform)) { o.err(`${tag} --to ${to} needs --platform mac|win`); return 2; }
+  if (stages.includes("release") && !["patch", "update"].includes(tier)) { o.err(`${tag} --to release needs --tier patch|update (chosen explicitly, never defaulted)`); return 2; }
+  const commit = text(git("rev-parse", "HEAD")).trim();
+  const tree = text(git("rev-parse", "HEAD^{tree}")).trim();
+  const common = text(git("rev-parse", "--git-common-dir")).trim();
+  if (!/^[0-9a-f]{40}$/.test(commit) || !tree || !common) { o.err(`${tag} cannot read HEAD and the git directory`); return 2; }
+  const commonDir = path.resolve(root, common);
+  const dirty = git("status", "--porcelain", "--untracked-files=no");
+  if (failed(dirty) || text(dirty).trim()) { o.err(`${tag} BLOCKED: the checkout differs from HEAD; every stage works on the commit, so commit or stash first`); return 1; }
+
+  const which = (cmd) => { const r = o.spawn(o.platform === "win32" ? "where" : "which", [cmd]); return failed(r) ? [] : text(r).split(/\r?\n/).map((l) => l.trim()).filter(Boolean); };
+  const executor = (o.resolveExecutor ?? resolveExecutor)({ env: o.env, platform: o.platform, exists: o.exists, which, readFile: o.readFile });
+  if (executor.kind === "refuse") { o.err(`${tag} BLOCKED: ${executor.problem}`); return 1; }
+  const version = (cmd, a) => { const r = o.spawn(cmd, a, { cwd: root }); return failed(r) ? null : text(r).trim().split(/\r?\n/)[0]; };
+  const listed = git("ls-tree", "-r", "--name-only", "-z", "HEAD");
+  const lockFiles = {};
+  for (const f of failed(listed) ? [] : text(listed).split("\0").filter((x) => /(^|\/)(Cargo\.lock|pnpm-lock\.yaml)$/.test(x))) {
+    const shown = git("show", `HEAD:${f}`); if (!failed(shown)) lockFiles[f] = text(shown);
+  }
+  const binding = bindingOf({
+    tree, lockFiles, gateFile: fileURLToPath(import.meta.url), executor: executor.kind,
+    toolchain: { classA: { "cargo-deny": version("cargo-deny", ["--version"]), "cargo-audit": version("cargo-audit", ["--version"]), actionlint: version("actionlint", ["-version"]), shellcheck: version("shellcheck", ["--version"]) }, node: process.version, rustc: version(executor.kind === "broker" && executor.cargo[0] === "rustright" ? "rustright" : "rustc", executor.kind === "broker" && executor.cargo[0] === "rustright" ? ["rustc", "-V"] : ["-V"]), pnpm: version("pnpm", ["--version"]) },
+  });
+  // Release writes to R2. The write credential lives only in the trusted publisher: a GitHub Actions job in the protected
+  // publication environment, which sets RIGHTKIT_PUBLISHER=github-environment. Hosts and agents never hold it, so the door refuses the
+  // stage anywhere else rather than fail half way through an upload.
+  if (stages.includes("release") && !(o.env.GITHUB_ACTIONS === "true" && o.env.RIGHTKIT_PUBLISHER === "github-environment")) {
+    o.err(`${tag} BLOCKED: --to release runs only in the trusted publisher (the release workflow's protected publication job). Run --to qualify here, then dispatch the release workflow for ${commit.slice(0, 12)}`);
+    return 1;
+  }
+  // --receipt-in <file>: the receipt an earlier job of the same pipeline wrote (another runner: CI's package job, then its qualify and
+  // publish jobs). It is taken only for this commit and the same source binding (tree, lockfiles, gate); it then stands in for the
+  // stages it records, and the sealed bytes on disk must still hash to its manifest digest before anything uses them.
+  const receiptIn = option("--receipt-in");
+  if (receiptIn !== undefined) {
+    let imported = null;
+    try { imported = JSON.parse(o.readFile(path.resolve(o.cwd, receiptIn))); } catch { /* refused below */ }
+    if (!imported || imported.schema !== RECEIPT_SCHEMA || imported.commit !== commit || !sameSource(imported.binding, binding)) {
+      o.err(`${tag} BLOCKED: --receipt-in ${receiptIn} is not a ${RECEIPT_SCHEMA} receipt for ${commit.slice(0, 12)} with this tree, these lockfiles and this gate`);
+      return 1;
+    }
+    (o.writeReceipt ?? writeReceipt)({ commonDir, receipt: imported });
+  }
+  const previous = (o.readReceipt ?? readReceipt)({ commonDir, commit });
+  // Same host and inputs: every recorded stage counts. Same source on another host: only the stages bound to sealed bytes (package and
+  // later) carry over; check and compile run again here.
+  const receipt = previous && sameBinding(previous.binding, binding) ? previous
+    : previous && sameSource(previous.binding, binding) ? { ...previous, binding, stages: Object.fromEntries(Object.entries(previous.stages ?? {}).filter(([k]) => k !== "check" && k !== "compile")) }
+      : { schema: RECEIPT_SCHEMA, commit, binding, stages: {} };
+  const receiptOut = option("--receipt-out");
+  const save = () => {
+    (o.writeReceipt ?? writeReceipt)({ commonDir, receipt });
+    if (receiptOut !== undefined) o.writeFile(path.resolve(o.cwd, receiptOut), `${JSON.stringify(receipt, null, 2)}\n`);
+  };
+
+  const cli = fileURLToPath(new URL("../cli/right-release.mjs", import.meta.url));
+  const rightRelease = (stage, cliArgs) => {
+    const run = startRun({ commonDir, commit, tree, stage });
+    try {
+      o.out(`${tag} [${stage}] right-release ${cliArgs.join(" ")}`);
+      const r = (o.spawnInherit ?? ((cmd, a, opts) => spawnInherit(cmd, a, { ...opts, stdio: "inherit" })))(process.execPath, [cli, ...cliArgs], { cwd: root, env: { ...o.env, ...run.env } });
+      return r.status === 0;
+    } finally { endRun(run); }
+  };
+
+  o.out(`${tag} --to ${to} for ${commit.slice(0, 12)}: ${stages.join(" -> ")}; executor ${executor.kind}`);
+  // A later stage on the sealed bytes: check, compile and package already passed for them (in this receipt) and the bytes on disk are
+  // the ones they sealed, so they are not run again.
+  const sealedNow = receipt.stages.package?.ok ? (o.sealedFor ?? sealedFor)({ root, commit, platform }) : null;
+  const sealedIntact = Boolean(sealedNow && sealedNow.id === receipt.stages.package.sealed && sealedNow.digest === receipt.stages.package.manifestSha256);
+  for (const stage of stages) {
+    if ((stage === "check" || stage === "compile") && receipt.stages[stage]?.ok) { o.out(`${tag} [${stage}] already passed for this exact input (commit, tree, lockfiles, gate, toolchain)`); continue; }
+    if ((stage === "check" || stage === "compile" || stage === "package") && sealedIntact) {
+      o.out(`${tag} [${stage}] already passed for the sealed set ${sealedNow.id} (manifest ${sealedNow.digest.slice(0, 12)})`); continue;
+    }
+    // The publisher (another runner, often another OS) cannot repeat installed QA; it takes the qualify result recorded for exactly
+    // these sealed bytes. --to qualify itself always runs it.
+    if (stage === "qualify" && to !== "qualify" && sealedIntact && receipt.stages.qualify?.ok && receipt.stages.qualify.manifestSha256 === sealedNow.digest) {
+      o.out(`${tag} [qualify] already passed for the sealed set ${sealedNow.id} (manifest ${sealedNow.digest.slice(0, 12)})`); continue;
+    }
+    // The publisher only uploads. It never checks out a build environment, signs or runs installed QA, so every earlier stage must
+    // already stand in its receipt for exactly the sealed bytes on disk; anything else is refused, never rebuilt or requalified here.
+    if (to === "release" && stage !== "release") {
+      o.err(`${tag} BLOCKED: [${stage}] --to release only uploads: the receipt must already record ${stage} for the sealed bytes on disk (${sealedNow ? `manifest ${sealedNow.digest.slice(0, 12)}` : "none found"}); run --to qualify on the host and stage again`);
+      return 1;
+    }
+    let ok = false; const at = new Date().toISOString(); let extra = {};
+    if (stage === "check") ok = (await (o.runCheck ?? (() => main(["check", "--commit", "HEAD"], { ...io, cwd: root })))()) === 0;
+    else if (stage === "compile") {
+      // A Tauri crate with externalBin needs its sidecars in src-tauri/binaries before it compiles (its build script refuses
+      // otherwise), so every release config that declares `sidecars` is staged first, through right-release under this door run.
+      const listedConfigs = git("ls-tree", "-r", "--name-only", "-z", "HEAD");
+      const sidecarConfigs = (failed(listedConfigs) ? [] : text(listedConfigs).split("\0").filter((f) => /(^|\/)right-release\.config\.(json|mjs)$/.test(f)))
+        .filter((f) => { try { return /\bsidecars\b/.test(o.readFile(path.join(root, f))); } catch { return false; } });
+      ok = true;
+      for (const config of sidecarConfigs) if (!rightRelease(stage, ["stage-sidecar", "--config", config])) { ok = false; break; }
+      if (ok) ok = (await (o.runCompile ?? (() => main(["--all"], { ...io, cwd: root, readStdin: () => "" })))()) === 0;
+    }
+    else if (stage === "package") {
+      ok = rightRelease(stage, ["qa", "--stage", "source", "--platform", platform]) && rightRelease(stage, ["build", "--platform", platform]);
+      const sealed = ok ? (o.sealedFor ?? sealedFor)({ root, commit, platform }) : null;
+      if (ok && !sealed) { o.err(`${tag} [package] the build reported success but sealed nothing for ${commit.slice(0, 8)} on ${platform}`); ok = false; }
+      if (sealed) extra = { platform, sealed: sealed.id, manifestSha256: sealed.digest };
+    } else {
+      const sealed = receipt.stages.package?.ok ? receipt.stages.package : null;
+      const current = sealed ? (o.sealedFor ?? sealedFor)({ root, commit, platform }) : null;
+      if (!sealed || !current || current.id !== sealed.sealed || current.digest !== sealed.manifestSha256) {
+        o.err(`${tag} BLOCKED: [${stage}] needs the sealed set the package stage produced for this commit, unchanged (sealed manifest digest)`);
+        ok = false;
+      } else if (stage === "qualify") {
+        ok = rightRelease(stage, ["qa", "--stage", "installed", "--platform", platform, "--release", sealed.sealed]);
+        extra = { sealed: sealed.sealed, manifestSha256: sealed.manifestSha256 };
+      } else {
+        if (!receipt.stages.qualify?.ok || receipt.stages.qualify.manifestSha256 !== sealed.manifestSha256) { o.err(`${tag} BLOCKED: [release] the sealed set was not qualified (installed QA) in this door run's receipt`); ok = false; }
+        else { ok = rightRelease(stage, ["upload", "--release", sealed.sealed, "--platform", platform, "--tier", tier]); extra = { sealed: sealed.sealed, manifestSha256: sealed.manifestSha256, tier }; }
+      }
+    }
+    receipt.stages[stage] = { ok, at, ...extra };
+    save();
+    if (!ok) { o.err(`${tag} --to ${to} stopped at ${stage}: nothing after it ran`); return 1; }
+  }
+  o.out(`${tag} --to ${to} passed: ${stages.join(", ")}`);
+  return 0;
+}
+
+/**
+ * rightkit-gate stage --platform mac|win [--tier patch|update]: hands a qualified sealed set to the trusted publisher. The host signed,
+ * sealed and qualified it (--to qualify); only the publisher holds the R2 write credential. Requires this host's receipt for HEAD with
+ * package and qualify passed on the sealed bytes as they are now. Packs the sealed directory and the receipt into the draft GitHub
+ * release `rightkit-staging-<commit>` (replacing that platform's asset), then, with --tier, dispatches RightKit's publish-app workflow
+ * (the one trusted publisher for every app) for HEAD.
+ */
+const PUBLISHER_REPO = "bogusyogi/rightkit";
+function stageForPublisher(o, args, root, git) {
+  const option = (name) => { const i = args.indexOf(name); return i < 0 ? undefined : args[i + 1]; };
+  const tag = "rightkit-gate:";
+  const platform = option("--platform");
+  const tier = option("--tier");
+  if (!["mac", "win"].includes(platform)) { o.err(`${tag} stage needs --platform mac|win`); return 2; }
+  if (tier !== undefined && !["patch", "update"].includes(tier)) { o.err(`${tag} stage --tier must be patch or update`); return 2; }
+  const commit = text(git("rev-parse", "HEAD")).trim();
+  const common = text(git("rev-parse", "--git-common-dir")).trim();
+  if (!/^[0-9a-f]{40}$/.test(commit) || !common) { o.err(`${tag} cannot read HEAD and the git directory`); return 2; }
+  const commonDir = path.resolve(root, common);
+  const receipt = (o.readReceipt ?? readReceipt)({ commonDir, commit });
+  const pack = receipt?.stages?.package; const qual = receipt?.stages?.qualify;
+  const sealed = pack?.ok ? (o.sealedFor ?? sealedFor)({ root, commit, platform }) : null;
+  if (!pack?.ok || !qual?.ok || pack.platform !== platform || qual.manifestSha256 !== pack.manifestSha256 || !sealed || sealed.id !== pack.sealed || sealed.digest !== pack.manifestSha256) {
+    o.err(`${tag} BLOCKED: stage needs this host's receipt for ${commit.slice(0, 12)} with package and qualify passed on ${platform} and the sealed set unchanged; run rightkit-gate --to qualify --platform ${platform} first`);
+    return 1;
+  }
+  const releaseTag = `rightkit-staging-${commit}`;
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "rightkit-stage-"));
+  try {
+    const receiptFile = path.join(work, `receipt-${platform}.json`);
+    fs.writeFileSync(receiptFile, `${JSON.stringify(receipt, null, 2)}\n`);
+    const archive = path.join(work, `sealed-${platform}.tar.gz`);
+    const tar = o.spawn("tar", ["-czf", archive, "-C", root, path.join(".right-release", "sealed", sealed.id, platform)]);
+    if (failed(tar)) { o.err(`${tag} could not pack ${sealed.id}/${platform}`); return 1; }
+    const gh = (...a) => o.spawn("gh", a, { cwd: root });
+    if (failed(gh("release", "view", releaseTag))) {
+      const made = gh("release", "create", releaseTag, "--draft", "--target", commit, "--title", `staging ${commit.slice(0, 12)}`, "--notes", "Sealed and qualified sets for the trusted publisher; not a release.");
+      if (failed(made)) { o.err(`${tag} could not create the draft ${releaseTag}: ${text(made).trim()}`); return 1; }
+    }
+    const up = gh("release", "upload", releaseTag, archive, receiptFile, "--clobber");
+    if (failed(up)) { o.err(`${tag} could not upload to ${releaseTag}: ${text(up).trim()}`); return 1; }
+    o.out(`${tag} staged ${sealed.id}/${platform} (manifest ${sealed.digest.slice(0, 12)}) in draft ${releaseTag}`);
+    if (tier) {
+      // The trusted publisher is RightKit's publish-app workflow: app repositories are private and run no Actions.
+      const slug = text(gh("repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner")).trim();
+      const appDir = path.relative(root, o.cwd).replaceAll("\\", "/") || ".";
+      const run = gh("workflow", "run", "publish-app.yml", "-R", PUBLISHER_REPO, "-f", `app=${slug}`, "-f", `app_dir=${appDir}`, "-f", `source_revision=${commit}`, "-f", `tier=${tier}`, "-f", `platforms=${platform}`);
+      if (!slug || failed(run)) { o.err(`${tag} staged, but could not dispatch ${PUBLISHER_REPO} publish-app.yml: ${text(run).trim()}`); return 1; }
+      o.out(`${tag} dispatched ${PUBLISHER_REPO} publish-app.yml for ${slug}@${commit.slice(0, 12)} (${platform}, ${tier}); the publisher re-runs class A, verifies the receipt and the bytes, then uploads`);
+    }
+    return 0;
+  } finally { fs.rmSync(work, { recursive: true, force: true }); }
+}
+
+/**
+ * rightkit-gate --to dev|test [-- <right-release dev|test arguments>]: the door for the local compiles that work on the uncommitted tree.
+ * Class A runs over the working tree first (nothing compiles while it is red), then `right-release dev|test` runs under a live door
+ * run, the only way it runs at all. The executor is the same as every other stage: the broker where there is one (its own admission
+ * checks again), plain cargo on an unmanaged host, never around a managed host's broker.
+ */
+async function runWorktreeCompile(o, args, root, git, io, to) {
+  const tag = "rightkit-gate:";
+  const passthrough = args.includes("--") ? args.slice(args.indexOf("--") + 1) : [];
+  const commit = text(git("rev-parse", "HEAD")).trim();
+  const tree = text(git("rev-parse", "HEAD^{tree}")).trim();
+  const common = text(git("rev-parse", "--git-common-dir")).trim();
+  if (!/^[0-9a-f]{40}$/.test(commit) || !common) { o.err(`${tag} cannot read HEAD and the git directory`); return 2; }
+  const which = (cmd) => { const r = o.spawn(o.platform === "win32" ? "where" : "which", [cmd]); return failed(r) ? [] : text(r).split(/\r?\n/).map((l) => l.trim()).filter(Boolean); };
+  const executor = (o.resolveExecutor ?? resolveExecutor)({ env: o.env, platform: o.platform, exists: o.exists, which, readFile: o.readFile });
+  if (executor.kind === "refuse") { o.err(`${tag} BLOCKED: ${executor.problem}`); return 1; }
+  o.out(`${tag} --to ${to} on the working tree of ${commit.slice(0, 12)}: check (class A) -> right-release ${to}; executor ${executor.kind}`);
+  const checked = await (o.runCheck ?? (() => main(["check", "--worktree"], { ...io, cwd: root })))();
+  if (checked !== 0) { o.err(`${tag} --to ${to} stopped at check: nothing compiled`); return 1; }
+  const commonDir = path.resolve(root, common);
+  const run = startRun({ commonDir, commit, tree, stage: to });
+  try {
+    const cli = fileURLToPath(new URL("../cli/right-release.mjs", import.meta.url));
+    const r = (o.spawnInherit ?? ((cmd, a, opts) => spawnInherit(cmd, a, { ...opts, stdio: "inherit" })))(process.execPath, [cli, to, ...passthrough], { cwd: o.cwd, env: { ...o.env, ...run.env } });
+    return r.status === 0 ? 0 : 1;
+  } finally { endRun(run); }
+}
+
 // ---- main ---------------------------------------------------------------------------------------------------
 
 /**
  * Run the CLI. Returns the exit code (0 pass, 1 blocked or failed, 2 cannot run, 128+n cancelled). `io` overrides the
  * process, fs and output bindings so tests execute nothing real: spawn, exists, readFile, writeFile, mkdir, chmod,
- * readStdin, out, err, cwd, env, platform, abort (an AbortController).
+ * readStdin, out, err, cwd, env, platform, abort (an AbortController), runScans and findRustfmt (the scan runner and the
+ * lookup of a usable rustfmt, which the deferred Rust gate needs).
  */
 export async function main(argv, io = {}) {
   const o = {
     spawn: defaultSpawn, exists: fs.existsSync, readFile: (f) => fs.readFileSync(f, "utf8"), writeFile: fs.writeFileSync, mkdir: fs.mkdirSync, chmod: fs.chmodSync, readdir: fs.readdirSync,
     readStdin: () => { try { return process.stdin.isTTY ? "" : fs.readFileSync(0, "utf8"); } catch { return ""; } },
-    out: (m) => console.log(m), err: (m) => console.error(m), cwd: process.cwd(), env: process.env, platform: process.platform, ...io,
+    out: (m) => console.log(m), err: (m) => console.error(m), cwd: process.cwd(), env: process.env, platform: process.platform,
+    // Where this gate runs from (install-hook writes a path to it only when it is a plain path inside the repository: hookGatePlan).
+    gateFile: fileURLToPath(import.meta.url), ...io,
   };
   const args = [...argv];
   const option = (name) => { const i = args.indexOf(name); return i < 0 ? undefined : args[i + 1]; };
@@ -902,9 +1334,82 @@ export async function main(argv, io = {}) {
   }
   if (args.includes("--help") || args.includes("-h")) { o.out(USAGE); return 0; }
   const sub = args[0] && !args[0].startsWith("-") ? args[0] : null;
-  if (sub && sub !== "install-hook" && sub !== "check") { o.err(`rightkit-gate: unknown command ${JSON.stringify(sub)}\n${USAGE}`); return 2; }
-  // The app check has its own export and reads no gate state: it needs neither the base ref nor the pushed refs on stdin.
-  if (sub === "check") return (o.appCheck ?? (await import("../app-check.mjs")).main)(args.slice(1), { out: o.out, err: o.err, label: "check", cwd: o.cwd });
+  if (sub && sub !== "install-hook" && sub !== "check" && sub !== "stage") { o.err(`rightkit-gate: unknown command ${JSON.stringify(sub)}\n${USAGE}`); return 2; }
+  // `check` is the deterministic stage (Adrian, 2026-10-25: deterministic always first, one door): the app-check rules, then every
+  // class A scan (lockfiles, cargo-deny, cargo-audit, secrets, licences, manifests, workflow lint, syntax...) over the whole tree of the
+  // commit, never a diff. Nothing compiles. The RustRight broker runs exactly this before it admits any compile. `--list`,
+  // `--print-baseline` and `--only` stay app-check-only views.
+  if (sub === "check") {
+    const appCheck = await (o.appCheck ?? (await import("../app-check.mjs")).main)(args.slice(1), { out: o.out, err: o.err, label: "check", cwd: o.cwd });
+    if (args.includes("--list") || args.includes("--print-baseline") || args.includes("--only") || o.classA === false) {
+      // A view of the app rules, never a class A verdict: say so, so no caller can take its exit 0 for a full check.
+      // A green partial view exits PARTIAL_EXIT (3), never 0, so a caller that admits only exit 0 rejects it by status alone.
+      if (args.includes("--list") || args.includes("--print-baseline")) return appCheck;
+      o.err("rightkit-gate: PARTIAL: app rules only (--only); no class A scan ran, so this is not a class A result");
+      return appCheck === 0 ? PARTIAL_EXIT : appCheck;
+    }
+    const repoArg = option("--repo");
+    const checkCwd = repoArg ? path.resolve(o.cwd, repoArg) : o.cwd;
+    const classA = await main(["--class-a", ...(args.includes("--worktree") ? ["--worktree"] : ["--commit", option("--commit") ?? "HEAD"])], { ...io, cwd: checkCwd });
+    // RightKit checking itself: its own rules (line endings, consumer recipes, npm surface, version copies and the version feed, dispatcher
+    // pins, consumer locks, generated docs, temp paths: scripts/preflight.mjs) and its exports' import safety are class A for the RightKit repository. They run only when this gate is that
+    // repository's own in-tree copy, so a gate checking any other repository (the broker's pinned one included) never runs
+    // that repository's code.
+    let selfRules = 0;
+    const top = o.spawn("git", ["rev-parse", "--show-toplevel"], { cwd: checkCwd });
+    const root = failed(top) ? null : path.resolve(text(top).trim());
+    const self = o.selfPath ?? fileURLToPath(import.meta.url);
+    // RightKit's own scripts are the checked repository's code: they run only after the app rules and every class A scan passed,
+    // never after a failure, so a red tree executes nothing of its own.
+    // Compared as real, long paths (and case-blind on Windows): git prints the long form of an 8.3 short path such as RUNNER~1.
+    const canon = (p) => { let c; try { c = fs.realpathSync.native(p); } catch { c = path.resolve(p); } return process.platform === "win32" ? c.toLowerCase() : c; };
+    if (root && canon(self).startsWith(canon(root) + path.sep) && o.exists(path.join(root, "scripts", "preflight.mjs")) && appCheck === 0 && classA === 0) {
+      const launch = o.spawnInherit ?? ((cmd, a, opts) => spawnInherit(cmd, a, { ...opts, stdio: "inherit" }));
+      const selector = args.includes("--worktree") ? ["--worktree"] : ["--commit", option("--commit") ?? "HEAD"];
+      const r = launch(process.execPath, [path.join(root, "scripts", "preflight.mjs"), "--repo", root, ...selector], { cwd: root, env: o.env });
+      selfRules = r.status === 0 ? 0 : 1;
+      // And its exports import cleanly (scripts/ci/exports-import-effects.mjs: every exported module imported in a fresh, permission-
+      // limited process; an import that prints, exits or reads its argv fails), which publish.yml's scans job ran alone before. That
+      // check probes the checkout's HEAD, so it runs only when HEAD is the requested commit (or the working tree was asked for);
+      // any other commit is refused rather than proven by other bytes.
+      const effects = path.join(root, "scripts", "ci", "exports-import-effects.mjs");
+      if (selfRules === 0 && o.exists(effects)) {
+        const requested = args.includes("--worktree") ? null : option("--commit") ?? "HEAD";
+        const at = (rev) => { const v = o.spawn("git", ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`], { cwd: root }); return failed(v) ? null : text(v).trim(); };
+        // The probe exports HEAD, so a working tree whose tracked or untracked (unignored) files differ from HEAD is refused too.
+        const dirty = () => { const st = o.spawn("git", ["status", "--porcelain", "--untracked-files=all"], { cwd: root }); return failed(st) || text(st).trim() !== ""; };
+        if (requested !== null && at(requested) !== at("HEAD")) {
+          o.err(`rightkit-gate: BLOCKED: the exports import check probes the checkout's HEAD (${String(at("HEAD")).slice(0, 12)}), not the requested ${requested}; check out that commit to check it`);
+          selfRules = 1;
+        } else if (requested === null && dirty()) {
+          o.err("rightkit-gate: BLOCKED: the exports import check probes the checkout's HEAD, and the working tree differs from it; commit or stash the changes, or check --commit HEAD");
+          selfRules = 1;
+        } else {
+          // Like CI's scans job: exports that resolve to build output are INCOMPLETE here and handed, through --report, to the
+          // sealed-byte check that publication runs; without --report the probe exits 3 and a green tree could never pass.
+          const common = o.spawn("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: root });
+          const report = path.join(failed(common) ? path.join(root, ".git") : text(common).trim(), "rightkit-gate", "import-effects", "report.json");
+          const e = launch(process.execPath, [effects, "--report", report], { cwd: root, env: o.env });
+          if (e.status !== 0) selfRules = 1;
+        }
+      }
+    }
+    // A RustRight broker's check names the tree it captured for the compile: the declared inputs there (ignored files the
+    // commit does not hold) are judged too, as the bytes the compile will read.
+    let inputs = 0;
+    const captured = o.env.RIGHTKIT_COMPILE_INPUTS;
+    if (captured) {
+      const { judgeCompileInputs } = await import("../compile-inputs.mjs");
+      const judged = judgeCompileInputs(path.resolve(captured));
+      for (const i of judged.inputs) o.out(`rightkit-gate: compile input ${i.path}: ${i.files} file(s), sha256 ${i.sha256}`);
+      for (const f of judged.findings) o.err(`rightkit-gate: compile input FAIL ${f}`);
+      if (!judged.inputs.length && !judged.findings.length) o.out("rightkit-gate: no declared compile inputs in the captured tree");
+      inputs = judged.findings.length ? 1 : 0;
+    }
+    return Math.max(appCheck, classA, selfRules, inputs);
+  }
+  const classAOnly = args.includes("--class-a");
+  const classACommit = classAOnly && !args.includes("--worktree") ? (option("--commit") ?? "HEAD") : null;
   if (args.includes("--base") && (!option("--base") || option("--base").startsWith("--"))) { o.err("rightkit-gate: --base needs a ref"); return 2; }
 
   const top = o.spawn("git", ["rev-parse", "--show-toplevel"], { cwd: o.cwd });
@@ -912,16 +1417,26 @@ export async function main(argv, io = {}) {
   const root = path.resolve(text(top).trim());
   const git = (...a) => o.spawn("git", a, { cwd: root });
   if (sub === "install-hook") return await installHook(o, root, args.includes("--force"));
+  if (option("--to") !== undefined) return await runStages(o, args, root, git, io);
+  if (sub === "stage") return stageForPublisher(o, args, root, git);
 
   const planOnly = args.includes("--plan");
   let base = option("--base") ?? "origin/main";
   const tag = "rightkit-gate:";
 
   // git pre-push: "<local ref> <local sha> <remote ref> <remote sha>" per pushed ref. A plan reads no stdin.
-  if (!planOnly) {
+  // git's push lines are split on single ASCII spaces only (parsePushLines): a ref name may hold Unicode whitespace. A line that does not read as four fields
+  // (git hands the local field over verbatim, so a rev expression such as `HEAD@{1 minute ago}` or `HEAD^{/one thing}` holds spaces)
+  // refuses the push on every host and in every repository, never a line that disappears: its pushed commit could not be compared with
+  // HEAD and its remote ref could not be judged. `pushedRemoteShas` are the remote commits being replaced.
+  if (!planOnly && !classAOnly) {
     const head = text(git("rev-parse", "HEAD")).trim();
-    const lines = o.readStdin().split(/\r?\n/).map((l) => l.trim().split(/\s+/)).filter((f) => f.length === 4);
-    for (const [, localSha, remoteRef, remoteSha] of lines) {
+    const parsed = parsePushLines(o.readStdin());
+    if (parsed.malformed.length) {
+      o.err(`${tag} BLOCKED: pre-push stdin line ${parsed.malformed[0].number} is not "<local ref> <local sha> <remote ref> <remote sha>" (four fields separated by single spaces), so the pushed refs cannot all be read and the pushed commit cannot be compared with HEAD; push a plain ref (git push <remote> HEAD:<branch>)`);
+      return 1;
+    }
+    for (const { localSha, remoteRef, remoteSha } of parsed.lines) {
       if (ZERO.test(localSha)) continue; // a delete pushes no content
       if (localSha !== head) {
         o.err(`${tag} BLOCKED: pushing ${localSha.slice(0, 10)} to ${remoteRef}, but HEAD is ${head.slice(0, 10)}; broker scans read the checkout, so check the pushed commit out first (git checkout --detach ${localSha.slice(0, 10)}), push HEAD:<branch>, then return`);
@@ -931,51 +1446,16 @@ export async function main(argv, io = {}) {
     }
   }
 
-  const tracked = (name) => {
-    const r = git("ls-files", "-z", "--", `:(glob)**/${name}`);
-    if (failed(r)) throw new Error(`git ls-files failed: ${why(r)}`);
-    return text(r).split("\0").filter(Boolean).map(posix);
-  };
-  const readLive = (f) => o.readFile(f);
-
-  // Units come from the live checkout (cargo reads it); a dirty checkout then blocks below.
-  let rust; let npm; let cargoCommand = ["rustright", "cargo"];
-  try {
-    const manifests = tracked("Cargo.toml");
-    if (manifests.length) {
-      cargoCommand = resolveCargoCommand(o);
-      if (!cargoCommand) { o.err(`${tag} BLOCKED: neither \`rustright\` nor the managed cargo shim (cargo-guard.mjs) is first on PATH; plain cargo is never used`); return 1; }
-      if (!o.exists(path.join(root, GRANT_FILE))) { o.err(`${tag} BLOCKED: no local compile grant (${GRANT_FILE}); the broker refuses cargo, so the Rust units cannot be discovered or scanned`); return 1; }
-    }
-    // Untracked (not ignored) manifests only: git does not descend into ignored directories, so this stays cheap. A member of a
-    // workspace that is untracked or ignored is dropped by discoverRustWorkspaces itself.
-    const untracked = () => {
-      const r = git("ls-files", "-z", "--others", "--exclude-standard", "--", ":(glob)**/Cargo.toml");
-      return failed(r) ? [] : text(r).split("\0").filter(Boolean).map(posix);
-    };
-    // ci/gate.config.json `fixtures` (optional): directories whose manifests are consumer or sample crates, gated through the
-    // consumer rows of the crates they exercise (CI treats them the same: scripts/ci/gate.mjs consumerRowInvocations), never as units.
-    let fixtures = [];
-    try { const f = JSON.parse(o.readFile(path.join(root, GATE_CONFIG))).fixtures; if (Array.isArray(f)) fixtures = f.filter((d) => typeof d === "string"); } catch { /* no config: no fixtures */ }
-    rust = discoverRustWorkspaces({ root, spawn: (c, a, opts) => o.spawn(c, a, opts), cargoCommand, tracked, untracked, fixtures, readFile: readLive });
-    npm = discoverNpmUnits({ root, tracked, readFile: readLive, exists: o.exists });
-  } catch (e) { o.err(`${tag} BLOCKED: cannot discover the repository's units: ${e.message}`); return 1; }
-  for (const k of rust.skipped) o.out(`${tag} note: ${k.manifest} is skipped, not scanned: ${k.why}`);
-
-  // Broker scans (cargo, pnpm) read the live checkout, so it must equal HEAD where they read it: an uncommitted fix could
-  // otherwise hide a committed failure. Any change or untracked file under those paths blocks the gate.
-  if (!planOnly) {
-    const inputs = [...new Set([...rust.units.map((u) => u.dir), ...npm.map((u) => u.dir), ...rust.workspaces.map((w) => w.cargoDir), "ci", "scripts", "vendor", "Cargo.toml", "Cargo.lock", ".cargo", "rust-toolchain.toml", "rust-toolchain",
-      "deny.toml", "clippy.toml", "rustfmt.toml", "package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", ".npmrc", "eslint.config.js", "eslint.config.mjs", ".eslintrc.json", "biome.json"])];
-    const dirty = git("status", "--porcelain", "--untracked-files=all", "--", ...inputs);
-    const dirtyFiles = failed(dirty) ? [`git status failed: ${why(dirty)}`]
-      : text(dirty).split(/\r?\n/).filter(Boolean).filter((l) => !l.includes("node_modules") && !l.includes(GRANT_FILE));
-    if (dirtyFiles.length) {
-      o.err(`${tag} BLOCKED: the checkout differs from HEAD where broker scans read it; commit or stash first:`);
-      for (const l of dirtyFiles.slice(0, 20)) o.err(`  ${l}`);
-      return 1;
-    }
-  }
+  // ---- one door: the executor, then the exact snapshot every scan plans from and reads -----------------------------------
+  // The executor is chosen here, never by the caller (Adrian, 2026-10-25): the RustRight broker where this machine has it, a refusal
+  // on a broker-managed machine whose broker cannot be reached, direct cargo on any other host (a cloud container, a CI runner).
+  const which = (cmd) => { const r = o.spawn(o.platform === "win32" ? "where" : "which", [cmd]); return failed(r) ? [] : text(r).split(/\r?\n/).map((l) => l.trim()).filter(Boolean); };
+  const executor = (o.resolveExecutor ?? resolveExecutor)({ env: o.env, platform: o.platform, exists: o.exists, which, readFile: o.readFile });
+  if (executor.kind === "refuse") { o.err(`${tag} BLOCKED: ${executor.problem}`); return 1; }
+  const cargoCommand = executor.cargo;
+  // The snapshot: the commit or tree being checked (check --commit), HEAD for the gate, or the working tree (check --worktree, --plan).
+  const allFilesMode = classAOnly || args.includes("--all");
+  const snapshot = planOnly ? null : classAOnly ? classACommit : "HEAD";
 
   const ac = o.abort ?? new AbortController();
   let exportRoot = null;
@@ -983,16 +1463,66 @@ export async function main(argv, io = {}) {
   const signals = [];
   try {
     let repo = root;
-    if (!planOnly) {
+    if (snapshot) {
       exportRoot = fs.mkdtempSync(path.join(o.env.RK_GATE_TMPDIR || os.tmpdir(), "rk-gate-"));
       repo = path.join(exportRoot, "repo");
-      const made = o.spawn("git", ["archive", "--format=tar", "--prefix=repo/", "-o", path.join(exportRoot, "head.tar"), "HEAD"], { cwd: root });
-      const x = failed(made) ? made : o.spawn("tar", ["-xf", "head.tar"], { cwd: exportRoot });
-      if (failed(made) || failed(x)) { o.err(`${tag} cannot export HEAD: ${why(made) || why(x)}`); return 2; }
+      // Every file of the commit or tree: read-tree into a private index, then checkout-index. `git archive` would leave out files
+      // marked export-ignore in .gitattributes, so they would never be scanned; this export has no such exclusion.
+      const indexEnv = { ...o.env, GIT_INDEX_FILE: path.join(exportRoot, "index") };
+      const made = o.spawn("git", ["read-tree", snapshot], { cwd: root, env: indexEnv });
+      // git builds each path as <prefix><index path> with "/" separators and creates only the directories below the prefix, so the
+      // export root must exist and the prefix use "/": a "C:\\...\\repo\\" prefix made checkout-index fail on Windows
+      // (publish run 40282215043: "cannot create directory at ...\\repo\\.github").
+      fs.mkdirSync(repo, { recursive: true });
+      const x = failed(made) ? made : o.spawn("git", ["checkout-index", "--all", "--force", `--prefix=${repo.split(path.sep).join("/")}/`], { cwd: root, env: indexEnv });
+      if (failed(made) || failed(x)) { o.err(`${tag} cannot export ${snapshot}: ${why(made) || why(x)}`); return 2; }
     }
-    const diff = git("diff", "--name-only", "--diff-filter=ACMR", `${base}...HEAD`);
-    if (failed(diff)) { o.err(`${tag} cannot diff against ${base}: ${why(diff)}; pass --base <ref>`); return 2; }
-    const changed = [...new Set(text(diff).split(/\r?\n/).map((f) => f.trim()).filter(Boolean))].filter((f) => o.exists(path.join(repo, f)));
+    // Every file of the snapshot, once: units, manifests, lockfiles and the changed set are all read from what is scanned, never from
+    // the live checkout (a live edit cannot change what gets planned).
+    const listed = snapshot ? git("ls-tree", "-r", "--name-only", "-z", snapshot) : git("ls-files", "-z", "--cached", ...(classAOnly ? ["--others", "--exclude-standard"] : []));
+    if (failed(listed)) { o.err(`${tag} cannot list the files of ${snapshot ?? "the working tree"}: ${why(listed)}`); return 2; }
+    const files = text(listed).split("\0").filter(Boolean).map(posix);
+    const tracked = (name) => files.filter((f) => f === name || f.endsWith(`/${name}`));
+    const readSnap = (f) => o.readFile(f);
+
+    let rust; let npm; let npmRoots = []; let manifests = [];
+    try {
+      manifests = tracked("Cargo.toml");
+      // ci/gate.config.json `fixtures` (optional): directories whose manifests are consumer or sample crates, gated through the
+      // consumer rows of the crates they exercise (CI treats them the same), never as units.
+      let fixtures = [];
+      try { const f = JSON.parse(o.readFile(path.join(repo, GATE_CONFIG))).fixtures; if (Array.isArray(f)) fixtures = f.filter((d) => typeof d === "string"); } catch { /* no config: no fixtures */ }
+      // A snapshot has nothing untracked; the working tree (--plan, check --worktree) names its untracked manifests as skipped.
+      const untracked = () => {
+        if (snapshot) return [];
+        const r = git("ls-files", "-z", "--others", "--exclude-standard", "--", ":(glob)**/Cargo.toml");
+        return failed(r) ? [] : text(r).split("\0").filter(Boolean).map(posix);
+      };
+      rust = discoverRustWorkspaces({ root: repo, spawn: (c, a, opts) => o.spawn(c, a, opts), cargoCommand, tracked, untracked, fixtures, readFile: readSnap });
+      npm = discoverNpmUnits({ root: repo, tracked, readFile: readSnap, exists: o.exists });
+      npmRoots = discoverPnpmRoots({ root: repo, tracked, exists: o.exists });
+    } catch (e) { o.err(`${tag} BLOCKED: cannot discover the repository's units: ${e.message}`); return 1; }
+    for (const k of rust.skipped) o.out(`${tag} note: ${k.manifest} is skipped, not scanned: ${k.why}`);
+
+    // Class B scans (compile, lint, tests) run in the live checkout, so it must equal HEAD where they read it: an uncommitted fix could
+    // otherwise hide a committed failure. Class A reads only the snapshot.
+    if (!planOnly && !classAOnly) {
+      const npmRootFiles = ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", ".npmrc", ...ESLINT_CONFIG_FILES, ...BIOME_CONFIG_FILES];
+      const inputs = [...new Set([...rust.units.map((u) => u.dir), ...npm.map((u) => u.dir), ...rust.workspaces.map((w) => w.cargoDir), "ci", "scripts", "vendor", "Cargo.toml", "Cargo.lock", ".cargo", "rust-toolchain.toml", "rust-toolchain",
+        "deny.toml", "clippy.toml", "rustfmt.toml", ...npmRootFiles, ...npmRoots.filter((r) => r !== ".").flatMap((r) => npmRootFiles.map((f) => `${r}/${f}`))])];
+      const dirty = git("status", "--porcelain", "--untracked-files=all", "--", ...inputs);
+      const dirtyFiles = failed(dirty) ? [`git status failed: ${why(dirty)}`] : text(dirty).split(/\r?\n/).filter(Boolean).filter((l) => !l.includes("node_modules"));
+      if (dirtyFiles.length) {
+        o.err(`${tag} BLOCKED: the checkout differs from HEAD where compile scans read it; commit or stash first:`);
+        for (const l of dirtyFiles.slice(0, 20)) o.err(`  ${l}`);
+        return 1;
+      }
+    }
+
+    const diff = allFilesMode ? null : git("diff", "--name-only", "--diff-filter=ACMR", `${base}...HEAD`);
+    if (diff && failed(diff)) { o.err(`${tag} cannot diff against ${base}: ${why(diff)}; pass --base <ref> or --all`); return 2; }
+    const changed = allFilesMode ? files : [...new Set(text(diff).split(/\r?\n/).map((f) => f.trim()).filter(Boolean))].filter((f) => o.exists(path.join(repo, f)));
+    if (allFilesMode) base = snapshot ?? "the working tree";
 
     let crateFeatures = {}; let packageFeatures = {};
     try { const gateConfig = JSON.parse(o.readFile(path.join(repo, "ci/gate.config.json"))); crateFeatures = gateConfig.rust ?? {}; packageFeatures = gateConfig.npm ?? {}; } catch { /* no config: default feature sets */ }
@@ -1016,15 +1546,18 @@ export async function main(argv, io = {}) {
     const rustScope = restricted ? scopeNames : null;
 
     const fullPlan = planScans({
-      changed, contentRoot: repo, liveRoot: root, includeTests: true, rustScope, cargoCommand,
+      // Class A of a commit or tree reads only that snapshot: every scan, cargo's included, runs in the export, never in the live
+      // checkout (which may hold other bytes). Compiles (class B) use the live checkout, whose tree the dirty check pinned to HEAD.
+      changed, contentRoot: repo, liveRoot: classAOnly && snapshot ? repo : root, includeTests: true, rustScope, cargoCommand,
       // The quiet tests (port, pipe, desktop and wall-clock bound) are proven by the CI shards, one crate per runner, unless
       // RK_GATE_QUIET_TESTS=local asks for the serial quiet lane here (no CI, or a CI outage).
       quietTests: o.env.RK_GATE_QUIET_TESTS === "local" ? "local" : "ci", packageFeatures,
-      rustUnits: rust.units, npmUnits: npm, cargoDir: ".", rustLocks, crateFeatures,
-      localCompile: o.exists(path.join(root, GRANT_FILE)),
+      rustUnits: rust.units, npmUnits: npm, npmRoots, cargoDir: ".", rustLocks, crateFeatures,
+      // The broker (or, on a direct host, the gate itself) admits compiles; no separate grant file decides it here.
+      localCompile: true,
       exists: o.exists, readFile: o.readFile, platform: o.platform,
     });
-    const plan = args.includes("--pre-push") ? prePushPlan(fullPlan) : fullPlan;
+    let plan = args.includes("--pre-push") ? prePushPlan(fullPlan) : fullPlan;
     const jobs = Math.max(1, Number(o.env.RK_GATE_JOBS ?? 4) || 4);
     const testJobs = Math.max(1, Number(o.env.RK_GATE_TEST_JOBS ?? jobs) || jobs);
 
@@ -1039,6 +1572,7 @@ export async function main(argv, io = {}) {
     }
 
     for (const n of plan.notes) o.out(`${tag} note: ${n}`);
+    o.out(`${tag} executor: ${executor.kind}${executor.kind === "broker" ? ` (${cargoCommand.join(" ")})` : " (no broker on this host: cargo runs directly, through the same gates)"}`);
     const quietCount = plan.scans.filter((s) => s.quiet === true).length;
     o.out(`${tag} ${plan.scans.length} scan(s) for ${changed.length} changed file(s) vs ${base.slice(0, 12)}; compile scans ${jobs} at a time, tests ${testJobs} at a time${quietCount ? `, ${quietCount} quiet test scan(s) last under the broker's quiet lease` : ""}`);
     let signalCode = 0;
@@ -1053,7 +1587,7 @@ export async function main(argv, io = {}) {
     }
     // The result cache keys on the gated commit's object ids; the pre-push check above made HEAD the pushed commit.
     let cache = null;
-    if (!args.includes("--no-cache") && o.env.RK_GATE_CACHE !== "0") {
+    if (!classAOnly && !args.includes("--no-cache") && o.env.RK_GATE_CACHE !== "0") {
       try {
         const headSha = text(git("rev-parse", "HEAD")).trim();
         const treeId = text(git("rev-parse", `${headSha}^{tree}`)).trim();
@@ -1080,8 +1614,8 @@ export async function main(argv, io = {}) {
         }
       } catch { cache = null; }
     }
-    const scanResult = await runScans(plan, {
-      classes: ["A", "B"], jobs, testJobs, signal: ac.signal, ...(cache ? { cache } : {}),
+    const scanResult = await (o.runScans ?? runScans)(plan, {
+      classes: classAOnly ? ["A"] : ["A", "B"], jobs, testJobs, signal: ac.signal, ...(cache ? { cache } : {}),
       quietLane: quietLeaseLane(o, { tag, reason: `rightkit-gate-quiet-tests@${text(git("rev-parse", "--short", "HEAD")).trim()}` }),
       onResult: (row, p) => o.out(`${tag} [${p.done}/${p.total}] ${(row.cached ? "cached" : row.status).padEnd(7)} ${row.id} (${p.seconds}s)${row.status === "fail" ? ` :: ${String(row.detail ?? "").slice(0, 300)}` : ""}`),
     });
@@ -1099,9 +1633,13 @@ export async function main(argv, io = {}) {
     if (failures.length) {
       o.err(`${tag} BLOCKED (${failures.length})`);
       for (const f of failures) o.err(`  - ${f}`);
-      o.err("Fix and push again. Never bypass with --no-verify.");
+      o.err(classAOnly ? "Class A is red: nothing compiles until it is green." : "Fix and push again. Never bypass with --no-verify.");
       return 1;
     }
+    if (classAOnly) {
+      o.out(`${tag} class A pass: ${scanResult.scans.length} deterministic scan(s) over ${changed.length} file(s) of ${base}`);
+      return 0;
+    }
     o.out(`${tag} pass (${changed.length} changed file(s) vs ${base}); ${deferrals.length} scan(s) deferred, not passed${scanResult.cacheHits.length ? `; ${scanResult.cacheHits.length} reused from the result cache` : ""}`);
     return 0;
   } finally {