forgedock 1.30.0 → 1.32.0

package/bin/runner.mjs

@@ -1983,17 +1983,23 @@ export function runCliBackend({
   }
 }
 
-/** Descendant processes of `pid` (pid + command line), best effort. Used to record what was alive when a session was killed. */
-export function listDescendants(pid, { psFn = null } = {}) {
+/**
+ * Descendant processes of `pid` (pid + command line), best effort. Used to record what was alive when a session was killed;
+ * `maxCmd` caps each command line (the #4405 busy check needs it whole: a long script path would cut off the tool name).
+ */
+export function listDescendants(pid, { psFn = null, maxCmd = 200 } = {}) {
   try {
     const out = psFn ? psFn() : execSync("ps -eo pid=,ppid=,args=", { encoding: "utf-8", timeout: 3000, maxBuffer: 8 * 1024 * 1024 });
-    const rows = String(out).split("\n").map((l) => /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(l)).filter(Boolean).map((m) => ({ pid: Number(m[1]), ppid: Number(m[2]), cmd: m[3].slice(0, 200) }));
+    const rows = String(out).split("\n").map((l) => /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(l)).filter(Boolean).map((m) => ({ pid: Number(m[1]), ppid: Number(m[2]), cmd: m[3].slice(0, maxCmd) }));
     const kids = []; const seen = new Set([Number(pid)]);
     for (let grew = true; grew;) { grew = false; for (const r of rows) if (!seen.has(r.pid) && seen.has(r.ppid)) { seen.add(r.pid); kids.push({ pid: r.pid, cmd: r.cmd }); grew = true; } }
     return kids.slice(0, 30);
   } catch { return []; }
 }
 
+/** #4410: cap of the tool uses one stream session records. */
+const TOOL_USES_MAX = 5000;
+
 /**
  * Async twin of runCliBackend (core work-on live comments): the CLI runs under child_process.spawn so the caller's event
  * loop keeps turning while the session runs. It returns the SAME envelope (and throws the same errors) because the
@@ -2005,9 +2011,19 @@ export function listDescendants(pid, { psFn = null } = {}) {
  * stream-json so progress is observable (the final `result` line is the envelope); `wrap(bin,args)` rewrites the spawn
  * (cgroup caps); `control` receives {pause, resume} (SIGSTOP/SIGCONT of the child's whole process group) and paused time
  * does not count as idle. `onSpawn(child)` receives the ChildProcess.
+ * #4390: `contextMax` (stream only; 0 = off) kills the session once one assistant turn's context (input + cache read +
+ * cache creation) reaches it, throwing CLI_CONTEXT with the stream-aggregated usage (null when none was seen) and turns.
+ * #4392: `turnMax` (stream only; 0 = off) kills the session once it has produced that many assistant turns (deduped by
+ * message id), throwing CLI_TURNS with `turns`, `turnMax`, `lastTool` and the stream-aggregated usage.
+ * #4405: `busy(children)` (info or null) is asked once idle (at most every min(5 s, idleMs)); while it answers busy (a live
+ * heavy step, test or lint child) the kill waits until idleMs + `busyMs` of silence, `onIdleExtend(info)` is told once per
+ * idle stretch, and a later kill carries `extended: true` and `heavyQueue` (info.heavyQueue).
+ * #4395: a stream result carries `baselineTokens`, the first assistant turn's context; absent when no message was seen.
+ * #4410: a stream result (and a CLI_TURNS / CLI_CONTEXT error) carries `toolUses`, [{msg, name, path, cmd}] per tool_use
+ * (deduped by tool_use id, capped at TOOL_USES_MAX), for bin/lean/toolstats.mjs; absent on the non-stream path.
  */
 export async function runCliBackendAsync(opts) {
-  const { spawnFn: _ignored, onSpawn = null, idleMs = 0, maxMs = 0, stream = false, wrap = null, control = null, ...rest } = opts;
+  const { spawnFn: _ignored, onSpawn = null, idleMs = 0, maxMs = 0, stream = false, wrap = null, control = null, contextMax = 0, turnMax = 0, busy = null, busyMs = 0, onIdleExtend = null, ...rest } = opts;
   let captured = null;
   try {
     runCliBackend({ ...rest, spawnFn: (bin, args, o) => {
@@ -2032,14 +2048,16 @@ export async function runCliBackendAsync(opts) {
   }
   if (typeof wrap === "function") ({ bin, args } = wrap(bin, args));
   const ceiling = maxMs > 0 ? maxMs : o.timeout;
-  let collected, idleInfo = null;
+  let collected, idleInfo = null, ctxInfo = null, turnInfo = null;
+  const msgUsage = new Map(); // #4390: assistant message id -> its usage (a message spans several stream lines)
+  const toolUses = new Map(); // #4410: tool_use id -> {msg, name, path, cmd}
   try {
     collected = await new Promise((resolveP) => {
       let stdout = "", stderr = "", settled = false, timedOut = false, paused = false;
       let lineBuf = "", resultLine = null, lastTool = null;
       const max = o.maxBuffer ?? DEFAULT_SPAWN_MAX_BUFFER_BYTES;
       const startedAt = Date.now();
-      let lastActivity = startedAt, pausedAt = 0, pausedTotal = 0, timer = null;
+      let lastActivity = startedAt, pausedAt = 0, pausedTotal = 0, timer = null, busyAsk = null, extendedSince = null, extendInfo = null;
       const finish = (r) => { if (settled) return; settled = true; clearInterval(timer); resolveP(r); };
       let child;
       const input = typeof o.input === "string" ? o.input : null; // forge#4129: large prompt over stdin
@@ -2058,10 +2076,29 @@ export async function runCliBackendAsync(opts) {
       const tick = Math.max(20, Math.min(1000, (idleMs || 4000) / 4));
       timer = setInterval(() => {
         const now = Date.now();
-        if (!paused && idleMs > 0 && now - lastActivity >= idleMs && !idleInfo) {
-          idleInfo = { lastTool, children: listDescendants(child.pid), idleMs, pid: child.pid };
-          kill();
-        } else if (!timedOut && !idleInfo && now - startedAt - pausedTotal - (paused ? now - pausedAt : 0) >= ceiling) { timedOut = true; kill(); }
+        if (!paused && idleMs > 0 && now - lastActivity >= idleMs && !idleInfo && !ctxInfo && !turnInfo) {
+          let info = null, settle = false;
+          if (typeof busy === "function" && busyMs > 0 && now - lastActivity < idleMs + busyMs) {
+            const prev = busyAsk && busyAsk.since === lastActivity ? busyAsk : null;
+            if (prev && now - prev.at < Math.min(5000, idleMs)) info = prev.info;
+            else {
+              try { info = busy(listDescendants(child.pid, { maxCmd: 8192 })) || null; } catch { info = null; }
+              busyAsk = { at: now, since: lastActivity, info };
+              // The synchronous `ps` blocked the loop: output the child wrote meanwhile is read before a first "not busy" kills.
+              settle = !info && !(prev && prev.info === null);
+            }
+          }
+          if (settle) { /* re-decided next tick */ } else if (info) {
+            extendInfo = info;
+            if (extendedSince !== lastActivity) { extendedSince = lastActivity; try { onIdleExtend?.(info); } catch { /* observer only */ } }
+          } else {
+            const extended = extendedSince === lastActivity;
+            idleInfo = { lastTool, children: listDescendants(child.pid), idleMs, pid: child.pid, extended, heavyQueue: extended ? extendInfo?.heavyQueue ?? null : null };
+            kill();
+          }
+        }
+        // #4405: a separate check, so the absolute ceiling still applies while the idle kill is extended (busy) or settling.
+        if (!timedOut && !idleInfo && !ctxInfo && !turnInfo && now - startedAt - pausedTotal - (paused ? now - pausedAt : 0) >= ceiling) { timedOut = true; kill(); }
       }, tick);
       timer.unref?.();
       const noteLine = (line) => {
@@ -2069,7 +2106,20 @@ export async function runCliBackendAsync(opts) {
         let j; try { j = JSON.parse(line); } catch { return; }
         if (j?.type === "result") resultLine = line;
         else if (j?.type === "assistant" && Array.isArray(j.message?.content)) {
-          for (const c of j.message.content) if (c?.type === "tool_use") lastTool = { name: c.name, input: JSON.stringify(c.input ?? {}).slice(0, 200), at: Date.now() };
+          for (const c of j.message.content) {
+            if (c?.type !== "tool_use") continue;
+            lastTool = { name: c.name, input: JSON.stringify(c.input ?? {}).slice(0, 200), at: Date.now() };
+            const key = c.id ?? `${j.message.id}#${toolUses.size}`, inp = c.input ?? {};
+            if (!toolUses.has(key) && toolUses.size < TOOL_USES_MAX) toolUses.set(key, { msg: j.message.id ?? null, name: c.name ?? null,
+              path: typeof (inp.file_path ?? inp.path) === "string" ? (inp.file_path ?? inp.path) : null, cmd: typeof inp.command === "string" ? inp.command.slice(0, 1000) : null });
+          }
+          const u = j.message.usage;
+          if (u && typeof u === "object") {
+            msgUsage.set(j.message.id ?? `#${msgUsage.size}`, u);
+            const ctx = toFiniteUsageNumber(u.input_tokens) + toFiniteUsageNumber(u.cache_read_input_tokens) + toFiniteUsageNumber(u.cache_creation_input_tokens);
+            if (contextMax > 0 && ctx >= contextMax && !ctxInfo && !turnInfo && !idleInfo && !timedOut) { ctxInfo = { context: ctx, lastTool }; kill(); }
+            else if (turnMax > 0 && msgUsage.size >= turnMax && !ctxInfo && !turnInfo && !idleInfo && !timedOut) { turnInfo = { lastTool }; kill(); }
+          }
         }
       };
       child.stdout.on("data", (d) => {
@@ -2090,13 +2140,32 @@ export async function runCliBackendAsync(opts) {
       });
     });
   } finally { if (sysDir) rmSync(sysDir, { recursive: true, force: true }); }
+  const sum = (k) => [...msgUsage.values()].reduce((a, u) => a + toFiniteUsageNumber(u[k]), 0);
+  const streamUsage = () => (msgUsage.size ? { input_tokens: sum("input_tokens"), output_tokens: sum("output_tokens"), cache_creation_input_tokens: sum("cache_creation_input_tokens"), cache_read_input_tokens: sum("cache_read_input_tokens") } : null);
+  if (turnInfo) {
+    const err = new Error(`claude CLI session reached its turn budget (${turnMax} turns) and was stopped`);
+    err.code = "CLI_TURNS"; err.turns = msgUsage.size; err.turnMax = turnMax; err.lastTool = turnInfo.lastTool; err.usage = streamUsage(); err.toolUses = [...toolUses.values()];
+    throw err;
+  }
+  if (ctxInfo) {
+    const err = new Error(`claude CLI session reached ${ctxInfo.context} context tokens (ceiling ${contextMax}) after ${msgUsage.size} turn(s) and was stopped`);
+    err.code = "CLI_CONTEXT"; err.context = ctxInfo.context; err.contextMax = contextMax; err.turns = msgUsage.size; err.lastTool = ctxInfo.lastTool;
+    err.usage = streamUsage(); err.toolUses = [...toolUses.values()];
+    throw err;
+  }
   if (idleInfo) {
     const mins = Math.round((idleInfo.idleMs / 60000) * 10) / 10;
-    const err = new Error(`claude CLI had no stream activity for ${mins} min and was killed (idle). Last tool: ${idleInfo.lastTool ? `${idleInfo.lastTool.name} ${idleInfo.lastTool.input}` : "none"}. Live children: ${idleInfo.children.map((c) => `${c.pid}:${c.cmd}`).join("; ") || "none"}`);
+    const err = new Error(`claude CLI had no stream activity for ${mins} min and was killed (idle${idleInfo.extended ? ", after the busy extension" : ""}). Last tool: ${idleInfo.lastTool ? `${idleInfo.lastTool.name} ${idleInfo.lastTool.input}` : "none"}. Live children: ${idleInfo.children.map((c) => `${c.pid}:${c.cmd}`).join("; ") || "none"}`);
     err.code = "CLI_IDLE"; err.lastTool = idleInfo.lastTool; err.children = idleInfo.children; err.idleMs = idleInfo.idleMs;
+    err.extended = idleInfo.extended; err.heavyQueue = idleInfo.heavyQueue;
     throw err;
   }
-  return runCliBackend({ ...rest, spawnFn: () => collected });
+  const r = runCliBackend({ ...rest, spawnFn: () => collected });
+  // #4395: the session baseline is the first assistant turn's context (system prompt, tools, instructions, first prompt).
+  const first = msgUsage.values().next().value;
+  if (stream && toolUses.size && r && typeof r === "object") r.toolUses = [...toolUses.values()];
+  if (first && r && typeof r === "object") r.baselineTokens = toFiniteUsageNumber(first.input_tokens) + toFiniteUsageNumber(first.cache_read_input_tokens) + toFiniteUsageNumber(first.cache_creation_input_tokens);
+  return r;
 }
 
 // ---------------------------------------------------------------------------

package/bin/stats/aggregate.mjs

@@ -5,7 +5,9 @@
  *
  * Input record model (every source maps onto it; a missing field is null and degrades to "n/a"):
  *   run   { source, repo, version, issue, run, finished, hydrated, usageEvents, reason, code, remediated,
- *           startTs, endTs, wallMs, phases: { <id>: { cr, out, usd, ms, attempts } } }
+ *           startTs, endTs, wallMs, phases: { <id>: { cr, out, usd, ms, attempts } },
+ *           builderAttempts: [{ attempt, trigger, cost_usd }] (#4362; trigger null before the field existed),
+ *           pitfallsMatched (#4375: pitfalls in the context pack matching the issue's files; null when unknown, local logs only) }
  *   event { repo, version, issue, pr, ts, event, ...payload }          (FORGE:TELEMETRY gate/review events)
  *   issue { repo, number, isPr, createdAt, closedAt, labels: [name], authorType }
  *
@@ -14,6 +16,8 @@
  * per-phase mean divides by n (a run that skipped a phase counts 0).
  */
 
+import { REWORK_TRIGGERS, firstPassOf } from "../lean/fixround.mjs";
+
 export const DEFAULT_MIN_N = 10;
 export const UNKNOWN = "unknown";
 
@@ -113,6 +117,35 @@ function flowSection(runs) {
   };
 }
 
+/**
+ * #4362: builder attempts by trigger (all, and rework only) and the first-pass rate. An attempt without a trigger
+ * (written before the field) counts as "unknown" rework, never dropped; a run without one is unknown for first pass.
+ */
+function reworkSection(runs) {
+  const attempts = {}, byTrigger = {};
+  let n = 0, usd = 0, firstPass = 0, measured = 0, unknown = 0;
+  const split = { with: { firstPass: 0, n: 0 }, without: { firstPass: 0, n: 0 } }; // #4375: by matching pitfalls in the pack
+  for (const r of runs) {
+    const list = Array.isArray(r.builderAttempts) ? r.builderAttempts : [];
+    for (const a of list) {
+      const t = a?.trigger || UNKNOWN, c = isNum(a?.cost_usd) ? a.cost_usd : 0;
+      const all = (attempts[t] ??= { n: 0, usd: 0 });
+      all.n++; all.usd += c;
+      if (t !== UNKNOWN && !REWORK_TRIGGERS.includes(t)) continue;
+      const d = (byTrigger[t] ??= { n: 0, usd: 0 });
+      d.n++; d.usd += c; n++; usd += c;
+    }
+    const fp = firstPassOf(list);
+    // unknown: untagged attempts or no attempt list (an older cache); a run that never reached the build is not a lane here
+    if (fp == null) { if (!Array.isArray(r.builderAttempts) || list.some((a) => !a?.trigger)) unknown++; continue; }
+    measured++;
+    if (fp) firstPass++;
+    if (Number.isInteger(r.pitfallsMatched)) { const s = split[r.pitfallsMatched > 0 ? "with" : "without"]; s.n++; if (fp) s.firstPass++; }
+  }
+  const firstPassByPitfalls = Object.fromEntries(Object.entries(split).map(([k, v]) => [k, { rate: ratio(v.firstPass, v.n), ...v }]));
+  return { rework: { n, usd, byTrigger, attempts }, firstPass: { rate: ratio(firstPass, measured), firstPass, n: measured, unknown }, firstPassByPitfalls };
+}
+
 function funnelSection(events, issues) {
   const findings = events.filter((e) => e.event === "finding_disposition");
   const reviews = new Set([...events.filter((e) => e.event === "review_panel"), ...findings]
@@ -217,7 +250,8 @@ export function aggregate({ runs = [], events = [], issues = [] } = {}, opts = {
   let groups = [...keys.values()].map(({ version, repo }) => {
     const sel = (list) => list.filter((x) => x.version === version && x.repo === repo);
     const g = { version, repo, cost: costSection(sel(counted)), time: timeSection(sel(counted)), flow: flowSection(sel(counted)),
-      funnel: funnelSection(sel(evs), sel(iss)), gates: gatesSection(sel(evs)), issueFlow: null };
+      funnel: funnelSection(sel(evs), sel(iss)), gates: gatesSection(sel(evs)), issueFlow: null,
+      ...reworkSection(sel(counted)) };
     g.issueFlow = issueFlowSection(sel(iss), g.funnel.introduced);
     g.n = g.flow.n;
     g.lowN = g.n < minN;
@@ -233,3 +267,54 @@ export function aggregate({ runs = [], events = [], issues = [] } = {}, opts = {
   if (opts.sinceVersion) groups = groups.filter((g) => g.version !== UNKNOWN && compareVersions(g.version, opts.sinceVersion) >= 0);
   return { groups, excluded, minN };
 }
+
+/** forge#4354: fail-soft alert thresholds (forge.yaml `stats.alerts.*`). Percentages are 0..100. */
+export const DEFAULT_ALERTS = { window: 50, minLanes: 10, depsFailedPct: 20, deferredPct: 30, toolchainWarningPct: 50, outcomeShareFactor: 2 };
+
+/**
+ * Rates of fail-soft events over the last `window` lanes of `repo` (lanes from local-source `readLanes`), ordered by start
+ * time. Nothing below `minLanes`. Rules: DEPS_PREPARED failed per ecosystem, deferred-to-ci, each TOOLCHAIN_WARNING text,
+ * and outcome codes (except `completed`) whose share doubled against the previous window. Pure: no I/O, no clock.
+ */
+export function computeAlerts(lanes = [], opts = {}) {
+  const c = { ...DEFAULT_ALERTS };
+  for (const k of Object.keys(DEFAULT_ALERTS)) if (isNum(opts[k]) && opts[k] > 0) c[k] = opts[k];
+  const all = (lanes ?? []).filter((l) => l && (opts.repo == null || l.repo === opts.repo))
+    .map((l, i) => ({ l, i, t: toMs(l.startTs) ?? -Infinity }))
+    .sort((a, b) => a.t - b.t || a.i - b.i).map((x) => x.l);
+  const win = all.slice(-c.window);
+  if (win.length < c.minLanes) return [];
+  const prev = all.slice(Math.max(0, all.length - 2 * c.window), all.length - win.length);
+  const out = [];
+  const add = (event, count, sample, threshold, example, extra = {}) => out.push({ event, rate: count / sample, count, sample, threshold, example, ...extra });
+  const ecos = [...new Set(win.flatMap((l) => l.deps.map((d) => d.eco ?? "unknown")))].sort();
+  for (const eco of ecos) {
+    const used = win.filter((l) => l.deps.some((d) => (d.eco ?? "unknown") === eco));
+    const failed = used.filter((l) => l.deps.some((d) => (d.eco ?? "unknown") === eco && d.status === "failed"));
+    if (failed.length / used.length > c.depsFailedPct / 100) {
+      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);
+    }
+  }
+  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]);
+  const warnings = [...new Set(win.flatMap((l) => l.toolchainWarnings))].sort();
+  for (const w of warnings) {
+    const hit = win.filter((l) => l.toolchainWarnings.includes(w)).length;
+    if (hit / win.length > c.toolchainWarningPct / 100) add("TOOLCHAIN_WARNING", hit, win.length, c.toolchainWarningPct / 100, w);
+  }
+  const coded = (list) => list.filter((l) => l.code != null);
+  const cw = coded(win), cp = coded(prev);
+  if (cw.length && prev.length >= c.minLanes && cp.length) {
+    const share = (list, code) => list.filter((l) => l.code === code).length / list.length;
+    for (const code of [...new Set(cw.map((l) => l.code))].filter((x) => x !== "completed").sort()) {
+      const hits = cw.filter((l) => l.code === code);
+      const now = share(cw, code), before = share(cp, code);
+      if (hits.length >= 2 && now >= c.outcomeShareFactor * before) {
+        const ex = hits[hits.length - 1];
+        add(`outcome ${code}`, hits.length, cw.length, c.outcomeShareFactor, `#${ex.issue} ${ex.reason ?? code}`, { prevRate: before });
+      }
+    }
+  }
+  return out;
+}

package/bin/stats/efficiency.mjs

@@ -0,0 +1,335 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4402: batch efficiency and accuracy metrics, per batch and over trailing windows. No model, no clock (`now` is
+ * passed in), no network except the injected `gh` for merged issues' bodies, labels and FORGE:PROBE comments.
+ *
+ * Sources: the batch dirs (`~/.forge/batches/<id>/`: plan.json, report.json rows, log.jsonl settle times) and the run
+ * logs (`~/.forge/runs/<issue>.jsonl`). Batch membership exists only locally, and GitHub `phase_attempt` records keep one
+ * run per issue, so lane reruns would be lost there.
+ *
+ * Cohort: a batch's rows. A merged issue's metrics cover every RUN_START..RUN_TERMINAL slice of its run log that started
+ * at or before its settle time (the latest log.jsonl row for it), including earlier batches and ad-hoc runs: the cost to
+ * merge. Attempt cost is `cost_usd_delta`, else `cost_usd` (#4407; logs before the delta overstate resumed sessions).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { citesFileLine } from "../lean/fixround.mjs";
+import { laneSize, SIZES } from "../lean/budget.mjs";
+import { probeResultOf } from "../lean/probe.mjs";
+import { listBatches } from "../lean/batch.mjs";
+import { isTrustedComment } from "../engine/phases.mjs";
+import { noComments } from "../lean/render.mjs";
+import { readLog, runLogPath } from "../engine/runlog.mjs";
+
+export const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+export const RETRY_CAUSES = Object.freeze(["env", "engine", "code", "review", "unknown"]);
+
+/** Builder (implement) attempt trigger -> retry cause; null = not a retry. Every fixround.mjs TRIGGERS entry is listed. */
+export const TRIGGER_CAUSE = Object.freeze({
+  plan: null, build: null, verifier: null,
+  ci_unavailable: "env",
+  timeout_restart: "engine", context_restart: "engine", budget_wrapup: "engine", recovery: "engine",
+  precheck: "code", structure: "code", docs: "code", enumerating: "code", sequence: "code", post_merge: "code", duplicate: "code", ci_red: "code", conformance: "code",
+  merge_ci: "code", block_correction: "code", contract_correction: "code",
+  review: "review",
+});
+
+const CODE_CAUSE = [[/^env\./, "env"], [/^(engine|run|followup|base|dependency)\./, "engine"],
+  [/^(ci|conformance|precheck|budget|builder|contract)\./, "code"], [/^review\./, "review"]];
+/** A lane rerun's cause from the RUN_TERMINAL code of the slice it replaced. */
+export function codeCause(code) {
+  const c = String(code ?? "");
+  for (const [re, cause] of CODE_CAUSE) if (re.test(c)) return cause;
+  return "unknown";
+}
+
+const num = (x) => (typeof x === "number" && Number.isFinite(x) ? x : null);
+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);
+
+function parseLog(text) {
+  const out = [];
+  for (const line of String(text ?? "").split("\n")) {
+    if (!line.trim()) continue;
+    try { const e = JSON.parse(line); if (e && typeof e === "object") out.push(e); } catch { /* torn line */ }
+  }
+  return out;
+}
+
+export const LANE_SHAPES = Object.freeze(["light", "upgraded", "full"]);
+
+/** Every RUN_START..RUN_TERMINAL slice of one run log (all of them, not only the last). `shape` (#4452): light (LIGHT_DONE), upgraded (LIGHT_UPGRADE) or full. */
+export function issueSlices(events) {
+  const out = [];
+  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 (!cur) continue;
+    if (e.event === "LIGHT_DONE") cur.shape = "light";
+    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),
+        ...(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 };
+    }
+  }
+  return out;
+}
+
+/** Retries of one slice's builder attempts by cause. Legacy (no trigger anywhere): implement attempts beyond plan + build are unknown. */
+export function sliceRetries(slice) {
+  const out = Object.fromEntries(RETRY_CAUSES.map((c) => [c, 0]));
+  const impl = (slice?.attempts ?? []).filter((a) => a.phase === "implement");
+  if (impl.length && impl.every((a) => !a.trigger)) { out.unknown += Math.max(0, impl.length - 2); return out; }
+  for (const a of impl) {
+    if (!a.trigger) { out.unknown++; continue; }
+    const c = Object.hasOwn(TRIGGER_CAUSE, a.trigger) ? TRIGGER_CAUSE[a.trigger] : "unknown";
+    if (c) out[c]++;
+  }
+  return out;
+}
+
+const HEAD_RE = /^[ \t]{0,3}(?:#{1,6}[ \t]+(.+?)[ \t]*#*[ \t]*$|\*\*([^*\n]+)\*\*)/gm;
+/** Issue-quality tag from the body: root cause, file:line and fix design present (full), some (partial) or none. */
+export function issueQuality(body) {
+  const t = noComments(body);
+  const heads = [...t.matchAll(HEAD_RE)].map((m) => m[1] ?? m[2] ?? "");
+  const rootCause = heads.some((h) => /root cause/i.test(h));
+  const fileLine = citesFileLine([t]);
+  const fixDesign = heads.some((h) => /fix|design|approach|proposal/i.test(h));
+  const k = [rootCause, fileLine, fixDesign].filter(Boolean).length;
+  return { rootCause, fileLine, fixDesign, tag: k === 3 ? "full" : k ? "partial" : "none" };
+}
+
+/** pass | fail | pending | unprobed: trusted FORGE:PROBE records within 7 days of the first one (promotion, #4399). */
+export function acceptanceOf(comments, now) {
+  const recs = (Array.isArray(comments) ? comments : []).filter((c) => isTrustedComment(c))
+    .map((c) => ({ t: Date.parse(c.created_at ?? ""), res: probeResultOf(c.body) })).filter((x) => x.res && Number.isFinite(x.t)).sort((a, b) => a.t - b.t);
+  if (!recs.length) return "unprobed";
+  const t0 = recs[0].t;
+  if (now - t0 < WEEK_MS) return "pending";
+  return recs.filter((x) => x.t <= t0 + WEEK_MS).every((x) => x.res.result === "pass") ? "pass" : "fail";
+}
+
+/** Issue body, labels and comments over the injected gh (the calls of bin/lean/probe.mjs readIssue). */
+export async function fetchIssue(gh, repo, n) {
+  const iss = JSON.parse(String(await gh(["api", `repos/${repo}/issues/${n}`])));
+  const raw = String(await gh(["api", `repos/${repo}/issues/${n}/comments`, "--paginate", "--jq", ".[]"]));
+  const comments = raw.split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l));
+  return { body: iss?.body ?? "", labels: (Array.isArray(iss?.labels) ? iss.labels : []).map((l) => l?.name ?? l), comments };
+}
+
+/** #4410: a lane's implement tool calls per turn and re-reads, over the attempts that carry tool data; null when none. */
+function laneTools(impl) {
+  const xs = impl.filter((a) => a.calls != null && a.toolTurns > 0);
+  if (!xs.length) return null;
+  return { per_turn: r(sum(xs.map((a) => a.calls)) / sum(xs.map((a) => a.toolTurns)), 100), rereads: sum(xs.map((a) => a.rereads ?? 0)) };
+}
+const median = (xs) => {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b), h = Math.floor(s.length / 2);
+  return s.length % 2 ? s[h] : r((s[h - 1] + s[h]) / 2, 100);
+};
+
+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) };
+};
+
+/**
+ * The metrics of one cohort. `entries`: [{row, settleAt}] (a batch row and its settle time, ISO or null = unbounded);
+ * `logs`: issue -> run-log events; `issues`: issue -> {body, labels, comments} or null when gh was not available.
+ */
+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));
+  // #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) {
+    if (!Number.isSafeInteger(row?.issue)) continue;
+    for (const s of inScope(row, settleAt)) { const g = shapes[s.shape] ?? shapes.full; g.n++; g.cost_usd += sum(s.attempts.map((a) => a.cost)); }
+  }
+  for (const g of Object.values(shapes)) g.cost_usd = r(g.cost_usd, 1e6);
+  const lanes = { ...shapes, upgrade_rate: r(per(shapes.upgraded.n, shapes.light.n + shapes.upgraded.n)) };
+  for (const { row, settleAt } of entries) {
+    if (row?.outcome !== "merged") continue;
+    const slices = inScope(row, settleAt);
+    const atts = slices.flatMap((s) => s.attempts), impl = atts.filter((a) => a.phase === "implement");
+    const retries = Object.fromEntries(RETRY_CAUSES.map((c) => [c, 0]));
+    for (const s of slices) for (const [c, k] of Object.entries(sliceRetries(s))) retries[c] += k;
+    for (const s of slices.slice(0, -1)) retries[codeCause(s.terminal?.code)]++; // lane reruns
+    const info = issues?.get(row.issue) ?? null;
+    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 });
+  }
+  const all = group(merged);
+  const bySize = {};
+  for (const s of [...SIZES, "unknown"]) { const xs = merged.filter((m) => m.size === s); if (xs.length) bySize[s] = group(xs); }
+  const byModel = {};
+  for (const m of merged) {
+    for (const a of m.impl) {
+      const k = a.model ?? "unknown", g = (byModel[k] ??= { merges: new Set(), attempts: 0, turns: 0, cache: 0, cost: 0 });
+      g.merges.add(m.issue); g.attempts++; g.turns += a.turns ?? 0; g.cache += a.cacheRead ?? 0; g.cost += a.cost ?? 0;
+    }
+  }
+  const retries = Object.fromEntries(RETRY_CAUSES.map((c) => [c, sum(merged.map((m) => m.retries[c]))]));
+  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
+  const noAction = {};
+  for (const { row } of entries) {
+    const kind = row?.prefilter?.parked ? String(row.prefilter.kind ?? "parked")
+      : row?.code === "builder.blocked" && /^Builder is blocked \(promotion\)/.test(String(row.detail ?? "")) ? "blocked-promotion" : null;
+    if (!kind) continue;
+    const g = (noAction[kind] ??= { n: 0, cost_usd: 0, issues: [] });
+    g.n++; g.cost_usd += num(row.cost_usd) ?? 0; g.issues.push(row.issue);
+  }
+  let quality = null, acceptance = null;
+  if (issues) {
+    quality = {};
+    for (const t of ["full", "partial", "none"]) {
+      const xs = merged.filter((m) => m.info && issueQuality(m.info.body).tag === t);
+      quality[t] = group(xs);
+    }
+    acceptance = { pass: 0, fail: 0, pending: 0, unprobed: 0 };
+    for (const m of merged) if (m.info) acceptance[acceptanceOf(m.info.comments, now)]++;
+    acceptance.probed = acceptance.pass + acceptance.fail + acceptance.pending;
+    acceptance.pass_rate = r(per(acceptance.pass, acceptance.pass + acceptance.fail));
+  }
+  return {
+    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)),
+    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) }])),
+    retries: { total, per_merge: r(per(total, merged.length), 100), by_cause: retries, lane_reruns: sum(merged.map((m) => Math.max(0, m.slices - 1))) },
+    no_action: { lanes: sum(Object.values(noAction).map((g) => g.n)), cost_usd: r(sum(Object.values(noAction).map((g) => g.cost_usd)), 1e6),
+      by_kind: Object.fromEntries(Object.entries(noAction).map(([k, g]) => [k, { ...g, cost_usd: r(g.cost_usd, 1e6) }])) },
+    quality, acceptance, lanes,
+    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 } : {}) })),
+    notes,
+  };
+}
+
+const readJson = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
+/** #4432: the repo's run log (legacy `<n>.jsonl` only through readLog's fallback); null repo = the legacy file. */
+const readEvents = (runsDir, n, repo = null) => {
+  try { return readLog(runsDir, n, { repo }); } catch { /* a corrupt line: parse the file leniently */ }
+  try { return parseLog(readFileSync(runLogPath(runsDir, n, repo), "utf8")); } catch { return []; }
+};
+const readLogRows = (dir) => { try { return parseLog(readFileSync(join(dir, "log.jsonl"), "utf8")); } catch { return []; } };
+
+/** report.json rows, else state.json results (object or entry list). */
+function batchRows(dir) {
+  const rep = readJson(join(dir, "report.json"));
+  if (Array.isArray(rep?.rows)) return rep.rows;
+  const res = readJson(join(dir, "state.json"))?.results;
+  const vals = Array.isArray(res) ? res.map((x) => (Array.isArray(x) ? x[1] : x)) : res && typeof res === "object" ? Object.values(res) : [];
+  return vals.filter((x) => x && Number.isSafeInteger(x.issue));
+}
+
+/** Latest log.jsonl `at` per issue. */
+function settleTimes(logRows) {
+  const at = new Map();
+  for (const l of logRows) if (Number.isSafeInteger(l?.issue) && typeof l.at === "string" && l.at > (at.get(l.issue) ?? "")) at.set(l.issue, l.at);
+  return at;
+}
+
+async function computeScope({ entries, runsDir, repo, gh, now }) {
+  const logs = new Map(entries.map(({ row }) => [row.issue, readEvents(runsDir, row.issue, repo)]));
+  const notes = [];
+  let issues = null;
+  const mergedIssues = [...new Set(entries.filter(({ row }) => row.outcome === "merged").map(({ row }) => row.issue))];
+  if (!gh || !repo) notes.push("issue quality and acceptance: no gh/repo");
+  else {
+    issues = new Map();
+    for (const n of mergedIssues) {
+      try { issues.set(n, await fetchIssue(gh, repo, n)); } catch (e) {
+        issues = null; notes.push(`issue quality and acceptance: gh failed (${String(e?.message ?? e).split("\n")[0].slice(0, 160)})`); break;
+      }
+    }
+  }
+  return efficiencyMetrics({ entries, logs, issues, repo, now, notes });
+}
+
+/** One batch. `rows`/`logRows` override the files (the batch report passes its in-memory rows). */
+export async function batchEfficiency({ batchDir, runsDir, repo = null, gh = null, now = Date.now(), rows = null, logRows = null }) {
+  const plan = readJson(join(batchDir, "plan.json")) ?? {};
+  const rs = Array.isArray(rows) ? rows : batchRows(batchDir);
+  const at = settleTimes(Array.isArray(logRows) ? logRows : readLogRows(batchDir));
+  const entries = rs.filter((x) => Number.isSafeInteger(x?.issue)).map((row) => ({ row, settleAt: at.get(row.issue) ?? null }));
+  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] }) {
+  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);
+  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 })) };
+  }
+  return out;
+}
+
+export const windowLabel = (ms) => `${Math.round(ms / 86400000)}d`;
+/** "7d,30d" -> [ms]; throws on anything else. */
+export function parseWindows(s) {
+  const out = String(s ?? "").split(",").map((x) => x.trim()).filter(Boolean).map((x) => {
+    const m = /^(\d+)d$/.exec(x);
+    if (!m || Number(m[1]) < 1) throw new Error(`--window must be a comma list of Nd (e.g. 7d,30d): ${s}`);
+    return Number(m[1]) * 86400000;
+  });
+  if (!out.length) throw new Error("--window needs at least one Nd");
+  return out;
+}
+
+const f = (x, d = 2) => (num(x) == null ? "n/a" : x.toFixed(d));
+const usd = (x) => (num(x) == null ? "n/a" : `$${x.toFixed(2)}`);
+const int = (x) => (num(x) == null ? "n/a" : String(Math.round(x)));
+const g1 = (g) => `n=${g.n} ${usd(g.usd_per_merge)}/merge turns/merge ${f(g.turns_per_merge, 1)} context/turn ${int(g.context_per_turn)}`;
+
+/** The report lines of one scope (the batch report prints them unlabelled). */
+export function formatEfficiencyLines(m, label = "") {
+  const lines = [`efficiency${label ? ` (${label})` : ""}: merged ${m.merged}, ${usd(m.usd_per_merge)}/merge (implement ${usd(m.implement_usd)}, review ${usd(m.review_usd)}), turns/merge ${f(m.turns_per_merge, 1)}, context/turn ${int(m.context_per_turn)}`];
+  const sizes = Object.entries(m.by_size ?? {});
+  lines.push(`efficiency by size: ${sizes.length ? sizes.map(([s, g]) => `${s} ${g1(g)}`).join("; ") : "n/a"}`);
+  const models = Object.entries(m.by_model ?? {});
+  lines.push(`efficiency by model: ${models.length ? models.map(([k, g]) => `${k} n=${g.merges} ${usd(g.usd_per_merge)}/merge turns/merge ${f(g.turns_per_merge, 1)} context/turn ${int(g.context_per_turn)}`).join("; ") : "n/a"}`);
+  const rc = m.retries?.by_cause ?? {};
+  lines.push(`retries/merge ${f(m.retries?.per_merge)} (${RETRY_CAUSES.map((c) => `${c} ${rc[c] ?? 0}`).join(", ")}; lane reruns ${m.retries?.lane_reruns ?? 0})`);
+  const kinds = Object.entries(m.no_action?.by_kind ?? {});
+  lines.push(`no action: ${m.no_action?.lanes ?? 0} lanes, ${usd(m.no_action?.cost_usd ?? 0)}${kinds.length ? ` (${kinds.map(([k, g]) => `${k} ${g.n}`).join(", ")})` : ""}`);
+  const note = (m.notes ?? []).find((x) => /^issue quality/.test(x));
+  lines.push(m.quality ? `issue quality: ${["full", "partial", "none"].map((t) => `${t} ${g1(m.quality[t])}`).join("; ")}` : `issue quality: n/a${note ? ` (${note.replace(/^issue quality and acceptance: /, "")})` : ""}`);
+  const a = m.acceptance;
+  lines.push(a ? `acceptance (7d after promotion): pass ${a.pass}/${a.pass + a.fail}${a.pass_rate == null ? "" : ` (${Math.round(a.pass_rate * 100)}%)`}, pending ${a.pending}, unprobed ${a.unprobed}`
+    : "acceptance (7d after promotion): n/a");
+  lines.push(`tools: calls/turn p50 ${f(m.tool_calls_per_turn_p50)}, re-reads (>=3x same path)/merge ${f(m.rereads_per_merge)}`); // #4410
+  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");
+  return lines;
+}