forgedock 1.30.0 → 1.31.0

package/bin/lean/ledger.mjs

@@ -48,9 +48,11 @@ export function dockerLabels({ batch, lane, issue, expires } = {}) {
   return [`forgedock.owner=1`, `forgedock.batch=${v(batch)}`, `forgedock.lane=${v(lane)}`, `forgedock.issue=${v(issue)}`, `forgedock.expires=${v(expires)}`];
 }
 
-export function makeLedger({ root = ledgerRoot(), batch = "adhoc", lane, owner, issue, host = hostname(), pid = process.pid, now = () => Date.now(), ttlMs = LEDGER_TTL_MS, fs = nodeFs } = {}) {
+/** #4432: with a `repo`, the lane file is `<batch>/<owner>__<repo>__<lane>.json` (issue numbers, hence lane names, are per repo). */
+export function makeLedger({ root = ledgerRoot(), batch = "adhoc", lane, owner, issue, repo = null, host = hostname(), pid = process.pid, now = () => Date.now(), ttlMs = LEDGER_TTL_MS, fs = nodeFs } = {}) {
   const dir = join(root, safeSegment(batch));
-  const path = join(dir, `${safeSegment(lane ?? `lane-${issue}`)}.json`);
+  const repoPrefix = repo ? `${String(repo).split("/").map(safeSegment).join("__")}__` : "";
+  const path = join(dir, `${repoPrefix}${safeSegment(lane ?? `lane-${issue}`)}.json`);
   const read = () => { try { const j = JSON.parse(fs.readFileSync(path, "utf8")); return j && typeof j === "object" && Array.isArray(j.resources) ? j : null; } catch { return null; } };
   const write = (j) => {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -58,7 +60,7 @@ export function makeLedger({ root = ledgerRoot(), batch = "adhoc", lane, owner,
     fs.writeFileSync(tmp, JSON.stringify(j, null, 2) + "\n");
     fs.renameSync(tmp, path);
   };
-  const fresh = () => { const c = now(); return { v: 1, owner, batch: String(batch), lane: String(lane ?? `lane-${issue}`), issue, host, pid, created: c, expires: c + ttlMs, resources: [] }; };
+  const fresh = () => { const c = now(); return { v: 1, owner, batch: String(batch), lane: String(lane ?? `lane-${issue}`), issue, ...(repo ? { repo: String(repo) } : {}), host, pid, created: c, expires: c + ttlMs, resources: [] }; };
   const same = (r, kind, value) => r.kind === kind && String(r.value) === String(value);
   return {
     path,

package/bin/lean/ledger.test.mjs

@@ -54,6 +54,24 @@ describe("lane resource ledger (#4179)", () => {
   });
 });
 
+describe("repo-scoped lane files (#4432)", () => {
+  it("ledgers of two repos with the same lane are separate files", () => {
+    const root = tmpDir("ledger-");
+    const one = makeLedger({ root, batch: "adhoc", lane: "lean-2", owner: "core_1", issue: 2, repo: "acme/one" });
+    const two = makeLedger({ root, batch: "adhoc", lane: "lean-2", owner: "core_2", issue: 2, repo: "acme/two" });
+    assert.equal(one.path, join(root, "adhoc", "acme__one__lean-2.json"));
+    assert.notEqual(one.path, two.path);
+    one.register("worktree", "/one/.claude/worktrees/lean-2");
+    two.register("worktree", "/two/.claude/worktrees/lean-2");
+    one.release("worktree", "/one/.claude/worktrees/lean-2");
+    assert.deepEqual(two.entries().map((r) => r.value), ["/two/.claude/worktrees/lean-2"], "one repo's teardown leaves the other's resources");
+    assert.equal(JSON.parse(readFileSync(two.path, "utf8")).repo, "acme/two");
+    assert.equal(JSON.parse(readFileSync(two.path, "utf8")).lane, "lean-2", "the lane field is unchanged");
+    const legacy = makeLedger({ root, batch: "adhoc", lane: "lean-2", issue: 2 });
+    assert.equal(legacy.path, join(root, "adhoc", "lean-2.json"), "no repo: unchanged path");
+  });
+});
+
 describe("live lane count (#4182)", () => {
   it("counts only live, same-host, unexpired lane files across batches, and deletes nothing", async () => {
     const { mkdirSync, writeFileSync } = await import("node:fs");

package/bin/lean/light.mjs

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Light-lane eligibility and upgrade triggers (#4448, parent #4442). Rules first: an issue is eligible for the light
+ * lane (one builder session, deterministic gates) when it has a concrete repro or expected behaviour, predicts 1..max_files
+ * non-test files, is size S, touches no risk path and is not an investigation, post-deploy or decision issue. A missing
+ * repro or file prediction is `ambiguous` (the caller's cheap classifier decides). During a light lane, any upgrade
+ * trigger (oversized diff, repro not red on base, two test failures, risk path, public-API-shape change from #4449)
+ * moves the lane to the full pipeline. forge.yaml `lean.light` {mode: off|shadow (default)|on, max_lines: 40,
+ * max_files: 2}: off is never eligible, shadow reports the verdict without changing the lane shape, on lets an eligible
+ * issue run light (lane wiring: #4450). Pure: no I/O, no model call.
+ */
+import { riskClassOf, riskPathHits } from "./review-trigger.mjs";
+import { classifyPath } from "./routing.mjs";
+import { laneSize } from "./budget.mjs";
+import { isInvestigation } from "./conformance.mjs";
+import { postDeployOnly } from "./prefilter.mjs";
+
+export const LIGHT_MODES = Object.freeze(["off", "shadow", "on"]);
+export const LIGHT_DEFAULTS = Object.freeze({ mode: "shadow", maxLines: 40, maxFiles: 2 });
+
+const posInt = (v) => { const s = String(v ?? "").trim(); return /^\d+$/.test(s) && Number(s) > 0 ? Number(s) : null; };
+
+/**
+ * forge.yaml lean section -> {mode, maxLines, maxFiles}. The one-level parser flattens a nested `light:` block to
+ * `lean.mode|max_lines|max_files`; flat `lean.light_mode|light_max_lines|light_max_files` also work and win.
+ * An unknown mode is shadow; a limit that is not a positive integer keeps its default.
+ */
+export function parseLightConfig(lean = {}) {
+  const l = lean && typeof lean === "object" ? lean : {};
+  const m = String(l.light_mode ?? l.mode ?? "").trim().toLowerCase();
+  return {
+    mode: LIGHT_MODES.includes(m) ? m : LIGHT_DEFAULTS.mode,
+    maxLines: posInt(l.light_max_lines) ?? posInt(l.max_lines) ?? LIGHT_DEFAULTS.maxLines,
+    maxFiles: posInt(l.light_max_files) ?? posInt(l.max_files) ?? LIGHT_DEFAULTS.maxFiles,
+  };
+}
+
+/** A parsed config, or the defaults merged with whatever valid fields `cfg` carries. */
+const cfgOf = (cfg) => {
+  const c = cfg && typeof cfg === "object" ? cfg : {};
+  return {
+    mode: LIGHT_MODES.includes(c.mode) ? c.mode : LIGHT_DEFAULTS.mode,
+    maxLines: posInt(c.maxLines) ?? LIGHT_DEFAULTS.maxLines,
+    maxFiles: posInt(c.maxFiles) ?? LIGHT_DEFAULTS.maxFiles,
+  };
+};
+
+const uniquePaths = (xs) => [...new Set((Array.isArray(xs) ? xs : []).map((p) => String(p ?? "").trim().replace(/^\.\//, "")).filter(Boolean))].sort();
+const labelNames = (labels) => (Array.isArray(labels) ? labels : []).map((l) => String(l?.name ?? l ?? "").trim()).filter(Boolean);
+const sortReasons = (rs) => rs.sort((a, b) => a.code.localeCompare(b.code) || a.detail.localeCompare(b.detail));
+
+const REPRO_RE = /steps to reproduce|\brepro(duction|duce)?\b|\bexpected[ _-]+(behaviou?r|result|output)\b|\bactual[ _-]+(behaviou?r|result|output)\b/i;
+const FENCE_RE = /^\s*(```|~~~)/m;
+const DECISION_LABEL_RE = /^(type[:/]\s*)?(decision|needs-decision|product-decision|rfc|adr)$/i;
+const DECISION_TITLE_RE = /^\s*(decision|rfc|adr)[(:]/i;
+const POST_DEPLOY_LABELS = new Set(["post-deploy", "awaiting-promotion"]);
+
+/** Risk details for `files`: a built-in risk word or a declared review.risk_paths glob. */
+function riskDetails(files, riskPaths) {
+  const declared = new Set(riskPathHits(files, riskPaths));
+  const out = [];
+  for (const f of files) {
+    const cls = riskClassOf(f);
+    if (cls) out.push(`${f} (${cls})`);
+    else if (declared.has(f)) out.push(`${f} (review.risk_paths)`);
+  }
+  return out;
+}
+
+/**
+ * Light-lane eligibility of one issue: {mode, verdict, eligible, light, reasons:[{code, detail}]}.
+ * verdict: off | eligible | ineligible (a hard reason: files, size, risk_path, investigate, post_deploy, decision) |
+ * ambiguous (only soft reasons: no_repro, files_unknown). `light` is the lane shape: true only in mode on when eligible.
+ */
+export function lightEligibility({ title = "", body = "", labels = [], predictedFiles = [], riskPaths = [], cfg = {} } = {}) {
+  const c = cfgOf(cfg);
+  if (c.mode === "off") return { mode: "off", verdict: "off", eligible: false, light: false, reasons: [] };
+  const hard = [], soft = [];
+  const text = String(body ?? "").replace(/<!--[\s\S]*?-->/g, " ");
+  if (!FENCE_RE.test(text) && !REPRO_RE.test(text)) soft.push({ code: "no_repro", detail: "no repro, expected behaviour or code block in the body" });
+
+  const files = uniquePaths(predictedFiles);
+  const nonTest = files.filter((f) => classifyPath(f) !== "test");
+  if (nonTest.length > c.maxFiles) hard.push({ code: "files", detail: `${nonTest.length} predicted non-test files (max ${c.maxFiles})` });
+  else if (!nonTest.length) soft.push({ code: "files_unknown", detail: "no predicted non-test files" });
+
+  const names = labelNames(labels);
+  const size = laneSize({ labels: names });
+  if (size && size !== "S") hard.push({ code: "size", detail: `size:${size}` });
+
+  for (const d of riskDetails(files, riskPaths)) hard.push({ code: "risk_path", detail: d });
+
+  if (isInvestigation(title)) hard.push({ code: "investigate", detail: "investigate( issue" });
+  const pdLabel = names.find((n) => POST_DEPLOY_LABELS.has(n.toLowerCase()));
+  if (pdLabel) hard.push({ code: "post_deploy", detail: `label ${pdLabel}` });
+  else if (postDeployOnly(body)) hard.push({ code: "post_deploy", detail: "every checklist item is a post-deploy check" });
+  const decLabel = names.find((n) => DECISION_LABEL_RE.test(n));
+  if (decLabel) hard.push({ code: "decision", detail: `label ${decLabel}` });
+  else if (DECISION_TITLE_RE.test(String(title ?? ""))) hard.push({ code: "decision", detail: "decision title" });
+
+  const verdict = hard.length ? "ineligible" : soft.length ? "ambiguous" : "eligible";
+  const eligible = verdict === "eligible";
+  return { mode: c.mode, verdict, eligible, light: c.mode === "on" && eligible, reasons: sortReasons([...hard, ...soft]) };
+}
+
+const lineCount = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? n : 0; };
+
+/**
+ * Upgrade triggers of a light lane: {upgrade, reasons:[{code, detail}]}. diff: {files:[{path, added, deleted}]}
+ * (git numstat; "-" binary counts 0). repro: {base, head} words of scripts/acceptance-red-green.sh. testFailures: count
+ * of failed targeted-test runs. apiShape: public-API-shape changes from #4449 (strings or {symbol, kind}).
+ * Codes: diff_lines, diff_files (non-test files only), repro_not_red, tests_failed_twice, risk_path (every path), api_shape.
+ */
+export function upgradeTriggers({ diff = null, repro = null, testFailures = 0, riskPaths = [], apiShape = [], cfg = {} } = {}) {
+  const c = cfgOf(cfg);
+  const reasons = [];
+  const rows = (Array.isArray(diff?.files) ? diff.files : []).filter((f) => f && String(f.path ?? "").trim());
+  const nonTest = rows.filter((f) => classifyPath(String(f.path).trim()) !== "test");
+  const lines = nonTest.reduce((n, f) => n + lineCount(f.added) + lineCount(f.deleted), 0);
+  if (lines > c.maxLines) reasons.push({ code: "diff_lines", detail: `${lines} non-test lines (max ${c.maxLines})` });
+  const nFiles = uniquePaths(nonTest.map((f) => f.path)).length;
+  if (nFiles > c.maxFiles) reasons.push({ code: "diff_files", detail: `${nFiles} non-test files (max ${c.maxFiles})` });
+  const base = repro && typeof repro === "object" ? String(repro.base ?? "") : "";
+  if (base !== "FAILED") reasons.push({ code: "repro_not_red", detail: base ? `repro on base: ${base}` : "no repro result" });
+  const fails = Number(testFailures);
+  if (Number.isFinite(fails) && fails >= 2) reasons.push({ code: "tests_failed_twice", detail: `${fails} failed test runs` });
+  for (const d of riskDetails(uniquePaths(rows.map((f) => f.path)), riskPaths)) reasons.push({ code: "risk_path", detail: d });
+  for (const a of Array.isArray(apiShape) ? apiShape : []) {
+    const d = typeof a === "string" ? a.trim() : a && typeof a === "object" ? [a.symbol, a.kind].filter(Boolean).map(String).join(": ") : "";
+    if (d) reasons.push({ code: "api_shape", detail: d });
+  }
+  sortReasons(reasons);
+  return { upgrade: reasons.length > 0, reasons };
+}

package/bin/lean/light.test.mjs

@@ -0,0 +1,173 @@
+// 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 { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { LIGHT_MODES, LIGHT_DEFAULTS, parseLightConfig, lightEligibility, upgradeTriggers } from "./light.mjs";
+import { readLight } from "../engine-cli.mjs";
+
+const ON = { mode: "on", maxLines: 40, maxFiles: 2 };
+const BODY = "## Steps to reproduce\n```js\nchunk([1, 2], 0)\n```\nExpected behaviour: a ValueError.";
+/** A fully eligible issue; override one field to break one rule. */
+const issue = (o = {}) => ({ title: "fix(chunk): reject n=0", body: BODY, labels: ["bug", "size:S"], predictedFiles: ["src/chunk.py", "tests/test_chunk.py"], riskPaths: [], cfg: ON, ...o });
+const codes = (r) => r.reasons.map((x) => x.code);
+const numstat = (...rows) => ({ files: rows.map(([path, added, deleted = 0]) => ({ path, added, deleted })) });
+const RED = { base: "FAILED", head: "RAN" };
+
+describe("parseLightConfig (#4448)", () => {
+  it("defaults to shadow, 40 lines, 2 files", () => {
+    assert.deepEqual(LIGHT_MODES, ["off", "shadow", "on"]);
+    assert.deepEqual(parseLightConfig(), LIGHT_DEFAULTS);
+    assert.deepEqual(parseLightConfig(null), { mode: "shadow", maxLines: 40, maxFiles: 2 });
+  });
+  it("reads the flattened nested keys; flat light_* keys win; junk keeps the default", () => {
+    assert.deepEqual(parseLightConfig({ mode: "ON", max_lines: "60", max_files: "3" }), { mode: "on", maxLines: 60, maxFiles: 3 });
+    assert.deepEqual(parseLightConfig({ mode: "on", light_mode: "off", max_lines: "60", light_max_lines: "80", light_max_files: "1" }), { mode: "off", maxLines: 80, maxFiles: 1 });
+    assert.deepEqual(parseLightConfig({ mode: "enforce", max_lines: "0", max_files: "-1" }), LIGHT_DEFAULTS);
+    assert.deepEqual(parseLightConfig({ light_max_lines: "4x" }), LIGHT_DEFAULTS);
+  });
+  it("readLight reads forge.yaml lean.light; absent forge.yaml is the defaults", () => {
+    const d = tmpDir("light-yaml-");
+    assert.deepEqual(readLight(d), LIGHT_DEFAULTS);
+    writeFileSync(join(d, "forge.yaml"), "lean:\n  light:\n    mode: on\n    max_lines: 50\n    max_files: 3\n");
+    assert.deepEqual(readLight(d), { mode: "on", maxLines: 50, maxFiles: 3 });
+    writeFileSync(join(d, "forge.yaml"), "lean:\n  light_mode: off\n");
+    assert.equal(readLight(d).mode, "off");
+  });
+});
+
+describe("lightEligibility rules (#4448)", () => {
+  it("accepts a well-specified size:S issue with 1-2 predicted files", () => {
+    const r = lightEligibility(issue());
+    assert.deepEqual(r, { mode: "on", verdict: "eligible", eligible: true, light: true, reasons: [] });
+  });
+  it("repro or expected behaviour: present accepts, absent is ambiguous (never a model call)", () => {
+    for (const body of ["Repro: `x()` throws", "Expected result: 3", "```\nboom\n```", "actual output differs"]) assert.equal(lightEligibility(issue({ body })).verdict, "eligible", body);
+    const r = lightEligibility(issue({ body: "It is broken. <!-- steps to reproduce -->" }));
+    assert.equal(r.verdict, "ambiguous");
+    assert.equal(r.eligible, false);
+    assert.equal(r.light, false);
+    assert.deepEqual(codes(r), ["no_repro"]);
+  });
+  it("predicted files: 1 or 2 non-test files accept, 3 reject, tests do not count, none is ambiguous", () => {
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/a.py"] })).verdict, "eligible");
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/a.py", "src/b.py", "tests/test_a.py", "src/c.test.ts"] })).verdict, "eligible");
+    const r = lightEligibility(issue({ predictedFiles: ["src/a.py", "src/b.py", "src/c.py"] }));
+    assert.equal(r.verdict, "ineligible");
+    assert.deepEqual(codes(r), ["files"]);
+    assert.deepEqual(codes(lightEligibility(issue({ predictedFiles: [] }))), ["files_unknown"]);
+    assert.equal(lightEligibility(issue({ predictedFiles: ["tests/test_a.py"] })).verdict, "ambiguous");
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/a.py", "src/b.py", "src/c.py"], cfg: { ...ON, maxFiles: 3 } })).verdict, "eligible");
+  });
+  it("size: size:S accepts, size:M and size:L reject", () => {
+    assert.equal(lightEligibility(issue({ labels: [{ name: "size:S" }] })).verdict, "eligible");
+    assert.equal(lightEligibility(issue({ labels: [] })).verdict, "eligible");
+    for (const s of ["size:M", "size:L"]) {
+      const r = lightEligibility(issue({ labels: ["bug", s] }));
+      assert.equal(r.verdict, "ineligible", s);
+      assert.deepEqual(codes(r), ["size"]);
+    }
+  });
+  it("risk path: a built-in risk word or a declared review.risk_paths glob rejects; a clean path accepts", () => {
+    const w = lightEligibility(issue({ predictedFiles: ["src/auth/login.ts"] }));
+    assert.deepEqual(codes(w), ["risk_path"]);
+    assert.match(w.reasons[0].detail, /src\/auth\/login\.ts \(auth\)/);
+    const g = lightEligibility(issue({ predictedFiles: ["src/detect/rules.ts"], riskPaths: "src/detect/**" }));
+    assert.deepEqual(codes(g), ["risk_path"]);
+    assert.match(g.reasons[0].detail, /review\.risk_paths/);
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/chunk.py"], riskPaths: ["src/detect/**"] })).verdict, "eligible");
+  });
+  it("kind: investigate(, post-deploy and decision issues reject; a plain bug accepts", () => {
+    assert.deepEqual(codes(lightEligibility(issue({ title: "investigate(lean): why lanes stall" }))), ["investigate"]);
+    assert.deepEqual(codes(lightEligibility(issue({ labels: ["awaiting-promotion"] }))), ["post_deploy"]);
+    assert.deepEqual(codes(lightEligibility(issue({ labels: ["post-deploy"] }))), ["post_deploy"]);
+    const pd = "Post-deploy checks.\n```\nx\n```\n- [ ] `R3: verify in prod` — post-deploy: needs a deploy\n";
+    assert.deepEqual(codes(lightEligibility(issue({ body: pd }))), ["post_deploy"]);
+    for (const labels of [["decision"], ["needs-decision"], ["type:decision"], ["product-decision"], ["RFC"], ["adr"]]) assert.deepEqual(codes(lightEligibility(issue({ labels }))), ["decision"], labels[0]);
+    for (const title of ["decision(lean): pick a queue", "RFC: light lanes", "adr(engine): leases"]) assert.deepEqual(codes(lightEligibility(issue({ title }))), ["decision"], title);
+    assert.equal(lightEligibility(issue({ title: "fix: decision table off by one", labels: ["bug"] })).verdict, "eligible");
+  });
+  it("hard reasons win over soft ones; reasons are sorted and deterministic", () => {
+    const o = issue({ body: "broken", labels: ["size:L", "decision"], predictedFiles: ["src/billing.ts", "a.py", "b.py"] });
+    const r = lightEligibility(o);
+    assert.equal(r.verdict, "ineligible");
+    assert.deepEqual(codes(r), ["decision", "files", "no_repro", "risk_path", "size"]);
+    assert.deepEqual(lightEligibility({ ...o, predictedFiles: [...o.predictedFiles].reverse() }), r);
+  });
+  it("tolerates missing and junk input", () => {
+    assert.equal(lightEligibility().verdict, "ambiguous");
+    assert.doesNotThrow(() => lightEligibility({ title: null, body: null, labels: "x", predictedFiles: "y", riskPaths: 3, cfg: null }));
+  });
+});
+
+describe("lightEligibility modes (#4448)", () => {
+  it("off never returns eligible, even for a fully eligible issue", () => {
+    assert.deepEqual(lightEligibility(issue({ cfg: { mode: "off" } })), { mode: "off", verdict: "off", eligible: false, light: false, reasons: [] });
+  });
+  it("shadow returns the verdict without changing the lane shape", () => {
+    const r = lightEligibility(issue({ cfg: { mode: "shadow" } }));
+    assert.equal(r.verdict, "eligible");
+    assert.equal(r.eligible, true);
+    assert.equal(r.light, false);
+    assert.equal(lightEligibility(issue({ cfg: {} })).mode, "shadow", "default mode");
+    assert.equal(lightEligibility(issue({ cfg: { mode: "shadow" }, labels: ["size:M"] })).verdict, "ineligible");
+  });
+  it("on runs an eligible issue light and never an ineligible one", () => {
+    assert.equal(lightEligibility(issue()).light, true);
+    assert.equal(lightEligibility(issue({ labels: ["size:M"] })).light, false);
+    assert.equal(lightEligibility(issue({ body: "broken" })).light, false);
+  });
+});
+
+describe("upgradeTriggers (#4448)", () => {
+  const quiet = { diff: numstat(["src/chunk.py", 30, 10], ["tests/test_chunk.py", 200]), repro: RED, testFailures: 1, cfg: ON };
+  it("no trigger on a small red-green diff", () => {
+    assert.deepEqual(upgradeTriggers(quiet), { upgrade: false, reasons: [] });
+  });
+  it("oversized diff by lines: 41 non-test lines fire, 40 do not, test lines are ignored, max_lines is honoured", () => {
+    const r = upgradeTriggers({ ...quiet, diff: numstat(["src/chunk.py", 31, 10], ["tests/test_chunk.py", 500]) });
+    assert.equal(r.upgrade, true);
+    assert.deepEqual(codes(r), ["diff_lines"]);
+    assert.match(r.reasons[0].detail, /41 non-test lines \(max 40\)/);
+    assert.equal(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 41], ["src/b.py", "-", "-"]), cfg: { ...ON, maxLines: 41 } }).upgrade, false);
+  });
+  it("oversized diff by files: 3 non-test files fire, 2 do not", () => {
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 1], ["src/b.py", 1], ["src/c.py", 1]) })), ["diff_files"]);
+    assert.equal(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 1], ["src/b.py", 1], ["tests/test_a.py", 1]) }).upgrade, false);
+  });
+  it("non-red repro: anything but FAILED on base fires, a missing repro included", () => {
+    for (const base of ["RAN", "RAN_NOTHING", "UNRUNNABLE", "SKIPPED"]) assert.deepEqual(codes(upgradeTriggers({ ...quiet, repro: { base, head: "RAN" } })), ["repro_not_red"], base);
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, repro: null })), ["repro_not_red"]);
+    assert.equal(upgradeTriggers({ ...quiet, repro: RED }).upgrade, false);
+  });
+  it("tests fail twice: 2 failures fire, 1 does not", () => {
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, testFailures: 2 })), ["tests_failed_twice"]);
+    assert.equal(upgradeTriggers({ ...quiet, testFailures: 1 }).upgrade, false);
+  });
+  it("risk path: a risk word or declared glob on any diff path fires, tests included; a clean diff does not", () => {
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["src/session.ts", 2]) })), ["risk_path"]);
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 2], ["tests/test_payments.py", 2]) })), ["risk_path"]);
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["lib/detect.py", 2]), riskPaths: "lib/detect.py" })), ["risk_path"]);
+    assert.equal(upgradeTriggers({ ...quiet, riskPaths: ["lib/**"] }).upgrade, false);
+  });
+  it("public-API-shape changes (#4449) plug in as one more input", () => {
+    const r = upgradeTriggers({ ...quiet, apiShape: ["ichunked: generator -> function", { symbol: "chunk", kind: "signature" }, "", null] });
+    assert.deepEqual(r.reasons, [{ code: "api_shape", detail: "chunk: signature" }, { code: "api_shape", detail: "ichunked: generator -> function" }]);
+  });
+  it("reasons are sorted and deterministic; junk input does not throw", () => {
+    const o = { diff: numstat(["src/z.py", 30], ["src/auth.py", 30], ["src/m.py", 1]), repro: null, testFailures: 3, cfg: ON };
+    const r = upgradeTriggers(o);
+    assert.deepEqual(codes(r), ["diff_files", "diff_lines", "repro_not_red", "risk_path", "tests_failed_twice"]);
+    assert.deepEqual(upgradeTriggers({ ...o, diff: { files: [...o.diff.files].reverse() } }), r);
+    assert.doesNotThrow(() => upgradeTriggers({ diff: { files: [null, { path: "" }, { path: 3, added: "x" }] }, testFailures: "nan", apiShape: "x", cfg: null }));
+  });
+});
+
+describe("light.mjs purity (#4448)", () => {
+  it("imports no filesystem, process or network module", () => {
+    const src = readFileSync(new URL("./light.mjs", import.meta.url), "utf8");
+    for (const m of ["node:fs", "node:child_process", "node:net", "node:http", "node:https"]) assert.equal(src.includes(`"${m}"`), false, m);
+  });
+});

package/bin/lean/limits.test.mjs

@@ -108,12 +108,47 @@ describe("account-scoped usage-limit holds (#4190)", () => {
     const limits = openLimits(storeFile(), { now });
     limits.set("A", t0 + 3_600_000, "batch b0 #1");
     const starts = [];
-    const sleep = async (ms) => { limits.clear("A"); c.t += Math.min(ms, 5000); };
+    const sleep = async (ms) => { limits.clear("A"); c.t += ms; }; // faithful: a sleep advances the full time asked for
     await orchestrate({ issues: [1], now, sleep, readBody: async () => "", limits, identity: () => "A", getParallel: () => 1, pollMs: 5000,
       runOne: async () => { starts.push(now()); return { terminalReason: "merged" }; } });
     assert.equal(starts[0], t0 + 5000, "admitted on the poll after the clear, not at the hour-long reset");
   });
 
+  it("a held batch polls the host store: limits clear admits within one poll without getCancelled or getParallel (#4446)", async () => {
+    const { c, now } = fakeClock();
+    const t0 = c.t;
+    const file = storeFile();
+    const limits = openLimits(file, { now });
+    limits.set("A", t0 + 3_600_000, "batch b0 #1");
+    const sleeps = [];
+    // The operator clears the hold from another process (its own handle on the host file) while the batch sleeps.
+    const sleep = async (ms) => {
+      sleeps.push(ms);
+      if (sleeps.length === 1) await quiet(() => limitsFromCli(["clear", "A"], { limits: openLimits(file, { now }), identity: () => "A" }));
+      c.t += ms;
+    };
+    const starts = [];
+    const rows = await orchestrate({ issues: [1, 2], parallel: 2, now, sleep, readBody: async () => "", limits, identity: () => "A", pollMs: 5000,
+      runOne: async (n) => { starts.push([n, now()]); return { terminalReason: "merged" }; } });
+    assert.deepEqual(rows.map((r) => r.outcome), ["merged", "merged"]);
+    assert.ok(starts.every(([, at]) => at <= t0 + 30_000), `admitted within 30s of the clear, got ${JSON.stringify(starts)}`);
+    assert.deepEqual(starts, [[1, t0 + 5000], [2, t0 + 5000]], "admitted on the first poll after the clear");
+  });
+
+  it("a held batch keeps waiting while the hold is present (#4446)", async () => {
+    const { c, now } = fakeClock();
+    const t0 = c.t;
+    const limits = openLimits(storeFile(), { now });
+    limits.set("A", t0 + 3_600_000, "batch b0 #1");
+    const sleeps = [];
+    const sleep = async (ms) => { sleeps.push(ms); c.t += ms; };
+    const starts = [];
+    await orchestrate({ issues: [1], now, sleep, readBody: async () => "", limits, identity: () => "A", pollMs: 5000,
+      runOne: async () => { starts.push(now()); return { terminalReason: "merged" }; } });
+    assert.deepEqual(starts, [t0 + 3_600_000], "admitted exactly at the reset, never earlier");
+    assert.ok(sleeps.length > 1 && sleeps.every((ms) => ms > 0 && ms <= 5000), "re-read the store every poll while held");
+  });
+
   it("a legacy batch-local holdUntil is ignored on resume and no longer persisted", async () => {
     const { c, now, sleep } = fakeClock();
     let state = { v: 1, order: [1], pending: [1], holdUntil: c.t + 3_600_000 };