forgedock 1.35.0 → 1.37.0

package/bin/lean/signoff.test.mjs

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4651: sign-off rewrite of a lane's own unpushed commits, on a real temp git repo (bare origin + clone).
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { ensureSignedOff, needsSignoff, offendersOf } from "./signoff.mjs";
+
+const CLEAN = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^GIT_(AUTHOR|COMMITTER)_/.test(k)));
+const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", env: { ...CLEAN, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null" } }).trim();
+const PLACEHOLDER = ["-c", "user.name=forgedock", "-c", "user.email=forgedock@localhost"];
+
+function fixture() {
+  const root = tmpDir("signoff-"), origin = join(root, "origin.git"), wt = join(root, "wt");
+  sh(root, "init", "--bare", "-b", "staging", origin);
+  sh(root, "clone", origin, wt);
+  sh(wt, "config", "user.name", "Lane Bot"); sh(wt, "config", "user.email", "lane@example.com");
+  const commit = (file, msg, ...flags) => { writeFileSync(join(wt, file), `${file}\n`); sh(wt, "add", file); sh(wt, ...(flags.includes("placeholder") ? PLACEHOLDER : []), "commit", "-q", "-m", msg, ...flags.filter((f) => f !== "placeholder")); return sh(wt, "rev-parse", "HEAD"); };
+  commit("base.txt", "base");
+  sh(wt, "push", "-q", "origin", "HEAD:staging");
+  sh(wt, "checkout", "-q", "-b", "feat/x");
+  const git = async (a, o = {}) => execFileSync("git", a, { cwd: wt, encoding: "utf8", env: { ...CLEAN, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null", ...(o.env ?? {}) } }).trim();
+  return { wt, commit, git, sh: (...a) => sh(wt, ...a) };
+}
+
+describe("needsSignoff / offendersOf", () => {
+  it("flags placeholder authors and missing or mismatched sign-offs", () => {
+    assert.equal(needsSignoff({ authorEmail: "a@x.io", committerEmail: "a@x.io", signedOff: ["A <a@x.io>"] }), false);
+    assert.equal(needsSignoff({ authorEmail: "a@x.io", committerEmail: "a@x.io", signedOff: [] }), true);
+    assert.equal(needsSignoff({ authorEmail: "a@x.io", committerEmail: "a@x.io", signedOff: ["B <b@x.io>"] }), true);
+    assert.equal(needsSignoff({ authorEmail: "forgedock@localhost", committerEmail: "forgedock@localhost", signedOff: ["F <forgedock@localhost>"] }), true);
+    assert.deepEqual(offendersOf(""), []);
+  });
+});
+
+describe("ensureSignedOff", () => {
+  it("rewrites unpushed placeholder-author commits and leaves pushed commits alone", async () => {
+    const f = fixture();
+    const pushed = f.commit("a.txt", "pushed unsigned", "placeholder");
+    f.sh("push", "-q", "origin", "feat/x");
+    const bad = f.commit("b.txt", "unpushed placeholder", "placeholder");
+    const unsigned = f.commit("c.txt", "unpushed unsigned");
+    const good = f.commit("d.txt", "unpushed signed", "--signoff");
+    const r = await ensureSignedOff({ git: f.git, lane: "staging", branch: "feat/x", env: {} });
+    assert.equal(r.rewritten, 2);
+    const rows = f.sh("log", "--format=%H|%ae|%(trailers:key=Signed-off-by,valueonly,separator=;)", "origin/feat/x..HEAD").split("\n").map((l) => l.split("|"));
+    assert.equal(rows.length, 3);
+    for (const [, email, so] of rows) { assert.equal(email, "lane@example.com"); assert.match(so, /Lane Bot <lane@example\.com>/); }
+    const shas = rows.map((x) => x[0]);
+    assert.ok(!shas.includes(bad) && !shas.includes(unsigned), "originals are gone from the pushed range");
+    assert.equal(f.sh("rev-parse", "origin/feat/x"), pushed);
+    assert.equal(f.sh("merge-base", "--is-ancestor", pushed, "HEAD") ?? "", "");
+    assert.equal(f.sh("log", "-1", "--format=%ae", pushed), "forgedock@localhost"); // the pushed commit itself is untouched
+    assert.equal(f.sh("rev-parse", "HEAD~3"), pushed);
+    assert.equal(f.sh("show", "-s", "--format=%an", "HEAD"), "Lane Bot"); // the already-signed one is authored by the lane here, so it is unchanged
+    assert.ok(good);
+  });
+  it("never rewrites commits already on origin/<lane>, nor a clean range", async () => {
+    const f = fixture();
+    f.sh("checkout", "-q", "staging");
+    const onLane = f.commit("l.txt", "lane commit unsigned", "placeholder");
+    f.sh("push", "-q", "origin", "staging");
+    f.sh("checkout", "-q", "feat/x"); f.sh("merge", "-q", "--no-edit", "staging");
+    f.commit("m.txt", "mine", "--signoff");
+    const before = f.sh("rev-parse", "HEAD");
+    const r = await ensureSignedOff({ git: f.git, lane: "staging", branch: "feat/x", env: {} });
+    assert.equal(r.rewritten, 0);
+    assert.equal(f.sh("rev-parse", "HEAD"), before);
+    assert.equal(f.sh("merge-base", "--is-ancestor", onLane, "HEAD") ?? "", "");
+  });
+  it("rewrites with a merge commit in the range and keeps lane commits intact", async () => {
+    const f = fixture();
+    f.sh("checkout", "-q", "staging");
+    const onLane = f.commit("l.txt", "lane commit", "placeholder");
+    f.sh("push", "-q", "origin", "staging");
+    f.sh("checkout", "-q", "feat/x");
+    f.commit("b.txt", "unpushed placeholder", "placeholder");
+    f.sh("merge", "-q", "--no-edit", "staging");
+    const r = await ensureSignedOff({ git: f.git, lane: "staging", branch: "feat/x", env: {} });
+    assert.equal(r.rewritten, 1);
+    assert.equal(f.sh("merge-base", "--is-ancestor", onLane, "HEAD") ?? "", "");
+    assert.equal(f.sh("log", "--format=%ae", "origin/staging..HEAD", "--no-merges"), "lane@example.com");
+    assert.equal(f.sh("log", "-1", "--format=%ae", onLane), "forgedock@localhost");
+  });
+  it("uses GIT_AUTHOR_* from the env over the worktree config (sandbox lanes)", async () => {
+    const f = fixture();
+    f.commit("b.txt", "unpushed placeholder", "placeholder");
+    await ensureSignedOff({ git: f.git, lane: "staging", branch: "feat/x", env: { GIT_AUTHOR_NAME: "Host Dev", GIT_AUTHOR_EMAIL: "host@example.com" } });
+    assert.equal(f.sh("log", "-1", "--format=%ae|%an"), "host@example.com|Host Dev");
+    assert.match(f.sh("log", "-1", "--format=%(trailers:key=Signed-off-by,valueonly)"), /Host Dev <host@example\.com>/);
+  });
+  it("throws noIdentity (and rewrites nothing) when the worktree has no usable identity", async () => {
+    const f = fixture();
+    const bad = f.commit("b.txt", "unpushed placeholder", "placeholder");
+    f.sh("config", "user.email", "forgedock@localhost");
+    await assert.rejects(ensureSignedOff({ git: f.git, lane: "staging", branch: "feat/x", env: {} }), (e) => e.noIdentity === true);
+    assert.equal(f.sh("rev-parse", "HEAD"), bad);
+  });
+});

package/bin/lean/train.mjs

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Native unattended milestone train (#4658): `forgedock milestone train <slug...>`.
+ *
+ * One durable state file `<batchRoot>/trains/<id>/state.json` (tmp + fsync + rename, like a batch) holds the order, the
+ * active set, each milestone's status and lifecycle state (#4657) and the typed STOP, if any. Deterministic, 0 LLM calls.
+ * Each milestone runs as one orchestrate batch; its lanes resolve their base from the issue's milestone (lane.mjs), so
+ * the train never steers them through `branches.staging` and never writes forge.yaml. After a batch the lifecycle seam
+ * (`onBatchEnd`) records `shipped:staging` and closes at `milestones.close_on`. A slug is a milestone title.
+ * Caps have one source, forge.yaml `orchestration.global_parallel` (see `resolveCaps`); a conflicting override is ignored.
+ * Order is defined once, in the state; `insertMilestone` is the only way to add one and re-runs dependency validation.
+ */
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { writeAtomic } from "./batch.mjs";
+import { classifyEdges } from "../../scripts/plan-validate-live.mjs";
+
+export const STOP_REASONS = ["dependency-unmet", "needs-human", "breaker", "budget", "cancelled", "milestone-open", "error"];
+export const DEFAULT_LANE_PARALLEL = 3;
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export const trainRoot = (batchRoot) => join(batchRoot, "trains");
+export const newTrainId = (now = Date.now()) => `train-${new Date(now).toISOString().replace(/[-:T]/g, "").slice(0, 14)}-${process.pid}`;
+
+/** Handle on one train's state file. */
+export function openTrain(root, id) {
+  if (!ID_RE.test(String(id))) throw new Error(`invalid train id: ${id}`);
+  const file = join(trainRoot(root), id, "state.json");
+  return {
+    id, file,
+    exists: () => existsSync(file),
+    load() { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } },
+    save(state) { writeAtomic(file, `${JSON.stringify(state, null, 2)}\n`); },
+  };
+}
+
+/**
+ * The only cap source is `orchestration.global_parallel` (host-wide lane cap, shared with `forgedock sched cap`); unset
+ * it is DEFAULT_LANE_PARALLEL. A `requested` lane cap (`--parallel`) that differs is ignored with a warning.
+ * Active milestones split the cap, at least 1 lane each.
+ */
+export function resolveCaps({ requested = null, globalParallel = null, parallelMilestones = 1 }) {
+  const cap = globalParallel ?? DEFAULT_LANE_PARALLEL;
+  const warnings = [];
+  if (requested != null && requested !== cap) warnings.push(`train: --parallel ${requested} conflicts with the lane cap ${cap} (${globalParallel ? "orchestration.global_parallel" : "default"}); ignored`);
+  return { cap, parallelMilestones, perMilestone: Math.max(1, Math.floor(cap / parallelMilestones)), warnings };
+}
+
+/** Throws when `order` puts a milestone before one its issues depend on (`live`: {issues} as plan-validate-live reads them). */
+export function validateOrder(order, live) {
+  const { ok, edges } = classifyEdges({ order, issues: live.issues });
+  if (!ok) {
+    const bad = edges.filter((e) => e.state === "invalid").map((e) => `#${e.from} (${e.fromMilestone}) depends on #${e.to} (${e.toMilestone}), which is later in the train`);
+    throw new Error(`train order invalid: ${bad.join("; ")}`);
+  }
+  return edges;
+}
+
+export function createTrain({ slugs, parallelMilestones = 1, repo = null, live, now = () => new Date().toISOString() }) {
+  const order = [...new Set(slugs)];
+  if (!order.length) throw new Error("train needs at least one milestone slug");
+  if (!Number.isInteger(parallelMilestones) || parallelMilestones < 1) throw new Error("--parallel-milestones must be a positive integer");
+  if (live) validateOrder(order, live);
+  return { v: 1, repo, created: now(), parallelMilestones, order, active: [], stop: null,
+    milestones: Object.fromEntries(order.map((s) => [s, { status: "pending", lifecycle: null, batch: null }])) };
+}
+
+/** Insert `slug` at the end, or before/after another; re-validates dependencies and leaves the state unchanged on a refusal. */
+export function insertMilestone(state, slug, { before = null, after = null, live = null } = {}) {
+  if (state.milestones[slug]) throw new Error(`milestone ${slug} is already in the train`);
+  const anchor = before ?? after;
+  if (anchor && !state.milestones[anchor]) throw new Error(`milestone ${anchor} is not in the train`);
+  const order = [...state.order];
+  order.splice(anchor ? order.indexOf(anchor) + (after ? 1 : 0) : order.length, 0, slug);
+  if (live) validateOrder(order, live);
+  return { ...state, order, milestones: { ...state.milestones, [slug]: { status: "pending", lifecycle: null, batch: null } } };
+}
+
+/** A milestone is ready when every earlier-in-train milestone its issues depend on is done (shipped to staging or later). */
+export function readyMilestones(state, live) {
+  const edges = live ? classifyEdges({ order: state.order, issues: live.issues }).edges : [];
+  return state.order.filter((s) => state.milestones[s].status === "pending"
+    && edges.every((e) => e.fromMilestone !== s || state.milestones[e.toMilestone]?.status === "done"));
+}
+
+/** Typed STOP reason of a failed milestone run: its rows' outcomes, else `error`. */
+export function stopOf(result) {
+  const outcomes = (result?.rows ?? []).map((r) => String(r.outcome ?? ""));
+  const has = (re) => outcomes.find((o) => re.test(o));
+  if (has(/^dependency-/)) return "dependency-unmet";
+  if (has(/^needs-human/)) return "needs-human";
+  if (has(/breaker/)) return "breaker";
+  if (has(/budget/)) return "budget";
+  if (has(/cancel/)) return "cancelled";
+  return "error";
+}
+
+/**
+ * Run the train until done or a STOP. `runMilestone(slug, {parallel, resume})` -> {ok, batch?, rows?, stop?}; `onBatchEnd([slug])`
+ * is the #4657 lifecycle seam. Saves after every transition. A resume (state loaded from disk) clears the STOP and re-runs
+ * milestones left `running` through their batch (`resume`). Never writes forge.yaml.
+ * @returns {Promise<{ok: boolean, state: object}>}
+ */
+export async function runTrain({ train, state, runMilestone, onBatchEnd = async () => [], readLive = async () => null, caps, now = () => new Date().toISOString(), log = () => {} }) {
+  state = { ...state, stop: null, active: [], milestones: { ...state.milestones } };
+  for (const [s, m] of Object.entries(state.milestones)) if (m.status === "running" || m.status === "stopped") state.milestones[s] = { ...m, status: "pending", resume: m.batch };
+  const save = () => train.save(state);
+  const set = (slug, patch) => { state.milestones[slug] = { ...state.milestones[slug], ...patch }; };
+  const running = new Map();
+  const finish = async (slug) => {
+    let r;
+    try { r = await runMilestone(slug, { parallel: caps.perMilestone, resume: state.milestones[slug].resume ?? null, onBatch: (b) => { set(slug, { batch: b }); save(); } }); } catch (e) { r = { ok: false, stop: "error", detail: e?.message ?? String(e) }; }
+    state.active = state.active.filter((s) => s !== slug);
+    if (!r?.ok) { set(slug, { status: "stopped", batch: r?.batch ?? state.milestones[slug].batch }); state.stop ??= { reason: STOP_REASONS.includes(r?.stop) ? r.stop : stopOf(r), milestone: slug, detail: r?.detail ?? "", at: now() }; return save(); }
+    let life = null;
+    try { life = (await onBatchEnd([slug]))?.find((x) => x.title === slug) ?? null; } catch (e) { log(`train: lifecycle for ${slug}: ${e?.message ?? e}`); }
+    if (life && !["shipped:staging", "deployed:default", "closed"].includes(life.state)) {
+      set(slug, { status: "stopped", lifecycle: life.state });
+      state.stop ??= { reason: "milestone-open", milestone: slug, detail: "open issues remain after the batch", at: now() };
+    } else set(slug, { status: "done", lifecycle: life?.state ?? "shipped:staging", batch: r.batch ?? state.milestones[slug].batch });
+    save();
+  };
+  save();
+  for (;;) {
+    while (!state.stop && running.size < state.parallelMilestones) {
+      const next = readyMilestones(state, await readLive()).find((s) => !running.has(s));
+      if (!next) break;
+      set(next, { status: "running" }); state.active.push(next); save();
+      log(`train: starting ${next}`);
+      running.set(next, finish(next).finally(() => running.delete(next)));
+    }
+    if (!running.size) break;
+    await Promise.race(running.values());
+  }
+  const pending = state.order.filter((s) => state.milestones[s].status === "pending");
+  if (!state.stop && pending.length) { state.stop = { reason: "dependency-unmet", milestone: pending[0], detail: `waiting on an earlier milestone: ${pending.join(", ")}`, at: now() }; save(); }
+  return { ok: !state.stop, state };
+}
+
+const valueOf = (argv, name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; };
+const intOf = (v, name) => { if (v == null) return null; const n = Number(v); if (!Number.isInteger(n) || n < 1) throw new Error(`${name} must be a positive integer`); return n; };
+
+/**
+ * `forgedock milestone train <slug...> [--parallel-milestones N] [--parallel K]` | `--resume <id>` | `--insert <id> <slug> [--before s|--after s]` | `--show <id>`.
+ * deps: {root, readLive, runMilestone, onBatchEnd, globalParallel, repo, print}. Resolves {ok, id, state}.
+ */
+export async function trainCli(argv, deps) {
+  const { root, readLive, print = (l) => console.log(l) } = deps;
+  const usage = "usage: forgedock milestone train <slug...> [--parallel-milestones N] [--parallel K] [--repo owner/repo] | --resume <id> | --insert <id> <slug> [--before <slug>|--after <slug>] | --show <id>";
+  const valued = new Set(["--parallel-milestones", "--parallel", "--repo", "--resume", "--before", "--after"]);
+  const operands = []; for (let i = 0; i < argv.length; i++) { if (argv[i] === "--insert" || argv[i] === "--show") continue; if (valued.has(argv[i])) i++; else if (!argv[i].startsWith("--")) operands.push(argv[i]); }
+  const open = (id) => { const t = openTrain(root, id); const state = t.load(); if (!state) throw new Error(`no train ${id} in ${trainRoot(root)}`); return { t, state }; };
+  if (argv.includes("--show")) { const id = valueOf(argv, "--show"); const { state } = open(id); print(`train ${id}: ${state.order.map((s) => `${s}=${state.milestones[s].status}${state.milestones[s].lifecycle ? `(${state.milestones[s].lifecycle})` : ""}`).join(", ")}${state.stop ? `; STOP ${state.stop.reason} at ${state.stop.milestone}` : ""}`); return { ok: !state.stop, id, state }; }
+  if (argv.includes("--insert")) {
+    const id = valueOf(argv, "--insert"); const { t, state } = open(id); const slug = operands[1]; // operands[0] is the train id
+    if (!slug) throw new Error(usage);
+    const next = insertMilestone(state, slug, { before: valueOf(argv, "--before"), after: valueOf(argv, "--after"), live: await readLive() });
+    t.save(next); print(`train ${id}: inserted ${slug}; order: ${next.order.join(", ")}`); return { ok: true, id, state: next };
+  }
+  let train, state, id;
+  const pm = intOf(valueOf(argv, "--parallel-milestones"), "--parallel-milestones");
+  if (argv.includes("--resume")) { id = valueOf(argv, "--resume"); ({ t: train, state } = open(id)); }
+  else {
+    if (!operands.length) throw new Error(usage);
+    id = deps.id ?? newTrainId(); train = openTrain(root, id);
+    if (train.exists()) throw new Error(`train ${id} already exists`);
+    state = createTrain({ slugs: operands, parallelMilestones: pm ?? 1, repo: deps.repo ?? null, live: await readLive() });
+  }
+  const caps = resolveCaps({ requested: intOf(valueOf(argv, "--parallel"), "--parallel"), globalParallel: deps.globalParallel ?? null, parallelMilestones: pm ?? state.parallelMilestones });
+  for (const w of caps.warnings) print(w);
+  if (pm && argv.includes("--resume")) state = { ...state, parallelMilestones: pm };
+  print(`train: ${id} (${train.file}); resume with: forgedock milestone train --resume ${id}`);
+  const r = await runTrain({ train, state, runMilestone: deps.runMilestone, onBatchEnd: deps.onBatchEnd, readLive, caps, log: print });
+  print(r.ok ? `train ${id}: done` : `train ${id}: STOP ${r.state.stop.reason} at ${r.state.stop.milestone}${r.state.stop.detail ? ` (${r.state.stop.detail})` : ""}; resume with: forgedock milestone train --resume ${id}`);
+  return { ok: r.ok, id, state: r.state };
+}

package/bin/lean/train.test.mjs

@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { openTrain, createTrain, insertMilestone, resolveCaps, runTrain, stopOf, trainCli, STOP_REASONS } from "./train.mjs";
+
+const live = { issues: [
+  { number: 1, milestone: "m1", state: "OPEN", body: "" },
+  { number: 2, milestone: "m2", state: "OPEN", body: "Depends on #1" },
+  { number: 3, milestone: "m3", state: "OPEN", body: "" },
+] };
+const tmp = () => tmpDir("train-");
+const okRun = (calls) => async (slug, o) => { calls.push([slug, o]); return { ok: true, batch: `b-${slug}`, rows: [] }; };
+const life = async (titles) => titles.map((title) => ({ title, state: "shipped:staging" }));
+
+test("createTrain keeps order, refuses a dependency on a later milestone", () => {
+  const s = createTrain({ slugs: ["m1", "m2"], live });
+  assert.deepEqual(s.order, ["m1", "m2"]);
+  assert.equal(s.milestones.m1.status, "pending");
+  assert.throws(() => createTrain({ slugs: ["m2", "m1"], live }), /train order invalid/);
+});
+
+test("insertMilestone re-validates and leaves the state unchanged on refusal", () => {
+  const s = createTrain({ slugs: ["m1", "m2"], live });
+  const n = insertMilestone(s, "m3", { after: "m1", live });
+  assert.deepEqual(n.order, ["m1", "m3", "m2"]);
+  assert.deepEqual(s.order, ["m1", "m2"]);
+  assert.throws(() => insertMilestone(s, "m1", { live }), /already in the train/);
+  const live2 = { issues: [...live.issues, { number: 4, milestone: "m4", state: "OPEN", body: "Depends on #2" }, { number: 5, milestone: "m2", state: "OPEN", body: "Depends on #4" }] };
+  assert.throws(() => insertMilestone(s, "m4", { live: live2 }), /train order invalid/);
+});
+
+test("runTrain runs in order, persists lifecycle, and resumes from the state file", async () => {
+  const root = tmp(), train = openTrain(root, "t1"), calls = [];
+  const r = await runTrain({ train, state: createTrain({ slugs: ["m1", "m2"], live }), runMilestone: okRun(calls), onBatchEnd: life, readLive: async () => live, caps: resolveCaps({}) });
+  assert.equal(r.ok, true);
+  assert.deepEqual(calls.map((c) => c[0]), ["m1", "m2"]);
+  const saved = train.load();
+  assert.equal(saved.milestones.m2.status, "done");
+  assert.equal(saved.milestones.m2.lifecycle, "shipped:staging");
+  assert.equal(saved.milestones.m1.batch, "b-m1");
+});
+
+test("a failed milestone ends in a typed STOP and --resume continues through its batch", async () => {
+  const root = tmp(), train = openTrain(root, "t2"), calls = [];
+  let fail = true;
+  const run = async (slug, o) => { calls.push([slug, o.resume]); return fail && slug === "m1" ? { ok: false, batch: "b1", rows: [{ issue: 1, outcome: "needs-human" }] } : { ok: true, rows: [] }; };
+  const args = { train, runMilestone: run, onBatchEnd: life, readLive: async () => live, caps: resolveCaps({}) };
+  const a = await runTrain({ ...args, state: createTrain({ slugs: ["m1", "m2"], live }) });
+  assert.equal(a.ok, false);
+  assert.equal(a.state.stop.reason, "needs-human");
+  assert.ok(STOP_REASONS.includes(a.state.stop.reason));
+  assert.equal(a.state.milestones.m2.status, "pending");
+  fail = false;
+  const b = await runTrain({ ...args, state: train.load() });
+  assert.equal(b.ok, true);
+  assert.deepEqual(calls.slice(1), [["m1", "b1"], ["m2", null]]);
+});
+
+test("open issues left after a batch stop the train with milestone-open", async () => {
+  const r = await runTrain({ train: openTrain(tmp(), "t3"), state: createTrain({ slugs: ["m1"] }), runMilestone: okRun([]), onBatchEnd: async (t) => [{ title: t[0], state: "building" }], caps: resolveCaps({}) });
+  assert.equal(r.state.stop.reason, "milestone-open");
+});
+
+test("stopOf maps row outcomes to typed reasons", () => {
+  assert.equal(stopOf({ rows: [{ outcome: "dependency-open" }] }), "dependency-unmet");
+  assert.equal(stopOf({ rows: [{ outcome: "budget-exceeded" }] }), "budget");
+  assert.equal(stopOf({ rows: [] }), "error");
+});
+
+test("parallel milestones run together and split one cap", async () => {
+  const caps = resolveCaps({ globalParallel: 6, parallelMilestones: 2 });
+  assert.equal(caps.perMilestone, 3);
+  let live_ = 0, max = 0;
+  const run = async () => { live_++; max = Math.max(max, live_); await new Promise((r) => setTimeout(r, 10)); live_--; return { ok: true, rows: [] }; };
+  const r = await runTrain({ train: openTrain(tmp(), "t4"), state: createTrain({ slugs: ["m1", "m3"], parallelMilestones: 2 }), runMilestone: run, onBatchEnd: life, caps });
+  assert.equal(r.ok, true);
+  assert.equal(max, 2);
+});
+
+test("a conflicting --parallel override warns and is ignored; the cap source is global_parallel", () => {
+  const c = resolveCaps({ requested: 32, globalParallel: 12 });
+  assert.equal(c.cap, 12);
+  assert.match(c.warnings[0], /conflicts.*ignored/);
+  assert.equal(resolveCaps({ requested: 12, globalParallel: 12 }).warnings.length, 0);
+});
+
+test("trainCli: forge.yaml is byte-identical after a run and lanes get no branches.staging override", async () => {
+  const root = tmp(), cwd = tmp(), out = [], calls = [];
+  const yaml = "branches:\n  staging: staging\norchestration:\n  global_parallel: 4\n";
+  writeFileSync(join(cwd, "forge.yaml"), yaml);
+  const before = readFileSync(join(cwd, "forge.yaml"));
+  const r = await trainCli(["m1", "m2", "--parallel", "32"], { root, id: "t5", globalParallel: 4, readLive: async () => live, runMilestone: okRun(calls), onBatchEnd: life, print: (l) => out.push(l) });
+  assert.equal(r.ok, true);
+  assert.ok(out.some((l) => /conflicts with the lane cap 4/.test(l)));
+  assert.equal(calls[0][1].parallel, 4);
+  assert.deepEqual(readFileSync(join(cwd, "forge.yaml")), before);
+  assert.equal(openTrain(root, "t5").load().milestones.m2.status, "done");
+});
+
+test("trainCli --insert adds a milestone explicitly; --resume clears nothing it did not own", async () => {
+  const root = tmp(), out = [];
+  const deps = { root, id: "t6", readLive: async () => live, runMilestone: okRun([]), onBatchEnd: life, print: (l) => out.push(l) };
+  await trainCli(["m1"], deps);
+  const r = await trainCli(["--insert", "t6", "m3"], deps);
+  assert.deepEqual(r.state.order, ["m1", "m3"]);
+  const done = await trainCli(["--resume", "t6"], deps);
+  assert.equal(done.state.milestones.m3.status, "done");
+  await assert.rejects(() => trainCli(["--resume", "nope"], deps), /no train/);
+});

package/bin/pool/cli.mjs

@@ -42,12 +42,14 @@ export async function runPoolCli(argv, deps = {}) {
         if (r.status !== 0) throw new Error(`install-router.sh exited ${r.status}`);
         break;
       }
+      process.title = "forgedock-pool-router"; // distinctive name for OOM-killer avoid lists and ps (#4673)
       const cfg = routerConfig();
       (deps.startRouter ?? startRouter)(cfg);
       console.log(`computeshare router on ${cfg.listen.host}:${cfg.listen.port} (public ${cfg.public_url})`);
       break;
     }
     case "agent": {
+      process.title = "forgedock-pool-agent";
       const cfg = agentConfig();
       startAgent(cfg, { docker: dockerCli });
       console.log(`computeshare agent ${cfg.name} on ${cfg.listen.host}:${cfg.listen.port}: ${cfg.allow_cpus} cpus, ${cfg.allow_mem_gb} GB reserved for lanes`);

package/bin/pool/health.mjs

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { spawnSync } from "node:child_process";
+
+const sh = (cmd, args) => { const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000 }); return r.status === 0 ? r.stdout : null; };
+
+/** Last exit reason in journal lines, or null. Matches systemd's "Main process exited, code=killed, status=15/TERM" and oom-kill results. */
+export function lastExitReason(lines) {
+  let reason = null;
+  for (const l of lines) {
+    const m = /Main process exited, (code=\S+, status=\S+)/.exec(l) || /(Failed with result '(?:oom-kill|signal|exit-code)')/.exec(l);
+    if (m) reason = m[1];
+  }
+  return reason;
+}
+
+/**
+ * Did a systemd --user unit restart in the last hour? `run(cmd,args)` returns stdout or null (injected for tests).
+ * "skip" when the unit is absent or systemd is unavailable. Restarts come from the journal because NRestarts is only cumulative.
+ */
+export function restartCheck({ unit, run = sh } = {}) {
+  const show = run("systemctl", ["--user", "show", unit, "-p", "NRestarts", "-p", "LoadState"]);
+  if (!show || /LoadState=not-found/.test(show)) return { status: "skip" };
+  const total = Number(/NRestarts=(\d+)/.exec(show)?.[1] ?? 0);
+  const lines = (run("journalctl", ["--user", "-u", unit, "--since", "1 hour ago", "--no-pager", "-o", "cat"]) ?? "").split("\n");
+  const recent = lines.filter((l) => /Scheduled restart job/.test(l)).length;
+  if (recent === 0) return { status: "pass", detail: `no restarts in the last hour (NRestarts=${total})` };
+  const why = lastExitReason(lines);
+  return { status: "warn", detail: `${unit} restarted ${recent}x in the last hour (NRestarts=${total})${why ? `; last exit: ${why}` : ""}. Check for OOM kills (earlyoom/systemd-oomd) under memory pressure` };
+}