forgedock 1.34.0 → 1.36.0

package/bin/lean/batch.mjs

@@ -6,6 +6,8 @@
  * A batch lives in `~/.forge/batches/<id>/` (or `FORGEDOCK_BATCH_DIR`): `plan.json` (the command), `state.json` (the
  * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K),
  * `add` (issues added to the batch by `--add`, #4408: a cumulative JSON set the runner re-reads every pass),
+ * `requeue` (`--requeue`, #4550: a cumulative JSON list of `{issue, reason, by, at}` the runner applies once each, moving a terminal issue back to pending),
+ * `hold` (issues held by `--hold`, #4592: a cumulative JSON set; the runner admits none of them until `--release` or a `--resume` names them),
  * `cancel` (`{at, reason}` written by `--cancel`, #4376: the runner stops admitting and stops its local lanes; a resume clears it),
  * `lanes/<issue>.{json,log}` (each lane's result and output) and `report.json` (the final rows and printed report, written
  * when the scheduler loop returns; `forgedock orchestrate --resume` on a finished batch replays it, #4192). Every write is tmp + fsync + rename, and the root must be
@@ -68,6 +70,19 @@ const readAdded = (file) => {
   return Array.isArray(v) ? [...new Set(v.filter((n) => Number.isSafeInteger(n) && n > 0))].sort((a, b) => a - b) : [];
 };
 
+/** `outcome`s `--requeue` may move back to pending (#4550). */
+export const REQUEUABLE = (outcome) => ["needs-human", "invalid", "skipped", "ci-pending", "budget-exceeded"].includes(outcome) || /^dependency-/.test(String(outcome));
+/** Key of one requeue entry; the runner records the applied keys in state.json `requeueApplied`. */
+export const requeueKey = (e) => `${e.issue}@${e.at}`;
+
+const readRequeueFile = (file) => {
+  const v = readJson(file);
+  return Array.isArray(v) ? v.filter((e) => e && Number.isSafeInteger(e.issue) && e.issue > 0 && typeof e.at === "string") : [];
+};
+
+/** The positive integers among `list` (numbers, `7`, `#7`). */
+const ints = (list) => (Array.isArray(list) ? list : []).map((x) => (typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN)).filter((n) => Number.isSafeInteger(n) && n > 0);
+
 export function newBatchId(now = Date.now(), pid = process.pid) {
   return `b${new Date(now).toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)}-${pid}`;
 }
@@ -118,8 +133,53 @@ export function openBatch(root, id) {
       if (added.length) writeAtomic(f("add"), JSON.stringify([...new Set([...readAdded(f("add")), ...added])].sort((a, b) => a - b)) + "\n");
       return { added, skipped };
     },
-    /** `--cancel` (#4376): `{at, reason}` in the `cancel` file; the runner re-reads it every pass. */
-    requestCancel: ({ reason = "operator" } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason) }) + "\n"),
+    /**
+     * `--requeue` (#4550): record that each issue returns to pending. Refused: not a positive integer, not in the batch's
+     * `order`, no terminal result yet (`not terminal`), or already requeued and not yet applied. The needs-human label and
+     * closed checks need GitHub and live in the CLI. @returns {{requeued:number[], refused:Array<{issue, reason}>}}
+     */
+    requeue: (list, { reason = "operator decision", by = "operator" } = {}) => {
+      const st = readJson(f("state.json")) ?? {};
+      const order = new Set(st.order ?? []), applied = new Set(st.requeueApplied ?? []);
+      const entries = readRequeueFile(f("requeue"));
+      const pend = new Set(entries.filter((e) => !applied.has(requeueKey(e))).map((e) => e.issue));
+      const requeued = [], refused = [];
+      for (const x of Array.isArray(list) ? list : []) {
+        const n = typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN;
+        if (!Number.isSafeInteger(n) || n < 1) refused.push({ issue: x, reason: "not an integer" });
+        else if (!order.has(n)) refused.push({ issue: n, reason: "not in batch" });
+        else if (pend.has(n)) refused.push({ issue: n, reason: "already requeued" });
+        else if (!REQUEUABLE(st.results?.[n]?.outcome)) refused.push({ issue: n, reason: "not terminal" });
+        else { pend.add(n); requeued.push(n); }
+      }
+      if (requeued.length) {
+        const at = new Date().toISOString();
+        writeAtomic(f("requeue"), JSON.stringify([...entries, ...requeued.map((issue) => ({ issue, reason: String(reason), by: String(by), at }))]) + "\n");
+      }
+      return { requeued, refused };
+    },
+    /** Every `--requeue` entry, in order; [] when missing or invalid. */
+    readRequeued: () => readRequeueFile(f("requeue")),
+    /** Entries the runner has not applied yet (a finished or unhosted batch with a pending requeue). */
+    unrunRequeues: () => { const done = new Set(readJson(f("state.json"))?.requeueApplied ?? []); return readRequeueFile(f("requeue")).filter((e) => !done.has(requeueKey(e))); },
+    /** Issues held by `--hold` (#4592): the `hold` file, sorted unique positive integers; [] when missing or invalid. */
+    readHeld: () => readAdded(f("hold")),
+    /** Merge the positive integers of `list` into the `hold` file. @returns {number[]} the issues newly held */
+    holdIssues: (list) => {
+      const have = new Set(readAdded(f("hold")));
+      const added = [...new Set(ints(list))].filter((n) => !have.has(n)).sort((a, b) => a - b);
+      if (added.length) writeAtomic(f("hold"), JSON.stringify([...have, ...added].sort((a, b) => a - b)) + "\n");
+      return added;
+    },
+    /** Remove `list` from the `hold` file. @returns {number[]} the issues that were held */
+    releaseIssues: (list) => {
+      const have = new Set(readAdded(f("hold")));
+      const freed = [...new Set(ints(list))].filter((n) => have.has(n)).sort((a, b) => a - b);
+      if (freed.length) writeAtomic(f("hold"), JSON.stringify([...have].filter((n) => !freed.includes(n)).sort((a, b) => a - b)) + "\n");
+      return freed;
+    },
+    /** `--cancel` (#4376): `{at, reason, stopRemote?}` in the `cancel` file; the runner re-reads it every pass. `stopRemote` (#4612) also asks remote lanes to stop at their checkpoint. */
+    requestCancel: ({ reason = "operator", stopRemote = false } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason), ...(stopRemote === true ? { stopRemote: true } : {}) }) + "\n"),
     /** The cancel record, or null when missing or invalid. */
     readCancel: () => { const v = readJson(f("cancel")); return v && typeof v === "object" && !Array.isArray(v) && typeof v.at === "string" ? v : null; },
     clearCancel: () => rmSync(f("cancel"), { force: true }),
@@ -146,7 +206,10 @@ export function isLaneAlive(pid, marker, { kill = process.kill.bind(process), pr
   if (!existsSync(procDir)) return true;
   let cmd;
   try { cmd = readFileSync(join(procDir, String(pid), "cmdline"), "utf8"); } catch { return false; }
-  return !marker || cmd.split("\0").includes(marker);
+  if (marker && !cmd.split("\0").includes(marker)) return false;
+  // A zombie (exited, not yet reaped: PID 1 may not reap) answers `kill(pid, 0)` but is not running.
+  try { if (/^\d+ \(.*\) Z /s.test(readFileSync(join(procDir, String(pid), "stat"), "utf8"))) return false; } catch { /* no stat: treat as alive */ }
+  return true;
 }
 
 /**

package/bin/lean/batch.test.mjs

@@ -6,7 +6,7 @@ import { spawn } from "node:child_process";
 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 { orchestrate, deferPolicy, DEFER_BACKOFF_S, formatOutcomeLists } from "./orchestrate.mjs";
 import { openBatch, fsTypeOf, assertDiskPath, isLaneAlive, writeAtomic, launchLane, detachedLanes } from "./batch.mjs";
 import { orchestrateFromCli, runFromCli, readOrchestration, makeRelabelNeedsHuman, makeDispatchCheck } from "../engine-cli.mjs";
 
@@ -213,6 +213,14 @@ await orchestrateFromCli(["1", "2", "3", "--parallel", "2", "--repo", "o/r", "--
     assert.doesNotThrow(() => assertDiskPath("/home/u/.forge/batches", mounts));
     assert.equal(isLaneAlive(process.pid, "--definitely-not-in-my-cmdline"), false);
     assert.equal(isLaneAlive(2 ** 22 + 12345, null), false);
+    // #4592: a zombie answers kill(pid, 0) but is not a live lane.
+    const proc = tmpDir("proc-"), pd = join(proc, "42");
+    mkdirSync(pd, { recursive: true });
+    writeFileSync(join(pd, "cmdline"), "node\0lane\0");
+    writeFileSync(join(pd, "stat"), "42 (node) S 1 42 42 0 -1\n");
+    assert.equal(isLaneAlive(42, "lane", { kill: () => true, procDir: proc }), true);
+    writeFileSync(join(pd, "stat"), "42 (no) de) Z 1 42 42 0 -1\n");
+    assert.equal(isLaneAlive(42, "lane", { kill: () => true, procDir: proc }), false);
     assert.deepEqual(readOrchestration(root), { breaker: { errors: 3, window_min: 30 }, maxDeferrals: 3, globalParallel: null, recovery: { maxAttempts: 1 }, baseSync: { enabled: true, unionGlobs: [] } });
     writeFileSync(join(root, "forge.yaml"), "orchestration:\n  breaker:\n    errors: 5\n    window_min: 10\n  max_deferrals: 2\n  global_parallel: 4\n");
     assert.deepEqual(readOrchestration(root), { breaker: { errors: 5, window_min: 10 }, maxDeferrals: 2, globalParallel: 4, recovery: { maxAttempts: 1 }, baseSync: { enabled: true, unionGlobs: [] } });
@@ -520,6 +528,37 @@ describe("#4376: forgedock orchestrate --cancel", () => {
     assert.deepEqual(saved.deferrals, { 1: 1 });
   });
 
+  for (const stopRemote of [false, true]) {
+    it(`a cancel ${stopRemote ? "with" : "without"} stopRemote ${stopRemote ? "stops" : "leaves"} a remote lane (#4612)`, async () => {
+      let cancel = null, saved = null;
+      const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+      const started = [], stops = [];
+      let release;
+      const gate = new Promise((r) => { release = r; });
+      const done = orchestrate({ issues: [1], parallel: 1, pollMs: 5, readBody: async () => "", store, getCancelled: () => cancel,
+        stopLane: (n, rec) => { stops.push([n, rec.remote]); release(); },
+        runOne: async (n, _lane, ctx) => {
+          started.push(n);
+          ctx.onStart?.({ remote: true, handle: { id: "sbx-1" } });
+          if (!stopRemote) setTimeout(release, 100);
+          await gate;
+          return { terminalReason: "deferred", code: "run.interrupted" };
+        } });
+      await until(() => started.includes(1));
+      cancel = { at: new Date().toISOString(), reason: "operator", ...(stopRemote ? { stopRemote: true } : {}) };
+      await done;
+      assert.deepEqual(stops, stopRemote ? [[1, true]] : []);
+    });
+  }
+
+  it("requestCancel records stopRemote only when asked (#4612)", () => {
+    const b = openBatch(tmpDir("batch-cancel-stop-"), "b1");
+    b.requestCancel({});
+    assert.equal(b.readCancel().stopRemote, undefined);
+    b.requestCancel({ stopRemote: true });
+    assert.equal(b.readCancel().stopRemote, true);
+  });
+
   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 = {
@@ -703,6 +742,75 @@ describe("#4528: a full sandbox pool (sandbox.capacity) is never capped", () =>
   });
 });
 
+describe("#4550: forgedock orchestrate --requeue", () => {
+  const gate = () => { let open; const p = new Promise((r) => { open = r; }); return { p, open }; };
+  it("a needs-human issue is requeued and relaunched; its skipped dependent returns to pending and runs after it merges; one row per issue", async () => {
+    const bodies = { 1: "", 2: "Depends on #1", 3: "" };
+    let entries = [];
+    const started = [], g3 = gate(), log = [], decisions = [];
+    const done = orchestrate({ issues: [1, 2, 3], parallel: 3, pollMs: 5, readBody: async (n) => bodies[n] ?? "", getRequeued: () => entries,
+      decide: (d) => { decisions.push(d); }, onUpdate: (r) => log.push(r),
+      runOne: async (n) => {
+        started.push(n);
+        if (n === 3) { await g3.p; return { terminalReason: "merged" }; }
+        if (n === 1 && started.filter((x) => x === 1).length === 1) return { terminalReason: "needs-human", detail: "builder.blocked: product-decision" };
+        return { terminalReason: "merged" };
+      } });
+    await until(() => log.some((r) => r.issue === 2 && r.outcome === "skipped"));
+    entries = [{ issue: 1, reason: "decided in scope", by: "operator", at: "2026-10-24T00:00:00Z" }];
+    await until(() => started.filter((x) => x === 2).length === 1, 3000);
+    g3.open();
+    const rows = await done;
+    assert.deepEqual(started.filter((x) => x === 1).length, 2, "relaunched once");
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"], [3, "merged"]]);
+    assert.equal(rows[0].requeued.reason, "decided in scope");
+    assert.equal(rows[0].requeued.prior[0].outcome, "needs-human");
+    assert.deepEqual(formatOutcomeLists(rows), ["requeued: #1 (decided in scope)"]);
+    assert.ok(decisions.some((d) => d.issue === 1 && /requeued/.test(d.what) && d.why === "decided in scope"));
+    assert.ok(started.indexOf(2) > started.lastIndexOf(1) - 1 && started.filter((x) => x === 2).length === 1, "#2 ran once, after #1 was relaunched");
+  });
+
+  it("an entry is applied once; one for an issue that is not terminal changes nothing", async () => {
+    const entries = [{ issue: 1, reason: "r", by: "operator", at: "t1" }];
+    let runs = 0;
+    const rows = await orchestrate({ issues: [1], parallel: 1, pollMs: 5, readBody: async () => "", getRequeued: () => entries,
+      runOne: async () => { runs++; return { terminalReason: "merged" }; } });
+    assert.equal(runs, 1);
+    assert.equal(rows[0].requeued, undefined);
+  });
+
+  it("batch.requeue: terminal issues are recorded; unknown, merged and double requests are refused; --add still says already in batch", () => {
+    const b = openBatch(tmpDir("batch-requeue-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [1, 2, 3, 4], results: { 1: { outcome: "needs-human" }, 2: { outcome: "merged" }, 3: { outcome: "dependency-blocked" } } });
+    const r = b.requeue([1, 2, 3, 4, 9, "x", 1], { reason: "why", by: "me" });
+    assert.deepEqual(r.requeued, [1, 3]);
+    assert.deepEqual(r.refused.map((x) => [x.issue, x.reason]), [[2, "not terminal"], [4, "not terminal"], [9, "not in batch"], ["x", "not an integer"], [1, "already requeued"]]);
+    assert.deepEqual(b.readRequeued().map((e) => [e.issue, e.reason, e.by]), [[1, "why", "me"], [3, "why", "me"]]);
+    assert.equal(b.unrunRequeues().length, 2);
+    assert.deepEqual(b.addIssues([1]).skipped, [{ issue: 1, reason: "already in batch" }]);
+  });
+
+  it("the CLI refuses a needs-human-labelled or closed issue and writes nothing; an open, cleared one is requeued (a finished batch's report is cleared)", async () => {
+    const root = tmpDir("batch-requeue-cli-");
+    const b = openBatch(root, "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [5, 6, 7], results: { 5: { outcome: "needs-human" }, 6: { outcome: "needs-human" }, 7: { outcome: "needs-human" } } });
+    b.writeReport({ rows: [], report: "x" });
+    const io = { gh: async (a) => JSON.stringify({ state: a[2] === "6" ? "CLOSED" : "OPEN", labels: a[2] === "7" ? [{ name: "needs-human" }] : [] }) };
+    const bad = await quiet(() => orchestrateFromCli(["--requeue", "b1", "6", "7", "--reason", "r"], { batchRoot: root, io }));
+    assert.deepEqual(bad.requeued, []);
+    assert.deepEqual(bad.refused.map((x) => x.issue), [6, 7]);
+    assert.match(bad.refused[1].reason, /needs-human/);
+    assert.deepEqual(b.readRequeued(), []);
+    assert.ok(b.readReport(), "nothing changed");
+    const ok = await quiet(() => orchestrateFromCli(["--requeue", "b1", "5", "--reason", "decided"], { batchRoot: root, io }));
+    assert.deepEqual(ok.requeued, [5]);
+    assert.equal(b.readRequeued()[0].reason, "decided");
+    assert.equal(b.readReport(), null, "the finished batch is reopened for --resume");
+  });
+});
+
 describe("#4540: remote admissions are capped to the provider's free capacity", () => {
   const run = async (capacity) => {
     const c = { t: 1_000_000 };
@@ -760,3 +868,70 @@ describe("#4547: opt-in local fallback in mode remote when no pool agent is onli
     }
   });
 });
+
+describe("#4592: forgedock orchestrate --hold / --release", () => {
+  it("the hold file: holdIssues / readHeld / releaseIssues merge sorted unique positive integers; invalid content reads as []", () => {
+    const b = openBatch(tmpDir("batch-hold-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    assert.deepEqual(b.readHeld(), []);
+    assert.deepEqual(b.holdIssues([5, "#3", "x", 0, 5, "7"]), [3, 5, 7]);
+    assert.deepEqual(b.holdIssues([3, 9]), [9], "already held is not newly held");
+    assert.deepEqual(b.readHeld(), [3, 5, 7, 9]);
+    assert.deepEqual(b.releaseIssues([5, 4, "#9"]), [5, 9]);
+    assert.deepEqual(b.readHeld(), [3, 7]);
+    writeFileSync(join(b.dir, "hold"), "not json");
+    assert.deepEqual(b.readHeld(), []);
+  });
+
+  it("a held issue is never admitted; the rest run, the batch ends with it held, and a release (resume) runs it", async () => {
+    let saved = null, held = [2];
+    const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+    const started = [], log = [];
+    const run = (issues) => orchestrate({ issues, parallel: 2, pollMs: 5, readBody: async () => "", store, getHeld: () => held, onUpdate: (r) => log.push(r),
+      runOne: async (n) => { started.push(n); return { terminalReason: "merged" }; } });
+    const rows = await run([1, 2, 3]);
+    assert.deepEqual(started.sort(), [1, 3], "#2 is not admitted");
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "held"], [3, "merged"]]);
+    assert.equal(rows[1].detail, "held by operator");
+    assert.equal(log.filter((r) => r.outcome === "hold").length, 1, "one row when the set changes");
+    held = [];
+    const resumed = await run([]);
+    assert.deepEqual(resumed.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"], [3, "merged"]]);
+    assert.deepEqual(started.sort(), [1, 2, 3]);
+  });
+
+  it("a release while another lane runs admits the held issue in the same batch", async () => {
+    let saved = null, held = [2], free;
+    const gate = new Promise((r) => { free = r; });
+    const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+    const started = [];
+    const done = orchestrate({ issues: [1, 2], parallel: 2, pollMs: 5, readBody: async () => "", store, getHeld: () => held,
+      runOne: async (n) => { started.push(n); if (n === 1) await gate; return { terminalReason: "merged" }; } });
+    await until(() => started.includes(1));
+    await new Promise((r) => setTimeout(r, 30));
+    assert.deepEqual(started, [1]);
+    held = [];
+    await until(() => started.includes(2));
+    free();
+    assert.deepEqual((await done).map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"]]);
+  });
+
+  it("through the CLI: --hold / --release write the hold file (usage and unknown batch reject); --resume <id> N releases N", async () => {
+    const root = tmpDir("batch-hold-cli-");
+    const b = openBatch(root, "b1");
+    b.writePlan({ argv: [], repo: "o/r" });
+    b.store.save({ order: [1, 2] });
+    const io = { gh: async () => JSON.stringify({ state: "OPEN" }) };
+    let res = await quiet(() => orchestrateFromCli(["--hold", "b1", "1", "2"], { batchRoot: root, io }));
+    assert.deepEqual(res.changed, [1, 2]);
+    res = await quiet(() => orchestrateFromCli(["--release", "b1", "1"], { batchRoot: root, io }));
+    assert.deepEqual(res.changed, [1]);
+    assert.deepEqual(b.readHeld(), [2]);
+    await assert.rejects(orchestrateFromCli(["--hold", "b1"], { batchRoot: root, io }), /usage/);
+    await assert.rejects(orchestrateFromCli(["--hold", "nope", "1"], { batchRoot: root, io }), /no batch nope/);
+    // A resume naming a held issue re-admits it (the plan has no issues, so the resume stops with the usage error after that step).
+    await assert.rejects(quiet(() => orchestrateFromCli(["--resume", "b1", "2"], { batchRoot: root, io })), /usage/);
+    assert.deepEqual(b.readHeld(), []);
+    assert.deepEqual(b.readAdded(), [], "an issue already in the batch is not added again");
+  });
+});

package/bin/lean/budget.mjs

@@ -42,6 +42,17 @@ export const nextSize = (size) => (SIZES.includes(size) ? SIZES[Math.min(SIZES.i
 /** #4505: a `budget.exceeded` recovery lane runs at the next size's budget; any other lane keeps its size. */
 export const recoverySize = (size, recover) => (recover?.code === "budget.exceeded" ? nextSize(size) : size);
 
+/**
+ * Extra implement turns for a big L lane (#4587): +10 per distinct deliverable path above 5, capped at +2x the L base;
+ * a `budget.exceeded` recovery of an L lane adds +ceil(base/2) so it gets more than the pass that failed.
+ * 0 for S/M, an unsized lane or a disabled (0) base.
+ */
+export function scaledExtra({ size, contract = null, recover = null, base = TURN_BUDGET_DEFAULTS.L } = {}) {
+  if (size !== "L" || !(base > 0)) return 0;
+  const paths = Array.isArray(contract?.deliverables) ? new Set(contract.deliverables.map((d) => d?.path).filter((p) => typeof p === "string" && p.trim())).size : 0;
+  return Math.min(10 * Math.max(0, paths - 5), 2 * base) + (recover?.code === "budget.exceeded" ? Math.ceil(base / 2) : 0);
+}
+
 /** Turns the wrap-up call may use after the budget is spent. */
 export const wrapupGrant = (budget) => Math.max(5, Math.ceil(budget / 5));
 
@@ -52,10 +63,10 @@ export const wrapupGrant = (budget) => Math.max(5, Math.ceil(budget / 5));
  */
 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);
+  let size = null, extra = 0, build = 0, total = 0, exceeded = false;
+  const budget = () => (size && Number.isFinite(b[size]) && b[size] > 0 ? b[size] + extra : 0);
   return {
-    setSize(s) { if (SIZES.includes(s)) size = s; },
+    setSize(s, add = 0) { if (SIZES.includes(s)) { size = s; extra = Number.isFinite(add) && add > 0 ? Math.floor(add) : 0; } },
     get size() { return size; },
     budget,
     on: () => budget() > 0,

package/bin/lean/budget.test.mjs

@@ -5,7 +5,7 @@ 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, nextSize, recoverySize, wrapupGrant, makeTurnBudget, budgetDigest, formatTurnSummary } from "./budget.mjs";
+import { TURN_BUDGET_DEFAULTS, parseTurnBudgets, laneSize, nextSize, recoverySize, wrapupGrant, makeTurnBudget, scaledExtra, 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";
@@ -54,6 +54,16 @@ describe("#4392 turn budget", () => {
     assert.equal(wrapupGrant(25), 5); assert.equal(wrapupGrant(100), 20); assert.equal(wrapupGrant(3), 5);
   });
 
+  it("#4587 L budgets scale with the contract (+10/path over 5, cap +2x) and an L recovery gets more; S/M and off unchanged", () => {
+    const b = (n, size = "L", recover = null) => { const tb = makeTurnBudget(); tb.setSize(size, scaledExtra({ size, contract: contract(n), recover })); return tb.budget(); };
+    assert.equal(b(6), 110); assert.equal(b(15), 200); assert.equal(b(40), 300);
+    assert.equal(b(5, "L"), 100);
+    assert.equal(b(15, "L", { code: "budget.exceeded" }), 250); assert.ok(b(6, "L", { code: "budget.exceeded" }) > b(6));
+    assert.equal(b(15, "M"), 60); assert.equal(b(1, "S"), 25);
+    assert.equal(scaledExtra({ size: "L", contract: contract(15), base: 0 }), 0);
+    const off = makeTurnBudget({ L: 0 }); off.setSize("L", 50); assert.equal(off.on(), false);
+  });
+
   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);

package/bin/lean/conflictres.mjs

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Deterministic base-merge conflict resolution for sibling lanes (#4588). Sibling lanes of one milestone always collide
+ * on the same kinds of file once one lands; `resolveBaseConflicts` settles them while a base merge is in progress (ours =
+ * the lane, theirs = the base), with no builder session:
+ *   - `unionGlobs`: append-only lists; hunks where both sides purely added lines keep both (basesync.mjs `unionResolve`).
+ *   - `jsonGlobs`: JSON maps (status files); a 3-way key union. A key both sides changed differently, or a non-object
+ *     document, is refused.
+ *   - `generatedGlobs`: the base side is taken, then `generatedCommand` runs once and the files are re-added.
+ * Sequence/migration files are never touched here (sequence.mjs). A file that cannot be fully resolved stays conflicted
+ * and is returned in `remaining`. Resolved files are `git add`ed; the caller commits. Never throws.
+ */
+import { execFile } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { isSequenceFile, matchesGlobs, unionResolve } from "./basesync.mjs";
+
+const pexec = promisify(execFile);
+const defaultRun = (cmd, { cwd }) => pexec("sh", ["-c", cmd], { cwd, timeout: 600000, maxBuffer: 50 * 1024 * 1024 });
+const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const NONE = Symbol("absent");
+
+/** 3-way merge of parsed JSON (NONE = absent): one-sided changes win, objects merge per key, anything else throws. */
+export function jsonMerge(base, ours, theirs) {
+  if (same(ours, theirs) || same(theirs, base)) return ours;
+  if (same(ours, base)) return theirs;
+  if (!isObj(ours) || !isObj(theirs) || !(isObj(base) || base === NONE)) throw new Error("both sides changed the same value");
+  const b = isObj(base) ? base : {}, out = {};
+  for (const k of [...Object.keys(ours), ...Object.keys(theirs)]) {
+    if (k in out) continue;
+    const v = jsonMerge(k in b ? b[k] : NONE, k in ours ? ours[k] : NONE, k in theirs ? theirs[k] : NONE);
+    if (v !== NONE) out[k] = v;
+  }
+  return out;
+}
+
+/** The merged text of a JSON map file from index stages 1-3, written with the lane's indent; throws when it cannot merge. */
+export function jsonUnionText(baseTxt, oursTxt, theirsTxt) {
+  const base = baseTxt === null ? NONE : JSON.parse(baseTxt), ours = JSON.parse(oursTxt), theirs = JSON.parse(theirsTxt);
+  if (!isObj(ours) || !isObj(theirs)) throw new Error("not a JSON object");
+  const indent = /^([ \t]+)"/m.exec(oursTxt)?.[1] ?? 2;
+  return `${JSON.stringify(jsonMerge(base, ours, theirs), null, indent)}\n`;
+}
+
+/**
+ * @param {{git:(args:string[])=>Promise<string>, cwd:string, files:string[], cfg?:{unionGlobs?:string[],jsonGlobs?:string[],generatedGlobs?:string[],generatedCommand?:string}, run?:Function}} p
+ *   `git` runs in the worktree with the merge in progress and throws on failure.
+ * @returns {Promise<{resolved:string[], remaining:string[], note?:string}>}
+ */
+export async function resolveBaseConflicts({ git, cwd, files = [], cfg = {}, run = defaultRun }) {
+  const resolved = [], remaining = [];
+  try {
+    const stages = new Map();
+    for (const l of lines(await git(["-c", "core.quotepath=off", "ls-files", "-u"]).catch(() => ""))) {
+      const m = /^\d+ \S+ (\d)\t(.+)$/.exec(l); if (m) stages.set(m[2], (stages.get(m[2]) ?? 0) + (1 << Number(m[1])));
+    }
+    const generated = [];
+    for (const f of files) {
+      let ok = false;
+      try {
+        const st = stages.get(f);
+        if (isSequenceFile(f)) ok = false;
+        else if (matchesGlobs(f, cfg.generatedGlobs) && cfg.generatedCommand && (st & 8)) { await git(["checkout", "--theirs", "--", f]); generated.push(f); ok = true; }
+        else if (st === 14 && matchesGlobs(f, cfg.jsonGlobs)) {
+          const show = (n) => git(["show", `:${n}:${f}`]);
+          writeFileSync(join(cwd, f), jsonUnionText(await show(1), await show(2), await show(3))); ok = true;
+        } else if (st === 14 && matchesGlobs(f, cfg.unionGlobs)) {
+          await git(["checkout", "--conflict=diff3", "--", f]);
+          const text = unionResolve(readFileSync(join(cwd, f), "utf8"));
+          if (text !== null) { writeFileSync(join(cwd, f), text); ok = true; }
+        }
+      } catch { ok = false; }
+      if (ok) resolved.push(f); else remaining.push(f);
+    }
+    let note;
+    if (generated.length) {
+      try { await run(cfg.generatedCommand, { cwd }); } catch (e) {
+        note = `generated command failed: ${String(e?.stderr || e?.message || e).trim().split("\n")[0].slice(0, 160)}`;
+        for (const f of generated) { await git(["checkout", "-m", "--", f]).catch(() => {}); resolved.splice(resolved.indexOf(f), 1); remaining.push(f); }
+        generated.length = 0;
+      }
+    }
+    for (const f of resolved) await git(["add", "--", f]);
+    for (const f of generated) await git(["add", "-A", "--", f]);
+    return { resolved, remaining: files.filter((f) => remaining.includes(f)), ...(note ? { note } : {}) };
+  } catch (e) {
+    return { resolved: [], remaining: [...files], note: String(e?.message ?? e).split("\n")[0].slice(0, 160) };
+  }
+}

package/bin/lean/conflictres.test.mjs

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4588: deterministic base-merge conflict resolution, on real temp git repos.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { readBaseMerge } from "../engine-cli.mjs";
+import { resolveBaseConflicts, jsonUnionText } from "./conflictres.mjs";
+
+const sh = (cwd, ...a) => execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", ...a], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+const put = (root, files) => { for (const [p, t] of Object.entries(files)) { mkdirSync(dirname(join(root, p)), { recursive: true }); writeFileSync(join(root, p), t); } };
+const commit = (d, m) => { sh(d, "add", "-A"); sh(d, "commit", "-qm", m); };
+
+/** A repo whose lane and main both edited `files`; the merge of main into the lane is left in progress. */
+function conflicted(root, start, lane, main) {
+  sh(root, "init", "-q", "-b", "main"); put(root, start); commit(root, "base");
+  sh(root, "checkout", "-qb", "lane"); put(root, lane); commit(root, "lane");
+  sh(root, "checkout", "-q", "main"); put(root, main); commit(root, "main");
+  sh(root, "checkout", "-q", "lane");
+  try { sh(root, "merge", "--no-edit", "main"); } catch { /* conflicts */ }
+  return Object.keys(start).filter((f) => sh(root, "diff", "--name-only", "--diff-filter=U").split("\n").includes(f));
+}
+const env = (root) => ({ git: async (a) => sh(root, ...a), cwd: root });
+
+describe("resolveBaseConflicts (#4588)", () => {
+  it("union: two lanes appending to one barrel keep both lines", async () => {
+    const root = tmpDir("cr-union"); const files = conflicted(root, { "index.ts": "a\n" }, { "index.ts": "a\nlane\n" }, { "index.ts": "a\nmain\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { unionGlobs: ["index.ts"] } });
+    assert.deepEqual(r, { resolved: ["index.ts"], remaining: [] });
+    assert.equal(readFileSync(join(root, "index.ts"), "utf8"), "a\nlane\nmain\n");
+    sh(root, "commit", "--no-edit"); // all staged: the merge commits
+  });
+
+  it("union: a hunk that edits a base line is refused and stays conflicted", async () => {
+    const root = tmpDir("cr-union-edit"); const files = conflicted(root, { "index.ts": "a\n" }, { "index.ts": "x\n" }, { "index.ts": "y\n" });
+    assert.deepEqual(await resolveBaseConflicts({ ...env(root), files, cfg: { unionGlobs: ["index.ts"] } }), { resolved: [], remaining: ["index.ts"] });
+  });
+
+  it("json: key union of a status map; the lane's indent is kept", async () => {
+    const root = tmpDir("cr-json");
+    const files = conflicted(root, { "status.json": '{\n    "a": 1\n}\n' }, { "status.json": '{\n    "a": 1,\n    "lane": 2\n}\n' }, { "status.json": '{\n    "a": 1,\n    "main": 3\n}\n' });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { jsonGlobs: ["status.json"] } });
+    assert.deepEqual(r.resolved, ["status.json"]);
+    assert.equal(readFileSync(join(root, "status.json"), "utf8"), '{\n    "a": 1,\n    "lane": 2,\n    "main": 3\n}\n');
+  });
+
+  it("json: the same key changed differently on both sides is refused", async () => {
+    const root = tmpDir("cr-json-clash");
+    const files = conflicted(root, { "status.json": '{"a":1}\n' }, { "status.json": '{"a":2}\n' }, { "status.json": '{"a":3}\n' });
+    assert.deepEqual(await resolveBaseConflicts({ ...env(root), files, cfg: { jsonGlobs: ["status.json"] } }), { resolved: [], remaining: ["status.json"] });
+    assert.throws(() => jsonUnionText('[1]', '[2]', '[3]'));
+  });
+
+  it("generated: the base side is taken and the command regenerates the file", async () => {
+    const root = tmpDir("cr-gen");
+    const files = conflicted(root, { "gen/out.txt": "v0\n", "src.txt": "s\n" }, { "gen/out.txt": "lane\n" }, { "gen/out.txt": "main\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { generatedGlobs: ["gen/*"], generatedCommand: "echo regenerated > gen/out.txt" } });
+    assert.deepEqual(r, { resolved: ["gen/out.txt"], remaining: [] });
+    assert.equal(readFileSync(join(root, "gen/out.txt"), "utf8"), "regenerated\n");
+    assert.equal(sh(root, "diff", "--name-only", "--diff-filter=U"), "");
+  });
+
+  it("generated: a failing command leaves the file conflicted", async () => {
+    const root = tmpDir("cr-gen-fail");
+    const files = conflicted(root, { "gen/out.txt": "v0\n" }, { "gen/out.txt": "lane\n" }, { "gen/out.txt": "main\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { generatedGlobs: ["gen/*"], generatedCommand: "exit 3" } });
+    assert.deepEqual(r.resolved, []);
+    assert.deepEqual(r.remaining, ["gen/out.txt"]);
+    assert.match(r.note, /generated command failed/);
+    assert.match(readFileSync(join(root, "gen/out.txt"), "utf8"), /<<<<<<</);
+  });
+
+  it("sequence files and unconfigured files are left alone", async () => {
+    const root = tmpDir("cr-skip");
+    const files = conflicted(root, { "db/meta/_journal.json": '{"a":1}\n', "x.ts": "a\n" }, { "db/meta/_journal.json": '{"a":1,"l":1}\n', "x.ts": "a\nl\n" }, { "db/meta/_journal.json": '{"a":1,"m":1}\n', "x.ts": "a\nm\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { jsonGlobs: ["*.json"] } });
+    assert.deepEqual(r.resolved, []);
+    assert.deepEqual(r.remaining.sort(), ["db/meta/_journal.json", "x.ts"]);
+    assert.deepEqual(await resolveBaseConflicts({ ...env(root), files, cfg: {} }), { resolved: [], remaining: files });
+  });
+});
+
+describe("readBaseMerge (#4588)", () => {
+  it("reads lean.base_merge_* and is undefined when no glob is set", () => {
+    const root = tmpDir("cr-cfg");
+    assert.equal(readBaseMerge(root), undefined);
+    writeFileSync(join(root, "forge.yaml"), 'lean:\n  base_merge_union_globs: "index.ts, **/messages.ts"\n  base_merge_json_globs: "status.json"\n  base_merge_generated_globs: "gen/**"\n  base_merge_generated_command: "pnpm gen"\n');
+    assert.deepEqual(readBaseMerge(root), { unionGlobs: ["index.ts", "**/messages.ts"], jsonGlobs: ["status.json"], generatedGlobs: ["gen/**"], generatedCommand: "pnpm gen" });
+  });
+});