forgedock 1.42.0 → 1.43.0

package/bin/engine-cli.mjs

@@ -32,6 +32,7 @@ import { parseTurnBudgets, formatTurnSummary, TURN_BUDGET_DEFAULTS } from "./lea
 import { writeAtomic as writeResultAtomic } from "./lean/batch.mjs";
 import { parseLightConfig, LIGHT_DEFAULTS } from "./lean/light.mjs";
 import { OUTCOME_CODES } from "./engine/outcome-codes.mjs";
+import * as _autoChildren from "./lean/autochildren.mjs";
 
 /**
  * Workflow labels that mark an issue as "in the pipeline" (not yet terminal).
@@ -408,8 +409,8 @@ export function readVerify(cwd = process.cwd()) {
   try {
     const sec = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.verify;
     if (!sec || typeof sec !== "object") return undefined;
-    const invariants = readInvariants(cwd), flaky = readYamlList(cwd, "verify", "flaky");
-    return parseVerify({ ...sec, ...(invariants ? { invariants } : {}), ...(flaky ? { flaky } : {}) });
+    const invariants = readInvariants(cwd), flaky = readYamlList(cwd, "verify", "flaky"), guard_command = readYamlMap(cwd, "verify", "guard_command");
+    return parseVerify({ ...sec, ...(invariants ? { invariants } : {}), ...(flaky ? { flaky } : {}), ...(guard_command ? { guard_command } : {}) });
   } catch { return undefined; }
 }
 /** #4542: forge.yaml `execution.host_capabilities` (+ patterns) for a lane's remote-block mapping; undefined when none are declared. */
@@ -447,6 +448,30 @@ export function readPrecheckCommands(cwd = process.cwd()) {
 export function readInvariants(cwd = process.cwd()) {
   return readYamlList(cwd, "verify", "invariants");
 }
+/** #4792: a block map under `section.key` (`    ".py": "cmd"` or `    py: cmd`); the one-level parser drops these lines. undefined when absent or empty. */
+export function readYamlMap(cwd, section, key) {
+  let raw;
+  try { raw = readFileSync(join(cwd, "forge.yaml"), "utf8"); } catch { return undefined; }
+  const out = {};
+  const head = new RegExp(`^${section}:\\s*(#.*)?$`), keyRe = new RegExp(`^\\s+${key}:\\s*(#.*)?$`);
+  let inSection = false, mapIndent = null;
+  for (const line of raw.split(/\r?\n/)) {
+    if (/^\s*(#.*)?$/.test(line)) continue;
+    if (/^\S/.test(line)) { inSection = head.test(line); mapIndent = null; continue; }
+    if (!inSection) continue;
+    const indent = line.length - line.trimStart().length;
+    if (mapIndent === null) { if (keyRe.test(line)) mapIndent = indent; continue; }
+    if (indent <= mapIndent) { mapIndent = keyRe.test(line) ? indent : null; continue; }
+    const m = /^\s+(?:"([^"]+)"|'([^']+)'|([^\s:#"']+))\s*:\s+(.*)$/.exec(line);
+    if (!m) continue;
+    let v = m[4].trim();
+    const q = /^"((?:[^"\\]|\\.)*)"\s*(#.*)?$/.exec(v) ?? /^'((?:[^']|'')*)'\s*(#.*)?$/.exec(v);
+    if (q) v = v.startsWith('"') ? q[1].replace(/\\(["\\])/g, "$1") : q[1].replace(/''/g, "'");
+    else v = v.replace(/\s+#.*$/, "").trim();
+    if (v) out[m[1] ?? m[2] ?? m[3]] = v;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
 function readYamlList(cwd, section, key) {
   let raw;
   try { raw = readFileSync(join(cwd, "forge.yaml"), "utf8"); } catch { return undefined; }
@@ -496,11 +521,14 @@ function readPrecheckOptions(cwd = process.cwd()) {
  */
 export function readEnvConfig(cwd = process.cwd()) {
   try {
-    const e = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.env ?? {};
+    const y = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"));
+    const e = y?.env ?? {};
+    const tr = y?.verification?.test_runners; // #4857: {path prefix: runner command prefix} for validate commands
+    const runners = tr && typeof tr === "object" && !Array.isArray(tr) ? Object.fromEntries(Object.entries(tr).filter(([k, v]) => k && typeof v === "string" && v.trim())) : {};
     const s = (v) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
     const kb = typeof e.sparse_max_kb === "string" && /^\d+$/.test(e.sparse_max_kb.trim()) ? Number(e.sparse_max_kb) : e.sparse_max_kb;
     return { ...(s(e.toolchain) ? { toolchainOverride: s(e.toolchain) } : {}), ...(s(e.setup) ? { envSetup: s(e.setup) } : {}),
-      ...(Number.isInteger(kb) && kb >= 0 ? { sparseMaxKb: kb } : {}) };
+      ...(Number.isInteger(kb) && kb >= 0 ? { sparseMaxKb: kb } : {}), ...(Object.keys(runners).length ? { testRunners: runners } : {}) };
   } catch { return {}; }
 }
 export const ENGINE_PATHS = ["core", "full", "lean", "auto"];
@@ -1204,8 +1232,8 @@ async function envBatch({ argv, root, print = (l) => console.log(l) }) {
   return { ok: true, batch: id };
 }
 
-const ORCH_USAGE = "usage: forgedock orchestrate <issue...> [--parallel K] [--lane L] [--lane-override] [--force <reason>] [--repo owner/repo] | --resume <id> [issue...] | --set-parallel <id> <K> | --clear-breaker <id> | --add <id> <issue...> | --requeue <id> <issue...> [--reason <text>] | --cancel <id> [--stop-remote] | --hold <id> <issue...> | --release <id> <issue...> | --show-env <id> | --set-env <id> KEY=VAL | --unset-env <id> KEY";
-const ORCH_VALUED = ["--parallel", "--lane", "--repo", "--model", "--prefilter-model", "--reason", "--force"];
+const ORCH_USAGE = "usage: forgedock orchestrate <issue...> [--parallel K] [--lane L] [--lane-override] [--force <reason>] [--repo owner/repo] [--auto-children off|decomposed|epic|all] [--epic N] | --resume <id> [issue...] | --set-parallel <id> <K> | --clear-breaker <id> | --add <id> <issue...> | --requeue <id> <issue...> [--reason <text>] | --cancel <id> [--stop-remote] | --hold <id> <issue...> | --release <id> <issue...> | --show-env <id> | --set-env <id> KEY=VAL | --unset-env <id> KEY";
+const ORCH_VALUED = ["--parallel", "--lane", "--repo", "--model", "--prefilter-model", "--reason", "--force", "--auto-children", "--epic"];
 const issuesOf = (argv) => {
   const issues = [];
   for (let i = 0; i < argv.length; i++) {
@@ -1379,7 +1407,7 @@ async function orchestrateClient(argv, deps = {}) {
     if (!Number.isInteger(k) || k < 1) throw new Error("parallel must be a positive integer");
     let sock = null;
     try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { sock = null; }
-    if (sock) await schedd.request(sock, { op: "set-parallel", id, k });
+    if (sock) await schedd.request(sock, { op: "set-parallel", id, k }, undefined, { timeoutMs: schedd.REQUEST_MS });
     else {
       // No daemon: the batch is not running anywhere; the parallel file is all there is to change.
       const batchMod = await import("./lean/batch.mjs");
@@ -1394,17 +1422,17 @@ async function orchestrateClient(argv, deps = {}) {
   const addVia = (id) => async (issues) => {
     let sock = null;
     try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { sock = null; }
-    return sock ? schedd.request(sock, { op: "add", id, issues }) : null;
+    return sock ? schedd.request(sock, { op: "add", id, issues }, undefined, { timeoutMs: schedd.REQUEST_MS }) : null;
   };
   const requeueVia = (id) => async (issues, reason, by) => {
     let sock = null;
     try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { sock = null; }
-    return sock ? schedd.request(sock, { op: "requeue", id, issues, reason, by }) : null;
+    return sock ? schedd.request(sock, { op: "requeue", id, issues, reason, by }, undefined, { timeoutMs: schedd.REQUEST_MS }) : null;
   };
   const holdVia = (id) => async (op, issues) => {
     let sock = null;
     try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { sock = null; }
-    return sock ? schedd.request(sock, { op, id, issues }) : null;
+    return sock ? schedd.request(sock, { op, id, issues }, undefined, { timeoutMs: schedd.REQUEST_MS }) : null;
   };
   const batchRootOf = async () => (await import("./lean/batch.mjs")).batchRoot();
   if (["--show-env", "--set-env", "--unset-env"].some((f) => argv.includes(f))) return envBatch({ argv, root: await batchRootOf() });
@@ -1414,7 +1442,7 @@ async function orchestrateClient(argv, deps = {}) {
     return cancelBatch({ id, root: await batchRootOf(), stopRemote: argv.includes("--stop-remote"), viaDaemon: async () => {
       let sock = null;
       try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { sock = null; }
-      return sock ? schedd.request(sock, { op: "cancel", id, stopRemote: argv.includes("--stop-remote") }) : null;
+      return sock ? schedd.request(sock, { op: "cancel", id, stopRemote: argv.includes("--stop-remote") }, undefined, { timeoutMs: schedd.REQUEST_MS }) : null;
     } });
   }
   if (argv.includes("--requeue")) {
@@ -1718,6 +1746,10 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     lanes = { ...lanes, stopLane };
   }
   const orch = deps.orchestration ?? readOrchestration(cwd);
+  // #4965: --auto-children overrides forge.yaml; it is part of plan.argv, so --resume keeps it
+  const autoMod = _autoChildren, yamlAuto = readAutoChildren(cwd);
+  const autoChildren = { mode: argv.includes("--auto-children") ? autoMod.parseAutoModeFlag(flag(argv, "--auto-children")) : yamlAuto.mode, pollS: yamlAuto.pollS,
+    epics: argv.flatMap((a, i) => (a === "--epic" && /^#?\d+$/.test(argv[i + 1] ?? "") ? [parseInt(argv[i + 1].replace("#", ""), 10)] : [])) };
   // #4304: recovery lanes run on the core path only (run-issue throws on --recover with full), so a full-path repo gets none.
   const recoveryOn = Boolean(orch.recovery?.maxAttempts) && (deps.enginePath !== undefined ? deps.enginePath : readEnginePath(cwd)) !== "full";
   if (orch.recovery?.maxAttempts && !recoveryOn) sink.line("recovery: off (engine.path is full; recovery lanes run on the core path only)");
@@ -1835,7 +1867,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     const hostIo = await laneCheck.hostLaneIo({ env });
     preflight = async () => (await laneCheck.runLaneChecks({ exec: execForNeeds, env, io: hostIo })).filter((c) => !c.ok);
   }
-  let rows;
+  let rows, childFields = null; // #4965: the host gh's accepted `issue list --json` fields, read once from its help
   try {
     rows = await orchestrate({
       ...(estimate ? { estimate } : {}),
@@ -1843,9 +1875,11 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       ...(preflight ? { preflight } : {}),
       ...(orch.blockedLabel ? { getBlocked: async () => JSON.parse(await leanIo.gh(["issue", "list", "-R", repo, "--label", orch.blockedLabel, "--state", "open", "--limit", "200", "--json", "number"])).map((x) => x.number) } : {}), // #4773
       trusted: (n) => trustedOf.get(n) === true,
+      autoChildren,
+      ...(autoMod.addsEpicChildren(autoChildren.mode) ? { getChildren: async () => ({ list: await autoMod.readChildList({ gh: (a) => leanIo.gh(a), repo, fields: childFields ??= await autoMod.hostListFields((a) => leanIo.gh(a)) }), elsewhere: autoMod.liveElsewhere({ batchMod, root, self: batch.id, repo }) }) } : {}),
       issues, parallel, prefilter, resolveLane: laneOf, store: batch.store, getParallel: batch.readParallel, getAdded: batch.readAdded, getRequeued: batch.readRequeued, getCancelled: batch.readCancel, getHeld: batch.readHeld, getGates: batch.readGates, ...lanes,
       breaker: orch.breaker, maxDeferrals: orch.maxDeferrals, ...(deps.pollMs ? { pollMs: deps.pollMs } : {}), ...budget, limits, identity, batchId: batch.id, drift, lifecycle, integration,
-      ...(registry ? { sched: { registry, batch: batch.id, repo, cap: liveLaneCap(orch.globalParallel ?? null), exclusive: true }, priorityOf: async (n) => schedMod.priorityFromLabels(await labelNames(n)) } : {}),
+      ...(registry ? { sched: { registry, batch: batch.id, repo, cap: liveLaneCap(orch.globalParallel ?? null, { cfg: readAdmission(cwd) }), exclusive: true }, priorityOf: async (n) => schedMod.priorityFromLabels(await labelNames(n)) } : {}),
       ...(remote ? { remote } : {}),
       // #4267: mechanical needs-human outcomes are recovered in the batch; every runner decision is a FORGE:DECISION.
       ...(recoveryOn ? { recovery: orch.recovery } : {}),
@@ -2058,8 +2092,20 @@ export async function scheddFromCli(argv, deps = {}) {
   if (argv[0] === "status") {
     let sock;
     try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { console.log("schedd: not running"); return { running: false }; }
-    const st = await schedd.request(sock, { op: "status" });
-    console.log(`schedd: pid ${st.pid}, ${st.batches.length} batch(es)${st.batches.length ? ": " + st.batches.map((b) => b.id).join(", ") : ""}${Number.isFinite(st.lastTick) ? `, last tick ${Math.round((Date.now() - st.lastTick) / 1000)} s ago` : ""}`);
+    let st;
+    try { st = await schedd.request(sock, { op: "status" }, undefined, { timeoutMs: deps.statusMs ?? schedd.REQUEST_MS }); }
+    catch (e) {
+      if (e?.code !== "schedd.timeout") throw e;
+      console.log(`schedd: not responding (${e.message}); see ${schedd.scheddPaths(dir).log}`);
+      process.exitCode = 1;
+      return { running: true, responding: false };
+    }
+    console.log(`schedd: pid ${st.pid}, ${st.batches.length} batch(es)${Number.isFinite(st.lastTick) ? `, last tick ${Math.round((Date.now() - st.lastTick) / 1000)} s ago` : ""}`);
+    for (const b of st.batches) {
+      const age = b.lastProgressAgeSec == null ? "no progress yet" : `last progress ${b.lastProgressAgeSec}s ago`;
+      const pend = b.pendingAdds?.length ? `, pending adds: ${b.pendingAdds.map((n) => `#${n}`).join(" ")}` : "";
+      console.log(`  ${b.id}${b.running ? "" : " (not hosted)"}: ${age}${pend}`);
+    }
     return { running: true, ...st };
   }
   if (argv[0] === "watchdog") { // #4780: run by the schedd watchdog timer; signals a live daemon whose heartbeat went stale
@@ -2073,7 +2119,13 @@ export async function scheddFromCli(argv, deps = {}) {
   process.title = "forgedock-schedd"; // distinctive name for OOM-killer avoid lists and ps (#4673)
   const d = await schedd.startDaemon({ dir, runBatch: (a) => runBatch({ ...a, daemon: true, deps: deps.batchDeps ?? {} }), ...(deps.due !== undefined ? { due: deps.due } : { due: scheddDue }),
     ...(deps.daemonPreflight !== undefined ? { preflight: deps.daemonPreflight } : deps.batchDeps ? {} : { preflight: async () => { const lc = await import("./lean/lanecheck.mjs"); return (await lc.runLaneChecks({ exec: readExecution(process.cwd()), io: await lc.hostLaneIo() })).filter((c) => !c.ok); } }) });
-  if (!d.running) return d;
+  if (!d.running) {
+    // #4775: under systemd, exiting here (code 0) makes `Restart=always` loop while another daemon holds the lock: stand by, take over when it dies
+    if (!(deps.standby ?? Boolean(process.env.INVOCATION_ID))) return d;
+    const wait = deps.standbyMs ?? 5000, alive = deps.alive ?? ((await import("./lean/sched.mjs")).pidAlive);
+    do await (deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))))(wait); while (alive(d.owner));
+    return scheddFromCli(argv, deps);
+  }
   // #4454: a signal stops the hosted batch loops, then releases the lock and socket, then exits 128+signo
   schedd.exitOnSignals(d, { ...(deps.processOn ? { on: deps.processOn } : {}), ...(deps.exit ? { exit: deps.exit } : {}) });
   await d.closed;
@@ -2129,7 +2181,7 @@ export async function decisionsFromCli(argv, deps = {}) {
   const [sub, ...rest] = argv;
   if (sub !== "list") throw new Error(usage);
   const flag = (n) => { const i = rest.indexOf(n); return i >= 0 ? rest[i + 1] : null; };
-  const run = deps.exec ?? (async (cmd, args) => String((await pexec(cmd, args, { maxBuffer: 64 * 1024 * 1024 })).stdout));
+  const run = deps.exec ?? (async (cmd, args) => String((await pexec(cmd, args, { maxBuffer: 64 * 1024 * 1024, timeout: 60000 })).stdout));
   const repo = flag("--repo") ?? String(await run("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"])).trim();
   if (rest.includes("--refresh")) {
     const jq = '.[] | select(.body | startswith("<!-- FORGE:DECISION {")) | {body, user, author_association, issue_url} | tojson';
@@ -2266,6 +2318,13 @@ export async function schedFromCli(argv, deps = {}) {
 /** #4773: is the author of a `viewIssue` record (author plus the REST association, #4859) trusted (the engine admission's `isTrustedActor`)? */
 const bodyTrusted = (v) => isTrustedActor({ association: v?.authorAssociation, type: v?.author?.is_bot ? "Bot" : "User", login: v?.author?.login });
 
+/** forge.yaml `orchestration.auto_add_children` (#4965; default `decomposed`) and `auto_add_children_poll_s` (default 120). */
+export function readAutoChildren(cwd = process.cwd()) {
+  let o = {};
+  try { o = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.orchestration ?? {}; } catch { o = {}; }
+  return { mode: _autoChildren.parseAutoMode(o.auto_add_children), pollS: _autoChildren.parsePollS(o.auto_add_children_poll_s) };
+}
+
 /**
  * forge.yaml `orchestration.breaker` ({errors, window_min}; default 3 engine-errors in 30 min; errors 0 turns it off),
  * `orchestration.max_deferrals` (default 3) and `orchestration.global_parallel` (#4191: host-wide lane cap; unset = none). The parser flattens one nested level, so the breaker keys arrive as

package/bin/lean/autochildren.mjs

@@ -0,0 +1,103 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Auto-add of epic and decomposition children to a running batch (#4965): `orchestration.auto_add_children`.
+// Pure and deterministic: the child scan reads one open-issue list per pass; no LLM call.
+import { parentOf } from "./context.mjs";
+import { parseHelpFields } from "./selftest-static.mjs";
+
+export const AUTO_MODES = ["off", "decomposed", "epic", "all"];
+export const DEFAULT_AUTO_MODE = "decomposed";
+export const DEFAULT_POLL_S = 120;
+
+/** @returns {string} a valid mode (case-insensitive), else `fallback` (forge.yaml typos never stop a batch). */
+export function parseAutoMode(v, fallback = DEFAULT_AUTO_MODE) {
+  const m = String(v ?? "").trim().toLowerCase();
+  return AUTO_MODES.includes(m) ? m : fallback;
+}
+
+/** The CLI form: an unknown mode is an operator error. */
+export function parseAutoModeFlag(v) {
+  const m = String(v ?? "").trim().toLowerCase();
+  if (!AUTO_MODES.includes(m)) throw new Error(`--auto-children must be one of ${AUTO_MODES.join(" | ")}`);
+  return m;
+}
+
+/** Seconds between scans: a positive integer, else the default. */
+export function parsePollS(v, fallback = DEFAULT_POLL_S) {
+  const n = Number(v);
+  return v !== undefined && v !== null && v !== "" && Number.isInteger(n) && n >= 1 ? n : fallback;
+}
+
+/** Does `mode` add the epic/tracker children (`epic`, `all`)? */
+export const addsEpicChildren = (mode) => mode === "epic" || mode === "all";
+/** Does `mode` join the sub-issues of a decomposed lane (`decomposed`, `all`; `epic` keeps today's join too)? */
+export const joinsDecomposed = (mode) => mode !== "off";
+
+const nodesOf = (v) => (Array.isArray(v) ? v : Array.isArray(v?.nodes) ? v.nodes : []);
+const labelsOf = (it) => nodesOf(it?.labels).map((l) => String(l?.name ?? l));
+
+/**
+ * @param {{number:number, body?:string, labels?:any, parent?:any, subIssues?:any}[]} list one open-issue list
+ * @param {Iterable<number>} roots the batch issues plus the `--epic N` epics
+ * @param {Iterable<number>} skip issues the batch already holds
+ * @returns {number[]} open children of a root, ascending: `**Parent**: #P` line, `parent` field, or the root's `subIssues`;
+ *   an issue labelled `needs-human` is left out.
+ */
+export function selectChildren({ list, roots, skip = [] }) {
+  const rootSet = new Set(roots), skipSet = new Set(skip), open = new Set(), out = new Set();
+  for (const it of list ?? []) if (Number.isSafeInteger(it?.number)) open.add(it.number);
+  for (const it of list ?? []) {
+    const n = it?.number;
+    if (!open.has(n)) continue;
+    if (rootSet.has(n)) for (const s of nodesOf(it.subIssues)) if (open.has(s?.number)) out.add(s.number);
+    const p = it.parent?.number ?? parentOf(it.body ?? "");
+    if (p != null && rootSet.has(p)) out.add(n);
+  }
+  const byNum = new Map((list ?? []).map((it) => [it.number, it]));
+  return [...out].filter((n) => !skipSet.has(n) && !labelsOf(byNum.get(n)).includes("needs-human")).sort((a, b) => a - b);
+}
+
+const REQUIRED_FIELDS = ["number", "body", "labels"], OPTIONAL_FIELDS = ["parent", "subIssues"];
+
+/** The `--json` list this host's `gh issue list` accepts (read from its `--help`, K4): the required fields plus whichever sub-issue fields it advertises. */
+export async function hostListFields(gh) {
+  let have = [];
+  try { have = parseHelpFields(await gh(["issue", "list", "--help"])); } catch { have = []; }
+  return [...REQUIRED_FIELDS, ...OPTIONAL_FIELDS.filter((f) => have.includes(f))];
+}
+
+/**
+ * One open-issue list with what `selectChildren` reads. A host `gh` without `parent`/`subIssues` still lists with the
+ * required fields, so children are found by their `**Parent**: #P` line.
+ */
+export async function readChildList({ gh, repo, limit = 1000, fields = null }) {
+  const f = fields ?? (await hostListFields(gh));
+  const raw = await gh(["issue", "list", "-R", repo, "--state", "open", "--limit", String(limit), "--json", f.join(",")]);
+  const v = JSON.parse(raw);
+  return Array.isArray(v) ? v : [];
+}
+
+/**
+ * Issues another live batch of this repo still holds (in its order, no final row): children there are not added here.
+ * @param {{batchMod:object, root:string, self:string, repo:string}} p
+ */
+export function liveElsewhere({ batchMod, root, self, repo }) {
+  const held = new Set();
+  let ids = [];
+  try { ids = batchMod.listBatches(root); } catch { return held; }
+  for (const raw of ids) {
+    const id = typeof raw === "string" ? raw : raw?.id;
+    if (!id || id === self) continue;
+    try {
+      const b = batchMod.openBatch(root, id);
+      if (b.readReport() || (b.readPlan()?.repo ?? repo) !== repo) continue;
+      const st = b.store.load();
+      if (!st) continue;
+      for (const n of st.order ?? []) if (!(st.results ?? {})[n]) held.add(n);
+    } catch { /* an unreadable batch holds nothing */ }
+  }
+  return held;
+}
+
+/** `#a blocked by #b, ...` for the declared edges of the added children that stay inside the batch. */
+export const edgeText = (edges) => edges.map((e) => `#${e.from} blocked by #${e.to}`).join(", ");

package/bin/lean/autochildren.test.mjs

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4965: auto-add of epic and decomposition children: mode parse, child selection, filters.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseAutoMode, parseAutoModeFlag, parsePollS, selectChildren, readChildList, hostListFields, liveElsewhere, joinsDecomposed, addsEpicChildren, DEFAULT_POLL_S } from "./autochildren.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+describe("#4965 modes", () => {
+  it("default is decomposed; unknown yaml values fall back; the flag rejects them", () => {
+    assert.equal(parseAutoMode(undefined), "decomposed");
+    assert.equal(parseAutoMode("EPIC"), "epic");
+    assert.equal(parseAutoMode("bogus"), "decomposed");
+    assert.equal(parseAutoModeFlag("all"), "all");
+    assert.throws(() => parseAutoModeFlag("bogus"), /--auto-children/);
+    assert.equal(parsePollS(undefined), DEFAULT_POLL_S);
+    assert.equal(parsePollS("30"), 30);
+    assert.equal(parsePollS("0"), DEFAULT_POLL_S);
+  });
+  it("which modes add epic children and which join decomposed", () => {
+    assert.deepEqual(["off", "decomposed", "epic", "all"].map(addsEpicChildren), [false, false, true, true]);
+    assert.deepEqual(["off", "decomposed", "epic", "all"].map(joinsDecomposed), [false, true, true, true]);
+  });
+});
+
+describe("#4965 selectChildren", () => {
+  const list = [
+    { number: 1, body: "epic", labels: [], subIssues: { nodes: [{ number: 5 }, { number: 9 }] } },
+    { number: 2, body: "x\n\n**Parent**: #1", labels: [] },
+    { number: 3, body: "", labels: [], parent: { number: 1 } },
+    { number: 4, body: "**Parent**: #1", labels: [{ name: "needs-human" }] },
+    { number: 5, body: "", labels: [] },
+    { number: 6, body: "**Parent**: #77", labels: [] },
+    { number: 7, body: "**Parent**: #1", labels: [] },
+  ];
+  it("finds children by Parent line, parent field and sub-issues; skips needs-human, closed sub-issues and unrelated", () => {
+    assert.deepEqual(selectChildren({ list, roots: [1], skip: [1] }), [2, 3, 5, 7]);
+  });
+  it("skips issues already in the batch or held elsewhere", () => {
+    assert.deepEqual(selectChildren({ list, roots: [1], skip: [1, 2, 7] }), [3, 5]);
+  });
+  it("an --epic root outside the batch yields its children", () => {
+    assert.deepEqual(selectChildren({ list, roots: [77] }), [6]);
+  });
+  it("children filed later appear on a later list", () => {
+    assert.deepEqual(selectChildren({ list: [...list, { number: 8, body: "**Parent**: #1", labels: [] }], roots: [1], skip: [1, 2, 3, 5, 7] }), [8]);
+  });
+});
+
+describe("#4965 readers", () => {
+  const help = (fields) => `Usage\n\nJSON FIELDS\n  ${fields.join(", ")}\n\nEXAMPLES\n  $ gh issue list\n`;
+  const fakeGh = (fields, calls) => async (a) => {
+    calls.push(a);
+    if (a.includes("--help")) return help(fields);
+    const j = a[a.indexOf("--json") + 1].split(",");
+    const bad = j.find((f) => !fields.includes(f));
+    if (bad) throw new Error(`Unknown JSON field: "${bad}"`);
+    return "[{\"number\":1}]";
+  };
+  it("readChildList asks the host gh for its fields, then makes one list call", async () => {
+    const calls = [];
+    const r = await readChildList({ gh: fakeGh(["number", "body", "labels", "parent", "subIssues", "title"], calls), repo: "o/r" });
+    assert.equal(calls.filter((a) => !a.includes("--help")).length, 1);
+    assert.equal(calls.at(-1)[calls.at(-1).indexOf("--json") + 1], "number,body,labels,parent,subIssues");
+    assert.deepEqual(r, [{ number: 1 }]);
+  });
+  it("a host gh without parent/subIssues still lists, with the fields it has (children found by Parent line)", async () => {
+    const calls = [];
+    const gh = fakeGh(["number", "body", "labels", "title"], calls);
+    assert.deepEqual(await hostListFields(gh), ["number", "body", "labels"]);
+    assert.deepEqual(await readChildList({ gh, repo: "o/r" }), [{ number: 1 }]);
+    assert.equal(calls.at(-1)[calls.at(-1).indexOf("--json") + 1], "number,body,labels");
+  });
+  it("liveElsewhere holds the unsettled issues of other live batches of the repo only", () => {
+    const mk = (o) => ({ readReport: () => o.report ?? null, readPlan: () => ({ repo: o.repo ?? "o/r" }), store: { load: () => ({ order: o.order, results: o.results ?? {} }) } });
+    const bs = { a: mk({ order: [1, 2], results: { 1: {} } }), b: mk({ order: [3], report: {} }), c: mk({ order: [4], repo: "x/y" }), self: mk({ order: [5] }) };
+    const batchMod = { listBatches: () => Object.keys(bs), openBatch: (_r, id) => bs[id] };
+    assert.deepEqual([...liveElsewhere({ batchMod, root: "/r", self: "self", repo: "o/r" })], [2]);
+  });
+});
+
+describe("#4965 forge.yaml and resume", () => {
+  it("readAutoChildren reads auto_add_children and its poll; defaults keep today's behaviour", async () => {
+    const { readAutoChildren } = await import("../engine-cli.mjs");
+    const { writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const d = tmpDir("ac-");
+    assert.equal(readAutoChildren(d).mode, "decomposed");
+    assert.equal(readAutoChildren(d).pollS, 120);
+    writeFileSync(join(d, "forge.yaml"), "orchestration:\n  auto_add_children: epic\n  auto_add_children_poll_s: 30\n");
+    assert.equal(readAutoChildren(d).mode, "epic");
+    assert.equal(readAutoChildren(d).pollS, 30);
+  });
+  it("--resume keeps the mode: a resumed batch whose plan carries --auto-children epic --epic 9 adds #9's children", async () => {
+    const { openBatch } = await import("./batch.mjs");
+    const { orchestrateFromCli } = await import("../engine-cli.mjs");
+    const fs = await import("node:fs");
+    const { join } = await import("node:path");
+    process.env.FORGEDOCK_SCHED_DIR = tmpDir("ac-sched-");
+    const work = tmpDir("acb-"), root = join(work, "batches"), launches = join(work, "launches");
+    fs.writeFileSync(launches, "");
+    const stub = join(work, "stub.mjs");
+    fs.writeFileSync(stub, `import { appendFileSync, writeFileSync } from "node:fs";
+const a = process.argv.slice(2); const rf = a[a.indexOf("--result-file") + 1];
+appendFileSync(${JSON.stringify(launches)}, a[1] + "\\n"); writeFileSync(rf, JSON.stringify({ terminalReason: "merged", pr: 100 + Number(a[1]), cost_usd: 0 }));
+`);
+    const b = openBatch(root, "b20261101-000000-1");
+    b.writePlan({ v: 1, id: b.id, argv: ["1", "--repo", "o/r", "--no-prefilter", "--auto-children", "epic", "--epic", "9"], repo: "o/r", cwd: process.cwd(), created: new Date().toISOString() });
+    b.setParallel(2);
+    const lists = [];
+    const gh = async (a) => {
+      if (a[0] === "issue" && a[1] === "list" && a.includes("--help")) return "JSON FIELDS\n  number, body, labels, parent, subIssues\n\nEXAMPLES\n";
+      if (a[0] === "issue" && a[1] === "list" && a.includes("--state") && a.includes("number,body,labels,parent,subIssues")) { lists.push(a); return JSON.stringify([{ number: 9, body: "", labels: [] }, { number: 51, body: "**Parent**: #9", labels: [] }]); }
+      if (a.includes("milestone")) return JSON.stringify({ milestone: null });
+      if (a[0] === "repo") return "main\n";
+      return JSON.stringify({ body: "", state: "OPEN", labels: [] });
+    };
+    const deps = { batchRoot: root, allowTmpfs: true, laneScript: stub, pollMs: 20, orchestration: { breaker: null, maxDeferrals: 3 }, io: { gh: async () => "o/r\n" },
+      leanIo: { gh, git: async (a) => (a[0] === "ls-remote" ? "abc\trefs/heads/staging\n" : "") } };
+    const l = console.log; console.log = () => {};
+    let res;
+    try { res = await orchestrateFromCli(["--resume", b.id], deps); } finally { console.log = l; }
+    assert.ok(lists.length >= 1, "the child list was read: the epic mode survived the resume");
+    assert.deepEqual(res.rows.map((r) => r.issue).sort((x, y) => x - y), [1, 51]);
+  });
+});

package/bin/lean/batch.mjs

@@ -15,7 +15,7 @@
  * running; a resumed dispatcher re-attaches to it by pid, checking `/proc/<pid>/cmdline` against its result path. These
  * detached lanes are the `local` execution (#4253); `execution.mjs` is the sandbox-provider seam for remote lanes.
  */
-import { appendFileSync, chmodSync, closeSync, existsSync, fchmodSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, existsSync, fchmodSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
@@ -86,7 +86,7 @@ const readAdded = (file) => {
 };
 
 /** `outcome`s `--requeue` may move back to pending (#4550). */
-export const REQUEUABLE = (outcome) => ["needs-human", "invalid", "skipped", "ci-pending", "budget-exceeded", "lane-refused"].includes(outcome) || /^dependency-/.test(String(outcome));
+export const REQUEUABLE = (outcome) => ["needs-human", "invalid", "skipped", "ci-pending", "budget-exceeded", "lane-refused", "deferred"].includes(outcome) || /^dependency-/.test(String(outcome));
 /** Key of one requeue entry; the runner records the applied keys in state.json `requeueApplied`. */
 export const requeueKey = (e) => `${e.issue}@${e.at}`;
 
@@ -220,6 +220,12 @@ export function openBatch(root, id) {
     clearCancel: () => rmSync(f("cancel"), { force: true }),
     /** Added issues the batch never took into its `order` (a finished or unhosted batch with pending adds). */
     unrunAdds: () => { const order = new Set(readJson(f("state.json"))?.order ?? []); return readAdded(f("add")).filter((n) => !order.has(n)); },
+    /** #4775: epoch ms of the batch's last progress (newest mtime of `state.json` / `log.jsonl`), or null when neither exists. */
+    lastProgressMs: () => {
+      let best = null;
+      for (const n of ["state.json", "log.jsonl"]) { try { const m = statSync(f(n)).mtimeMs; if (best === null || m > best) best = m; } catch { /* absent */ } }
+      return best;
+    },
     /** The lane updates in `log.jsonl`, in order (unparsable lines skipped). */
     readLog: () => {
       let text = "";

package/bin/lean/batch.test.mjs

@@ -75,12 +75,13 @@ await orchestrateFromCli(["1", "2", "3", "--parallel", "2", "--repo", "o/r", "--
       { code: "merge.transient" },
       { code: "push.transient" },
       { code: "cli.idle" },
+      { 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.deepEqual(gaps, [60, 600, DEFER_BACKOFF_S, 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
@@ -844,7 +845,7 @@ describe("#4528: a full sandbox pool (sandbox.capacity) is never capped", () =>
     assert.deepEqual(deferPolicy({ code: "sandbox.capacity" }, { now: 0, deferrals: 99 }), { delayMs: 60000, host: true });
     assert.deepEqual(deferPolicy({ code: "sandbox.capacity", retryInSeconds: 30 }, { now: 0, deferrals: 99, maxDeferrals: 3 }), { delayMs: 30000, host: true });
     assert.deepEqual(deferPolicy({ code: "sandbox.unreachable", retryInSeconds: 60 }, { now: 0, deferrals: 99, maxDeferrals: 3 }), { delayMs: 60000, host: true }); // #4788
-    for (const code of ["merge.transient", "gh.unavailable", "cli.idle", "rate_limited", "sandbox.start_failed"]) {
+    for (const code of ["merge.transient", "gh.unavailable", "cli.idle", "sandbox.start_failed"]) {
       assert.deepEqual(deferPolicy({ code, retryInSeconds: 60 }, { now: 0, deferrals: 3, maxDeferrals: 3 }), { capped: true }, code);
     }
   });
@@ -873,6 +874,32 @@ describe("#4528: a full sandbox pool (sandbox.capacity) is never capped", () =>
   });
 });
 
+describe("#4784: usage-limit deferrals", () => {
+  it("rate_limited is never capped and keeps its hold; a deferred row is requeuable", async () => {
+    assert.deepEqual(deferPolicy({ code: "rate_limited", resetAtEpochMs: 5000 }, { now: 1000, deferrals: 99, maxDeferrals: 3 }), { delayMs: 4000, hold: true });
+    const { now, sleep } = fakeClock();
+    let runs = 0;
+    const rows = await orchestrate({ issues: [1], readBody: async () => "", now, sleep, maxDeferrals: 3,
+      runOne: async () => (++runs <= 6 ? { terminalReason: "deferred", code: "rate_limited", retryInSeconds: 600 } : { terminalReason: "merged", pr: 9 }) });
+    assert.equal(runs, 7);
+    assert.equal(rows[0].outcome, "merged");
+    const b = openBatch(tmpDir("batch-requeue-deferred-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [1], results: { 1: { outcome: "deferred" } } });
+    assert.deepEqual(b.requeue([1]).requeued, [1]);
+  });
+  it("a requeuable deferred row: an issue that gave up after N deferrals (#4984)", async () => {
+    const { now, sleep } = fakeClock();
+    const rows = await orchestrate({ issues: [1], readBody: async () => "", now, sleep, maxDeferrals: 3,
+      runOne: async () => ({ terminalReason: "deferred", code: "followup.unavailable", detail: "no tracking issue was returned for R2" }) });
+    assert.match(rows[0].detail, /gave up after 3 deferrals/);
+    const b = openBatch(tmpDir("batch-requeue-gaveup-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [1], results: { 1: { outcome: rows[0].outcome, detail: rows[0].detail } } });
+    assert.deepEqual(b.requeue([1]).requeued, [1]);
+  });
+});
+
 describe("#4550: forgedock orchestrate --requeue", () => {
   const gate = () => { let open; const p = new Promise((r) => { open = r; }); return { p, open }; };
   it("a needs-human issue is requeued and relaunched; its skipped dependent returns to pending and runs after it merges; one row per issue", async () => {