@rightkit/release 0.6.16 → 0.6.20

package/qa-layout.mjs

@@ -0,0 +1,229 @@
+// Source QA against the gate-built QA shell, in the layout an install has (rightkit#1309 gap 2).
+//
+// A TOML-scenario launch of a Tauri app with a sidecar needs the test-mode engine and `resources/` BESIDE the UI binary, and the snapshot a package
+// stage reads holds no Cargo target (and may not be written: the snapshot is exactly the commit's tree, GATE-CONTRACT §1). So `right-release qa --stage
+// source` does not look for a binary in the source. The gate hands it the output directories its own compile recorded (RIGHT_RELEASE_QA_COMPILED_DIRS,
+// set only after the recorded compile still proved intact), and this module builds a RUN-SCOPED directory, never inside the snapshot:
+//
+//   <run dir>/app/                          the overlay app root: every top-level entry of the snapshot's app root as a symlink (read-only view), the
+//                                           qa config as a real COPY at the same relative path (its `app_root` resolves to the overlay, so the runner's
+//                                           own writes, `.rightkit-qa-bin` included, land here), `.rightkit-qa-bin/<triple|host>/<bin>` the QA shell
+//   <run dir>/app/.rightkit-qa-bin/<triple|host>/   the layout beside the shell: the sidecars and trees the app declared
+//
+// and the runner is pointed at the staged shell with RIGHTKIT_QA_APP_BINARY (already inside the stash, so it is launched as is, never copied again).
+// The shell is the newest `[<triple>/]<debug|dev|release-iterate>/<bin>` in the compile outputs that carries the QA control marker; a `release` profile
+// directory is never read. The layout is declared by the app in its release config:
+//
+//   qa.layout = {
+//     binary: "heardright_next_bin",                              // cargo bin target of the QA shell
+//     build: ["qa-build-shell", "qa-build-engine", "qa-sign"],    // tests.suites that build (and sign) the QA shell and what sits beside it
+//     beside: [                                                    // staged beside the shell, in order
+//       { built: "heardright-engine" },                            // another executable of the same compile output (same profile directory)
+//       { built: "heardright-engine", optional: true },            // ... absent is allowed
+//       { from: "src-tauri/resources", to: "resources" },          // a file or tree of the snapshot (a list names fallbacks: the first that exists)
+//       { from: "src-tauri/fonts", to: "fonts", resource: true, platforms: ["mac"] },  // `platforms` (mac, win) limits an entry to those hosts
+//       { from: "src-tauri/resources", to: ".", resource: true },  // ... into the app's RESOURCE directory, as an install has it: beside the exe on
+//                                                                  //     Windows, `Contents/Resources` of the bundle rightkit-qa makes on macOS
+//       { from: ["src-tauri/binaries/heardright-engine-aarch64-apple-darwin"], to: "heardright-engine" },
+//     ],
+//   }
+//
+// `build` names suites of the app's own `tests.suites` (the steps `--to test` runs): source QA runs them first, through the same door and signing policy
+// (test-command.mjs runSuites), and the shell and `built` entries are then found in THOSE suites' output directories, never the release compile's. When a
+// sign step is among them, the shell and every `built` entry are staged from its signed copies (rightkit#1303), and one it did not sign is refused.
+// Without `build` the shell is looked for in the compile outputs the gate hands over.
+// On macOS rightkit-qa wraps the stashed shell in a bundle and carries the staged layout into it (control.rs make_bundle): every entry beside the
+// shell goes to `Contents/MacOS` (where an install keeps its externalBin sidecars), and the `Resources/` directory a `resource: true` entry is
+// staged into goes to `Contents/Resources` (where Tauri's resource_dir() points in an install). On Windows the shell runs in place, its
+// resource directory is its own directory, so a `resource: true` entry is staged beside it.
+// `from` stays inside the snapshot app root (links resolved), `to` stays beside the shell. Scenario state (a seeded settings.json) is the scenario's
+// own `write_file` step inside the runner's isolated data directory, not this layout. Every file staged is digested into the receipt.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { QA_CONTROL_MARKER } from "./qa-control-scan.mjs";
+import { realish } from "./qa-snapshot.mjs";
+
+export const QA_COMPILED_DIRS_ENV = "RIGHT_RELEASE_QA_COMPILED_DIRS";
+/** A direct host's Cargo output directories the gate pinned for this stage (JSON list): what a suite built there lands in (test-command.mjs). */
+export const GATE_TARGET_DIRS_ENV = "RIGHTKIT_GATE_TARGET_DIRS";
+export const QA_APP_BINARY_ENV = "RIGHTKIT_QA_APP_BINARY";
+export const STASH_DIR = ".rightkit-qa-bin";
+/** The profile directories the runner reads for a dev build (binary.rs DEV_PROFILES); `release` is never one. */
+export const DEV_PROFILES = Object.freeze(["release-iterate", "debug", "dev"]);
+
+const LAYOUT_KEYS = new Set(["binary", "beside", "build"]);
+const BESIDE_KEYS = new Set(["built", "from", "to", "optional", "resource", "platforms"]);
+const LAYOUT_PLATFORMS = new Set(["mac", "win"]);
+/** The directory beside a macOS shell that rightkit-qa's bundle maps to `Contents/Resources` (rightkit-qa control.rs MAC_RESOURCES_DIR). */
+export const MAC_RESOURCES_DIR = "Resources";
+const BARE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+
+const fail = (code, message) => Object.assign(new Error(`${code}: ${message}`), { code });
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const sha256Of = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+const insideOrSame = (child, parent) => { const rel = path.relative(parent, child); return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel)); };
+const cleanRel = (value) => (typeof value === "string" && value && !path.isAbsolute(value) && !/^[A-Za-z]:/.test(value) && !value.replaceAll("\\", "/").split("/").includes("..") ? value.replaceAll("\\", "/").replace(/\/+$/, "") || "." : null);
+
+/** Problems with a `qa.layout` declaration, all at once; empty when it is well formed. */
+export function validateQaLayout(layout) {
+  if (!isObject(layout)) return ["qa.layout must be an object { binary, beside? }"];
+  const problems = [];
+  for (const key of Object.keys(layout)) if (!LAYOUT_KEYS.has(key)) problems.push(`qa.layout has unknown key ${JSON.stringify(key)} (allowed: ${[...LAYOUT_KEYS].join(", ")})`);
+  if (typeof layout.binary !== "string" || !BARE_NAME.test(layout.binary) || /\.exe$/i.test(layout.binary)) problems.push("qa.layout.binary must be a bare cargo bin target name (no path, no .exe)");
+  if (layout.beside !== undefined && !Array.isArray(layout.beside)) problems.push("qa.layout.beside must be a list");
+  if (layout.build !== undefined && (!Array.isArray(layout.build) || !layout.build.length || layout.build.some((name) => typeof name !== "string" || !name) || new Set(layout.build).size !== layout.build.length)) problems.push("qa.layout.build must be a non-empty list of distinct tests.suites names");
+  const tos = new Set();
+  (Array.isArray(layout.beside) ? layout.beside : []).forEach((item, index) => {
+    const at = `qa.layout.beside[${index}]`;
+    if (!isObject(item)) { problems.push(`${at} must be an object`); return; }
+    for (const key of Object.keys(item)) if (!BESIDE_KEYS.has(key)) problems.push(`${at} has unknown key ${JSON.stringify(key)} (allowed: ${[...BESIDE_KEYS].join(", ")})`);
+    const hasBuilt = item.built !== undefined; const hasFrom = item.from !== undefined;
+    if (hasBuilt === hasFrom) problems.push(`${at} needs exactly one of built or from`);
+    if (hasBuilt && (typeof item.built !== "string" || !BARE_NAME.test(item.built) || /\.exe$/i.test(item.built))) problems.push(`${at}.built must be a bare cargo bin target name`);
+    if (hasFrom) {
+      const list = Array.isArray(item.from) ? item.from : [item.from];
+      if (!list.length || list.some((from) => cleanRel(from) === null)) problems.push(`${at}.from must be a relative path (or a non-empty list of them) inside the app, without ..`);
+      if (item.to === undefined) problems.push(`${at}.to is required with from`);
+    }
+    if (item.to !== undefined && cleanRel(item.to) === null) problems.push(`${at}.to must be a relative path beside the binary, without ..`);
+    if (item.optional !== undefined && typeof item.optional !== "boolean") problems.push(`${at}.optional must be a boolean`);
+    if (item.resource !== undefined && (item.resource !== true || !hasFrom)) problems.push(`${at}.resource must be true and only with from`);
+    if (item.platforms !== undefined && (!Array.isArray(item.platforms) || !item.platforms.length || item.platforms.some((p) => !LAYOUT_PLATFORMS.has(p)))) problems.push(`${at}.platforms must be a non-empty list of ${[...LAYOUT_PLATFORMS].join(", ")}`);
+    const to = hasBuilt ? (cleanRel(item.to) ?? item.built) : item.resource ? `${MAC_RESOURCES_DIR}/${cleanRel(item.to)}` : cleanRel(item.to);
+    // Several `from` entries may fill one directory (a file both would write is refused when staged); a built executable is staged once.
+    if (to && hasBuilt) { if (tos.has(to)) problems.push(`${at} stages ${to} a second time`); tos.add(to); }
+  });
+  return problems;
+}
+
+/** `RIGHT_RELEASE_QA_COMPILED_DIRS`: a JSON list of absolute directories; null when unset, a typed error when malformed. */
+export function compiledDirsFromEnv(env = process.env) {
+  const raw = env?.[QA_COMPILED_DIRS_ENV];
+  if (raw === undefined || raw === "") return null;
+  let dirs;
+  try { dirs = JSON.parse(raw); } catch { throw fail("RK_QA_LAYOUT_DIRS", `${QA_COMPILED_DIRS_ENV} is not a JSON list`); }
+  if (!Array.isArray(dirs) || !dirs.length || dirs.some((dir) => typeof dir !== "string" || !path.isAbsolute(dir))) throw fail("RK_QA_LAYOUT_DIRS", `${QA_COMPILED_DIRS_ENV} must be a non-empty JSON list of absolute directories`);
+  return dirs;
+}
+
+const exeName = (name, platform) => (platform === "win" ? `${name}.exe` : name);
+const hasMarker = (file) => {
+  const bytes = fs.readFileSync(file);
+  return bytes.includes(Buffer.from(QA_CONTROL_MARKER, "latin1")) || bytes.includes(Buffer.from(QA_CONTROL_MARKER, "utf16le"));
+};
+const listDirs = (dir) => { try { return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); } catch { return []; } };
+
+/** Every `<dir>/[<triple>/]<profile>/<name>` regular file under the compile output directories, newest first, with the profile directory and triple. */
+export function findBuiltExecutables(dirs, name, platform) {
+  const found = [];
+  for (const dir of dirs) {
+    const profileRoots = [{ root: dir, triple: "host" }, ...listDirs(dir).filter((n) => n.includes("-") && !DEV_PROFILES.includes(n)).map((n) => ({ root: path.join(dir, n), triple: n }))];
+    for (const { root, triple } of profileRoots) {
+      for (const profile of DEV_PROFILES) {
+        const file = path.join(root, profile, exeName(name, platform));
+        try { const meta = fs.statSync(file); if (meta.isFile()) found.push({ file, dir, profileDir: path.dirname(file), triple, mtimeMs: meta.mtimeMs }); } catch { /* not built here */ }
+      }
+    }
+  }
+  return found.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+
+function copyTree(from, to, entries, relBase) {
+  const meta = fs.lstatSync(from);
+  if (meta.isSymbolicLink()) throw fail("RK_QA_LAYOUT_LINK", `${from} is a symbolic link; a staged layout copies only regular files`);
+  if (meta.isDirectory()) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const name of fs.readdirSync(from).sort()) copyTree(path.join(from, name), path.join(to, name), entries, `${relBase}/${name}`);
+    return;
+  }
+  if (!meta.isFile()) throw fail("RK_QA_LAYOUT_KIND", `${from} is neither a file nor a directory`);
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  // Two entries filling one directory may not write the same file with other bytes.
+  if (fs.existsSync(to)) {
+    if (sha256Of(fs.readFileSync(to)) !== sha256Of(fs.readFileSync(from))) throw fail("RK_QA_LAYOUT_COLLISION", `${relBase} is staged twice with different bytes (${from})`);
+    return; // the same bytes, already staged and recorded
+  }
+  fs.copyFileSync(from, to);
+  fs.chmodSync(to, meta.mode & 0o777);
+  entries.push({ path: relBase, sha256: sha256Of(fs.readFileSync(to)), bytes: meta.size });
+}
+
+/** A directory that mirrors `src` with every entry a symlink, except the directories on the way to `relFile`, which are real, and `relFile` itself (a copy). */
+function mirror(src, dst, relParts, copyFile) {
+  fs.mkdirSync(dst, { recursive: true });
+  const [head, ...tail] = relParts;
+  for (const name of fs.readdirSync(src)) {
+    if (name === ".git" || name === STASH_DIR) continue;
+    const from = path.join(src, name); const to = path.join(dst, name);
+    if (name === head && tail.length) mirror(from, to, tail, copyFile);
+    else if (name === head) copyFile(from, to);
+    else fs.symlinkSync(from, to);
+  }
+}
+
+/**
+ * Stage the run-scoped overlay app root, the QA shell and its declared layout. Returns
+ * `{ runDir, appRoot, configFile, binary, evidence, cleanup }`; `cleanup()` removes `runDir`. Nothing is written under `appRoot` of the snapshot.
+ * `snapshotAppRoot` is the app root the release config lives in, `qaConfigFile` the absolute qa config inside it, `runsRoot` the gate's runs root
+ * (outside every repository and snapshot), `dirs` the compile output directories. `signed` (a sign step's `{ "<path in its output dir>": "<signed copy>" }`)
+ * makes the shell and every `built` entry come from their signed copies; a file it does not name is refused.
+ */
+export function stageQaLayout({ layout, snapshotAppRoot, qaConfigFile, runsRoot, dirs, platform, signed = null, now = () => Date.now() }) {
+  const problems = validateQaLayout(layout);
+  if (problems.length) throw fail("RK_QA_LAYOUT_INVALID", problems.join("; "));
+  const sourceRoot = fs.realpathSync.native(snapshotAppRoot);
+  const configReal = fs.realpathSync.native(qaConfigFile);
+  if (!insideOrSame(configReal, sourceRoot)) throw fail("RK_QA_LAYOUT_CONFIG", `the qa config ${qaConfigFile} is outside the app root ${snapshotAppRoot}`);
+  if (!path.isAbsolute(runsRoot) || insideOrSame(realish(runsRoot), sourceRoot)) throw fail("RK_QA_LAYOUT_PLACE", `the runs root ${runsRoot} must be an absolute directory outside the snapshot`);
+
+  const candidates = findBuiltExecutables(dirs, layout.binary, platform);
+  if (!candidates.length) throw fail("RK_QA_LAYOUT_NO_BINARY", `no ${exeName(layout.binary, platform)} in a ${DEV_PROFILES.join("/")} directory of the compile outputs (${dirs.join(", ")}); the compile did not build the QA shell`);
+  // The bytes staged for a built file: its signed copy when a sign step ran, keyed by its path inside the output directory it was found in.
+  const bytesOf = (file, dir) => {
+    if (!signed) return file;
+    const rel = path.relative(dir, file).split(path.sep).join("/");
+    const copy = signed[rel];
+    if (typeof copy !== "string" || !fs.existsSync(copy)) throw fail("RK_QA_LAYOUT_UNSIGNED", `${file} (${rel}) has no signed copy; the declared sign step signed ${Object.keys(signed).join(", ") || "nothing"}`);
+    return copy;
+  };
+  const shell = candidates.find((candidate) => hasMarker(candidate.file));
+  if (!shell) throw fail("RK_QA_LAYOUT_NOT_QA", `${candidates.map((c) => c.file).join(", ")} carry no QA control marker; the compile built a plain app, not the QA shell`);
+
+  fs.mkdirSync(runsRoot, { recursive: true, mode: 0o700 });
+  const runDir = fs.mkdtempSync(path.join(runsRoot, `qa-layout-${now().toString(36)}-`));
+  const cleanup = () => { try { fs.rmSync(runDir, { recursive: true, force: true }); } catch { /* the runs root is pruned */ } };
+  try {
+    const appRoot = path.join(runDir, "app");
+    const relConfig = path.relative(sourceRoot, configReal).split(path.sep);
+    const configFile = path.join(appRoot, ...relConfig);
+    mirror(sourceRoot, appRoot, relConfig, (from, to) => fs.copyFileSync(from, to));
+    const besideDir = path.join(appRoot, STASH_DIR, shell.triple);
+    fs.mkdirSync(besideDir, { recursive: true });
+    const binary = path.join(besideDir, exeName(layout.binary, platform));
+    fs.copyFileSync(bytesOf(shell.file, shell.dir), binary);
+    fs.chmodSync(binary, 0o755);
+    const evidence = { source: shell.file, ...(signed ? { signed: true } : {}), binary: { name: path.basename(binary), sha256: sha256Of(fs.readFileSync(binary)) }, qaConfig: { sha256: sha256Of(fs.readFileSync(configFile)) }, beside: [] };
+    for (const item of layout.beside ?? []) {
+      if (Array.isArray(item.platforms) && !item.platforms.includes(platform)) continue;
+      const optional = item.optional === true;
+      if (item.built !== undefined) {
+        const from = path.join(shell.profileDir, exeName(item.built, platform));
+        const toName = cleanRel(item.to) ?? exeName(item.built, platform);
+        if (!fs.existsSync(from)) { if (optional) continue; throw fail("RK_QA_LAYOUT_MISSING", `layout names built executable ${item.built}, but ${from} is not in the QA shell's output directory`); }
+        copyTree(bytesOf(from, shell.dir), path.join(besideDir, toName), evidence.beside, toName);
+        continue;
+      }
+      const options = (Array.isArray(item.from) ? item.from : [item.from]).map(cleanRel);
+      const pick = options.map((rel) => path.join(sourceRoot, rel)).find((file) => fs.existsSync(file));
+      if (!pick) { if (optional) continue; throw fail("RK_QA_LAYOUT_MISSING", `layout source ${options.join(" or ")} does not exist in the snapshot`); }
+      if (!insideOrSame(fs.realpathSync.native(pick), sourceRoot)) throw fail("RK_QA_LAYOUT_ESCAPE", `layout source ${pick} resolves outside the app root`);
+      const rel = cleanRel(item.to);
+      // A resource goes to the app's resource directory: `Resources/` (Contents/Resources of the macOS bundle) on macOS, beside the shell on Windows.
+      const toName = item.resource && platform === "mac" ? path.posix.join(MAC_RESOURCES_DIR, rel) : rel;
+      copyTree(pick, path.join(besideDir, toName), evidence.beside, toName);
+    }
+    evidence.beside.sort((a, b) => a.path.localeCompare(b.path));
+    return { runDir, appRoot, configFile, binary, evidence, cleanup };
+  } catch (error) { cleanup(); throw error; }
+}

package/qa-runner.mjs

@@ -0,0 +1,156 @@
+// The rightkit-qa runner an app's `qa.version` names, obtained the one sanctioned way (rightkit#1309 pins are routine; never a PATH binary).
+//
+// `right-release qa` used to take the runner from `qa.runner` (a file inside the source) or the first `rightkit-qa` on PATH. A source snapshot holds no
+// runner and PATH is not a trust root, so a package stage's source QA had nothing admissible to run. The runner is now a managed tool, the pattern of
+// scan-tool-enrolment.mjs:
+//
+//   record   `<managed data root>/qa-runners/<mac|win>/record.json`, `{schema, platform, runners: {<version>: {path, sha256, version}}, enrolledAt}`, and the
+//            binary itself at `<managed data root>/qa-runners/<platform>/<version>/rightkit-qa[.exe]`: a COPY the enrol operation made, so a later
+//            `cargo clean` or target rotation cannot change what a receipt digests. Outside every repository and snapshot.
+//   enrol    `enrollQaRunner` (also `right-release qa runner enroll`): the operator names a built file (RightKit's own gate-built `crates/rightkit-qa`
+//            output) and the version; the file must be a regular executable that answers `--version` with exactly `rightkit-qa <version>`; its copy is
+//            digested and recorded. A second enrolment of the same version is a rotation and needs `rotate`.
+//   use      `resolveManagedQaRunner`: the record names the version the app declared; the managed file must still be a real file inside the managed
+//            directory whose sha256 IS the recorded one and which still answers `--version` as that version. Anything else refuses, naming it.
+//   admit    unchanged and separate: the sealed receipt carries the runner's sha256, and qa-admission-policy.json `approvedRunners` (version + platform +
+//            sha256, release-qa-policy.mjs approve-runner) decides whether the receipt is admitted. This module trusts nothing on its own.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { resolveManagedRoots } from "./managed-roots.mjs";
+
+export const QA_RUNNERS_SCHEMA = "rightkit.qa-runners/1";
+export const QA_RUNNERS_DIR = "qa-runners";
+export const QA_RUNNER_PLATFORMS = Object.freeze(["mac", "win"]);
+const HOST_PLATFORM = { darwin: "mac", win32: "win" };
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export class QaRunnerError extends Error {
+  constructor(code, message) { super(message); this.name = "QaRunnerError"; this.code = code; }
+}
+const fail = (code, message) => { throw new QaRunnerError(code, message); };
+
+/** True when `qa.version` names a rightkit-qa release (`0.10.0`), as opposed to the legacy QA plan version (`"1"`). */
+export const isRunnerVersion = (version) => SEMVER.test(String(version ?? ""));
+
+export const runnerExecutableName = (platform) => (platform === "win" ? "rightkit-qa.exe" : "rightkit-qa");
+
+const checkPlatform = (platform) => { if (!QA_RUNNER_PLATFORMS.includes(platform)) fail("RK_QA_RUNNER_PLATFORM", `platform must be ${QA_RUNNER_PLATFORMS.join(" or ")}, not ${JSON.stringify(platform)}`); };
+const checkDataRoot = (dataRoot) => { if (!dataRoot || !path.isAbsolute(dataRoot)) fail("RK_QA_RUNNER_ROOT", "the managed data root must be an absolute path"); };
+
+export const qaRunnersDir = ({ dataRoot, platform }) => { checkDataRoot(dataRoot); checkPlatform(platform); return path.join(dataRoot, QA_RUNNERS_DIR, platform); };
+export const qaRunnersRecordFile = (args) => path.join(qaRunnersDir(args), "record.json");
+export const qaRunnerFile = ({ dataRoot, platform, version }) => {
+  if (!isRunnerVersion(version)) fail("RK_QA_RUNNER_VERSION", `${JSON.stringify(version)} is not a rightkit-qa version (major.minor.patch)`);
+  return path.join(qaRunnersDir({ dataRoot, platform }), version, runnerExecutableName(platform));
+};
+
+const sha256OfFile = (file) => crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+const isInside = (child, parent) => { const rel = path.relative(parent, child); return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel); };
+
+/** The runner's own answer to `--version` must be exactly `rightkit-qa <version>`; the file that answers is the file that is digested. */
+function assertReportsVersion(file, version, spawn) {
+  const run = spawn(file, ["--version"], { encoding: "utf8", windowsHide: true, timeout: 30000 });
+  const output = String(run?.stdout ?? "").trim();
+  if (run?.status !== 0 || output !== `rightkit-qa ${version}`) {
+    fail("RK_QA_RUNNER_VERSION_MISMATCH", `${file} --version reported ${JSON.stringify(output.slice(0, 80))} (exit ${run?.status ?? run?.error?.message ?? "none"}), expected "rightkit-qa ${version}"`);
+  }
+}
+
+function readRecord({ dataRoot, platform }) {
+  const file = qaRunnersRecordFile({ dataRoot, platform });
+  let meta;
+  try { meta = fs.lstatSync(file); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (meta.isSymbolicLink() || !meta.isFile()) fail("RK_QA_RUNNER_RECORD", `${file} is not a regular file`);
+  if (process.platform !== "win32" && (meta.mode & 0o022)) fail("RK_QA_RUNNER_RECORD", `${file} is writable by group or others`);
+  let record;
+  try { record = JSON.parse(fs.readFileSync(file, "utf8")); } catch (error) { fail("RK_QA_RUNNER_RECORD", `${file} is not JSON (${error.message})`); }
+  if (record?.schema !== QA_RUNNERS_SCHEMA || record.platform !== platform || record.runners === null || typeof record.runners !== "object" || Array.isArray(record.runners)) {
+    fail("RK_QA_RUNNER_RECORD", `${file} is not a ${QA_RUNNERS_SCHEMA} record for ${platform}`);
+  }
+  return { file, record };
+}
+
+/**
+ * The explicit enrol operation. `runner` is a built rightkit-qa file (an absolute path); its copy under the managed directory is what is recorded.
+ * Enrols on the host whose platform it is (the bytes are executed here to read their version). Returns `{ file, runnerFile, entry, rotated }`.
+ */
+export function enrollQaRunner({ dataRoot, platform, runner, version, rotate = false, spawn = spawnSync, hostPlatform = process.platform, now = () => new Date() }) {
+  checkPlatform(platform);
+  if (HOST_PLATFORM[hostPlatform] !== platform) fail("RK_QA_RUNNER_PLATFORM", `a ${platform} runner is enrolled on a ${platform} host (this is ${hostPlatform}): its bytes are executed to read their version`);
+  const target = qaRunnerFile({ dataRoot, platform, version });
+  if (!runner || !path.isAbsolute(String(runner))) fail("RK_QA_RUNNER_PATH", "the runner must be named by an absolute path");
+  let source; let meta;
+  try { source = fs.realpathSync.native(runner); meta = fs.statSync(source); } catch (error) { fail("RK_QA_RUNNER_PATH", `the runner ${runner} cannot be resolved (${error.code ?? error.message})`); }
+  if (!meta.isFile()) fail("RK_QA_RUNNER_PATH", `${source} is not a regular file`);
+  if (platform !== "win" && (meta.mode & 0o111) === 0) fail("RK_QA_RUNNER_PATH", `${source} is not executable`);
+  assertReportsVersion(source, version, spawn);
+  const existing = readRecord({ dataRoot, platform });
+  const had = existing?.record.runners?.[version] ?? null;
+  if (had && !rotate) fail("RK_QA_RUNNER_EXISTS", `${existing.file} already enrols rightkit-qa ${version} (sha256 ${String(had.sha256).slice(0, 12)}); replacing it is a rotation (pass rotate)`);
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const staging = `${target}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.copyFileSync(source, staging, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(staging, 0o755);
+    assertReportsVersion(staging, version, spawn);
+    fs.renameSync(staging, target);
+  } finally { fs.rmSync(staging, { force: true }); }
+  const entry = { path: target, sha256: sha256OfFile(target), version };
+  const record = { schema: QA_RUNNERS_SCHEMA, platform, runners: { ...(existing?.record.runners ?? {}), [version]: entry }, enrolledAt: now().toISOString() };
+  const file = qaRunnersRecordFile({ dataRoot, platform });
+  const tmp = `${file}.${crypto.randomUUID()}.tmp`;
+  try { fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 }); fs.renameSync(tmp, file); } finally { fs.rmSync(tmp, { force: true }); }
+  return { file, runnerFile: target, entry, rotated: Boolean(had) };
+}
+
+/**
+ * The managed runner for `version` on `platform`: `{ file, sha256, version, source: "managed" }`, or a typed refusal. The record is read, the file it names
+ * must be the managed copy (inside the managed directory, not a link), its bytes must still hash to the recorded sha256, and it must still answer
+ * `--version` with that version. There is no fallback: a missing enrolment is a refusal that names the operation that makes one.
+ */
+export function resolveManagedQaRunner({ dataRoot, platform, version, spawn = spawnSync }) {
+  checkPlatform(platform);
+  if (!isRunnerVersion(version)) fail("RK_QA_RUNNER_VERSION", `qa.version ${JSON.stringify(version)} is not a rightkit-qa version (major.minor.patch)`);
+  const expected = qaRunnerFile({ dataRoot, platform, version });
+  const read = readRecord({ dataRoot, platform });
+  const entry = read?.record.runners?.[version];
+  if (!entry) fail("RK_QA_RUNNER_MISSING", `rightkit-qa ${version} is not enrolled for ${platform} (${qaRunnersRecordFile({ dataRoot, platform })}); build crates/rightkit-qa ${version} through the gate and run \`right-release qa runner enroll --runner <built rightkit-qa> --version ${version} --platform ${platform}\``);
+  if (entry.version !== version || !SHA256.test(String(entry.sha256)) || entry.path !== expected) fail("RK_QA_RUNNER_RECORD", `${read.file}: the entry for ${version} is malformed or names a file other than ${expected}`);
+  let meta;
+  try { meta = fs.lstatSync(expected); } catch (error) { fail("RK_QA_RUNNER_MISSING", `the enrolled rightkit-qa ${version} is gone (${expected}: ${error.code ?? error.message}); enrol it again`); }
+  if (meta.isSymbolicLink() || !meta.isFile()) fail("RK_QA_RUNNER_RECORD", `${expected} is not a regular file`);
+  if (!isInside(fs.realpathSync.native(expected), fs.realpathSync.native(path.join(dataRoot, QA_RUNNERS_DIR)))) fail("RK_QA_RUNNER_RECORD", `${expected} resolves outside ${path.join(dataRoot, QA_RUNNERS_DIR)}`);
+  const actual = sha256OfFile(expected);
+  if (actual !== entry.sha256) fail("RK_QA_RUNNER_DIGEST", `the enrolled rightkit-qa ${version} at ${expected} has sha256 ${actual}, not the recorded ${entry.sha256}; it changed after enrolment`);
+  assertReportsVersion(expected, version, spawn);
+  return { file: expected, sha256: actual, version, source: "managed" };
+}
+
+/** `node qa-runner.mjs enroll --data-root <dir> --platform mac|win --runner <file> --version <v> [--rotate]` or `show --data-root <dir> --platform mac|win`. */
+export function main(argv, { out = (m) => process.stdout.write(`${m}\n`), err = (m) => process.stderr.write(`${m}\n`), env = process.env, spawn, program = "qa-runner.mjs" } = {}) {
+  const [command, ...rest] = argv;
+  const opt = (name) => { const i = rest.indexOf(name); return i < 0 ? undefined : rest[i + 1]; };
+  try {
+    const platform = opt("--platform") ?? HOST_PLATFORM[process.platform];
+    const dataRoot = opt("--data-root") ?? resolveManagedRoots({ env }).dataRoot;
+    if (command === "enroll") {
+      const r = enrollQaRunner({ dataRoot, platform, runner: opt("--runner") && path.resolve(opt("--runner")), version: opt("--version"), rotate: rest.includes("--rotate"), ...(spawn ? { spawn } : {}) });
+      out(`enrolled rightkit-qa ${r.entry.version} for ${platform} (sha256 ${r.entry.sha256}) at ${r.runnerFile}${r.rotated ? " (rotation)" : ""}; approve it for admission with \`right-release qa policy approve-runner --runner ${r.runnerFile} --version ${r.entry.version} --platform ${platform} --set-by <name>\``);
+      return 0;
+    }
+    if (command === "show") {
+      const read = readRecord({ dataRoot, platform });
+      out(read ? JSON.stringify(read.record) : "no enrolment");
+      return read ? 0 : 1;
+    }
+    err(`usage: ${program} enroll --platform mac|win --runner <built rightkit-qa> --version <v> [--data-root <dir>] [--rotate]\n       ${program} show [--platform mac|win] [--data-root <dir>]`);
+    return 2;
+  } catch (error) { err(`${error.code ?? "error"}: ${error.message}`); return 1; }
+}
+
+if (process.argv[1] && (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })()) process.exit(main(process.argv.slice(2)));

package/release-artifact-path.mjs

@@ -26,6 +26,7 @@
 import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { shimMapOfEnv } from "./cargo-target-shim.mjs";
 import { resolveTargetRoot as cargoResolveTargetRoot } from "./cargo-target.mjs";
 import { expandRecipeBuildCommands } from "./recipe-build.mjs";
 import { SourceSplitError, readSourceSplit } from "./source-split.mjs";
@@ -123,10 +124,17 @@ export function splitArtifactContext({
   if (!root) { try { root = readSourceSplit({ env, cwd: appRoot })?.snapshot ?? null; } catch (error) { if (!(error instanceof SourceSplitError)) throw error; } }
   const snapshot = canonical(root ?? appRoot);
   const pinned = typeof env.CARGO_TARGET_DIR === "string" && path.isAbsolute(env.CARGO_TARGET_DIR) ? canonical(env.CARGO_TARGET_DIR) : null;
+  // Under the per-call wrapper of SEVERAL workspaces (cargo-target-shim.mjs) CARGO_TARGET_DIR is no binding: the wrapper binds each call's
+  // workspace to its own checkout target, and any CARGO_TARGET_DIR in this process is ambient or a scan sentinel. The binding of a manifest
+  // is then the wrapper's map entry for the workspace that holds it. One workspace (or no wrapper) keeps the process-wide value.
+  const wrapperMap = resolve ? multiWorkspaceWrapperMap(env) : null;
   const cache = new Map();
   const boundTargets = declared.map(({ prefix, manifest }) => {
     if (!resolve) return Object.freeze({ prefix, manifest, dir: null });
-    if (!cache.has(manifest)) cache.set(manifest, bindManifest({ manifest, appRoot, snapshot, pinned, resolveTargetRoot, exists }));
+    if (!cache.has(manifest)) {
+      const mapped = wrapperMap ? wrapperBindingOf(wrapperMap, manifest) : null;
+      cache.set(manifest, bindManifest({ manifest, appRoot, snapshot, pinned: wrapperMap ? (mapped?.target ?? null) : pinned, workspace: mapped?.workspace ?? null, resolveTargetRoot, exists }));
+    }
     return Object.freeze({ prefix, manifest, dir: cache.get(manifest) });
   });
   return Object.freeze({
@@ -135,7 +143,25 @@ export function splitArtifactContext({
   });
 }
 
-function bindManifest({ manifest, appRoot, snapshot, pinned, resolveTargetRoot, exists }) {
+/** The wrapper map of this process when it binds more than one workspace; null for no wrapper or a single workspace (CARGO_TARGET_DIR binds that). */
+function multiWorkspaceWrapperMap(env) {
+  const map = shimMapOfEnv(env);
+  return map && Object.keys(map.workspaces).length > 1 ? map : null;
+}
+
+/** The wrapper's binding for the workspace holding `manifest`: the deepest mapped workspace that contains it, as `{ workspace, target }`; null when none does. */
+function wrapperBindingOf(map, manifest) {
+  const dir = canonical(path.dirname(manifest));
+  let best = null;
+  for (const [workspace, target] of Object.entries(map.workspaces)) {
+    if (typeof target !== "string" || !path.isAbsolute(target)) continue;
+    const root = canonical(workspace);
+    if (insideCanonical(dir, root) && (!best || root.length > best.root.length)) best = { root, workspace, target: canonical(target) };
+  }
+  return best ? { workspace: best.workspace, target: best.target } : null;
+}
+
+function bindManifest({ manifest, appRoot, snapshot, pinned, workspace = null, resolveTargetRoot, exists }) {
   if (!exists(manifest)) throw new ArtifactPathError(SPLIT_TARGET_UNRESOLVED_CODE, `the Cargo manifest ${manifest} is not in the snapshot, so its target directory cannot be bound; a split never falls back to a snapshot-relative target/`);
   let dir;
   try { dir = resolveTargetRoot(manifest); } catch (error) {
@@ -146,7 +172,7 @@ function bindManifest({ manifest, appRoot, snapshot, pinned, resolveTargetRoot,
   if (insideCanonical(real, snapshot) || insideCanonical(real, canonical(appRoot))) {
     throw new ArtifactPathError(SPLIT_TARGET_UNRESOLVED_CODE, `the Cargo target of ${manifest} resolves inside the snapshot (${dir}); the gate binds a split's target outside it (CARGO_TARGET_DIR, row 7.09) and never to a snapshot-relative target/`);
   }
-  if (pinned && real !== pinned) throw new ArtifactPathError(SPLIT_TARGET_DRIFT_CODE, `the Cargo target of ${manifest} is ${dir}, not the CARGO_TARGET_DIR the gate bound for this stage`);
+  if (pinned && real !== pinned) throw new ArtifactPathError(SPLIT_TARGET_DRIFT_CODE, `the Cargo target of ${manifest} is ${dir}, not the CARGO_TARGET_DIR the gate bound for this stage (expected ${pinned}${workspace ? `, the cargo wrapper's target for workspace ${workspace}` : ""})`);
   return path.resolve(dir);
 }
 

package/release-config.mjs

@@ -41,7 +41,7 @@ export const LEGACY_EXECUTABLE_EXTENSIONS = Object.freeze([".mjs", ".js", ".cjs"
 export const TOP_LEVEL_KEYS = Object.freeze([
   "$schema", "$comment", "schema", "app", "version", "channel", "distribution", "packageManager", "workdir", "targets", "development",
   "deps", "checks", "buildInputs", "hostedWorkflows", "devtools", "releaseSwitches", "qa", "nativeAssembly", "legal", "web", "tests",
-  "sidecars", "assembly", "releaseDependencies", "appStoreConnect", "storage", "cargoProfileExempt", "runtimeArtifacts",
+  "sidecars", "assembly", "releaseDependencies", "appStoreConnect", "storage", "cargoProfileExempt", "runtimeArtifacts", "windows",
 ]);
 export const TEMPLATE_TOKENS = Object.freeze(["app", "version", "home", "localAppData"]);
 

package/release-qa-command.mjs

@@ -6,13 +6,17 @@
 //   right-release qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]   (release-qa-audit.mjs; exit 1 when an uploaded build lacks passing QA)
 //   right-release qa policy show | set --app <app> --mode warn|refuse --set-by <name> [--stage source|installed]
 //                         | approve-runner --runner <file> --version <v> --platform mac|win --set-by <name> [--note <text>]   (release-qa-policy.mjs)
+//   right-release qa runner enroll --runner <built rightkit-qa> --version <v> [--platform mac|win] [--rotate] | show   (qa-runner.mjs)
 //
 // The release config declares the app's QA plan:
 //   qa: { version: "1", config: "rightkit-qa.toml", runner?: "<path to rightkit-qa>",
 //         args?: { source?: [..], installed?: [..] },                                   // {sealedDir} {releaseId} expand; installed also {installedApp} {installedDir} {qaRoot}
 //         installed?: { installDir?: "<abs dir>" },                                       // opt in: mount the sealed DMG (mac) / run the sealed NSIS installer (win, needs RIGHT_RELEASE_QA_ALLOW_INSTALL=1 off CI), see release-qa-installed.mjs
 //         journeys?: { manifest?: "journeys.toml", receipt?: "<path to a rightkit.journeys.receipt/1>", args?: { source?: [..], installed?: [..] } },
+//         layout?: { binary: "<bin target of the QA shell>", beside?: [..], build?: [<tests.suites names>] },   // source stage: run against the gate-built QA shell in the layout an install has, see qa-layout.mjs
 //         checks: { "smoke.launch": ["app.launch"], journey: ["journey.*"] } }          // floor id -> evidence check names
+// `qa.version` that is a rightkit-qa version (0.10.0) names the runner: the managed, digest-recorded one enrolled by `right-release qa runner enroll`
+// (qa-runner.mjs), never a PATH binary. A legacy plan version ("1") with no `qa.runner` still takes the first `rightkit-qa` on PATH.
 // Every id in release-qa-floor.json must be mapped; skipped/failed/missing required checks fail the receipt.
 // `qa.journeys` maps the floor's `journey` id to "every release-critical journey required on this platform passed":
 // `rightkit-qa journeys run` is run (or `receipt` is read), the receipt is validated through `rightkit-qa journeys
@@ -37,6 +41,11 @@ import {
   qaReceiptPath, QA_STAGES, sealQaReceipt, sourceIdentity, validateAppQaConfig, writeQaReceipt,
 } from "./release-qa-receipt.mjs";
 import { platformDirOf } from "./platform-dir.mjs";
+import { isRunnerVersion, main as runnerMain, resolveManagedQaRunner } from "./qa-runner.mjs";
+import { compiledDirsFromEnv, QA_APP_BINARY_ENV, stageQaLayout, validateQaLayout } from "./qa-layout.mjs";
+import { gateRunsRoot, resolveManagedRoots } from "./managed-roots.mjs";
+import { planTests, runSuites } from "./test-command.mjs";
+import { QA_SIGNED_FILES_ENV } from "./suite-signing-policy.mjs";
 
 const sha256File = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
 
@@ -119,6 +128,8 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
   const { floor, digest: floorDigest } = loadQaFloor(deps.floorDir);
   const problems = validateAppQaConfig(config.qa, floor, stage);
   if (problems.length) throw new Error(`release config QA plan does not meet the protected QA floor:\n- ${problems.join("\n- ")}`);
+  const layoutProblems = config.qa.layout === undefined ? [] : validateQaLayout(config.qa.layout);
+  if (layoutProblems.length) throw new Error(`release config qa.layout is invalid:\n- ${layoutProblems.join("\n- ")}`);
 
   let releaseId = releaseIdArg;
   let sealed = null;
@@ -145,8 +156,17 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
     if (journeysDeclared.receipt) assertInsideSource(release, path.resolve(appRoot, String(journeysDeclared.receipt)), "qa.journeys.receipt");
   }
   if (config.qa.runner && !deps.runnerFile) assertInsideSource(release, path.resolve(appRoot, config.qa.runner), "qa.runner");
-  const runnerFile = deps.runnerFile ?? resolveRunner({ qa: config.qa, appRoot });
+  // A runner the config names is read from the source; else the managed runner of the version `qa.version` names (qa-runner.mjs); else, for a legacy plan version only, PATH.
+  let managedRunner = null;
+  let runnerFile = deps.runnerFile;
+  if (!runnerFile) {
+    if (!config.qa.runner && isRunnerVersion(config.qa.version)) {
+      managedRunner = (deps.resolveManagedRunner ?? resolveManagedQaRunner)({ dataRoot: resolveManagedRoots({ env: deps.env ?? process.env }).dataRoot, platform, version: String(config.qa.version) });
+      runnerFile = managedRunner.file;
+    } else runnerFile = resolveRunner({ qa: config.qa, appRoot });
+  }
   const runnerSha = sha256File(runnerFile);
+  if (managedRunner && managedRunner.sha256 !== runnerSha) throw new Error(`the managed rightkit-qa ${managedRunner.version} changed between its verification and its digest; refusing to seal`);
   const journeysConfig = config.qa.journeys ?? null;
   const qaConfig = path.resolve(appRoot, config.qa.config);
   if (!existsSync(qaConfig)) throw new Error(`qa.config does not exist: ${qaConfig}`);
@@ -161,25 +181,50 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
     });
   }
   let run, journeysRun = null;
+  let layoutStage = null;
   try {
+    // Source stage with a declared layout: the QA shell and its layout are staged in a run-scoped directory from the gate's compile outputs (qa-layout.mjs); the snapshot is never written.
+    if (stage === "source" && config.qa.layout?.build) {
+      // The QA shell is built here, by the app's own build (and sign) suites, never by the release compile (qa-layout.mjs `build`).
+      const env = deps.env ?? process.env;
+      const plan = planTests(config, { suites: config.qa.layout.build, appRoot });
+      const stageFrom = ({ outputs, env: suiteEnv }) => {
+        const dirs = [...new Set(plan.filter((item) => !item.sign).flatMap((item) => outputs.get(item.name) ?? []))];
+        if (!dirs.length) throw new Error(`qa.layout.build: ${plan.map((item) => item.name).join(", ")} passed but named no output directory (no carried receipt, and no RIGHTKIT_GATE_TARGET_DIRS from the gate)`);
+        const signed = plan.some((item) => item.sign) ? JSON.parse(suiteEnv[QA_SIGNED_FILES_ENV] ?? "{}") : null;
+        return (deps.stageLayout ?? stageQaLayout)({ layout: config.qa.layout, snapshotAppRoot: appRoot, qaConfigFile: qaConfig, runsRoot: deps.runsRoot ?? gateRunsRoot({ env }), dirs, platform, signed });
+      };
+      const built = await (deps.runSuites ?? runSuites)(plan, { appRoot, prefix: "qa_build", env, config, log: (line) => console.error(line), errLog: (line) => console.error(line), within: stageFrom });
+      if (built.exitCode !== 0) throw new Error(`qa.layout.build: the QA shell build failed (${built.results.filter((r) => r.exitCode !== 0).map((r) => r.suite).join(", ")}); no QA ran`);
+      layoutStage = built.within;
+    } else if (stage === "source" && config.qa.layout) {
+      const dirs = deps.compiledDirs ?? compiledDirsFromEnv(deps.env ?? process.env);
+      if (!dirs) throw new Error("qa.layout needs the gate's compile outputs (RIGHT_RELEASE_QA_COMPILED_DIRS names none): run source QA through `rightkit-gate --to package`, after its compile");
+      layoutStage = (deps.stageLayout ?? stageQaLayout)({ layout: config.qa.layout, snapshotAppRoot: appRoot, qaConfigFile: qaConfig, runsRoot: deps.runsRoot ?? gateRunsRoot({ env: deps.env ?? process.env }), dirs, platform });
+    }
     const expand = (value) => String(value).replaceAll("{sealedDir}", sealed?.sealedDir ?? "").replaceAll("{releaseId}", releaseId)
       .replaceAll("{installedApp}", installedQa?.installedApp ?? "").replaceAll("{installedDir}", installedQa?.installedDir ?? "").replaceAll("{qaRoot}", installedQa?.qaRoot ?? "");
     const installedDirs = installedDirNames(config, deps.env ?? process.env);
     const runEnv = {
       ...process.env, RIGHT_RELEASE_QA_STAGE: stage, RIGHT_RELEASE_QA_COMMIT: source.commit, RIGHT_RELEASE_QA_RELEASE_ID: releaseId,
       ...(sealed ? { RIGHT_RELEASE_QA_SEALED_DIR: sealed.sealedDir } : {}), ...(installedDirs.length ? { RIGHTKIT_QA_INSTALLED_DIRS: installedDirs.join(";") } : {}), ...(installedQa?.env ?? {}),
+      ...(layoutStage ? { [QA_APP_BINARY_ENV]: layoutStage.binary } : {}),
     };
-    const args = ["run", "--config", qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
+    const runCwd = layoutStage?.appRoot ?? appRoot;
+    const args = ["run", "--config", layoutStage?.configFile ?? qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
     run = (deps.spawnRunner ?? spawnSync)(runnerFile, args, {
-      cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+      cwd: runCwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
       env: runEnv,
     });
     // Journeys lane: the one release proof (ADR-0001 item 10). A receipt named in the config is read as is.
     if (journeysConfig && !journeysConfig.receipt) {
-      journeysRun = (deps.spawnJourneys ?? deps.spawnRunner ?? spawnSync)(runnerFile, ["journeys", "run", "--root", appRoot, ...((journeysConfig.args?.[stage] ?? []).map(expand))], {
-        cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024, env: runEnv,
+      journeysRun = (deps.spawnJourneys ?? deps.spawnRunner ?? spawnSync)(runnerFile, ["journeys", "run", "--root", runCwd, ...((journeysConfig.args?.[stage] ?? []).map(expand))], {
+        cwd: runCwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024, env: runEnv,
       });
     }
+  } catch (error) {
+    layoutStage?.cleanup();
+    throw error;
   } finally {
     installedQa?.cleanup();
   }
@@ -207,19 +252,23 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
     required = required.map((item) => (item.id === floor.journeys.floorId ? journeyRequiredItem({ floorId: item.id, validation }) : item));
   }
   const executionFinishedAt = new Date();
+  // The runner's outputs (evidence, journeys receipt) have been read; the run-scoped layout is not evidence and goes.
+  const layoutEvidence = layoutStage?.evidence ?? null;
+  layoutStage?.cleanup();
   // A passing receipt needs the runner to exit cleanly AND an evidence bundle that itself passed.
   if (run.status !== 0 && evidence) evidence = { ...evidence, status: "failed" };
-  const receipt = sealQaReceipt(buildQaReceipt({
+  // The layout evidence rides beside the standard body (release-qa-receipt.mjs is a policy-bundle entrypoint and stays untouched); the seal covers it.
+  const receipt = sealQaReceipt({ ...buildQaReceipt({
     stage, app: config.app, platform, releaseId, source, closure: dependencyClosure(repoRoot, source.commit, gitRunner),
     releaseConfigSha256: sha256File(configPath), qa: config.qa, floor, floorDigest,
     policyBundleDigest: deps.policyBundleDigest ?? currentPolicyBundleDigest(deps.floorDir),
-    runner: { basename: path.basename(runnerFile).replace(/\.exe$/i, ""), path: runnerFile, sha256: runnerSha },
+    runner: { basename: path.basename(runnerFile).replace(/\.exe$/i, ""), path: runnerFile, sha256: runnerSha, ...(managedRunner ? { version: managedRunner.version, source: "managed" } : {}) },
     evidence, evidenceSha256, required, artifacts, sourceReceiptDigest, journeys,
     execution: {
       startedAt: executionStartedAt.toISOString(), finishedAt: executionFinishedAt.toISOString(),
       runnerPids: [run.pid, journeysRun?.pid].filter((pid) => Number.isInteger(pid) && pid > 0), sealerPid: process.pid,
     },
-  }), key);
+  }), ...(layoutEvidence ? { layout: layoutEvidence } : {}) }, key);
   const file = qaReceiptPath({ repoRoot, releaseId, platform, stage });
   writeQaReceipt(file, receipt);
   // #183: copy the sealed receipt next to the candidate handoff so the signing job (a different runner) can read it.
@@ -239,6 +288,7 @@ function usage(code) {
 export async function main(args) {
   if (args[0] === "audit") process.exit(auditMain(args.slice(1)));
   if (args[0] === "policy") process.exit(policyMain(args.slice(1), { program: "right-release qa policy" }));
+  if (args[0] === "runner") process.exit(runnerMain(args.slice(1), { program: "right-release qa runner" }));
   let stage = "", platform = process.platform === "win32" ? "win" : "mac", releaseId = "", configName = defaultReleaseConfigFile(), carryTo = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];