@rightkit/release 0.6.21 → 0.6.23

package/bin/rightkit-gate.mjs

@@ -1642,7 +1642,13 @@ async function runStages(o, args, root, git, io) {
       ok = true;
       if (ds) ok = await stageWebBuildOnce({ o, ds, root, git, appDir, cli, commonDir, commit, tree, stage, executor });
       if (ok && ds) ok = await stageWindowsIdentityOnce({ o, ds, root, git, appDir, cli, commonDir, commit, tree, stage, executor });
-      if (ok && ds) ok = await stageSidecarsOnce({ o, ds, root, git, configs: sidecarConfigsOf(), appDir, cli, commonDir, commit, tree, stage, executor });
+      if (ok && ds) {
+        // The package triple: a Mac recipe with `stageSidecars` builds for its own triple (universal-apple-darwin by default), so the gate stages that triple here, under its own
+        // producer carrier, and the recipe's prepare step (`stage-sidecar --target <triple>`) then finds it current and changes nothing.
+        const packageConfigs = sidecarConfigsOf();
+        const packageTarget = await packageSidecarTarget({ o, ds, configs: packageConfigs });
+        ok = await stageSidecarsOnce({ o, ds, root, git, configs: packageConfigs, appDir, cli, commonDir, commit, tree, stage, executor, target: packageTarget });
+      }
       // Source QA (right-release qa --stage source) exists for mac and win only; a mobile package is the signed build alone.
       // Row 7.04c (R-T1, 7.09): the snapshot holds no Cargo target. On a direct host the checkout's output directory is resolved here, in the primary
       // checkout, and handed to right-release absolute: it binds every manifest's target for this stage, and the sealed manifest must record it back
@@ -1944,6 +1950,16 @@ async function restagedSidecars({ o, ds, prior, now }) {
   return out;
 }
 
+/**
+ * The --target the package stage stages sidecars for: `package` on a Mac host, which right-release stage-sidecar resolves itself from the
+ * snapshot's config (the Mac package recipe's own triple, e.g. universal-apple-darwin), so this gate never imports app code; null elsewhere (host).
+ */
+export async function packageSidecarTarget({ o, ds, configs = [] }) {
+  if (o.platform !== "darwin" || !ds) return null;
+  // Read as text, never imported (as committedSidecarConfigs does): only a config whose Mac package recipe stages sidecars gets a package-triple staging.
+  return configs.some((config) => { try { return /\bstageSidecars\b/.test(o.readFile(path.join(ds.path, config))); } catch { return false; } }) ? "package" : null;
+}
+
 /** The release configs of `commit` (under `appDir`) that declare `sidecars`, read from `base` (the snapshot on the snapshot route): the commit's config decides, never the checkout's. */
 export function committedSidecarConfigs({ o, git, commit, appDir = ".", base }) {
   const listedConfigs = git("ls-tree", "-r", "--name-only", "-z", commit);
@@ -1957,9 +1973,14 @@ export function committedSidecarConfigs({ o, git, commit, appDir = ".", base })
  * step's additions must equal the files it reported plus its receipt (anything else is an unattributed write, RK_CHECK_ERROR). The
  * staged files become immutable `staged` ledger entries. Returns true when nothing is owed or staging passed.
  */
-export async function stageSidecarsOnce({ o, ds, root, git = null, configs, appDir, cli, commonDir, commit, tree, stage, executor = null, tag = "rightkit-gate:" }) {
-  if (ds.sidecarsStaged) return true;
-  ds.sidecarsStaged = true;
+export async function stageSidecarsOnce({ o, ds, root, git = null, configs, appDir, cli, commonDir, commit, tree, stage, executor = null, tag = "rightkit-gate:", target = null }) {
+  // Once per door run PER TARGET TRIPLE: `target` null is the host (the compile stage: stage-sidecar's own default, no `--target` passed), anything else is the triple the
+  // package recipe stages for (universal-apple-darwin on a Mac recipe with `stageSidecars`), passed to stage-sidecar as `--target`. stage-sidecar is a no-op for a target whose
+  // receipt and files are already current, so the recipe's own prepare step afterwards changes nothing.
+  const staged = ds.sidecarsStaged instanceof Set ? ds.sidecarsStaged : (ds.sidecarsStaged = new Set());
+  const key = target ?? "host";
+  if (staged.has(key)) return true;
+  staged.add(key);
   if (!configs.length) return true;
   const { attributionProblems, reportedPaths } = await import("../stage-ledger.mjs");
   const source = sourceSplitOf({ root, ds, appDir });
@@ -1967,13 +1988,13 @@ export async function stageSidecarsOnce({ o, ds, root, git = null, configs, appD
   for (const config of configs) {
     const before = ds.ledger?.entries ?? [];
     // The stage-sidecar child's Cargo calls (its builds and metadata queries) are carried on a broker host (carried-cargo.mjs).
-    const carrier = await carrierForChildren({ o, ds, root, git, executor, stage, tag });
+    const carrier = await carrierForChildren({ o, ds, root, git, executor, stage, tag, producer: true });
     if (carrier.refusal) { o.err(`${tag} BLOCKED: ${carrier.refusal}; nothing was staged`); return false; }
     const run = startRun({ commonDir, commit, tree, stage, source });
     let r;
     try {
-      o.out(`${tag} [${stage}] right-release stage-sidecar --config ${path.join(ds.path, config)} (from the snapshot ${ds.path})`);
-      r = (o.spawnCapture ?? ((cmd, a, opts) => spawnInherit(cmd, a, { ...opts, encoding: "utf8", maxBuffer: 1 << 26 })))(process.execPath, [cli, "stage-sidecar", "--config", path.join(ds.path, config), "--json"], { cwd: snapshotAppRootOf(ds.path, appDir), env: carriedEnv(carrier, { ...cleanEnv, ...run.env }) });
+      o.out(`${tag} [${stage}] right-release stage-sidecar --config ${path.join(ds.path, config)}${target ? ` --target ${target}` : ""} (from the snapshot ${ds.path})`);
+      r = (o.spawnCapture ?? ((cmd, a, opts) => spawnInherit(cmd, a, { ...opts, encoding: "utf8", maxBuffer: 1 << 26 })))(process.execPath, [cli, "stage-sidecar", "--config", path.join(ds.path, config), ...(target ? ["--target", target] : []), "--json"], { cwd: snapshotAppRootOf(ds.path, appDir), env: carriedEnv(carrier, { ...cleanEnv, ...run.env }) });
     } finally { endRun(run); }
     const carriedOk = await carrier.finish({ stage });
     if (r?.stderr) o.err(String(r.stderr).trimEnd());
@@ -1989,7 +2010,7 @@ export async function stageSidecarsOnce({ o, ds, root, git = null, configs, appD
     const configDir = path.posix.dirname(String(config).replaceAll("\\", "/"));
     const underApp = (rel) => (configDir === "." ? rel : `${configDir}/${rel}`).replaceAll("\\", "/");
     const receiptAbs = typeof result.receiptPath === "string" ? path.relative(ds.path, result.receiptPath).split(path.sep).join("/") : null;
-    const problems = [...walked.problems, ...attributionProblems({ before, after: walked.entries, reported: [...reportedPaths(result)].map(underApp), receipt: receiptAbs })];
+    const problems = [...walked.problems, ...attributionProblems({ before, after: walked.entries, reported: [...reportedPaths(result)].map(underApp), receipt: receiptAbs, removable: before.filter((e) => e.kind === "staged" && e.producer?.stage === "sidecar" && e.producer?.step === config).map((e) => e.path) /* only THIS config's earlier staged files (Oracle: another config's build must never delete them unreported) */ })];
     if (problems.length) { for (const p of problems.slice(0, 10)) o.err(`${tag} RK_CHECK_ERROR: [${stage}] stage-sidecar ${config}: ${p}`); return false; }
     const priorPaths = new Set(before.map((e) => e.path));
     const priorByPath = new Map(before.map((e) => [e.path, e]));
@@ -2048,7 +2069,7 @@ export async function stageWebBuildOnce({ o, ds, root, git = null, appDir, cli,
   for (const config of configs) {
     if (!absent().length) break;
     const before = ds.ledger?.entries ?? [];
-    const carrier = await carrierForChildren({ o, ds, root, git, executor, stage, tag });
+    const carrier = await carrierForChildren({ o, ds, root, git, executor, stage, tag, producer: true });
     if (carrier.refusal) { o.err(`${tag} BLOCKED: ${carrier.refusal}; the web build did not run`); return false; }
     const run = startRun({ commonDir, commit, tree, stage, source });
     let r;
@@ -2100,7 +2121,7 @@ export async function stageWindowsIdentityOnce({ o, ds, root, git = null, appDir
   const producer = path.join(path.dirname(cli), "..", "windows-identity.mjs");
   for (const config of configs) {
     const before = ds.ledger?.entries ?? [];
-    const carrier = await carrierForChildren({ o, ds, root, git, executor, stage, tag });
+    const carrier = await carrierForChildren({ o, ds, root, git, executor, stage, tag, producer: true });
     if (carrier.refusal) { o.err(`${tag} BLOCKED: ${carrier.refusal}; the Windows identity package did not build`); return false; }
     const run = startRun({ commonDir, commit, tree, stage, source });
     let r;
@@ -2731,7 +2752,7 @@ async function snapshotCargoWorkspaces({ git, ds, root }) {
  * child's environment; `finish` runs after the child ended, fails on any call that was refused, unverified or unfinished and on any
  * receipt the gate cannot verify again itself, and removes the carrier. A direct executor, or no snapshot, has nothing to carry.
  */
-async function carrierForChildren({ o, ds, root, git, executor, stage, tag = "rightkit-gate:" }) {
+async function carrierForChildren({ o, ds, root, git, executor, stage, tag = "rightkit-gate:", producer = false }) {
   const none = { env: {}, carried: false, refusal: null, async finish() { return true; }, cleanup() {} };
   if (!ds || executor?.kind !== "broker") return none;
   let base = null;
@@ -2740,6 +2761,15 @@ async function carrierForChildren({ o, ds, root, git, executor, stage, tag = "ri
     const carried = await import("../carried-cargo.mjs");
     const { brokerSection } = await import("../snapshot-broker.mjs");
     const sb = await carrierBroker({ o, root, ds, executor });
+    // Only a PRODUCER carrier (the gate's own web-build, windows-identity and stage-sidecar steps, which write declared inputs by design) takes the gate's digest of the
+    // declared inputs at stage open (absent included); the end-of-stage ledger re-verify then accepts any receipt state for an input that digest says the step changed.
+    // Every other carrier passes none: each receipt, adapter receipts included, must equal the stage-end digest of every declared input (strict), so a child that swaps
+    // an input around an admission and restores it is refused. A malformed declaration or an unreadable input is the refusal below, as before.
+    let openInputDigests = null;
+    if (producer) {
+      const { readDeclaredInputs: readInputsOf, declaredInputDigestsOf: digestInputsOf } = await import("../snapshot-request.mjs");
+      openInputDigests = digestInputsOf(ds.path, readInputsOf(ds.path), { allowAbsent: true });
+    }
     // Installing the carrier map sends nothing, so it records nothing: the child's own uncarried probes (`rustc -vV`, `--version`) never
     // reach the broker under a snapshot, and each carried request records its sub-handle just before it is sent (snapshot-broker.mjs).
     const checkoutDirs = await snapshotCargoWorkspaces({ git, ds, root });
@@ -2758,7 +2788,7 @@ async function carrierForChildren({ o, ds, root, git, executor, stage, tag = "ri
         finished = true;
         let problems;
         try {
-          problems = await installed.problems(sb);
+          problems = await installed.problems(sb, openInputDigests ? { openInputDigests } : {});
           // The output directories the stage's verified receipts name: the package stage's sealed manifest must record only these.
           for (const dir of installed.outputDirs?.() ?? []) ((ds.carriedByStage ??= {})[at] ??= new Set()).add(dir);
           // And by workspace, for the next stage's children: a receipt already names the output directory, so none asks Cargo for it.
@@ -4055,12 +4085,20 @@ export async function main(argv, io = {}) {
       const unitByName = new Map(rust.units.map((u) => [u.name, u]));
       const known = new Set(unitByName.keys());
       const builtBins = {};
-      const addBins = (dir, unit) => { if (dir && unit?.testLinksBins && unit.bins?.length) builtBins[dir] = [...new Set([...(builtBins[dir] ?? []), ...unit.bins])].sort(); };
+      // Where Cargo put them: `<dir>/debug` on a direct host, `<dir>/<triple>/debug` on a broker host, whose jobs build with --target <triple> (the receipt
+      // names it, `targetTriple`). A broker row with no triple records nothing for its directory: a guessed path could vouch for a stale binary.
+      const addBins = (dir, unit, profile) => {
+        if (!dir || !profile || !unit?.testLinksBins || !unit.bins?.length) return;
+        const prior = builtBins[dir];
+        if (prior && prior.profile !== profile) { builtBins[dir] = { profile: null, bins: [] }; return; }
+        builtBins[dir] = { profile, bins: [...new Set([...(prior?.bins ?? []), ...unit.bins])].sort() };
+      };
       for (const r of scanResult.scans) {
         // A row answered from the scan cache compiled nothing in this run: the bytes in the target are not vouched for by it.
         if (r.status !== "pass" || r.cached === true || !/^test:rust(?:-serial)?:/.test(String(r.id))) continue;
         const unit = unitByName.get(rustUnitOfScanId(r.id, known));
-        addBins(snapshotBroker ? r.snapshotEvidence?.outputDir : targetDirs?.[unit?.cargoDir ?? "."], unit);
+        if (snapshotBroker) addBins(r.snapshotEvidence?.outputDir, unit, r.snapshotEvidence?.targetTriple ? `${r.snapshotEvidence.targetTriple}/debug` : null);
+        else addBins(targetDirs?.[unit?.cargoDir ?? "."], unit, "debug");
       }
       const outputWorkspaces = (snapshotBroker ? scanResult.scans.map((r) => r.snapshotEvidence?.outputDir) : Object.values(targetDirs ?? {})).filter(Boolean).map((dir) => [dir]);
       o.onCompileOutputs?.(outputWorkspaces.map(([dir]) => dir), builtBins);

package/broker-wire.mjs

@@ -217,6 +217,10 @@ export function refusalInCapturedOutput(text) {
     const diagnosis = diagnoseControlReply(event);
     if (diagnosis.kind === "refused") return { code: diagnosis.code, refusal: diagnosis.refusal, retryable: diagnosis.retryable === true, message: diagnosis.message };
   }
+  // The client's plain-text form of the same refusal (its stderr without --json): `rustright: admission is paused; resume with rustright resume-admission`.
+  // Without it a paused broker read as "no request reference" (HeardRight Mac, 2026-11-02).
+  const paused = /^rustright: (admission is paused\b[^\r\n]*)/m.exec(String(text ?? ""));
+  if (paused) return { code: "RK_ADMISSION_PAUSED", refusal: "paused", retryable: false, message: paused[1].trim() };
   return null;
 }
 

package/carried-cargo.mjs

@@ -136,10 +136,10 @@ function finish(ledgerDir, dir, workspaces = {}) {
   const checkoutRoots = Object.values(workspaces);
   return {
     /** Every call of the stage that is not a completed, verified success, and every verified call the gate cannot verify again itself. */
-    async problems(sb) {
+    async problems(sb, opts = {}) {
       const { entries, problems } = readLedger(ledgerDir, UNSCOPED);
       const out = [...problems];
-      if (sb) out.push(...await verifyBrokerLedger(entries, sb));
+      if (sb) out.push(...await verifyBrokerLedger(entries, sb, opts));
       return out;
     },
     /** The verified calls' output directories, in call order (the receipts'; an adapter job's nested children's included). */

package/deterministic-scans.mjs

@@ -37,7 +37,7 @@ import { observedEnvOf, readRequestRef, verifySnapshotReceipt, writeSnapshotRequ
 import { SCAN_TOKEN_ENV, appendLedger, readLedger, scanTokenOf, unclaimedLedgers } from "./cargo-ledger.mjs";
 import { brokerSection, carryBrokerAdapterAsync, verifyBrokerLedger } from "./snapshot-broker.mjs";
 import { ADMISSION_POLL_MS, CARRIED_CANCEL_GRACE_MS, QUEUED_CEILING_FACTOR, createBrokerLive, createRunClock, createStatusPoller, watchBrokerAdmission } from "./broker-admission.mjs";
-import { CANCEL_WAIT_ENV, operationDeadlineEnv } from "./broker-wire.mjs";
+import { CANCEL_WAIT_ENV, operationDeadlineEnv, refusalInCapturedOutput } from "./broker-wire.mjs";
 import { removeCarrier } from "./carrier-census.mjs";
 
 export const SCAN_RESULT_SCHEMA = "rightkit.deterministic-scans/1";
@@ -2755,11 +2755,19 @@ export async function runScans(plan, options = {}) {
           // The broker's signed account of that request: the receipt verifies against this host's pins and its snapshotEvidence names
           // this commit, this snapshot unchanged from START to exit, this ownership and the output directory. Anything less fails the row.
           if (carrier) {
+            // A typed broker refusal with no request reference (admission paused, a cutover drain): nothing was admitted under this scan's sub-handle, so it is
+            // recorded unsent at once, as a busy connection is; otherwise a dead owner's record could never be reclaimed (HeardRight Mac, 2026-11-02).
+            if (!fs.existsSync(path.join(carrier.refDir, "request.json"))) {
+              const refused = refusalInCapturedOutput(`${r?.stdout ?? ""}\n${r?.stderr ?? ""}`);
+              if (refused && typeof deps.snapshotBroker?.markBrokerUnsent === "function") {
+                try { deps.snapshotBroker.markBrokerUnsent(carrier.made.carrier.ownership.handle, `the broker refused the submit before admitting it (${refused.code}): nothing was spawned`); } catch { /* the reclaim then judges the sub-handle as before */ }
+              }
+            }
             try {
               const ref = readRequestRef(path.join(carrier.refDir, "request.json"));
               const receipt = await deps.snapshotBroker.receiptOf(ref.requestId);
               const { evidence } = verifySnapshotReceipt(receipt, { pins: deps.snapshotBroker.pins, jobId: ref.requestId, carrier: carrier.made.carrier, argv: carrier.cargoArgv, workspace: ref.workspace, observedEnv: observedEnvOf({ ...deps.env, ...s.env, ...(extraEnv ?? {}) }, deps.platform ?? process.platform), checkout: deps.snapshotBroker.checkout, outputRoots: deps.snapshotBroker.outputRoots, platform: deps.snapshotBroker.platform ?? deps.platform ?? process.platform });
-              row.snapshotEvidence = { requestId: ref.requestId, outputDir: evidence.outputDir, cargoDir: s.cwd ?? ".", treeAtStart: evidence.snapshot.treeAtStart, treeAtExit: evidence.snapshot.treeAtExit };
+              row.snapshotEvidence = { requestId: ref.requestId, outputDir: evidence.outputDir, cargoDir: s.cwd ?? ".", targetTriple: typeof receipt?.targetTriple === "string" && /^[A-Za-z0-9_.]+(?:-[A-Za-z0-9_.]+){1,4}$/.test(receipt.targetTriple) ? receipt.targetTriple : null, treeAtStart: evidence.snapshot.treeAtStart, treeAtExit: evidence.snapshot.treeAtExit };
             } catch (e) {
               status = "fail"; code = "SNAPSHOT_EVIDENCE"; detail = `${s.id}: the broker's snapshot evidence did not verify (${e.code ?? "error"}: ${e.message})`;
             }

package/disk-command.mjs

@@ -210,7 +210,10 @@ function defaultGlobalRoots() {
   return roots;
 }
 
-export function scheduleSpec({ platform = process.platform, nodePath = process.execPath, cli = path.join(path.dirname(fileURLToPath(import.meta.url)), "cli", "right-release.mjs"), home = os.homedir() } = {}) {
+// The node a scheduled job runs is the real file, never a version manager's link to it: nvm-windows' C:\\nvm4w\\nodejs is a symlink into the user profile that a
+// scheduled task context cannot always follow (the Dell task failed with 0x80070003, path not found, 2026-11-02).
+const realNode = () => { try { return realpathSync.native(process.execPath); } catch { return process.execPath; } };
+export function scheduleSpec({ platform = process.platform, nodePath = realNode(), cli = path.join(path.dirname(fileURLToPath(import.meta.url)), "cli", "right-release.mjs"), home = os.homedir() } = {}) {
   if (platform === "darwin") {
     // launchd cannot open log files on an external volume for a background job (spawn fails with EX_CONFIG);
     // `disk run` writes its own structured log to disk-hygiene.jsonl on the heavy volume.

package/gate-stages.mjs

@@ -234,10 +234,11 @@ export function compileKeyOf(env = {}) {
 export const COMPILE_PROFILE_DIR = "debug";
 
 /** How `binaries` was chosen: only the bin targets the compile built in that directory (a consumer requires this marker). */
-export const BUILT_BINARIES_SCHEMA = "built-bin-targets/1";
+export const BUILT_BINARIES_SCHEMA = "built-bin-targets/2";
 
 /**
- * The sha256 of each binary this compile built (rustright#209 item 5): for every output directory, the files `<dir>/debug/<bin>[.exe]` of the
+ * The sha256 of each binary this compile built (rustright#209 item 5): for every output directory, the files `<dir>/<profile>/<bin>[.exe]` (`debug`, or
+ * `<triple>/debug` for a broker build with --target; each row's `path` names it, schema built-bin-targets/2) of the
  * bin targets the compile built there (`builtBins`, { [dir]: [bin target name] }: the units whose scans ran `cargo build -p <crate>` in that
  * directory's workspace, so each binary was rebuilt or proven fresh by Cargo for this commit). Any other file in `debug/`, a stale binary of a
  * removed or renamed target or of a package this run did not build, is never recorded. A census proves nothing once truncated (a broker
@@ -247,12 +248,16 @@ export const BUILT_BINARIES_SCHEMA = "built-bin-targets/1";
 export function compiledBinaries(builtBins = {}, { platform = process.platform, stat = (f) => fs.statSync(f), readFile = (f) => fs.readFileSync(f) } = {}) {
   const out = [];
   for (const dir of Object.keys(builtBins ?? {}).filter((d) => typeof d === "string" && d).sort()) {
-    for (const bin of [...new Set(builtBins[dir] ?? [])].sort()) {
+    // { profile, bins }: profile is the directory under `dir` Cargo wrote them to (`debug`, or `<triple>/debug` for a --target build); a bare array is `debug`.
+    const entry = Array.isArray(builtBins[dir]) ? { profile: COMPILE_PROFILE_DIR, bins: builtBins[dir] } : builtBins[dir] ?? {};
+    if (typeof entry.profile !== "string" || !/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)?$/.test(entry.profile) || entry.profile.split("/").some((c) => c === "." || c === "..")) continue;
+    for (const bin of [...new Set(entry.bins ?? [])].sort()) {
       const name = `${bin}${platform === "win32" ? ".exe" : ""}`;
-      const file = path.join(dir, COMPILE_PROFILE_DIR, name);
+      const rel = `${entry.profile}/${name}`;
+      const file = path.join(dir, ...rel.split("/"));
       let info = null;
       try { info = stat(file); } catch { info = null; }
-      out.push(info?.isFile?.() ? { dir, name, size: info.size, sha256: sha256(readFile(file)) } : { dir, name, size: null, sha256: null });
+      out.push(info?.isFile?.() ? { dir, path: rel, name, size: info.size, sha256: sha256(readFile(file)) } : { dir, path: rel, name, size: null, sha256: null });
     }
   }
   return out;

package/local-publish.mjs

@@ -368,6 +368,10 @@ export function localTestPlan({ kind, unit, dir, config, manifest, batch = false
   // Every tested feature set is linted (-D warnings), not only the first.
   if (!batch) for (const features of featureSets) steps.push({ command: "cargo", args: ["clippy", "-p", unit, "--message-format=json-render-diagnostics", "--no-deps", "--all-targets", ...features, "--", "-D", "warnings"], test: false });
   for (const features of allFeatureCheckSets(entry)) steps.push({ command: "cargo", args: ["check", "-p", unit, "--message-format=json-render-diagnostics", "--all-targets", ...features], test: false });
+  // rustdoc with -D warnings, for the tested and the checked feature sets: the same rows the CI shards (scripts/ci/gate.mjs) and
+  // publish.yml's native verify run, so a broken or private intra-doc link fails this unit stage instead of a later verify.
+  const docSets = [...new Map([...featureSets, ...allFeatureCheckSets(entry)].map((features) => [JSON.stringify(features), features])).values()];
+  for (const features of docSets) steps.push({ command: "cargo", args: ["doc", "-p", unit, "--message-format=json-render-diagnostics", "--no-deps", ...features], test: false, env: { RUSTDOCFLAGS: "-D warnings" } });
   // Consumer rows (separate Cargo workspaces) gate only this crate: they come from this crate's own entry.
   const consumers = consumerRows(unit, entry);
   for (const row of consumers) steps.push(...consumerRowInvocations(row));
@@ -666,7 +670,7 @@ async function* publishUnitStages(parsed, deps, batch) {
     // A crate's own steps run in its Cargo workspace (its own Cargo.lock and target directory, #1285); a consumer row names its
     // separate workspace by --manifest-path relative to the repository root.
     const stepCwd = kind === "cargo" && step.command === "cargo" && !step.args.includes("--manifest-path") ? unitPath : workspaceRoot;
-    const result = await run(step.command, step.command === "cargo" ? withCargoJobs(step.args, parsed.jobs) : step.args, { cwd: stepCwd, env });
+    const result = await run(step.command, step.command === "cargo" ? withCargoJobs(step.args, parsed.jobs) : step.args, { cwd: stepCwd, env: step.env ? { ...env, ...step.env } : env });
     const row = { command: commandText, ok: false, isTest: step.test && TEST_COMMAND.test(commandText) };
     if (result.error || result.status !== 0) {
       steps.push(row);

package/package-recipe-targets.mjs

@@ -272,6 +272,16 @@ function stageSidecarsSpec(value) {
   };
 }
 
+/** The triple a `targets.mac.macPackage` spec builds for: `triple`, else this host's arch when `universal: false`, else universal-apple-darwin. */
+export function macPackageTriple(spec) {
+  return spec.triple ?? (spec.universal === false ? (process.arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin") : "universal-apple-darwin");
+}
+
+/** True when the macPackage spec stages its declared sidecars itself (`stageSidecars: true | { config?, receipt? }`, the recipe's first prepare step). */
+export function macPackageStagesSidecars(spec) {
+  return spec.stageSidecars !== undefined && spec.stageSidecars !== false;
+}
+
 export function expandMacPackageTarget(target, { appRoot, config = {}, env = process.env, resolveTargetRoot = cargoResolveTargetRoot, managedRoots }) {
   if (!target?.macPackage) return withoutRecipe(target);
   const spec = target.macPackage;
@@ -291,7 +301,7 @@ export function expandMacPackageTarget(target, { appRoot, config = {}, env = pro
   if (spec.updater !== undefined && spec.updater !== true && spec.updater !== false && typeof spec.updater !== "string") fail("targets.mac.macPackage.updater must be true or an app-relative .tar.gz path");
   if (typeof spec.updater === "string" && !/\.tar\.gz$/i.test(relativeInside(spec.updater, "targets.mac.macPackage.updater"))) fail("targets.mac.macPackage.updater must end in .tar.gz");
   // Tauri's universal-apple-darwin target builds both slices and lipos them itself.
-  const triple = spec.triple ?? (spec.universal === false ? (process.arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin") : "universal-apple-darwin");
+  const triple = macPackageTriple(spec);
   if (spec.triple !== undefined) {
     const wrong = [...MAC_TRIPLES, "universal-apple-darwin"].find((other) => other !== triple && target.notarize.app.replaceAll("\\", "/").split("/").includes(other));
     if (wrong) fail(`targets.mac.macPackage.triple is ${triple} but notarize.app is under ${wrong}; the built .app lives in the ${triple} directory`);
@@ -301,7 +311,7 @@ export function expandMacPackageTarget(target, { appRoot, config = {}, env = pro
   const sidecars = stageSidecarsSpec(spec.stageSidecars);
   if (sidecars) {
     // First prepare step: stage the declared sidecars for this triple (universal: both slices, lipo, <name>-universal-apple-darwin).
-    extras.prepare = [{ cmd: "right-release", args: ["stage-sidecar", "--target", triple, ...(sidecars.config ? ["--config", sidecars.config] : [])] }, ...extras.prepare];
+    extras.prepare = [{ cmd: "right-release", args: ["stage-sidecar", "--target", triple, "--if-stale", ...(sidecars.config ? ["--config", sidecars.config] : [])] }, ...extras.prepare];
   }
   let helpers;
   if (spec.nativeHelpers !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "description": "Portable release CLI/SDK with fail-closed public GitHub Releases and private R2 + RightApps distribution.",
   "license": "MIT OR Apache-2.0",
   "type": "module",

package/rightkit-versions.json

@@ -49,7 +49,7 @@
     "@rightkit/qa": "0.6.2",
     "@rightkit/qa-chrome": "0.1.12",
     "@rightkit/react-shell": "0.7.2",
-    "@rightkit/release": "0.6.21",
+    "@rightkit/release": "0.6.23",
     "@rightkit/settings-ui": "0.7.0",
     "@rightkit/social-ui": "0.1.0",
     "@rightkit/system-ui": "0.1.0",

package/snapshot-broker.mjs

@@ -27,7 +27,7 @@ import { removeCarrier, sweepSnapshotRequests } from "./carrier-census.mjs";
 import { DEFAULT_RETRY_WINDOW_MS, RETRYABLE_OUTCOME_CODES, clientGuardMs, diagnoseControlReply, drainFrames, operationDeadlineEnv, operationOutcomeInOutput, overCapProblem, refusalInCapturedOutput, retryPauseMs, sleepSync } from "./broker-wire.mjs";
 import { OWNERSHIP_ENV, OWNERSHIP_FILE_ENV, markCarriedSend, markCarriedUnsent } from "./ownership-mark.mjs";
 import {
-  MANAGED_RUST_ENVIRONMENT_KEYS, SNAPSHOT_REQUEST_SCHEMA, SnapshotRequestError, argvSha256, isCallHandleOf, lockedArgv, observedEnvOf, readDeclaredInputs, readRequestRef, verifySnapshotReceipt, writeSnapshotRequest,
+  MANAGED_RUST_ENVIRONMENT_KEYS, SNAPSHOT_REQUEST_SCHEMA, SnapshotRequestError, argvSha256, declaredInputDigestsOf, isCallHandleOf, lockedArgv, observedEnvOf, readDeclaredInputs, readRequestRef, verifySnapshotReceipt, writeSnapshotRequest,
 } from "./snapshot-request.mjs";
 
 /**
@@ -438,6 +438,10 @@ function carryBrokerCargoOnce({ words, cwd, env, section, workspace, checkoutWor
     // RK_BROKER_BUSY with no request reference: the connection never opened, so no byte reached the broker. That is the gate's own proof that this sub-handle was never sent (GB-21), recorded under
     // the ownership lock so the retry's own sub-handle, not this one, is what the stage waits on; a busy answer after a reference exists (a reconnect) proves nothing of the kind.
     if (outcome.status === "unverified" && outcome.code === "broker-busy" && ref === null) markCarriedUnsentRequest({ section, env, callHandle: made.carrier.ownership.handle, reason: "every broker connection was busy (RK_BROKER_BUSY): the connection never opened and no byte was sent" });
+    // A typed REJECTED result (admission paused, a cutover drain, ...) with no request reference: the broker refused the submit before it admitted anything, so nothing
+    // runs under this sub-handle and the broker will never list it as a member. Recorded unsent now, or a dead owner's record could never be reclaimed (HeardRight Mac,
+    // 2026-11-02: 42 paused refusals left a member-less sub-handle the broker answers UNKNOWN for).
+    else if (outcome.status === "unverified" && /^broker-refused-/.test(String(outcome.code)) && ref === null) markCarriedUnsentRequest({ section, env, callHandle: made.carrier.ownership.handle, reason: `the broker refused the submit before admitting it (${outcome.code}): nothing was spawned` });
     // GB-53: captured output that lost a frame to FRAME_OVER_CAP (or a result the broker replaced with RK_RESPONSE_OVER_CAP) is truncated: refused, never read as complete.
     if (outcome.status === "verified" && capture) {
       const drained = drainFrames(`${out.stdout}\n${out.stderr}`);
@@ -650,6 +654,10 @@ function* carryBrokerAdapterSteps({ adapter, words, cwd, env, section, record, e
     // RK_BROKER_BUSY with no request reference: the connection never opened, so no byte reached the broker. That is the gate's own proof that this sub-handle was never sent (GB-21), recorded under
     // the ownership lock so the retry's own sub-handle, not this one, is what the stage waits on; a busy answer after a reference exists (a reconnect) proves nothing of the kind.
     if (outcome.status === "unverified" && outcome.code === "broker-busy" && ref === null) markCarriedUnsentRequest({ section, env, callHandle: made.carrier.ownership.handle, reason: "every broker connection was busy (RK_BROKER_BUSY): the connection never opened and no byte was sent" });
+    // A typed REJECTED result (admission paused, a cutover drain, ...) with no request reference: the broker refused the submit before it admitted anything, so nothing
+    // runs under this sub-handle and the broker will never list it as a member. Recorded unsent now, or a dead owner's record could never be reclaimed (HeardRight Mac,
+    // 2026-11-02: 42 paused refusals left a member-less sub-handle the broker answers UNKNOWN for).
+    else if (outcome.status === "unverified" && /^broker-refused-/.test(String(outcome.code)) && ref === null) markCarriedUnsentRequest({ section, env, callHandle: made.carrier.ownership.handle, reason: `the broker refused the submit before admitting it (${outcome.code}): nothing was spawned` });
     // GB-53: captured output that lost a frame to FRAME_OVER_CAP (or a result the broker replaced with RK_RESPONSE_OVER_CAP) is truncated: refused, never read as complete.
     if (outcome.status === "verified" && capture) {
       const drained = drainFrames(`${out.stdout}\n${out.stderr}`);
@@ -698,9 +706,26 @@ export const runBrokerCargo = (call) => carryBrokerCargo(call).status;
  * again now, verifies against THIS gate's commit, snapshot, ownership handle and pins, and its carrier was used once: a nonce or a
  * request id that appears twice in the run (`seen`) is a replay. Returns the problems; none means every call verified.
  */
-export async function verifyBrokerLedger(entries, sb, { seen = { nonces: new Set(), ids: new Set(), handles: new Set() } } = {}) {
+export async function verifyBrokerLedger(entries, sb, { seen = { nonces: new Set(), ids: new Set(), handles: new Set() }, openInputDigests = null } = {}) {
   seen.handles ??= new Set();
   const problems = [];
+  // `openInputDigests` is supplied ONLY by a producer carrier (the gate's own web-build, windows-identity and stage-sidecar steps, which write declared inputs by design):
+  // the inputs whose digest at stage open (the gate's own, allowAbsent) differs from the digest at stage end, computed once, are then "produced" and accept any well-formed
+  // receipt entry. Without it (every other carrier) nothing is produced: every receipt, cargo AND adapter, must equal the stage-end digest input by input, so an input a child
+  // swapped around an admission and restored is refused. closeSnapshotStage's attribution check is what makes "produced" safe. A failure to digest ends the verification with that problem.
+  let inputPolicy = null;
+  const ledgered = entries.some((e) => e.mode === "broker" && e.status === "verified");
+  if (ledgered) {
+    try {
+      const end = declaredInputDigestsOf(sb.snapshot.path, readDeclaredInputs(sb.snapshot.path), { platform: sb.platform, allowAbsent: true });
+      const produced = new Set();
+      if (Array.isArray(openInputDigests)) {
+        if (openInputDigests.length !== end.length) throw new SnapshotRequestError("ledger", "the stage-open digest of the declared inputs does not match the declaration");
+        end.forEach((d, i) => { if (openInputDigests[i]?.path !== d.path) throw new SnapshotRequestError("ledger", "the stage-open digest of the declared inputs is not in declaration order"); if (canonicalJson(openInputDigests[i]) !== canonicalJson(d)) produced.add(d.path); });
+      }
+      inputPolicy = { produced, current: end };
+    } catch (error) { return [`the gate cannot digest the snapshot's declared inputs at the end of the stage (${error.code ?? "error"}: ${error.message})`]; }
+  }
   for (const e of entries) {
     if (e.mode !== "broker" || e.status !== "verified") continue;
     const adapter = typeof e.adapter === "string" && e.adapter ? e.adapter : null;
@@ -733,7 +758,7 @@ export async function verifyBrokerLedger(entries, sb, { seen = { nonces: new Set
         ownership: { handle: e.ownershipHandle }, primaryCwd: e.checkoutCwd, argvSha256: argvSha256(e.argv), nonce: e.nonce,
       };
       const receipt = await sb.receiptOf(e.requestId);
-      const verified = verifySnapshotReceipt(receipt, { pins: sb.pins, jobId: e.requestId, carrier, argv: e.argv, workspace: e.workspace, observedEnv: e.observedEnv ?? {}, adapter, adapterEnv: e.adapterEnv ?? {}, checkout: sb.checkout, outputRoots: sb.outputRoots, platform: sb.platform });
+      const verified = verifySnapshotReceipt(receipt, { pins: sb.pins, jobId: e.requestId, carrier, argv: e.argv, workspace: e.workspace, observedEnv: e.observedEnv ?? {}, adapter, adapterEnv: e.adapterEnv ?? {}, checkout: sb.checkout, outputRoots: sb.outputRoots, platform: sb.platform, inputPolicy });
       if (adapter !== null) {
         // The children the ledger records (the bundle root and the stage's output directories are read from them) are the signed ones, and no more.
         if (canonicalJson(e.nestedChildren ?? null) !== canonicalJson(verified.nestedChildren)) throw new SnapshotRequestError("nested", "the nested children the call recorded are not the ones the broker's receipt signs");

package/snapshot-request.mjs

@@ -356,9 +356,9 @@ export function assertSuppliedInputs(snapshotRoot, supplied) {
  * anywhere, a special file, or a limit breach is a refusal. The name is the input's path components joined by `/` on EVERY platform (GB-49: RustRight hashes
  * `/` on Windows too, so a `\` in a declaration or a platform separator never reaches the hash), UTF-8, no Unicode normalisation.
  *
- * `allowAbsent` is set ONLY for a non-compiling snapshot-bound request (the carried read-only set): a declared input that does not exist in the
- * snapshot (ENOENT/ENOTDIR on a component; a link is still refused) is then the entry `{ path, absent: true }` (no `sha256`, 0 files, 0 bytes), the
- * wire form RustRight signs. A compile request never allows it: a missing declared input is a refusal there (the build outputs must exist).
+ * `allowAbsent` makes a declared input that does not exist in the snapshot (ENOENT/ENOTDIR on a component; a link is still refused) the entry
+ * `{ path, absent: true }` (no `sha256`, 0 files, 0 bytes), the wire form RustRight signs. The broker admits every request with an absent input
+ * (a compile is refused at exit only if an input CHANGED while it ran, rustright d378d32), so the receipt check digests with it for every class.
  */
 export function declaredInputDigestsOf(snapshotRoot, inputs, { allowAbsent = false } = {}) {
   let files = 0; let bytes = 0;
@@ -528,7 +528,8 @@ export function verifyNestedChildren(evidence, receipt, { snapshotPath, checkout
  * Beyond the signature, the job, the nonce and the request digest, the receipt must carry (item 7 row 7.22):
  *   - signed SUCCEEDED with exit 0, and signed snapshotEvidence equal to the receipt's copies (commit, ownership handle, request id,
  *     snapshot path, `treeAtStart` = `treeAtExit` = the expected tree);
- *   - `declaredInputDigests` equal to the gate's own digest of the snapshot's declared inputs, read from the snapshot now;
+ *   - `declaredInputDigests` well formed (the declaration's paths in order, each `{path, sha256}` or `{path, absent:true}`), and for a cargo request equal to the gate's own
+ *     digest of the snapshot's declared inputs read now (absent included; an adapter request skips the comparison, it may produce an input); `inputPolicy` replaces that digest (see below);
  *   - `outputDir` absolute, outside the snapshot and the checkout, and a managed generation target under one of `outputRoots`;
  *   - signed stageEvidence (freshness, attribution, toolchain) equal to the receipt's;
  *   - for a compile, freshness.causeEvidence (rustright.cause-evidence.v1) coherent with its census and with a verdict of `explained`: refused as `evidence` when missing,
@@ -536,7 +537,7 @@ export function verifyNestedChildren(evidence, receipt, { snapshotPath, checkout
  *   - timingsMs, exit, diagnosticsPath, brokerVersion and executor present with their types; the retired `verdict` and `refreshed` are refused (GB-30: Class A and its verdict reuse are the gate's).
  * `checkout` and `outputRoots` are required: without them nothing can be said about where the outputs went, so it refuses.
  */
-export function verifySnapshotReceipt(receipt, { pins, jobId, carrier, argv, workspace, observedEnv = {}, adapter = null, adapterEnv = {}, checkout, outputRoots, platform = process.platform, canonicalPath = (p) => fs.realpathSync.native(p), digestInputs = declaredInputDigestsOf, readInputs = readDeclaredInputs }) {
+export function verifySnapshotReceipt(receipt, { pins, jobId, carrier, argv, workspace, observedEnv = {}, adapter = null, adapterEnv = {}, checkout, outputRoots, platform = process.platform, canonicalPath = (p) => fs.realpathSync.native(p), digestInputs = declaredInputDigestsOf, readInputs = readDeclaredInputs, inputPolicy = null }) {
   const requestDigest = requestDigestOf(snapshotRequestCore({ argv, workspace, observedEnv, carrier, adapter, adapterEnv }));
   const payload = verifyProvenance(receipt, pins, { jobId, nonce: carrier.nonce, requestDigest });
   // The signed outcome, not the client's exit code: a passing row needs the broker to have signed SUCCEEDED with exit 0 and no
@@ -563,21 +564,36 @@ export function verifySnapshotReceipt(receipt, { pins, jobId, carrier, argv, wor
     commit: carrier.commit, tree: carrier.snapshot.expectedTree, jobId, handle: carrier.ownership.handle, snapshotPath: carrier.snapshot.path,
     samePath: (a, b) => { try { return canonicalPath(a) === canonicalPath(b); } catch { return false; } },
   });
-  // Declared inputs: what the broker digested in place must be what the gate digests in the snapshot, from the same manifest.
-  // An absent entry ({path, absent:true}) is evidence only for a non-compiling snapshot-bound request, and only when the gate's own read of the
-  // snapshot finds the input absent too: the gate digests with `allowAbsent` for that class alone, so a receipt that says absent where the gate
-  // sees the input present (or present where it is absent) differs below and is refused. A compile receipt never carries one.
-  const nonCompile = adapter === null && !isCompileClass(argv);
-  if (!nonCompile && Array.isArray(evidence.declaredInputDigests) && evidence.declaredInputDigests.some((d) => isObject(d) && (d.absent !== undefined || d.sha256 === undefined))) {
-    fail("evidence", "the signed declaredInputDigests carry an absent declared input on a compile request (cargo " + `${cargoSubcommandOf(argv)}); only a non-compiling request may record one`);
-  }
-  let gateInputs; let gateDigests;
+  // Declared inputs. The broker admits every snapshot request with a declared input absent and records it as `{ path, absent: true }` in the signed
+  // snapshotEvidence.declaredInputDigests (declaration order); a compile is refused at exit if any declared input changed while it ran, an absent one
+  // appearing included (rustright d378d32). So an absent entry is evidence on any request, and the receipt is judged per class:
+  //   - a cargo request (adapter === null): the receipt's digests equal the gate's current digest of the snapshot's inputs (the child copies the next
+  //     file only after the call returns, and the broker refused a compile whose inputs changed during it);
+  //   - an adapter request: the digest comparison is skipped (the job may be the producer of an input), but the receipt's entries must be well formed,
+  //     the declaration's paths in declaration order, each exactly `{ path, sha256 }` or exactly `{ path, absent: true }`;
+  //   - with `inputPolicy` ({ produced: Set<path>, current: digest array }) the gate's own digest is replaced: an input whose path is in `produced` accepts any
+  //     well-formed entry (absent or any sha256); every other input must equal `current`'s entry for that path (the swap-around-admission refusal).
+  let gateInputs; let gateDigests = null;
   try {
     gateInputs = readInputs(carrier.snapshot.path);
-    gateDigests = digestInputs(carrier.snapshot.path, gateInputs, { platform, allowAbsent: nonCompile });
+    if (!inputPolicy && adapter === null) gateDigests = digestInputs(carrier.snapshot.path, gateInputs, { platform, allowAbsent: true });
   } catch (e) { fail("evidence", `the gate cannot digest the snapshot's declared inputs (${e.message})`); }
   if (!same(gateInputs, carrier.declaredInputs?.inputs)) fail("evidence", "the snapshot's declared inputs are not the ones this request carried (declaredInputs differs from the snapshot declaration)");
-  if (!same(evidence.declaredInputDigests, gateDigests)) fail("evidence", "the signed declaredInputDigests are not the gate's own digest of the snapshot's declared inputs (an input the receipt records absent must be absent in the snapshot, and the reverse)");
+  const signedInputs = evidence.declaredInputDigests;
+  const wellFormed = Array.isArray(signedInputs) && signedInputs.length === gateInputs.length && signedInputs.every((d, i) => {
+    if (!isObject(d) || d.path !== gateInputs[i]) return false;
+    const keys = Object.keys(d).sort().join();
+    return (keys === "path,sha256" && typeof d.sha256 === "string" && /^[0-9a-f]{64}$/.test(d.sha256)) || (keys === "absent,path" && d.absent === true);
+  });
+  if (!wellFormed) fail("evidence", "the signed declaredInputDigests are not the snapshot's declared inputs in declaration order, each exactly { path, sha256 } or { path, absent: true }");
+  if (inputPolicy) {
+    const { produced, current } = inputPolicy;
+    if (!(produced instanceof Set) || !Array.isArray(current) || current.length !== gateInputs.length) fail("evidence", "the gate's input policy is not { produced: Set, current: one digest per declared input }");
+    signedInputs.forEach((d, i) => {
+      if (produced.has(gateInputs[i])) return;
+      if (!same(d, current[i])) fail("evidence", `the signed declaredInputDigests entry for ${gateInputs[i]} is not the gate's own digest of that input at the end of the stage, and the stage did not change it (an input the receipt records absent must be absent, and the reverse)`);
+    });
+  } else if (adapter === null && !same(signedInputs, gateDigests)) fail("evidence", "the signed declaredInputDigests are not the gate's own digest of the snapshot's declared inputs (an input the receipt records absent must be absent in the snapshot, and the reverse)");
   // Output directory: where the outputs went must be the broker's managed generation target, never under the snapshot or the checkout.
   const out = evidence.outputDir;
   if (typeof out !== "string" || !path.isAbsolute(out) && !path.win32.isAbsolute(out)) fail("evidence", "the signed evidence names no absolute output directory");

package/stage-ledger.mjs

@@ -137,12 +137,15 @@ export const sameEntries = (x, y) => { const d = diffEntries(x, y); return !d.ad
  * The attribution diff of a staging step: every path the step added must be one it reported (or its receipt), and every path it
  * reported must exist. Anything else is an unattributed write. `reported` and `receipt` are snapshot-relative posix paths.
  */
-export function attributionProblems({ before, after, reported, receipt }) {
+export function attributionProblems({ before, after, reported, receipt, removable = [] }) {
   const d = diffEntries(before, after);
   const allowed = new Set([...reported, ...(receipt ? [receipt] : [])]);
+  // A step re-staging another target may replace a file an earlier staging step staged (a CHANGED path it reports is allowed above) and may remove one (a path in `removable`,
+  // the staged sidecar outputs of the step's own earlier staging, which a `wipeStageDir` re-stage deletes); nothing else may be removed.
+  const removableSet = new Set(removable);
   const problems = [];
   for (const p of [...d.added, ...d.changed]) if (!allowed.has(p)) problems.push(`${p} was written by the staging step but it did not report it`);
-  for (const p of d.removed) problems.push(`${p} was removed by the staging step`);
+  for (const p of d.removed) if (!removableSet.has(p)) problems.push(`${p} was removed by the staging step`);
   const present = new Set(after.map((e) => e.path));
   for (const p of allowed) if (!present.has(p)) problems.push(`${p} was reported by the staging step but is not in the snapshot as a ledger entry`);
   return problems;

package/stage-sidecar-command.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// `right-release stage-sidecar [--config right-release.config.json] [--target <triple>] [--check] [--json]` (bogusyogi/rightkit#345):
+// `right-release stage-sidecar [--config right-release.config.json] [--target <triple>|package] [--if-stale] [--check] [--json]` (bogusyogi/rightkit#345):
 // stages the config's declarative `sidecars` into src-tauri/binaries with Tauri externalBin naming. `--check` validates
 // the manifest and prints the plan without building, downloading, copying or deleting anything (for template gates).
 import path from "node:path";
@@ -9,7 +9,7 @@ import { planSidecarStaging, resolveTargetTriple, stageSidecars } from "./stage-
 import { readSourceSplit } from "./source-split.mjs";
 
 export function parseStageSidecarArgs(argv, cwd = process.cwd()) {
-  const opts = { config: defaultReleaseConfigFile(cwd), target: undefined, json: false, check: false };
+  const opts = { config: defaultReleaseConfigFile(cwd), target: undefined, json: false, check: false, ifStale: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--config" || arg === "--target") {
@@ -19,6 +19,7 @@ export function parseStageSidecarArgs(argv, cwd = process.cwd()) {
       i += 1;
     } else if (arg === "--json") opts.json = true;
     else if (arg === "--check") opts.check = true;
+    else if (arg === "--if-stale") opts.ifStale = true;
     else throw new Error(`unknown stage-sidecar argument: ${arg}`);
   }
   return opts;
@@ -57,15 +58,23 @@ async function main() {
   const config = await importReleaseConfig(configPath, { lenient: true });
   if (config?.sidecars === undefined) throw new Error(`${opts.config} declares no sidecars`);
   if (opts.check) {
-    const target = opts.target ?? process.env.TAURI_ENV_TARGET_TRIPLE ?? nodeHostTriple();
+    const target = (opts.target === "package" ? undefined : opts.target) ?? process.env.TAURI_ENV_TARGET_TRIPLE ?? nodeHostTriple();
     const plan = planSidecarStaging({ manifest: config.sidecars, target });
     if (opts.json) console.log(JSON.stringify(plan, null, 2));
     else for (const line of formatSidecarPlan(plan)) console.log(line);
     return;
   }
-  const target = resolveTargetTriple({ target: opts.target, cwd: appRoot });
+  // `--target package` (the gate's package stage): the triple the config's Mac package recipe stages for (its first prepare step's own
+  // --target), decided here in the child that already loaded the config, so the gate never imports app code; otherwise the host's.
+  let wanted = opts.target;
+  if (wanted === "package") {
+    const { macPackageStagesSidecars, macPackageTriple } = await import("./package-recipe-targets.mjs");
+    const mac = process.platform === "darwin" ? config?.targets?.mac?.macPackage : undefined;
+    wanted = mac && macPackageStagesSidecars(mac) ? macPackageTriple(mac) : undefined;
+  }
+  const target = resolveTargetTriple({ target: wanted, cwd: appRoot });
   // Warnings (a never-run row, a catalog row that is not staged) go to stderr; stdout stays the staged-file list or the --json document.
-  const result = await stageSidecars({ appRoot, manifest: config.sidecars, target, ...(split ? { cacheRoot: split.checkoutAppRoot } : {}), deps: { warn: (line) => console.error(line) } });
+  const result = await stageSidecars({ appRoot, manifest: config.sidecars, target, ifStale: opts.ifStale, ...(split ? { cacheRoot: split.checkoutAppRoot } : {}), deps: { warn: (line) => console.error(line) } });
   if (opts.json) console.log(JSON.stringify(result, null, 2));
   else {
     for (const file of result.files ?? []) console.log(`right-release stage-sidecar: staged ${typeof file === "string" ? file : file.path ?? JSON.stringify(file)}`);

package/stage-sidecar.mjs

@@ -1936,12 +1936,11 @@ export function planSidecarStaging({ manifest, target, env = process.env } = {})
  * fs (existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, renameSync, chmodSync, statSync, readdirSync, rmSync), run, fetch (https downloads of `remote`), fetchBytes, extractMember, loadMediaCatalog, loadNativeCatalog, makeTempDir, removeDir, now, pid, log (progress), warn (warnings; defaults to log), env.
  * The API is quiet by default; the `right-release stage-sidecar` command passes `warn` so the CLI prints warnings on stderr.
  */
-export async function stageSidecars({ appRoot, manifest, target, cacheRoot, deps = {} } = {}) {
+export async function stageSidecars({ appRoot, manifest, target, cacheRoot, ifStale = false, deps = {} } = {}) {
   if (typeof appRoot !== "string" || !path.isAbsolute(appRoot)) fail("STAGE_SIDECAR_CONFIG_INVALID", "appRoot must be an absolute path");
   if (cacheRoot !== undefined && (typeof cacheRoot !== "string" || !path.isAbsolute(cacheRoot))) fail("STAGE_SIDECAR_CONFIG_INVALID", "cacheRoot must be an absolute path");
   const env = deps.env ?? process.env;
   const plan = validateSidecarManifest(manifest, { target, mode: resolveBuildMode(env) });
-  assertNotNested(plan, env);
   // A source split (source-split.mjs; rightkit-gate's snapshot route): `appRoot` is the snapshot of the commit, where the declared
   // sources are read and where the staged files and the receipt go (the Tauri build script reads them there). `cacheRoot` is the
   // checkout's app directory, which keeps every cache, archive, slice and build tree right-release owns (`.right-release/...`) and
@@ -1969,6 +1968,14 @@ export async function stageSidecars({ appRoot, manifest, target, cacheRoot, deps
     makeTempDir: deps.makeTempDir ?? (() => nodeFs.mkdtempSync(path.join(os.tmpdir(), "rightkit-stage-"))),
     removeDir: deps.removeDir ?? ((dir) => nodeFs.rmSync(dir, { recursive: true, force: true })),
   };
+  // Already staged: when the receipt at the plan's receipt path is for this manifest and target and every file it names is on disk with its recorded sha256, nothing is built,
+  // downloaded, copied or written (the gate staged the package triple first, rightkit-gate stageSidecarsOnce, so a recipe's own prepare step changes nothing). Judged before the
+  // nested-broker refusal, which guards only a step that would build.
+  // Opt-in (`ifStale`, `stage-sidecar --if-stale`): only a Mac package recipe's own prepare step asks for it. The check is structural (no source hash), so every
+  // other caller, the gate's staging step included, builds as before.
+  const current = ifStale ? currentStageReceipt(plan, ctx) : null;
+  if (current) return { receipt: current, receiptPath: path.resolve(appRoot, plan.receiptPath), files: current.files, externalBinNames: current.files.filter((file) => file.externalBin).map((file) => file.name), unchanged: true };
+  assertNotNested(plan, env);
   await claimNativeOutputs(plan, ctx);
   const files = [];
   const skipped = [];
@@ -2009,6 +2016,40 @@ export async function stageSidecars({ appRoot, manifest, target, cacheRoot, deps
   return { receipt, receiptPath: receiptFile, files, externalBinNames: files.filter((file) => file.externalBin).map((file) => file.name) };
 }
 
+/**
+ * The receipt at the plan's receipt path when staging is already current, else null: a valid receipt of this target whose skipped rows are the plan's, that has a file of the
+ * same kind and name for every named row the plan stages, and whose every file is on disk, a regular file, with its recorded sha256 (and, for a plan that wipes its stage
+ * directory, nothing else in that directory). A receipt that cannot be read or does not match is not current; nothing is ever written.
+ */
+function currentStageReceipt(plan, ctx) {
+  const { fs, appRoot } = ctx;
+  try {
+    const receiptFile = path.resolve(appRoot, plan.receiptPath);
+    const receipt = validateStageSidecarReceipt(JSON.parse(fs.readFileSync(receiptFile, "utf8")), { target: plan.target.triple });
+    const planned = plan.entries.filter((entry) => !entry.skipped);
+    const skipped = plan.entries.filter((entry) => entry.skipped).map((entry) => ({ kind: entry.kind, index: entry.index, platforms: entry.platforms }));
+    if (JSON.stringify(skipped) !== JSON.stringify(receipt.skipped ?? [])) return null;
+    if (receipt.files.length < planned.length) return null;
+    for (const entry of planned) if (typeof entry.name === "string" && ["cargo-bin", "command", "cmake", "prebuilt", "remote"].includes(entry.kind) && !receipt.files.some((file) => file.kind === entry.kind && file.name === entry.name)) return null;
+    const named = new Set();
+    for (const file of receipt.files) {
+      const full = path.resolve(appRoot, file.path);
+      const meta = fs.statSync(full);
+      if (!meta.isFile() || sha256Of(fs.readFileSync(full)) !== file.sha256) return null;
+      named.add(full.toLowerCase());
+    }
+    if (plan.wipeStageDir) {
+      named.add(receiptFile.toLowerCase());
+      const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).every((item) => {
+        const full = path.join(dir, item.name);
+        return item.isDirectory() ? walk(full) : named.has(path.resolve(full).toLowerCase());
+      });
+      if (!walk(path.resolve(appRoot, plan.stageDir))) return null;
+    }
+    return receipt;
+  } catch { return null; }
+}
+
 /** Structural check of a staging receipt; `expected` may pin target and names. */
 export function validateStageSidecarReceipt(receipt, expected = {}) {
   const bad = (message) => fail("STAGE_SIDECAR_RECEIPT_INVALID", `stage sidecar receipt: ${message}`);