forgedock 1.32.1 → 1.34.0

package/bin/review-staging.mjs

@@ -85,6 +85,9 @@ export function parseArgs(argv) {
   return o;
 }
 
+/** Largest diff slice substituted into a brief; a larger one is referenced by its file (#4573). */
+const INLINE_SLICE_MAX = 16000;
+
 /** Replace every `[KEY]` in one pass: a substituted value is never rescanned, so diff text cannot inject placeholders. */
 export function renderBrief(template, values) {
   return template.replace(/\[([A-Z][A-Z0-9_]*)\]/g, (m, k) => (Object.hasOwn(values, k) && values[k] != null ? String(values[k]) : m));
@@ -273,6 +276,8 @@ async function main(argv, io) {
   const agents = ctx.roster?.agents?.length ? ctx.roster.agents : ["security"];
   const launchedFile = join(sd, `${pr}_launched_review_agents`);
   io.writeFile(launchedFile, "");
+  // The head this list describes: review-prepare trusts the list as --delta proof only for this head.
+  io.writeFile(`${launchedFile}.head`, `${head}\n`);
   const briefDir = join(sd, `review-staging-${pr}`);
   io.mkdir(briefDir);
   const briefs = [];
@@ -282,6 +287,8 @@ async function main(argv, io) {
     const slice = ctx.slices?.[domain];
     let diff = "";
     try { diff = slice?.diff_file ? io.readFile(slice.diff_file) : ""; } catch { diff = ""; }
+    // #4573: the persona templates repeat [DOMAIN_DIFF_SLICE] many times, so only a small slice is inlined; a large one is a pointer to the on-disk slice file.
+    if (diff.length > INLINE_SLICE_MAX) diff = `(diff slice too large to inline: ${diff.length} chars. Read the file ${slice.diff_file} instead, e.g. grep -n or sed -n 'X,Yp' on it, never cat it whole. Files listed as OMITTED at its top are read from the head checkout.)`;
     const values = {
       PR_NUMBER: pr, REVIEW_SHA: head, REVIEW_SHA_SHORT: sha7, AGENT_DOMAIN: domain, GH_REPO: c.ghRepo,
       TITLE: ctx.pr?.title ?? "", FILE_LIST: (slice?.paths ?? ctx.full_files ?? []).join(" "), SERVICES: (ctx.classification?.services ?? []).join(" "),
@@ -405,7 +412,11 @@ async function finalize(a, io) {
   if (!/^[A-Za-z0-9._/-]+$/.test(codeBranch)) codeBranch = c.stagingBranch;
 
   const findings = readJson(io, join(outDir, "findings.json"))?.findings ?? [];
-  const confirmed = (sev) => findings.filter((f) => upper(f.confidence) === "CONFIRMED" && upper(f.severity) === sev).length;
+  // A finding whose own filed issue is already closed (file-prepare: skip-resolved, delta pass) is resolved: it never blocks (#4569).
+  const resolvedBy = new Map(worklist.items.filter((i) => i.action === "skip-resolved").map((i) => [i.id, i.dedup_of]));
+  const resolved = findings.filter((f) => resolvedBy.has(f.id) && upper(f.confidence) === "CONFIRMED" && ["CRITICAL", "HIGH"].includes(upper(f.severity)))
+    .map((f) => ({ id: f.id, severity: upper(f.severity), title: f.title ?? "", issue: resolvedBy.get(f.id) }));
+  const confirmed = (sev) => findings.filter((f) => !resolvedBy.has(f.id) && upper(f.confidence) === "CONFIRMED" && upper(f.severity) === sev).length;
   const outOfScope = Number(/out_of_scope=(\d+)/.exec(readText(io, join(outDir, "note-disposition.md")) ?? "")?.[1] ?? 0);
   const counts = {
     findings_kept: Number(x.FINDINGS_KEPT ?? 0), findings_dropped_stale: Number(x.FINDINGS_DROPPED_STALE ?? 0), findings_preexisting: Number(x.FINDINGS_PREEXISTING ?? 0),
@@ -415,7 +426,7 @@ async function finalize(a, io) {
   const items = worklist.items;
   const state = {
     pr, head, bundle, codeBranch, scopeMode, delta, testGate: { verdict: tg.verdict, reason: tg.reason }, counts, notes,
-    confirmedCritical: confirmed("CRITICAL"), confirmedHigh: confirmed("HIGH"),
+    confirmedCritical: confirmed("CRITICAL"), confirmedHigh: confirmed("HIGH"), resolved,
     toFile: items.filter((i) => i.action === "file"), skipped: items.filter((i) => String(i.action).startsWith("skip-")),
   };
   io.writeFile(join(sd, `${pr}_finalize.json`), JSON.stringify(state));
@@ -500,6 +511,7 @@ async function summary(a, io) {
     `- findings_kept: ${n.findings_kept ?? 0}; dropped_stale: ${n.findings_dropped_stale ?? 0}; pre-existing: ${n.findings_preexisting ?? 0}; notes_demoted_no_scenario: ${n.notes_demoted_no_scenario ?? 0}`,
     `- findings_filed: ${n.findings_filed ?? 0}${filed.length ? ` (${filed.join(", ")})` : ""}; out_of_scope: ${n.out_of_scope ?? 0}`,
     `- notes_fixed: 0; notes_listed: ${n.notes_listed ?? 0}; notes_dropped: ${n.notes_dropped ?? 0}; notes_capped: ${n.notes_capped ?? 0}; notes_reflag: ${n.notes_reflag ?? 0}`,
+    `- resolved (excluded from the verdict): ${(st.resolved ?? []).length ? st.resolved.map((r) => `${r.severity} ${r.id} ${r.title} (closed #${r.issue})`.replace(/\s+/g, " ")).join("; ") : "(none)"}`,
     `- deduped: ${deduped.length ? deduped.join("; ") : "(none)"}`,
     ...(st.delta?.from ? [`- delta pass: ${String(st.delta.from).slice(0, 7)}..${head.slice(0, 7)} (${(st.delta.files ?? []).length} file(s)); earlier pass at ${st.delta.from} credited (its findings re-read by extract)`] : []),
     "",

package/bin/runner.mjs

@@ -1809,6 +1809,7 @@ export function runCliBackend({
           ` Invocation: ${bin} ${argvSummary} (cwd: ${cwd})`,
       );
       err.code = "CLI_BACKEND_FAILED";
+      err.status = result.status ?? null; err.signal = result.signal ?? null; // #4518: lets bin/lean/hostkill.mjs tell an external kill
       // forge#2241: attach the CLI's reported session-limit reset time (when
       // present) so callers (bin/engine.mjs) can surface *when* a
       // quota-exhaustion failure will clear without reading raw logs. Only

package/bin/stats/aggregate.mjs

@@ -295,6 +295,12 @@ export function computeAlerts(lanes = [], opts = {}) {
       const ex = failed.flatMap((l) => l.deps).find((d) => (d.eco ?? "unknown") === eco && d.status === "failed");
       add(`DEPS_PREPARED failed (${eco})`, failed.length, used.length, c.depsFailedPct / 100, ex?.reason ?? null);
     }
+    // #4522: a broken snapshot falls back to a fresh install; the lane has dependencies, but the cache still needs a look.
+    const fell = used.filter((l) => l.deps.some((d) => (d.eco ?? "unknown") === eco && d.status === "materialize-fallback"));
+    if (fell.length / used.length > c.depsFailedPct / 100) {
+      const ex = fell.flatMap((l) => l.deps).find((d) => (d.eco ?? "unknown") === eco && d.status === "materialize-fallback");
+      add(`DEPS_PREPARED materialize-fallback (${eco})`, fell.length, used.length, c.depsFailedPct / 100, ex?.reason ?? null);
+    }
   }
   const deferred = win.filter((l) => l.deferred.length);
   if (deferred.length / win.length > c.deferredPct / 100) add("deferred-to-ci", deferred.length, win.length, c.deferredPct / 100, deferred[deferred.length - 1].deferred[0]);

package/bin/stats/efficiency.mjs

@@ -49,6 +49,8 @@ const costOf = (e) => num(e.cost_usd_delta) ?? num(e.cost_usd);
 const sum = (xs) => xs.reduce((a, b) => a + (num(b) ?? 0), 0);
 const r = (x, p = 1e4) => (num(x) == null ? null : Math.round(x * p) / p);
 const per = (a, b) => (b > 0 ? a / b : null);
+/** #4491: GitHub slugs are case-insensitive (`--repo o/forgedock` matches a plan's `O/ForgeDock`). */
+export const sameRepo = (a, b) => String(a ?? "").toLowerCase() === String(b ?? "").toLowerCase();
 
 function parseLog(text) {
   const out = [];
@@ -67,13 +69,14 @@ export function issueSlices(events) {
   let cur = null;
   for (const e of Array.isArray(events) ? events : []) {
     if (!e || typeof e !== "object") continue;
-    if (e.event === "RUN_START") { cur = { startTs: e.ts ?? null, repo: e.repo ?? null, terminal: null, shape: "full", attempts: [] }; out.push(cur); continue; }
+    if (e.event === "RUN_START") { cur = { startTs: e.ts ?? null, repo: e.repo ?? null, terminal: null, shape: "full", conformance: null, attempts: [] }; out.push(cur); continue; }
     if (!cur) continue;
     if (e.event === "LIGHT_DONE") cur.shape = "light";
+    else if (e.event === "CONFORMANCE" && typeof e.state === "string") cur.conformance = e.state; // #4491: the slice's last verdict
     else if (e.event === "LIGHT_UPGRADE") cur.shape = "upgraded";
     if (e.event === "PHASE_ATTEMPT_USAGE") {
       cur.attempts.push({ phase: e.phase ?? "other", trigger: e.trigger ?? null, restart_of: e.restart_of ?? null, model: e.model ?? null,
-        turns: num(e.turns), cacheRead: num(e.usage?.cache_read_input_tokens), cost: costOf(e),
+        turns: num(e.turns), cacheRead: num(e.usage?.cache_read_input_tokens), cost: costOf(e), durationMs: num(e.duration_ms), // #4491
         ...(e.tools && typeof e.tools === "object" ? { calls: num(e.tools.calls), toolTurns: num(e.tools.turns), rereads: num(e.tools.rereads) } : {}) }); // #4410
     } else if (e.event === "RUN_TERMINAL") {
       cur.terminal = { reason: e.reason ?? null, code: e.code ?? null, ts: e.ts ?? null, size: SIZES.includes(e.turns?.size) ? e.turns.size : null };
@@ -137,10 +140,17 @@ const median = (xs) => {
   return s.length % 2 ? s[h] : r((s[h - 1] + s[h]) / 2, 100);
 };
 
+/** #4491: a lane's implement wall in minutes, the sum of its implement attempts' duration_ms; null when none carries it. */
+function laneWall(impl) {
+  const xs = impl.filter((a) => a.durationMs != null);
+  return xs.length ? r(sum(xs.map((a) => a.durationMs)) / 60000, 100) : null;
+}
+const wallP50 = (xs) => median(xs.map((x) => x.implWall).filter((w) => w != null));
+
 const group = (xs) => {
   const turns = sum(xs.map((x) => x.implTurns)), cache = sum(xs.map((x) => x.implCache));
   return { n: xs.length, cost_usd: r(sum(xs.map((x) => x.cost)), 1e6), usd_per_merge: r(per(sum(xs.map((x) => x.cost)), xs.length)),
-    turns_per_merge: r(per(turns, xs.length), 10), context_per_turn: r(per(cache, turns), 1) };
+    turns_per_merge: r(per(turns, xs.length), 10), context_per_turn: r(per(cache, turns), 1), implement_wall_p50_min: wallP50(xs) };
 };
 
 /**
@@ -149,7 +159,7 @@ const group = (xs) => {
  */
 export function efficiencyMetrics({ entries = [], logs = new Map(), issues = null, repo = null, now = 0, notes = [] } = {}) {
   const merged = [];
-  const inScope = (row, settleAt) => issueSlices(logs.get(row.issue) ?? []).filter((s) => (!repo || !s.repo || s.repo === repo) && (!settleAt || !s.startTs || s.startTs <= settleAt));
+  const inScope = (row, settleAt) => issueSlices(logs.get(row.issue) ?? []).filter((s) => (!repo || !s.repo || sameRepo(s.repo, repo)) && (!settleAt || !s.startTs || s.startTs <= settleAt));
   // #4452: light/full split and upgrade rate over every lane of every row (all outcomes); cost is the #4407 delta sum
   const shapes = Object.fromEntries(LANE_SHAPES.map((k) => [k, { n: 0, cost_usd: 0 }]));
   for (const { row, settleAt } of entries) {
@@ -169,7 +179,7 @@ export function efficiencyMetrics({ entries = [], logs = new Map(), issues = nul
     const term = [...slices].reverse().find((s) => s.terminal?.reason === "merged")?.terminal;
     merged.push({ issue: row.issue, slices: slices.length, cost: sum(atts.map((a) => a.cost)), implCost: sum(impl.map((a) => a.cost)),
       reviewCost: sum(atts.filter((a) => a.phase === "review").map((a) => a.cost)), implTurns: sum(impl.map((a) => a.turns)), implCache: sum(impl.map((a) => a.cacheRead)),
-      size: term?.size ?? laneSize({ labels: info?.labels ?? [] }) ?? "unknown", impl, retries, info, tools: laneTools(impl), shape: slices.at(-1)?.shape ?? null });
+      size: term?.size ?? laneSize({ labels: info?.labels ?? [] }) ?? "unknown", impl, retries, info, tools: laneTools(impl), shape: slices.at(-1)?.shape ?? null, implWall: laneWall(impl) });
   }
   const all = group(merged);
   const bySize = {};
@@ -182,6 +192,9 @@ export function efficiencyMetrics({ entries = [], logs = new Map(), issues = nul
     }
   }
   const retries = Object.fromEntries(RETRY_CAUSES.map((c) => [c, sum(merged.map((m) => m.retries[c]))]));
+  // #4491: merge rate over the rows, conformance pass rate over rows whose lanes logged a verdict (each row's last one)
+  const rows = entries.filter(({ row }) => Number.isSafeInteger(row?.issue));
+  const verdicts = rows.map(({ row, settleAt }) => inScope(row, settleAt).map((s) => s.conformance).filter(Boolean).at(-1)).filter(Boolean);
   const withTools = merged.filter((m) => m.tools);
   const total = sum(Object.values(retries));
   // no possible action: parked post-deploy follow-ups and promotion-blocked lanes (#4389), over all rows
@@ -209,6 +222,8 @@ export function efficiencyMetrics({ entries = [], logs = new Map(), issues = nul
     merged: merged.length, cost_usd: all.cost_usd, implement_usd: r(sum(merged.map((m) => m.implCost)), 1e6), review_usd: r(sum(merged.map((m) => m.reviewCost)), 1e6),
     usd_per_merge: all.usd_per_merge, turns_per_merge: all.turns_per_merge, context_per_turn: all.context_per_turn,
     implement_turns: sum(merged.map((m) => m.implTurns)), implement_cache_read: sum(merged.map((m) => m.implCache)),
+    implement_wall_p50_min: all.implement_wall_p50_min, merge_rate: r(per(merged.length, rows.length)),
+    conformance_pass_rate: r(per(verdicts.filter((v) => v === "conforms").length, verdicts.length)),
     by_size: bySize,
     by_model: Object.fromEntries(Object.entries(byModel).map(([k, g]) => [k, { merges: g.merges.size, attempts: g.attempts, turns: g.turns, cost_usd: r(g.cost, 1e6),
       usd_per_merge: r(per(g.cost, g.merges.size)), turns_per_merge: r(per(g.turns, g.merges.size), 10), context_per_turn: r(per(g.cache, g.turns), 1) }])),
@@ -219,7 +234,8 @@ export function efficiencyMetrics({ entries = [], logs = new Map(), issues = nul
     tool_calls_per_turn_p50: median(withTools.map((m) => m.tools.per_turn)), rereads_per_merge: withTools.length ? r(per(sum(withTools.map((m) => m.tools.rereads)), withTools.length), 100) : null,
     per_issue: merged.map((m) => ({ issue: m.issue, slices: m.slices, cost_usd: r(m.cost, 1e6), implement_usd: r(m.implCost, 1e6), implement_turns: m.implTurns,
       implement_cache_read: m.implCache, size: m.size, retries: m.retries, ...(m.shape ? { shape: m.shape } : {}), ...(m.info ? { quality: issueQuality(m.info.body).tag } : {}),
-      ...(m.tools ? { implement_tool_calls_per_turn: m.tools.per_turn, implement_rereads: m.tools.rereads } : {}) })),
+      ...(m.tools ? { implement_tool_calls_per_turn: m.tools.per_turn, implement_rereads: m.tools.rereads } : {}),
+      ...(m.implWall != null ? { implement_wall_min: m.implWall } : {}) })),
     notes,
   };
 }
@@ -274,26 +290,77 @@ export async function batchEfficiency({ batchDir, runsDir, repo = null, gh = nul
   return { batch: plan.id ?? null, ...(await computeScope({ entries, runsDir, repo: repo ?? plan.repo ?? null, gh, now })) };
 }
 
-/** Trailing windows: the union of the repo's batches created in each window; an issue in several batches counts once (latest row). */
-export async function windowEfficiency({ batchRoot, runsDir, repo = null, gh = null, now = Date.now(), windows = [WEEK_MS] }) {
+/** The repo's batches by creation time, and the repo slug as the plans spell it (run-log file names are case-sensitive, #4491). */
+function repoBatches(batchRoot, repo) {
   const batches = (existsSync(batchRoot) ? listBatches(batchRoot) : []).map((id) => {
     const dir = join(batchRoot, id), plan = readJson(join(dir, "plan.json")) ?? {};
     return { dir, plan, created: Date.parse(plan.created ?? "") };
-  }).filter((b) => Number.isFinite(b.created) && (!repo || b.plan.repo === repo)).sort((a, b) => a.created - b.created);
+  }).filter((b) => Number.isFinite(b.created) && (!repo || sameRepo(b.plan.repo, repo))).sort((a, b) => a.created - b.created);
+  return { batches, repo: repo ? (batches.find((b) => typeof b.plan.repo === "string")?.plan.repo ?? repo) : repo };
+}
+
+/** Rows of the batches created in [from, to]; an issue in several batches counts once (latest row). */
+function cohortEntries(batches, from, to, toInclusive = true) {
+  const inside = batches.filter((b) => b.created >= from && (toInclusive ? b.created <= to : b.created < to));
+  const latest = new Map();
+  for (const b of inside) {
+    const at = settleTimes(readLogRows(b.dir));
+    for (const row of batchRows(b.dir)) if (Number.isSafeInteger(row?.issue)) latest.set(row.issue, { row, settleAt: at.get(row.issue) ?? null });
+  }
+  return { batches: inside.length, entries: [...latest.values()] };
+}
+
+/** Trailing windows: the union of the repo's batches created in each window; an issue in several batches counts once (latest row). */
+export async function windowEfficiency({ batchRoot, runsDir, repo = null, gh = null, now = Date.now(), windows = [WEEK_MS] }) {
+  const { batches, repo: slug } = repoBatches(batchRoot, repo);
   const out = {};
   for (const w of windows) {
-    const latest = new Map();
-    for (const b of batches) {
-      if (b.created > now || now - b.created > w) continue;
-      const at = settleTimes(readLogRows(b.dir));
-      for (const row of batchRows(b.dir)) if (Number.isSafeInteger(row?.issue)) latest.set(row.issue, { row, settleAt: at.get(row.issue) ?? null });
-    }
-    out[windowLabel(w)] = { batches: batches.filter((b) => b.created <= now && now - b.created <= w).length,
-      ...(await computeScope({ entries: [...latest.values()], runsDir, repo, gh, now })) };
+    const c = cohortEntries(batches, now - w, now);
+    out[windowLabel(w)] = { batches: c.batches, ...(await computeScope({ entries: c.entries, runsDir, repo: slug, gh, now })) };
+  }
+  return out;
+}
+
+export const COMPARE_KEYS = Object.freeze(["turns_per_merge", "implement_wall_p50_min", "tool_calls_per_turn_p50", "rereads_per_merge", "merge_rate", "conformance_pass_rate"]);
+const delta = (a, b) => Object.fromEntries(COMPARE_KEYS.map((k) => [k, num(a?.[k]) == null || num(b?.[k]) == null ? null : r(b[k] - a[k], 100)]));
+
+/**
+ * #4491: full-shape merged lanes per size bucket present in both cohorts (light lanes, #4452, cut turns on their own).
+ * A merged row with no in-scope run log carries no shape and drops out, so its zero turns do not pull a bucket down.
+ */
+function matchedCohorts(pre, post) {
+  const full = (m) => (m.per_issue ?? []).filter((x) => x.shape === "full");
+  const bySize = (xs) => xs.reduce((o, x) => ((o[x.size] ??= []).push(x), o), {});
+  const a = bySize(full(pre)), b = bySize(full(post)), out = {};
+  const g = (xs) => {
+    const tools = xs.filter((x) => x.implement_tool_calls_per_turn != null);
+    return { n: xs.length, turns_per_merge: r(per(sum(xs.map((x) => x.implement_turns)), xs.length), 10),
+      implement_wall_p50_min: median(xs.map((x) => x.implement_wall_min).filter((w) => w != null)),
+      tool_calls_per_turn_p50: median(tools.map((x) => x.implement_tool_calls_per_turn)),
+      rereads_per_merge: tools.length ? r(per(sum(tools.map((x) => x.implement_rereads)), tools.length), 100) : null };
+  };
+  for (const size of Object.keys(a).sort()) {
+    if (!b[size]) continue;
+    const pa = g(a[size]), pb = g(b[size]);
+    out[size] = { pre: pa, post: pb, delta: delta(pa, pb) };
   }
   return out;
 }
 
+/**
+ * #4491: before/after A/B around a deploy `pivot` (ms): post = the repo's batches created in [pivot, min(now, pivot + span)],
+ * pre = the same span ending just before the pivot. `span` defaults to the time since the pivot, so both cohorts are equally long.
+ */
+export async function compareEfficiency({ batchRoot, runsDir, repo = null, gh = null, pivot, now = Date.now(), span = null }) {
+  if (!Number.isFinite(pivot) || pivot > now) throw new Error("compare: the pivot must be a time in the past");
+  const s = Math.max(0, Math.min(Number.isFinite(span) ? span : Infinity, now - pivot));
+  const { batches, repo: slug } = repoBatches(batchRoot, repo);
+  const a = cohortEntries(batches, pivot - s, pivot, false), b = cohortEntries(batches, pivot, pivot + s);
+  const pre = { batches: a.batches, ...(await computeScope({ entries: a.entries, runsDir, repo: slug, gh, now })) };
+  const post = { batches: b.batches, ...(await computeScope({ entries: b.entries, runsDir, repo: slug, gh, now })) };
+  return { pivot: new Date(pivot).toISOString(), span_days: r(s / 86400000, 100), pre, post, delta: delta(pre, post), matched: matchedCohorts(pre, post) };
+}
+
 export const windowLabel = (ms) => `${Math.round(ms / 86400000)}d`;
 /** "7d,30d" -> [ms]; throws on anything else. */
 export function parseWindows(s) {
@@ -331,5 +398,24 @@ export function formatEfficiencyLines(m, label = "") {
   const ln = m.lanes; // #4452
   lines.push(ln ? `lanes: ${LANE_SHAPES.map((k) => `${k} ${ln[k]?.n ?? 0} (${usd(ln[k]?.cost_usd ?? 0)})`).join(", ")}; upgrade rate ${ln.upgrade_rate == null ? "n/a"
     : `${Math.round(ln.upgrade_rate * 100)}% (${ln.upgraded?.n ?? 0}/${(ln.light?.n ?? 0) + (ln.upgraded?.n ?? 0)})`}` : "lanes: n/a");
+  lines.push(rates(m)); // #4491
+  return lines;
+}
+
+const pct = (x) => (num(x) == null ? "n/a" : `${Math.round(x * 100)}%`);
+const rates = (m) => `implement wall p50 ${m.implement_wall_p50_min == null ? "n/a" : `${f(m.implement_wall_p50_min, 1)} min`}, merge rate ${pct(m.merge_rate)}, conformance pass ${pct(m.conformance_pass_rate)}`;
+const sign = (x, d, unit = "") => (num(x) == null ? "n/a" : `${x > 0 ? "+" : ""}${x.toFixed(d)}${unit}`);
+const deltaLine = (d, withRates = true) => `turns/merge ${sign(d.turns_per_merge, 1)}, implement wall p50 ${sign(d.implement_wall_p50_min, 1, " min")}, calls/turn p50 ${sign(d.tool_calls_per_turn_p50, 2)}, `
+  + `re-reads/merge ${sign(d.rereads_per_merge, 2)}${withRates ? `, merge rate ${sign(d.merge_rate == null ? null : d.merge_rate * 100, 0, " pts")}, conformance pass ${sign(d.conformance_pass_rate == null ? null : d.conformance_pass_rate * 100, 0, " pts")}` : ""}`;
+const cohortLine = (k, m) => `compare ${k}: n=${m.n ?? m.merged} turns/merge ${f(m.turns_per_merge, 1)}, implement wall p50 ${m.implement_wall_p50_min == null ? "n/a" : `${f(m.implement_wall_p50_min, 1)} min`}, `
+  + `calls/turn p50 ${f(m.tool_calls_per_turn_p50)}, re-reads/merge ${f(m.rereads_per_merge)}${"merge_rate" in m ? `, merge rate ${pct(m.merge_rate)}, conformance pass ${pct(m.conformance_pass_rate)}` : ""}`;
+
+/** #4491: the `--compare` report: pre/post cohorts, their delta, then the full-shape per-size matched cohorts. */
+export function formatCompareLines(c) {
+  const lines = [`compare: pivot ${c.pivot}, ${f(c.span_days, 1)} days each side (pre ${c.pre.batches} batches, post ${c.post.batches} batches)`,
+    cohortLine("pre", c.pre), cohortLine("post", c.post), `compare delta: ${deltaLine(c.delta)}`];
+  const sizes = Object.entries(c.matched ?? {});
+  if (!sizes.length) lines.push("compare matched (full lanes per size): n/a");
+  for (const [size, g] of sizes) lines.push(`compare matched ${size}: pre n=${g.pre.n} post n=${g.post.n}; delta ${deltaLine(g.delta, false)}`);
   return lines;
 }

package/bin/stats/efficiency.test.mjs

@@ -9,9 +9,10 @@ import { tmpDir } from "../tests/_tmp.mjs";
 import { TRIGGERS } from "../lean/fixround.mjs";
 import {
   TRIGGER_CAUSE, RETRY_CAUSES, WEEK_MS, codeCause, issueSlices, sliceRetries, issueQuality, acceptanceOf, efficiencyMetrics,
-  batchEfficiency, windowEfficiency, formatEfficiencyLines, parseWindows,
+  batchEfficiency, windowEfficiency, formatEfficiencyLines, parseWindows, compareEfficiency, formatCompareLines,
 } from "./efficiency.mjs";
-import { parseArgs, runStats } from "./index.mjs";
+import { comparePivot, parseArgs, runStats } from "./index.mjs";
+import { runLogPath } from "../engine/runlog.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const FX = join(here, "fixtures", "efficiency-20261022");
@@ -115,7 +116,8 @@ describe("#4402 efficiencyMetrics", () => {
   });
   it("renders n/a, never NaN, for an empty cohort", () => {
     const lines = formatEfficiencyLines(efficiencyMetrics({}));
-    assert.equal(lines.length, 9);
+    assert.equal(lines.length, 10);
+    assert.equal(lines[9], "implement wall p50 n/a, merge rate n/a, conformance pass n/a"); // #4491, appended
     assert.ok(!lines.some((l) => /NaN|undefined/.test(l)), lines.join("\n"));
     assert.match(lines[0], /^efficiency: merged 0, n\/a\/merge/);
     assert.equal(lines[6], "acceptance (7d after promotion): n/a");
@@ -152,7 +154,7 @@ describe("#4452 light/full split and upgrade rate", () => {
   });
   it("the batch report prints the split and the upgrade rate", () => {
     const lines = formatEfficiencyLines(m);
-    assert.equal(lines.at(-1), "lanes: light 2 ($0.65), upgraded 2 ($0.90), full 1 ($1.00); upgrade rate 50% (2/4)");
+    assert.equal(lines.find((l) => l.startsWith("lanes:")), "lanes: light 2 ($0.65), upgraded 2 ($0.90), full 1 ($1.00); upgrade rate 50% (2/4)");
   });
 });
 
@@ -264,3 +266,100 @@ describe("#4402 forgedock stats --efficiency", () => {
     assert.match(text, /^no action: 32 lanes, \$10\.13 \(blocked-promotion 32\)$/m);
   });
 });
+
+describe("#4491 before/after compare", () => {
+  const PIVOT = Date.parse("2026-10-20T00:00:00Z"), SLUG = "Own/Repo";
+  const tools = (calls, turns, rereads) => ({ tools: { calls, turns, per_turn: calls / turns, rereads, top: [] } });
+  // pre batch (10-18): issues 1, 2 merged (M, full), 3 failed; post batch (10-21): issues 4 merged (M, full), 5 merged light, 6 merged (L, full);
+  // 8 (pre) and 7 (post) merged with no run log, so both sides hold a size-unknown, shapeless lane
+  const lane = (turns, wallMin, t, conf, size = "M", extra = []) => [start("2026-10-01T00:00:00Z", SLUG), att("implement", { trigger: "build", turns, duration_ms: wallMin * 60000, ...t }),
+    ...extra, ...(conf ? [{ event: "CONFORMANCE", state: conf }] : []), term("merged", "merged", { turns: { size } })];
+  const setup = () => {
+    const root = tmpDir("eff-cmp-root-"), runs = tmpDir("eff-cmp-runs-");
+    const batch = (id, created, rows) => {
+      mkdirSync(join(root, id), { recursive: true });
+      writeFileSync(join(root, id, "plan.json"), JSON.stringify({ v: 1, id, repo: SLUG, created }));
+      writeFileSync(join(root, id, "report.json"), JSON.stringify({ rows }));
+    };
+    batch("pre", "2026-10-18T00:00:00Z", [{ issue: 1, outcome: "merged" }, { issue: 2, outcome: "merged" }, { issue: 3, outcome: "failed" }, { issue: 8, outcome: "merged" }]);
+    batch("old", "2026-10-10T00:00:00Z", [{ issue: 9, outcome: "merged" }]); // outside the 3-day span
+    batch("post", "2026-10-21T00:00:00Z", [{ issue: 4, outcome: "merged" }, { issue: 5, outcome: "merged" }, { issue: 6, outcome: "merged" }, { issue: 7, outcome: "merged" }]);
+    const logs = {
+      1: lane(40, 30, tools(40, 40, 2), "conforms"), 2: lane(60, 50, tools(60, 60, 4), "nonconforming"),
+      3: [start("2026-10-01T00:00:00Z", SLUG), att("implement", { trigger: "build" }), { event: "CONFORMANCE", state: "nonconforming" }, term("failed", "ci.red")],
+      4: lane(20, 20, tools(30, 20, 0), "conforms"), 5: lane(5, 2, tools(5, 5, 0), "conforms", "S", [{ event: "LIGHT_DONE" }]), 6: lane(30, 25, tools(30, 30, 1), null, "L"),
+      9: lane(99, 99, tools(99, 99, 9), "conforms"),
+    };
+    for (const [n, evs] of Object.entries(logs)) writeFileSync(runLogPath(runs, Number(n), SLUG), evs.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    return { root, runs };
+  };
+
+  it("compare splits equal-span cohorts at the pivot with implement wall, merge and conformance rates, and deltas", async () => {
+    const { root, runs } = setup();
+    const c = await compareEfficiency({ batchRoot: root, runsDir: runs, repo: SLUG, pivot: PIVOT, now: PIVOT + 3 * DAY });
+    assert.equal(c.span_days, 3);
+    assert.deepEqual([c.pre.batches, c.pre.merged, c.post.batches, c.post.merged], [1, 3, 1, 4]); // 8 and 7 merged without a run log
+    assert.equal(c.pre.implement_wall_p50_min, 40); // median of 30 and 50
+    assert.equal(c.post.implement_wall_p50_min, 20);
+    assert.equal(c.pre.merge_rate, 0.75);
+    assert.equal(c.post.merge_rate, 1);
+    assert.equal(c.pre.conformance_pass_rate, 0.3333); // 1 of 3 verdicts
+    assert.equal(c.post.conformance_pass_rate, 1); // issue 6 has no verdict
+    assert.equal(c.delta.turns_per_merge, -19.5); // (40 + 60 + 0) / 3 = 33.3 -> (20 + 5 + 30 + 0) / 4 = 13.8
+    assert.equal(c.delta.implement_wall_p50_min, -20);
+    assert.equal(c.delta.merge_rate, 0.25);
+    assert.equal(c.delta.tool_calls_per_turn_p50, 0);
+  });
+  it("compare matches full lanes per size present on both sides (light, log-less lanes and unmatched sizes drop out)", async () => {
+    const { root, runs } = setup();
+    const c = await compareEfficiency({ batchRoot: root, runsDir: runs, repo: SLUG, pivot: PIVOT, now: PIVOT + 3 * DAY });
+    assert.deepEqual(Object.keys(c.matched), ["M"]); // issues 7 and 8 (no log, size unknown) are in no bucket
+    assert.deepEqual(c.matched.M.pre, { n: 2, turns_per_merge: 50, implement_wall_p50_min: 40, tool_calls_per_turn_p50: 1, rereads_per_merge: 3 });
+    assert.deepEqual(c.matched.M.post, { n: 1, turns_per_merge: 20, implement_wall_p50_min: 20, tool_calls_per_turn_p50: 1.5, rereads_per_merge: 0 });
+    assert.equal(c.matched.M.delta.tool_calls_per_turn_p50, 0.5);
+    assert.equal(c.matched.M.delta.turns_per_merge, -30);
+  });
+  it("compare report lines", async () => {
+    const { root, runs } = setup();
+    const lines = formatCompareLines(await compareEfficiency({ batchRoot: root, runsDir: runs, repo: SLUG, pivot: PIVOT, now: PIVOT + 3 * DAY }));
+    assert.equal(lines[0], "compare: pivot 2026-10-20T00:00:00.000Z, 3.0 days each side (pre 1 batches, post 1 batches)");
+    assert.match(lines[1], /^compare pre: n=3 turns\/merge 33\.3, implement wall p50 40\.0 min, calls\/turn p50 1\.00, re-reads\/merge 3\.00, merge rate 75%, conformance pass 33%$/);
+    assert.match(lines[3], /^compare delta: turns\/merge -?\d+\.\d, implement wall p50 -20\.0 min, .*merge rate \+25 pts, conformance pass \+67 pts$/);
+    assert.match(lines[4], /^compare matched M: pre n=2 post n=1; delta turns\/merge -30\.0, implement wall p50 -20\.0 min, calls\/turn p50 \+0\.50, re-reads\/merge -3\.00$/);
+    assert.ok(!lines.some((l) => /NaN|undefined/.test(l)), lines.join("\n"));
+  });
+  it("case-insensitive repo: a lowercase --repo matches the plans and reads the run logs under their spelling", async () => {
+    const { root, runs } = setup();
+    const c = await compareEfficiency({ batchRoot: root, runsDir: runs, repo: "own/repo", pivot: PIVOT, now: PIVOT + 3 * DAY });
+    assert.deepEqual([c.pre.merged, c.post.merged, c.pre.implement_wall_p50_min], [3, 4, 40]);
+    const w = (await windowEfficiency({ batchRoot: root, runsDir: runs, repo: "OWN/REPO", now: PIVOT + 3 * DAY, windows: [7 * DAY] }))["7d"];
+    assert.deepEqual([w.batches, w.merged], [2, 7]);
+  });
+  it("compare rejects a pivot in the future and prints a bare n/a delta for empty cohorts", async () => {
+    await assert.rejects(compareEfficiency({ batchRoot: tmpDir("eff-cmp-x-"), runsDir: tmpDir("eff-cmp-y-"), pivot: NOW + DAY, now: NOW }), /pivot/);
+    const empty = formatCompareLines(await compareEfficiency({ batchRoot: tmpDir("eff-cmp-x-"), runsDir: tmpDir("eff-cmp-y-"), pivot: NOW - DAY, now: NOW }));
+    assert.equal(empty[3], "compare delta: turns/merge n/a, implement wall p50 n/a, calls/turn p50 n/a, re-reads/merge n/a, merge rate n/a, conformance pass n/a");
+  });
+  it("compare and offline flags: parsing, pivot resolution and the offline CLI skips gh", async () => {
+    const o = parseArgs(["--efficiency", "--compare", "v1.32.0", "--offline"]);
+    assert.deepEqual([o.compare, o.offline], ["v1.32.0", true]);
+    assert.throws(() => parseArgs(["--compare", "2026-10-20"]), /need --efficiency/);
+    assert.throws(() => parseArgs(["--offline"]), /need --efficiency/);
+    assert.throws(() => parseArgs(["--efficiency", "--compare", "last-week"]), /--compare must be/);
+    assert.equal(comparePivot("2026-10-20T00:00:00Z"), PIVOT);
+    assert.equal(comparePivot("v1.32.0", [{ v: "1.32.0", t: PIVOT / 1000 }]), PIVOT);
+    assert.throws(() => comparePivot("9.9.9", []), /no release time known/);
+    const { root, runs } = setup();
+    const out = [], w = process.stdout.write;
+    process.stdout.write = (t) => { out.push(String(t)); return true; };
+    let code;
+    try {
+      code = await runStats(["--efficiency", "--window", "7d", "--compare", "2026-10-20T00:00:00Z", "--offline", "--repo", "own/repo"],
+        { batchRoot: root, runsDir: runs, now: () => PIVOT + 3 * DAY, releaseTimes: [], gh: async () => { throw new Error("gh must not be called offline"); } });
+    } finally { process.stdout.write = w; }
+    assert.equal(code, 0);
+    const text = out.join("");
+    assert.match(text, /^compare: pivot 2026-10-20T00:00:00\.000Z/m);
+    assert.match(text, /^issue quality: n\/a \(no gh\/repo\)$/m);
+  });
+});

package/bin/stats/index.mjs

@@ -15,14 +15,16 @@ import { readLanes, readLocalLaneRuns, readLocalRuns, runsDir } from "./local-so
 import { parseForgeYaml } from "../forge-utils.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
 import { edgeQuery, parseEdge, verdictMix, contextPackAb, renderContextAb, builderTierReport, renderTiers, exploreAb, renderExploreAb, laneProfileReport, renderLaneProfiles } from "./query.mjs";
-import { batchEfficiency, windowEfficiency, formatEfficiencyLines, parseWindows } from "./efficiency.mjs";
+import { batchEfficiency, windowEfficiency, compareEfficiency, formatEfficiencyLines, formatCompareLines, parseWindows } from "./efficiency.mjs";
+import { poolUtilisation, formatPoolLines } from "./pool.mjs";
 import { batchRoot } from "../lean/batch.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
 export const HELP = `Usage: forgedock stats [--since <version|date>] [--repo <owner/repo>] [--json] [--refresh]
                       [--compact] [--no-local] [--no-cache] [--min-n N] [--release-times FILE]
-       forgedock stats --efficiency [--batch <id>] [--window 7d,30d] [--repo <owner/repo>] [--json]
+       forgedock stats --pool [--window 7d,30d] [--repo <owner/repo>] [--json]
+       forgedock stats --efficiency [--batch <id>] [--window 7d,30d] [--compare <date|version>] [--offline] [--repo <owner/repo>] [--json]
 
 Version-over-version report: Cost, Time, Flow, Review funnel, Gates and Issue flow per (version, repo), with a
 delta against the previous version and a low-n flag for samples under 10. Missing data prints n/a.
@@ -56,11 +58,18 @@ Explorer A/B (forge#4418; local run logs only, every run of each log, no GitHub
   --explore-ab          builder turns, builder cache-read, merge and conformance rates per size (S, M, L) and
                         lean.explore mode (on, off), plus the same issues run in both modes; --json for JSON
 
+Pool (forge#4549; local batch reports, no gh):
+  --pool                remote lane minutes, lanes and share per pool agent over --window (default 7d,30d)
+
 Efficiency (forge#4402; local batch dirs and run logs, gh only for merged issues' bodies, labels and probes):
   --efficiency          $/merge, turns/merge, context/turn per size and model, retries/merge by cause, no-action
                         lanes, issue quality vs cost and the acceptance pass rate 7 days after promotion
   --batch <id>          also report one batch (~/.forge/batches/<id>, FORGEDOCK_BATCH_DIR)
   --window <list>       trailing windows over the repo's batches (default 7d,30d)
+  --compare <date|v>    before/after A/B around a deploy (date or release tag): equal-span cohorts of batches either side,
+                        turns/merge, implement wall p50, calls/turn p50, re-reads/merge, merge and conformance rates,
+                        their delta and full-lane cohorts matched per size (forge#4491)
+  --offline             skip the GitHub crawl for merged issues (issue quality and acceptance print n/a)
 
 Builder model tiers (forge#4394; local run logs only, no GitHub crawl):
   --tiers               merge, conformance and post-merge-rework rates, first-pass yield and cost per builder tier
@@ -73,7 +82,7 @@ Lane profile baseline (forge#4436; local run logs only, every run of each issue,
 `;
 
 export function parseArgs(argv) {
-  const o = { since: null, repo: null, edge: null, milestone: null, contextAb: false, exploreAb: false, tiers: false, laneProfile: false, issues: null, efficiency: false, batch: null, windows: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
+  const o = { since: null, repo: null, edge: null, milestone: null, contextAb: false, exploreAb: false, tiers: false, laneProfile: false, issues: null, efficiency: false, pool: false, batch: null, windows: null, compare: null, offline: false, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
   const val = (i, name) => {
     const v = argv[i + 1];
     if (v == null || v.startsWith("--")) throw new Error(`${name} needs a value`);
@@ -95,8 +104,15 @@ export function parseArgs(argv) {
     else if (name === "--lane-profile") o.laneProfile = true;
     else if (name === "--issues") { const v = take(); if (!/^[1-9]\d*(,[1-9]\d*)*$/.test(v)) throw new Error("--issues must be a comma list of issue numbers"); o.issues = v.split(",").map(Number); }
     else if (name === "--efficiency") o.efficiency = true;
+    else if (name === "--pool") o.pool = true;
     else if (name === "--batch") { const v = take(); if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v)) throw new Error(`invalid --batch id: ${v}`); o.batch = v; }
     else if (name === "--window") o.windows = parseWindows(take());
+    else if (name === "--compare") { // #4491
+      const v = take(), bad = () => new Error(`--compare must be a date (YYYY-MM-DD[THH:MM:SSZ]) or a version (1.32.0): ${v}`);
+      try { if (!v || !Object.keys(parseSince(v)).length) throw bad(); } catch { throw bad(); }
+      o.compare = v;
+    }
+    else if (name === "--offline") o.offline = true;
     else if (name === "--min-n") { const v = take(); if (!/^\d+$/.test(v)) throw new Error("--min-n must be a non-negative integer"); o.minN = Number(v); }
     else if (name === "--json") o.json = true;
     else if (name === "--refresh") o.refresh = true;
@@ -106,7 +122,9 @@ export function parseArgs(argv) {
     else if (name === "--help" || name === "-h") o.help = true;
     else throw new Error(`unknown argument: ${a}`);
   }
-  if ((o.batch || o.windows) && !o.efficiency) throw new Error("--batch and --window need --efficiency");
+  if (o.batch && !o.efficiency) throw new Error("--batch and --window need --efficiency");
+  if (o.windows && !o.efficiency && !o.pool) throw new Error("--batch and --window need --efficiency");
+  if ((o.compare || o.offline) && !o.efficiency) throw new Error("--compare and --offline need --efficiency");
   return o;
 }
 
@@ -147,6 +165,15 @@ export function sinceToTimestamp(since, releaseTimes = []) {
   return { since: null, note: null };
 }
 
+/** #4491: `--compare` pivot in ms: a date as is, a version as its exact tag time (no crawl margin); throws when unknown. */
+export function comparePivot(v, releaseTimes = []) {
+  const p = parseSince(v);
+  if (p.sinceMs != null) return p.sinceMs;
+  const hit = releaseTimes.find((r) => r.v === p.sinceVersion);
+  if (!hit) throw new Error(`--compare: no release time known for ${p.sinceVersion} (pass --release-times or a date)`);
+  return hit.t * 1000;
+}
+
 /** Throttled stderr progress printer (never stdout, so --json stays parseable). */
 export function makeProgressPrinter(write = (t) => process.stderr.write(t), now = Date.now) {
   let last = 0, lastPhase = null;
@@ -215,11 +242,16 @@ export async function buildReport(opts, deps = {}) {
   if (opts.releaseTimes) releaseTimes = parseReleaseTimes(readFileSync(opts.releaseTimes, "utf8"));
   else if (deps.releaseTimes) releaseTimes = deps.releaseTimes;
   else releaseTimes = gitTagTimes();
+  if (opts.pool) { // forge#4549: local batch reports only
+    const pool = poolUtilisation({ batchRoot: deps.batchRoot ?? batchRoot(env), repo, windows: opts.windows ?? parseWindows("7d,30d"), now: deps.now?.() ?? Date.now() });
+    return { repo, query: { pool } };
+  }
   if (opts.efficiency) { // forge#4402: local batch dirs + run logs; gh only for merged issues
-    const root = deps.batchRoot ?? batchRoot(env), rd = deps.runsDir ?? runsDir(env), now = deps.now?.() ?? Date.now(), gh = deps.gh ?? defaultGh;
+    const root = deps.batchRoot ?? batchRoot(env), rd = deps.runsDir ?? runsDir(env), now = deps.now?.() ?? Date.now(), gh = opts.offline ? null : (deps.gh ?? defaultGh);
     const efficiency = {};
     if (opts.batch) efficiency.batch = await batchEfficiency({ batchDir: join(root, opts.batch), runsDir: rd, repo, gh, now });
     efficiency.windows = await windowEfficiency({ batchRoot: root, runsDir: rd, repo, gh, now, windows: opts.windows ?? parseWindows("7d,30d") });
+    if (opts.compare) efficiency.compare = await compareEfficiency({ batchRoot: root, runsDir: rd, repo, gh, now, pivot: comparePivot(opts.compare, releaseTimes) });
     return { repo, query: { efficiency } };
   }
   if (opts.contextAb) { // forge#4275: run logs only
@@ -276,10 +308,12 @@ export async function runStats(argv, deps = {}) {
     const report = await buildReport(opts, { onProgress: makeProgressPrinter(), ...deps });
     if (report.query?.lane_profile && !opts.json) { process.stdout.write(`${renderLaneProfiles(report.query.lane_profile)}\n`); return 0; }
     if (report.query?.tiers && !opts.json) { process.stdout.write(`${renderTiers(report.query.tiers)}\n`); return 0; }
+    if (report.query?.pool && !opts.json) { process.stdout.write(`${formatPoolLines(report.query.pool).join("\n")}\n`); return 0; }
     if (report.query?.efficiency && !opts.json) {
       const e = report.query.efficiency;
       const lines = [...(e.batch ? formatEfficiencyLines(e.batch, `batch ${e.batch.batch ?? opts.batch}`) : []),
-        ...Object.entries(e.windows).flatMap(([w, m]) => formatEfficiencyLines(m, `${w}, ${m.batches} batch${m.batches === 1 ? "" : "es"}`))];
+        ...Object.entries(e.windows).flatMap(([w, m]) => formatEfficiencyLines(m, `${w}, ${m.batches} batch${m.batches === 1 ? "" : "es"}`)),
+        ...(e.compare ? formatCompareLines(e.compare) : [])];
       process.stdout.write(`${lines.join("\n")}\n`);
       return 0;
     }

package/bin/stats/local-source.mjs

@@ -58,7 +58,7 @@ export function summariseLog(events, fallbackIssue = null) {
   const usage = ev.filter((e) => e.event === "PHASE_ATTEMPT_USAGE");
   const builderCalls = usage.filter((e) => e.phase === "implement");
   const reviewCalls = usage.filter((e) => e.phase === "review").length;
-  const contextPack = { mode: term?.context_pack ?? cp?.mode ?? "off", laneType: term?.lane_type ?? cp?.lane_type ?? null, ab: (term?.context_ab ?? cp?.context_ab) === true };
+  const contextPack = { mode: term?.context_pack ?? cp?.mode ?? "off", laneType: term?.lane_type ?? cp?.lane_type ?? null, ab: (term?.context_ab ?? cp?.context_ab) === true, light: term?.light === true };
   const startTs = start.ts ?? null;
   const endTs = finished ? ev[t].ts ?? null : null;
   const a = Date.parse(startTs ?? ""); const b = Date.parse(endTs ?? "");

package/bin/stats/pool.mjs

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4549: pool utilisation for `forgedock stats --pool`: remote lane minutes, lanes and share per pool agent, from the
+ * repo's local batch report.json rows (`sandbox.by_agent`, written by the orchestrator). No network, no model.
+ * Live capacity stays in `forgedock pool status`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listBatches } from "../lean/batch.mjs";
+import { sameRepo, windowLabel } from "./efficiency.mjs";
+
+const readJson = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
+const round1 = (x) => Math.round(x * 10) / 10;
+
+/** Per window: the repo's batches created in it; an issue in several batches counts once (latest row). */
+export function poolUtilisation({ batchRoot, repo = null, windows, now = Date.now() }) {
+  const batches = (existsSync(batchRoot) ? listBatches(batchRoot) : []).map((id) => {
+    const dir = join(batchRoot, id), plan = readJson(join(dir, "plan.json")) ?? {};
+    return { dir, plan, created: Date.parse(plan.created ?? "") };
+  }).filter((b) => Number.isFinite(b.created) && (!repo || sameRepo(b.plan.repo, repo))).sort((a, b) => a.created - b.created);
+  const out = {};
+  for (const w of windows) {
+    const inWin = batches.filter((b) => b.created <= now && now - b.created <= w);
+    const latest = new Map();
+    for (const b of inWin) for (const row of readJson(join(b.dir, "report.json"))?.rows ?? []) if (Number.isSafeInteger(row?.issue)) latest.set(row.issue, row);
+    const agents = {};
+    let remoteLanes = 0, minutes = 0;
+    for (const row of latest.values()) {
+      if (!row.sandbox) continue;
+      remoteLanes++; minutes += Number(row.sandbox.minutes) || 0;
+      for (const [a, m] of Object.entries(row.sandbox.by_agent ?? {})) {
+        const e = (agents[a] ??= { minutes: 0, lanes: 0 });
+        e.minutes += Number(m) || 0; e.lanes++;
+      }
+    }
+    const attributed = Object.values(agents).reduce((s, e) => s + e.minutes, 0);
+    for (const e of Object.values(agents)) { e.share = attributed > 0 ? Math.round((e.minutes / attributed) * 1000) / 1000 : null; e.minutes = round1(e.minutes); }
+    out[windowLabel(w)] = { batches: inWin.length, remote_lanes: remoteLanes, minutes: round1(minutes), agents };
+  }
+  return out;
+}
+
+export function formatPoolLines(windows) {
+  return Object.entries(windows).flatMap(([w, m]) => {
+    const head = `pool ${w}: ${m.batches} batch${m.batches === 1 ? "" : "es"}, ${m.remote_lanes} remote lane${m.remote_lanes === 1 ? "" : "s"}, ${m.minutes.toFixed(1)} min`;
+    const rows = Object.entries(m.agents).sort((a, b) => b[1].minutes - a[1].minutes || a[0].localeCompare(b[0]))
+      .map(([a, e]) => `  ${a}: ${e.minutes.toFixed(1)} min, ${e.lanes} lane${e.lanes === 1 ? "" : "s"}${e.share == null ? "" : `, ${Math.round(e.share * 100)}% of pool`}`);
+    return [head, ...(rows.length ? rows : ["  per-agent minutes: n/a"])];
+  });
+}