forgedock 1.30.0 → 1.32.0

package/bin/lean/batch.test.mjs

@@ -3,12 +3,12 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { orchestrate, deferPolicy, DEFER_BACKOFF_S } from "./orchestrate.mjs";
 import { openBatch, fsTypeOf, assertDiskPath, isLaneAlive, writeAtomic, launchLane } from "./batch.mjs";
-import { orchestrateFromCli, runFromCli, readOrchestration, makeRelabelNeedsHuman } from "../engine-cli.mjs";
+import { orchestrateFromCli, runFromCli, readOrchestration, makeRelabelNeedsHuman, makeDispatchCheck } from "../engine-cli.mjs";
 
 // orchestrateFromCli opens the host lane registry (#4191): keep it in a temp dir, also for spawned dispatchers.
 process.env.FORGEDOCK_SCHED_DIR = tmpDir("batch-sched-");
@@ -293,3 +293,339 @@ describe("#4318: the batch dispatcher's signal relabel and the needs-human relab
     });
   });
 });
+
+describe("#4354: the batch report ends with the fail-soft alerts of the batch's repo", () => {
+  const seed = (dir, repo, status) => {
+    mkdirSync(dir, { recursive: true });
+    for (let i = 0; i < 10; i++) {
+      const evs = [{ event: "RUN_START", ts: new Date(Date.UTC(2026, 9, 1, 0, i)).toISOString(), repo, issue: 500 + i },
+        { event: "DEPS_PREPARED", eco: "pnpm", status, reason: "tool not found: spawn pnpm ENOENT" }, { event: "RUN_TERMINAL", reason: "merged", code: "completed" }];
+      writeFileSync(join(dir, `${500 + i}.jsonl`), evs.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    }
+  };
+  const run = async (dir) => {
+    const lines = [], l = console.log;
+    console.log = (...a) => lines.push(a.join(" "));
+    try {
+      await orchestrateFromCli(["1", "--repo", "o/r", "--no-prefilter"], { dir, batchRoot: tmpDir("alert-batch-"), allowTmpfs: true,
+        emitTelemetry: async () => {}, io: { gh: async () => "o/r\n" }, sched: null, decide: () => {}, alertConfig: {}, heavyStats: null,
+        leanIo: { gh: async (a) => (a.includes("milestone") ? JSON.stringify({ milestone: null }) : JSON.stringify({ body: "" })), git: async (a) => (a[0] === "ls-remote" ? "abc\trefs/heads/staging\n" : "") },
+        orchestration: { breaker: null, maxDeferrals: 3, globalParallel: null, recovery: { maxAttempts: 2 } },
+        leanModule: { runCore: async () => ({ terminalReason: "merged", pr: 51 }) } });
+    } finally { console.log = l; }
+    return lines.join("\n").split("\n").filter((x) => x.trim());
+  };
+
+  it("prints ALERTS last for the repo's failing dependency cache, nothing for a healthy one or another repo's lanes", async () => {
+    const bad = tmpDir("alert-runs-");
+    seed(bad, "o/r", "failed");
+    const out = await run(bad);
+    const at = out.indexOf("ALERTS");
+    assert.ok(at > 0, out.join("\n"));
+    assert.match(out[at + 1], /^DEPS_PREPARED failed \(pnpm\): 100% \(10\/10 lanes, threshold 20%\), e\.g\. "tool not found: spawn pnpm ENOENT"$/);
+    assert.equal(out.length, at + 2, "the alerts end the report");
+    const good = tmpDir("alert-runs-");
+    seed(good, "o/r", "hit");
+    assert.ok(!(await run(good)).some((x) => /ALERTS|DEPS_PREPARED/.test(x)));
+    const other = tmpDir("alert-runs-");
+    seed(other, "x/y", "failed");
+    assert.ok(!(await run(other)).some((x) => /ALERTS/.test(x)));
+  });
+});
+
+describe("#4402: the batch report prints the efficiency lines, fail-soft", () => {
+  const run = async (deps) => {
+    const lines = [], l = console.log;
+    console.log = (...a) => lines.push(a.join(" "));
+    try {
+      await orchestrateFromCli(["1", "--repo", "o/r", "--no-prefilter"], { dir: tmpDir("eff-runs-"), batchRoot: tmpDir("eff-batch-"), allowTmpfs: true,
+        emitTelemetry: async () => {}, io: { gh: async () => "o/r\n" }, sched: null, decide: () => {}, alertConfig: {}, heavyStats: null,
+        leanIo: { gh: async (a) => (a.includes("milestone") ? JSON.stringify({ milestone: null }) : a[0] === "api" ? (String(a[1]).endsWith("/comments") ? "" : JSON.stringify({ body: "## Root cause\na.js:1\n## Fix", labels: [] })) : JSON.stringify({ body: "" })),
+          git: async (a) => (a[0] === "ls-remote" ? "abc\trefs/heads/staging\n" : "") },
+        orchestration: { breaker: null, maxDeferrals: 3, globalParallel: null, recovery: { maxAttempts: 2 } },
+        leanModule: { runCore: async () => ({ terminalReason: "merged", pr: 51 }) }, ...deps });
+    } finally { console.log = l; }
+    return lines.join("\n").split("\n").filter((x) => x.trim());
+  };
+  it("prints the batch's efficiency section", async () => {
+    const out = await run({});
+    const at = out.findIndex((x) => x.startsWith("efficiency: merged 1,"));
+    assert.ok(at > 0, out.join("\n"));
+    assert.match(out[at + 3], /^retries\/merge 0\.00 \(env 0, engine 0, code 0, review 0, unknown 0; lane reruns 0\)$/);
+    assert.match(out[at + 5], /^issue quality: full n=1 /);
+    assert.equal(out[at + 6], "acceptance (7d after promotion): pass 0/0, pending 0, unprobed 1");
+  });
+  it("a throwing efficiency stub still ends the batch with its other report lines", async () => {
+    const out = await run({ efficiency: async () => { throw new Error("boom"); } });
+    assert.ok(out.includes("efficiency: n/a (boom)"), out.join("\n"));
+    assert.ok(out.some((x) => x.startsWith("reclaimed:")), out.join("\n"));
+  });
+});
+
+describe("#4408: issues added to a running batch (forgedock orchestrate --add)", () => {
+  const gate = () => { let open; const p = new Promise((r) => { open = r; }); return { p, open }; };
+  it("one lane running: an added independent issue starts on the next pass, an added one that Depends on the running issue waits for its merge", async () => {
+    const bodies = { 1: "", 2: "", 3: "Depends on #1" };
+    let added = [];
+    const started = [], g1 = gate(), log = [], decisions = [];
+    const done = orchestrate({ issues: [1], parallel: 3, pollMs: 5, readBody: async (n) => bodies[n] ?? "", getAdded: () => added,
+      decide: (d) => { decisions.push(d); }, onUpdate: (r) => log.push(r),
+      runOne: async (n) => { started.push(n); if (n === 1) await g1.p; return { terminalReason: "merged" }; } });
+    await until(() => started.includes(1));
+    added = [2, 3];
+    await until(() => started.includes(2), 3000);
+    await new Promise((r) => setTimeout(r, 50));
+    assert.deepEqual(started, [1, 2], "#3 waits for #1 to merge");
+    g1.open();
+    const rows = await done;
+    assert.deepEqual(started, [1, 2, 3]);
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"], [3, "merged"]]);
+    assert.deepEqual(log.filter((r) => r.outcome === "added").map((r) => r.detail), ["#2, #3"], "one added row; re-reads add nothing");
+    assert.equal(decisions.filter((d) => d.issue === null).length, 1);
+  });
+
+  it("edges hold both ways: a pending issue that Depends on an added one (declared, or written after the batch started) waits for it", async () => {
+    const bodies = { 7: "", 4: "Depends on #5", 8: "", 5: "", 6: "" };
+    let added = [];
+    const started = [], g7 = gate();
+    const done = orchestrate({ issues: [7, 4, 8], parallel: 1, pollMs: 5, readBody: async (n) => bodies[n] ?? "", getAdded: () => added,
+      runOne: async (n) => { started.push(n); if (n === 7) await g7.p; return { terminalReason: "merged" }; } });
+    await until(() => started.includes(7));
+    bodies[8] = "Depends on #6"; // edited while the batch runs
+    added = [5, 6];
+    await new Promise((r) => setTimeout(r, 50));
+    g7.open();
+    const rows = await done;
+    assert.deepEqual(started, [7, 5, 4, 6, 8]);
+    assert.ok(rows.every((r) => r.outcome === "merged"));
+  });
+
+  it("an add after the queue drained still runs before the batch returns; without getAdded nothing changes", async () => {
+    let added = [];
+    const started = [];
+    const rows = await orchestrate({ issues: [1], parallel: 2, pollMs: 5, readBody: async () => "", getAdded: () => added,
+      runOne: async (n) => { started.push(n); if (n === 1) added = [2]; return { terminalReason: "merged" }; } });
+    assert.deepEqual(rows.map((r) => r.issue), [1, 2]);
+    const plain = await orchestrate({ issues: [1], parallel: 2, readBody: async () => "", runOne: async () => ({ terminalReason: "merged" }) });
+    assert.deepEqual(plain.map((r) => r.issue), [1]);
+  });
+
+  it("the add file: integers only, no issue twice, cumulative; --add through the CLI skips closed and unreadable issues", async () => {
+    const root = tmpDir("batch-add-");
+    const b = openBatch(root, "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [1] });
+    assert.deepEqual(b.readAdded(), []);
+    const r = b.addIssues([2, "#3", "abc", 1, 2, 0, -4]);
+    assert.deepEqual(r.added, [2, 3]);
+    assert.deepEqual(r.skipped.map((x) => [x.issue, x.reason]), [["abc", "not an integer"], [1, "already in batch"], [2, "already in batch"], [0, "not an integer"], [-4, "not an integer"]]);
+    assert.deepEqual(b.addIssues([5]).added, [5]);
+    assert.deepEqual(b.readAdded(), [2, 3, 5]);
+    assert.deepEqual(b.unrunAdds(), [2, 3, 5]);
+    const views = [];
+    const io = { gh: async (a) => { views.push(a); if (a[2] === "8") throw new Error("gh down"); return JSON.stringify({ state: a[2] === "7" ? "CLOSED" : "OPEN" }); } };
+    const res = await quiet(() => orchestrateFromCli(["--add", "b1", "6", "7", "8", "3", "x"], { batchRoot: root, io }));
+    assert.deepEqual(res.added, [6]);
+    assert.deepEqual(res.skipped.map((x) => [x.issue, x.reason]).sort(), [[3, "already in batch"], [7, "closed"], [8, "unreadable"], ["x", "not an integer"]]);
+    assert.ok(views.every((a) => a.includes("-R") && a.includes("o/r")), "state read against the batch's repo");
+    assert.deepEqual(b.readAdded(), [2, 3, 5, 6]);
+    await assert.rejects(orchestrateFromCli(["--add", "nope", "2"], { batchRoot: root, io }), /no batch nope/);
+  });
+
+  it("#4469: --resume <id> and --add ignore the values of valued flags (--parallel 5 is not issue #5)", async () => {
+    const root = tmpDir("batch-add-flags-");
+    const b = openBatch(root, "b1");
+    b.writePlan({ argv: [], repo: "o/r" }); // no issues: the resume stops with the usage error after its adds
+    b.store.save({ order: [1] });
+    const views = [];
+    const io = { gh: async (a) => { views.push(a[2]); return JSON.stringify({ state: "OPEN" }); } };
+    await assert.rejects(quiet(() => orchestrateFromCli(["--resume", "b1", "--parallel", "5"], { batchRoot: root, io })), /usage/);
+    assert.deepEqual(views, [], "no issue read for a flag value");
+    assert.deepEqual(b.readAdded(), []);
+    await assert.rejects(quiet(() => orchestrateFromCli(["--resume", "b1", "--parallel", "5", "6", "--lane", "staging"], { batchRoot: root, io })), /usage/);
+    assert.deepEqual(views, ["6"]);
+    assert.deepEqual(b.readAdded(), [6]);
+    const res = await quiet(() => orchestrateFromCli(["--add", "b1", "7", "--parallel", "5"], { batchRoot: root, io }));
+    assert.deepEqual(res.added, [7]);
+    assert.deepEqual(res.skipped, []);
+    assert.deepEqual(b.readAdded(), [6, 7]);
+  });
+});
+
+describe("#4376: forgedock orchestrate --cancel", () => {
+  it("the cancel file: requestCancel / readCancel / clearCancel; invalid content reads as null", () => {
+    const b = openBatch(tmpDir("batch-cancel-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    assert.equal(b.readCancel(), null);
+    b.requestCancel({ reason: "operator" });
+    assert.equal(b.readCancel().reason, "operator");
+    assert.match(b.readCancel().at, /^\d{4}-\d\d-\d\dT/);
+    b.clearCancel();
+    assert.equal(b.readCancel(), null);
+    writeFileSync(join(b.dir, "cancel"), "[1]\n");
+    assert.equal(b.readCancel(), null);
+    writeFileSync(join(b.dir, "cancel"), "not json");
+    assert.equal(b.readCancel(), null);
+  });
+
+  it("a cancel while a lane runs: no more admissions, the lane is stopped once, its interrupt is no deferral, the rest end held; a resume runs them", async () => {
+    let cancel = null, saved = null;
+    const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+    const started = [], stops = [], log = [];
+    let release;
+    const stopped = new Promise((r) => { release = r; });
+    const done = orchestrate({ issues: [1, 2, 3], parallel: 1, pollMs: 5, readBody: async () => "", store, getCancelled: () => cancel,
+      stopLane: (n, rec) => { stops.push([n, rec.pid]); release(); }, onUpdate: (r) => log.push(r),
+      runOne: async (n, _lane, ctx) => {
+        started.push(n);
+        ctx.onStart?.({ pid: 4242 });
+        if (n !== 1) return { terminalReason: "merged" };
+        await stopped; // the lane's SIGTERM teardown reports deferred run.interrupted
+        return { terminalReason: "deferred", code: "run.interrupted", detail: "interrupted by SIGTERM" };
+      } });
+    await until(() => started.includes(1));
+    cancel = { at: new Date().toISOString(), reason: "operator" };
+    const rows = await done;
+    assert.deepEqual(started, [1], "nothing admitted after the cancel");
+    assert.deepEqual(stops, [[1, 4242]], "the running lane is stopped exactly once");
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome, r.detail]), [[1, "held", "cancelled by operator"], [2, "held", "cancelled by operator"], [3, "held", "cancelled by operator"]]);
+    assert.equal(log.filter((r) => r.outcome === "cancelled").length, 1);
+    assert.deepEqual(saved.deferrals, {}, "an operator stop is not counted as a deferral");
+    assert.ok(saved.cancelled, "the cancel is persisted with the batch state");
+    // The operator's resume clears the cancel file: the held issues run.
+    cancel = null;
+    const resumed = await orchestrate({ issues: [], parallel: 1, pollMs: 5, readBody: async () => "", store, getCancelled: () => cancel,
+      runOne: async (n) => { started.push(n); return { terminalReason: "merged" }; } });
+    assert.deepEqual(resumed.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"], [3, "merged"]]);
+    assert.equal(saved.cancelled, undefined);
+  });
+
+  it("without getCancelled nothing changes: a deferred lane still counts a deferral", async () => {
+    let saved = null, k = 0;
+    const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+    const { now, sleep } = fakeClock();
+    const rows = await orchestrate({ issues: [1], parallel: 1, readBody: async () => "", store, now, sleep, stopLane: () => { throw new Error("never"); },
+      runOne: async () => (k++ ? { terminalReason: "merged" } : { terminalReason: "deferred", code: "run.interrupted" }) });
+    assert.equal(rows[0].outcome, "merged");
+    assert.deepEqual(saved.deferrals, { 1: 1 });
+  });
+
+  it("through the CLI: --cancel during a lane holds the rest, a finished batch is left alone, unknown ids reject, --resume clears it", async () => {
+    const root = tmpDir("batch-cancel-cli-");
+    const leanIo = {
+      gh: async (a) => (a.includes("milestone") ? JSON.stringify({ milestone: null }) : JSON.stringify({ body: "" })),
+      git: async (a) => (a[0] === "ls-remote" ? "abc\trefs/heads/staging\n" : ""),
+    };
+    const ran = [];
+    const deps = { dir: tmpDir("cancel-run-"), batchRoot: root, batchId: "bc1", allowTmpfs: true, emitTelemetry: async () => {}, io: { gh: async () => "o/r\n" }, leanIo, sched: null,
+      decide: () => {}, orchestration: { breaker: null, maxDeferrals: 3, globalParallel: null },
+      leanModule: { runCore: async (o) => {
+        ran.push(o.issue);
+        if (o.issue === 1) {
+          const res = await quiet(() => orchestrateFromCli(["--cancel", "bc1"], { batchRoot: root }));
+          assert.equal(res.cancelled, true);
+        }
+        return { terminalReason: "merged", pr: 50 + o.issue };
+      } } };
+    const first = await quiet(() => orchestrateFromCli(["1", "2", "--parallel", "1", "--repo", "o/r", "--no-prefilter"], deps));
+    assert.deepEqual(first.rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "held"]]);
+    assert.equal(first.rows[1].detail, "cancelled by operator");
+    assert.deepEqual(ran, [1]);
+    const b = openBatch(root, "bc1");
+    assert.ok(b.readCancel());
+    const lines = [];
+    const l = console.log;
+    console.log = (...a) => lines.push(a.join(" "));
+    try { assert.equal((await orchestrateFromCli(["--cancel", "bc1"], { batchRoot: root })).cancelled, false); } finally { console.log = l; }
+    assert.match(lines.join("\n"), /batch bc1: already finished/);
+    await assert.rejects(orchestrateFromCli(["--cancel", "nope"], { batchRoot: root }), /no batch nope/);
+    await assert.rejects(orchestrateFromCli(["--cancel"], { batchRoot: root }), /usage: forgedock orchestrate/);
+    const resumed = await quiet(() => orchestrateFromCli(["--resume", "bc1"], deps));
+    assert.equal(b.readCancel(), null, "the operator's resume clears the cancel");
+    assert.deepEqual(resumed.rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"]]);
+    assert.deepEqual(ran, [1, 2]);
+  });
+});
+
+describe("#4454: orchestrate's shutdown signal (schedd stop)", () => {
+  it("#4454: an aborted signal admits nothing more, leaves without awaiting or stopping the running lane, relabels nothing, keeps it adoptable", async () => {
+    let saved = null;
+    const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+    const started = [], stops = [], relabels = [];
+    let releaseLane;
+    const lane = new Promise((r) => { releaseLane = r; });
+    const ac = new AbortController();
+    const done = orchestrate({ issues: [1, 2], parallel: 1, pollMs: 5, readBody: async () => "", store, signal: ac.signal,
+      stopLane: (n) => stops.push(n), relabelNeedsHuman: async (x) => { relabels.push(x); return true; },
+      runOne: async (n, _lane, ctx) => { started.push(n); ctx.onStart?.({ pid: 4242 }); if (n === 1) await lane; return { terminalReason: "merged" }; } });
+    await until(() => started.includes(1) && saved?.running?.["1"]?.pid === 4242);
+    const t0 = Date.now();
+    ac.abort();
+    await assert.rejects(done, (e) => e.code === "batch.stopped");
+    assert.ok(Date.now() - t0 < 1000, "the running lane is not awaited");
+    releaseLane();
+    await new Promise((r) => setTimeout(r, 100));
+    assert.deepEqual(started, [1], "nothing admitted after the stop, also once the lane ends");
+    assert.deepEqual(stops, [], "lanes are detached: no stop on shutdown");
+    assert.deepEqual(relabels, []);
+    assert.equal(saved.running["1"].pid, 4242, "the running lane stays in the state for a resume to adopt");
+    assert.deepEqual(saved.pending, [2]);
+    assert.deepEqual(saved.results, {}, "the lane that ended after the stop is not recorded by this process");
+  });
+
+  it("#4454: an abort wakes a loop sleeping on a long requeue delay", async () => {
+    const ac = new AbortController();
+    let deferred = 0;
+    const done = orchestrate({ issues: [9], parallel: 1, readBody: async () => "", signal: ac.signal,
+      runOne: async () => { deferred++; return { terminalReason: "deferred", detail: `leased by x until ${new Date(Date.now() + 3600e3).toISOString()}` }; } });
+    await until(() => deferred === 1);
+    await new Promise((r) => setTimeout(r, 50));
+    const t0 = Date.now();
+    ac.abort();
+    await assert.rejects(done, (e) => e.code === "batch.stopped");
+    assert.ok(Date.now() - t0 < 1000);
+  });
+});
+
+describe("#4481: a closed issue or a merged lane PR is skipped at dispatch", () => {
+  it("a requeued issue whose PR merged meanwhile ends merged without a second lane", async () => {
+    const { now, sleep } = fakeClock();
+    let runs = 0, checks = 0;
+    const rows = await orchestrate({ issues: [1], readBody: async () => "", now, sleep,
+      dispatchCheck: async () => (++checks === 1 ? null : { outcome: "merged", pr: 77, detail: "PR #77 already merged" }),
+      runOne: async () => { runs++; return { terminalReason: "deferred", code: "host.busy", retryInSeconds: 60 }; } });
+    assert.deepEqual([runs, checks], [1, 2], "checked on every start, the requeue included");
+    assert.deepEqual([rows[0].outcome, rows[0].pr], ["merged", 77]);
+    assert.match(rows[0].detail, /skipped at dispatch: PR #77 already merged/);
+  });
+
+  it("a closed issue ends invalid without a lane and its dependents still run; a throwing check runs the lane", async () => {
+    const ran = [];
+    const rows = await orchestrate({ issues: [1, 2], readBody: async (n) => (n === 2 ? "Depends on #1" : ""),
+      dispatchCheck: async (n) => (n === 1 ? { outcome: "invalid", detail: "issue closed" } : (() => { throw new Error("gh down"); })()),
+      runOne: async (n) => { ran.push(n); return { terminalReason: "merged", cost_usd: 0 }; } });
+    assert.deepEqual(ran, [2]);
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "invalid"], [2, "merged"]]);
+  });
+
+  it("makeDispatchCheck: merged head-branch PR, closed issue, open issue, unreadable answers fail open", async () => {
+    const mk = (issue, prs, events = "") => makeDispatchCheck({ repo: "o/r", gh: async (a) => {
+      if (a[0] === "issue") { assert.deepEqual(a, ["issue", "view", "9", "-R", "o/r", "--json", "state"]); if (issue instanceof Error) throw issue; return issue; }
+      if (a[0] === "api") { assert.equal(a[1], "repos/o/r/issues/9/events"); if (events instanceof Error) throw events; return events; }
+      assert.deepEqual(a.slice(0, 6), ["pr", "list", "-R", "o/r", "--head", "feat/issue-9-lean"]);
+      if (prs instanceof Error) throw prs;
+      return prs;
+    } });
+    const merged = '[{"number":12,"mergedAt":"2026-10-23T08:00:00Z"}]';
+    assert.deepEqual(await mk('{"state":"OPEN"}', merged)(9), { outcome: "merged", pr: 12, detail: "PR #12 already merged" }, "open, never reopened: the merge is still closing it");
+    assert.deepEqual(await mk('{"state":"OPEN"}', merged, "2026-10-22T08:00:00Z\n")(9), { outcome: "merged", pr: 12, detail: "PR #12 already merged" }, "reopened before the merge");
+    assert.equal(await mk('{"state":"OPEN"}', merged, "2026-10-22T08:00:00Z\n2026-10-23T09:00:00Z\n")(9), null, "reopened after the merge (failed probe, rework): the lane runs");
+    assert.equal(await mk('{"state":"OPEN"}', merged, new Error("api down"))(9), null, "unreadable reopen history: the lane runs");
+    assert.equal(await mk('{"state":"OPEN"}', '[{"number":12}]')(9), null, "no mergedAt: the lane runs");
+    assert.deepEqual(await mk('{"state":"CLOSED"}', merged, new Error("not read"))(9), { outcome: "merged", pr: 12, detail: "PR #12 already merged" }, "closed: no reopen lookup");
+    assert.deepEqual(await mk('{"state":"CLOSED"}', "[]")(9), { outcome: "invalid", detail: "issue closed" });
+    assert.equal(await mk('{"state":"OPEN"}', "[]")(9), null);
+    assert.equal(await mk('{"body":"","labels":[]}', '{"body":""}')(9), null, "a stub without state or a list: run");
+    assert.equal(await mk(new Error("x"), new Error("y"))(9), null);
+  });
+});

package/bin/lean/budget.mjs

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Per-size implement turn budgets (#4392). A lane's size comes from facts, never a model: a `size:S|M|L` issue label,
+ * else the frozen contract's distinct deliverable paths (S <= 2, M <= 5, else L). The budget for the size is forge.yaml
+ * `engine.turn_budget_s|m|l` (defaults 25/60/100; 0 disables that size). The implement stage (the build call and its
+ * context/timeout restarts) spends it; on overrun the builder gets one wrap-up grant to finish or stop with a digest, and
+ * an unfinished lane ends needs-human `budget.exceeded` (recoverable once by the batch). Pure module: no I/O.
+ */
+
+export const TURN_BUDGET_DEFAULTS = Object.freeze({ S: 25, M: 60, L: 100 });
+export const SIZES = Object.freeze(["S", "M", "L"]);
+/** Max chars of the builder's digest carried into the needs-human detail. */
+export const DIGEST_MAX = 1500;
+
+/** forge.yaml engine section -> {S, M, L} budgets; a missing or junk key keeps its default. null when no key is set (callers use the defaults). */
+export function parseTurnBudgets(engine) {
+  if (!engine || typeof engine !== "object") return null;
+  const out = { ...TURN_BUDGET_DEFAULTS };
+  let set = false;
+  for (const s of SIZES) {
+    const v = String(engine[`turn_budget_${s.toLowerCase()}`] ?? "").trim();
+    if (/^\d+$/.test(v)) { out[s] = Number(v); set = true; }
+  }
+  return set ? out : null;
+}
+
+/** "S" | "M" | "L" for a lane: a `size:X` label wins, else the contract's distinct deliverable paths. null without either. */
+export function laneSize({ contract = null, labels = [] } = {}) {
+  for (const l of Array.isArray(labels) ? labels : []) {
+    const m = /^size[:/]\s*([SML])$/i.exec(String(l?.name ?? l ?? "").trim());
+    if (m) return m[1].toUpperCase();
+  }
+  if (!contract || !Array.isArray(contract.deliverables)) return null;
+  const n = new Set(contract.deliverables.map((d) => d?.path).filter((p) => typeof p === "string" && p.trim())).size;
+  return n <= 2 ? "S" : n <= 5 ? "M" : "L";
+}
+
+/** Turns the wrap-up call may use after the budget is spent. */
+export const wrapupGrant = (budget) => Math.max(5, Math.ceil(budget / 5));
+
+/**
+ * Lane turn accounting. `note(turns, build)` adds one builder attempt's turns (build: it ran in the implement stage);
+ * `remaining()` is the implement budget left (Infinity when off or unsized); `record()` rides on the lane result and
+ * RUN_TERMINAL ({size, budget, build, total, exceeded}), null while the lane is unsized.
+ */
+export function makeTurnBudget(budgets = TURN_BUDGET_DEFAULTS) {
+  const b = { ...TURN_BUDGET_DEFAULTS, ...(budgets ?? {}) };
+  let size = null, build = 0, total = 0, exceeded = false;
+  const budget = () => (size && Number.isFinite(b[size]) && b[size] > 0 ? b[size] : 0);
+  return {
+    setSize(s) { if (SIZES.includes(s)) size = s; },
+    get size() { return size; },
+    budget,
+    on: () => budget() > 0,
+    note(turns, isBuild) { const t = Number.isFinite(turns) && turns > 0 ? turns : 0; total += t; if (isBuild) build += t; },
+    remaining: () => (budget() > 0 ? budget() - build : Infinity),
+    markExceeded() { exceeded = true; },
+    record: () => (size ? { size, budget: budget(), build, total, exceeded } : null),
+  };
+}
+
+/** The needs-human detail: the builder's digest (capped), else the diff stat and the last self-check state. */
+export function budgetDigest({ size, budget, used, digest = null, stat = "", check = null }) {
+  const head = `Implement turn budget spent (size ${size}, ${budget} turns; ${used} used) and the wrap-up did not finish; work is checkpointed on the lane branch.`;
+  const d = typeof digest === "string" && digest.trim() ? digest.trim().slice(0, DIGEST_MAX) : null;
+  if (d) return `${head}\n\nBuilder digest:\n${d}`;
+  return `${head}\n\nNo builder digest; changes so far:\n${String(stat || "(no diff)").trim().slice(0, DIGEST_MAX)}${check ? `\nLast self-check: ${check}` : ""}`;
+}
+
+const pct = (xs, p) => xs[Math.min(xs.length - 1, Math.floor((xs.length - 1) * p))];
+/**
+ * Batch-report line (#4392): implement turns per size over the merged rows (`turns.build`), then the lanes that went
+ * over budget. null when no row carries turns.
+ */
+export function formatTurnSummary(rows) {
+  const withTurns = (rows ?? []).filter((r) => r?.turns && SIZES.includes(r.turns.size));
+  if (!withTurns.length) return null;
+  const parts = [];
+  for (const s of SIZES) {
+    const merged = withTurns.filter((r) => r.outcome === "merged" && r.turns.size === s);
+    if (!merged.length) continue;
+    const xs = merged.map((r) => Number(r.turns.build) || 0).sort((a, c) => a - c);
+    const budget = Number(merged[0].turns.budget) || 0;
+    parts.push(`${s} n=${xs.length} p50 ${pct(xs, 0.5)} max ${xs[xs.length - 1]}/${budget > 0 ? budget : "off"}`);
+  }
+  const over = withTurns.filter((r) => r.turns.exceeded).map((r) => `#${r.issue} (${r.turns.size} ${r.turns.budget})`);
+  return `turns by size: ${parts.join("; ") || "no merged lanes"}${over.length ? `; over budget: ${over.join(" ")}` : ""}`;
+}

package/bin/lean/budget.test.mjs

@@ -0,0 +1,106 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4392: per-size implement turn budgets: sizing, config, digest, the stream turn cap and the batch-report line.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, chmodSync } from "node:fs";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { TURN_BUDGET_DEFAULTS, parseTurnBudgets, laneSize, wrapupGrant, makeTurnBudget, budgetDigest, formatTurnSummary } from "./budget.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+import { OUTCOME_CODES, RECOVERABLE_CODES } from "../engine/outcome-codes.mjs";
+import { RECOVER_HOW } from "./lean.mjs";
+import { TRIGGERS, REWORK_TRIGGERS, firstPassOf } from "./fixround.mjs";
+
+process.env.FORGEDOCK_SCHED_DIR = tmpDir("budget-sched-");
+const contract = (n) => ({ deliverables: Array.from({ length: n }, (_, i) => ({ id: `D${i + 1}`, path: `src/f${i % Math.max(1, n)}.js` })) });
+
+describe("#4392 turn budget", () => {
+  it("defaults are S=25, M=60, L=100; forge.yaml keys override, 0 allowed, junk ignored", () => {
+    assert.deepEqual(TURN_BUDGET_DEFAULTS, { S: 25, M: 60, L: 100 });
+    assert.equal(parseTurnBudgets({}), null);
+    assert.equal(parseTurnBudgets(null), null);
+    assert.deepEqual(parseTurnBudgets({ turn_budget_s: "10", turn_budget_m: 0, turn_budget_l: "x" }), { S: 10, M: 0, L: 100 });
+  });
+
+  it("size: a size label wins, else distinct deliverable paths (S <= 2, M <= 5, else L); unsized without either", () => {
+    assert.equal(laneSize({ contract: contract(1) }), "S");
+    assert.equal(laneSize({ contract: contract(2) }), "S");
+    assert.equal(laneSize({ contract: contract(3) }), "M");
+    assert.equal(laneSize({ contract: contract(5) }), "M");
+    assert.equal(laneSize({ contract: contract(6) }), "L");
+    assert.equal(laneSize({ contract: { deliverables: [{ path: "a" }, { path: "a" }, { path: "b" }] } }), "S", "paths are deduped");
+    assert.equal(laneSize({ contract: contract(9), labels: [{ name: "size:S" }] }), "S");
+    assert.equal(laneSize({ contract: contract(1), labels: ["bug", "Size/l"] }), "L");
+    assert.equal(laneSize({}), null);
+  });
+
+  it("the tally: build turns spend the budget, other attempts count only in total; off or unsized is unlimited", () => {
+    const tb = makeTurnBudget({ M: 60 });
+    assert.equal(tb.record(), null); assert.equal(tb.remaining(), Infinity);
+    tb.setSize("M"); tb.note(4, false); tb.note(50, true); tb.note(undefined, true);
+    assert.equal(tb.remaining(), 10);
+    tb.markExceeded();
+    assert.deepEqual(tb.record(), { size: "M", budget: 60, build: 50, total: 54, exceeded: true });
+    const off = makeTurnBudget({ S: 0 }); off.setSize("S");
+    assert.equal(off.on(), false); assert.equal(off.remaining(), Infinity);
+    assert.equal(wrapupGrant(25), 5); assert.equal(wrapupGrant(100), 20); assert.equal(wrapupGrant(3), 5);
+  });
+
+  it("the digest is the builder's (capped), else the diff stat and the last self-check", () => {
+    const d = budgetDigest({ size: "M", budget: 60, used: 66, digest: "x".repeat(5000) });
+    assert.match(d, /size M, 60 turns; 66 used/); assert.ok(d.length < 1800);
+    const s = budgetDigest({ size: "S", budget: 25, used: 30, stat: " src/a.js | 4 ++--", check: "red" });
+    assert.match(s, /No builder digest/); assert.match(s, /src\/a\.js/); assert.match(s, /Last self-check: red/);
+  });
+
+  it("budget.exceeded is a typed, recoverable outcome with a recovery instruction; budget_wrapup is a build restart, not rework", () => {
+    assert.equal(OUTCOME_CODES.BUDGET_EXCEEDED, "budget.exceeded");
+    assert.ok(RECOVERABLE_CODES.includes("budget.exceeded"));
+    assert.match(RECOVER_HOW["budget.exceeded"], /split-required/);
+    assert.ok(TRIGGERS.includes("budget_wrapup")); assert.ok(!REWORK_TRIGGERS.includes("budget_wrapup"));
+    assert.equal(firstPassOf([{ trigger: "plan" }, { trigger: "budget_wrapup", restart_of: "build" }]), true);
+  });
+
+  it("runCliBackendAsync turnMax stops a stream session at that many assistant turns (deduped by message id)", async () => {
+    const { runCliBackendAsync } = await import("../runner.mjs");
+    const d = tmpDir("core-turns-");
+    const line = (id) => JSON.stringify({ type: "assistant", message: { id, content: [{ type: "tool_use", name: "Edit", input: { file: "a" } }], usage: { input_tokens: 10, output_tokens: 3, cache_read_input_tokens: 5, cache_creation_input_tokens: 0 } } });
+    writeFileSync(`${d}/fake`, `#!/bin/sh\necho '${line("m1")}'\necho '${line("m1")}'\necho '${line("m2")}'\necho '${line("m3")}'\nexec sleep 30\n`); chmodSync(`${d}/fake`, 0o755);
+    const t0 = Date.now();
+    await assert.rejects(runCliBackendAsync({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: d, bin: `${d}/fake`, logger: { log() {} }, stream: true, turnMax: 3 }), (e) => {
+      assert.equal(e.code, "CLI_TURNS"); assert.equal(e.turns, 3); assert.equal(e.turnMax, 3);
+      assert.deepEqual(e.usage, { input_tokens: 30, output_tokens: 9, cache_creation_input_tokens: 0, cache_read_input_tokens: 15 });
+      assert.equal(e.lastTool.name, "Edit");
+      return true;
+    });
+    assert.ok(Date.now() - t0 < 15000, "killed, not waited out");
+  });
+
+  it("#4410 runCliBackendAsync returns the stream's tool uses, deduped by tool_use id, with path and command", async () => {
+    const { runCliBackendAsync } = await import("../runner.mjs");
+    const d = tmpDir("core-tools-");
+    const use = (id, name, input) => ({ type: "tool_use", id, name, input });
+    const line = (id, content) => JSON.stringify({ type: "assistant", message: { id, content, usage: { input_tokens: 1, output_tokens: 1 } } });
+    const a = line("m1", [use("t1", "Read", { file_path: "a.sh" })]), b = line("m1", [use("t2", "Bash", { command: "sed -n 1,9p a.sh" })]);
+    const c = line("m2", [use("t3", "Grep", { pattern: "x", path: "src" })]);
+    const result = JSON.stringify({ type: "result", subtype: "success", is_error: false, result: "ok", session_id: "s-1", usage: { input_tokens: 2, output_tokens: 2 } });
+    writeFileSync(`${d}/fake`, `#!/bin/sh\necho '${a}'\necho '${a}'\necho '${b}'\necho '${c}'\necho '${result}'\n`); chmodSync(`${d}/fake`, 0o755);
+    const r = await runCliBackendAsync({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: d, bin: `${d}/fake`, logger: { log() {} }, stream: true });
+    assert.deepEqual(r.toolUses, [{ msg: "m1", name: "Read", path: "a.sh", cmd: null }, { msg: "m1", name: "Bash", path: null, cmd: "sed -n 1,9p a.sh" },
+      { msg: "m2", name: "Grep", path: "src", cmd: null }]);
+    writeFileSync(`${d}/fake`, `#!/bin/sh\necho '${a}'\necho '${b}'\necho '${c}'\nexec sleep 30\n`);
+    await assert.rejects(runCliBackendAsync({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: d, bin: `${d}/fake`, logger: { log() {} }, stream: true, turnMax: 2 }),
+      (e) => e.code === "CLI_TURNS" && e.toolUses.length === 3);
+  });
+
+  it("the batch row carries the lane's turns and the report prints a size x turns line with overruns", async () => {
+    const T = (size, budget, build, exceeded = false) => ({ size, budget, build, total: build + 3, exceeded });
+    const results = { 1: { terminalReason: "merged", turns: T("S", 25, 10) }, 2: { terminalReason: "merged", turns: T("S", 25, 22) }, 3: { terminalReason: "merged", turns: T("S", 25, 30, true) },
+      4: { terminalReason: "merged", turns: T("M", 60, 41) }, 5: { terminalReason: "needs-human", code: "budget.exceeded", turns: T("L", 100, 105, true) } };
+    const rows = await orchestrate({ issues: [1, 2, 3, 4, 5], parallel: 2, readBody: async () => "", runOne: async (n) => results[n], recovery: { maxAttempts: 0 } });
+    assert.deepEqual(rows.find((r) => r.issue === 4).turns, results[4].turns);
+    assert.equal(formatTurnSummary(rows), "turns by size: S n=3 p50 22 max 30/25; M n=1 p50 41 max 41/60; over budget: #3 (S 25) #5 (L 100)");
+    assert.equal(formatTurnSummary([{ issue: 1, outcome: "merged" }]), null);
+    assert.equal(formatTurnSummary([{ issue: 1, outcome: "merged", turns: T("S", 0, 7) }]), "turns by size: S n=1 p50 7 max 7/off");
+  });
+});

package/bin/lean/checks.mjs

@@ -13,7 +13,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { git, changedFiles, sha256, homeForgeDir, shellSplit, shellQuote, globToRegex } from "../../scripts/ci-local/lib.mjs";
+import { git, changedFiles, sha256, homeForgeDir, shellSplit, shellQuote, globToRegex, parseYaml, trustedForgeYaml } from "../../scripts/ci-local/lib.mjs";
 import { makeScopeCtx, scopeCommand } from "../../scripts/ci-local/scoping.mjs";
 
 const px = path.posix;
@@ -67,16 +67,16 @@ export function discoverChecks(repo) {
     const turbo = turboTasks(repo);
     const scripts = new Map(pkgDirs.map((d) => [d, (readJson(path.join(repo, d, "package.json")) || {}).scripts || {}]));
     for (const [script, kind] of Object.entries(SCRIPT_KINDS)) {
-      if (turbo.has(script)) { out.push({ kind, command: `${exists(repo, "node_modules/.bin/turbo") ? "" : "npx "}turbo run ${script}`, cwd: "." }); continue; }
+      if (turbo.has(script)) { out.push({ kind, command: `${exists(repo, "node_modules/.bin/turbo") ? "" : "npx "}turbo run ${script}`, cwd: ".", eco: "js" }); continue; }
       const ws = pkgDirs.filter((d) => d !== "." && typeof scripts.get(d)[script] === "string").sort();
       const dirs = ws.length ? ws : typeof (scripts.get(".") || {})[script] === "string" ? ["."] : [];
-      for (const d of dirs) out.push({ kind, command: `${pm} run ${script}`, cwd: d, exec: EXEC[pm] });
+      for (const d of dirs) out.push({ kind, command: `${pm} run ${script}`, cwd: d, exec: EXEC[pm], eco: "js" });
     }
   }
   const pyproject = readText(path.join(repo, "pyproject.toml"));
   const run = exists(repo, "uv.lock") ? "uv run " : exists(repo, "poetry.lock") ? "poetry run " : "";
-  if (/^\[tool\.ruff/m.test(pyproject) || exists(repo, "ruff.toml") || exists(repo, ".ruff.toml")) out.push({ kind: "lint", command: `${run}ruff check .`, cwd: "." });
-  if (/^\[tool\.pytest/m.test(pyproject) || exists(repo, "pytest.ini") || tracked.some((f) => px.basename(f) === "conftest.py")) out.push({ kind: "test", command: `${run}pytest`, cwd: "." });
+  if (/^\[tool\.ruff/m.test(pyproject) || exists(repo, "ruff.toml") || exists(repo, ".ruff.toml")) out.push({ kind: "lint", command: `${run}ruff check .`, cwd: ".", eco: "py" });
+  if (/^\[tool\.pytest/m.test(pyproject) || exists(repo, "pytest.ini") || tracked.some((f) => px.basename(f) === "conftest.py")) out.push({ kind: "test", command: `${run}pytest`, cwd: ".", eco: "py" });
   return out;
 }
 
@@ -150,16 +150,39 @@ export function laneChanges(repo, base) {
   return { files: files.filter((f) => !f.startsWith(".forge-lean/")), from };
 }
 
-/** The scoped checks for this lane: [{kind, command, cwd, mode, widen_reason, selector, reason}]. */
-export function scopedChecks({ repo, base, checks = discoverChecks(repo) }) {
+/**
+ * The repo's configured `verification.commands.typescript.lint` (#4381), read only from the trusted forge.yaml copy
+ * (forge#4040: never the PR's own tree). null when absent, empty or unreadable (no yq, parse error).
+ */
+export function configuredLint(repo, base) {
+  try {
+    const mb = git(repo, ["merge-base", base, "HEAD"]).out.trim();
+    const { text } = trustedForgeYaml(repo, base, mb);
+    if (!text) return null;
+    const v = parseYaml(text)?.verification?.commands?.typescript?.lint;
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+  } catch { return null; }
+}
+
+/**
+ * The scoped checks for this lane: [{kind, command, cwd, mode, widen_reason, selector, reason, configured}]. A configured
+ * typescript.lint replaces the discovered JS lint checks (#4381); Python checks are never replaced.
+ */
+export function scopedChecks({ repo, base, checks = discoverChecks(repo), lint = configuredLint(repo, base) }) {
   const { files, from } = laneChanges(repo, base);
   const sctx = makeScopeCtx({ repo, baseRef: base, from, changed: files });
+  if (lint) {
+    const i = checks.findIndex((c) => c.kind === "lint" && c.eco === "js");
+    const own = { kind: "lint", command: lint, cwd: ".", configured: true, ...(exists(repo, "package.json") ? { exec: EXEC[packageManager(repo)] } : {}) };
+    checks = i < 0 ? [...checks, own] : [...checks.slice(0, i), own, ...checks.slice(i).filter((c) => !(c.kind === "lint" && c.eco === "js"))];
+  }
   return checks.map((c) => {
     const r = scopeCommand(c.command, c.cwd === "." ? "" : c.cwd, sctx);
     // A resolved script body (`pnpm run typecheck` -> `tsc -p apps/web`) runs its binary through the package manager.
     const resolved = r.action !== "skip" && c.exec && r.command !== c.command && !SYSTEM_BINS.has(px.basename((shellSplit(r.command) || [""])[0]));
     const out = { kind: c.kind, cwd: c.cwd, command: r.action === "skip" ? "" : resolved ? `${c.exec} ${r.command}` : r.command, mode: r.mode, widen_reason: r.widen_reason || "", selector: r.selector || "" };
     if (r.reason) out.reason = r.reason;
+    if (c.configured) out.configured = true;
     return r.action === "skip" ? out : withCacheFlags(out, repo);
   });
 }
@@ -190,8 +213,8 @@ function main(argv) {
   if (!checks.length) console.log("# no typecheck/lint/test command found");
   for (const c of checks) {
     const where = c.cwd && c.cwd !== "." ? `(cd ${shellQuote(c.cwd)} && ${c.command})` : c.command;
-    if (c.mode === "skip") console.log(`${c.kind} skip  # skipped: ${c.reason || "not affected"}`);
-    else console.log(`${c.kind} ${c.mode} ${where}${c.widen_reason ? `  # widened: ${c.widen_reason}` : ""}`);
+    if (c.mode === "skip") console.log(`${c.kind} skip  # skipped: ${c.reason || "not affected"}${c.configured ? " (configured: verification.commands.typescript.lint)" : ""}`);
+    else console.log(`${c.kind} ${c.mode} ${where}${c.widen_reason ? `  # widened: ${c.widen_reason}` : ""}${c.configured ? "  # configured: verification.commands.typescript.lint" : ""}`);
   }
   return 0;
 }