@rightkit/release 0.6.7 → 0.6.10

package/build-release.mjs

@@ -20,6 +20,7 @@ import {
 import path from "node:path";
 import { preflightOwnershipScope } from "./ownership-scope.mjs";
 import { spawn, spawnSync } from "./background-process.mjs";
+import { spawnUnderOwnership } from "./build-ownership.mjs";
 import { RightKitRegistryError, SNAPSHOT_ENV, SNAPSHOT_FILE, assertManifestRegistryEvidence, loadAdmittedSnapshot, prepareRightKitResolution, registryManifestFields, rightKitLockInventory, writeAdmissionRecord, writeSnapshot } from "./rightkit-registry-resolver.mjs";
 import { formatAdmission, formatNotRun, runAdmission } from "./admission.mjs";
 import { sccacheRefusal } from "./admission-host.mjs";
@@ -875,7 +876,7 @@ async function runProgress(cmd, runArgs, cwd, env, watchDir, diagnosticPath = nu
     const settleResolve = () => { if (!settled) { settled = true; resolve(); } };
     const settleReject = (error) => { if (!settled) { settled = true; reject(error); } };
     const useShell = process.platform === "win32" && !/\.(?:exe|com)$/i.test(cmd);
-    child = spawn(cmd, runArgs, { cwd, env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true, shell: useShell, detached: process.platform !== "win32" });
+    child = spawnUnderOwnership(spawn, cmd, runArgs, { cwd, env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true, shell: useShell, detached: process.platform !== "win32" });
     try {
       if (child.pid && heavySlot) heavySlot.trackChild(child.pid, cmd);
     } catch (error) {

package/cargo-contract.mjs

@@ -2,7 +2,7 @@ import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
-import { managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
+import { directPlatform, managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
 
 const SKIP_DIRECTORIES = new Set([".audit", ".cache", ".git", ".claude", ".right-release", ".worktrees", "node_modules", "target", "vendor"]);
 const CRATES_IO_SOURCES = new Set([
@@ -12,6 +12,7 @@ const CRATES_IO_SOURCES = new Set([
 const CACHE_V2_ENVIRONMENT = ["CARGO_HOME", "CARGO_TARGET_DIR", "RUSTC_WRAPPER", "SCCACHE_DIR", "SCCACHE_BASEDIRS", "RIGHT_RELEASE_CACHE_OWNER"];
 
 export function managedCargoShimOnPath(env = process.env, platform = process.platform, exists = existsSync) {
+  if (directPlatform(platform)) return false; // Linux never uses a RustRight shim (managed-cargo directPlatform)
   const pathApi = platform === "win32" ? path.win32 : path.posix;
   const delimiter = platform === "win32" ? ";" : ":";
   const extensions = platform === "win32"
@@ -29,6 +30,7 @@ export function managedCargoShimOnPath(env = process.env, platform = process.pla
 }
 
 export function brokerManagedHost(env = process.env, platform = process.platform, exists = existsSync) {
+  if (directPlatform(platform)) return false; // Linux is never broker-managed, whatever socket or control root the env names
   return Boolean(managedRuntimeClient(env, platform, exists)) || Boolean(env.RIGHTKIT_BUILD_BROKER_SOCKET) || managedCargoShimOnPath(env, platform, exists);
 }
 

package/cargo-target-shim.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// The runtime cargo wrapper of a commit-snapshot compile (item 7, GATE-CONTRACT §1 "Broker interface", output directory). Scope: the
+// DIRECT POSIX (Linux) host only. On Mac and Dell the positive snapshot-compile path is the RustRight broker's snapshot carrier alone
+// (the gate refuses a snapshot compile on a broker host until it is wired); on a direct Windows host the static walk
+// (deterministic-scans.mjs cargoReachOf) is the fail-closed baseline, because a child started without a shell finds only an .exe.
+//
+// The gate puts this `cargo` first on PATH and names it in CARGO for every scan. Real cargo honours CARGO as its own path and hands
+// it to build scripts and tests (env!("CARGO"), $CARGO), so those come back here too. Each invocation resolves its Cargo workspace
+// (`cargo locate-project --workspace`, from its working directory or --manifest-path) and runs with that workspace's ORIGINAL checkout
+// target directory as CARGO_TARGET_DIR. Refused with an RK_* code (the unit fails): a workspace the compile did not resolve (outside
+// the snapshot, a fixture, a temporary project), an option that moves the workspace, configuration or output, a command that writes
+// no bound output or rewrites the commit (clean, install, publish, update, an alias or plugin), a command that reads a workspace
+// outside the bound ones or may write its Cargo.lock (tree, fetch, pkgid... without --locked/--frozen; fmt only as --check). A cargo
+// that bypasses PATH and CARGO (an absolute path, `rustup run`, a reset PATH) inherits the scan-wide CARGO_TARGET_DIR: the one
+// workspace's checkout target, or with several workspaces a per-scan sentinel directory that must stay empty (runScans fails the
+// scan with RK_CARGO_UNBOUND otherwise). An absolute cargo that also passes its own --target-dir is deliberate evasion of the gate,
+// out of scope under the standing rule (the gate binds what a test does, not what a test sets out to hide).
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const SHIM_MAP_SCHEMA = "rightkit.cargo-target-shim/2";
+// Exit status of a refusal: cargo's own error status, so every caller reads it as a failed cargo.
+export const SHIM_REFUSAL_STATUS = 101;
+// Cargo commands that compile or report on a workspace: run bound to its checkout target directory.
+const COMPILE = new Set(["build", "b", "check", "c", "test", "t", "bench", "run", "r", "doc", "d", "rustc", "rustdoc", "clippy", "metadata", "package"]);
+// Commands that only read a workspace but may resolve and write its Cargo.lock: bound, and only with --locked or --frozen.
+const LOCKED = new Set(["fetch", "tree", "pkgid", "verify-project", "read-manifest", "locate-project", "deny"]);
+// Commands with no lock flag (cargo fmt, cargo-audit): bound, and only where the workspace's committed Cargo.lock already exists.
+const LOCKFILE = new Set(["fmt", "audit"]);
+// Plugins whose options are their own, not cargo's (cargo-deny's --config is its config file, not a cargo redirect).
+const PLUGIN = new Set(["deny", "audit"]);
+const BOUND = new Set([...COMPILE, ...LOCKED, ...LOCKFILE]);
+// Commands that read no workspace at all: run unchanged.
+const PASSTHROUGH = new Set(["version", "help"]);
+// Global options that take a value (`--color always`, `--explain E0001`); the subcommand is the first word after them.
+const GLOBAL_VALUE = new Set(["--color", "--explain"]);
+// Options that move the working directory, the configuration or the output (a short cluster holding C or Z too).
+const REDIRECT = /^(--config|-Z|-C)(=|$)|^-[A-Za-z]*[CZ]/;
+
+const refusal = (code, message) => ({ refuse: { code, message } });
+
+/**
+ * What one cargo invocation may do: `{ exec: { args, env, workspace, targetDir } }` (bound), `{ exec: { args, env } }` (a command
+ * that writes nothing), or `{ refuse: { code, message } }`. `locate(manifestPath | null, cwd, toolchain | null)` returns the absolute
+ * path of the workspace root's Cargo.toml or throws; `realpath` resolves a directory. `map.shim` (the wrapper's own path) is set as
+ * CARGO for the real cargo, so its build scripts and tests reach the wrapper again.
+ */
+export function decideCargoInvocation({ args, cwd, env, map, locate, realpath = (p) => fs.realpathSync.native(p), exists = fs.existsSync }) {
+  const words = [...args];
+  const toolchain = words[0]?.startsWith("+") ? words[0] : null;
+  const withCargo = (e) => (map.shim ? { ...e, CARGO: map.shim } : e);
+  let i = toolchain ? 1 : 0;
+  let sub = null;
+  for (; i < words.length; i += 1) {
+    const w = words[i];
+    if (w === "--") break;
+    if (REDIRECT.test(w)) return refusal("RK_CARGO_REDIRECT", `\`cargo ${words.join(" ")}\` passes ${w}, which moves its working directory, configuration or output; a snapshot compile's outputs must be the checkout's`);
+    if (GLOBAL_VALUE.has(w)) { i += 1; continue; }
+    if (w.startsWith("-")) continue;
+    sub = w;
+    break;
+  }
+  const end = sub === null ? -1 : words.indexOf("--", i + 1);
+  const own = sub === null ? [] : words.slice(i + 1, end < 0 ? undefined : end);
+  const globals = words.slice(toolchain ? 1 : 0, sub === null ? undefined : i);
+  if (sub === "fmt" && !own.includes("--check")) return refusal("RK_CARGO_UNBOUND_COMMAND", "`cargo fmt` without --check rewrites tracked files; a snapshot compile changes no file of the commit");
+  if (sub === null || PASSTHROUGH.has(sub)) return { exec: { args: words, env: withCargo({ ...env }) } };
+  if (!BOUND.has(sub)) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` is not a command a snapshot compile binds (${[...BOUND].join(", ")}; or ${[...PASSTHROUGH].join(", ")}, which read no workspace): an alias, plugin, clean, install, publish or lock rewrite is refused`);
+  if (LOCKED.has(sub) && ![...globals, ...own].some((w) => w === "--locked" || w === "--frozen")) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` without --locked or --frozen may write a Cargo.lock; a snapshot compile changes no file of the commit and writes nothing outside its bound outputs`);
+  if (!PLUGIN.has(sub)) for (const w of own) if (REDIRECT.test(w)) return refusal("RK_CARGO_REDIRECT", `\`cargo ${sub}\` passes ${w}, which moves its working directory, configuration or output; a snapshot compile's outputs must be the checkout's`);
+  const valueOf = (name) => {
+    const at = own.findIndex((w) => w === name || w.startsWith(`${name}=`));
+    if (at < 0) return undefined;
+    return own[at].includes("=") ? own[at].slice(name.length + 1) : (own[at + 1] ?? "");
+  };
+  const manifestPath = valueOf("--manifest-path");
+  let workspace;
+  try {
+    const manifest = locate(manifestPath === undefined ? null : path.resolve(cwd, manifestPath), cwd, toolchain);
+    if (typeof manifest !== "string" || !path.isAbsolute(manifest)) throw new Error(`locate-project reported ${JSON.stringify(manifest)}`);
+    workspace = realpath(path.dirname(manifest));
+  } catch (error) {
+    return refusal("RK_CARGO_UNBOUND_WORKSPACE", `\`cargo ${sub}\` from ${cwd}${manifestPath === undefined ? "" : ` (--manifest-path ${manifestPath})`}: its Cargo workspace cannot be resolved (${error.message}); a snapshot compile's outputs must be the checkout's`);
+  }
+  const targetDir = Object.hasOwn(map.workspaces ?? {}, workspace) ? map.workspaces[workspace] : null;
+  if (!targetDir) return refusal("RK_CARGO_UNBOUND_WORKSPACE", `\`cargo ${sub}\` builds the Cargo workspace ${workspace}, which is not one this snapshot compile resolved (${Object.keys(map.workspaces ?? {}).join(", ") || "none"}); its outputs would not be the checkout's`);
+  if (LOCKFILE.has(sub) && !exists(path.join(workspace, "Cargo.lock"))) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` has no --locked, and workspace ${workspace} has no committed Cargo.lock it would only read; it may write one`);
+  const explicit = valueOf("--target-dir");
+  if (explicit !== undefined && path.resolve(cwd, explicit) !== targetDir) return refusal("RK_CARGO_REDIRECT", `\`cargo ${sub}\` passes --target-dir ${explicit}; workspace ${workspace} writes only to the checkout's ${targetDir}`);
+  return { exec: { args: words, env: withCargo({ ...env, CARGO_TARGET_DIR: targetDir, CARGO_BUILD_TARGET_DIR: targetDir }), workspace, targetDir } };
+}
+
+/**
+ * Writes the wrapper for one snapshot compile under `base`: the map file and `bin/cargo`, which runs this module with node. The
+ * directory is named by the sha256 of the map and this module's bytes (`identity`), so the same workspaces, targets and wrapper give
+ * the same path (and the same CARGO in a scan's cache key) and any change gives another. `targetDirs` is the gate's { [cargoDir]:
+ * absolute checkout target directory }; each workspace is keyed by its real path in the snapshot. `realCargo` is the absolute cargo
+ * the wrapper runs (never itself). POSIX hosts only: a Windows child started without a shell finds only an .exe on PATH.
+ */
+export function installCargoShim({ base, snapshotRoot, targetDirs, realCargo, node = process.execPath, platform = process.platform, realpath = (p) => fs.realpathSync.native(p), onDir = () => {}, write = (file, text, mode) => fs.writeFileSync(file, text, { mode }) }) {
+  if (platform === "win32") throw Object.assign(new Error("the runtime cargo wrapper needs a POSIX host: a Windows child finds only an .exe on PATH"), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+  if (typeof realCargo !== "string" || !path.isAbsolute(realCargo)) throw Object.assign(new Error(`no absolute cargo to wrap (${JSON.stringify(realCargo)})`), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+  const workspaces = {};
+  for (const [cargoDir, targetDir] of Object.entries(targetDirs ?? {})) workspaces[realpath(path.join(snapshotRoot, ...(cargoDir === "." ? [] : cargoDir.split("/"))))] = targetDir;
+  const self = fileURLToPath(import.meta.url);
+  const sorted = Object.fromEntries(Object.entries(workspaces).sort(([a], [b]) => (a < b ? -1 : 1)));
+  const identity = createHash("sha256").update(JSON.stringify({ realCargo, node, workspaces: sorted })).update(fs.readFileSync(self)).digest("hex");
+  const dir = path.join(base, `rk-cargo-shim-${identity.slice(0, 16)}`);
+  const bin = path.join(dir, "bin");
+  const shim = path.join(bin, "cargo");
+  const mapFile = path.join(dir, "cargo-target-map.json");
+  // The caller learns the directory before anything is written into it (its cleanup owns it from here), and a failed install removes
+  // what it wrote before it throws.
+  onDir(dir);
+  try {
+    fs.mkdirSync(bin, { recursive: true });
+    const quote = (s) => `'${String(s).replaceAll("'", "'\\''")}'`;
+    const put = (file, text, mode) => { const tmp = `${file}.${process.pid}.tmp`; write(tmp, text, mode); fs.renameSync(tmp, file); };
+    put(mapFile, `${JSON.stringify({ schema: SHIM_MAP_SCHEMA, identity, realCargo, shim, workspaces: sorted }, null, 2)}\n`, 0o644);
+    put(shim, `#!/bin/sh\nexec ${quote(node)} ${quote(self)} --map ${quote(mapFile)} -- "$@"\n`, 0o755);
+  } catch (error) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    throw error;
+  }
+  return { dir, bin, shim, mapFile, workspaces: sorted, identity, sentinel: Object.keys(sorted).length > 1 ? path.join(dir, "unbound") : null };
+}
+
+/**
+ * The environment every scan of a wrapped snapshot compile starts from: the wrapper first on PATH and named in CARGO, and, when the
+ * snapshot has exactly one Cargo workspace, its checkout target as the scan-wide CARGO_TARGET_DIR, so a cargo that bypasses the
+ * wrapper (an absolute path, `rustup run`, a reset PATH) still writes there. With several workspaces runScans gives each scan its own
+ * empty sentinel as CARGO_TARGET_DIR instead (installed.sentinel; options.cargoSentinel), which must still be empty afterwards.
+ */
+export function shimScanEnv(env, installed) {
+  const targets = Object.values(installed.workspaces);
+  const pathKey = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
+  return { ...env, [pathKey]: `${installed.bin}${path.delimiter}${env[pathKey] ?? ""}`, CARGO: installed.shim, ...(targets.length === 1 ? { CARGO_TARGET_DIR: targets[0] } : {}) };
+}
+
+/** The wrapper itself: `cargo-target-shim.mjs --map <file> -- <cargo args>`. Returns the exit status. */
+export function runShim(argv, { env = process.env, cwd = process.cwd(), spawn = spawnSync, err = (m) => process.stderr.write(`${m}\n`) } = {}) {
+  const sep = argv.indexOf("--");
+  const mapAt = argv.indexOf("--map");
+  if (mapAt < 0 || sep < 0 || mapAt > sep) { err("rightkit-gate: RK_CARGO_SHIM_ERROR: usage: cargo-target-shim.mjs --map <file> -- <cargo args>"); return SHIM_REFUSAL_STATUS; }
+  let map;
+  try { map = JSON.parse(fs.readFileSync(argv[mapAt + 1], "utf8")); if (map?.schema !== SHIM_MAP_SCHEMA) throw new Error(`schema ${JSON.stringify(map?.schema)}`); }
+  catch (error) { err(`rightkit-gate: RK_CARGO_SHIM_ERROR: the cargo target map cannot be read (${error.message}); nothing ran`); return SHIM_REFUSAL_STATUS; }
+  // locate-project runs the real cargo with CARGO pointing at it, never at the wrapper.
+  const locateEnv = { ...env, CARGO: map.realCargo };
+  const locate = (manifestPath, from, toolchain) => {
+    const r = spawn(map.realCargo, [...(toolchain ? [toolchain] : []), "locate-project", "--workspace", "--message-format", "plain", ...(manifestPath ? ["--manifest-path", manifestPath] : [])], { cwd: from, env: locateEnv, encoding: "utf8" });
+    if (r.error) throw r.error;
+    if (r.status !== 0) throw new Error(String(r.stderr || `exit ${r.status}`).trim().split(/\r?\n/).at(-1));
+    return String(r.stdout).trim();
+  };
+  const decision = decideCargoInvocation({ args: argv.slice(sep + 1), cwd, env, map, locate });
+  if (decision.refuse) { err(`rightkit-gate: ${decision.refuse.code}: ${decision.refuse.message}`); return SHIM_REFUSAL_STATUS; }
+  const r = spawn(map.realCargo, decision.exec.args, { cwd, env: decision.exec.env, stdio: "inherit" });
+  if (r.error) { err(`rightkit-gate: RK_CARGO_SHIM_ERROR: ${map.realCargo} did not start (${r.error.message})`); return SHIM_REFUSAL_STATUS; }
+  return r.status ?? (r.signal ? 128 : SHIM_REFUSAL_STATUS);
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) process.exit(runShim(process.argv.slice(2)));

package/class-a-launch-guard.mjs

@@ -0,0 +1,126 @@
+// Class A launch guard: class A runs before any compile, so a class A test row may not launch a compiler or an emitting build.
+//
+// The gate runs every class A test row with NODE_OPTIONS carrying `--import=<this file>`. In every Node process of the row (the
+// test runner, pnpm, workers, any Node child they launch, including one given a replacement environment) the child_process launchers are wrapped, and a launch is
+// refused (it throws, so the row fails) when the program, or a command line it hands to a shell, is a compile or an emitting
+// build: cargo, rustc, rustright, rightkit (broker client), tauri / cargo-tauri, tsc without --noEmit, tsup, esbuild, swc, rollup,
+// webpack, `vite build`, `next build`, or a package-manager run of a build / build:* script.
+//
+// Scope, exactly: launches from Node processes of the row. Not covered: a compiler API called inside a process
+// (typescript.createProgram().emit(), vite.build() / the rollup JS API), and launches by a non-Node program that does not load
+// this hook (rightkit#1240). esbuild's JS API is covered: it launches the esbuild service binary.
+//
+// A Node child handed a replacement environment keeps the guard (withGuard restores it). There is no exemption: a unit whose tests
+// launch stand-ins named like compilers (stub scripts can run anything) runs after class A instead (npm.<unit>.afterClassA).
+import childProcess from "node:child_process";
+import path from "node:path";
+import { syncBuiltinESMExports } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const INSTALLED = Symbol.for("rightkit.classA.launchGuard");
+export const LAUNCH_GUARD_IMPORT = `--import=${pathToFileURL(fileURLToPath(import.meta.url)).href}`;
+export const REFUSAL_CODE = "RK_CLASS_A_COMPILE_LAUNCH";
+const COMPILERS = new Set(["cargo", "rustc", "rustright", "rightkit", "tauri", "cargo-tauri", "tsup", "esbuild", "swc", "rollup", "webpack"]);
+const PACKAGE_MANAGERS = new Set(["pnpm", "npm", "yarn", "bun"]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "cmd", "powershell", "pwsh"]);
+const WRAPPERS = new Set(["env", "npx", "pnpx", "exec", "time", "nice"]);
+// Options that take a value, per package manager: pnpm's `-w` is `--workspace-root` (a flag), npm's `-w` is `--workspace <name>`.
+const OPTIONS_WITH_VALUES = Object.freeze({
+  pnpm: new Set(["--filter", "-F", "--dir", "-C"]),
+  npm: new Set(["--workspace", "-w", "--prefix"]),
+  yarn: new Set(["--cwd"]),
+  bun: new Set(["--cwd", "--filter"]),
+});
+
+const base = (p) => path.basename(String(p ?? "").replaceAll("\\", "/")).replace(/\.(exe|cmd|bat|ps1|js|mjs|cjs)$/i, "").toLowerCase();
+
+/** A shell command line split into commands (on && || ; |) and words, quotes removed: enough to read what a `sh -c` text launches. */
+export function shellWords(text) {
+  const commands = []; let words = []; let word = ""; let quote = null;
+  const end = () => { if (word) { words.push(word); word = ""; } };
+  const s = String(text);
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (quote) { if (c === quote) quote = null; else word += c; continue; }
+    if (c === "'" || c === "\"") { quote = c; continue; }
+    if (/\s/.test(c)) { end(); continue; }
+    if (c === ";" || c === "|" || c === "&") { end(); if (words.length) commands.push(words); words = []; continue; }
+    word += c;
+  }
+  end(); if (words.length) commands.push(words);
+  return commands;
+}
+
+/** Why `[program, ...args]` is a compile or an emitting build, or null. */
+export function compileLaunch(program, args = []) {
+  let words = [String(program), ...args.map(String)];
+  for (let guard = 0; guard < 8 && words.length; guard++) {
+    const name = base(words[0]);
+    if (name === "node" && words[1] && !String(words[1]).startsWith("-")) { words = words.slice(1); continue; }
+    if (WRAPPERS.has(name)) { words = words.slice(1).filter((w, i, a) => !(i === 0 && /^[A-Z_][A-Z0-9_]*=/.test(w))); continue; }
+    if (SHELLS.has(name)) {
+      const at = words.findIndex((w, i) => i > 0 && /^(-c|\/c|\/s|-Command|-command)$/i.test(w));
+      if (at < 0 || !words[at + 1]) return null;
+      for (const cmd of shellWords(words.slice(at + 1).join(" "))) { const why = compileLaunch(cmd[0], cmd.slice(1)); if (why) return why; }
+      return null;
+    }
+    const rest = words.slice(1);
+    if (COMPILERS.has(name)) return name;
+    if (name === "tsc") return rest.some((w) => /^--?noEmit(=true)?$/i.test(w)) ? null : "tsc (emits)";
+    if (name === "vite" || name === "next") return rest.find((w) => !w.startsWith("-")) === "build" ? `${name} build` : null;
+    if (PACKAGE_MANAGERS.has(name)) {
+      let next = null;
+      for (let j = 0; j < rest.length; j++) {
+        if (OPTIONS_WITH_VALUES[name].has(rest[j])) { j++; continue; }
+        if (rest[j].startsWith("-") || rest[j] === "run" || rest[j] === "run-script") continue;
+        if (/^build(:|$)/.test(rest[j])) return `${name} ${rest[j]}`;
+        if (rest[j] === "exec" || rest[j] === "dlx" || rest[j] === "x") next = rest.slice(j + 1);
+        break;
+      }
+      if (!next || !next.length) return null;
+      words = next; continue;
+    }
+    return null;
+  }
+  return null;
+}
+
+function refuse(why, program, args) {
+  const error = new Error(`class A refuses a compile/emit launch (${why}): ${[program, ...args].join(" ").slice(0, 300)}. Class A runs before any compile; this test row belongs after class A.`);
+  error.code = REFUSAL_CODE;
+  try { process.stderr.write(`rightkit-gate: ${error.message}\n`); } catch { /* stderr closed */ }
+  throw error;
+}
+
+function check(program, args, options) {
+  const argv = Array.isArray(args) ? args : [];
+  if (options?.shell) { for (const cmd of shellWords([program, ...argv].join(" "))) { const why = compileLaunch(cmd[0], cmd.slice(1)); if (why) refuse(why, program, argv); } return; }
+  const why = compileLaunch(program, argv);
+  if (why) refuse(why, program, argv);
+}
+
+/** `env` with the guard switched on and loaded (NODE_OPTIONS appended, never replaced). */
+export function withGuard(env) {
+  const current = String(env.NODE_OPTIONS ?? "");
+  return { ...env, RIGHTKIT_CLASS_A_LAUNCH_GUARD: "1", NODE_OPTIONS: current.includes(LAUNCH_GUARD_IMPORT) ? current : `${current} ${LAUNCH_GUARD_IMPORT}`.trim() };
+}
+
+export function installLaunchGuard() {
+  if (globalThis[INSTALLED]) return;
+  globalThis[INSTALLED] = true;
+  const o = { ...childProcess };
+  const split = (args) => (Array.isArray(args[1]) ? [args[0], args[1], args[2]] : [args[0], [], args[1]]);
+  // A child handed a replacement environment keeps the guard: its NODE_OPTIONS (and the switch) are restored into that env.
+  // The caller's options object is never modified: the launch gets a copy carrying the restored env.
+  const keep = (a) => a.map((x) => (x && typeof x === "object" && !Array.isArray(x) && x.env && typeof x.env === "object" ? { ...x, env: withGuard(x.env) } : x));
+  childProcess.spawn = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.spawn.apply(this, keep(a)); };
+  childProcess.spawnSync = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.spawnSync.apply(this, keep(a)); };
+  childProcess.execFile = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.execFile.apply(this, keep(a)); };
+  childProcess.execFileSync = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.execFileSync.apply(this, keep(a)); };
+  childProcess.exec = function (cmd, ...a) { for (const c of shellWords(cmd)) { const why = compileLaunch(c[0], c.slice(1)); if (why) refuse(why, cmd, []); } return o.exec.call(this, cmd, ...keep(a)); };
+  childProcess.execSync = function (cmd, ...a) { for (const c of shellWords(cmd)) { const why = compileLaunch(c[0], c.slice(1)); if (why) refuse(why, cmd, []); } return o.execSync.call(this, cmd, ...keep(a)); };
+  childProcess.fork = function (modulePath, ...a) { const v = Array.isArray(a[0]) ? a[0] : []; check(modulePath, v, {}); return o.fork.call(this, modulePath, ...keep(a)); };
+  syncBuiltinESMExports();
+}
+
+if (process.env.RIGHTKIT_CLASS_A_LAUNCH_GUARD === "1") installLaunchGuard();

package/cli/right-release.mjs

@@ -25,6 +25,7 @@ const commands = new Map([
   ["sign-candidate", "sign-candidate.mjs"],
   ["engine-locate", "engine-locator.mjs"],
   ["stage-sidecar", "stage-sidecar-command.mjs"],
+  ["assemble-app", "assemble-app-command.mjs"],
   ["init", "init-command.mjs"],
   ["pe", "pe-content.mjs"],
   ["icons", "icon-pack.mjs"],
@@ -269,6 +270,7 @@ Commands:
   icons ico|icns --out <file> --frame <PNG>... [--dir <folder>]  Pack hand-tuned per-size PNG frames into an ICO or ICNS
   init --name <Product Name> --id <reverse.dns.bundle.id> [--slug <lowercase>] [--dir <root>] [--dry-run]  Rename the desktop app template into a real app, in place
   stage-sidecar [--config <file>] [--target <triple>] [--json]  Stage declarative sidecars into src-tauri/binaries (Tauri externalBin naming)
+  assemble-app --platform mac|win [--profile release|dev] [--build] [--out <dir>] | --verify-staged [--signed] | --package  Assemble the declared composite app (assembly.<platform>) for production packaging; the same definition installs through dev
   recipe-build --plan <json> | --plan-file <path> [--app-root <dir>]  Run a package recipe: prepare steps, the Tauri build, postBuild steps (argv, no shell, fail closed)
   dmg build --app <.app> --out <dmg> --volname <name> [--background <png>] [--spec <appdmg.json>]
             [--icon-size N] [--app-position x,y] [--applications-position x,y] [--window w,h] [--window-position x,y]
@@ -360,7 +362,7 @@ Commands:
   signing-agent install|uninstall|status              Manage invisible Aqua-session signing service
   check [--repo <dir>] [--config <file>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]
                                                       The offline app check, same as rightkit-gate check: committed files only, every finding in one run (exit 0 pass, 1 findings, 2 could not run).
-                                                      Build, package, dev, test, web-build, swift-package, recipe-build, stage-sidecar, qa, upload, publish, publish-update, github, doctor,
+                                                      Build, package, dev, test, web-build, swift-package, recipe-build, assemble-app, stage-sidecar, qa, upload, publish, publish-update, github, doctor,
                                                       sign-windows, sign-updater, sign-candidate, sign-dev-artifact, addon build and create-mac-updater run it first and start nothing when it is red; there is no flag that skips it.
                                                       Baseline: .rightkit/app-check-baseline.json (entries carry issue, added and sunset; the sunset is at most 90 days after added)
   doctor [--platform mac|win] [--gates] [--inspect] [--strict]

package/codesign-shim.mjs

@@ -23,7 +23,17 @@ export async function runCodesignShim(argv, { cwd = process.cwd(), env = process
     privatePath(paths.config, 0o600, { io });
     roots = JSON.parse(io.readFileSync(paths.config, "utf8")).roots;
   }
-  const { targets } = parseCodesignArgv(argv, cwd);
+  const { targets, mode } = parseCodesignArgv(argv, cwd);
+  if (mode !== "sign") {
+    // Verify & display read the code they are given and need no identity, so
+    // they run the system codesign here. The agent's roots are the signing
+    // policy (where the identity may be applied), not a read policy: a dev
+    // install verifies its installed copy under /Applications, which no
+    // signing root contains.
+    const direct = run("/usr/bin/codesign", argv, { cwd, env, encoding: "utf8", shell: false, windowsHide: true });
+    if (direct.error) throw direct.error;
+    return { status: direct.status ?? 1, stdout: String(direct.stdout ?? ""), stderr: String(direct.stderr ?? "") };
+  }
   const report = await request({ schema: 1, type: "codesign-argv", argv, cwd, targets,
     allowedRoots: roots.filter((root) => io.existsSync(root)), timeoutMs: 180000 }, { paths });
   const result = report.results?.[0];