forgedock 1.26.0 → 1.28.0

package/bin/lean/toolchain.test.mjs

@@ -0,0 +1,154 @@
+// 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 { writeFileSync, mkdirSync, chmodSync, existsSync, readFileSync, statSync } from "node:fs";
+import { join, delimiter } from "node:path";
+import { execFileSync } from "node:child_process";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { detectPins, parsePackageManager, nodeSatisfies, nodeWarning, shimScripts, prepareToolchain, toolchainEnv, writeShims, summary } from "./toolchain.mjs";
+
+const tmp = (p) => tmpDir(p);
+const repo = (files) => {
+  const d = tmp("tc-repo-");
+  for (const [f, t] of Object.entries(files)) writeFileSync(join(d, f), typeof t === "string" ? t : JSON.stringify(t));
+  return d;
+};
+const exe = (dir, name, body) => { mkdirSync(dir, { recursive: true }); const p = join(dir, name); writeFileSync(p, `#!/bin/sh\n${body}\n`); chmodSync(p, 0o755); return p; };
+/**
+ * A host whose PATH has pnpm 11.0.0 and a fake corepack/npx that print the requested version for `--version`
+ * (`corepack pnpm@X --version`, `npx -y -p pnpm@X pnpm --version`) without any network.
+ */
+const fakeHost = ({ corepack = true } = {}) => {
+  const d = tmp("tc-host-");
+  exe(d, "pnpm", 'echo 11.0.0');
+  const pick = 'for a in "$@"; do case "$a" in pnpm@*) v="${a#pnpm@}";; esac; done; for a in "$@"; do [ "$a" = "--version" ] && { echo "$v"; exit 0; }; done; exit 0';
+  if (corepack) exe(d, "corepack", pick);
+  exe(d, "npx", pick);
+  return d;
+};
+const sysPath = process.env.PATH ?? "";
+
+describe("toolchain pins (#4163)", () => {
+  it("parsePackageManager accepts pm@x.y.z (with a +sha suffix) and nothing else", () => {
+    assert.deepEqual(parsePackageManager("pnpm@10.4.1+sha512.abc"), { name: "pnpm", version: "10.4.1" });
+    assert.deepEqual(parsePackageManager("yarn@4.1.0"), { name: "yarn", version: "4.1.0" });
+    for (const bad of ["pnpm@10", "bun@1.0.0", "pnpm@latest", "pnpm@1.0.0;rm -rf /", "", null]) assert.equal(parsePackageManager(bad), null, String(bad));
+  });
+
+  it("detects packageManager and node pins in priority order", async () => {
+    const d = repo({ "package.json": { packageManager: "pnpm@10.4.1", engines: { node: ">=18" } }, ".nvmrc": "20.11.0\n", ".node-version": "22\n" });
+    const p = await detectPins(d);
+    assert.deepEqual(p.pm, { name: "pnpm", version: "10.4.1", source: "package.json packageManager" });
+    assert.deepEqual(p.node, { spec: "20.11.0", source: ".nvmrc" });
+    const e = await detectPins(repo({ "package.json": { engines: { node: "^20" } } }));
+    assert.deepEqual(e.node, { spec: "^20", source: "package.json engines.node" });
+    assert.equal(e.pm, null);
+    const tv = await detectPins(repo({ ".tool-versions": "# pins\nnodejs 20.1.0\npnpm 9.1.0\n" }));
+    assert.deepEqual(tv.pm, { name: "pnpm", version: "9.1.0", source: ".tool-versions" });
+    assert.deepEqual(tv.node, { spec: "20.1.0", source: ".tool-versions" });
+  });
+
+  it("forge.yaml env.toolchain overrides the pm pin; off disables detection; junk is a note", async () => {
+    const d = repo({ "package.json": { packageManager: "pnpm@10.4.1" }, ".nvmrc": "20" });
+    assert.deepEqual((await detectPins(d, { override: "pnpm@9.0.0" })).pm, { name: "pnpm", version: "9.0.0", source: "forge.yaml env.toolchain" });
+    const off = await detectPins(d, { override: "off" });
+    assert.equal(off.pm, null); assert.equal(off.node, null);
+    const junk = await detectPins(d, { override: "pnpm" });
+    assert.equal(junk.pm.version, "10.4.1");
+    assert.match(junk.notes[0], /env\.toolchain "pnpm" is not/);
+  });
+
+  it("nodeSatisfies covers exact, partial, x, caret, tilde, comparators and ||", () => {
+    const t = [["20", "v20.11.0", true], ["20", "v22.1.0", false], ["20.11", "v20.11.4", true], ["20.x", "v20.0.0", true], ["^20.5", "v20.4.0", false],
+      ["^20.5", "v20.9.0", true], ["~20.5.1", "v20.6.0", false], [">=18", "v26.7.0", true], [">=18 <21", "v22.0.0", false], ["18 || 20", "v20.1.0", true],
+      ["< 20", "v20.0.0", false], ["<=20", "v20.9.9", true], [">20", "v20.9.9", false], [">20", "v21.0.0", true], ["v20.11.0", "v20.11.0", true]];
+    for (const [spec, v, want] of t) assert.equal(nodeSatisfies(spec, v), want, `${spec} vs ${v}`);
+    assert.equal(nodeSatisfies("18 - 20", "v19.0.0"), true);
+    assert.equal(nodeSatisfies("18 - 20", "v21.0.0"), false);
+    assert.equal(nodeSatisfies("hydrogen", "v19.0.0"), null);
+  });
+
+  it("an unsatisfied node pin yields a clear warning; a satisfied or alias pin yields none", () => {
+    assert.match(nodeWarning({ spec: "18.19.0", source: ".nvmrc" }, "v26.7.0"), /host node v26\.7\.0 does not satisfy the \.nvmrc pin "18\.19\.0"/);
+    assert.equal(nodeWarning({ spec: ">=18", source: "package.json engines.node" }, "v26.7.0"), null);
+    assert.equal(nodeWarning({ spec: "lts/iron", source: ".nvmrc" }, "v26.7.0"), null);
+    assert.match(nodeWarning({ spec: "iron-ish", source: ".nvmrc" }, "v26.7.0"), /cannot evaluate/);
+  });
+
+  it("shims: corepack first, npx fallback, yarn berry via @yarnpkg/cli-dist, values quoted", () => {
+    const pm = { name: "pnpm", version: "10.4.1" };
+    assert.match(shimScripts(pm, { corepack: "/h/corepack", npx: "/h/npx" }).pnpm, /exec '\/h\/corepack' 'pnpm@10\.4\.1' "\$@"/);
+    assert.match(shimScripts(pm, { corepack: "/h/corepack" }).pnpx, /'pnpm@10\.4\.1' dlx "\$@"/);
+    assert.match(shimScripts(pm, { npx: "/h/npx" }).pnpm, /exec '\/h\/npx' -y -p 'pnpm@10\.4\.1' pnpm "\$@"/);
+    assert.match(shimScripts({ name: "yarn", version: "4.1.0" }, { npx: "/h/npx" }).yarn, /-p '@yarnpkg\/cli-dist@4\.1\.0' yarn/);
+    assert.match(shimScripts({ name: "yarn", version: "1.22.19" }, { npx: "/h/npx" }).yarn, /-p 'yarn@1\.22\.19' yarn/);
+    const npm = shimScripts({ name: "npm", version: "10.2.0" }, { corepack: "/h/c", npx: "/h/npx" });
+    assert.deepEqual(Object.keys(npm), ["npm", "npx"]);
+    assert.match(npm.npx, /exec '\/h\/npx' -y -p 'npm@10\.2\.0' npx "\$@"/);
+    assert.deepEqual(shimScripts(pm, {}), {});
+  });
+
+  for (const corepack of [true, false]) {
+    it(`R1: with packageManager pnpm@10.4.1 and pnpm 11 on PATH, runner/validate/hook shells resolve pnpm --version to 10.4.1 (${corepack ? "corepack" : "npx"})`, async () => {
+      const host = fakeHost({ corepack });
+      const basePath = `${host}${delimiter}${sysPath}`;
+      assert.equal(execFileSync("sh", ["-c", "pnpm --version"], { env: { ...process.env, PATH: basePath } }).toString().trim(), "11.0.0", "the host pnpm is the wrong one");
+      const d = repo({ "package.json": { name: "x", packageManager: "pnpm@10.4.1+sha512.ff" } });
+      const binDir = join(tmp("tc-run-"), "toolchain", "bin");
+      const tc = await prepareToolchain({ dir: d, binDir, basePath, hostNode: () => "v20.0.0" });
+      assert.ok(tc.env && tc.env.PATH.startsWith(binDir + delimiter), "shim dir first on PATH");
+      assert.equal(tc.summary, "pnpm@10.4.1 (package.json packageManager)");
+      const env = { ...process.env, ...tc.env };
+      // runner: the claude CLI child gets this env (bin/runner.mjs applies `env` last); its Bash tool shells inherit it.
+      assert.equal(execFileSync("bash", ["-lc", "pnpm --version"], { env, cwd: d }).toString().trim(), "10.4.1", "runner shell");
+      // validate: a validate command is a shell command in the worktree.
+      assert.equal(execFileSync("sh", ["-c", "cd . && pnpm --version"], { env, cwd: d }).toString().trim(), "10.4.1", "validate command");
+      // hooks: git runs pre-commit / commit-msg hooks with the committing shell's PATH.
+      const git = (a) => execFileSync("git", a, { env: { ...env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" }, cwd: d }).toString();
+      git(["init", "-q"]);
+      exe(join(d, ".git", "hooks"), "pre-commit", `pnpm --version > "${join(d, "pre.out")}"`);
+      exe(join(d, ".git", "hooks"), "commit-msg", `pnpm --version > "${join(d, "msg.out")}"`);
+      git(["add", "package.json"]);
+      git(["commit", "-q", "-m", "x"]);
+      assert.equal(readFileSync(join(d, "pre.out"), "utf8").trim(), "10.4.1", "pre-commit hook");
+      assert.equal(readFileSync(join(d, "msg.out"), "utf8").trim(), "10.4.1", "commit-msg hook");
+    });
+  }
+
+  it("R2: a node pin the host does not satisfy produces a warning (and no shim without a pm pin)", async () => {
+    const binDir = join(tmp("tc-run-"), "bin");
+    const tc = await prepareToolchain({ dir: repo({ ".nvmrc": "18.19.0" }), binDir, hostNode: () => "v26.7.0" });
+    assert.match(tc.warning, /^host node v26\.7\.0 does not satisfy the \.nvmrc pin "18\.19\.0"/);
+    assert.equal(tc.summary, "node 18.19.0 (.nvmrc)");
+    assert.equal(tc.env, null); assert.equal(existsSync(binDir), false);
+  });
+
+  it("R4: a repo without pins gets nothing: no env, no shim dir, no warning, no notes", async () => {
+    const binDir = join(tmp("tc-run-"), "bin");
+    for (const files of [{}, { "package.json": { name: "x", scripts: { test: "node --test" } } }]) {
+      const tc = await prepareToolchain({ dir: repo(files), binDir, hostNode: () => { throw new Error("must not probe node"); } });
+      assert.equal(tc.env, null); assert.equal(tc.summary, null); assert.equal(tc.warning, null);
+      assert.deepEqual(tc.shims, []); assert.deepEqual(tc.notes, []);
+      assert.equal(existsSync(binDir), false);
+    }
+  });
+
+  it("toolchainEnv prepends the shim dir", () => {
+    assert.deepEqual(toolchainEnv("/s", "/a:/b"), { PATH: `/s${delimiter}/a:/b`, COREPACK_ENABLE_DOWNLOAD_PROMPT: "0", COREPACK_ENABLE_STRICT: "0" });
+  });
+
+  it("writeShims writes 0755 shims that never resolve the launcher from the shim dir; summary names the pins", async () => {
+    const host = fakeHost();
+    const binDir = join(tmp("tc-ws-"), "bin");
+    exe(binDir, "corepack", "echo self");
+    const names = await writeShims(binDir, { name: "pnpm", version: "10.4.1" }, { path: `${binDir}${delimiter}${host}` });
+    assert.deepEqual(names, ["pnpm", "pnpx"]);
+    for (const n of names) assert.equal(statSync(join(binDir, n)).mode & 0o777, 0o755);
+    assert.match(readFileSync(join(binDir, "pnpm"), "utf8"), new RegExp(`exec '${join(host, "corepack")}' 'pnpm@10\\.4\\.1'`));
+    assert.deepEqual(await writeShims(join(tmp("tc-ws-"), "bin"), { name: "yarn", version: "4.1.0" }, { path: "/nonexistent" }), []);
+    assert.equal(summary({ pm: { name: "pnpm", version: "10.4.1", source: "package.json packageManager" }, node: { spec: "20", source: ".nvmrc" } }), "pnpm@10.4.1 (package.json packageManager), node 20 (.nvmrc)");
+    assert.equal(summary({ pm: null, node: null }), null);
+    assert.equal(nodeWarning({ spec: "1", source: ".nvmrc" }) !== null, true, "defaults to process.version");
+  });
+});

package/bin/lean/verify.mjs

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Verify-by-CI (#4167): run the lane's heavy verification on CI runners instead of the host. The engine pushes the
+ * branch, dispatches the configured workflow (or waits on the head commit's push-triggered checks), and returns the
+ * failed jobs' log tails for the builder's fix loop. All GitHub effects go through the injected io.
+ */
+import { ciPollDelayMs } from "../engine.mjs";
+
+export const VERIFY_MODES = Object.freeze(["local", "ci", "hybrid"]);
+/** Changed files that never need the CI matrix (docs-only lanes skip CI verification). */
+export const DEFAULT_SKIP_PATHS = Object.freeze(["*.md", "*.mdx", "*.rst", "*.txt", "docs/**", "devdocs/**"]);
+export const DEFAULT_MAX_ROUNDS = 2;
+/** Per-command timeout of the pre-PR declared check commands (#4240, `verify.precheck_timeout_seconds`). */
+export const DEFAULT_PRECHECK_TIMEOUT_SECONDS = 300;
+/** Total characters of failed-job log handed to the builder. */
+export const LOG_CAP = 12000;
+/** No run or check for the head after this long means CI is unavailable (local fallback). */
+export const DEFAULT_GRACE_MS = 5 * 60000;
+const LEAN_PREFIX = ".forge-lean/";
+const OK = ["success", "neutral", "skipped"];
+
+/**
+ * forge.yaml `verify:` section (block style; parseForgeYaml gives strings) → {mode, workflow, pathsInput, skipPaths,
+ * maxRounds, precheckTimeoutSeconds}. Invalid values fall back to the defaults; mode defaults to local (today's behaviour).
+ */
+export function parseVerify(sec = {}) {
+  const s = sec && typeof sec === "object" ? sec : {};
+  const str = (v) => (v === undefined || v === null ? "" : String(v).trim());
+  const mode = VERIFY_MODES.includes(str(s.mode)) ? str(s.mode) : "local";
+  const workflow = /^[A-Za-z0-9._/-]+$/.test(str(s.workflow)) ? str(s.workflow) : null;
+  const pathsInput = /^[A-Za-z_][A-Za-z0-9_-]*$/.test(str(s.paths_input)) ? str(s.paths_input) : null;
+  const rawSkip = Array.isArray(s.skip_paths) ? s.skip_paths : str(s.skip_paths) ? str(s.skip_paths).split(",") : null;
+  const skipPaths = rawSkip ? rawSkip.map((x) => String(x).trim()).filter(Boolean) : [...DEFAULT_SKIP_PATHS];
+  const n = Number(str(s.max_rounds));
+  const maxRounds = str(s.max_rounds) !== "" && Number.isInteger(n) && n >= 0 && n <= 10 ? n : DEFAULT_MAX_ROUNDS;
+  const t = Number(str(s.precheck_timeout_seconds));
+  const precheckTimeoutSeconds = str(s.precheck_timeout_seconds) !== "" && Number.isInteger(t) && t >= 1 && t <= 3600 ? t : DEFAULT_PRECHECK_TIMEOUT_SECONDS;
+  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds };
+}
+
+const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);
+/** A glob without "/" matches the basename anywhere (gitignore style); one with "/" matches the whole path. */
+export function matchesGlob(file, glob) {
+  const f = String(file), g = String(glob).replace(/^\.?\//, "");
+  return g.includes("/") ? globRe(g).test(f) : globRe(g).test(f.split("/").at(-1));
+}
+/** Changed files that CI must see: everything except the engine's own `.forge-lean/` hand-off files. */
+export const verifiableFiles = (files) => (files ?? []).filter((f) => f && !String(f).startsWith(LEAN_PREFIX));
+/** True when every verifiable changed file matches a skip glob (a docs-only lane), or there is none. */
+export function skipsCi(files, skipPaths = DEFAULT_SKIP_PATHS) {
+  const fs = verifiableFiles(files);
+  return fs.every((f) => skipPaths.some((g) => matchesGlob(f, g)));
+}
+
+/** Tail each log so the total stays under `cap` characters. */
+export function capLogs(failures, cap = LOG_CAP) {
+  const per = Math.max(500, Math.floor(cap / Math.max(1, failures.length)));
+  return failures.map((f) => { const l = String(f.log ?? ""); return { ...f, log: l.length > per ? `…${l.slice(-per)}` : l }; });
+}
+const runIdOf = (url) => /\/actions\/runs\/(\d+)/.exec(String(url ?? ""))?.[1] ?? null;
+/**
+ * Failed checks [{name, url}] → capped [{job, url, log}]: one `failedLogs` fetch per Actions run id, the log attached to
+ * the first check of that run only (#4240: shared by runCiVerify and the merge-time fix rounds).
+ */
+export async function collectFailedLogs(io, failedChecks) {
+  const logs = {}, out = [];
+  for (const c of failedChecks ?? []) {
+    const id = runIdOf(c.url);
+    if (id && !(id in logs)) { try { logs[id] = String((await io.failedLogs?.(id)) ?? ""); } catch { logs[id] = ""; } }
+    out.push({ job: c.name, url: c.url ?? null, log: id && !out.some((x) => runIdOf(x.url) === id) ? logs[id] : "" });
+  }
+  return capLogs(out);
+}
+const sameSha = (a, b) => Boolean(a && b) && (String(a).startsWith(b) || String(b).startsWith(a));
+
+/**
+ * One CI verification of `head` on `branch`. Returns {result: pass|fail|timeout|unavailable|skipped, failures, runUrl,
+ * detail, runId}. `push` is called before any CI call (never for a skipped lane); `exclude` lists run ids already judged,
+ * so a re-dispatch on the same head never reuses an old run; `onPoll` runs before each wait (lease renew, progress).
+ */
+export async function runCiVerify({ io, branch, head, changedFiles, verify, ciMaxMinutes = 360, now = () => Date.now(), sleep, random = Math.random,
+  push = async () => {}, exclude = [], onPoll = async () => {}, graceMs = DEFAULT_GRACE_MS }) {
+  const v = verify ?? parseVerify({});
+  const files = verifiableFiles(changedFiles);
+  if (skipsCi(files, v.skipPaths)) return { result: "skipped", failures: [], runUrl: null, detail: `all ${files.length} changed file(s) match skip_paths` };
+  await push();
+  const startedAt = now();
+  const unavailable = (detail) => ({ result: "unavailable", failures: [], runUrl: null, detail });
+  if (v.workflow) {
+    if (!io.dispatchWorkflow || !io.workflowRuns) return unavailable("no workflow dispatch seam");
+    const inputs = v.pathsInput ? { [v.pathsInput]: files.join("\n") } : {};
+    try { await io.dispatchWorkflow({ workflow: v.workflow, ref: branch, inputs }); }
+    catch (e) { return unavailable(`workflow ${v.workflow} could not be dispatched: ${String(e?.stderr ?? e?.message ?? e).split("\n")[0].slice(0, 200)}`); }
+  } else if (!io.commitChecks) return unavailable("no commit-checks seam");
+  const skip = new Set(exclude.map(String));
+  for (let i = 0; ; i++) {
+    if (v.workflow) {
+      let runs = [];
+      try { runs = (await io.workflowRuns({ workflow: v.workflow, branch })) ?? []; } catch { runs = []; }
+      const run = runs.find((r) => sameSha(r?.headSha, head) && !skip.has(String(r?.databaseId)));
+      if (run && String(run.status).toLowerCase() === "completed") {
+        const c = String(run.conclusion ?? "").toLowerCase();
+        if (OK.includes(c)) return { result: "pass", failures: [], runUrl: run.url ?? null, runId: run.databaseId, detail: `${v.workflow} ${c}` };
+        let log = "";
+        try { log = String((await io.failedLogs?.(run.databaseId)) ?? ""); } catch { log = ""; }
+        return { result: "fail", failures: capLogs([{ job: run.name ?? v.workflow, url: run.url ?? null, log }]), runUrl: run.url ?? null, runId: run.databaseId, detail: `${v.workflow} ${c || "failed"}` };
+      }
+      if (!run && now() - startedAt >= graceMs) return unavailable(`no ${v.workflow} run for ${String(head).slice(0, 12)} appeared within ${Math.round(graceMs / 60000)} min`);
+    } else {
+      let checks = [];
+      try { checks = (await io.commitChecks(head)) ?? []; } catch { checks = []; }
+      if (!checks.length && now() - startedAt >= graceMs) return unavailable(`no checks reported for ${String(head).slice(0, 12)} within ${Math.round(graceMs / 60000)} min`);
+      if (checks.length && checks.every((c) => c.state !== "pending")) {
+        const failed = checks.filter((c) => c.state === "failure");
+        if (!failed.length) return { result: "pass", failures: [], runUrl: null, detail: `${checks.length} check(s) green` };
+        return { result: "fail", failures: await collectFailedLogs(io, failed), runUrl: failed[0].url ?? null, detail: `${failed.length} check(s) failed: ${failed.map((c) => c.name).join(", ")}` };
+      }
+    }
+    if (now() - startedAt >= ciMaxMinutes * 60000) return { result: "timeout", failures: [], runUrl: null, detail: `CI still pending after ${ciMaxMinutes} min` };
+    await onPoll();
+    await sleep(ciPollDelayMs(i, random));
+  }
+}

package/bin/lean/verify.test.mjs

@@ -0,0 +1,118 @@
+// 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 { parseVerify, matchesGlob, skipsCi, capLogs, runCiVerify, collectFailedLogs, DEFAULT_SKIP_PATHS, LOG_CAP } from "./verify.mjs";
+import { precheck } from "./conformance.mjs";
+
+const HEAD = "abc123abc123abc123";
+/** Fake io + clock: `runs` is a list of successive workflowRuns answers (the last repeats); `checks` likewise. */
+function fake(o = {}) {
+  const f = { clock: 0, dispatched: [], logsFor: [], pushes: 0, runsQ: [...(o.runs ?? [])], checksQ: [...(o.checks ?? [])] };
+  f.io = {
+    dispatchWorkflow: async (a) => { if (o.dispatchError) throw Object.assign(new Error("HTTP 422"), { stderr: o.dispatchError }); f.dispatched.push(a); },
+    workflowRuns: async () => (f.runsQ.length > 1 ? f.runsQ.shift() : f.runsQ[0] ?? []),
+    commitChecks: async () => (f.checksQ.length > 1 ? f.checksQ.shift() : f.checksQ[0] ?? []),
+    failedLogs: async (id) => { f.logsFor.push(String(id)); return o.log ?? `log of ${id}`; },
+  };
+  f.args = (extra = {}) => ({ io: f.io, branch: "feat/issue-7-lean", head: HEAD, changedFiles: ["src/a.ts", ".forge-lean/result.json"], verify: parseVerify({ mode: "ci", workflow: "verify.yml", paths_input: "changed_paths" }),
+    ciMaxMinutes: 30, now: () => f.clock, sleep: async (ms) => { f.clock += ms; }, random: () => 0.5, push: async () => { f.pushes++; }, ...extra });
+  return f;
+}
+
+describe("verify-by-CI config (#4167)", () => {
+  it("parseVerify defaults to local and rejects invalid values", () => {
+    assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300 });
+    const v = parseVerify({ mode: "ci", workflow: ".github/workflows/verify.yml", paths_input: "changed_paths", skip_paths: "*.md, docs/** ,", max_rounds: "3" });
+    assert.deepEqual(v, { mode: "ci", workflow: ".github/workflows/verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 3, precheckTimeoutSeconds: 300 });
+    assert.equal(parseVerify({ mode: "remote" }).mode, "local");
+    assert.equal(parseVerify({ workflow: "x; rm -rf /" }).workflow, null);
+    assert.equal(parseVerify({ max_rounds: "-1" }).maxRounds, 2);
+    assert.equal(parseVerify({ max_rounds: "0" }).maxRounds, 0);
+    assert.equal(parseVerify({ mode: "hybrid" }).mode, "hybrid");
+  });
+  it("globs: a pattern without / matches the basename anywhere; ** spans directories", () => {
+    assert.ok(matchesGlob("README.md", "*.md")); assert.ok(matchesGlob("pkg/a/CHANGELOG.md", "*.md"));
+    assert.ok(matchesGlob("docs/guide/x.png", "docs/**")); assert.ok(!matchesGlob("src/docs/x.ts", "docs/**"));
+    assert.ok(!matchesGlob("src/a.ts", "*.md")); assert.ok(!matchesGlob("a.mdx.ts", "*.mdx"));
+  });
+  it("a docs-only change skips CI; one code file does not; .forge-lean files are ignored", () => {
+    assert.ok(skipsCi(["README.md", "docs/a.md", ".forge-lean/result.json"]));
+    assert.ok(!skipsCi(["README.md", "src/a.ts"]));
+    assert.ok(!skipsCi(["poetry.lock"]), "a lock file is never docs-only");
+  });
+  it("capLogs keeps the tails within the cap", () => {
+    const out = capLogs([{ job: "a", log: "x".repeat(50000) + "END-A" }, { job: "b", log: "short" }]);
+    assert.ok(out[0].log.endsWith("END-A")); assert.ok(out[0].log.length <= LOG_CAP / 2 + 1); assert.equal(out[1].log, "short");
+  });
+  it("precheck: a CI-verified head covers validate ids left to CI; a recorded failure still fails", () => {
+    const contract = { requirements: [], deliverables: [{ id: "D1", path: "src/a.ts", change: "x", requirements: [] }], validate: [{ id: "V1", command: "tsc" }, { id: "V2", command: "lint" }] };
+    const result = { validation: [{ id: "V1", command: "tsc", ci: true }, { id: "V2", command: "lint", exit: 0 }] };
+    const kinds = (r, ciVerified) => precheck({ contract, result: r, changedFiles: ["src/a.ts"], ciVerified }).failures.map((f) => f.kind);
+    assert.deepEqual(kinds(result, false), ["validate_missing"]);
+    assert.deepEqual(kinds(result, true), []);
+    assert.deepEqual(kinds({ validation: [] }, true), []);
+    assert.deepEqual(kinds({ validation: [{ id: "V1", exit: 0 }, { id: "V2", exit: 1 }] }, true), ["validate_failed"]);
+  });
+});
+
+describe("runCiVerify (#4167)", () => {
+  it("docs-only: skipped without a push or any CI call", async () => {
+    const f = fake();
+    const r = await runCiVerify(f.args({ changedFiles: ["README.md", "docs/x.md"] }));
+    assert.equal(r.result, "skipped"); assert.equal(f.pushes, 0); assert.equal(f.dispatched.length, 0);
+  });
+  it("workflow: pushes, dispatches on the branch with the changed paths, waits for the run of this head, passes", async () => {
+    const f = fake({ runs: [[], [{ databaseId: 9, headSha: HEAD, status: "in_progress" }], [{ databaseId: 9, headSha: HEAD, status: "completed", conclusion: "success", url: "u9" }]] });
+    const r = await runCiVerify(f.args());
+    assert.equal(r.result, "pass"); assert.equal(r.runId, 9); assert.equal(f.pushes, 1);
+    assert.deepEqual(f.dispatched, [{ workflow: "verify.yml", ref: "feat/issue-7-lean", inputs: { changed_paths: "src/a.ts" } }]);
+  });
+  it("workflow: a red run returns the failed-job log; excluded (already judged) runs are never reused", async () => {
+    const f = fake({ runs: [[{ databaseId: 1, headSha: HEAD, status: "completed", conclusion: "failure" }, { databaseId: 2, headSha: HEAD, status: "completed", conclusion: "failure", name: "verify", url: "u2" }]], log: "poetry.lock is out of date" });
+    const r = await runCiVerify(f.args({ exclude: [1] }));
+    assert.equal(r.result, "fail"); assert.equal(r.runId, 2); assert.deepEqual(f.logsFor, ["2"]);
+    assert.deepEqual(r.failures, [{ job: "verify", url: "u2", log: "poetry.lock is out of date" }]);
+  });
+  it("workflow: a refused dispatch, or no run within the grace period, is unavailable (local fallback)", async () => {
+    assert.equal((await runCiVerify(fake({ dispatchError: "workflow does not have workflow_dispatch trigger" }).args())).result, "unavailable");
+    const r = await runCiVerify(fake({ runs: [[{ databaseId: 5, headSha: "other", status: "completed", conclusion: "success" }]] }).args());
+    assert.equal(r.result, "unavailable"); assert.match(r.detail, /no verify\.yml run/);
+  });
+  it("slow CI is a timeout at the budget, never a failure", async () => {
+    const f = fake({ runs: [[{ databaseId: 3, headSha: HEAD, status: "queued" }]] });
+    const r = await runCiVerify(f.args({ ciMaxMinutes: 10 }));
+    assert.equal(r.result, "timeout"); assert.ok(f.clock >= 10 * 60000);
+  });
+  it("no workflow: waits on the head's push-triggered checks and fetches each failed Actions run's log once", async () => {
+    const f = fake({ checks: [[{ name: "lint", state: "pending" }], [{ name: "lint", state: "success" }, { name: "test", state: "failure", url: "https://github.com/o/r/actions/runs/55/job/1" }, { name: "types", state: "failure", url: "https://github.com/o/r/actions/runs/55/job/2" }]] });
+    const r = await runCiVerify(f.args({ verify: parseVerify({ mode: "ci" }) }));
+    assert.equal(r.result, "fail"); assert.deepEqual(f.logsFor, ["55"]); assert.equal(f.dispatched.length, 0);
+    assert.deepEqual(r.failures.map((x) => [x.job, Boolean(x.log)]), [["test", true], ["types", false]]);
+    const g = fake({ checks: [[]] });
+    assert.equal((await runCiVerify(g.args({ verify: parseVerify({ mode: "ci" }) }))).result, "unavailable");
+  });
+});
+
+describe("merge-time fix rounds and declared check commands (#4240)", () => {
+  it("collectFailedLogs fetches one log per Actions run and caps the total", async () => {
+    const fetched = [];
+    const io = { failedLogs: async (id) => { fetched.push(id); return "x".repeat(LOG_CAP * 2); } };
+    const out = await collectFailedLogs(io, [
+      { name: "Unit tests", url: "https://github.com/o/r/actions/runs/9/job/1" },
+      { name: "Shell tests", url: "https://github.com/o/r/actions/runs/9/job/2" },
+      { name: "status", url: null },
+    ]);
+    assert.deepEqual(fetched, ["9"]);
+    assert.deepEqual(out.map((f) => f.job), ["Unit tests", "Shell tests", "status"]);
+    assert.ok(out[0].log.length > 0 && out[1].log === "" && out[2].log === "");
+    assert.ok(out.reduce((n, f) => n + f.log.length, 0) <= LOG_CAP + 3);
+    assert.deepEqual(await collectFailedLogs({ failedLogs: async () => { throw new Error("gone"); } }, [{ name: "a", url: "https://x/actions/runs/1" }]), [{ job: "a", url: "https://x/actions/runs/1", log: "" }]);
+  });
+
+  it("parseVerify precheck_timeout_seconds: default 300, integer 1-3600 accepted, others fall back", () => {
+    assert.equal(parseVerify({}).precheckTimeoutSeconds, 300);
+    assert.equal(parseVerify({ precheck_timeout_seconds: "60" }).precheckTimeoutSeconds, 60);
+    for (const bad of ["0", "-5", "1.5", "abc", "3601"]) assert.equal(parseVerify({ precheck_timeout_seconds: bad }).precheckTimeoutSeconds, 300, bad);
+  });
+});

package/bin/lean/worktree.mjs

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Sparse lane worktrees (#4221). A lane checks out every tracked file except regular blobs at or above
+ * `maxBlobBytes` (forge.yaml `env.sparse_max_kb`, default 1024; 0 = off). Lockfiles, manifests, toolchain pins and
+ * git/forge config are always checked out (the #4220 dep cache and #4163 toolchain pins read them). The patterns are
+ * non-cone (`/*` then `!/<path>`), kept in the worktree's own `info/sparse-checkout`; `core.sparseCheckout` is per-worktree
+ * config (git sets `extensions.worktreeConfig` in the shared config), so the main checkout is untouched. A repo with no
+ * such blob gets today's plain `git worktree add`. A failed sparse step falls back to a full checkout; never fails a lane.
+ */
+import { join } from "node:path";
+
+export const DEFAULT_SPARSE_MAX_KB = 1024;
+
+const KEEP_RE = /^(package\.json|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|yarn\.lock|\.yarnrc\.yml|uv\.lock|poetry\.lock|pyproject\.toml|requirements.*\.txt|setup\.py|setup\.cfg|\.nvmrc|\.node-version|\.tool-versions|tsconfig.*\.json|forge\.yaml|\.gitattributes|\.gitignore)$/;
+
+/** Blobs to leave out, from `git ls-tree -r -l -z <ref>` output: {excludes, bytes}. Symlinks, gitlinks and kept files never. */
+export function sparsePlan(lsTree, { maxBlobBytes = DEFAULT_SPARSE_MAX_KB * 1024 } = {}) {
+  const excludes = [];
+  let bytes = 0;
+  if (!(maxBlobBytes > 0)) return { excludes, bytes };
+  for (const rec of String(lsTree ?? "").split("\0")) {
+    const m = /^(\d{6}) blob [0-9a-f]+ +(\d+)\t([\s\S]+)$/.exec(rec.replace(/^\n+/, ""));
+    if (!m || !["100644", "100755"].includes(m[1])) continue;
+    const size = Number(m[2]), path = m[3];
+    if (size < maxBlobBytes || /[\n\r]/.test(path) || KEEP_RE.test(path.split("/").at(-1))) continue;
+    excludes.push(path);
+    bytes += size;
+  }
+  return { excludes, bytes };
+}
+
+/** gitignore-syntax escape for a literal path: \ * ? [ anywhere, trailing spaces. */
+const esc = (p) => p.replace(/[\\*?[]| (?= *$)/g, (c) => `\\${c}`);
+
+/** Non-cone sparse patterns that include everything except `excludes`. */
+export function sparsePatterns(excludes) {
+  return ["/*", ...excludes.map((p) => `!/${esc(p)}`)];
+}
+
+/**
+ * Add a lane worktree, sparse when the plan is non-empty. `git(args, {cwd})` is the injected io.git; `write(path, text)`
+ * writes the pattern file (argv-safe for any number of patterns). `addArgs` is the plain `["worktree","add",...]` argv.
+ * A failing `worktree add` is rethrown unchanged (the caller retries lock races). Returns {sparse, excluded, bytes, fallback?}.
+ */
+export async function addLaneWorktree(git, write, { cwd, wt, addArgs, ref, maxBlobBytes = DEFAULT_SPARSE_MAX_KB * 1024 }) {
+  let plan = { excludes: [], bytes: 0 };
+  if (maxBlobBytes > 0 && typeof write === "function") {
+    try { plan = sparsePlan(await git(["ls-tree", "-r", "-l", "-z", ref], { cwd }), { maxBlobBytes }); } catch { /* no plan: full checkout */ }
+  }
+  if (!plan.excludes.length) {
+    await git(addArgs, { cwd });
+    return { sparse: false, excluded: 0, bytes: 0 };
+  }
+  await git([...addArgs.slice(0, 2), "--no-checkout", ...addArgs.slice(2)], { cwd });
+  const g = (a) => git(a, { cwd: wt });
+  try {
+    await g(["sparse-checkout", "set", "--no-cone", "/*"]);
+    const file = String(await g(["rev-parse", "--git-path", "info/sparse-checkout"])).trim();
+    await write(file.startsWith("/") ? file : join(wt, file), `${sparsePatterns(plan.excludes).join("\n")}\n`);
+    await g(["read-tree", "-mu", "HEAD"]);
+    return { sparse: true, excluded: plan.excludes.length, bytes: plan.bytes };
+  } catch (e) {
+    const reason = String(e?.stderr || e?.message || e).trim().split("\n").slice(-2).join(" ").slice(0, 300);
+    try { await g(["sparse-checkout", "disable"]); } catch { /* full read-tree below */ }
+    await g(["read-tree", "-mu", "HEAD"]);
+    return { sparse: false, excluded: 0, bytes: 0, fallback: reason || "sparse checkout failed" };
+  }
+}

package/bin/lean/worktree.test.mjs

@@ -0,0 +1,141 @@
+// 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 { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, readdirSync, statSync, existsSync, rmSync } from "node:fs";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { join, dirname } from "node:path";
+import { sparsePlan, sparsePatterns, addLaneWorktree } from "./worktree.mjs";
+
+const MiB = 1024 * 1024;
+const gitSync = (args, cwd) => execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * MiB, stdio: ["ignore", "pipe", "pipe"] });
+const git = async (args, { cwd } = {}) => gitSync(args, cwd);
+const write = async (p, t) => { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, t); };
+const blob = (n, ch = "x") => ch.repeat(n);
+
+/** A fixture repo: {path: content}. Returns its dir. */
+function repo(files) {
+  const dir = tmpDir("wt4221-");
+  const r = join(dir, "r");
+  mkdirSync(r);
+  gitSync(["init", "-q", "-b", "main"], r);
+  for (const [p, c] of Object.entries(files)) { mkdirSync(dirname(join(r, p)), { recursive: true }); writeFileSync(join(r, p), c); }
+  gitSync(["add", "-A"], r);
+  gitSync(["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "init"], r);
+  return { dir, r, wt: join(dir, "wt") };
+}
+/** Bytes of regular files on disk under `d`, skipping .git. */
+function diskBytes(d) {
+  let n = 0;
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    if (e.name === ".git") continue;
+    const p = join(d, e.name);
+    if (e.isDirectory()) n += diskBytes(p); else if (e.isFile()) n += statSync(p).size;
+  }
+  return n;
+}
+
+const FIXTURES = {
+  "npm JS/TS": {
+    files: { "package.json": '{"name":"a","version":"1.0.0"}\n', "package-lock.json": `{"lockfileVersion":3,"pad":"${blob(MiB + 10)}"}\n`,
+      "tsconfig.json": "{}\n", "src/index.ts": "export const x = 1;\n", "public/asset.json": blob(2 * MiB) },
+    big: "public/asset.json", kept: ["package.json", "package-lock.json", "src/index.ts", "tsconfig.json"],
+  },
+  "uv Python": {
+    files: { "pyproject.toml": '[project]\nname = "a"\nversion = "0.1.0"\n', "uv.lock": `version = 1\n# ${blob(MiB + 10)}\n`,
+      "app/main.py": "print(1)\n", "data/blob.bin": blob(2 * MiB, "\u0001") },
+    big: "data/blob.bin", kept: ["pyproject.toml", "uv.lock", "app/main.py"],
+  },
+};
+
+describe("sparse lane worktrees (#4221)", () => {
+  for (const [name, fx] of Object.entries(FIXTURES)) {
+    it(`${name}: large blobs stay out, lockfiles and manifests stay in, git sees no change`, async () => {
+      const { dir, r, wt } = repo(fx.files);
+      try {
+        const res = await addLaneWorktree(git, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "feat/issue-1-lean", wt, "main"], ref: "main", maxBlobBytes: MiB });
+        assert.deepEqual(res, { sparse: true, excluded: 1, bytes: 2 * MiB });
+        assert.equal(existsSync(join(wt, fx.big)), false);
+        assert.match(gitSync(["ls-files", "-t", fx.big], wt), /^S /);
+        for (const k of fx.kept) assert.ok(existsSync(join(wt, k)), `${k} checked out`);
+        assert.equal(gitSync(["status", "--porcelain"], wt), "");
+        gitSync(["add", "-A"], wt);
+        assert.equal(gitSync(["diff", "--cached", "--name-only"], wt), "", "git add -A stages no deletion");
+        // R5: on-disk checkout is no more than the included blobs (+1 MiB slack): the left-out blob costs nothing.
+        const included = Object.entries(fx.files).filter(([p]) => p !== fx.big).reduce((n, [, c]) => n + Buffer.byteLength(c), 0);
+        assert.ok(diskBytes(wt) <= included + MiB, `disk ${diskBytes(wt)} <= ${included + MiB}`);
+        assert.throws(() => gitSync(["config", "--get", "core.sparseCheckout"], r), "main checkout has no core.sparseCheckout");
+        assert.equal(Object.keys(fx.files).every((p) => existsSync(join(r, p))), true);
+        mkdirSync(dirname(join(wt, fx.big)), { recursive: true });
+        writeFileSync(join(wt, fx.big), "regenerated\n");
+        assert.match(gitSync(["status", "--porcelain"], wt), new RegExp(` M ${fx.big}`));
+        gitSync(["checkout", "--", fx.big], wt);
+        gitSync(["sparse-checkout", "add", `/${fx.big}`], wt);
+        assert.equal(statSync(join(wt, fx.big)).size, 2 * MiB);
+      } finally { rmSync(dir, { recursive: true, force: true }); }
+    });
+  }
+
+  it("a repo with no large blob gets today's plain worktree add", async () => {
+    const { dir, r, wt } = repo({ "package.json": "{}\n", "src/a.js": "1\n" });
+    try {
+      const calls = [];
+      const spy = async (a, o) => { calls.push(a); return git(a, o); };
+      const addArgs = ["worktree", "add", "-B", "feat/issue-1-lean", wt, "main"];
+      assert.deepEqual(await addLaneWorktree(spy, write, { cwd: r, wt, addArgs, ref: "main" }), { sparse: false, excluded: 0, bytes: 0 });
+      assert.deepEqual(calls.filter((a) => a[0] === "worktree"), [addArgs]);
+      assert.equal(calls.some((a) => a[0] === "sparse-checkout"), false);
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  it("maxBlobBytes 0 disables it; a failing sparse step falls back to a full checkout", async () => {
+    const { dir, r, wt } = repo({ "a.bin": blob(2 * MiB), "b.txt": "1\n" });
+    try {
+      const calls = [];
+      const spy = async (a, o) => { calls.push(a); return git(a, o); };
+      await addLaneWorktree(spy, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "lane", wt, "main"], ref: "main", maxBlobBytes: 0 });
+      assert.equal(calls.some((a) => a[0] === "ls-tree" || a.includes("--no-checkout")), false);
+      assert.ok(existsSync(join(wt, "a.bin")));
+      gitSync(["worktree", "remove", "--force", wt], r);
+      const failing = async (a, o) => { if (a[0] === "read-tree" && !failing.done) { failing.done = true; throw Object.assign(new Error("boom"), { stderr: "fatal: boom" }); } return git(a, o); };
+      const res = await addLaneWorktree(failing, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "lane", wt, "main"], ref: "main", maxBlobBytes: MiB });
+      assert.equal(res.sparse, false);
+      assert.match(res.fallback, /boom/);
+      assert.ok(existsSync(join(wt, "a.bin")) && existsSync(join(wt, "b.txt")));
+      assert.equal(gitSync(["status", "--porcelain"], wt), "");
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  it("a failing worktree add is rethrown unchanged (the caller retries lock races)", async () => {
+    const e = Object.assign(new Error("lock"), { stderr: "could not lock config file" });
+    const g = async (a) => { if (a[0] === "worktree") throw e; return "100644 blob " + "a".repeat(40) + " 2000000\tbig.bin\0"; };
+    await assert.rejects(addLaneWorktree(g, write, { cwd: "/x", wt: "/x/wt", addArgs: ["worktree", "add", "/x/wt", "main"], ref: "main" }), (x) => x === e);
+  });
+
+  it("sparsePlan: threshold, keep-list, symlinks and gitlinks; patterns escape glob characters", () => {
+    const h = "a".repeat(40);
+    const out = [
+      `100644 blob ${h} 2000000\tweb/openapi.json`, `100755 blob ${h} 1048576\tbin/tool`, `100644 blob ${h}  1048575\tsmall.txt`,
+      `120000 blob ${h}      40\tlink`, `160000 commit ${h}       -\tsub`, `100644 blob ${h} 3000000\tpnpm-lock.yaml`,
+      `100644 blob ${h} 3000000\tsvc/requirements-dev.txt`, `100644 blob ${h} 3000000\tpkg/tsconfig.base.json`, `100644 blob ${h} 5000000\ta [x]*?.bin `,
+    ].join("\0") + "\0";
+    const p = sparsePlan(out, { maxBlobBytes: MiB });
+    assert.deepEqual(p.excludes, ["web/openapi.json", "bin/tool", "a [x]*?.bin "]);
+    assert.equal(p.bytes, 2000000 + 1048576 + 5000000);
+    assert.deepEqual(sparsePlan(out, { maxBlobBytes: 0 }).excludes, []);
+    assert.deepEqual(sparsePatterns(p.excludes), ["/*", "!/web/openapi.json", "!/bin/tool", "!/a \\[x]\\*\\?.bin\\ "]);
+  });
+
+  it("an escaped pattern really matches its odd path", async () => {
+    const odd = "d/a [x]*?.bin";
+    const { dir, r, wt } = repo({ [odd]: blob(2 * MiB), "d/a x.bin": "keep\n", "f.txt": "1\n" });
+    try {
+      const res = await addLaneWorktree(git, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "lane", wt, "main"], ref: "main", maxBlobBytes: MiB });
+      assert.equal(res.sparse, true);
+      assert.equal(existsSync(join(wt, odd)), false);
+      assert.ok(existsSync(join(wt, "d/a x.bin")));
+      assert.equal(gitSync(["status", "--porcelain"], wt), "");
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+});