forgedock 1.24.4 → 1.25.0

package/bin/lean/batch.test.mjs

@@ -0,0 +1,184 @@
+// 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 { spawn } from "node:child_process";
+import { existsSync, 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 } from "./batch.mjs";
+import { orchestrateFromCli, runFromCli, readOrchestration } from "../engine-cli.mjs";
+
+const quiet = async (fn) => { const l = console.log; console.log = () => {}; try { return await fn(); } finally { console.log = l; } };
+const until = async (cond, ms = 15000) => {
+  const end = Date.now() + ms;
+  while (!cond()) { if (Date.now() > end) throw new Error("timed out waiting"); await new Promise((r) => setTimeout(r, 25)); }
+};
+// A fake clock: `sleep` advances it, so delays are asserted without waiting.
+const fakeClock = () => { const c = { t: 1_000_000 }; return { c, now: () => c.t, sleep: async (ms) => { c.t += ms; } }; };
+
+describe("durable batch runner (#4121)", () => {
+  it("killing the dispatcher mid-batch and --resume re-adopts live lanes and finishes without duplicate launches", async () => {
+    const work = tmpDir("batch-int-");
+    const root = join(work, "batches");
+    const launches = join(work, "launches"), release = join(work, "release");
+    writeFileSync(launches, "");
+    // Stub lane: records its launch, waits for the release file, then writes its result like `run-issue --result-file`.
+    const stub = join(work, "stub-lane.mjs");
+    writeFileSync(stub, `import { appendFileSync, existsSync, writeFileSync, renameSync } from "node:fs";
+const a = process.argv.slice(2); const n = Number(a[1]); const rf = a[a.indexOf("--result-file") + 1];
+appendFileSync(${JSON.stringify(launches)}, n + "\\n");
+const t = setInterval(() => { if (!existsSync(${JSON.stringify(release)})) return; clearInterval(t);
+  writeFileSync(rf + ".tmp", JSON.stringify({ terminalReason: "merged", pr: 100 + n, cost_usd: 0 })); renameSync(rf + ".tmp", rf); }, 20);
+`);
+    const depsSrc = `{ batchRoot: ${JSON.stringify(root)}, batchId: "bt1", allowTmpfs: true, laneScript: ${JSON.stringify(stub)}, pollMs: 30,
+      orchestration: { breaker: null, maxDeferrals: 3 }, io: { gh: async () => "o/r\\n" },
+      leanIo: { gh: async (a) => a.includes("milestone") ? JSON.stringify({ milestone: null }) : a[0] === "repo" ? "main\\n" : JSON.stringify({ body: a[2] === "3" ? "Depends on #1" : "" }),
+        git: async (a) => (a[0] === "ls-remote" ? "abc\\trefs/heads/staging\\n" : "") } }`;
+    const dispatcher = join(work, "dispatcher.mjs");
+    writeFileSync(dispatcher, `import { orchestrateFromCli } from ${JSON.stringify(new URL("../engine-cli.mjs", import.meta.url).href)};
+await orchestrateFromCli(["1", "2", "3", "--parallel", "2", "--repo", "o/r", "--no-prefilter"], ${depsSrc});
+`);
+    const batch = openBatch(root, "bt1");
+    const pids = () => Object.values(batch.store.load()?.running ?? {}).map((r) => r.pid).filter(Boolean);
+    let lanePids = [];
+    try {
+      const child = spawn(process.execPath, [dispatcher], { stdio: "ignore" });
+      const exited = new Promise((r) => child.on("exit", r));
+      await until(() => readFileSync(launches, "utf8").trim().split("\n").filter(Boolean).length === 2 && pids().length === 2);
+      lanePids = pids();
+      child.kill("SIGKILL");
+      await exited;
+      // The lanes run in their own session: the dispatcher's death did not take them down.
+      for (const pid of lanePids) assert.equal(isLaneAlive(pid, null), true, `lane ${pid} survived`);
+      const deps = (await import(`data:text/javascript,export default ${encodeURIComponent(depsSrc)}`)).default;
+      const resumed = quiet(() => orchestrateFromCli(["--resume", "bt1"], deps));
+      setTimeout(() => writeFileSync(release, ""), 200);
+      const res = await resumed;
+      assert.deepEqual(res.rows.map((r) => [r.issue, r.outcome, r.pr]), [[1, "merged", 101], [2, "merged", 102], [3, "merged", 103]]);
+      assert.deepEqual(readFileSync(launches, "utf8").trim().split("\n").map(Number).sort(), [1, 2, 3]); // no duplicate launch
+      assert.deepEqual(batch.store.load().running, {});
+    } finally {
+      writeFileSync(release, "");
+      for (const pid of lanePids) { try { process.kill(pid, "SIGKILL"); } catch { /* gone */ } }
+    }
+  });
+
+  it("deferred codes are requeued with their own delay; non-host deferrals stop at the cap", async () => {
+    const { now, sleep } = fakeClock();
+    const seq = [
+      { code: "host.busy", retryInSeconds: 60 },
+      { code: "rate_limited", resetAtEpochMs: null, retryInSeconds: 600 },
+      { code: "merge.transient" },
+      { code: "push.transient" },
+      { code: "cli.idle" },
+    ];
+    const starts = [];
+    const rows = await orchestrate({ issues: [1], readBody: async () => "", now, sleep, maxDeferrals: 3,
+      runOne: async () => { starts.push(now()); const d = seq.shift(); return { terminalReason: "deferred", detail: d.code, ...d }; } });
+    const gaps = starts.slice(1).map((t, i) => (t - starts[i]) / 1000);
+    assert.deepEqual(gaps, [60, 600, DEFER_BACKOFF_S * 2, DEFER_BACKOFF_S * 4]);
+    assert.equal(rows[0].outcome, "deferred");
+    assert.match(rows[0].detail, /gave up after 3 deferrals/);
+    // the usage-limit reset time and a lease expiry are honoured
+    assert.deepEqual(deferPolicy({ code: "rate_limited", resetAtEpochMs: 5000 }, { now: 1000 }), { delayMs: 4000, hold: true });
+    assert.equal(deferPolicy({ code: "lease-held", detail: "leased by x until 1970-01-01T00:01:40.000Z" }, { now: 0 }).delayMs, 105000);
+    assert.deepEqual(deferPolicy({ code: "host.busy" }, { now: 0, deferrals: 99 }), { delayMs: 60000, host: true });
+  });
+
+  it("a usage limit holds every admission until its reset; a deferred issue's dependents wait instead of being skipped", async () => {
+    const { now, sleep, c } = fakeClock();
+    const t0 = c.t, starts = {};
+    let limited = true;
+    const rows = await orchestrate({ issues: [1, 2, 3], parallel: 1, now, sleep, readBody: async (n) => (n === 3 ? "Blocked by #1" : ""),
+      runOne: async (n) => {
+        (starts[n] ??= []).push(now());
+        if (n === 1 && limited) { limited = false; return { terminalReason: "deferred", code: "rate_limited", resetAtEpochMs: t0 + 600_000 }; }
+        return { terminalReason: "merged" };
+      } });
+    assert.deepEqual(rows.map((r) => r.outcome), ["merged", "merged", "merged"]);
+    assert.ok(starts[2][0] >= t0 + 600_000, "no admission during the hold");
+    assert.equal(starts[1].length, 2);
+  });
+
+  it("the breaker stops admissions after N engine-errors in M minutes and lets running lanes finish", async () => {
+    const started = [];
+    let releaseSlow;
+    const slow = new Promise((r) => { releaseSlow = r; });
+    // #3 runs slowly; #1 fails (relaunch queued behind #2, #4), then #2 fails: two errors in the window trip the breaker.
+    const rows = await orchestrate({ issues: [3, 1, 2, 4], parallel: 2, breaker: { errors: 2, window_min: 30 }, readBody: async () => "",
+      onUpdate: (r) => { if (r.outcome === "breaker") setTimeout(releaseSlow, 10); },
+      runOne: async (n) => {
+        started.push(n);
+        if (n === 3) { await slow; return { terminalReason: "merged", pr: 103 }; }
+        throw new Error(`boom ${n}`);
+      } });
+    assert.deepEqual(started, [3, 1, 2]);
+    assert.deepEqual(rows.map((r) => r.outcome), ["merged", "held", "held", "held"]);
+    assert.match(rows[1].detail, /circuit breaker: 2 engine-errors within 30 min/);
+  });
+
+  it("an engine-error is relaunched once; a resume after the breaker continues the held issues", async () => {
+    const saved = { state: null };
+    const store = { load: () => saved.state, save: (s) => { saved.state = JSON.parse(JSON.stringify(s)); } };
+    const runs = [];
+    let fail = true;
+    const runOne = async (n) => { runs.push(n); if (fail) throw new Error("x"); return { terminalReason: "merged" }; };
+    let rows = await orchestrate({ issues: [1, 2, 3], parallel: 1, breaker: { errors: 2, window_min: 30 }, store, readBody: async () => "", runOne });
+    assert.deepEqual(runs, [1, 2]); // #1's relaunch is queued behind #2, whose error trips the breaker
+    assert.deepEqual(rows.map((r) => r.outcome), ["held", "held", "held"]);
+    fail = false;
+    saved.state = { ...saved.state, breaker: null, errorTimes: [] }; // what --resume does
+    rows = await orchestrate({ issues: [1, 2, 3], parallel: 1, breaker: { errors: 2, window_min: 30 }, store, readBody: async () => "", runOne });
+    assert.deepEqual(rows.map((r) => r.outcome), ["merged", "merged", "merged"]);
+    assert.deepEqual(runs, [1, 2, 3, 1, 2]);
+    // without a breaker an engine-error is relaunched exactly once, then final
+    const again = [];
+    const [row] = await orchestrate({ issues: [9], readBody: async () => "", runOne: async (n) => { again.push(n); throw new Error("boom"); } });
+    assert.deepEqual([again, row.outcome], [[9, 9], "engine-error"]);
+  });
+
+  it("concurrency follows the live K", async () => {
+    let k = 1, active = 0, maxActive = 0;
+    const rows = await orchestrate({ issues: [1, 2, 3, 4, 5, 6, 7], parallel: 1, pollMs: 5, getParallel: () => k, readBody: async () => "",
+      onUpdate: () => { k = 3; },
+      runOne: async () => { active++; maxActive = Math.max(maxActive, active); await new Promise((r) => setTimeout(r, 15)); active--; return { terminalReason: "merged" }; } });
+    assert.equal(maxActive, 3);
+    assert.equal(rows.length, 7);
+  });
+
+  it("batch files: atomic writes, live K via --set-parallel, tmpfs refused, pid reuse not adopted", async () => {
+    const root = tmpDir("batch-files-");
+    const b = openBatch(root, "b1");
+    b.writePlan({ argv: ["1"] });
+    await quiet(() => orchestrateFromCli(["--set-parallel", "b1", "7"], { batchRoot: root }));
+    assert.equal(b.readParallel(), 7);
+    await assert.rejects(orchestrateFromCli(["--set-parallel", "nope", "2"], { batchRoot: root }), /no batch nope/);
+    await assert.rejects(orchestrateFromCli(["--set-parallel", "b1", "0"], { batchRoot: root }), /positive integer/);
+    assert.throws(() => openBatch(root, "../x"), /invalid batch id/);
+    writeAtomic(join(root, "f.json"), "{}");
+    assert.equal(readFileSync(join(root, "f.json"), "utf8"), "{}");
+    const mounts = [{ mount: "/", type: "ext4" }, { mount: "/tmp", type: "tmpfs" }, { mount: "/home", type: "btrfs" }];
+    assert.equal(fsTypeOf("/tmp/x/y", mounts), "tmpfs");
+    assert.equal(fsTypeOf("/tmpx/y", mounts), "ext4");
+    assert.throws(() => assertDiskPath("/tmp/batches", mounts), /must be on disk/);
+    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);
+    assert.deepEqual(readOrchestration(root), { breaker: { errors: 3, window_min: 30 }, maxDeferrals: 3 });
+    writeFileSync(join(root, "forge.yaml"), "orchestration:\n  breaker:\n    errors: 5\n    window_min: 10\n  max_deferrals: 2\n");
+    assert.deepEqual(readOrchestration(root), { breaker: { errors: 5, window_min: 10 }, maxDeferrals: 2 });
+  });
+
+  it("run-issue --result-file writes the lane result, also when the run throws", async () => {
+    const d = tmpDir("batch-rf-");
+    const rf = join(d, "lanes", "7.json");
+    const base = { dir: d, emitTelemetry: async () => {}, leanIo: {}, io: { gh: async () => "o/r\n" } };
+    await quiet(() => runFromCli(["7", "--repo", "o/r", "--result-file", rf], { ...base, leanModule: { runCore: async () => ({ terminalReason: "merged", pr: 9 }) } }));
+    assert.deepEqual(JSON.parse(readFileSync(rf, "utf8")), { terminalReason: "merged", pr: 9 });
+    await assert.rejects(quiet(() => runFromCli(["7", "--repo", "o/r", "--result-file", rf], { ...base, leanModule: { runCore: async () => { throw new Error("kaboom"); } } })), /kaboom/);
+    assert.equal(JSON.parse(readFileSync(rf, "utf8")).terminalReason, "engine-error");
+    assert.ok(!existsSync(`${rf}.tmp-${process.pid}`));
+  });
+});

package/bin/lean/lane.mjs

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Lane resolution for core work-on (#4125). The lane (base and merge branch) comes from the issue, not the caller:
+ * a milestone maps to forge.yaml `branches.feature_pattern` with `{slug}` from the milestone title, otherwise
+ * `branches.staging`. A requested `--lane` is an assertion; the default/production branch is never a lane; the branch
+ * must exist on origin. Every failure is fail-closed with a typed `lane.*` code. Reads are injected through `io`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseForgeYaml } from "../forge-utils.mjs";
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+
+/** The documented forge.yaml conventions (forge.yaml.example, scripts/classify-lane.sh); always verified on origin. */
+export const DEFAULT_STAGING_BRANCH = "staging";
+export const DEFAULT_FEATURE_PATTERN = "milestone/{slug}";
+const LANE_RE = /^[A-Za-z0-9._][A-Za-z0-9._/-]*$/;
+
+/** Same slug as scripts/classify-lane.sh: lowercase, spaces to hyphens, keep [a-z0-9-], collapse and trim hyphens. */
+export function milestoneSlug(title) {
+  return String(title ?? "").toLowerCase().replace(/ /g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+
+/** forge.yaml `branches` from the checkout: {default, staging, featurePattern}; missing keys are null. */
+export function readBranches(cwd = process.cwd()) {
+  let b = {};
+  try { b = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.branches ?? {}; } catch { b = {}; }
+  const s = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
+  return { default: s(b.default), staging: s(b.staging), featurePattern: s(b.feature_pattern) };
+}
+
+/** True when `lane` is one of the default (production) branches. */
+export function isDefaultLane(lane, defaults) {
+  return !!lane && (defaults ?? []).includes(lane);
+}
+
+/** The repo's default branches: forge.yaml `branches.default` plus GitHub's default branch. Throws when GitHub's is unreadable. */
+export async function defaultBranches({ repo, io, branches = {} }) {
+  const gh = String(await io.gh(["repo", "view", repo, "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"])).trim();
+  if (!gh) throw new Error("GitHub reported no default branch");
+  return [...new Set([branches.default, gh].filter(Boolean))];
+}
+
+/**
+ * @returns {Promise<{ok:true, lane:string, expected:string, milestone:?string, overridden:boolean, defaults:string[]}
+ *   | {ok:false, code:string, detail:string}>}
+ */
+export async function resolveLane({ issue, repo, io, cwd, branches = {}, requested = null, override = false }) {
+  const refuse = (code, detail) => ({ ok: false, code, detail });
+  const staging = branches.staging || DEFAULT_STAGING_BRANCH;
+  const pattern = branches.featurePattern || DEFAULT_FEATURE_PATTERN;
+  if (!pattern.includes("{slug}")) return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `forge.yaml branches.feature_pattern "${pattern}" has no {slug}`);
+  let milestone = null, defaults;
+  try {
+    milestone = JSON.parse(String(await io.gh(["issue", "view", String(issue), "-R", repo, "--json", "milestone"])))?.milestone?.title || null;
+  } catch (e) { return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `cannot read the milestone of #${issue}: ${String(e?.message ?? e).slice(0, 200)}`); }
+  try { defaults = await defaultBranches({ repo, io, branches }); } catch (e) {
+    return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `cannot read the default branch of ${repo}: ${String(e?.message ?? e).slice(0, 200)}`);
+  }
+  let expected = staging;
+  if (milestone) {
+    const slug = milestoneSlug(milestone);
+    if (!slug) return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `milestone "${milestone}" gives an empty branch slug; rename it to include ASCII letters or digits`);
+    expected = pattern.replace("{slug}", slug);
+  }
+  const why = milestone ? `milestone "${milestone}"` : "no milestone (branches.staging)";
+  if (isDefaultLane(requested, defaults)) {
+    return refuse(OUTCOME_CODES.LANE_DEFAULT_BRANCH, `--lane ${requested} is the default branch; the core path never targets it (promotion is a human-merged release PR). #${issue} belongs on ${expected} (${why})`);
+  }
+  if (isDefaultLane(expected, defaults)) {
+    return refuse(OUTCOME_CODES.LANE_DEFAULT_BRANCH, `#${issue} resolves to ${expected} (${why}), which is the default branch; set forge.yaml branches.staging to a non-default branch`);
+  }
+  let lane = expected, overridden = false;
+  if (requested && requested !== expected) {
+    if (!override) return refuse(OUTCOME_CODES.LANE_MISMATCH, `--lane ${requested} does not match #${issue}'s lane ${expected} (${why}); omit --lane, or pass --lane-override to force it`);
+    lane = requested; overridden = true;
+  }
+  if (!LANE_RE.test(lane) || lane.includes("..")) return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `invalid lane ${JSON.stringify(lane)}`);
+  let out;
+  try { out = String(await io.git(["ls-remote", "--heads", "origin", `refs/heads/${lane}`], { cwd })); } catch (e) {
+    return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `cannot check origin for ${lane}: ${String(e?.message ?? e).slice(0, 200)}`);
+  }
+  if (!out.trim()) return refuse(OUTCOME_CODES.LANE_BRANCH_MISSING, `lane branch ${lane} (${why}) does not exist on origin; create it first (e.g. /milestone start) or fix the milestone title`);
+  return { ok: true, lane, expected, milestone, overridden, defaults };
+}

package/bin/lean/lane.test.mjs

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync } from "node:fs";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { milestoneSlug, readBranches, resolveLane } from "./lane.mjs";
+
+/** Fake gh/git: the issue's milestone, GitHub's default branch, and the branches on origin. */
+function io({ milestone = null, ghDefault = "main", onOrigin = ["staging", "main"], ghFails = null, gitFails = false } = {}) {
+  const calls = [];
+  return {
+    calls,
+    gh: async (a) => {
+      calls.push(["gh", ...a]);
+      if (ghFails && a[0] === ghFails) throw new Error("HTTP 502");
+      if (a[0] === "issue" && a[1] === "view") return JSON.stringify({ milestone: milestone ? { title: milestone } : null });
+      if (a[0] === "repo" && a[1] === "view") return `${ghDefault}\n`;
+      throw new Error(`unexpected gh ${a.join(" ")}`);
+    },
+    git: async (a) => {
+      calls.push(["git", ...a]);
+      if (gitFails) throw new Error("network down");
+      const b = a.at(-1).replace(/^refs\/heads\//, "");
+      return onOrigin.includes(b) ? `abc\trefs/heads/${b}\n` : "";
+    },
+  };
+}
+const resolve = (o, extra = {}) => resolveLane({ issue: 5, repo: "o/r", io: io(o), cwd: "/repo", ...extra });
+
+describe("lane resolution (#4125)", () => {
+  it("slug matches scripts/classify-lane.sh", () => {
+    assert.equal(milestoneSlug("Adaptive Unblocking: Control Loop"), "adaptive-unblocking-control-loop");
+    assert.equal(milestoneSlug("User Auth v2"), "user-auth-v2");
+    assert.equal(milestoneSlug(" -- Foo  (Bar) -- "), "foo-bar");
+    assert.equal(milestoneSlug("🚀✨"), "");
+  });
+
+  it("a milestone issue resolves to feature_pattern with the slug; no milestone resolves to staging", async () => {
+    const m = await resolve({ milestone: "Adaptive Unblocking Control Loop", onOrigin: ["staging", "milestone/adaptive-unblocking-control-loop"] });
+    assert.deepEqual([m.ok, m.lane, m.overridden], [true, "milestone/adaptive-unblocking-control-loop", false]);
+    const s = await resolve({});
+    assert.deepEqual([s.ok, s.lane], [true, "staging"]);
+  });
+
+  it("forge.yaml branches.staging and feature_pattern are honoured", async () => {
+    const branches = { staging: "develop", featurePattern: "feature/{slug}" };
+    assert.equal((await resolve({ onOrigin: ["develop"] }, { branches })).lane, "develop");
+    assert.equal((await resolve({ milestone: "X Y", onOrigin: ["feature/x-y"] }, { branches })).lane, "feature/x-y");
+    const bad = await resolve({}, { branches: { featurePattern: "milestone/fixed" } });
+    assert.equal(bad.code, "lane.unresolved");
+  });
+
+  it("--lane is an assertion: a mismatch is refused, --lane-override accepts it", async () => {
+    const o = { milestone: "M1", onOrigin: ["staging", "milestone/m1"] };
+    const r = await resolve(o, { requested: "staging" });
+    assert.equal(r.ok, false); assert.equal(r.code, "lane.mismatch");
+    assert.match(r.detail, /--lane staging does not match #5's lane milestone\/m1/);
+    assert.equal((await resolve(o, { requested: "milestone/m1" })).ok, true);
+    const ov = await resolve(o, { requested: "staging", override: true });
+    assert.deepEqual([ov.ok, ov.lane, ov.expected, ov.overridden], [true, "staging", "milestone/m1", true]);
+  });
+
+  it("the default branch is never a lane, even with an override or when staging is configured as it", async () => {
+    for (const requested of ["main", "trunk"]) {
+      const r = await resolve({ ghDefault: "trunk" }, { requested, override: true, branches: { default: "main" } });
+      assert.equal(r.code, "lane.default_branch", requested);
+    }
+    assert.equal((await resolve({}, { branches: { staging: "main" } })).code, "lane.default_branch");
+  });
+
+  it("a missing lane branch fails closed with lane.branch_missing", async () => {
+    const r = await resolve({ milestone: "Not Created", onOrigin: ["staging"] });
+    assert.equal(r.code, "lane.branch_missing");
+    assert.match(r.detail, /milestone\/not-created/);
+  });
+
+  it("unreadable milestone, default branch or origin, and an empty slug, fail closed with lane.unresolved", async () => {
+    assert.equal((await resolve({ ghFails: "issue" })).code, "lane.unresolved");
+    assert.equal((await resolve({ ghFails: "repo" })).code, "lane.unresolved");
+    assert.equal((await resolve({ gitFails: true })).code, "lane.unresolved");
+    assert.equal((await resolve({ milestone: "🚀" })).code, "lane.unresolved");
+  });
+
+  it("readBranches reads forge.yaml branches; missing keys are null", () => {
+    const d = tmpDir("lane-");
+    writeFileSync(`${d}/forge.yaml`, 'branches:\n  default: "main"\n  staging: "develop"\n  feature_pattern: "milestone/{slug}"\n');
+    assert.deepEqual(readBranches(d), { default: "main", staging: "develop", featurePattern: "milestone/{slug}" });
+    assert.deepEqual(readBranches(tmpDir("lane-")), { default: null, staging: null, featurePattern: null });
+  });
+});

package/bin/lean/lean.mjs

@@ -12,19 +12,48 @@ import { codeForTerminalReason, OUTCOME_CODES } from "../engine/outcome-codes.mj
 import { ciPollDelayMs, ENGINE_VERSION, DEFAULT_MAX_SESSION_LIMIT_PAUSES, DEFAULT_SESSION_LIMIT_WAIT_MS, parseLeaseHolder, sanitizeLeaseHost } from "../engine.mjs";
 import { openDependency } from "../engine/phases.mjs";
 import { checkAdmission, ADMISSION_RETRY_SECONDS } from "./admission.mjs";
+import { resolveLane, isDefaultLane } from "./lane.mjs";
 import { retrying, PUSH_TRANSIENT_RE, PUSH_PERMANENT_RE, GH_TRANSIENT_RE, MERGE_TRANSIENT_RE, MERGE_CONFLICT_RE } from "./retry.mjs";
 import { renderInvestigation, renderPlan, renderImplementation, renderReview, renderPrBody, renderTrajectory, capComment, sanitizeMd } from "./render.mjs";
-import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, PLAN_FILE, IMPLEMENTATION_FILE, builderPrompt, resumeBuilderPrompt, reviewerPrompt, parseVerdict } from "./prompts.mjs";
+import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, PLAN_FILE, IMPLEMENTATION_FILE, builderPrompt, resumeBuilderPrompt, reviewerPrompt, REVIEW_DIFF_MAX_BYTES, parseVerdict, blockCorrectionPrompt, HUMAN_BLOCK_REASONS } from "./prompts.mjs";
 
 export const DEFAULT_REVIEWER_MODEL = "claude-sonnet-5-5";
 export const REGISTER_MARKER = "FORGE:WORK-ON"; // alias marker carried by the FORGE:TRAJECTORY comment
 const num = (v) => (Number.isFinite(v) ? v : null);
+export const MAX_SUBISSUES = 8;
+
+/**
+ * Typed builder block (#4124), from result.json `block`. Returns {kind:"dependency", issues} | {kind:"split", subissues}
+ * | {kind:"human", why} | {kind:"untyped", problem}. Only `human` with an allowed reason may end as needs-human.
+ */
+export function classifyBlock(result, issue) {
+  const b = result?.block;
+  if (!b || typeof b !== "object" || Array.isArray(b)) return { kind: "untyped", problem: "it has no typed \"block\" object" };
+  if (b.kind === "dependency") {
+    const issues = [...new Set((Array.isArray(b.issues) ? b.issues : []).map((x) => Number(String(x).replace(/^#/, ""))))].filter((n) => Number.isSafeInteger(n) && n > 0 && n !== Number(issue));
+    return issues.length ? { kind: "dependency", issues } : { kind: "untyped", problem: "the dependency block names no other issue number" };
+  }
+  if (b.kind === "split-required") {
+    const subs = (Array.isArray(b.subissues) ? b.subissues : []).filter((x) => x && typeof x.title === "string" && x.title.trim() && typeof x.body === "string");
+    if (!subs.length) return { kind: "untyped", problem: "the split-required block lists no sub-issues with a title and body" };
+    if (subs.length > MAX_SUBISSUES) return { kind: "untyped", problem: `the split-required block lists ${subs.length} sub-issues (at most ${MAX_SUBISSUES})` };
+    return { kind: "split", subissues: subs.map((x, i) => ({ title: x.title.trim(), body: x.body,
+      dependsOn: [...new Set((Array.isArray(x.depends_on) ? x.depends_on : []).filter((j) => Number.isInteger(j) && j >= 0 && j < i))] })) };
+  }
+  if (b.kind === "human") {
+    return HUMAN_BLOCK_REASONS.includes(b.why) ? { kind: "human", why: b.why }
+      : { kind: "untyped", problem: `"${String(b.why ?? "").slice(0, 80)}" is not a human-only reason (${HUMAN_BLOCK_REASONS.join(", ")})` };
+  }
+  return { kind: "untyped", problem: `block kind "${String(b.kind ?? "").slice(0, 40)}" is unknown` };
+}
 
 /**
  * @param {object} o
  * @param {number} o.issue
  * @param {string} o.repo            "owner/repo"
- * @param {string} o.lane            base branch (staging|main)
+ * @param {string} [o.lane]          requested lane: an assertion checked against the lane resolved from the issue (#4125)
+ * @param {boolean} [o.laneOverride] accept a requested lane that differs from the resolved one (never the default branch)
+ * @param {object} [o.branches]      forge.yaml branches {default, staging, featurePattern} (lane.mjs readBranches)
  * @param {string} o.cwd             main checkout (worktrees are added from here)
  * @param {string} o.dir             run-log dir
  * @param {object} o.io              injected effects: gh, git, runner, waitCiGreen, transitionLabel, fs, projector?, now?, sleep?
@@ -33,11 +62,11 @@ const num = (v) => (Number.isFinite(v) ? v : null);
  * @param {number} [o.ciMaxMinutes]  remote-CI wait budget (default 360); exhaustion is NOT needs-human
  */
 export async function runCore(o) {
-  const { issue, repo, lane, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
+  const { issue, repo, lane: requestedLane = null, laneOverride = false, branches = {}, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
     ciMaxMinutes = 360, mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, cliIdleMinutes = 15, cliMaxMinutes = 180, laneLimits = null, maxMergeRetries = 5, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
   const now = io.now ?? (() => Date.now());
   const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-  const base = `origin/${lane}`;
+  let lane = null, base = null, defaults = []; // set by lane resolution, before the lease
   const branch = `feat/issue-${issue}-lean`;
   const wt = join(o.worktreeRoot ?? join(cwd, ".claude", "worktrees"), `lean-${issue}`);
   const t0 = now();
@@ -101,7 +130,7 @@ export async function runCore(o) {
     const code = codeOverride ?? codeForTerminalReason(reason);
     ev({ event: "RUN_TERMINAL", reason, code });
     await emit({ event: "RUN_TERMINAL", reason, code });
-    if (["needs-human", "engine-error"].includes(reason)) {
+    if (["needs-human", "engine-error", "dependency-open", "dependency-blocked", "dependency-unreadable", "decomposed"].includes(reason)) {
       const wf = ["investigating", "building", "in-review"].map((x) => `workflow:${x}`).join(",");
       try { await ghc(["issue", "edit", String(issue), "-R", repo, "--remove-label", wf]); } catch { /* best effort */ }
     }
@@ -285,11 +314,75 @@ export async function runCore(o) {
   }
   const readResult = async () => { try { const j = JSON.parse(await io.fs.read(`${wt}/${RESULT_FILE}`)); return j && typeof j === "object" ? j : null; } catch { return null; } };
 
+  /** Live-checks a builder block (#4124). Dependency issues are re-read, so a closed or unknown number is not a block. */
+  async function resolveBlock(r) {
+    const b = classifyBlock(r, issue);
+    if (b.kind !== "dependency") return b;
+    const open = [], blockers = [];
+    for (const d of b.issues) {
+      let v;
+      try { v = JSON.parse(String(await ghc(["issue", "view", String(d), "-R", repo, "--json", "state,labels"]))); } catch (e) {
+        return { kind: "unreadable", detail: `dependency #${d} named by the builder could not be read: ${String(e?.message ?? e).slice(0, 200)}` };
+      }
+      if (String(v?.state).toUpperCase() !== "OPEN") continue;
+      open.push(d);
+      if ((v.labels ?? []).some((l) => (l?.name ?? l) === "needs-human")) blockers.push(d);
+    }
+    if (!open.length) return { kind: "untyped", problem: `its dependencies ${b.issues.map((n) => `#${n}`).join(", ")} are not open` };
+    return { kind: "dependency", issues: open, blockers };
+  }
+  /** Ends a run whose builder stayed blocked: only a typed human reason is needs-human. */
+  async function endBlocked(b, summary) {
+    const s = summary ?? "(no summary)";
+    const refs = (ns) => ns.map((n) => `#${n}`).join(", ");
+    if (b.kind === "human") return await needsHuman(`Builder is blocked (${b.why}): ${s}`, OUTCOME_CODES.BUILDER_BLOCKED);
+    if (b.kind === "unreadable") return await finish("dependency-unreadable", b.detail);
+    if (b.kind === "dependency") {
+      const blocked = b.blockers.length > 0;
+      const detail = blocked
+        ? `blocked by ${refs(b.blockers)} (needs-human); depends on ${refs(b.issues)}. ${s}`
+        : `depends on ${refs(b.issues)} which is still open; requeue behind it. ${s}`;
+      T.decisions.push(`Builder block: dependency on ${refs(b.issues)}${blocked ? ` (needs-human: ${refs(b.blockers)})` : ""}`);
+      try { await post("FORGE:DEPENDENCY", `## ${blocked ? "Blocked by" : "Waiting on"} ${refs(blocked ? b.blockers : b.issues)}\n${detail}\n\n_${usageLine()}_`); } catch { /* best effort */ }
+      return blocked
+        ? await finish("dependency-blocked", detail, { code: OUTCOME_CODES.DEPENDENCY_BLOCKED, dependencies: b.issues, blockers: b.blockers }, OUTCOME_CODES.DEPENDENCY_BLOCKED)
+        : await finish("dependency-open", detail, { code: OUTCOME_CODES.DEPENDENCY_OPEN, dependencies: b.issues }, OUTCOME_CODES.DEPENDENCY_OPEN);
+    }
+    if (b.kind === "split") {
+      const filed = [];
+      try {
+        for (const sub of b.subissues) {
+          const lines = [`**Parent**: #${issue}`, ...sub.dependsOn.map((j) => `**Depends on**: #${filed[j]}`)];
+          const out = String(await ghw(["issue", "create", "-R", repo, "--title", sub.title, "--body", `${sub.body.trim()}\n\n${lines.join("\n")}`]));
+          const n = Number(/\/issues\/(\d+)/.exec(out)?.[1]);
+          if (!Number.isSafeInteger(n)) throw new Error(`cannot parse the sub-issue number from: ${out.slice(0, 200)}`);
+          filed.push(n);
+        }
+      } catch (e) { return await finish("engine-error", `filing sub-issues failed after ${refs(filed) || "none"}: ${e?.message ?? e}`, { subissues: filed }); }
+      T.decisions.push(`Builder block: split into ${refs(filed)}`);
+      try { await post("FORGE:DECOMPOSED", `## Split into sub-issues\n${filed.map((n, i) => `- #${n} ${b.subissues[i].title}`).join("\n")}\n\n${s}`); } catch { /* best effort */ }
+      await label("decomposed");
+      return await finish("decomposed", `split into ${refs(filed)}`, { code: OUTCOME_CODES.DECOMPOSED, subissues: filed });
+    }
+    return await needsHuman(`Builder is blocked without a valid typed reason after one correction (${b.problem}): ${s}`, OUTCOME_CODES.BUILDER_BLOCK_UNTYPED);
+  }
+
   // ---- host admission (#4105): before the lease, the worktree or any GitHub call ----
   if (io.host && o.admission?.enabled !== false) {
     const a = await checkAdmission({ cfg: o.admission, host: io.host });
     if (!a.ok) return { terminalReason: "deferred", code: OUTCOME_CODES.HOST_BUSY, detail: a.detail, retryInSeconds: ADMISSION_RETRY_SECONDS };
   }
+  // ---- lane (#4125): worked out from the issue before any lease, comment or worktree; fail closed ----
+  {
+    const r = await resolveLane({ issue, repo, io, cwd, branches, requested: requestedLane, override: laneOverride });
+    if (!r.ok) return { terminalReason: "lane-refused", code: r.code, detail: r.detail };
+    lane = r.lane; base = `origin/${lane}`; defaults = r.defaults;
+    if (r.overridden) T.decisions.push(`Lane override: ${lane} instead of the resolved ${r.expected}`);
+  }
+  /** Last guard before a PR is created or merged: the default branch is never a lane. */
+  const laneGuard = (target, what) => {
+    if (isDefaultLane(target, defaults)) throw Object.assign(new Error(`refusing to ${what} into the default branch ${target}`), { laneCode: OUTCOME_CODES.LANE_DEFAULT_BRANCH });
+  };
   // ---- admission: Depends-on refusal, then lease ----
   {
     let dep = null;
@@ -335,10 +428,15 @@ export async function runCore(o) {
     try { await io.git(["fetch", "origin", lane], { cwd }); } catch { /* offline: use the local ref */ }
     let resumed = null;
     try {
-      const prs = JSON.parse(String(await ghc(["pr", "list", "-R", repo, "--head", branch, "--state", "open", "--json", "number,headRefOid"])) || "[]");
+      const prs = JSON.parse(String(await ghc(["pr", "list", "-R", repo, "--head", branch, "--state", "open", "--json", "number,headRefOid,baseRefName"])) || "[]");
       const remote = String(await io.git(["ls-remote", "--heads", "origin", branch], { cwd })).trim();
-      if (prs.length || remote) resumed = { pr: prs[0]?.number ?? null };
+      if (prs.length || remote) resumed = { pr: prs[0]?.number ?? null, base: prs[0]?.baseRefName ?? null };
     } catch { /* no resume info: start fresh */ }
+    // An open PR on another base (a hand-retargeted PR, or one opened before lane resolution) is never merged (#4125).
+    if (resumed?.base && resumed.base !== lane) {
+      return await needsHuman(`Open PR #${resumed.pr} targets \`${resumed.base}\`, but #${issue}'s lane is \`${lane}\`; retarget or close it before rerunning.`,
+        isDefaultLane(resumed.base, defaults) ? OUTCOME_CODES.LANE_DEFAULT_BRANCH : OUTCOME_CODES.LANE_MISMATCH);
+    }
     try { await io.git(["worktree", "remove", "--force", wt], { cwd }); } catch { /* none */ }
     try { await io.git(["worktree", "prune"], { cwd }); } catch { /* best effort */ }
     // Concurrent lanes in one repo race on .git/config.lock / index.lock during `worktree add`; retry with jitter.
@@ -366,8 +464,23 @@ export async function runCore(o) {
         }
       }
     };
-    if (resumed) {
-      await io.git(["fetch", "origin", branch], { cwd });
+    if (resumed) { try { await io.git(["fetch", "origin", branch], { cwd }); } catch { /* remote branch may not exist (PR-less resume) */ } }
+    // #4118: a local lane branch with commits not yet pushed (e.g. a reviewed commit whose push failed) must never be reset.
+    // Reuse it when it is ahead of the base and contains everything the remote branch has.
+    let keepLocal = false;
+    try {
+      const ahead = Number(String(await io.git(["rev-list", "--count", `${base}..refs/heads/${branch}`], { cwd })).trim());
+      if (ahead > 0) {
+        let containsRemote = true;
+        if (resumed) { try { await io.git(["merge-base", "--is-ancestor", `origin/${branch}`, `refs/heads/${branch}`], { cwd }); } catch { containsRemote = false; } }
+        keepLocal = containsRemote;
+      }
+    } catch { /* no local branch */ }
+    if (keepLocal) {
+      await addWorktree(["worktree", "add", wt, branch]);
+      resumed = resumed ?? { pr: null, local: true };
+      ev({ event: "LOCAL_BRANCH_REUSED", branch });
+    } else if (resumed) {
       await addWorktree(["worktree", "add", "-B", branch, wt, `origin/${branch}`]);
     } else {
       await addWorktree(["worktree", "add", "-B", branch, wt, base]);
@@ -385,6 +498,13 @@ export async function runCore(o) {
       await label("building");
       await builder(++attemptN, builderPrompt(issue) + (fromCheckpoint ? CONTINUE_NOTE.replace("BASE", base) : ""), null, true);
       result = await readResult();
+      let block = result?.status === "blocked" ? await resolveBlock(result) : null;
+      if (block?.kind === "untyped" && sessionId) { // #4124: one corrective resume before any untyped block can reach needs-human
+        T.decisions.push(`Builder block rejected (${block.problem}); resumed once`);
+        await builder(++attemptN, blockCorrectionPrompt(block.problem), sessionId);
+        result = await readResult();
+        block = result?.status === "blocked" ? await resolveBlock(result) : null;
+      }
       const files0 = await changedFiles();
       const evidence = (Array.isArray(result?.evidence) ? result.evidence : []).filter((x) => typeof x === "string" && x.trim());
       const closing = ["invalid", "already-fixed"].includes(result?.status);
@@ -398,7 +518,7 @@ export async function runCore(o) {
         await label("invalid");
         return await finish("invalid", result.summary ?? result.status);
       }
-      if (result?.status === "blocked") return await needsHuman(`Builder is blocked: ${result.summary ?? "(no summary)"}`, OUTCOME_CODES.BUILDER_BLOCKED);
+      if (block) return await endBlocked(block, result.summary);
       if (!files0.length) return await needsHuman(`Builder made no commit${result ? ` (status "${result.status}")` : " and wrote no result.json"}.\n\n${result?.summary ?? ""}`, OUTCOME_CODES.BUILDER_NO_COMMIT);
       await flushStages(result, ["plan", "implementation"]);
       T.plan = "posted"; T.implement = [`${files0.length} file(s)`, branch];
@@ -413,9 +533,11 @@ export async function runCore(o) {
     const doReview = async () => {
       for (let t = 0; t < 2; t++) {
         const diff = String(await git(["diff", `${base}...HEAD`]));
+        // #4129: an over-budget diff is bounded in the prompt; the stat keeps every changed file visible.
+        const stat = Buffer.byteLength(diff, "utf-8") > REVIEW_DIFF_MAX_BYTES ? String(await git(["diff", "--stat=200", `${base}...HEAD`]).catch(() => "")) : "";
         await renew();
         const rr = await callRunner({ role: "reviewer", issue, cwd: wt, model: reviewerModel, resume: null, system: REVIEWER_SYSTEM, readOnly: true,
-          prompt: reviewerPrompt({ issue: iss, diff }) });
+          prompt: reviewerPrompt({ issue: iss, diff, stat, base }) });
         await renew();
         await attempt("review", ++reviewN, rr);
         const v = parseVerdict(rr?.text);
@@ -441,6 +563,7 @@ export async function runCore(o) {
     // ---- 5. push + PR ----
     const files = await changedFiles();
     await gitPush(["push", "-u", "origin", branch]);
+    laneGuard(lane, "open a PR");
     const prOut = resumed?.pr ? `/pull/${resumed.pr}` : String(await ghw(["pr", "create", "-R", repo, "--base", lane, "--head", branch,
       "--title", `${iss.title} (#${issue})`, "--body", renderPrBody({ issue, investigation: await readStage(STAGES[0]), plan: await readStage(STAGES[1]), implementation: await readStage(STAGES[2]), result, gitFiles: files })])).trim();
     const pr = Number(/\/pull\/(\d+)/.exec(prOut)?.[1] ?? /(\d+)\s*$/.exec(prOut)?.[1]);
@@ -568,6 +691,7 @@ export async function runCore(o) {
       }
       if (syncs > 0 && (await prConflicting()) === "conflict") continue; // the base moved again while waiting
       T.merge = [policyText, `merged at ${localHead.slice(0, 12)}`];
+      laneGuard(resumed?.base ?? lane, "merge");
       try {
         await ghc(["pr", "merge", String(pr), "-R", repo, "--merge", "--match-head-commit", localHead]);
         break;
@@ -593,6 +717,10 @@ export async function runCore(o) {
       return finish("deferred", `usage limit hit; resets at ${when}`, { code: OUTCOME_CODES.RATE_LIMITED, resetAt: when, resetAtEpochMs: Number.isFinite(e.resetAtEpochMs) ? e.resetAtEpochMs : null }, OUTCOME_CODES.RATE_LIMITED);
     }
     if (e?.deferCode) return finish("deferred", e.deferDetail ?? String(e.message), { code: e.deferCode }, e.deferCode);
+    if (e?.laneCode) return await needsHuman(e.message, e.laneCode);
+    if (e?.code === "CLI_SPAWN_FAILED" || e?.spawnDeterministic === true) { // #4129: certain to fail again, so not engine-error (orchestrate would relaunch it)
+      return await needsHuman(`The claude CLI could not be started (${e.spawnErrno ?? "spawn error"}); a rerun fails the same way: ${String(e.message).slice(0, 400)}`, OUTCOME_CODES.CLI_SPAWN_FAILED);
+    }
     if (e?.pushRejected) return await needsHuman(`git push was rejected (no retry): ${String(e?.stderr ?? e?.message ?? e).slice(0, 400)}`);
     return finish("engine-error", e?.message ?? String(e));
   }