forgedock 1.24.5 → 1.25.1

package/bin/lean/batch.mjs

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Durable batch state and detached lanes for `forgedock orchestrate` (#4121).
+ *
+ * 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) and
+ * `lanes/<issue>.{json,log}` (each lane's result and output). Every write is tmp + fsync + rename, and the root must be
+ * on disk, never tmpfs. A lane is its own session (`setsid` through `detached`), so killing the dispatcher leaves it
+ * running; a resumed dispatcher re-attaches to it by pid, checking `/proc/<pid>/cmdline` against its result path.
+ */
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+
+export const RAM_FS = new Set(["tmpfs", "ramfs"]);
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function batchRoot(env = process.env) {
+  return env.FORGEDOCK_BATCH_DIR || join(homedir(), ".forge", "batches");
+}
+
+/** `[{mount, type}]` from /proc/self/mounts; empty when unreadable (non-Linux). */
+export function readMounts(file = "/proc/self/mounts") {
+  try {
+    return readFileSync(file, "utf8").split("\n").filter(Boolean).map((l) => {
+      const [, mount, type] = l.split(" ");
+      return { mount: mount.replace(/\\(\d{3})/g, (_, o) => String.fromCharCode(parseInt(o, 8))), type };
+    });
+  } catch { return []; }
+}
+
+/** Filesystem type of the mount that holds `path` (longest mount-point prefix); null when unknown. */
+export function fsTypeOf(path, mounts = readMounts()) {
+  const p = resolve(path);
+  let best = null;
+  for (const m of mounts) {
+    const under = m.mount === "/" || p === m.mount || p.startsWith(m.mount.endsWith(sep) ? m.mount : m.mount + sep);
+    if (under && (!best || m.mount.length > best.mount.length)) best = m;
+  }
+  return best?.type ?? null;
+}
+
+/** Throws when `path` is on a RAM filesystem: a full tmpfs truncated an earlier state file to 0 bytes. */
+export function assertDiskPath(path, mounts = readMounts()) {
+  const type = fsTypeOf(path, mounts);
+  if (RAM_FS.has(type)) throw new Error(`batch state must be on disk, but ${path} is on ${type}; set FORGEDOCK_BATCH_DIR to a disk path`);
+}
+
+/** Write `data` to `file` atomically: a reader sees the old or the new content, never a truncated file. */
+export function writeAtomic(file, data) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  const fd = openSync(tmp, "w");
+  try { writeSync(fd, data); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(tmp, file);
+}
+
+const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
+
+export function newBatchId(now = Date.now(), pid = process.pid) {
+  return `b${new Date(now).toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)}-${pid}`;
+}
+
+/** Handle on one batch directory. */
+export function openBatch(root, id) {
+  if (!ID_RE.test(String(id ?? ""))) throw new Error(`invalid batch id ${JSON.stringify(id)}`);
+  const dir = join(root, id);
+  const f = (name) => join(dir, name);
+  return {
+    id, dir,
+    exists: () => existsSync(f("plan.json")),
+    readPlan: () => readJson(f("plan.json")),
+    writePlan: (plan) => writeAtomic(f("plan.json"), JSON.stringify(plan, null, 2) + "\n"),
+    store: {
+      load: () => readJson(f("state.json")),
+      save: (state) => writeAtomic(f("state.json"), JSON.stringify(state) + "\n"),
+      log: (row) => { try { appendFileSync(f("log.jsonl"), JSON.stringify({ at: new Date().toISOString(), ...row }) + "\n"); } catch { /* the log is advisory */ } },
+    },
+    /** Live K: the `parallel` file, read on every scheduler pass; null when missing or invalid. */
+    readParallel: () => { try { const k = parseInt(readFileSync(f("parallel"), "utf8"), 10); return Number.isInteger(k) && k >= 1 ? k : null; } catch { return null; } },
+    setParallel: (k) => {
+      if (!Number.isInteger(k) || k < 1) throw new Error("parallel must be a positive integer");
+      writeAtomic(f("parallel"), `${k}\n`);
+    },
+    resultFile: (n) => f(join("lanes", `${n}.json`)),
+    logFile: (n) => f(join("lanes", `${n}.log`)),
+  };
+}
+
+/** True when `pid` is alive and (where /proc exists) its command line names `marker`, so a reused pid is not adopted. */
+export function isLaneAlive(pid, marker, { kill = process.kill.bind(process), procDir = "/proc" } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { kill(pid, 0); } catch (e) { if (e?.code !== "EPERM") return false; }
+  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);
+}
+
+/**
+ * Start one lane in its own session: `<bin> <script> run-issue <issue> ...args --result-file <lanes/N.json>`, output to
+ * `lanes/N.log`. A stale result from an earlier attempt is removed first. @returns {{pid:number}}
+ */
+export function launchLane({ batch, issue, args = [], bin = process.execPath, script, cwd = process.cwd(), env = process.env, spawnFn = spawn }) {
+  const rf = batch.resultFile(issue);
+  mkdirSync(dirname(rf), { recursive: true });
+  rmSync(rf, { force: true });
+  const out = openSync(batch.logFile(issue), "a");
+  try {
+    const child = spawnFn(bin, [script, "run-issue", String(issue), ...args, "--result-file", rf], { cwd, env, detached: true, stdio: ["ignore", out, out] });
+    child.on?.("error", () => { /* surfaces as a dead pid without a result */ });
+    child.unref?.();
+    return { pid: child.pid };
+  } finally { closeSync(out); }
+}
+
+/** Poll a lane until its result file appears; a lane that died without one is an engine-error. */
+export async function waitLane({ batch, issue, pid, alive = isLaneAlive, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), pollMs = 5000 }) {
+  const rf = batch.resultFile(issue);
+  for (;;) {
+    const r = readJson(rf);
+    if (r) return r;
+    if (!alive(pid, rf)) {
+      const last = readJson(rf); // it may have written the result just before exiting
+      return last ?? { terminalReason: "engine-error", detail: `lane pid ${pid} exited without a result; see ${batch.logFile(issue)}` };
+    }
+    await sleep(pollMs);
+  }
+}
+
+/** Lane seams for `orchestrate()`: `runOne` launches a detached lane, `adopt` re-attaches to a live one (else null). */
+export function detachedLanes({ batch, laneArgs, script, cwd, env, bin, alive = isLaneAlive, pollMs, spawnFn }) {
+  return {
+    runOne: async (n, lane, ctx = {}) => {
+      const { pid } = launchLane({ batch, issue: n, args: laneArgs(n, lane), script, cwd, env, bin, spawnFn });
+      ctx.onStart?.({ pid });
+      return waitLane({ batch, issue: n, pid, alive, pollMs });
+    },
+    adopt: async (n, rec) => {
+      const rf = batch.resultFile(n);
+      if (!existsSync(rf) && !alive(rec.pid, rf)) return null;
+      return waitLane({ batch, issue: n, pid: rec.pid, alive, pollMs });
+    },
+  };
+}

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 });
+  });
+});