@rightkit/release 0.6.8 → 0.6.11

package/freshness-census.mjs

@@ -0,0 +1,257 @@
+// The freshness census of a direct (Linux) snapshot compile (item 7 row 7.19; GATE-CONTRACT "Returned evidence", `freshness`:
+// `{ unitsAtStart, fresh, notFresh, invalidationReasons }`, the census the measured-cache rule is judged from; E16: "the second
+// build's census shows reuse").
+//
+// Cargo keeps no invalidation reason on disk: a fingerprint file holds the current hash only. The reason exists only in Cargo's own
+// fingerprint log (`CARGO_LOG=cargo::core::compiler::fingerprint=info`: a `fingerprint dirty for <unit>` line, then `dirty: <reason>`),
+// the same source the RustRight broker reads for its receipt (rustright-broker job_service/cargo_evidence.rs; attested-runs.md).
+// The gate turns that log on for the cargo processes that compile a workspace, on THAT process only (never in the scan environment
+// the repository's own tests and scripts inherit), reads it from the process's standard error, and keeps the lines out of the output
+// unless the caller set CARGO_LOG itself (a caller's own CARGO_LOG is read the same way and left visible).
+//
+// Counts come from the target directory the way the broker takes them (rustright-policy cargo_freshness.rs): a unit is one directory
+// of a `.fingerprint`; a unit whose newest file is at or after the census start was rebuilt (`notFresh`, a new unit included), the
+// others were reused (`fresh`). Judging unexplained rebuilds belongs to item 11; this module only measures and records.
+import fs from "node:fs";
+import path from "node:path";
+
+/** The `CARGO_LOG` filter the gate sets for a compiling cargo process (the broker's FINGERPRINT_LOG_FILTER). */
+export const FINGERPRINT_LOG_FILTER = "cargo::core::compiler::fingerprint=info";
+const FINGERPRINT_TARGET = "cargo::core::compiler::fingerprint";
+export const FRESHNESS_SOURCE = "cargo-fingerprint-log+fingerprint-mtime";
+/** Reasons kept in the receipt; the rest are counted. */
+export const REASONS_CAP = 200;
+/** Characters kept of one reason (Cargo prints it with `Debug`, paths and mtimes included). */
+export const REASON_TEXT_CAP = 512;
+/** Unit directories and files visited before the census is declared unavailable rather than partial. */
+export const CENSUS_ENTRY_CAP = 250_000;
+// A held partial line longer than this is not a log line.
+const PARTIAL_CAP = 64 * 1024;
+
+const stripAnsi = (text) => text.replace(/\u001b\[[^A-Za-z]*[A-Za-z]/g, "");
+const afterPrefix = (message, prefixes) => {
+  for (const prefix of prefixes) if (message.startsWith(prefix)) return message.slice(prefix.length);
+  return null;
+};
+
+/** `name version` and the target of the unit a dirty line names (the span carries `target="..."`; the message `<name> v<ver> (<src>)/<mode>/...`). */
+function unitOf(prefix, rest) {
+  let target = null;
+  const at = prefix.indexOf('target="');
+  if (at >= 0) {
+    const value = prefix.slice(at + 8);
+    const end = value.indexOf('"');
+    if (end >= 0) target = value.slice(0, end);
+  }
+  const head = rest.split("/")[0] ?? rest;
+  const unit = (head.split(" (")[0] ?? head).trim();
+  return { unit, target };
+}
+
+/** The reason's variant name (`FsStatusOutdated`, `RustflagsChanged`, ...): what a summary groups by. */
+const reasonKind = (reason) => {
+  const kind = reason.split(/[^\p{L}\p{N}_]/u)[0];
+  return kind ? kind : "unknown";
+};
+
+/** Reads Cargo's fingerprint log from a process's standard error; `strip` keeps its lines out of what the caller sees. */
+export class FingerprintLog {
+  constructor({ strip = false } = {}) {
+    this.strip = strip;
+    this.partial = "";
+    this.current = null;
+    this.dirtyUnits = 0;
+    this.reasons = [];
+    this.truncated = 0;
+  }
+
+  /** One chunk of standard error in; what the caller sees out. Without stripping that is the chunk itself. */
+  feed(chunk) {
+    this.partial += String(chunk);
+    let shown = "";
+    for (let at = this.partial.indexOf("\n"); at >= 0; at = this.partial.indexOf("\n")) {
+      const line = this.partial.slice(0, at + 1);
+      this.partial = this.partial.slice(at + 1);
+      const isLog = this.#line(line);
+      if (!isLog || !this.strip) shown += line;
+    }
+    if (this.partial.length > PARTIAL_CAP) {
+      const rest = this.partial;
+      this.partial = "";
+      if (this.strip) shown += rest;
+    }
+    return this.strip ? shown : String(chunk);
+  }
+
+  /** The end of the stream: a held partial line is judged and, when stripping and it is not a log line, returned. */
+  finish() {
+    const rest = this.partial;
+    this.partial = "";
+    if (rest === "" || this.#line(rest) || !this.strip) return "";
+    return rest;
+  }
+
+  #line(raw) {
+    const line = stripAnsi(raw.replace(/\s+$/, ""));
+    const at = line.indexOf(FINGERPRINT_TARGET);
+    if (at < 0) return false;
+    const message = line.slice(at + FINGERPRINT_TARGET.length).replace(/^:+/, "").trim();
+    const unitLine = afterPrefix(message, ["fingerprint dirty for ", "fingerprint error for "]);
+    if (unitLine !== null) {
+      this.dirtyUnits += 1;
+      this.current = unitOf(line.slice(0, at), unitLine);
+      return true;
+    }
+    const reason = afterPrefix(message, ["dirty:", "err:"]);
+    if (reason !== null) this.#record(reason.trim());
+    return true;
+  }
+
+  #record(reason) {
+    if (this.reasons.length >= REASONS_CAP) { this.truncated += 1; return; }
+    const { unit, target } = this.current ?? { unit: "unknown", target: null };
+    const chars = Array.from(reason);
+    const text = chars.length > REASON_TEXT_CAP ? `${chars.slice(0, REASON_TEXT_CAP).join("")}…` : reason;
+    this.reasons.push({ unit, target, kind: reasonKind(reason), reason: text });
+  }
+
+  /** What another log's reading adds to this one (the census keeps one aggregate over every compiling process). */
+  merge(other) {
+    this.dirtyUnits += other.dirtyUnits;
+    this.truncated += other.truncated;
+    for (const reason of other.reasons) {
+      if (this.reasons.length >= REASONS_CAP) this.truncated += 1;
+      else this.reasons.push(reason);
+    }
+  }
+}
+
+// Cargo subcommands that compile a workspace's units (the wrapper's COMPILE set without metadata and package, which the census
+// does not count). `--` ends cargo's own arguments; `--color` and `--explain` take a value.
+const COMPILING = new Set(["build", "b", "check", "c", "test", "t", "bench", "run", "r", "doc", "d", "rustc", "rustdoc", "clippy"]);
+const GLOBAL_VALUE = new Set(["--color", "--explain"]);
+
+/** True when `command args` is a cargo process that compiles a workspace's units (its fingerprint log is the census's). */
+export function compilesWorkspace(command, args) {
+  if (path.basename(String(command)).replace(/\.exe$/i, "") !== "cargo") return false;
+  const words = Array.isArray(args) ? args : [];
+  let i = typeof words[0] === "string" && words[0].startsWith("+") ? 1 : 0;
+  for (; i < words.length; i += 1) {
+    const w = String(words[i]);
+    if (w === "--") return false;
+    if (GLOBAL_VALUE.has(w)) { i += 1; continue; }
+    if (w.startsWith("-")) continue;
+    return COMPILING.has(w);
+  }
+  return false;
+}
+
+// Directories never searched for `.fingerprint`s: rustdoc output and packaging verification are not a profile's units.
+const NOT_PROFILES = new Set(["doc", "package", "tmp", "incremental"]);
+
+/** The `.fingerprint` directories of one target directory: `<target>/<profile>/.fingerprint` and `<target>/<triple>/<profile>/.fingerprint`. */
+export function fingerprintDirectories(targetDir, fsApi = fs) {
+  const found = [];
+  const subdirs = (dir) => {
+    try { return fsApi.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !NOT_PROFILES.has(e.name)).map((e) => e.name); } catch { return []; }
+  };
+  const has = (dir) => { try { return fsApi.statSync(dir).isDirectory(); } catch { return false; } };
+  for (const first of subdirs(targetDir)) {
+    const direct = path.join(targetDir, first, ".fingerprint");
+    if (has(direct)) { found.push(direct); continue; }
+    for (const second of subdirs(path.join(targetDir, first))) {
+      const nested = path.join(targetDir, first, second, ".fingerprint");
+      if (has(nested)) found.push(nested);
+    }
+  }
+  return found;
+}
+
+/**
+ * Walks every fingerprint directory of `targetDirs`. `withTimes: false` only counts units; `withTimes: true` also takes each unit's
+ * newest file time. `capped` is set when more than `cap` entries (units and files) were visited.
+ */
+export function walkFingerprints(targetDirs, { withTimes, cap = CENSUS_ENTRY_CAP, fsApi = fs } = {}) {
+  const units = new Map();
+  let visited = 0;
+  for (const targetDir of targetDirs) {
+    for (const fpDir of fingerprintDirectories(targetDir, fsApi)) {
+      let names;
+      try { names = fsApi.readdirSync(fpDir); } catch { continue; }
+      for (const name of names) {
+        visited += 1;
+        if (visited > cap) return { units, capped: true };
+        const unitDir = path.join(fpDir, name);
+        if (!withTimes) { units.set(unitDir, 0); continue; }
+        let newest = 0;
+        try {
+          const own = fsApi.statSync(unitDir);
+          newest = own.mtimeMs;
+          if (own.isDirectory()) {
+            for (const file of fsApi.readdirSync(unitDir)) {
+              visited += 1;
+              if (visited > cap) return { units, capped: true };
+              try { newest = Math.max(newest, fsApi.statSync(path.join(unitDir, file)).mtimeMs); } catch { /* vanished: ignore */ }
+            }
+          }
+        } catch { /* vanished: counted with the time it had */ }
+        units.set(unitDir, newest);
+      }
+    }
+  }
+  return { units, capped: false };
+}
+
+/**
+ * One census for one stage of a direct compile: `start()` before the scans, `wrapSpawn(spawn)` around the scan runner's spawner
+ * (it turns the fingerprint log on for the compiling cargo processes only), `finish()` after them.
+ */
+export function createFreshnessCensus({ targetDirs, now = Date.now, fsApi = fs, cap = CENSUS_ENTRY_CAP } = {}) {
+  const dirs = [...new Set(Object.values(targetDirs ?? {}).filter((d) => typeof d === "string" && d))];
+  const log = new FingerprintLog({ strip: false });
+  let since = null; let atStart = null; let processes = 0; let outputCut = false;
+  return {
+    start() { since = now(); atStart = walkFingerprints(dirs, { withTimes: false, cap, fsApi }); },
+    wrapSpawn(spawn) {
+      return async (command, args, options = {}) => {
+        if (!compilesWorkspace(command, args)) return spawn(command, args, options);
+        const env = options.env ?? process.env;
+        // A caller's own CARGO_LOG stands and stays visible; the gate's own is kept out of the output.
+        const ours = !Object.keys(env).some((k) => k.toUpperCase() === "CARGO_LOG");
+        const result = await spawn(command, args, ours ? { ...options, env: { ...env, CARGO_LOG: FINGERPRINT_LOG_FILTER } } : options);
+        processes += 1;
+        if (!result || typeof result.stderr !== "string") return result;
+        if (result.truncated) outputCut = true;
+        const reading = new FingerprintLog({ strip: ours });
+        const shown = reading.feed(result.stderr) + reading.finish();
+        log.merge(reading);
+        return { ...result, stderr: shown };
+      };
+    },
+    finish() {
+      const base = { source: FRESHNESS_SOURCE, cargoProcesses: processes, dirtyUnits: log.dirtyUnits, truncated: log.truncated, ...(outputCut ? { outputCut: true } : {}) };
+      const unavailable = (reason) => ({ unitsAtStart: 0, fresh: 0, notFresh: 0, invalidationReasons: log.reasons, available: false, reason, ...base });
+      if (since === null || atStart === null) return unavailable("fingerprint-census-not-started");
+      const end = walkFingerprints(dirs, { withTimes: true, cap, fsApi });
+      if (atStart.capped || end.capped) return unavailable("fingerprint-census-entry-cap-exceeded");
+      if (end.units.size === 0) return unavailable("no-fingerprint-units-found");
+      let notFresh = 0;
+      for (const newest of end.units.values()) if (newest >= since) notFresh += 1;
+      return { unitsAtStart: atStart.units.size, fresh: end.units.size - notFresh, notFresh, invalidationReasons: log.reasons, available: true, ...base };
+    },
+  };
+}
+
+const isCount = (n) => Number.isInteger(n) && n >= 0;
+
+/** What is wrong with a `freshness` object (an empty list: it is the census the contract names, well formed). */
+export function validateFreshness(freshness) {
+  const problems = [];
+  if (!freshness || typeof freshness !== "object" || Array.isArray(freshness)) return ["freshness is absent"];
+  for (const key of ["unitsAtStart", "fresh", "notFresh"]) if (!isCount(freshness[key])) problems.push(`freshness.${key} is not a count`);
+  if (!Array.isArray(freshness.invalidationReasons)) problems.push("freshness.invalidationReasons is not a list");
+  else freshness.invalidationReasons.forEach((r, i) => { if (!r || typeof r.unit !== "string" || typeof r.kind !== "string" || typeof r.reason !== "string") problems.push(`freshness.invalidationReasons[${i}] has no unit, kind and reason`); });
+  if (freshness.available !== undefined && typeof freshness.available !== "boolean") problems.push("freshness.available is not a boolean");
+  if (freshness.available === false && typeof freshness.reason !== "string") problems.push("an unavailable census names no reason");
+  return problems;
+}

package/gate-executor.mjs

@@ -2,16 +2,28 @@
 //   broker  - `rustright` is on PATH, or the first `cargo` is the broker's managed shim: every cargo call goes through the broker.
 //   refuse  - a broker-managed machine (Mac/Dell markers, broker socket, managed agent-bin) whose broker cannot be reached from here:
 //             the gate never compiles around it.
-//   direct  - any other host (a throwaway cloud container, a CI runner): cargo runs directly, through the same gates and stages.
+//   direct  - every Linux host (WSL2, VM, cloud, CI, Linux hosted on the Dell) always, and any unmanaged Mac or Windows host: cargo
+//             runs directly, through the same gates and stages.
 import { brokerManagedHost, managedCargoShimOnPath } from "./cargo-contract.mjs";
+import { directCargoPath, directPlatform } from "./managed-cargo.mjs";
+
+export { directCargoPath };
 
 export const EXECUTOR_KINDS = Object.freeze(["broker", "refuse", "direct"]);
 
 /**
  * @param {{ env?: object, platform?: string, exists?: (p: string) => boolean, which: (cmd: string) => string[], readFile: (p: string) => string }} o
- * @returns {{ kind: "broker" | "refuse" | "direct", cargo: string[] | null, problem?: string }}
+ * @returns {{ kind: "broker" | "refuse" | "direct", cargo: string[] | null, problem?: string, env?: { PATH: string }, note?: string }}
  */
 export function resolveExecutor({ env = process.env, platform = process.platform, exists, which, readFile }) {
+  // Every Linux (and any other non-Mac, non-Windows) execution host runs direct, whatever is on PATH or in the environment: WSL2, a VM,
+  // a cloud or CI runner, or Linux hosted on the Dell (GATE-CONTRACT §1 "One entry"; joint plan step 4). Only Adrian's Mac and Windows
+  // hosts use the broker.
+  // `cargo` there must be a real toolchain: RustRight shim directories are taken off the PATH the gate hands its children (`env`).
+  if (directPlatform(platform)) {
+    const direct = directCargoPath({ env, exists });
+    return { kind: "direct", cargo: ["cargo"], ...(direct.dropped.length ? { env: { PATH: direct.path }, note: `RustRight shims taken off PATH for direct cargo: ${direct.dropped.join(", ")}` } : {}), ...(direct.cargo ? {} : { note: `no direct cargo on PATH${direct.dropped.length ? ` (RustRight shims skipped: ${direct.dropped.join(", ")})` : ""}; cargo scans fail as a missing tool` }) };
+  }
   if (which("rustright").length) return { kind: "broker", cargo: ["rustright", "cargo"] };
   const first = which("cargo")[0];
   if (first) {

package/gate-stages.mjs

@@ -15,9 +15,62 @@ import path from "node:path";
 export const STAGES = Object.freeze(["check", "compile", "package", "qualify", "release"]);
 export const RECEIPT_SCHEMA = "rightkit.gate-receipt/1";
 export const RUN_ENV = "RK_GATE_RUN";
+/** Set beside RUN_ENV for a run that carries a source split: the checkout whose git directory holds the run file. */
+export const CHECKOUT_ENV = "RK_GATE_CHECKOUT";
 
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
 
+/**
+ * Where every stage the gate runs reads its source from (docs/GATE-CONTRACT.md "Commit-only build": every stage, `--to dev` and
+ * `--to test` included, builds a commit; uncommitted changes never enter a build). One row per stage name the gate dispatches:
+ * the STAGES, `dev` and `test`, `stage` (the hand-off to the publisher) and each STAGES entry again as a RightKit unit stage
+ * (`--to <stage> --unit <selector>`). `compiles` and `packages` say whether the stage starts a compiler or seals bytes.
+ *   source "snapshot": the gate-owned snapshot of the selected commit (`wired: false` names a stage whose snapshot route is
+ *     refused today, `blocker` saying why; it still never reads the checkout).
+ *   source "sealed" or "publisher", with `basis`: the stage compiles nothing from source (it acts on bytes an earlier stage
+ *     sealed, or runs only in the trusted publisher on hosted CI with its normal checkout, docs/GATE-CONTRACT.md).
+ *   source "checkout", with `gap`: a known breach, listed so it cannot grow; stageSourceProblems ignores it, stageSourceGaps names it.
+ * door-stages.test.mjs fails on a stage with no row, on a compiling or packaging row that has none of these, and on a gap that is
+ * not in its expected list.
+ */
+export const STAGE_SOURCES = Object.freeze({
+  check: { compiles: false, packages: false, source: "snapshot" },
+  compile: { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: the clean-HEAD checkout route until the cutover" },
+  // Wired in code (row 7.04: build-release.mjs, release.mjs, cli/right-release.mjs, release-source-identity.mjs): right-release builds and seals the selected commit from the snapshot. `wired` becomes true when door-package.test.mjs passes on L and on M and D (dev broker).
+  package: { compiles: true, packages: true, source: "snapshot", wired: false, blocker: "wired in code (rows 7.04 and 7.04c: release-artifact-path.mjs binds each Cargo manifest's target, one resolver reads every declared artifact path); awaiting 7.04c green on L, M and D: the dev-broker rows need the snapshot carrier (rows 7.20 to 7.24) and RustRight's item-4 dev pins" },
+  // Narrowed by decision 2 (7.06 correction): qualification rebuilds nothing, but its source reads (config, QA plan, test code) go through the split.
+  qualify: { compiles: false, packages: false, source: "snapshot", wired: false, blocker: "qa --stage installed takes its identity from the split (release-qa-command.mjs, row 7.04); awaiting its tests on every host" },
+  release: { compiles: false, packages: false, source: "publisher", basis: "--to release runs only in the trusted publisher on hosted CI with its normal checkout (docs/GATE-CONTRACT.md), and only uploads sealed bytes" },
+  dev: { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: the checkout route (check --worktree) until the cutover" },
+  test: { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: the checkout route (check --worktree) until the cutover" },
+  stage: { compiles: false, packages: false, source: "sealed", basis: "stage packs the sealed directory and its receipt into the publisher's draft release; it compiles nothing" },
+  // Row 7.06a: a unit stage builds the selected commit's snapshot (Linux now; Mac and Dell at the cutover commit, until which they take
+  // the clean-HEAD checkout route, decision 2 "Interim").
+  "unit:check": { compiles: false, packages: false, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
+  "unit:compile": { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
+  "unit:package": { compiles: true, packages: true, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
+  "unit:qualify": { compiles: false, packages: false, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
+  "unit:release": { compiles: false, packages: false, source: "publisher", basis: "a unit release is dispatched to the trusted publisher (releaseUnit); it compiles nothing here" },
+});
+
+/** Rows of `table` that compile or package without a snapshot source, a stated exclusion basis or a registered gap. */
+export function stageSourceProblems(table = STAGE_SOURCES) {
+  const out = [];
+  for (const [stage, row] of Object.entries(table)) {
+    if (!row.compiles && !row.packages) continue;
+    if (row.source === "snapshot") continue;
+    if (typeof row.basis === "string" && row.basis && ["sealed", "publisher"].includes(row.source)) continue;
+    if (row.source === "checkout" && typeof row.gap === "string" && row.gap) continue;
+    out.push({ stage, problem: `${stage} compiles or packages and its source is ${JSON.stringify(row.source)} with no snapshot source, exclusion basis or registered gap` });
+  }
+  return out;
+}
+
+/** The registered breaches in `table`: stages that compile or package from the checkout. */
+export function stageSourceGaps(table = STAGE_SOURCES) {
+  return Object.entries(table).filter(([, row]) => row.source === "checkout" && (row.compiles || row.packages)).map(([stage]) => stage);
+}
+
 /** The stages a run to `target` covers, in order; null when `target` is not a stage. */
 export function stagesTo(target) {
   const i = STAGES.indexOf(target);
@@ -29,14 +82,18 @@ export function gateStateDir(commonDir) {
   return path.join(commonDir, "rightkit-gate");
 }
 
-/** Starts a door run: writes the run file and returns { nonce, file, env }. The caller removes it with endRun. */
-export function startRun({ commonDir, commit, tree, stage, pid = process.pid, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
+/**
+ * Starts a door run: writes the run file and returns { nonce, file, env }. The caller removes it with endRun. `source` is the
+ * commit-only build's source split (source-split.mjs): { checkout, snapshot, commit, tree, appDir }, written into the run so a
+ * right-release child can learn which snapshot it may read; its env then names the checkout the run file lives under.
+ */
+export function startRun({ commonDir, commit, tree, stage, source, pid = process.pid, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
   const nonce = randomBytes(16).toString("hex");
   const dir = path.join(gateStateDir(commonDir), "runs");
   mkdir(dir, { recursive: true });
   const file = path.join(dir, `${nonce}.json`);
-  write(file, `${JSON.stringify({ pid, commit, tree, stage, startedAt: new Date().toISOString() })}\n`);
-  return { nonce, file, env: { [RUN_ENV]: nonce } };
+  write(file, `${JSON.stringify({ pid, commit, tree, stage, ...(source ? { source } : {}), startedAt: new Date().toISOString() })}\n`);
+  return { nonce, file, env: { [RUN_ENV]: nonce, ...(source ? { [CHECKOUT_ENV]: source.checkout } : {}) } };
 }
 
 export function endRun(run, rm = fs.rmSync) {
@@ -48,26 +105,45 @@ export function endRun(run, rm = fs.rmSync) {
  * whose pid is gone, or that names another commit, is no run.
  */
 export function requireDoorRun({ env = process.env, commonDir, commit, readFile = (f) => fs.readFileSync(f, "utf8"), alive = pidAlive, command = "this command" }) {
-  const nonce = env[RUN_ENV];
   const refusal = `${command} runs only through the one door: rightkit-gate --to <check|compile|package|qualify|release> (it runs class A first, then every stage in order)`;
-  if (!nonce || !/^[0-9a-f]{32}$/.test(nonce)) return refusal;
-  let run;
-  try { run = JSON.parse(readFile(path.join(gateStateDir(commonDir), "runs", `${nonce}.json`))); } catch { return `${refusal}; RK_GATE_RUN names no live door run`; }
-  if (!alive(run.pid)) return `${refusal}; the door run that launched it has ended`;
-  if (commit && run.commit !== commit) return `${refusal}; the door run is for ${String(run.commit).slice(0, 12)}, HEAD is ${commit.slice(0, 12)}`;
+  const found = readDoorRun({ env, commonDir, readFile, alive });
+  if (found.problem === "none") return refusal;
+  if (found.problem === "unread") return `${refusal}; RK_GATE_RUN names no live door run`;
+  if (found.problem === "ended") return `${refusal}; the door run that launched it has ended`;
+  if (commit && found.run.commit !== commit) return `${refusal}; the door run is for ${String(found.run.commit).slice(0, 12)}, HEAD is ${commit.slice(0, 12)}`;
   return null;
 }
 
+/** The live door run RK_GATE_RUN names: { run } or { problem: "none" | "unread" | "ended" }. */
+export function readDoorRun({ env = process.env, commonDir, readFile = (f) => fs.readFileSync(f, "utf8"), alive = pidAlive }) {
+  const nonce = env[RUN_ENV];
+  if (!nonce || !/^[0-9a-f]{32}$/.test(nonce)) return { problem: "none" };
+  let run;
+  try { run = JSON.parse(readFile(path.join(gateStateDir(commonDir), "runs", `${nonce}.json`))); } catch { return { problem: "unread" }; }
+  if (!alive(run.pid)) return { problem: "ended" };
+  return { run };
+}
+
 function pidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
 }
 
-/** Reads the receipt for `commit`, or a fresh one bound to it. */
-export function readReceipt({ commonDir, commit, readFile = (f) => fs.readFileSync(f, "utf8") }) {
+/**
+ * The receipt file for `commit` and the app it was run for: a repository with one app at its root keeps `<commit>.json`; an app in a
+ * nested directory (CodeRight's apps/coderight-tauri and apps/coderight-ios, CutRight's apps/cutright, HeardRight's tauri-app-next)
+ * gets `<commit>--<dir, _ as _u, / as __>.json`, so two apps of one repository never share or overwrite a receipt (Astra, 2026-10-26).
+ */
+export function receiptKey(commit, app = ".") {
+  // Reversible: "_" becomes "_u" before "/" becomes "__", so apps/a__b (apps__a_u_ub) and apps/a/b (apps__a__b) never share a key.
+  return app && app !== "." ? `${commit}--${app.replaceAll("_", "_u").replaceAll("/", "__")}` : commit;
+}
+
+/** Reads the receipt for `commit` (and `app`), or null. */
+export function readReceipt({ commonDir, commit, app = ".", readFile = (f) => fs.readFileSync(f, "utf8") }) {
   try {
-    const r = JSON.parse(readFile(path.join(gateStateDir(commonDir), "receipts", `${commit}.json`)));
-    if (r.schema === RECEIPT_SCHEMA && r.commit === commit) return r;
+    const r = JSON.parse(readFile(path.join(gateStateDir(commonDir), "receipts", `${receiptKey(commit, app)}.json`)));
+    if (r.schema === RECEIPT_SCHEMA && r.commit === commit && (r.app ?? ".") === (app ?? ".")) return r;
   } catch { /* none yet */ }
   return null;
 }
@@ -75,7 +151,7 @@ export function readReceipt({ commonDir, commit, readFile = (f) => fs.readFileSy
 export function writeReceipt({ commonDir, receipt, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
   const dir = path.join(gateStateDir(commonDir), "receipts");
   mkdir(dir, { recursive: true });
-  write(path.join(dir, `${receipt.commit}.json`), `${JSON.stringify(receipt, null, 2)}\n`);
+  write(path.join(dir, `${receiptKey(receipt.commit, receipt.app ?? ".")}.json`), `${JSON.stringify(receipt, null, 2)}\n`);
 }
 
 /**

package/heavy-command.mjs

@@ -3,6 +3,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, r
 import os from "node:os";
 import path from "node:path";
 import { spawn, spawnSync } from "./background-process.mjs";
+import { spawnUnderOwnership } from "./build-ownership.mjs";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 
@@ -208,7 +209,7 @@ export async function watchOwnedProcessTree(
 
 function spawnOwnerWatcher(details) {
   const payload = Buffer.from(JSON.stringify(details)).toString("base64url");
-  const watcher = spawn(process.execPath, [SELF, "--watch-owner-base64", payload], {
+  const watcher = spawnUnderOwnership(spawn, process.execPath, [SELF, "--watch-owner-base64", payload], {
     detached: true, env: process.env, stdio: "ignore", windowsHide: true,
   });
   watcher.once("error", () => {
@@ -335,7 +336,7 @@ export async function runHeavyCommand(args, { env = process.env } = {}) {
 
 function spawnAttached(command, args, env, slot) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { cwd: process.cwd(), env, stdio: "inherit", windowsHide: true, detached: heavyChildDetached({ slot }) });
+    const child = spawnUnderOwnership(spawn, command, args, { cwd: process.cwd(), env, stdio: "inherit", windowsHide: true, detached: heavyChildDetached({ slot }) });
     try {
       if (child.pid && slot) slot.trackChild(child.pid, command);
     } catch (error) {

package/hook-retirement.mjs

@@ -0,0 +1,65 @@
+// Retirement of the git hooks RightKit used to write (docs/GATE-CONTRACT.md: "Commit and push run no gate and no local hook
+// checks"). `rightkit-gate install-hook` and `right-release hooks install` no longer write a pre-push gate, the forwarders
+// that chained .git/hooks beside it, or the advisory ownership pre-commit step; they remove the ones an earlier release wrote.
+//
+// A file is ours only by its own text, never by its name or its place:
+//   - the gate hook      : line 2 is the header every published hook carries ("# Mandatory local [check and] gate before every
+//                          push (rightkit-gate install-hook). Never bypass with --no-verify.");
+//   - a forwarder        : line 2 is the forwarder header naming the hook it forwards, and that hook is the file's own name
+//                          (pre-commit.rightkit-foreign may forward `pre-commit` or itself);
+//   - the ownership step : the HOOK_MARKER sits in the first three lines.
+// Anything else is a foreign hook and is never read for change, moved, rewritten or deleted. A symbolic link is never ours.
+// One exception to "never moved": the foreign pre-commit the ownership step preserved as pre-commit.rightkit-foreign goes back to
+// pre-commit when the ownership step that displaced it is removed.
+import path from "node:path";
+
+export const HOOK_MARKER = "rightkit-ownership-precommit v1";
+export const FOREIGN_PRE_COMMIT = "pre-commit.rightkit-foreign";
+
+const GATE_HEADER = /^# Mandatory local (?:check and )?gate before every push \(rightkit-gate install-hook\)\. Never bypass with --no-verify\.$/;
+const FORWARDER_HEADER = /^# rightkit-gate install-hook: core\.hooksPath=\.githooks hides \.git\/hooks, so run this repository's own (\S+) hook from there\.$/;
+
+const lines = (text) => String(text).replace(/\r\n/g, "\n").split("\n");
+
+/** What a hook file is, by its text and its name: "gate", "forwarder", "ownership" or null (foreign). `scripts` is false for a directory the gate never wrote into. */
+export function hookKind(name, text, { scripts = true } = {}) {
+  const [shebang, second = "", third = ""] = lines(text);
+  if (shebang !== "#!/bin/sh") return null;
+  if ([second, third].some((line) => line.startsWith(`# ${HOOK_MARKER}`))) return "ownership";
+  if (!scripts) return null;
+  if (name === "pre-push" && GATE_HEADER.test(second)) return "gate";
+  const forwarded = FORWARDER_HEADER.exec(second)?.[1];
+  if (forwarded && (forwarded === name || (name === FOREIGN_PRE_COMMIT && forwarded === "pre-commit"))) return "forwarder";
+  return null;
+}
+
+/**
+ * Remove the hooks RightKit wrote from `dir`. `ops` = { readdir, readFile, lstat, unlink, rename, rmdir } (fs-shaped). Returns
+ * { found, removed: [name], restored: [name], remaining: [name] }: `found` is false when `dir` cannot be listed, `remaining` is every
+ * file left in it (foreign hooks), and an emptied directory is removed (`removedDir`).
+ */
+export function retireHooksIn(dir, ops, { scripts = true, removeEmptyDir = scripts } = {}) {
+  let names;
+  try { names = [...ops.readdir(dir)].map(String).sort(); } catch { return { found: false, removed: [], restored: [], remaining: [], removedDir: false }; }
+  const removed = []; const restored = []; const kinds = new Map();
+  for (const name of names) {
+    const file = path.join(dir, name);
+    let kind = null;
+    try {
+      const stat = ops.lstat(file);
+      if (stat.isFile() && !stat.isSymbolicLink()) kind = hookKind(name, ops.readFile(file), { scripts });
+    } catch { kind = null; }
+    kinds.set(name, kind);
+    if (!kind) continue;
+    try { ops.unlink(file); removed.push(name); } catch { kinds.set(name, null); }
+  }
+  // The ownership step displaced a foreign pre-commit into pre-commit.rightkit-foreign: it goes back where git runs it.
+  if (kinds.get("pre-commit") === "ownership" && removed.includes("pre-commit") && names.includes(FOREIGN_PRE_COMMIT) && kinds.get(FOREIGN_PRE_COMMIT) === null) {
+    try { ops.rename(path.join(dir, FOREIGN_PRE_COMMIT), path.join(dir, "pre-commit")); restored.push("pre-commit"); } catch { /* left where it is, still foreign */ }
+  }
+  let left = names.filter((name) => !removed.includes(name));
+  if (restored.length) left = [...left.filter((name) => name !== FOREIGN_PRE_COMMIT), "pre-commit"].sort();
+  let removedDir = false;
+  if (removeEmptyDir && removed.length && !left.length) { try { ops.rmdir(dir); removedDir = true; } catch { /* not empty after all */ } }
+  return { found: true, removed, restored, remaining: left, removedDir };
+}

package/init-command.mjs

@@ -253,7 +253,7 @@ export function initTemplate(root, options) {
 
 /** What a person does after init: the steps no command can do for them, in order. */
 export const NEXT_STEPS = Object.freeze([
-  "pnpm install                      (installs the pinned packages and, through `prepare`, the pre-push hook)",
+  "pnpm install                      (installs the pinned packages and, through `prepare`, the agent hook; no git hook)",
   "right-release doctor              (the build's own checks for this app, as rows)",
   "set the app's public legal host in legal-snapshot.config.json, replace legal/PRODUCT_SCHEDULE.md and legal/PRIVACY_NOTICE.md with reviewed text, then `pnpm exec legal-snapshot`",
   "register the repository on each host: add it to packages/release/ownership-repositories.json in RightKit (and its byte copy under packages/build-control-policy), then run `right-release ownership trust-refresh` on the Mac and the Dell (a person with administrator rights; an agent cannot)",

package/install-app.mjs

@@ -12,6 +12,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
 const SIGTERM_WAIT_MS = 15_000;
 const POLL_MS = 250;
 
@@ -632,12 +633,20 @@ export async function installApp(opts, deps = {}) {
     swap = null;
     event("replaced", { installed, previous: null, swap: swapMode });
 
+    // A dev install from a build folder (--app) leaves that product registered with Launch Services, which then resolves the bundle
+    // id to it instead of the installed copy (rightkit#1225): unregister it so only the installed copy is known.
+    if (opts.app && path.resolve(sourceApp) !== path.resolve(installed)) {
+      try { await run(LSREGISTER, ["-u", sourceApp]); event("unregistered", { path: sourceApp }); }
+      catch (error) { event("unregister-failed", { path: sourceApp, reason: errText(error) }); }
+    }
+
     // Relaunch hidden and in the background only.
     const relaunch = opts.relaunch === null ? wasRunning : opts.relaunch;
     if (relaunch) {
       failedStage = "relaunch";
-      await run("/usr/bin/open", ["-g", "-j", "-b", bundleId]);
-      event("relaunched", { bundleId });
+      // By the installed path, never by bundle id: Launch Services may resolve the id to another registered copy (rightkit#1225).
+      await run("/usr/bin/open", ["-g", "-j", installed]);
+      event("relaunched", { bundleId, installed });
     }
     const result = { ok: true, app: appName, installed, bundleId, teamId: newTeam, previous: null, swap: swapMode, relaunched: relaunch, ...(dev ? { dev: true } : {}) };
     event("done", result);