forgedock 1.16.2 → 1.18.0

package/bin/hooks/pre-tool-use.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "module";
 import { existsSync } from "fs";
+import { spawnSync } from "child_process";
 import { dirname, join, resolve as resolvePath } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 const _require = createRequire(import.meta.url);
@@ -115,6 +116,21 @@ async function getInvariants() {
  *    starting Claude Code (operator-set only — same process.env semantics as
  *    the gist guard above).
  *
+ * 9. Main-checkout mutation guard (issue #3650) — enforced by default
+ *    Enforced (exit 2) unless FORGE_ENFORCE_MAIN_CHECKOUT_GIT=0, which downgrades it
+ *    to a stderr warning (#3873). Ref-only verbs are narrowed: `git branch -d/-D/-m/-f`
+ *    is denied only for the branch checked out in the target dir, and
+ *    `git restore --staged` (index only) is allowed.
+ *    It denies `git checkout|switch|stash|merge`, `git reset --hard`, and
+ *    `gh pr checkout` when the shell's cwd is the main (non-worktree) checkout
+ *    (`git rev-parse --git-dir` equals `--git-common-dir`). Pipeline workers and
+ *    reviewers share that tree with the operator; mutating it races with them.
+ *    Read-only git, `git checkout -b`, `git worktree ...`, and anything in a
+ *    linked worktree stay allowed. Fails open when the repo cannot be resolved,
+ *    and treats `git -C <dir>`, `--git-dir`, `--work-tree` and a leading `cd` as
+ *    indeterminate (allowed). Override: FORGE_ALLOW_MAIN_CHECKOUT_GIT=1 in the
+ *    shell environment (operator-set only).
+ *
  * Rules 1-4 and 6 only apply inside a ForgeDock-managed directory (a directory
  * with a `forge.yaml` or `.forgedock` marker) — see `isForgeDockManagedCwd()`
  * (issue #1591). The hook installs into the user's global
@@ -566,6 +582,20 @@ async function main() {
     return;
   }
 
+  // --- Rule 9: Main-checkout mutation guard (issue #3650) ---
+  // Deliberately BEFORE the managed-cwd gate: pipeline workers run with cwd = a linked worktree (no
+  // forge.yaml), and `git -C <main> ...` from there is the case this rule exists for.
+  const mainCheckoutViolation = checkMainCheckoutMutation(command);
+  if (mainCheckoutViolation) {
+    if (process.env.FORGE_ENFORCE_MAIN_CHECKOUT_GIT !== "0") {
+      process.stderr.write(mainCheckoutViolation);
+      process.exit(2);
+      return;
+    }
+    // Advisory only when the operator opts out with FORGE_ENFORCE_MAIN_CHECKOUT_GIT=0 (#3873).
+    process.stderr.write("WARNING (advisory, not blocked): " + mainCheckoutViolation.replace(/^BLOCKED: /, ""));
+  }
+
   // Only enforce Rules 1-4 and 6 inside a ForgeDock-managed project — this hook
   // installs globally (~/.claude/settings.json), so without this guard those
   // rules would fire in every unrelated repo on the machine (issue #1591).
@@ -1233,6 +1263,196 @@ function checkTempPathStaging(command) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Rule 9: Main-checkout mutation guard (issue #3650)
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify one command segment as a main-checkout mutation.
+ *
+ * The option tables live INSIDE the function: `main()` runs at module top via
+ * `await`, before module-level `const`s declared further down are initialised,
+ * so a module-level table throws (TDZ) and the hook fails open.
+ *
+ * @param {string[]} tokens
+ * @param {number} [depth] wrapper-unwrap depth (bounded)
+ * @returns {{name: string, dir: string|null}|null} offender and the `-C` dir it targets, or null
+ */
+function mutatingGitCommand(tokens, depth = 0) {
+  // Strip grouping/compound prefixes: `(git x)`, `{ git x; }`, `then git x`, `do git x`, `! git x`.
+  tokens = tokens.slice();
+  for (;;) {
+    if (/^[({]+$/.test(tokens[0] || "") || ["then", "do", "else", "elif", "!", "if", "while", "until"].includes(tokens[0])) tokens.shift();
+    else if (/^[({]+[^({]/.test(tokens[0] || "")) tokens[0] = tokens[0].replace(/^[({]+/, "");
+    else break;
+  }
+  const valueOpts = new Set(["-c", "--exec-path", "--namespace", "--super-prefix", "--config-env"]);
+  let i = 0;
+  // Skip leading env assignments (`FOO=1 git ...`) and transparent wrappers.
+  for (;;) {
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+    const w = String(tokens[i] || "").replace(/^.*\//, "");
+    if (["sudo", "env", "command", "exec", "nice", "nohup", "time", "xargs", "builtin"].includes(w)) {
+      i++;
+      while (i < tokens.length && (tokens[i].startsWith("-") || /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))) i++;
+      continue;
+    }
+    if (["bash", "sh", "zsh", "dash"].includes(w) || w === "eval") {
+      if (depth >= 3) return null;
+      const k = w === "eval" ? i + 1 : tokens.findIndex((t, n) => n > i && /^-[a-z]*c$/.test(t)) + 1;
+      if (k <= i || k >= tokens.length) return null;
+      const inner = w === "eval" ? tokens.slice(k).join(" ") : tokens[k];
+      // Every hit of the payload, not just the first (#3920): an allowed ref-only segment (`git branch -d other`)
+      // must not mask a later mutating one. The caller decides per hit.
+      const hits = [];
+      for (const seg of extractCommandSegments(inner)) hits.push(...mutatingGitHits(seg, depth + 1));
+      return hits.length ? { name: hits[0].name, dir: hits[0].dir, hits } : null;
+    }
+    break;
+  }
+  const cmd = String(tokens[i] || "").replace(/^.*\//, "");
+  if (cmd === "gh") {
+    return tokens[i + 1] === "pr" && tokens[i + 2] === "checkout" ? { name: "gh pr checkout", dir: null } : null;
+  }
+  if (cmd !== "git") return null;
+  i++;
+  let dir = null;
+  while (i < tokens.length && tokens[i].startsWith("-")) {
+    if (tokens[i] === "-C") { dir = dir === null ? (tokens[i + 1] ?? ".") : resolvePath(dir, tokens[i + 1] ?? "."); i += 2; continue; }
+    const wt = /^--work-tree(?:=(.*))?$/.exec(tokens[i]);
+    if (wt) { const v = wt[1] ?? tokens[i + 1] ?? "."; dir = dir === null ? v : resolvePath(dir, v); i += wt[1] === undefined ? 2 : 1; continue; }
+    if (/^--git-dir(?:=.*)?$/.test(tokens[i])) { i += tokens[i].includes("=") ? 1 : 2; continue; } // work tree stays the cwd/-C
+    i += valueOpts.has(tokens[i]) ? 2 : 1;
+  }
+  const sub = tokens[i];
+  // Arguments end at a shell comment; options end at `--`.
+  let rest = tokens.slice(i + 1);
+  const hash = rest.findIndex((t) => t.startsWith("#"));
+  if (hash >= 0) rest = rest.slice(0, hash);
+  const dd = rest.indexOf("--");
+  const opts = dd >= 0 ? rest.slice(0, dd) : rest;
+  const hit = (name) => ({ name, dir });
+  switch (sub) {
+    case "checkout":
+      // Creating a new branch is the one sanctioned form (`git checkout -b`).
+      return opts.some((t) => t === "-b") ? null : hit("git checkout");
+    case "switch":
+      return opts.some((t) => t === "-c" || t === "--create") ? null : hit("git switch");
+    case "merge": case "pull": case "rebase": case "cherry-pick": case "revert": case "am":
+      return hit(`git ${sub}`);
+    case "restore": {
+      // `restore --staged` only rewrites the index (not the working tree); anything else (or --worktree/-W) does.
+      const flag = (long, ch) => opts.some((t) => t === long || (/^-[a-zA-Z]+$/.test(t) && t.includes(ch)));
+      return flag("--worktree", "W") || !flag("--staged", "S") ? hit("git restore") : null;
+    }
+    case "clean":
+      return opts.some((t) => t === "-n" || t === "--dry-run") ? null : hit("git clean");
+    case "branch": {
+      // Ref-only verbs: a hit only when the delete/move/force target is the branch checked out at the
+      // target dir (resolved by the caller). `-m <new>` with one positional renames the current branch.
+      if (!opts.some((t) => /^(?:-[a-zA-Z]*[fFmMdD][a-zA-Z]*|--force|--move|--delete)$/.test(t))) return null;
+      // Positionals after `--` count too (`git branch -m -- renamed` renames the checked-out branch, #3920).
+      const pos = [...opts.filter((t) => !t.startsWith("-")), ...(dd >= 0 ? rest.slice(dd + 1) : [])];
+      if (!pos.length) return null;
+      const moves = opts.some((t) => t === "--move" || /^-[a-zA-Z]*[mM][a-zA-Z]*$/.test(t));
+      const deletes = opts.some((t) => t === "--delete" || /^-[a-zA-Z]*[dD][a-zA-Z]*$/.test(t));
+      const branches = moves && !deletes ? (pos.length === 1 ? ["@current"] : [pos[0]]) : deletes ? pos : [pos[0]];
+      return { name: "git branch", dir, branches };
+    }
+    case "reset":
+      return opts.some((t) => t === "--hard" || t === "--merge" || t === "--keep") ? hit("git reset") : null;
+    case "stash": {
+      const action = opts.find((t) => !t.startsWith("-"));
+      return action === "list" || action === "show" ? null : hit("git stash");
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * All main-checkout mutation hits in one command segment, flattening `bash -c` / `eval` payloads (#3920).
+ * @param {string[]} tokens
+ * @param {number} [depth]
+ * @returns {Array<{name: string, dir: string|null, branches?: string[]}>}
+ */
+function mutatingGitHits(tokens, depth = 0) {
+  const h = mutatingGitCommand(tokens, depth);
+  if (!h) return [];
+  return h.hits ? h.hits : [h];
+}
+
+/**
+ * Is `cwd` the main (non-linked-worktree) checkout of a git repo?
+ * Fails closed-to-allow: any error or non-git dir returns false.
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function isMainCheckout(cwd) {
+  try {
+    const r = spawnSync(
+      "git",
+      ["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"],
+      { cwd, encoding: "utf-8", timeout: 5000 },
+    );
+    if (r.status !== 0) return false;
+    const [gitDir, commonDir] = String(r.stdout).trim().split(/\r?\n/);
+    if (!gitDir || !commonDir) return false;
+    return resolvePath(cwd, gitDir) === resolvePath(cwd, commonDir);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rule 9: deny mutating git/gh commands aimed at the main checkout.
+ * @param {string} command
+ * @returns {string|null} stderr message when denied, else null
+ */
+function checkMainCheckoutMutation(command) {
+  if (process.env.FORGE_ALLOW_MAIN_CHECKOUT_GIT === "1") return null;
+  if (!/\b(?:git|gh)\b/.test(command)) return null;
+  try {
+    let baseDir = process.cwd();
+    // Decide per segment: an allowed ref-only verb (`git branch -d other`) must not mask a later mutating segment.
+    for (const tokens of extractCommandSegments(command)) {
+      const head = tokens.slice();
+      while (head.length && (/^[({]+$/.test(head[0]) || ["then", "do", "else", "!"].includes(head[0]))) head.shift();
+      if (head.length && /^[({]+[^({]/.test(head[0])) head[0] = head[0].replace(/^[({]+/, "");
+      if (head[0] === "cd" || head[0] === "pushd") {
+        // Follow a literal target; a variable/substitution/`-` makes later segments' cwd indeterminate: allow those.
+        const t = head[1];
+        if (!t || /[$`~]/.test(t) || t === "-") break;
+        baseDir = resolvePath(baseDir, t);
+        continue;
+      }
+      for (const hit of mutatingGitHits(tokens)) {
+      const targetDir = hit.dir === null ? baseDir : resolvePath(baseDir, hit.dir);
+      if (!isMainCheckout(targetDir)) continue;
+      if (hit.branches) {
+        // Ref-only verb: only the checked-out branch matters; unresolvable (detached HEAD, error) = allow.
+        const cur = spawnSync("git", ["-C", targetDir, "branch", "--show-current"], { encoding: "utf-8", timeout: 5000 });
+        const current = cur.status === 0 ? String(cur.stdout).trim() : "";
+        if (!current || !hit.branches.some((b) => b === "@current" || b === current)) continue;
+      }
+      // Hook is global: only protect ForgeDock-managed main checkouts (issue #1591 scoping), never unrelated repos.
+      if (!existsSync(join(targetDir, "forge.yaml")) && !existsSync(join(targetDir, ".forgedock"))) continue;
+      return (
+        `BLOCKED: \`${hit.name}\` would mutate the main checkout (${targetDir}).\n` +
+        "The main checkout is shared with the operator and other agents. Work in a git worktree " +
+        "(`git worktree list`, `git worktree add`) and use `git -C <worktree> ...`, or read code with " +
+        "`git show <sha>:<path>`, `gh pr diff`, or `gh api`.\n" +
+        "Operator override: set FORGE_ALLOW_MAIN_CHECKOUT_GIT=1 in the shell before starting Claude Code " +
+        "(set FORGE_ENFORCE_MAIN_CHECKOUT_GIT=0 to make this advisory only).\n"
+      );
+      }
+    }
+    return null;
+  } catch {
+    return null; // fail open
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Rule 8: Dangerous `rm` target guard (issue #2856)
 //

package/bin/runner.mjs

@@ -74,6 +74,64 @@ export function withForgedockHome(env) {
   return env;
 }
 
+/** Expand a leading `~` and require an absolute result; anything else -> null. */
+function absoluteTmpRoot(value) {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (!v) return null;
+  const expanded = v === "~" || v.startsWith("~/") ? join(os.homedir(), v.slice(1)) : v;
+  return isAbsolute(expanded) ? expanded : null;
+}
+
+/**
+ * Root of the per-run scratch dirs (forge#3572). Precedence: forge.yaml `engine.tmp_root`
+ * (absolute or `~`-prefixed), else null when the operator exported their own
+ * CLAUDE_CODE_TMPDIR/TMPDIR (their choice is respected and never cleaned), else `~/.forge/tmp`.
+ * A null return means "operator-managed: leave the child env untouched".
+ *
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+export function resolveRunTmpRoot(cwd, env = process.env) {
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (existsSync(forgeYamlPath)) {
+      const configured = absoluteTmpRoot(parseForgeYaml(readFileSync(forgeYamlPath, "utf-8"))?.engine?.tmp_root);
+      if (configured) return configured;
+    }
+  } catch { /* unreadable config: fall through to the defaults */ }
+  if (env.CLAUDE_CODE_TMPDIR || env.TMPDIR) return null;
+  return join(os.homedir(), ".forge", "tmp");
+}
+
+/** `<root>/<issue>` for a numeric issue; null for an empty root or non-numeric issue (no path-escape, never the root). */
+export function runTmpDir(root, issue) {
+  const id = String(issue ?? "").trim();
+  return root && /^[0-9]+$/.test(id) ? join(root, id) : null;
+}
+
+/**
+ * Point TMPDIR and CLAUDE_CODE_TMPDIR at a per-run, disk-backed dir so venvs and Claude session data
+ * stay off a size-limited /tmp. No-op when the issue is unknown or the operator owns the tmp root.
+ * Best-effort: a failed mkdir leaves the env unchanged.
+ */
+export function withRunTmpdir(env, { issue, cwd = process.cwd() } = {}) {
+  const dir = runTmpDir(resolveRunTmpRoot(cwd, env), issue);
+  if (!dir) return env;
+  try {
+    mkdirSync(dir, { recursive: true });
+    env.TMPDIR = dir;
+    env.CLAUDE_CODE_TMPDIR = dir;
+  } catch { /* scratch stays on the inherited tmp */ }
+  return env;
+}
+
+/** First positional arg when it is an issue number (the phase arg convention), else null. */
+function issueFromArgs(args) {
+  const first = Array.isArray(args) ? args[0] : String(args ?? "").trim().split(/\s+/)[0];
+  return /^[0-9]+$/.test(String(first ?? "")) ? String(first) : null;
+}
+
 const DEFAULT_MODEL = "claude-sonnet-5";
 const DEFAULT_MAX_ITERATIONS = 50;
 const DEFAULT_MAX_TOKENS = 16384;
@@ -1410,7 +1468,7 @@ export function runCliBackend({
     // Mirrors the existing scrub in the `run_bash` tool handler below.
     // GH_TOKEN/GITHUB_TOKEN and all other env vars are intentionally left
     // intact — only the Anthropic key is removed.
-    const childEnv = withForgedockHome({ ...process.env });
+    const childEnv = withRunTmpdir(withForgedockHome({ ...process.env }), { issue: issueFromArgs(args), cwd });
     delete childEnv.ANTHROPIC_API_KEY;
 
     // No `shell` option (defaults to false): argv is passed as discrete,
@@ -1609,10 +1667,15 @@ export function runCliBackend({
     let parsedResult = null;
     let usage = null;
     let turns = null;
+    // forge#3696: envelope cost/duration per attempt (null when absent or non-finite).
+    let costUsd = null;
+    let durationMs = null;
     try {
       const parsed = JSON.parse(stdoutTrimmed);
       if (parsed && typeof parsed === "object") {
         if (Number.isFinite(parsed.num_turns)) turns = parsed.num_turns;
+        if (Number.isFinite(parsed.total_cost_usd)) costUsd = parsed.total_cost_usd;
+        if (Number.isFinite(parsed.duration_ms)) durationMs = parsed.duration_ms;
         parsedResult = typeof parsed.result === "string" ? parsed.result : null;
         if (parsed.usage && typeof parsed.usage === "object") {
           usage = {
@@ -1697,6 +1760,8 @@ export function runCliBackend({
       // and the envelope's turn count (null when absent), for runlog recording.
       cliModel: modelFlag,
       turns,
+      costUsd,
+      durationMs,
       backend: "cli",
       // forge#3521: the phase's final reply (the CLI envelope's `.result`), so
       // callers can read its structured `*_RESULT` block. Additive; "" when absent.
@@ -2179,9 +2244,10 @@ export function resolveBashShell() {
  * the loop catches and reports the error back to the model as an error result.
  *
  * @param {string} cwd
+ * @param {string|null} [runIssueNumber] - issue number scoping the per-run TMPDIR (forge#3572)
  * @returns {Record<string, (input: object) => string>}
  */
-export function getToolHandlers(cwd) {
+export function getToolHandlers(cwd, runIssueNumber = null) {
   return {
     read_file: ({ path }) => {
       if (!path) throw new Error("read_file requires a 'path'");
@@ -2201,7 +2267,7 @@ export function getToolHandlers(cwd) {
       // into the model loop, so a prompt-injection payload could otherwise issue
       // a run_bash command that exfiltrates the key. gh/git auth tokens
       // (GH_TOKEN/GITHUB_TOKEN) are intentionally left intact.
-      const childEnv = withForgedockHome({ ...process.env });
+      const childEnv = withRunTmpdir(withForgedockHome({ ...process.env }), { issue: runIssueNumber, cwd });
       delete childEnv.ANTHROPIC_API_KEY;
       // Run under bash when available so bash-style commands the model emits
       // (heredocs, scripts/*.sh, single-quote semantics) behave consistently
@@ -2641,7 +2707,7 @@ export async function runCommand(opts = {}) {
   // is a known Linux limitation at the OS level; closing it would require
   // a native module (e.g. prctl PR_SET_DUMPABLE) or process isolation.
   // See: issue #1370 for tracking this known limitation.
-  const handlers = getToolHandlers(cwd);
+  const handlers = getToolHandlers(cwd, issueFromArgs(args));
   const messages = [{ role: "user", content: userMessage }];
 
   // Accumulate token usage across all messages.create() calls in this run.

package/bin/stats/aggregate.mjs

@@ -0,0 +1,231 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Pure, source-agnostic aggregation for `forgedock stats` (forge#3835). No I/O, no clock, no model.
+ *
+ * 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 } } }
+ *   event { repo, version, issue, pr, ts, event, ...payload }          (FORGE:TELEMETRY gate/review events)
+ *   issue { repo, number, isPr, createdAt, closedAt, labels: [name], authorType }
+ *
+ * Counting rules reproduce scripts/cost-report.sh so both reports agree on the same logs: only finished runs
+ * count, hydrated runs and runs with no usage events are excluded, tokens are cache-read tokens, and the
+ * per-phase mean divides by n (a run that skipped a phase counts 0).
+ */
+
+export const DEFAULT_MIN_N = 10;
+export const UNKNOWN = "unknown";
+
+const PHASES = ["investigate", "build", "review", "remediate", "close"];
+const isNum = (x) => typeof x === "number" && Number.isFinite(x);
+const sum = (a) => a.reduce((s, x) => s + x, 0);
+const mean = (a) => (a.length ? sum(a) / a.length : null);
+
+/** p=50 is the median (average of the middle pair, as cost-report.sh); any other p is nearest-rank. */
+export function percentile(values, p) {
+  const v = values.filter(isNum).sort((a, b) => a - b);
+  if (!v.length) return null;
+  if (p === 50) return v.length % 2 ? v[(v.length - 1) / 2] : (v[v.length / 2 - 1] + v[v.length / 2]) / 2;
+  return v[Math.max(0, Math.ceil((v.length * p) / 100) - 1)];
+}
+
+/** Sort key for "1.16.1" / "1.16.1~": numeric parts, unparseable parts count as 0. */
+export function versionKey(v) {
+  return String(v).replace(/~$/, "").split(".").map((x) => (/^\d+$/.test(x) ? Number(x) : 0));
+}
+export function compareVersions(a, b) {
+  const x = versionKey(a); const y = versionKey(b);
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+/** releaseTimes: [{ v, t }] with t in epoch seconds. Latest release at or before `ms`, marked "~" (estimated). */
+export function estimateVersion(ms, releaseTimes) {
+  if (!isNum(ms)) return UNKNOWN;
+  let best = null;
+  for (const r of releaseTimes ?? []) if (r.t * 1000 <= ms && (!best || r.t > best.t)) best = r;
+  return best ? `${best.v}~` : UNKNOWN;
+}
+
+const toMs = (ts) => { const t = Date.parse(ts ?? ""); return Number.isNaN(t) ? null : t; };
+const ratio = (num, den) => (den > 0 ? num / den : null);
+const sub = (a, b) => (isNum(a) && isNum(b) ? a - b : null);
+
+function issueSource(i) {
+  if (i.labels.includes("review-finding")) return "review-finding";
+  return i.authorType === "Bot" ? "pipeline" : "human";
+}
+function closedKind(i) {
+  if (i.labels.includes("workflow:merged")) return "merged";
+  if (i.labels.includes("workflow:invalid") || i.labels.includes("invalid")) return "invalid";
+  if (i.labels.includes("duplicate")) return "duplicate";
+  return "other";
+}
+
+function costSection(runs) {
+  const n = runs.length;
+  const cr = runs.map((r) => sum(Object.values(r.phases).map((p) => p.cr ?? 0)));
+  const merged = runs.filter((r) => r.reason === "merged").length;
+  const usd = runs.map((r) => {
+    const v = Object.values(r.phases).map((p) => p.usd).filter(isNum);
+    return v.length ? sum(v) : null;
+  }).filter(isNum);
+  const perPhase = {};
+  for (const id of [...PHASES, ...new Set(runs.flatMap((r) => Object.keys(r.phases)).filter((p) => !PHASES.includes(p)))]) {
+    perPhase[id] = n ? sum(runs.map((r) => r.phases[id]?.cr ?? 0)) / n : null;
+  }
+  return {
+    n, cacheReadMean: mean(cr), cacheReadMedian: percentile(cr, 50), perPhase,
+    outputMean: n ? sum(runs.map((r) => sum(Object.values(r.phases).map((p) => p.out ?? 0)))) / n : null,
+    perMergedIssue: merged ? sum(cr) / merged : null,
+    usdN: usd.length, usdMean: mean(usd), usdTotal: usd.length ? sum(usd) : null,
+  };
+}
+
+function timeSection(runs) {
+  const phases = {};
+  const ids = new Set(runs.flatMap((r) => Object.keys(r.phases)));
+  for (const id of ids) {
+    const ms = runs.map((r) => r.phases[id]?.ms).filter((x) => isNum(x) && x > 0);
+    if (ms.length) phases[id] = { n: ms.length, p50: percentile(ms, 50), p90: percentile(ms, 90) };
+  }
+  const wall = runs.map((r) => r.wallMs).filter((x) => isNum(x) && x >= 0);
+  return { phases, wall: { n: wall.length, p50: percentile(wall, 50), p90: percentile(wall, 90) } };
+}
+
+function flowSection(runs) {
+  const n = runs.length;
+  const codes = {};
+  let coded = 0;
+  for (const r of runs) if (r.code) { codes[r.code] = (codes[r.code] ?? 0) + 1; coded++; }
+  const top = Object.entries(codes).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([code, count]) => ({ code, count, pct: count / coded }));
+  return {
+    n,
+    mergedPct: ratio(runs.filter((r) => r.reason === "merged").length, n),
+    needsHumanPct: ratio(runs.filter((r) => r.reason === "needs-human").length, n),
+    remediationPct: ratio(runs.filter((r) => r.remediated).length, n),
+    codesN: coded, codes: top,
+  };
+}
+
+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]
+    .map((e) => `${e.repo}#${e.pr ?? e.issue}`));
+  const bySeverity = {};
+  for (const f of findings) {
+    const s = String(f.severity ?? "unknown").toUpperCase();
+    const d = (bySeverity[s] ??= { total: 0, ISSUE: 0, NOTE: 0, INPR_FIX: 0, other: 0 });
+    d.total++;
+    if (f.disposition in d) d[f.disposition]++; else d.other++;
+  }
+  for (const d of Object.values(bySeverity)) d.perReview = reviews.size ? d.total / reviews.size : null;
+  const dispositions = { ISSUE: 0, NOTE: 0, INPR_FIX: 0 };
+  for (const f of findings) if (f.disposition in dispositions) dispositions[f.disposition]++;
+  return {
+    reviews: reviews.size, findings: findings.length, perReview: ratio(findings.length, reviews.size),
+    bySeverity, dispositions,
+    validated: issues.filter((i) => i.labels.includes("validated")).length,
+    falsePositive: issues.filter((i) => i.labels.includes("false-positive")).length,
+  };
+}
+
+function gatesSection(events) {
+  const of = (name) => events.filter((e) => e.event === name);
+  const acc = of("acceptance_gate"); const size = of("diff_size"); const ci = of("ci_gate"); const live = of("liveness");
+  const blocked = (list, fn) => ({ n: list.length, blocked: list.filter(fn).length, rate: ratio(list.filter(fn).length, list.length) });
+  const malformed = acc.filter((e) => Number(e.malformed) > 0);
+  const count = (list, key, val) => list.filter((e) => e[key] === val).length;
+  return {
+    acceptance: blocked(acc, (e) => Number(e.failed) > 0),
+    malformedRate: ratio(malformed.length, acc.length),
+    diffSize: { ...blocked(size, (e) => e.result === "OVER"), over: count(size, "result", "OVER"), cohesive: count(size, "result", "COHESIVE") },
+    ci: blocked(ci, (e) => e.result !== "PASS"),
+    liveness: blocked(live, (e) => e.decision === "DEFER" || e.decision === "EXHAUSTED"),
+  };
+}
+
+function issueFlowSection(issues) {
+  const real = issues.filter((i) => !i.isPr);
+  const created = {};
+  for (const i of real) { const s = issueSource(i); created[s] = (created[s] ?? 0) + 1; }
+  const closedIssues = real.filter((i) => i.closedAt);
+  const closed = {};
+  for (const i of closedIssues) { const k = closedKind(i); closed[k] = (closed[k] ?? 0) + 1; }
+  const merged = closed.merged ?? 0;
+  return {
+    n: real.length, created, createdTotal: real.length, closed, closedTotal: closedIssues.length,
+    net: real.length ? real.length - closedIssues.length : null,
+    findingsPerMerge: ratio(created["review-finding"] ?? 0, merged),
+  };
+}
+
+function deltaOf(cur, prev) {
+  if (!prev) return null;
+  return {
+    against: prev.version,
+    cacheReadMean: sub(cur.cost.cacheReadMean, prev.cost.cacheReadMean),
+    mergedPct: sub(cur.flow.mergedPct, prev.flow.mergedPct),
+    needsHumanPct: sub(cur.flow.needsHumanPct, prev.flow.needsHumanPct),
+    remediationPct: sub(cur.flow.remediationPct, prev.flow.remediationPct),
+    wallP50: sub(cur.time.wall.p50, prev.time.wall.p50),
+  };
+}
+
+/**
+ * Join runs, gate events and issues into per-(version, repo) groups with a delta against the previous version of
+ * the same repo and a low-n flag. opts: { minN, releaseTimes, sinceMs, sinceVersion }.
+ */
+export function aggregate({ runs = [], events = [], issues = [] } = {}, opts = {}) {
+  const minN = isNum(opts.minN) ? opts.minN : DEFAULT_MIN_N;
+  const rel = opts.releaseTimes ?? [];
+  const sinceMs = opts.sinceMs ?? null;
+  const inWindow = (...ts) => sinceMs == null || ts.some((t) => (toMs(t) ?? -Infinity) >= sinceMs);
+
+  const excluded = { unfinished: 0, noUsage: 0 };
+  const counted = [];
+  for (const r of runs) {
+    if (!r.finished) { excluded.unfinished++; continue; }
+    if (r.hydrated || !(r.usageEvents > 0)) { excluded.noUsage++; continue; }
+    if (!inWindow(r.endTs, r.startTs)) continue;
+    counted.push({ ...r, version: r.version ?? estimateVersion(toMs(r.endTs ?? r.startTs ?? r.mtimeTs), rel), repo: r.repo ?? UNKNOWN });
+  }
+
+  const versionOfIssue = new Map();
+  for (const r of counted) if (r.issue != null && r.version !== UNKNOWN) versionOfIssue.set(`${r.repo}#${r.issue}`, r.version);
+  const evs = events.filter((e) => inWindow(e.ts)).map((e) => ({
+    ...e, repo: e.repo ?? UNKNOWN,
+    version: e.version ?? e.forge_version ?? estimateVersion(toMs(e.ts), rel),
+  }));
+  for (const e of evs) if (e.issue != null && e.version !== UNKNOWN && !versionOfIssue.has(`${e.repo}#${e.issue}`)) versionOfIssue.set(`${e.repo}#${e.issue}`, e.version);
+  const iss = issues.filter((i) => inWindow(i.createdAt, i.closedAt)).map((i) => ({
+    ...i, repo: i.repo ?? UNKNOWN, labels: i.labels ?? [],
+    version: versionOfIssue.get(`${i.repo}#${i.number}`) ?? estimateVersion(toMs(i.createdAt), rel),
+  }));
+
+  const keys = new Map();
+  for (const x of [...counted, ...evs, ...iss]) keys.set(`${x.version}\u0000${x.repo}`, { version: x.version, repo: x.repo });
+
+  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: issueFlowSection(sel(iss)) };
+    g.n = g.flow.n;
+    g.lowN = g.n < minN;
+    g.minN = minN;
+    return g;
+  });
+  groups.sort((a, b) => a.repo.localeCompare(b.repo) || (a.version === UNKNOWN) - (b.version === UNKNOWN)
+    || compareVersions(a.version, b.version));
+  for (let i = 0; i < groups.length; i++) {
+    const prev = [...groups.slice(0, i)].reverse().find((p) => p.repo === groups[i].repo && p.version !== UNKNOWN);
+    groups[i].delta = groups[i].version === UNKNOWN ? null : deltaOf(groups[i], prev);
+  }
+  if (opts.sinceVersion) groups = groups.filter((g) => g.version !== UNKNOWN && compareVersions(g.version, opts.sinceVersion) >= 0);
+  return { groups, excluded, minN };
+}

package/bin/stats/cache.mjs

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Optional local cache for `forgedock stats` (forge#3835): ~/.forge/stats-cache/<owner>_<repo>/cache.json.
+ * GitHub is the source of truth; this only stores what was already fetched plus the `updated_at` watermark so a
+ * refresh is incremental. A missing, unreadable or wrong-version cache is treated as empty (a re-fetch), and
+ * deleting the directory costs nothing but time. Writes never throw.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const CACHE_VERSION = 1;
+
+export function cacheDir(repo, env = process.env) {
+  const root = env.FORGE_STATS_CACHE_DIR || join(homedir(), ".forge", "stats-cache");
+  return join(root, repo.replace("/", "_"));
+}
+
+/** { watermark: ISO string | null, items: { "<number>": item } } */
+export const emptyCache = () => ({ v: CACHE_VERSION, watermark: null, items: {} });
+
+export function loadCache(repo, env = process.env) {
+  try {
+    const c = JSON.parse(readFileSync(join(cacheDir(repo, env), "cache.json"), "utf8"));
+    if (c && c.v === CACHE_VERSION && c.items && typeof c.items === "object") return { ...emptyCache(), ...c };
+  } catch { /* missing or corrupt: refetch */ }
+  return emptyCache();
+}
+
+export function saveCache(repo, cache, env = process.env) {
+  try {
+    const dir = cacheDir(repo, env);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `cache.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(cache));
+    renameSync(tmp, join(dir, "cache.json"));
+    return true;
+  } catch { return false; }
+}