forgedock 1.27.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

@@ -11,6 +11,8 @@ 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). */
@@ -20,7 +22,7 @@ const OK = ["success", "neutral", "skipped"];
 
 /**
  * forge.yaml `verify:` section (block style; parseForgeYaml gives strings) → {mode, workflow, pathsInput, skipPaths,
- * maxRounds}. Invalid values fall back to the defaults; mode defaults to local (today's behaviour).
+ * 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 : {};
@@ -32,7 +34,9 @@ export function parseVerify(sec = {}) {
   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;
-  return { mode, workflow, pathsInput, skipPaths, maxRounds };
+  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(".*")}$`);
@@ -55,6 +59,19 @@ export function capLogs(failures, cap = LOG_CAP) {
   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));
 
 /**
@@ -97,13 +114,7 @@ export async function runCiVerify({ io, branch, head, changedFiles, verify, ciMa
       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` };
-        const logs = {}, out = [];
-        for (const c of failed) {
-          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 { result: "fail", failures: capLogs(out), runUrl: failed[0].url ?? null, detail: `${failed.length} check(s) failed: ${failed.map((c) => c.name).join(", ")}` };
+        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` };

package/bin/lean/verify.test.mjs

@@ -2,7 +2,7 @@
 // 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, DEFAULT_SKIP_PATHS, LOG_CAP } from "./verify.mjs";
+import { parseVerify, matchesGlob, skipsCi, capLogs, runCiVerify, collectFailedLogs, DEFAULT_SKIP_PATHS, LOG_CAP } from "./verify.mjs";
 import { precheck } from "./conformance.mjs";
 
 const HEAD = "abc123abc123abc123";
@@ -22,9 +22,9 @@ function fake(o = {}) {
 
 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 });
+    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 });
+    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);
@@ -93,3 +93,26 @@ describe("runCiVerify (#4167)", () => {
     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 }); }
+  });
+});

package/bin/runner.mjs

@@ -359,6 +359,37 @@ export function resolveConfiguredDefaultModel(cwd) {
   }
 }
 
+/**
+ * Whether the owner approved the paid API backend as the `auto` fallback (#4257).
+ * Needs both forge.yaml `execution.agent_backend: api` in `cwd` (repo owner) and
+ * env `FORGEDOCK_ALLOW_API_BACKEND=1` (host owner), so a committed config edit
+ * alone cannot start billing an API key. Never throws.
+ *
+ * @param {{cwd?: string, env?: object}} [opts]
+ * @returns {boolean}
+ */
+export function isApiBackendApproved({ cwd = process.cwd(), env = process.env } = {}) {
+  if (String(env?.FORGEDOCK_ALLOW_API_BACKEND ?? "").trim() !== "1") return false;
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (!existsSync(forgeYamlPath)) return false;
+    return parseForgeYaml(readFileSync(forgeYamlPath, "utf-8"))?.execution?.agent_backend === "api";
+  } catch {
+    return false;
+  }
+}
+
+/** #4257: typed error when `auto` finds no usable CLI and the API backend is not approved. */
+function cliUnavailableError(detail = "The claude CLI is not available") {
+  const err = new Error(
+    `${detail}, and the API backend is never used implicitly. Install and authenticate the \`claude\` CLI, ` +
+      "or opt in to the API backend (forge.yaml `execution.agent_backend: api` plus FORGEDOCK_ALLOW_API_BACKEND=1), " +
+      "or pass --backend api.",
+  );
+  err.code = "CLI_BACKEND_UNAVAILABLE";
+  return err;
+}
+
 /**
  * Resolve the CLI backend timeout from forge.yaml's
  * `pipeline.cli_timeout_minutes` field, if it is a positive integer.
@@ -854,6 +885,7 @@ export function checkExecutionBackend({
   apiKey = env.ANTHROPIC_API_KEY,
   resolveCliFn = resolveClaudeCliBinary,
   spawnImpl = spawnSync,
+  apiApproved = isApiBackendApproved({ cwd, env }),
   sdkAvailableFn = () => {
     try {
       createRequire(import.meta.url).resolve("@anthropic-ai/sdk");
@@ -884,7 +916,8 @@ export function checkExecutionBackend({
         return { ready: true, backend: "cli", reason: "resolved-cli" };
       }
     }
-    if (requested === "cli") {
+    // #4257: auto never crosses to the paid API backend without the owner's opt-in.
+    if (requested === "cli" || !apiApproved) {
       return { ready: false, backend: "cli", reason: "cli-unavailable" };
     }
   }
@@ -905,7 +938,8 @@ export function checkExecutionBackend({
  * CLI and prefer it when present — but diverge on (a) which override
  * values are valid and whether an invalid one throws or is silently
  * ignored, and (b) what to return when the CLI probe fails (`resolveBackend`
- * always falls back to `"api"`; `resolveEnrichBackend` falls back to `"api"`
+ * falls back to `"api"` only with the owner's opt-in, else `"cli"` (#4257);
+ * `resolveEnrichBackend` falls back to `"api"`
  * only if `ANTHROPIC_API_KEY` is set, else `"none"`). Rather than force
  * those into one shape, this shared helper implements exactly the common
  * two steps and defers to a `cliFallback` callback for the diverging tail,
@@ -954,24 +988,27 @@ export function resolveBackendLadder({
  *   2. `"auto"` (the default) probes `isClaudeCliAvailable()`: prefers the
  *      CLI backend when a working `claude` install is detected (reuses
  *      whatever credentials the CLI already has — Pro/Max OAuth or a
- *      CLI-managed key — with no ANTHROPIC_API_KEY required), otherwise
- *      falls back to the API backend unchanged (existing behavior for every
- *      caller that never opts in to this feature).
+ *      CLI-managed key — with no ANTHROPIC_API_KEY required). Without a CLI it
+ *      falls back to the API backend ONLY when the owner opted in
+ *      (`isApiBackendApproved()`, #4257); otherwise it returns `"cli"` and
+ *      `runCommand()` fails with a typed `CLI_BACKEND_UNAVAILABLE`. The API
+ *      backend is never the implicit default.
  *
  * Delegates its shared "override-or-probe-CLI" shape to
  * `resolveBackendLadder()` (issue #2026) — this function retains its own
  * `VALID_BACKENDS` throw-on-invalid check (NOT shared; see that helper's
- * doc comment) and its own no-API-key-check fallback (always `"api"`,
- * unconditionally — the API key itself is validated lazily downstream, only
+ * doc comment) and its own opt-in-gated fallback (`"api"` only when
+ * approved — the API key itself is validated lazily downstream, only
  * if/when the api backend is actually selected).
  *
  * @param {object} [opts]
  * @param {string} [opts.requested] - "cli" | "api" | "auto" (default "auto").
  * @param {string} [opts.cwd]       - Working directory for the CLI probe.
  * @param {object} [opts.env]       - Runtime environment used for capability checks.
+ * @param {Function} [opts.isCliAvailableFn] - Injectable CLI-presence probe (test seam).
  * @returns {"cli"|"api"}
  */
-export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env } = {}) {
+export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env, isCliAvailableFn = isClaudeCliAvailable } = {}) {
   if (!VALID_BACKENDS.has(requested)) {
     throw new Error(
       `Invalid backend "${requested}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`,
@@ -982,7 +1019,8 @@ export function resolveBackend({ requested = "auto", cwd = process.cwd(), env =
     override: requested === "auto" ? undefined : requested,
     validOverrides: new Set(["cli", "api"]),
     cwd,
-    cliFallback: () => "api",
+    isCliAvailableFn,
+    cliFallback: () => (isApiBackendApproved({ cwd, env }) ? "api" : "cli"),
   });
 }
 
@@ -2789,7 +2827,9 @@ export function renderSummaryCard(ctx) {
  * @param {string} [opts.backend]            - "cli" | "api" | "auto" (default
  *   "auto"). Resolution order when omitted: $FORGEDOCK_BACKEND env > "auto".
  *   "auto" prefers the local Claude Code CLI when detected (no
- *   ANTHROPIC_API_KEY needed), else falls back to the API backend. This
+ *   ANTHROPIC_API_KEY needed); without a CLI it uses the API backend only
+ *   with the owner's opt-in (`isApiBackendApproved()`, #4257), else it fails
+ *   with a typed CLI_BACKEND_UNAVAILABLE — api is never the default. This
  *   precedence is intentional/shipped (issue #2003's accepted acceptance
  *   criteria) and is NOT changed by issue #2020 — that issue only adds a
  *   discoverability notice (below) for the case where the ladder silently
@@ -2840,6 +2880,7 @@ export async function runCommand(opts = {}) {
 
   if (resolvedBackend === "cli" && backend === "auto") {
     const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey, env: runtimeEnv });
+    // #4257: readiness only reports api when the owner approved it.
     if (readiness.backend === "api") resolvedBackend = "api";
   }
 
@@ -2938,6 +2979,8 @@ export async function runCommand(opts = {}) {
       sessionFlags = buildMinimalSessionFlags(commandName, caps);
     }
     if (!resolvedBin && backend === "auto") {
+      // #4257: never cross to the paid API backend without the owner's opt-in.
+      if (!isApiBackendApproved({ cwd, env: runtimeEnv })) throw cliUnavailableError();
       resolvedBackend = "api";
     } else if (!resolvedBin) {
       const err = new Error("The configured claude CLI path disappeared before invocation.");

package/bin/stats/github-source.mjs

@@ -163,7 +163,7 @@ async function* listIssuePages(gh, repo, startSince) {
 }
 
 const meta = (it) => ({ number: it.number, isPr: Boolean(it.pull_request), createdAt: it.created_at ?? null, closedAt: it.closed_at ?? null,
-  updatedAt: it.updated_at ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
+  updatedAt: it.updated_at ?? null, milestone: it.milestone?.title ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
 
 const CHECKPOINT_EVERY = 1000;
 const RATE_CHECK_EVERY = 50;