forgedock 1.29.1 → 1.31.0

package/bin/lean/decompose.mjs

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Decomposition gate (#4396): a builder `split-required` block is admitted only when its sub-issues touch disjoint
+ * areas (each declares `paths`) or the block's `size` estimate exceeds the large-lane budget; otherwise the issue stays
+ * one lane with an ordered checklist. Also the batch report's decomposed vs single-lane $/parent line. Pure: no I/O.
+ */
+
+/** The large-lane size budget: a split of overlapping parts is admitted only above it. */
+export const SPLIT_MIN_FILES = 25;
+export const SPLIT_MIN_LINES = 1500;
+
+const norm = (p) => String(p).trim().replace(/^(\.?\/+)+/, "").replace(/\/+$/, "");
+const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+const count = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null);
+
+/** The block's `size` as {files, lines} (null fields when not a finite non-negative number), or null when absent. */
+function sizeOf(block) {
+  const s = block?.size;
+  if (!s || typeof s !== "object" || Array.isArray(s)) return null;
+  const files = count(s.files), lines = count(s.lines);
+  return files == null && lines == null ? null : { files, lines };
+}
+
+/**
+ * @param {object} block result.json `block` of kind split-required (sub-issues already checked for title and body)
+ * @returns {{ok:true, rationale:{independent:boolean, oversize:boolean, overlaps:Array<[number,number,string,string]>, missing:number[], size:?{files:?number, lines:?number}}} | {ok:false, problem:string}}
+ */
+export function splitGate(block) {
+  const subs = Array.isArray(block?.subissues) ? block.subissues : [];
+  // `paths` or the #4385 `files` (the files each sub-issue edits): either declares the area a part touches.
+  const declared = (s) => [...(Array.isArray(s?.paths) ? s.paths : []), ...(Array.isArray(s?.files) ? s.files : [])];
+  const paths = subs.map((s) => [...new Set(declared(s).filter((p) => typeof p === "string" && norm(p)).map(norm))]);
+  const missing = paths.flatMap((p, i) => (p.length ? [] : [i]));
+  const found = [];
+  for (let i = 0; i < paths.length; i++) {
+    for (let j = i + 1; j < paths.length; j++) {
+      for (const a of paths[i]) for (const b of paths[j]) if (overlaps(a, b)) found.push([i, j, a, b]);
+    }
+  }
+  const independent = subs.length > 0 && !missing.length && !found.length;
+  const size = sizeOf(block);
+  const oversize = !!size && ((size.files ?? 0) > SPLIT_MIN_FILES || (size.lines ?? 0) > SPLIT_MIN_LINES);
+  if (independent || oversize) return { ok: true, rationale: { independent, oversize, overlaps: found, missing, size } };
+  const why = [];
+  if (missing.length) why.push(`sub-issue(s) ${missing.join(", ")} declare no "paths" or "files"`);
+  if (found.length) why.push(`the parts overlap (${found.slice(0, 5).map(([i, j, a, b]) => `${i}:${a} ~ ${j}:${b}`).join("; ")})`);
+  why.push(size ? `the size estimate (${size.files ?? "?"} files, ${size.lines ?? "?"} lines) is within the ${SPLIT_MIN_FILES}-file / ${SPLIT_MIN_LINES}-line budget` : "the block has no \"size\" estimate");
+  return { ok: false, problem: `the split is not justified: ${why.join("; ")}. Split only when every sub-issue lists "paths" (or "files") disjoint from the others, or when "size" exceeds ${SPLIT_MIN_FILES} files or ${SPLIT_MIN_LINES} lines. Otherwise keep one lane: write the contract as an ordered checklist, one requirement or deliverable per item, each with its own validate command` };
+}
+
+/** One line for the FORGE:DECOMPOSED comment and the decision log. */
+export function rationaleLine(r) {
+  if (!r) return "";
+  const ov = r.overlaps?.length ? ` (overlaps ${r.overlaps.slice(0, 3).map(([i, j, a, b]) => `${i}:${a} ~ ${j}:${b}`).join("; ")})` : r.missing?.length ? ` (no paths: ${r.missing.join(", ")})` : "";
+  const sz = r.size ? `${r.size.files ?? "?"} files, ${r.size.lines ?? "?"} lines` : "no estimate";
+  return `independent: ${r.independent ? "yes" : "no"}${ov}; size: ${sz} vs budget ${SPLIT_MIN_FILES} files / ${SPLIT_MIN_LINES} lines -> oversize ${r.oversize ? "yes" : "no"}`;
+}
+
+/**
+ * Batch-report line: cost per decomposed parent (its row plus its sub-issue rows, recursively) vs per single-lane
+ * parent (a merged row that is no row's sub-issue). Null when no row decomposed.
+ */
+export function formatDecompositionSummary(rows) {
+  const list = (rows ?? []).filter((r) => r && Number.isSafeInteger(r.issue));
+  const subsOf = (r) => (r?.outcome === "decomposed" && Array.isArray(r.subissues) ? r.subissues.filter((n) => Number.isSafeInteger(n) && n !== r.issue) : []);
+  const byIssue = new Map(list.map((r) => [r.issue, r]));
+  const isSub = new Set(list.flatMap(subsOf));
+  const parents = list.filter((r) => subsOf(r).length && !isSub.has(r.issue));
+  if (!list.some((r) => subsOf(r).length)) return null;
+  let lanes = 0, outside = 0;
+  const total = (r, seen) => {
+    let c = Number(r.cost_usd) || 0;
+    for (const n of subsOf(r)) {
+      if (seen.has(n)) continue;
+      seen.add(n);
+      const s = byIssue.get(n);
+      if (!s) { outside++; continue; }
+      lanes++;
+      c += total(s, seen);
+    }
+    return c;
+  };
+  const dCost = parents.reduce((a, r) => a + total(r, new Set([r.issue])), 0);
+  const single = list.filter((r) => r.outcome === "merged" && !isSub.has(r.issue));
+  const sCost = single.reduce((a, r) => a + (Number(r.cost_usd) || 0), 0);
+  const per = (c, n) => `$${(n ? c / n : 0).toFixed(2)}/parent`;
+  return `decomposition: ${parents.length} decomposed parent${parents.length === 1 ? "" : "s"} ${per(dCost, parents.length)} (${lanes} sub-lane${lanes === 1 ? "" : "s"}${outside ? `, ${outside} outside this batch` : ""}); `
+    + (single.length ? `${single.length} single-lane ${per(sCost, single.length)}` : "single-lane none");
+}

package/bin/lean/decompose.test.mjs

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4396: decomposition gate (independence and size) and the batch report's decomposed vs single-lane $/parent line.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { splitGate, rationaleLine, formatDecompositionSummary, SPLIT_MIN_FILES, SPLIT_MIN_LINES } from "./decompose.mjs";
+import { classifyBlock } from "./lean.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+
+const sub = (paths) => ({ title: "t", body: "b", ...(paths ? { paths } : {}) });
+
+describe("splitGate (#4396)", () => {
+  it("admits parts with disjoint paths and records independent", () => {
+    const g = splitGate({ subissues: [sub(["src/a", "docs/a.md"]), sub(["./src/b/"]), sub(["src/ab"])] });
+    assert.equal(g.ok, true);
+    assert.deepEqual(g.rationale, { independent: true, oversize: false, overlaps: [], missing: [], size: null });
+  });
+
+  it("rejects overlapping parts (same file, or a file under another part's directory) within the size budget", () => {
+    for (const [a, b] of [["src/alerts", "src/alerts/routing.ts"], ["src/x.ts", "./src/x.ts"]]) {
+      const g = splitGate({ subissues: [sub([a]), sub([b])], size: { files: 3, lines: 200 } });
+      assert.equal(g.ok, false, `${a} ~ ${b}`);
+      assert.match(g.problem, /parts overlap/);
+      assert.match(g.problem, /ordered checklist/);
+      assert.match(g.problem, /within the 25-file \/ 1500-line budget/);
+    }
+  });
+
+  it("reads the #4385 per-sub-issue files as the declared area, alone or with paths", () => {
+    const f = (files, paths) => ({ title: "t", body: "b", files, ...(paths ? { paths } : {}) });
+    assert.equal(splitGate({ subissues: [f(["src/a.ts"]), f(["/src/b.ts"])] }).ok, true);
+    const g = splitGate({ subissues: [f(["src/a.ts"]), f(["src/b.ts"], ["src/a.ts"])] });
+    assert.equal(g.ok, false);
+    assert.match(g.problem, /0:src\/a\.ts ~ 1:src\/a\.ts/);
+  });
+
+  it("rejects a split whose parts declare no paths and that has no size estimate", () => {
+    const g = splitGate({ subissues: [sub(), sub(["src/b"])] });
+    assert.equal(g.ok, false);
+    assert.match(g.problem, /sub-issue\(s\) 0 declare no "paths"/);
+    assert.match(g.problem, /no "size" estimate/);
+  });
+
+  it("admits overlapping parts when the size estimate exceeds the budget (files or lines); ignores a non-numeric size", () => {
+    const parts = [sub(["src/a"]), sub(["src/a/x.ts"])];
+    assert.equal(splitGate({ subissues: parts, size: { files: SPLIT_MIN_FILES + 1 } }).rationale.oversize, true);
+    const g = splitGate({ subissues: parts, size: { lines: SPLIT_MIN_LINES + 1 } });
+    assert.deepEqual({ ok: g.ok, independent: g.rationale.independent, oversize: g.rationale.oversize }, { ok: true, independent: false, oversize: true });
+    assert.equal(splitGate({ subissues: parts, size: { files: SPLIT_MIN_FILES, lines: SPLIT_MIN_LINES } }).ok, false, "at the budget is not over it");
+    assert.equal(splitGate({ subissues: parts, size: { files: "99" } }).ok, false);
+  });
+
+  it("rationaleLine names independence, overlaps and size against the budget", () => {
+    const g = splitGate({ subissues: [sub(["src/a"]), sub(["src/a/x.ts"])], size: { files: 40, lines: 3000 } });
+    assert.equal(rationaleLine(g.rationale), "independent: no (overlaps 0:src/a ~ 1:src/a/x.ts); size: 40 files, 3000 lines vs budget 25 files / 1500 lines -> oversize yes");
+    assert.equal(rationaleLine(null), "");
+  });
+
+  it("classifyBlock turns an unjustified split into an untyped block and carries the rationale of an admitted one", () => {
+    const bad = classifyBlock({ block: { kind: "split-required", subissues: [sub(["src/a"]), sub(["src/a"])] } }, 7);
+    assert.equal(bad.kind, "untyped");
+    assert.match(bad.problem, /split is not justified/);
+    const ok = classifyBlock({ block: { kind: "split-required", subissues: [sub(["src/a"]), { ...sub(["src/b"]), depends_on: [0] }] } }, 7);
+    assert.equal(ok.kind, "split");
+    assert.equal(ok.rationale.independent, true);
+    assert.deepEqual(ok.subissues.map((s) => s.dependsOn), [[], [0]]);
+  });
+});
+
+describe("formatDecompositionSummary (#4396)", () => {
+  it("is null when no row decomposed", () => {
+    assert.equal(formatDecompositionSummary([{ issue: 1, outcome: "merged", cost_usd: 3 }]), null);
+    assert.equal(formatDecompositionSummary(undefined), null);
+    assert.equal(formatDecompositionSummary([{ issue: 1, outcome: "decomposed", subissues: [] }]), null);
+  });
+
+  it("sums a parent with its sub-lanes (recursively) and compares with merged single-lane parents", () => {
+    const rows = [
+      { issue: 1, outcome: "decomposed", cost_usd: 2, subissues: [11, 12, 13] },
+      { issue: 11, outcome: "merged", cost_usd: 4 },
+      { issue: 12, outcome: "decomposed", cost_usd: 1, subissues: [121] },
+      { issue: 121, outcome: "merged", cost_usd: 3 },
+      { issue: 2, outcome: "merged", cost_usd: 5 },
+      { issue: 3, outcome: "merged", cost_usd: 7 },
+      { issue: 4, outcome: "needs-human", cost_usd: 9 },
+    ];
+    assert.equal(formatDecompositionSummary(rows), "decomposition: 1 decomposed parent $10.00/parent (3 sub-lanes, 1 outside this batch); 2 single-lane $6.00/parent");
+  });
+
+  it("reports no single-lane parents as none and guards a cycle", () => {
+    const rows = [{ issue: 1, outcome: "decomposed", cost_usd: 1, subissues: [2] }, { issue: 2, outcome: "decomposed", cost_usd: 1, subissues: [1] }];
+    assert.match(formatDecompositionSummary([{ issue: 1, outcome: "decomposed", cost_usd: 2, subissues: [5] }]), /^decomposition: 1 decomposed parent \$2\.00\/parent \(0 sub-lanes, 1 outside this batch\); single-lane none$/);
+    assert.ok(formatDecompositionSummary(rows));
+  });
+
+  it("the batch row keeps the lane's subissues and decomposition, so the report links a parent to its sub-lanes", async () => {
+    const rationale = { independent: true, oversize: false, overlaps: [], missing: [], size: null };
+    const script = { 1: { terminalReason: "decomposed", cost_usd: 2, subissues: [8], decomposition: rationale }, 8: { terminalReason: "merged", cost_usd: 4 }, 2: { terminalReason: "merged", cost_usd: 1 } };
+    const rows = await orchestrate({ issues: [1, 2], parallel: 1, readBody: async () => "", runOne: async (n) => script[n] });
+    const r1 = rows.find((r) => r.issue === 1);
+    assert.deepEqual(r1.subissues, [8]);
+    assert.deepEqual(r1.decomposition, rationale);
+    assert.equal(formatDecompositionSummary(rows), "decomposition: 1 decomposed parent $6.00/parent (1 sub-lane); 1 single-lane $1.00/parent");
+  });
+});

package/bin/lean/depcache.mjs

@@ -80,7 +80,8 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     return { npm_config_store_dir: store("pnpm-store"), npm_config_cache: store("npm-cache"), UV_CACHE_DIR: store("uv-cache"), UV_LINK_MODE: "hardlink",
       POETRY_CACHE_DIR: store("poetry-cache"), PIP_CACHE_DIR: store("pip-cache"), POETRY_VIRTUALENVS_IN_PROJECT: "true" };
   }
-  const run = (cmd, args, cwd) => exec(cmd, args, { cwd, env: env(), timeoutMs: installTimeoutMs });
+  /** Install/repair command; `laneEnv` (the lane's toolchain env, #4347) sits under the store env, so store keys win. */
+  const run = (cmd, args, cwd, laneEnv) => exec(cmd, args, { cwd, env: laneEnv ? { ...laneEnv, ...env() } : env(), timeoutMs: installTimeoutMs });
   const runtime = async (cmd) => { try { return String(await exec(cmd, ["--version"], { timeoutMs: 30000 })).trim(); } catch { return "unknown"; } };
 
   /** Tracked package.json files (workspace members), relative; root only when git cannot list them. */
@@ -190,7 +191,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     }
   }
 
-  async function prepareOne(wt, keyRoot, d) {
+  async function prepareOne(wt, keyRoot, d, laneEnv) {
     const t0 = now();
     const done = (status, extra = {}) => ({ status, eco: d.eco, key: extra.key ?? null, ms: now() - t0, reason: extra.reason ?? null, ...(extra.published === undefined ? {} : { published: extra.published }) });
     if (d.skip) return done("skipped", { reason: d.skip });
@@ -209,7 +210,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
       const created = [];
       try {
         for (const t of man.trees ?? []) { created.push(t); linkTree(join(snap, t), join(wt, t), { from: man.prefix, to: wt, binDir: binDirFor(d) }); }
-        for (const [c, a] of cmds.repair ?? []) await run(c, a, wt);
+        for (const [c, a] of cmds.repair ?? []) await run(c, a, wt, laneEnv);
         try { fs.writeFileSync(join(snap, "last-used"), String(now())); } catch { /* best effort */ }
         return done("hit", { key });
       } catch (e) {
@@ -218,7 +219,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
       }
     };
     const install = async () => {
-      try { for (const [c, a] of cmds.install) await run(c, a, wt); } catch (e) {
+      try { for (const [c, a] of cmds.install) await run(c, a, wt, laneEnv); } catch (e) {
         rmTrees(wt, expected);
         return { failed: done("failed", { key, reason: `${e?.code === "ENOENT" ? "tool not found" : "install failed"}: ${msg(e)}` }) };
       }
@@ -240,8 +241,11 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     return ins.failed ?? done("miss-installed", { key, published: false, reason: "cache lock busy" });
   }
 
-  /** Materialize or build node_modules/.venv for `wt`; one result per detected ecosystem. Never throws. */
-  async function prepare({ wt, repoKey } = {}) {
+  /**
+   * Materialize or build node_modules/.venv for `wt`; one result per detected ecosystem. Never throws.
+   * `env` (#4347): the lane's toolchain env (PATH with the pinned pm shims) for install/repair; absent means the host PATH.
+   */
+  async function prepare({ wt, repoKey, env: laneEnv } = {}) {
     if (disabled()) return [{ status: "skipped", eco: null, key: null, ms: 0, reason: "FORGE_DEPCACHE=0" }];
     let found;
     try { found = detect(fs, wt); } catch (e) { return [{ status: "failed", eco: null, key: null, ms: 0, reason: msg(e) }]; }
@@ -249,7 +253,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     const keyRoot = join(root, safeSegment(repoKey ?? "repo"));
     const out = [];
     for (const d of found) {
-      try { out.push(await prepareOne(wt, keyRoot, d)); } catch (e) { out.push({ status: "failed", eco: d.eco, key: null, ms: 0, reason: msg(e) }); }
+      try { out.push(await prepareOne(wt, keyRoot, d, laneEnv && typeof laneEnv === "object" ? laneEnv : undefined)); } catch (e) { out.push({ status: "failed", eco: d.eco, key: null, ms: 0, reason: msg(e) }); }
     }
     return out;
   }

package/bin/lean/depcache.test.mjs

@@ -8,6 +8,7 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, lstatSync
 import { tmpDir } from "../tests/_tmp.mjs";
 import { join, dirname, relative } from "node:path";
 import { makeDepCache } from "./depcache.mjs";
+import { prepareToolchain } from "./toolchain.mjs";
 
 const scratch = () => tmpDir("fd-depcache-");
 const put = (p, text, mode) => { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, text, mode ? { mode } : undefined); };
@@ -81,6 +82,10 @@ function fakeExec({ failInstall = false, installDelayMs = 0 } = {}) {
       symlinkSync("../left-pad/cli.js", join(cwd, "node_modules/.bin/left-pad"));
       return "";
     }
+    if (cmd === "yarn") {
+      put(join(cwd, "node_modules/left-pad/index.js"), `// ${readFileSync(join(cwd, "yarn.lock"), "utf8").length}\n`);
+      return "";
+    }
     if (cmd === "uv" && args[0] === "venv") { put(join(cwd, ".venv/pyvenv.cfg"), "home = /usr/bin\nrelocatable = true\n"); return ""; }
     if (cmd === "uv" || cmd === "poetry") { venv(cwd, readFileSync(join(cwd, cmd === "uv" ? "uv.lock" : "poetry.lock"), "utf8")); return ""; }
     throw Object.assign(new Error(`spawn ${cmd} ENOENT`), { code: "ENOENT" });
@@ -296,3 +301,79 @@ describe("depcache (#4220): shared dependency installs keyed by lock hash", () =
     assert.ok(!existsSync(fresh));
   });
 });
+
+describe("depcache (#4347): installs and repairs run with the lane toolchain env", () => {
+  const PMS = new Set(["pnpm", "pnpx", "yarn", "npm", "npx"]);
+  /** A host with no global package manager: pm commands resolve only when PATH starts with the toolchain shim dir. */
+  const shimOnlyExec = (f, binDir) => {
+    const seen = [];
+    const exec = async (cmd, args, o = {}) => {
+      if (PMS.has(cmd)) {
+        seen.push({ cmd, args: [...args], env: o.env });
+        if (!String(o.env?.PATH ?? "").startsWith(binDir)) throw Object.assign(new Error(`spawn ${cmd} ENOENT`), { code: "ENOENT" });
+      }
+      return f.exec(cmd, args, o);
+    };
+    return { exec, seen };
+  };
+  /** The real toolchain step: corepack on the host PATH, no global pm; shims recorded, not written. */
+  const laneToolchain = async (wt, binDir) => {
+    const tc = await prepareToolchain({ dir: wt, binDir, basePath: "/host/bin", find: (n) => (n === "corepack" ? "/host/bin/corepack" : null),
+      writeShim: async () => {}, mkdirp: async () => {}, hostNode: () => "v22.1.0" });
+    assert.ok(tc.env, "a packageManager pin yields a toolchain env");
+    return tc.env;
+  };
+
+  it("#4347 a packageManager-pinned pnpm repo with no host pnpm installs and repairs through the lane toolchain env", async () => {
+    const base = scratch(), root = join(base, "cache"), binDir = join(base, "toolchain", "bin");
+    const f = fakeExec(), x = shimOnlyExec(f, binDir);
+    const cache = makeDepCache({ root, exec: x.exec, env: {}, pollMs: 5 });
+    const lane = (name) => { const wt = join(base, "wt", name); FIXTURES.pnpm(wt); put(join(wt, "package.json"), '{"name":"web","private":true,"packageManager":"pnpm@9.12.0"}'); return wt; };
+    const a = lane("a");
+    const env = await laneToolchain(a, binDir);
+    const [r1] = await cache.prepare({ wt: a, repoKey: "r", env });
+    assert.equal(r1.status, "miss-installed", r1.reason);
+    assert.ok(existsSync(join(a, "node_modules/lodash/index.js")));
+    const [r2] = await cache.prepare({ wt: lane("b"), repoKey: "r", env });
+    assert.equal(r2.status, "hit", r2.reason);
+    assert.deepEqual(x.seen.map((c) => [c.cmd, c.args.includes("--offline")]), [["pnpm", false], ["pnpm", true]], "install then repair");
+    for (const c of x.seen) {
+      assert.ok(c.env.PATH.startsWith(`${binDir}:`), "the shim dir leads PATH");
+      assert.equal(c.env.COREPACK_ENABLE_DOWNLOAD_PROMPT, "0");
+      assert.equal(c.env.npm_config_store_dir, join(root, "stores", "pnpm-store"), "the store env stays");
+    }
+    // Without the toolchain env (the toolchain step failed or wrote no shim) it is the host PATH, as before.
+    const [r3] = await makeDepCache({ root: join(base, "cache2"), exec: x.exec, env: {} }).prepare({ wt: lane("c"), repoKey: "r" });
+    assert.equal(r3.status, "failed");
+    assert.match(r3.reason, /tool not found: spawn pnpm ENOENT/);
+  });
+
+  it("#4347 a pinned yarn (node-modules linker) repo installs through the shim env", async () => {
+    const base = scratch(), binDir = join(base, "toolchain", "bin");
+    const x = shimOnlyExec(fakeExec(), binDir);
+    const wt = join(base, "wt", "y");
+    put(join(wt, "package.json"), '{"name":"app","packageManager":"yarn@4.5.0"}');
+    put(join(wt, "yarn.lock"), "__metadata:\n  version: 8\n");
+    put(join(wt, ".yarnrc.yml"), "nodeLinker: node-modules\n");
+    const env = await laneToolchain(wt, binDir);
+    const [r] = await makeDepCache({ root: join(base, "cache"), exec: x.exec, env: {} }).prepare({ wt, repoKey: "r", env });
+    assert.equal(r.status, "miss-installed", r.reason);
+    assert.deepEqual(x.seen.map((c) => [c.cmd, c.args]), [["yarn", ["install", "--immutable"]]]);
+    assert.ok(x.seen[0].env.PATH.startsWith(`${binDir}:`));
+  });
+
+  it("#4347 a plain npm repo without pins passes exactly the store env, as before; store keys win over the lane env", async () => {
+    const s = setup("npm");
+    const [r] = await s.cache.prepare({ wt: s.lane("plain"), repoKey: "r" });
+    assert.equal(r.status, "miss-installed", r.reason);
+    const inst = s.f.calls.filter((c) => c.cmd === "npm");
+    assert.equal(inst.length, 1);
+    const seen = [];
+    const cache = makeDepCache({ root: join(s.base, "cache2"), exec: async (cmd, args, o = {}) => { if (cmd === "npm") seen.push(o); return s.f.exec(cmd, args, o); }, env: {} });
+    await cache.prepare({ wt: s.lane("plain2"), repoKey: "r" });
+    assert.deepEqual(seen[0].env, cache.env(), "no lane env: only the store env");
+    await cache.prepare({ wt: s.lane("pinned"), repoKey: "r2", env: { PATH: "/shim:/host", npm_config_cache: "/lane/should-not-win" } });
+    assert.equal(seen[1].env.PATH, "/shim:/host");
+    assert.equal(seen[1].env.npm_config_cache, cache.env().npm_config_cache);
+  });
+});

package/bin/lean/e2e.mjs

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * e2e merge gate (#4403): a lane that adds or changes e2e specs, or whose contract has `[type:e2e]` criteria, triggers
+ * the repo's e2e run (a PR label or a workflow dispatch) and waits on it before merge. Tiered CI skips e2e on lane PRs,
+ * so the required checks alone never run those specs. All GitHub effects go through the injected io.
+ */
+import { ciPollDelayMs } from "../engine.mjs";
+import { matchesGlob, verifiableFiles, skipsCi, runCiVerify, collectFailedLogs, VERIFY_CHECK_NAME, DEFAULT_SKIP_PATHS, DEFAULT_GRACE_MS } from "./verify.mjs";
+
+export const E2E_MODES = Object.freeze(["auto", "always", "never"]);
+/** Common e2e layouts across ecosystems (Playwright, Cypress, Nest/Jest e2e, plain e2e/ trees). */
+export const E2E_DEFAULT_PATHS = Object.freeze(["e2e/**", "**/e2e/**", "*.e2e.*", "*.e2e-spec.*", "cypress/**", "playwright/**"]);
+export const NO_TRIGGER = "no e2e_label or e2e_workflow configured";
+
+const str = (v) => (v === undefined || v === null ? "" : String(v).trim());
+const list = (v) => (Array.isArray(v) ? v : str(v) ? str(v).split(",") : null)?.map((x) => String(x).trim()).filter(Boolean) ?? null;
+
+/**
+ * forge.yaml `verify:` e2e keys → {mode, label, workflow, pathsInput, checks, paths, blocking}. mode defaults to auto
+ * (inert without a label or workflow), blocking to changed (only the lane's own specs block the merge).
+ */
+export function parseE2e(sec = {}) {
+  const s = sec && typeof sec === "object" ? sec : {};
+  const mode = E2E_MODES.includes(str(s.e2e)) ? str(s.e2e) : "auto";
+  const label = /^[A-Za-z0-9._:/ -]+$/.test(str(s.e2e_label)) ? str(s.e2e_label) : null;
+  const workflow = /^[A-Za-z0-9._/-]+$/.test(str(s.e2e_workflow)) ? str(s.e2e_workflow) : null;
+  const pathsInput = /^[A-Za-z_][A-Za-z0-9_-]*$/.test(str(s.e2e_paths_input)) ? str(s.e2e_paths_input) : null;
+  const checks = list(s.e2e_checks) ?? [];
+  const paths = list(s.e2e_paths) ?? [...E2E_DEFAULT_PATHS];
+  const blocking = str(s.e2e_blocking) === "all" ? "all" : "changed";
+  return { mode, label, workflow, pathsInput, checks, paths, blocking };
+}
+
+/** Changed files (minus the engine's hand-off files) that are e2e specs per `cfg.paths`. */
+export const e2eSpecs = (files, cfg = parseE2e({})) => verifiableFiles(files).filter((f) => (cfg.paths ?? []).some((g) => matchesGlob(f, g)));
+/** True when a contract requirement quote carries a `[type:e2e]` criterion. */
+export const contractWantsE2e = (contract) => (Array.isArray(contract?.requirements) ? contract.requirements : []).some((r) => /\[type:e2e\]/i.test(String(r?.quote ?? "")));
+
+/** Whether this lane runs the e2e gate: {run, reason, specs}. */
+export function e2eWanted({ cfg, files, contract } = {}) {
+  const c = cfg ?? parseE2e({});
+  const specs = e2eSpecs(files, c);
+  if (c.mode === "never") return { run: false, reason: "verify.e2e: never", specs };
+  if (!c.label && !c.workflow) return { run: false, reason: NO_TRIGGER, specs };
+  if (c.mode === "always") {
+    return skipsCi(files, DEFAULT_SKIP_PATHS) ? { run: false, reason: "docs-only change", specs } : { run: true, reason: "verify.e2e: always", specs };
+  }
+  if (specs.length) return { run: true, reason: `${specs.length} e2e spec(s) changed`, specs };
+  if (contractWantsE2e(contract)) return { run: true, reason: "contract has [type:e2e] criteria", specs };
+  return { run: false, reason: "no e2e spec changed and no [type:e2e] criteria", specs };
+}
+
+/**
+ * The failures attributable to the lane: every failure when it changed no spec; otherwise those whose log names one of
+ * its specs (path or basename), plus any whose log is empty (cannot be attributed: fail closed).
+ */
+export function ownFailures(failures, specs) {
+  const fs = failures ?? [];
+  if (!specs?.length) return [...fs];
+  const needles = [...new Set(specs.flatMap((s) => [String(s), String(s).split("/").at(-1)]))];
+  return fs.filter((f) => { const l = String(f?.log ?? ""); return !l.trim() || needles.some((n) => l.includes(n)); });
+}
+
+/**
+ * One e2e run of `head`: {result: pass|fail|timeout|unavailable, failures, runUrl, runId, detail}. Workflow path:
+ * dispatch `cfg.workflow` (runCiVerify). Label path: label the PR, then wait on the head's e2e check runs, where a
+ * skipped run (the unlabelled tier) counts as not run.
+ */
+export async function runE2eGate({ io, pr, branch, head, cfg, specs = [], changedFiles = [], ciMaxMinutes = 360, now = () => Date.now(), sleep, random = Math.random,
+  onPoll = async () => {}, exclude = [], graceMs = DEFAULT_GRACE_MS }) {
+  const c = cfg ?? parseE2e({});
+  if (c.workflow) {
+    const v = await runCiVerify({ io, branch, head, changedFiles: specs.length ? specs : changedFiles, verify: { workflow: c.workflow, pathsInput: c.pathsInput, skipPaths: [] },
+      ciMaxMinutes, now, sleep, random, onPoll, exclude, graceMs, push: async () => {} });
+    if (v.result === "skipped") return { ...v, result: "unavailable", detail: "no changed file to run e2e for" };
+    return v;
+  }
+  const unavailable = (detail) => ({ result: "unavailable", failures: [], runUrl: null, detail });
+  if (!c.label) return unavailable(NO_TRIGGER);
+  if (!io.addPrLabel || !io.commitChecks) return unavailable("no label or commit-checks seam");
+  try { await io.addPrLabel(pr, c.label); }
+  catch (e) { return unavailable(`label ${c.label} could not be added to PR #${pr}: ${String(e?.stderr ?? e?.message ?? e).split("\n")[0].slice(0, 200)}`); }
+  const startedAt = now();
+  const isE2e = (x) => (c.checks.length ? c.checks.includes(x?.name) : x?.name !== VERIFY_CHECK_NAME);
+  for (let i = 0; ; i++) {
+    let checks = [];
+    try { checks = ((await io.commitChecks(head)) ?? []).filter(isE2e); } catch { checks = []; }
+    const ran = checks.filter((x) => String(x?.conclusion ?? "").toLowerCase() !== "skipped");
+    const names = c.checks.length ? c.checks : [...new Set(checks.map((x) => x.name))];
+    const byName = names.map((n) => ran.filter((x) => x.name === n));
+    if (names.length && byName.every((rs) => rs.length && rs.every((x) => x.state !== "pending"))) {
+      const failed = byName.flatMap((rs) => rs.filter((x) => x.state === "failure"));
+      if (!failed.length) return { result: "pass", failures: [], runUrl: null, detail: `${names.length} e2e check(s) green` };
+      return { result: "fail", failures: await collectFailedLogs(io, failed), runUrl: failed[0].url ?? null, detail: `${failed.length} e2e check(s) failed: ${failed.map((x) => x.name).join(", ")}` };
+    }
+    if (!ran.length && now() - startedAt >= graceMs) return unavailable(`no e2e check ran for ${String(head).slice(0, 12)} within ${Math.round(graceMs / 60000)} min of labelling PR #${pr} ${c.label}`);
+    if (now() - startedAt >= ciMaxMinutes * 60000) return { result: "timeout", failures: [], runUrl: null, detail: `e2e still pending after ${ciMaxMinutes} min` };
+    await onPoll();
+    await sleep(ciPollDelayMs(i, random));
+  }
+}

package/bin/lean/e2e.test.mjs

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseE2e, e2eSpecs, contractWantsE2e, e2eWanted, ownFailures, runE2eGate, E2E_DEFAULT_PATHS, NO_TRIGGER } from "./e2e.mjs";
+import { VERIFY_CHECK_NAME } from "./verify.mjs";
+
+const HEAD = "abc123abc123abc123";
+const RUN = "https://github.com/o/r/actions/runs/42/job/1";
+/** Fake io + clock: `checks` is a list of successive commitChecks answers (the last repeats). */
+function fake(o = {}) {
+  const f = { clock: 0, labels: [], dispatched: [], q: [...(o.checks ?? [])] };
+  f.io = {
+    addPrLabel: async (pr, l) => { if (o.labelError) throw new Error(o.labelError); f.labels.push([pr, l]); },
+    commitChecks: async () => (f.q.length > 1 ? f.q.shift() : f.q[0] ?? []),
+    failedLogs: async () => o.log ?? "FAIL e2e/a.spec.ts",
+    dispatchWorkflow: async (a) => { f.dispatched.push(a); },
+    workflowRuns: async () => [{ databaseId: 9, headSha: HEAD, status: "completed", conclusion: o.conclusion ?? "success", url: "https://github.com/o/r/actions/runs/9", name: "e2e" }],
+  };
+  f.args = (extra = {}) => ({ io: f.io, pr: 77, branch: "feat/issue-7-lean", head: HEAD, cfg: parseE2e({ e2e_label: "full-ci", e2e_checks: "e2e" }), specs: ["e2e/a.spec.ts"],
+    ciMaxMinutes: 30, now: () => f.clock, sleep: async (ms) => { f.clock += ms; }, random: () => 0.5, ...extra });
+  return f;
+}
+const chk = (state, conclusion = state === "pending" ? null : state, name = "e2e") => ({ name, state, conclusion, url: RUN });
+
+describe("e2e config and trigger (#4403)", () => {
+  it("parseE2e defaults to auto/changed with the default paths and rejects invalid values", () => {
+    assert.deepEqual(parseE2e({}), { mode: "auto", label: null, workflow: null, pathsInput: null, checks: [], paths: [...E2E_DEFAULT_PATHS], blocking: "changed" });
+    const c = parseE2e({ e2e: "always", e2e_label: "full-ci", e2e_workflow: "e2e.yml", e2e_paths_input: "specs", e2e_checks: "e2e (1), e2e (2)", e2e_paths: "tests/e2e/**", e2e_blocking: "all" });
+    assert.deepEqual(c, { mode: "always", label: "full-ci", workflow: "e2e.yml", pathsInput: "specs", checks: ["e2e (1)", "e2e (2)"], paths: ["tests/e2e/**"], blocking: "all" });
+    assert.equal(parseE2e({ e2e: "sometimes" }).mode, "auto");
+    assert.equal(parseE2e({ e2e_workflow: "x; rm -rf /" }).workflow, null);
+    assert.equal(parseE2e({ e2e_label: "a$(b)" }).label, null);
+  });
+  it("e2eSpecs matches the default layouts and ignores .forge-lean files", () => {
+    const files = ["e2e/a.spec.ts", "apps/web/e2e/b.spec.ts", "src/x.e2e.test.ts", "test/app.e2e-spec.ts", "cypress/e2e/c.cy.ts", "playwright/d.ts", "src/a.ts", "src/a.spec.ts", ".forge-lean/e2e/x"];
+    assert.deepEqual(e2eSpecs(files), files.slice(0, 6));
+  });
+  it("e2eWanted: never never runs; no trigger never runs; auto runs on specs or [type:e2e]; always runs unless docs-only", () => {
+    const cfg = parseE2e({ e2e_label: "full-ci" });
+    const typed = { requirements: [{ quote: "Rosters render. [type:E2E]" }] };
+    assert.equal(e2eWanted({ cfg: { ...cfg, mode: "never" }, files: ["e2e/a.spec.ts"] }).run, false);
+    assert.deepEqual(e2eWanted({ cfg: parseE2e({}), files: ["e2e/a.spec.ts"] }), { run: false, reason: NO_TRIGGER, specs: ["e2e/a.spec.ts"] });
+    assert.equal(e2eWanted({ cfg, files: ["e2e/a.spec.ts"] }).run, true);
+    assert.equal(e2eWanted({ cfg, files: ["src/a.ts"] }).run, false);
+    assert.equal(contractWantsE2e(typed), true);
+    assert.equal(e2eWanted({ cfg, files: ["src/a.ts"], contract: typed }).run, true);
+    assert.equal(e2eWanted({ cfg: { ...cfg, mode: "always" }, files: ["src/a.ts"] }).run, true);
+    assert.equal(e2eWanted({ cfg: { ...cfg, mode: "always" }, files: ["README.md"] }).run, false);
+  });
+  it("ownFailures: by spec path or basename in the log; an empty log or no changed spec counts as the lane's", () => {
+    const fs = [{ job: "a", log: "FAIL e2e/a.spec.ts" }, { job: "b", log: "x/a.spec.ts:3 failed" }, { job: "c", log: "FAIL e2e/rosters.spec.ts" }, { job: "d", log: "" }];
+    assert.deepEqual(ownFailures(fs, ["e2e/a.spec.ts"]).map((f) => f.job), ["a", "b", "d"]);
+    assert.deepEqual(ownFailures(fs, []).map((f) => f.job), ["a", "b", "c", "d"]);
+  });
+});
+
+describe("runE2eGate (#4403)", () => {
+  it("label path: labels the PR; a skipped run is not a pass; waits for the real run", async () => {
+    const f = fake({ checks: [[chk("success", "skipped")], [chk("success", "skipped"), chk("pending")], [chk("success", "skipped"), chk("success")]] });
+    const r = await runE2eGate(f.args());
+    assert.equal(r.result, "pass"); assert.deepEqual(f.labels, [[77, "full-ci"]]);
+    assert.ok(f.clock > 0, "it waited");
+  });
+  it("label path: a red e2e run returns the failed log; other checks are ignored when e2e_checks is set", async () => {
+    const f = fake({ checks: [[chk("failure"), chk("failure", "failure", "lint")]], log: "FAIL e2e/a.spec.ts" });
+    const r = await runE2eGate(f.args());
+    assert.equal(r.result, "fail"); assert.deepEqual(r.failures.map((x) => x.job), ["e2e"]); assert.match(r.failures[0].log, /a\.spec\.ts/);
+  });
+  it("label path without e2e_checks waits on every check but the lane's own verify check", async () => {
+    const f = fake({ checks: [[chk("success", "success", "build"), chk("success", "skipped"), chk("success", "success", VERIFY_CHECK_NAME)], [chk("success", "success", "build"), chk("success")]] });
+    const r = await runE2eGate(f.args({ cfg: parseE2e({ e2e_label: "full-ci" }) }));
+    assert.equal(r.result, "pass"); assert.ok(f.clock > 0, "the skipped e2e kept it waiting");
+  });
+  it("label refused, or no e2e run within the grace period, is unavailable; slow e2e is a timeout", async () => {
+    assert.equal((await runE2eGate(fake({ labelError: "HTTP 422" }).args())).result, "unavailable");
+    assert.equal((await runE2eGate(fake({ checks: [[chk("success", "skipped")]] }).args())).result, "unavailable");
+    assert.equal((await runE2eGate(fake({ checks: [[chk("pending")]] }).args())).result, "timeout");
+  });
+  it("workflow path: dispatches the e2e workflow with the spec paths, wins over the label, judges the run of this head", async () => {
+    const f = fake({ conclusion: "failure" });
+    const r = await runE2eGate(f.args({ cfg: parseE2e({ e2e_label: "full-ci", e2e_workflow: "e2e.yml", e2e_paths_input: "specs" }) }));
+    assert.equal(r.result, "fail"); assert.equal(r.runId, 9); assert.deepEqual(f.labels, []);
+    assert.deepEqual(f.dispatched, [{ workflow: "e2e.yml", ref: "feat/issue-7-lean", inputs: { specs: "e2e/a.spec.ts" } }]);
+  });
+});