forgedock 1.16.2 → 1.17.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,23 @@ 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) — ADVISORY by default
+ *    Enforced (exit 2) only when FORGE_ENFORCE_MAIN_CHECKOUT_GIT=1. Otherwise it
+ *    writes a warning to stderr and allows the call: shipped specs (fix-ci,
+ *    milestone, test-gate, cleanup, rollback, recover-orphans, spec-doctor,
+ *    orchestrate phase-4) still run these verbs in the main checkout on purpose,
+ *    and a denial blocks the whole Bash call (their `|| true` fallbacks never run).
+ *    Enforcement becomes the default once those specs use worktrees (#3873).
+ *    When enforced 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 +584,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 === "1") {
+      process.stderr.write(mainCheckoutViolation);
+      process.exit(2);
+      return;
+    }
+    // Advisory (default): several shipped specs still mutate the main checkout on purpose (#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 +1265,161 @@ 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];
+      let hit = null;
+      for (const seg of extractCommandSegments(inner)) hit = hit || mutatingGitCommand(seg, depth + 1);
+      return hit;
+    }
+    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": case "restore":
+      return hit(`git ${sub}`);
+    case "clean":
+      return opts.some((t) => t === "-n" || t === "--dry-run") ? null : hit("git clean");
+    case "branch":
+      return opts.some((t) => /^(?:-[a-zA-Z]*[fFmMdD][a-zA-Z]*|--force|--move|--delete)$/.test(t)) ? hit("git branch") : null;
+    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;
+  }
+}
+
+/**
+ * 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 offender = null;
+    let baseDir = process.cwd();
+    let targetDir = baseDir;
+    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;
+      }
+      const hit = mutatingGitCommand(tokens);
+      if (hit) { offender = hit.name; targetDir = hit.dir === null ? baseDir : resolvePath(baseDir, hit.dir); break; }
+    }
+    if (!offender) return null;
+    if (!isMainCheckout(targetDir)) return null;
+    // 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"))) return null;
+    return (
+      `BLOCKED: \`${offender}\` 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 " +
+      "(enforcement itself is opt-in: FORGE_ENFORCE_MAIN_CHECKOUT_GIT=1).\n"
+    );
+  } catch {
+    return null; // fail open
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Rule 8: Dangerous `rm` target guard (issue #2856)
 //

package/bin/runner.mjs

@@ -1609,10 +1609,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 +1702,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.

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; }
+}

package/bin/stats/github-source.mjs

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Primary source for `forgedock stats` (forge#3835): the target repo's issues and PRs on GitHub.
+ * Reads labels and ONLY trusted `<!-- FORGE:TELEMETRY v1 -->` comments (same predicate as
+ * scripts/trusted-comments.sh: an author_association in FORGE_TRAIL_TRUSTED_ASSOCIATIONS, a Bot, or a login in
+ * FORGE_TRAIL_TRUSTED_LOGINS). Every `gh` call is argv-based (no shell). The `gh` runner is injectable for tests.
+ * Fetching is incremental: only items updated after the cached watermark are re-read.
+ */
+import { execFileSync } from "node:child_process";
+import { emptyCache, loadCache, saveCache } from "./cache.mjs";
+
+export const MARKER_RE = /^<!-- FORGE:TELEMETRY v1( part=(\d+))? -->/;
+const OWNER_REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+export const isValidRepo = (r) => typeof r === "string" && OWNER_REPO_RE.test(r) && !r.split("/").some((p) => p === "." || p === "..");
+
+export function defaultGh(args) {
+  return execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000, maxBuffer: 256 * 1024 * 1024 });
+}
+
+/** `gh api --paginate` prints one JSON array per page; join them into one flat array. */
+export function parsePages(raw) {
+  const t = (raw ?? "").trim();
+  if (!t) return [];
+  return JSON.parse(`[${t.replace(/\]\s*\[/g, "],[")}]`).flat();
+}
+
+export function isTrusted(comment, env = process.env) {
+  const assoc = (env.FORGE_TRAIL_TRUSTED_ASSOCIATIONS ?? "OWNER,MEMBER,COLLABORATOR").split(",").map((s) => s.trim()).filter(Boolean);
+  const logins = (env.FORGE_TRAIL_TRUSTED_LOGINS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  return assoc.includes(comment?.author_association ?? "") || (comment?.user?.type ?? "") === "Bot" || logins.includes(comment?.user?.login ?? "");
+}
+
+/**
+ * Trusted FORGE:TELEMETRY comments -> record objects. Parts are all read (order is irrelevant), the fenced `jsonl`
+ * block is parsed line by line (a torn or invalid line is skipped), and records are deduped on `eid` (never on the
+ * line text: identical same-second events carry different ids).
+ */
+export function parseTelemetryComments(comments, env = process.env) {
+  const seen = new Set();
+  const out = [];
+  for (const c of comments) {
+    if (!MARKER_RE.test(c?.body ?? "") || !isTrusted(c, env)) continue;
+    const block = /```jsonl\n([\s\S]*?)(?:\n```|$)/.exec(c.body);
+    if (!block) continue;
+    for (const line of block[1].split("\n")) {
+      if (!line.trim()) continue;
+      let rec;
+      try { rec = JSON.parse(line); } catch { continue; }
+      if (!rec || typeof rec !== "object" || typeof rec.event !== "string" || typeof rec.eid !== "string" || seen.has(rec.eid)) continue;
+      seen.add(rec.eid);
+      out.push(rec);
+    }
+  }
+  return out;
+}
+
+const num = (x) => { const v = Number(x); return x != null && x !== "" && Number.isFinite(v) ? v : null; };
+
+/**
+ * Turn `phase_attempt` / `run_terminal` records into run summaries (one per repo#issue#run, finished only when a
+ * `run_terminal` exists). Field names are the ones bin/engine/telemetry-seam.mjs writes (docs/TELEMETRY.md).
+ */
+export function runsFromRecords(records) {
+  const byRun = new Map();
+  for (const r of records) {
+    if ((r.event !== "phase_attempt" && r.event !== "run_terminal") || r.issue == null) continue;
+    const key = `${r.repo}#${r.issue}#${r.run ?? ""}`;
+    const run = byRun.get(key) ?? { source: "github", repo: r.repo ?? null, version: r.forge_version ?? null, issue: r.issue, run: r.run ?? null,
+      finished: false, hydrated: false, usageEvents: 0, reason: null, code: null, remediated: false, startTs: null, endTs: null, wallMs: null,
+      phases: {}, _first: null };
+    byRun.set(key, run);
+    if (!run._first || r.ts < run._first) run._first = r.ts;
+    if (r.event === "run_terminal") {
+      run.finished = true; run.reason = r.reason ?? null; run.code = r.code ?? null; run.endTs = r.ts ?? null; run.wallMs = num(r.wall_ms);
+      continue;
+    }
+    const id = r.phase ?? "other";
+    const p = (run.phases[id] ??= { cr: 0, out: 0, usd: null, ms: null, attempts: 0 });
+    const hasUsage = [r.input_tokens, r.output_tokens, r.cache_read_tokens].some((x) => num(x) != null);
+    if (hasUsage) run.usageEvents++;
+    p.cr += num(r.cache_read_tokens) ?? 0;
+    p.out += num(r.output_tokens) ?? 0;
+    p.attempts++;
+    if (num(r.duration_ms) != null) p.ms = (p.ms ?? 0) + num(r.duration_ms);
+    if (num(r.cost_usd) != null) p.usd = (p.usd ?? 0) + num(r.cost_usd);
+    if (id === "remediate") run.remediated = true;
+  }
+  return [...byRun.values()].map(({ _first, ...run }) => ({ ...run, startTs: _first }));
+}
+
+/** Gate/review records (everything that is not a run record) become aggregate events. */
+export const gateEvents = (records) => records.filter((r) => r.event !== "phase_attempt" && r.event !== "run_terminal")
+  .map((r) => ({ ...r, version: r.forge_version ?? null }));
+
+const meta = (it) => ({ number: it.number, isPr: Boolean(it.pull_request), createdAt: it.created_at ?? null, closedAt: it.closed_at ?? null,
+  updatedAt: it.updated_at ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
+
+/**
+ * Fetch (or incrementally refresh) the repo's issues, PRs and trusted telemetry records.
+ * Returns { items, records, fetched, fromCache }. `refresh` ignores the cache; `useCache:false` never touches disk.
+ */
+export function fetchGithubRecords({ repo, refresh = false, useCache = true, gh = defaultGh, env = process.env } = {}) {
+  if (!isValidRepo(repo)) throw new Error(`invalid repo: ${repo}`);
+  const cache = useCache && !refresh ? loadCache(repo, env) : emptyCache();
+  const q = ["state=all", "sort=updated", "direction=asc", "per_page=100", ...(cache.watermark ? [`since=${cache.watermark}`] : [])];
+  const listed = parsePages(gh(["api", "--paginate", `repos/${repo}/issues?${q.join("&")}`]));
+  const items = { ...cache.items };
+  let watermark = cache.watermark;
+  let fetched = 0;
+  for (const it of listed) {
+    if (!Number.isInteger(it?.number)) continue;
+    const m = meta(it);
+    let records = items[it.number]?.records ?? [];
+    // A telemetry comment is edited in place (which may not bump the issue's updated_at), so every listed item with
+    // comments is re-read rather than trusting a cached copy.
+    if ((it.comments ?? 0) > 0) {
+      records = parseTelemetryComments(parsePages(gh(["api", "--paginate", `repos/${repo}/issues/${it.number}/comments`])), env);
+      fetched++;
+    }
+    items[it.number] = { ...m, records };
+    if (m.updatedAt && (!watermark || m.updatedAt > watermark)) watermark = m.updatedAt;
+  }
+  if (useCache) saveCache(repo, { ...emptyCache(), watermark, items }, env);
+  const seen = new Set();
+  const records = [];
+  for (const it of Object.values(items)) for (const r of it.records ?? []) {
+    if (!seen.has(r.eid)) { seen.add(r.eid); records.push(r); }
+  }
+  return { items: Object.values(items), records, fetched, fromCache: cache.watermark != null };
+}
+
+/** Aggregate-model inputs for one repo from a fetch result. */
+export function toModel(repo, result) {
+  return {
+    runs: runsFromRecords(result.records.map((r) => ({ ...r, repo: r.repo ?? repo }))),
+    events: gateEvents(result.records.map((r) => ({ ...r, repo: r.repo ?? repo }))),
+    issues: result.items.map((i) => ({ repo, number: i.number, isPr: i.isPr, createdAt: i.createdAt, closedAt: i.closedAt, labels: i.labels, authorType: i.authorType })),
+  };
+}