@rightkit/release 0.6.8 → 0.6.11

package/development-signing.mjs

@@ -1,4 +1,5 @@
 import { createHash, X509Certificate } from "node:crypto";
+import { nativeHelperEntitlementMap, nativeHelpersFromConfig } from "./native-helpers.mjs";
 import { closeSync, copyFileSync, existsSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -192,7 +193,9 @@ export function readDevSigningSettings(descriptor = {}, config = {}, { root, exi
   };
   const signMap = typeof sign.entitlements === "object" && sign.entitlements !== null && !Array.isArray(sign.entitlements) ? sign.entitlements : undefined;
   const entitlements = [...compileBundlePathMap(descriptor.entitlements, "install.entitlements", { reject: invalidConfig, value: plistPath }),
-    ...compileBundlePathMap(signMap, "sign.entitlements", { reject: invalidConfig, value: plistPath })];
+    ...compileBundlePathMap(signMap, "sign.entitlements", { reject: invalidConfig, value: plistPath }),
+    // Native helpers embedded in the dev .app carry their own entitlements, exactly as the release lane signs them.
+    ...compileBundlePathMap((() => { const h = nativeHelpersFromConfig(config); return h ? nativeHelperEntitlementMap(h) : undefined; })(), "macPackage.nativeHelpers", { reject: invalidConfig, value: plistPath })];
   if (descriptor.timestamp !== undefined && typeof descriptor.timestamp !== "boolean") invalidConfig("install.timestamp must be true or false");
   if (descriptor.assertTeamSignedNested !== undefined && typeof descriptor.assertTeamSignedNested !== "boolean") invalidConfig("install.assertTeamSignedNested must be true or false");
   const rawAssertions = descriptor.assert ?? [];

package/development.mjs

@@ -2,12 +2,14 @@ import { discoverBrokerSocket, resolveManagedRoots } from './managed-roots.mjs';
 import { spawnSync } from "./background-process.mjs";
 import { createHash } from "node:crypto";
 import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, lstatSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
+import { buildLaunch } from "./build-launch.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
+import { readSourceSplit } from "./source-split.mjs";
 import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
-import { acquireManagedRunLease, managedRuntimeClient, managedRuntimeCommand, runCargoSync } from "./managed-cargo.mjs";
+import { acquireManagedRunLease, directCargoEnv, directPlatform, managedRuntimeClient, managedRuntimeCommand, runCargoSync } from "./managed-cargo.mjs";
 import { BUNDLE_MARKERS, bundleMarkerBuffer, readTauriBundleMarkers } from "./tauri-bundle-marker.mjs";
 import { installPortableDevelopment } from "./portable-development.mjs";
 import { previousPathOf, stagingPathOf, swapInPlace } from "./in-place-install.mjs";
@@ -15,7 +17,10 @@ import { stageDevelopmentBinaries, validateStageEntries } from "./stage-binary.m
 import { assertStableDesignatedRequirement, readBundleExecutable, requestedCiAdhocSigning, signMacosDevelopmentBundle } from "./development-signing.mjs";
 import { macosCodesignEnvironment } from "./codesign-environment.mjs";
 import { installTauriDevId, resolveTauriDevIdDescriptor, TAURI_DEVID_KIND } from "./install-tauri-devid.mjs";
-import { assertIosDevelopmentSession, installIosDevelopment, prepareIosDevelopment, validateIosDevelopment } from "./ios-dev.mjs";
+import { ASSEMBLED_APP_KIND, installAssembledMac, installAssembledWindows, resolveAssembledInstall } from "./install-assembled-app.mjs";
+import { assertIosDevelopmentSession, installIosDevelopment, iosUiTestCommands, prepareIosDevelopment, prepareIosUiTests, validateIosDevelopment } from "./ios-dev.mjs";
+import { packLinuxArtifacts, validateLinuxArchive } from "./linux-artifacts.mjs";
+import { buildAndEmbedNativeHelpers, nativeHelpersFromConfig } from "./native-helpers.mjs";
 import { androidDevelopmentNdkCommand, androidDevelopmentSerial, installAndroidDevelopment, validateAndroidDevelopment } from "./android-dev.mjs";
 
 // One standard Cargo profile for every app (templates/cargo-profiles.toml): Cargo's built-in `dev`.
@@ -30,9 +35,9 @@ export function cargoProfileDirectory(profile) {
 }
 const RELEASE_ONLY_APPLE_ENV = ["APPLE_ID", "APPLE_PASSWORD", "APPLE_API_KEY", "APPLE_API_ISSUER", "APPLE_API_KEY_PATH", "APPLE_CERTIFICATE", "APPLE_CERTIFICATE_PASSWORD"];
 
-export function developmentEnvironment(env = process.env) {
+export function developmentEnvironment(env = process.env, platform = process.platform) {
   const result = {
-    ...env,
+    ...(directPlatform(platform) ? directCargoEnv(env, platform) : env),
     RIGHTKIT_BUILD_MODE: "dev",
     RIGHTKIT_CARGO_PROFILE: DEVELOPMENT_PROFILE,
     TAURI_SIGNING_PRIVATE_KEY: "",
@@ -79,22 +84,39 @@ export function validateDevelopmentConfig(config, platform, { root = process.cwd
     if (platform !== "mac") throw new Error(`the ${TAURI_DEVID_KIND} development installer is for --platform mac`);
     resolveTauriDevIdDescriptor(target.install, { appRoot: root });
     if (!target.install.targetTriple && !target.install.bundleDirectory) throw new Error(`development.targets.${platform}.install requires targetTriple (or bundleDirectory) to find the built .app`);
+  } else if (target.install?.kind === ASSEMBLED_APP_KIND) {
+    if (platform !== "mac" && platform !== "win") throw new Error(`the ${ASSEMBLED_APP_KIND} development installer is for --platform mac or win`);
+    // The assembly (assembly.<platform>) and the install keys are validated together, before any build.
+    resolveAssembledInstall({ config, platform });
   } else if (target.install?.kind === "adb") {
     if (platform !== "android") throw new Error("the adb development installer is for --platform android");
   } else if (target.install) throw new Error(`unsupported development installer kind: ${target.install.kind}`);
+  // Linux is build-only: its artifacts are the staged sidecars bound in the stage receipt; nothing is installed on a Linux host.
+  if (platform === "linux" && target.install) throw new Error("development.targets.linux is build-only: it takes no install (the staged artifacts are the result)");
+  if (target.archive !== undefined && platform !== "linux") throw new Error(`development.targets.${platform}.archive: only the linux target packs an archive`);
+  if (platform === "linux") validateLinuxArchive(target.archive);
   validateStageEntries(target.stage, `development.targets.${platform}.stage`);
   if (platform === "android") return { ...target, ...validateAndroidDevelopment(target, { root }) };
   return target;
 }
 
-export function runDevelopment({ root, platform, config, buildOnly = false, dryRun = false, env = process.env, run = spawnSync,
-  codesignEnvironment = macosCodesignEnvironment, serial }) {
-  if (!new Set(["win", "mac", "android", "ios"]).has(platform)) throw new Error("--platform must be win, mac, android or ios");
+export function runDevelopment({ root, platform, config, buildOnly = false, dryRun = false, env = process.env, run = spawnSync, door = buildLaunch,
+  codesignEnvironment = macosCodesignEnvironment, serial, uiTests = false }) {
+  // UI test journeys (`right-release test --platform ios`): the declared XCUITest journeys on the dev device, under the same guards.
+  if (uiTests && platform !== "ios") throw new Error("UI test journeys run for --platform ios only");
+  if (!new Set(["win", "mac", "linux", "android", "ios"]).has(platform)) throw new Error("--platform must be win, mac, linux, android or ios");
   // iOS: --dry-run validates the config and prints the plan on any host; everything else needs macOS with Xcode.
   if (!(platform === "ios" && dryRun)) assertNativeDevelopmentHost(platform);
   const target = validateDevelopmentConfig(config, platform, { root });
-  const repoRoot = git(root, ["rev-parse", "--show-toplevel"]);
+  // Inside the door's source split `root` is the snapshot of a commit (no git directory): the repository is the checkout the door
+  // ran in, whose primary-checkout rule and execution policy still apply, and the commit is the split's.
+  const split = readSourceSplit({ env, cwd: root });
+  const repoRoot = split ? split.checkout : git(root, ["rev-parse", "--show-toplevel"]);
   assertPrimaryReleaseCheckout(repoRoot, env);
+  if (dryRun && uiTests) {
+    if (!target.uiTests) throw new Error("development.targets.ios.uiTests is not declared: list the journeys in uiTests.onlyTesting");
+    return { built: false, installed: false, plan: { tests: iosUiTestCommands(target, { root, storage: { derivedData: "<rustright storage xcode-args -derivedDataPath>" }, destinationId: "<device or simulator id>", resultBundle: "<fresh .xcresult per run>" }) } };
+  }
   if (dryRun) return { built: false, installed: false, plan: { ...(target.ndk ? { ndk: androidDevelopmentNdkCommand(target.ndk) } : {}), build: target.build, install: buildOnly ? null : target.install ?? null, profile: DEVELOPMENT_PROFILE } };
   assertReleaseExecutionAllowed({ cwd: repoRoot, environment: env, command: `right-release dev --platform ${platform}` });
   // Refuse an invalid or off-CI ad hoc opt-in before the (long) build, not after it.
@@ -103,7 +125,8 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
   let iosPrepared = null;
   if (platform === "ios") {
     assertIosDevelopmentSession(target, { env, run });
-    iosPrepared = prepareIosDevelopment(target, { root, env, run, serial });
+    if (uiTests && !target.uiTests) throw new Error("development.targets.ios.uiTests is not declared: list the journeys in uiTests.onlyTesting");
+    iosPrepared = uiTests ? prepareIosUiTests(target, { root, env, run, serial }) : prepareIosDevelopment(target, { root, env, run, serial });
   }
   // Android: the device serial is required, so a missing one is refused before the (long) build too.
   if (!buildOnly && platform === "android" && target.install) androidDevelopmentSerial({ descriptor: target.install, serial, env });
@@ -114,34 +137,85 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
   try {
     const startedMs = Date.now();
     // Android: cargo-ndk (Cargo dev profile) fills the generated jniLibs, then the Gradle debug build packages it.
-    if (target.ndk) { rmSync(target.ndk.jniLibs, { recursive: true, force: true }); execute(androidDevelopmentNdkCommand(target.ndk), { root, env: childEnv, dryRun, run, label: "native build" }); }
-    for (const command of iosPrepared ? iosPrepared.build : target.build) execute(command, { root, env: childEnv, dryRun, run, label: "build" });
+    if (target.ndk) { rmSync(target.ndk.jniLibs, { recursive: true, force: true }); execute(androidDevelopmentNdkCommand(target.ndk), { root, env: childEnv, dryRun, run, door, label: "native build" }); }
+    if (uiTests) {
+      for (const command of iosPrepared.tests) execute(command, { root, env: childEnv, dryRun, run, door, label: "ui tests" });
+      console.log(`right-release test: ios journeys passed (${target.uiTests.onlyTesting.join(", ")}); result bundle ${iosPrepared.resultBundle}`);
+      return { built: true, installed: false, tested: true, resultBundle: iosPrepared.resultBundle };
+    }
+    for (const command of iosPrepared ? iosPrepared.build : target.build) execute(command, { root, env: childEnv, dryRun, run, door, label: "build" });
     // Dev and QA binaries run from one stable staged path, copied in place (no backup of the old copy), never from the
     // broker's per-generation target folder or a hashed dev-targets folder.
     const staged = target.stage?.length ? stageDevelopmentBinaries(target.stage, { root, platform: platform === "win" ? "win32" : process.platform }) : [];
     for (const file of staged) console.log(`right-release dev: staged ${file}`);
+    // Linux: the declared files become one tarball per architecture plus the digest manifest a guest link pins (rightkit#1230).
+    // Only from a clean checkout: an artifact others install must name the exact commit it was built from.
+    if (platform === "linux" && target.archive && !dryRun) {
+      // A split's snapshot is exactly its commit (the door verifies it at the start and end of the stage); the checkout may hold anything.
+      if (!split && git(repoRoot, ["status", "--porcelain", "--untracked-files=normal"])) throw new Error("linux artifacts are packed only from a clean checkout: commit first, so the manifest names the exact source");
+      let version;
+      try { version = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).version; } catch { version = undefined; }
+      packLinuxArtifacts({ root, archive: validateLinuxArchive(target.archive), app: target.archive.name, version, commit: split ? split.commit : git(repoRoot, ["rev-parse", "HEAD"]), run });
+    }
     if (buildOnly || !target.install) return { built: true, installed: false, ...(staged.length ? { staged } : {}) };
     if (iosPrepared) return { built: true, installed: true, ios: installIosDevelopment(iosPrepared.install, { root, env: childEnv, run }) };
     if (target.install.kind === TAURI_DEVID_KIND) {
       // installTauriDevId is async: the lease is held until it settles, so a broker cutover cannot land mid-install.
       const built = resolveTauriArtifact(target.install, { root, platform, env: childEnv });
+      // Dev = production + QA: the same native helpers the release embeds are built, embedded and signed into the dev .app too.
+      const helpers = platform === "mac" ? nativeHelpersFromConfig(config) : undefined;
+      if (helpers) {
+        let version;
+        try { version = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).version; } catch { version = undefined; }
+        buildAndEmbedNativeHelpers({ appRoot: root, app: built, helpers, version, forceArch: String(target.install.targetTriple).startsWith("x86_64") ? "x86_64" : "arm64", configuration: "debug", replaceExisting: true, env: childEnv });
+      }
       releaseLease = false;
       return installTauriDevId({ appRoot: root, config: target.install, releaseConfig: config, built, env: childEnv })
         .then((outcome) => ({ built: true, installed: true, ...(staged.length ? { staged } : {}), devid: outcome }))
         .finally(() => lease.release());
     }
-    const signing = install(target.install, { root, platform, config, env: childEnv, run, sinceMs: startedMs, serial });
+    if (target.install.kind === ASSEMBLED_APP_KIND) {
+      const { spec, descriptor } = resolveAssembledInstall({ config, platform });
+      if (platform === "win") {
+        const assembled = installAssembledWindows({ root, config, descriptor, spec, env: childEnv });
+        return { built: true, installed: true, ...(staged.length ? { staged } : {}), assembled };
+      }
+      // installAssembledMac is async: the lease is held until it settles, so a broker cutover cannot land mid-install.
+      releaseLease = false;
+      return installAssembledMac({ root, config, descriptor, spec, env: childEnv })
+        .then((outcome) => ({ built: true, installed: true, ...(staged.length ? { staged } : {}), assembled: outcome }))
+        .finally(() => lease.release());
+    }
+    const signing = install(target.install, { root, platform, config, env: childEnv, run, door, sinceMs: startedMs, serial });
     return { built: true, installed: true, ...(staged.length ? { staged } : {}), ...(platform === "mac" && target.install.kind === "tauri" ? { signing } : {}) };
   } finally { if (releaseLease) lease.release(); }
 }
 
-export function assertNativeDevelopmentHost(platform, host = process.platform) {
-  if ((platform === "win" && host !== "win32") || ((platform === "mac" || platform === "ios") && host !== "darwin")) throw new Error(`development target ${platform} requires its native host`);
+/** WSL reports `linux` as its platform under both generations; which one it is decides whether a Linux kernel runs at all. */
+export function isWsl({ env = process.env, readFile = (f) => readFileSync(f, "utf8") } = {}) {
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true;
+  try { return /microsoft|wsl/i.test(readFile("/proc/sys/kernel/osrelease")) || /microsoft|wsl/i.test(readFile("/proc/version")); } catch { return false; }
 }
 
-function install(descriptor, { root, platform, config, env, run, sinceMs = null, serial }) {
+/**
+ * WSL1 translates Linux system calls onto the Windows kernel (osrelease like `4.4.0-19041-Microsoft`), so it is not a Linux host.
+ * WSL2 runs a genuine Linux kernel in a Hyper-V utility VM (osrelease `…-microsoft-standard-WSL2`): a Linux VM, which is what
+ * native Linux builds need (rightkit#1230: "x86_64 on a Linux VM on the Dell"; Astra 2026-10-28). Unknown WSL counts as WSL1.
+ */
+export function isWsl1({ env = process.env, readFile = (f) => readFileSync(f, "utf8") } = {}) {
+  if (!isWsl({ env, readFile })) return false;
+  try { return !/microsoft-standard-WSL2|WSL2/i.test(readFile("/proc/sys/kernel/osrelease")); } catch { return true; }
+}
+
+export function assertNativeDevelopmentHost(platform, host = process.platform, { wsl1 = () => isWsl1() } = {}) {
+  // Linux builds run on a Linux kernel of the target's architecture (no cross-compiling); WSL1 has no Linux kernel.
+  if ((platform === "win" && host !== "win32") || ((platform === "mac" || platform === "ios") && host !== "darwin") || (platform === "linux" && host !== "linux")) throw new Error(`development target ${platform} requires its native host`);
+  if (platform === "linux" && wsl1()) throw new Error("development target linux requires a Linux kernel; this is WSL1 (Linux system calls translated onto the Windows kernel). Use WSL2 or a Linux VM");
+}
+
+function install(descriptor, { root, platform, config, env, run, door, sinceMs = null, serial }) {
   if (descriptor.kind === "adb") return installAndroidDevelopment(descriptor, { root, env, run, serial });
-  if (descriptor.kind === "command") return execute(descriptor, { root, env, run, label: "install" });
+  if (descriptor.kind === "command") return execute(descriptor, { root, env, run, door, label: "install" });
   if (descriptor.kind === "portable") return installPortableDevelopment(descriptor, { root, platform: platform === "win" ? "win32" : "darwin", env });
   if (platform === "win") {
     if (!descriptor.expectedInstalledPath) throw new Error("Windows Tauri installer requires expectedInstalledPath for installed verification");
@@ -286,20 +360,45 @@ function resolveBundleRoot(descriptor, { root, env, runCargo }) {
 
 function platformBundleKind(descriptor) { return descriptor.targetTriple.includes("apple") ? "macos" : "nsis"; }
 function validateCommand(command, label) { if (!command || typeof command.cmd !== "string" || !command.cmd.trim() || (command.args !== undefined && !Array.isArray(command.args))) throw new Error(`${label} must declare cmd and args`); }
-function execute(command, { root, env, dryRun, run, label }) {
+function execute(command, { root, env, dryRun, run, label, door = null }) {
   validateCommand(command, `development ${label}`);
   const cwd = path.resolve(root, command.cwd ?? ".");
   if (!inside(root, cwd)) throw new Error(`development ${label} cwd must stay inside app root`);
   const args = (command.args ?? []).map(String);
   if (dryRun) return { cmd: command.cmd, args, cwd };
-  const launch = resolveCommand(command.cmd, args, { root, env });
+  // A pnpm step through the door is the broker's rightkit-pnpm job (or plain pnpm on a direct host), launched by name: the door never uses
+  // the node entry resolveCommand would find, so resolving pnpm's JavaScript CLI here would only fail a host that does not need it.
+  // The door's own `pnpm exec right-release` forms still resolve to this package's right-release.
+  const ownReleaseStep = (args[0] === "exec" && args[1] === "right-release") || args[0] === "right-release";
+  const resolved = door && command.cmd === "pnpm" && !ownReleaseStep ? { command: "pnpm", args } : resolveCommand(command.cmd, args, { root, env });
+  // Every dev build step goes through the one door (build-launch.mjs): the door's own right-release stays in process order, a pnpm step
+  // is the rightkit-pnpm broker job (by its own name, not the node entry resolveCommand finds), anything else as resolved.
+  // A configured command can run code regardless of its label, so installation commands use the door too.
+  const own = resolved.command === process.execPath && resolved.args[0] === OWN_RIGHT_RELEASE;
+  const launch = own || !door ? resolved : { ...resolved, ...door(command.cmd === "pnpm" ? "pnpm" : resolved.command, command.cmd === "pnpm" ? args : resolved.args, { env: resolved.env ?? env, cwd, exists: existsSync }) };
   const result = run(launch.command, launch.args, { cwd, env: launch.env ?? env, stdio: "inherit", windowsHide: true, shell: false, timeout: command.timeoutMs });
   if (result.status !== 0) throw new Error(`development ${label} command failed (${result.status}): ${command.name ?? command.cmd}`);
 }
-export function resolveCommand(command, args, { root, env = process.env } = {}) {
+/** This package's own right-release entry: the door's RightKit, whatever the app's node_modules holds. */
+const OWN_RIGHT_RELEASE = fileURLToPath(new URL("./cli/right-release.mjs", import.meta.url));
+/** `rustright <tool>` forms that map to the real toolchain on a direct (Linux) host. */
+const DIRECT_TOOLS = new Set(["cargo", "rustc", "rustdoc"]);
+export function resolveCommand(command, args, { root, env = process.env, platform = process.platform } = {}) {
   if (command === "node") return { command: process.execPath, args };
+  // A dev target's `right-release …` step runs the door's own right-release (this package), never the app's node_modules copy:
+  // `pnpm exec right-release` puts the app's bin first on PATH, so PATH order cannot decide it (HeardRight on the Dell, 2026-10-27:
+  // the app's older guard refused what the door had admitted). `pnpm exec right-release …` and `pnpm right-release …` are the same step.
+  if (command === "right-release") return { command: process.execPath, args: [OWN_RIGHT_RELEASE, ...args] };
+  if (command === "pnpm" && ((args[0] === "exec" && args[1] === "right-release") || args[0] === "right-release")) {
+    return { command: process.execPath, args: [OWN_RIGHT_RELEASE, ...args.slice(args[0] === "exec" ? 2 : 1)] };
+  }
   if (command === "pnpm") return { command: process.execPath, args: [resolvePnpmCli({ root, env }), ...args] };
   if (command === "rightkit") throw new Error("`rightkit` is the retired name of the RustRight client (rustright#91); use rustright (cmd: \"rustright\")");
+  // A direct (Linux) host has no broker: `rustright cargo <args>` runs the real cargo, RustRight shims off PATH (managed-cargo directPlatform).
+  if (command === "rustright" && directPlatform(platform)) {
+    if (!DIRECT_TOOLS.has(args[0])) throw new Error(`\`rustright ${args[0] ?? ""}\` has no direct form on this ${platform} host (no broker on Linux); only \`rustright cargo|rustc|rustdoc\` map to the toolchain`);
+    return { command: args[0], args: args.slice(1), env: directCargoEnv(env, platform) };
+  }
   if (command === "rustright") {
     const client = managedRuntimeClient(env);
     if (!client) throw new Error("installed RightKit runtime client is unavailable for development command");
@@ -351,7 +450,7 @@ function inside(root, child) { const rel = path.relative(path.resolve(root), pat
 export async function main(args = process.argv.slice(2)) {
   let platform, configPath = defaultReleaseConfigFile(), dryRun = false, buildOnly = false, serial;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "-h" || args[i] === "--help") { console.log("usage: right-release dev --platform win|mac|android|ios [--config right-release.config.json] [--dry-run] [--build-only] [--serial <adb serial | iOS device id>]"); return; }
+    if (args[i] === "-h" || args[i] === "--help") { console.log("usage: right-release dev --platform win|mac|linux|android|ios [--config right-release.config.json] [--dry-run] [--build-only] [--serial <adb serial | iOS device id>]"); return; }
     if (args[i] === "--platform") platform = args[++i];
     else if (args[i] === "--config") configPath = args[++i];
     else if (args[i] === "--dry-run") dryRun = true;
@@ -359,7 +458,7 @@ export async function main(args = process.argv.slice(2)) {
     else if (args[i] === "--serial") serial = args[++i];
     else throw new Error(`unknown dev option: ${args[i]}`);
   }
-  if (!platform) throw new Error("right-release dev requires --platform win|mac|android|ios");
+  if (!platform) throw new Error("right-release dev requires --platform win|mac|linux|android|ios");
   const absoluteConfig = path.resolve(configPath);
   const safeEnv = developmentEnvironment(process.env);
   for (const [key, value] of Object.entries(safeEnv)) process.env[key] = value;

package/direct-receipt.mjs

@@ -0,0 +1,135 @@
+// The direct (Linux) host's evidence for a snapshot compile (item 7 rows 7.09, 7.12, 7.18; GATE-CONTRACT "Broker interface"):
+//   - the output directory, resolved in the PRIMARY CHECKOUT with the stage's environment before the source location changes, with
+//     its inputs recorded (7.09);
+//   - the receipt the gate writes itself, "the same field names minus the broker-only ones (admission, queue, reusedFrom)" (7.18),
+//     and the consumer-side matrix that refuses a receipt that lacks one, carries a broker-only one, or holds no census (7.22 Linux half).
+// Pure functions with injected spawn and file system: the gate (bin/rightkit-gate.mjs) wires them to the host.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { validateFreshness } from "./freshness-census.mjs";
+
+export const DIRECT_RECEIPT_SCHEMA = "rightkit.gate-direct-receipt/1";
+export const DIAGNOSTICS_SCHEMA = "rightkit.gate-direct-diagnostics/1";
+/** The names GATE-CONTRACT lists as broker-only: a direct receipt never carries them. */
+export const BROKER_ONLY_FIELDS = Object.freeze(["admission", "queue", "reusedFrom"]);
+/** The contract's returned-evidence names a direct receipt carries (7.18). `snapshot.path|treeAtStart|treeAtExit` are checked inside `snapshot`. */
+export const DIRECT_RECEIPT_REQUIRED = Object.freeze(["requestId", "brokerVersion", "executor", "commit", "snapshot", "declaredInputDigests", "verdict", "freshness", "timingsMs", "exit", "diagnosticsPath", "outputDir", "refreshed"]);
+export const TIMING_FIELDS = Object.freeze(["bind", "cargo", "afterExitBind", "diagnostics"]);
+/** The environment a `cargo metadata` target resolution reads: recorded by value (the rest of the environment by digest only). */
+export const TARGET_ENV_NAMES = Object.freeze(["CARGO_TARGET_DIR", "CARGO_BUILD_TARGET_DIR", "CARGO_HOME", "RUSTUP_TOOLCHAIN"]);
+
+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(" | ");
+
+/** True when `child` is `parent` or below it (lexically, after resolving both). */
+export function isWithin(parent, child) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+
+/** The stage environment a resolution ran with: the target-relevant names by value, the whole environment by digest. */
+export function envInputs(env) {
+  const record = {};
+  for (const name of TARGET_ENV_NAMES) record[name] = typeof env?.[name] === "string" ? env[name] : null;
+  const all = Object.keys(env ?? {}).sort().map((k) => `${k}=${env[k]}`).join("\n");
+  return { ...record, digest: createHash("sha256").update(all).digest("hex") };
+}
+
+/**
+ * The absolute output directory Cargo would use for one workspace, resolved where the contract says: `cargo metadata --format-version 1
+ * --no-deps` run with its working directory in the PRIMARY CHECKOUT (never the snapshot) and with the stage's environment, so
+ * `CARGO_TARGET_DIR`, `.cargo/config.toml` `build.target-dir` (relative to the checkout's config, or absolute) and the default `target/`
+ * all resolve as they do for a developer's own build. Returns `{ dir, inputs }` (the inputs are recorded in the receipt) or throws an
+ * `RK_TARGET_RESOLUTION` error whose message names why: a resolution made in the snapshot, no absolute directory, or a directory that
+ * lies inside the snapshot (a second output directory).
+ */
+export function resolveTargetDirectory({ spawn, cargoCommand, manifest, env, checkoutRoot, snapshotRoot = null, workspace = "." }) {
+  const fail = (message) => Object.assign(new Error(message), { code: "RK_TARGET_RESOLUTION" });
+  const cwd = path.dirname(manifest);
+  if (!isWithin(checkoutRoot, cwd)) throw fail(`the output directory of workspace ${workspace} must be resolved in the primary checkout ${checkoutRoot}, not in ${cwd}`);
+  if (snapshotRoot && isWithin(snapshotRoot, cwd)) throw fail(`the output directory of workspace ${workspace} must be resolved before the source location changes, not in the snapshot ${snapshotRoot}`);
+  const args = [...cargoCommand.slice(1), "metadata", "--offline", "--format-version", "1", "--no-deps", "--manifest-path", manifest];
+  const r = spawn(cargoCommand[0], args, { cwd, env });
+  let dir = null;
+  try { dir = failed(r) ? null : JSON.parse(String(r.stdout ?? "")).target_directory; } catch { dir = null; }
+  if (typeof dir !== "string" || !path.isAbsolute(dir)) throw fail(`cargo metadata in the checkout reported no absolute target_directory for ${workspace}${failed(r) ? ` (${why(r)})` : ""}`);
+  const resolved = path.resolve(dir);
+  if (snapshotRoot && isWithin(snapshotRoot, resolved)) throw fail(`the output directory of workspace ${workspace} resolves to ${resolved}, inside the snapshot ${snapshotRoot}; a snapshot compile writes only to the checkout's directory, never a second one under the commit`);
+  return { dir: resolved, inputs: { cwd, manifest, command: [cargoCommand[0], ...args], env: envInputs(env), targetDirectory: resolved } };
+}
+
+/** The Class A and B result the receipt's `verdict` carries (a direct compile reuses nothing, so no `reusedFrom`). */
+export function directVerdict({ scans = [], failures = [], deferrals = [] } = {}) {
+  const byClass = (c) => { const rows = scans.filter((s) => s.class === c); return { scans: rows.length, failed: rows.filter((s) => s.status === "fail").length }; };
+  return { result: failures.length ? "FAILED" : "PASSED", classA: byClass("A"), classB: byClass("B"), deferred: deferrals.length };
+}
+
+/** Writes the structured diagnostics of one direct compile and returns the file's absolute path (the receipt's `diagnosticsPath`). */
+export function writeDirectDiagnostics({ dir, requestId, commit, exit, scans = [], failures = [], deferrals = [], notes = [], freshness = null, writeFile = fs.writeFileSync, mkdir = fs.mkdirSync }) {
+  mkdir(dir, { recursive: true });
+  const file = path.resolve(dir, `direct-diagnostics-${requestId}.json`);
+  const rows = scans.map((s) => ({ id: s.id, class: s.class ?? null, status: s.status, ...(s.code ? { code: s.code } : {}), ...(s.detail ? { detail: String(s.detail).slice(0, 1000) } : {}) }));
+  writeFile(file, `${JSON.stringify({ schema: DIAGNOSTICS_SCHEMA, requestId, commit, exit, scans: rows, failures, deferrals, notes, freshness }, null, 2)}\n`);
+  return file;
+}
+
+/** The receipt of one direct compile: the contract's returned-evidence names, no broker-only one. Throws nothing; `verifyDirectReceipt` judges it. */
+export function buildDirectReceipt({ requestId, issuedAt, commit, snapshotPath, treeAtStart, treeAtExit, ownershipHandle = null, declaredInputDigests = [], verdict, freshness, timingsMs, exit, diagnosticsPath, outputDirs = {}, outputResolution = {}, cargoWrapper = null }) {
+  const dirs = [...new Set(Object.values(outputDirs))];
+  return {
+    schema: DIRECT_RECEIPT_SCHEMA, requestId, brokerVersion: null, executor: "direct", issuedAt,
+    commit: { sha: commit.sha, tree: commit.tree },
+    snapshot: { path: snapshotPath, treeAtStart, treeAtExit },
+    declaredInputDigests, ownership: { handle: ownershipHandle },
+    verdict, freshness, timingsMs, exit, exitStatus: exit, diagnosticsPath,
+    outputDir: dirs.length === 1 ? dirs[0] : null, outputDirs: { ...outputDirs }, outputResolution,
+    refreshed: [], cargoWrapper,
+  };
+}
+
+/**
+ * The consumer's matrix over a direct receipt (the Linux half of row 7.22): every contract name present with the right type, the
+ * snapshot bound to the commit's tree at start and exit, a well formed freshness census, and none of the broker-only names.
+ * Returns the list of problems; an empty list means the receipt verifies.
+ */
+export function verifyDirectReceipt(receipt) {
+  const problems = [];
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) return ["the receipt is not an object"];
+  if (receipt.schema !== DIRECT_RECEIPT_SCHEMA) problems.push(`schema is ${JSON.stringify(receipt.schema)}, not ${DIRECT_RECEIPT_SCHEMA}`);
+  for (const name of DIRECT_RECEIPT_REQUIRED) if (!Object.hasOwn(receipt, name)) problems.push(`${name} is absent`);
+  for (const name of BROKER_ONLY_FIELDS) if (Object.hasOwn(receipt, name)) problems.push(`${name} is a broker-only field; a direct receipt never carries it`);
+  const text = (v) => typeof v === "string" && v !== "";
+  if (Object.hasOwn(receipt, "requestId") && !text(receipt.requestId)) problems.push("requestId is not a string");
+  if (Object.hasOwn(receipt, "brokerVersion") && receipt.brokerVersion !== null) problems.push("brokerVersion is not null on a direct host");
+  if (Object.hasOwn(receipt, "executor") && receipt.executor !== "direct") problems.push(`executor is ${JSON.stringify(receipt.executor)}, not "direct"`);
+  const commit = receipt.commit;
+  if (Object.hasOwn(receipt, "commit") && !(commit && text(commit.sha) && text(commit.tree))) problems.push("commit has no sha and tree");
+  const snap = receipt.snapshot;
+  if (Object.hasOwn(receipt, "snapshot")) {
+    if (!(snap && text(snap.path) && text(snap.treeAtStart) && text(snap.treeAtExit))) problems.push("snapshot has no path, treeAtStart and treeAtExit");
+    else if (commit && text(commit.tree) && (snap.treeAtStart !== commit.tree || snap.treeAtExit !== commit.tree)) problems.push("snapshot.treeAtStart and treeAtExit are not the commit's tree");
+  }
+  if (Object.hasOwn(receipt, "declaredInputDigests") && !Array.isArray(receipt.declaredInputDigests)) problems.push("declaredInputDigests is not a list");
+  const verdict = receipt.verdict;
+  if (Object.hasOwn(receipt, "verdict") && !(verdict && (verdict.result === "PASSED" || verdict.result === "FAILED"))) problems.push("verdict has no PASSED or FAILED result");
+  if (Object.hasOwn(receipt, "freshness")) for (const p of validateFreshness(receipt.freshness)) problems.push(p);
+  const timings = receipt.timingsMs;
+  if (Object.hasOwn(receipt, "timingsMs")) {
+    if (!timings || typeof timings !== "object") problems.push("timingsMs is not an object");
+    else {
+      for (const name of TIMING_FIELDS) if (!(Number.isFinite(timings[name]) && timings[name] >= 0)) problems.push(`timingsMs.${name} is not a duration`);
+      for (const name of BROKER_ONLY_FIELDS) if (Object.hasOwn(timings, name)) problems.push(`timingsMs.${name} is a broker-only field`);
+    }
+  }
+  if (Object.hasOwn(receipt, "exit") && !Number.isInteger(receipt.exit)) problems.push("exit is not an exit status");
+  if (Object.hasOwn(receipt, "diagnosticsPath") && !(text(receipt.diagnosticsPath) && path.isAbsolute(receipt.diagnosticsPath))) problems.push("diagnosticsPath is not an absolute path");
+  if (Object.hasOwn(receipt, "outputDir")) {
+    const dirs = receipt.outputDirs && typeof receipt.outputDirs === "object" ? Object.values(receipt.outputDirs) : [];
+    if (text(receipt.outputDir)) { if (!path.isAbsolute(receipt.outputDir)) problems.push("outputDir is not absolute"); }
+    else if (!(receipt.outputDir === null && new Set(dirs).size !== 1)) problems.push("outputDir is not the resolved absolute path (null only when the commit has no Cargo workspace, or several workspaces name several directories)");
+    for (const d of dirs) if (!(text(d) && path.isAbsolute(d))) problems.push(`outputDirs holds ${JSON.stringify(d)}, not an absolute path`);
+  }
+  if (Object.hasOwn(receipt, "refreshed") && !Array.isArray(receipt.refreshed)) problems.push("refreshed is not a list");
+  return problems;
+}

package/door-policy.mjs

@@ -17,7 +17,25 @@ const WRAPPERS = new Set(["env", "command", "exec", "time", "nice", "nohup", "su
 // Shell reserved words and grouping that can precede a command in the same simple command (`if true; then cargo build; fi`,
 // `{ cargo build; }`, `f() { cargo build; }`, `! cargo test`): they are skipped, never taken for the command.
 const KEYWORDS = new Set(["if", "then", "elif", "else", "fi", "do", "done", "while", "until", "{", "}", "!", "function"]);
-const DOOR_TOOLS = new Set(["cargo", "tauri", "right-release"]);
+// Adrian, 2026-10-26: every native and frontend build tool an app can be built with, not only cargo. xcodebuild's actions, swift's
+// compiling subcommands, Gradle tasks, the frontend bundlers, and a package script whose name says it builds.
+const XCODE_ACTIONS = new Set(["build", "archive", "test", "build-for-testing", "test-without-building", "analyze", "install", "installsrc", "clean"]);
+const XCODE_READONLY = new Set(["-version", "-list", "-showsdks", "-showBuildSettings", "-showdestinations", "-showTestPlans", "-help", "-usage", "-checkFirstLaunchStatus", "-exportLocalizations"]);
+const SWIFT_COMPILES = new Set(["build", "test", "run"]);
+const GRADLE_READONLY = new Set(["--version", "-v", "-version", "--help", "-h", "-?", "help", "tasks", "dependencies", "projects", "properties", "--stop", "--status"]);
+const FRONTEND_BUNDLERS = new Set(["webpack", "rollup", "esbuild", "tsup", "parcel"]);
+// A package script whose name says it builds (`pnpm build`, `pnpm run build:mac`, `npm run tauri`): the apps have no scripts, and a
+// script that builds would be a second door even if they did.
+const SCRIPT_BUILDS = /^(build|bundle|package|dist|compile|release|tauri|android|ios|xcode|gradle|test|tests|e2e|qa)(:|$)/;
+// Tools whose own options take a value, so the word after them is not the subcommand.
+const XCRUN_VALUE_OPTIONS = new Set(["--sdk", "-sdk", "--toolchain", "-toolchain", "--log", "-f", "--find", "--run"]);
+const SWIFT_VALUE_OPTIONS = new Set(["--package-path", "-c", "--configuration", "--build-path", "--scratch-path", "--cache-path", "--sdk", "--toolchain", "-Xswiftc", "-Xcc", "-Xlinker", "--triple", "--arch", "-j", "--jobs"]);
+const GRADLE_VALUE_OPTIONS = new Set(["-p", "--project-dir", "-b", "--build-file", "-c", "--settings-file", "-g", "--gradle-user-home", "-I", "--init-script", "--max-workers", "--console", "-x", "--exclude-task", "--project-cache-dir"]);
+const VITE_VALUE_OPTIONS = new Set(["--config", "-c", "--mode", "-m", "--base", "--logLevel", "-l", "--outDir", "--target", "--assetsDir", "--filter"]);
+/** The non-option words of argv, skipping the value of each option named in `valued` (`--config x`, and `--config=x` as one word). */
+const wordsOf = (argv, valued) => { const out = []; for (let i = 0; i < argv.length; i++) { const w = argv[i]; if (w.startsWith("-")) { if (valued.has(w)) i++; continue; } out.push(w); } return out; };
+const firstWord = (argv, valued) => wordsOf(argv, valued)[0] ?? null;
+const DOOR_TOOLS = new Set(["cargo", "tauri", "right-release", "xcodebuild", "swift", "swiftc", "gradle", "gradlew", "vite", ...FRONTEND_BUNDLERS]);
 
 /** Splits a shell command into simple commands (on ; && || | and newlines), each an argv of words. Quotes are respected. */
 export function simpleCommands(command) {
@@ -98,7 +116,8 @@ function argvViolation(argv, depth = 0, stdin = null) {
   let tool = base(a[0]);
   // A command string handed to another shell (`bash -c "cargo build"`, `eval "..."`) is judged as the command it is.
   if (depth < 4 && (SHELLS.has(tool.toLowerCase()) || tool === "eval")) {
-    const flag = a.findIndex((w, i) => i > 0 && /^(-c|\/c|-Command|-command)$/.test(w));
+    // `-c`, and combined short flags that carry it (`-lc`, `-xec`); pwsh `-Command`; cmd `/c`.
+    const flag = a.findIndex((w, i) => i > 0 && /^(-[a-zA-Z]*c[a-zA-Z]*|\/c|-Command|-command)$/.test(w));
     const script = tool === "eval" ? a.slice(1).join(" ") : flag > 0 ? a.slice(flag + 1).join(" ") : null;
     return script ? doorViolation(script, depth + 1) : null;
   }
@@ -115,12 +134,47 @@ function argvViolation(argv, depth = 0, stdin = null) {
   if (RUNNERS.has(tool)) {
     let rest = a.slice(1).filter((w, i, all) => !(w.startsWith("-") || (i > 0 && ["--filter", "-F", "--dir", "-C", "--prefix"].includes(all[i - 1]))));
     if (["exec", "dlx", "x"].includes(rest[0])) rest = rest.slice(1);
-    if (rest[0] === "run" || rest[0] === "run-script") return null; // the apps have no scripts; a script name is not a tool
+    const script = rest[0] === "run" || rest[0] === "run-script";
+    if (script) rest = rest.slice(1);
     if (!rest.length) return null;
-    a = rest; tool = base(a[0]);
+    // A script whose name says it builds is denied as the runner's script (`pnpm build`, `npm run tauri`); any other script name is
+    // not a tool (the apps have none). Without `run`, the word is judged as the tool it names (`pnpm tauri build`, `pnpm exec vite build`).
+    if (!script && DOOR_TOOLS.has(base(rest[0]))) { a = rest; tool = base(a[0]); }
+    else if (SCRIPT_BUILDS.test(rest[0])) return `${tool} ${rest[0]}`;
+    else if (script) return null;
+    else { a = rest; tool = base(a[0]); }
   }
+  // `rightkit-gate clippy [<cargo clippy args>]` is the agent entry for Clippy (GATE-CONTRACT §1 "Clippy route & batching", item 8 row
+  // 8.14): like every `rightkit-gate` subcommand it is the door, taken through the pinned gate (build-control-policy agentDoorViolation
+  // denies an unpinned copy as untrusted-gate) and run in the same order for a human and an agent. Direct `cargo clippy` and
+  // `cargo +<toolchain> clippy` stay denied by CARGO_COMPILES above, with the route named in the denial.
   if (tool === "rightkit-gate" || tool === "rustright") return null;
   if (tool === "tauri" && TAURI_BUILDS.has(a[1])) return `tauri ${a[1]}`;
+  // Apple: xcrun wraps the tool it names; xcodebuild builds by default (no action word is `build`); swift build|test|run and swiftc compile.
+  if (tool === "xcrun" && a.length > 1) {
+    // xcrun's own options come first (`--sdk iphoneos`, `--toolchain x`, `-f`); the tool it runs is the first word after them.
+    let rest = a.slice(1);
+    while (rest.length && rest[0].startsWith("-")) rest = XCRUN_VALUE_OPTIONS.has(rest[0]) ? rest.slice(2) : rest.slice(1);
+    return rest.length ? argvViolation(rest, depth + 1, stdin) : null;
+  }
+  if (tool === "xcodebuild") {
+    const words = a.slice(1);
+    const action = words.find((w) => XCODE_ACTIONS.has(w));
+    if (action) return `xcodebuild ${action}`;
+    return words.some((w) => XCODE_READONLY.has(w)) ? null : "xcodebuild build";
+  }
+  if (tool === "swift") { const sub = firstWord(a.slice(1), SWIFT_VALUE_OPTIONS); if (sub && SWIFT_COMPILES.has(sub)) return `swift ${sub}`; }
+  if (tool === "swiftc") return "swiftc";
+  // Android: a Gradle task that is not one of the read-only reports.
+  if (tool === "gradle" || tool === "gradlew") {
+    // Every task named counts (`gradle tasks assembleRelease` builds); a bare call prints help.
+    const tasks = wordsOf(a.slice(1), GRADLE_VALUE_OPTIONS);
+    const building = tasks.find((t) => !GRADLE_READONLY.has(t));
+    return building ? `gradle ${building}` : null;
+  }
+  // Frontend: a production bundle is the compile stage's frontend build.
+  if (tool === "vite" && wordsOf(a.slice(1), VITE_VALUE_OPTIONS).includes("build")) return "vite build";
+  if (FRONTEND_BUNDLERS.has(tool)) return tool;
   if (tool === "cargo") {
     let sub = null;
     for (let i = 1; i < a.length; i++) {
@@ -212,10 +266,21 @@ export function doorViolation(command, depth = 0) {
   return null;
 }
 
+/** The agent entry for Clippy; a direct `cargo clippy` is denied in its favour. */
+export const CLIPPY_ROUTE = "rightkit-gate clippy [<cargo clippy args>]";
+
 export function doorDenial(violation) {
+  if (violation === "cargo clippy") {
+    return `[HOOK:one-door:block]\nWhy: \`${violation}\` builds outside the one door. Every check, compile, test, package and release goes through rightkit-gate, class A first.\nRequired: ${CLIPPY_ROUTE} (Clippy on HEAD's commit, class A first).`;
+  }
+  const mobile = /^(cargo )?tauri (android|ios)$|^xcodebuild (archive|install)|^gradle (assemble|bundle|build|publish|install)/.test(violation) ? (/ios|xcodebuild/.test(violation) ? "ios" : "android") : null;
   const stage = /^right-release (dev|test)$/.test(violation) ? violation.slice("right-release ".length) : /^(cargo )?tauri dev$/.test(violation) ? "dev"
-    : /^right-release (upload|publish|publish-update|github)$/.test(violation) ? "release" : /^right-release qa$/.test(violation) ? "qualify" : /^right-release /.test(violation) || /^(cargo )?tauri (build|bundle|android|ios)$/.test(violation) ? "package" : "compile";
-  return `[HOOK:one-door:block]\nWhy: \`${violation}\` builds outside the one door. Every check, compile, test, package and release goes through rightkit-gate, class A first.\nRequired: rightkit-gate --to ${stage}${stage === "package" || stage === "qualify" || stage === "release" ? " --platform mac|win" : ""}${stage === "dev" || stage === "test" ? " -- <arguments>" : ""}${stage === "release" ? " --tier patch|update" : ""} (on a machine with the RustRight broker, \`rustright cargo ...\` is also admitted: the broker runs class A first).`;
+    : /^right-release (upload|publish|publish-update|github)$/.test(violation) ? "release" : /^right-release qa$/.test(violation) ? "qualify"
+    : /^right-release /.test(violation) || /^(cargo )?tauri (build|bundle|android|ios)$/.test(violation) || /^xcodebuild (archive|install)/.test(violation) || /^gradle /.test(violation) ? "package"
+    : "compile";
+  const platform = mobile ?? "mac|win";
+  const tail = stage === "package" || stage === "qualify" ? ` --platform ${platform}` : stage === "release" ? ` --platform ${platform}${mobile ? "" : " --tier patch|update"}` : stage === "dev" || stage === "test" ? " -- <arguments>" : "";
+  return `[HOOK:one-door:block]\nWhy: \`${violation}\` builds outside the one door. Every check, compile, test, package and release goes through rightkit-gate, class A first.\nRequired: rightkit-gate --to ${stage}${tail} (or rustright cargo ... on a broker host, which runs class A first).`;
 }
 
 /** Claude Code PreToolUse decision for one hook input. */

package/door.mjs

@@ -2,16 +2,16 @@
 // packager) that right-release runs inside a stage. The step proceeds only when a live `rightkit-gate --to` run for HEAD launched it,
 // the same check right-release makes for itself (gate-stages.mjs requireDoorRun), so `node scripts/release/<step>.mjs` run by hand is
 // refused instead of becoming a side door around class A.
-import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { requireDoorRun } from "./gate-stages.mjs";
+import { doorContextFor } from "./source-split.mjs";
 
-/** null when a live door run for HEAD launched this process, else the refusal message. */
+/** null when a live door run for HEAD (or, inside a source split, for the split's commit) launched this process, else the refusal message. */
 export function doorRefusal({ cwd = process.cwd(), env = process.env, command = "this build step", run = spawnSync, alive } = {}) {
-  const git = (args) => { const r = run("git", args, { cwd, encoding: "utf8" }); return r.status === 0 ? String(r.stdout).trim() : ""; };
-  const common = git(["rev-parse", "--git-common-dir"]);
-  if (!common) return `${command} runs only in a git checkout, through the one door: rightkit-gate --to <stage>`;
-  return requireDoorRun({ env, commonDir: path.resolve(cwd, common), commit: git(["rev-parse", "HEAD"]), command, ...(alive ? { alive } : {}) });
+  let context;
+  try { context = doorContextFor({ cwd, env, run }); } catch (error) { return `${command}: ${error.code ?? "RK_SOURCE_SPLIT"}: ${error.message}`; }
+  if (!context) return `${command} runs only in a git checkout, through the one door: rightkit-gate --to <stage>`;
+  return requireDoorRun({ env, commonDir: context.commonDir, commit: context.commit, command, ...(alive ? { alive } : {}) });
 }
 
 /** Exits 2 with the refusal unless a live door run launched this process. */