forgedock 1.18.0 → 1.20.0

package/bin/stats/stats.test.mjs

@@ -1,8 +1,9 @@
 // SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import { tmpDir } from "../tests/_tmp.mjs";
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,7 +11,7 @@ import { spawnSync } from "node:child_process";
 import { aggregate, compareVersions, percentile } from "./aggregate.mjs";
 import { cacheDir } from "./cache.mjs";
 import { fetchGithubRecords, parseTelemetryComments, runsFromRecords, toModel } from "./github-source.mjs";
-import { buildReport, parseArgs, parseSince, runStats } from "./index.mjs";
+import { buildReport, makeProgressPrinter, parseArgs, parseSince, runStats, sinceToTimestamp } from "./index.mjs";
 import { readLocalRuns } from "./local-source.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
 
@@ -29,6 +30,10 @@ function fakeGh() {
     const path = args.find((a) => a.startsWith("repos/"));
     const m = /issues\/(\d+)\/comments$/.exec(path);
     if (m) return JSON.stringify(comments[m[1]] ?? []);
+    if (/issues\/comments\?/.test(path)) { // repo-wide endpoint: every comment, tagged with its issue (fixtures carry no updated_at)
+      const all = Object.entries(comments).flatMap(([n, list]) => list.map((c) => ({ ...c, issue_url: `https://api.github.com/repos/o/r/issues/${n}` })));
+      return JSON.stringify(/page=1(&|$)/.test(path) ? all : []);
+    }
     const since = /since=([^&]+)/.exec(path)?.[1];
     return JSON.stringify(issues.filter((i) => !since || i.updated_at >= since));
   };
@@ -36,7 +41,7 @@ function fakeGh() {
 }
 
 let td;
-beforeEach(() => { td = mkdtempSync(join(tmpdir(), "stats-")); });
+beforeEach(() => { td = tmpDir("stats-"); });
 afterEach(() => rmSync(td, { recursive: true, force: true }));
 
 describe("telemetry comment parsing", () => {
@@ -58,9 +63,9 @@ describe("telemetry comment parsing", () => {
 });
 
 describe("GitHub-only report (fresh machine)", () => {
-  it("rebuilds cost, time, flow, funnel, gates and issue flow from GitHub alone", () => {
+  it("rebuilds cost, time, flow, funnel, gates and issue flow from GitHub alone", async () => {
     const { gh } = fakeGh();
-    const report = buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
+    const report = await buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
     const g = report.groups.find((x) => x.version === "1.17.0");
     assert.equal(g.n, 1);
     assert.equal(g.cost.cacheReadMean, 3000000);
@@ -85,6 +90,8 @@ describe("GitHub-only report (fresh machine)", () => {
     assert.equal(u.funnel.falsePositive, 1);
     assert.equal(u.issueFlow.net, 2);
     assert.equal(u.issueFlow.findingsPerMerge, null);
+    assert.equal(g.funnel.introduced, 2, "only events carrying scope=introduced are counted");
+    assert.equal(g.issueFlow.introducedPerMerge, (g.issueFlow.closed.merged ?? 0) > 0 ? 2 / g.issueFlow.closed.merged : null);
     assert.ok(!JSON.stringify(report).includes("999999999"), "untrusted record leaked into the report");
   });
   it("matches the run-record field names written by the engine seam", () => {
@@ -138,6 +145,15 @@ describe("local runs, joins, version delta and low-n", () => {
     assert.equal(legacy.cost.cacheReadMean, 4000000, "legacy PHASE_COMMIT usage counted when no attempt events exist");
     assert.equal(legacy.flow.codesN, 0, "old logs have no outcome codes");
   });
+  it("reports introduced findings per merged issue", () => {
+    const ev = (eid, scope) => ({ event: "finding_disposition", eid, repo: "o/r", pr: 1, issue: eid === "d" ? 2 : 1, version: "1.18.0", severity: "MEDIUM", disposition: "INPR_FIX", ...(scope ? { scope } : {}) });
+    const issue = (number) => ({ number, repo: "o/r", isPr: false, labels: ["workflow:merged"], createdAt: "2026-10-06T00:00:00Z", closedAt: "2026-10-07T00:00:00Z" });
+    const r = aggregate({ events: [ev("a", "introduced"), ev("b", "introduced"), ev("c", "pre-existing"), ev("d")], issues: [issue(1), issue(2)] }, { releaseTimes: [] });
+    const g = r.groups.find((x) => x.version === "1.18.0");
+    assert.equal(g.funnel.introduced, 2);
+    assert.equal(g.issueFlow.introducedPerMerge, 1);
+    assert.match(renderMarkdown(r), /introduced findings per merged issue/);
+  });
   it("computes the delta against the previous version of the same repo", () => {
     const g = agg().groups.find((x) => x.version === "1.17.0");
     assert.equal(g.delta.against, "1.16.0");
@@ -178,9 +194,9 @@ describe("n/a degradation and rendering", () => {
     assert.match(renderMarkdown(aggregate({})), /No data/);
     assert.equal(percentile([], 90), null);
   });
-  it("json output is parseable and carries every section", () => {
+  it("json output is parseable and carries every section", async () => {
     const { gh } = fakeGh();
-    const report = buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
+    const report = await buildReport({ repo: "o/r", local: false, cache: false, minN: 10 }, { gh, env: ENV, releaseTimes: [] });
     const parsed = JSON.parse(renderJson(report));
     for (const k of ["cost", "time", "flow", "funnel", "gates", "issueFlow"]) assert.ok(k in parsed.groups[0]);
     const md = renderMarkdown(report);
@@ -193,56 +209,173 @@ describe("n/a degradation and rendering", () => {
 });
 
 describe("cache", () => {
-  it("refreshes incrementally from the updated_at watermark and survives deletion or corruption", () => {
+  it("refreshes incrementally from the updated_at watermark and survives deletion or corruption", async () => {
     const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache") };
     const a = fakeGh();
-    const first = fetchGithubRecords({ repo: "o/r", gh: a.gh, env });
+    const first = await fetchGithubRecords({ repo: "o/r", gh: a.gh, env });
     assert.equal(first.fromCache, false);
     assert.ok(!a.calls[0].includes("since="));
     const b = fakeGh();
-    const second = fetchGithubRecords({ repo: "o/r", gh: b.gh, env });
+    const second = await fetchGithubRecords({ repo: "o/r", gh: b.gh, env });
     assert.equal(second.fromCache, true);
     assert.match(b.calls[0], /since=2026-10-06T12:55:00Z/); // watermark minus the 5 minute overlap window
     assert.deepEqual(second.records.map((r) => r.eid).sort(), first.records.map((r) => r.eid).sort());
     // corrupt cache -> treated as empty -> same result from a full fetch
     writeFileSync(join(cacheDir("o/r", env), "cache.json"), "{not json");
     const c = fakeGh();
-    const third = fetchGithubRecords({ repo: "o/r", gh: c.gh, env });
+    const third = await fetchGithubRecords({ repo: "o/r", gh: c.gh, env });
     assert.equal(third.fromCache, false);
     assert.equal(third.records.length, first.records.length);
     // --refresh ignores a good cache
     const d = fakeGh();
-    fetchGithubRecords({ repo: "o/r", gh: d.gh, env, refresh: true });
+    await fetchGithubRecords({ repo: "o/r", gh: d.gh, env, refresh: true });
     assert.ok(!d.calls[0].includes("since="));
     assert.equal(toModel("o/r", third).issues.length, 5);
   });
-  it("saves a partial checkpoint on a mid-crawl failure and the next run resumes from it", () => {
-    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-partial") };
-    const ok = fakeGh();
-    const full = fetchGithubRecords({ repo: "o/r", gh: ok.gh, env: { ...ENV }, useCache: false });
-    const withComments = full.items.filter((i) => ok.calls.some((c) => c.includes(`/issues/${i.number}/comments`)));
-    assert.ok(withComments.length >= 2, "fixture needs at least two items with comments");
-    let commentCalls = 0;
-    // The real API honours sort=updated&direction=asc, which the watermark resume relies on; the fixture is unsorted.
-    const asc = (gh) => (args) => {
-      const out = gh(args);
-      return args.some((a) => /\/issues\?/.test(a)) ? JSON.stringify(JSON.parse(out).sort((x, y) => x.updated_at.localeCompare(y.updated_at))) : out;
+  // Page-aware fake of the issues API over a synthetic store; the repo-wide comments endpoint is empty unless `comments` is given.
+  const storeGh = (store, { comments = [], failOnListCall = 0 } = {}) => {
+    const calls = [];
+    let listCalls = 0;
+    const gh = (args) => {
+      const path = args.find((a) => a.startsWith("repos/"));
+      calls.push(path);
+      const q = new URLSearchParams(path.split("?")[1] ?? "");
+      if (/issues\/comments\?/.test(path)) {
+        const since = q.get("since"), page = Number(q.get("page") ?? 1);
+        return JSON.stringify(comments.filter((c) => !since || c.updated_at >= since).slice((page - 1) * 100, page * 100));
+      }
+      const m = /issues\/(\d+)\/comments$/.exec(path);
+      if (m) return JSON.stringify(comments.filter((c) => c.issue_url.endsWith(`/issues/${m[1]}`)));
+      const one = /issues\/(\d+)$/.exec(path);
+      if (one) return JSON.stringify(store.find((i) => i.number === Number(one[1])));
+      if (++listCalls === failOnListCall) throw new Error("rate limited");
+      const since = q.get("since");
+      const sorted = store.filter((i) => !since || i.updated_at >= since).sort((x, y) => x.updated_at.localeCompare(y.updated_at) || x.number - y.number);
+      const per = Number(q.get("per_page")), page = Number(q.get("page") ?? 1);
+      return JSON.stringify(sorted.slice((page - 1) * per, page * per));
     };
-    const flaky = asc((args) => {
-      if (args[args.length - 1].endsWith("/comments") && ++commentCalls === 2) throw new Error("rate limited");
-      return ok.gh(args);
-    });
-    assert.throws(() => fetchGithubRecords({ repo: "o/r", gh: flaky, env }), /rate limited/);
+    return { gh, calls };
+  };
+  const ts = (n) => new Date(Date.UTC(2026, 9, 1) + n * 3600000).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const mkItems = (n) => Array.from({ length: n }, (_, i) => ({ number: i + 1, updated_at: ts(i + 1), created_at: ts(0), state: "open", comments: 0, labels: [], user: { type: "Bot" } }));
+  const telemetryComment = (issue, eid, event, updated, extra = {}) => ({ id: issue * 1000 + Number(eid.replace(/\D/g, "")), updated_at: updated, user: { type: "Bot" },
+    issue_url: `https://api.github.com/repos/o/r/issues/${issue}`,
+    body: `<!-- FORGE:TELEMETRY v1 -->\n\`\`\`jsonl\n${JSON.stringify({ v: 1, ts: updated, forge_version: "1.18.0", repo: "o/r", issue, run: `r_${issue}`, eid, event, phase: "build", cache_read_tokens: 100, ...extra })}\n\`\`\`` });
+
+  it("saves a partial checkpoint on a mid-crawl failure and the next run resumes from it", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-partial") };
+    const store = mkItems(250);
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r", gh: storeGh(store, { failOnListCall: 3 }).gh, env }), /rate limited/);
     const saved = JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8"));
     assert.ok(saved.watermark, "partial watermark persisted");
-    assert.ok(Object.keys(saved.items).length > 0 && Object.keys(saved.items).length < full.items.length);
-    const b = fakeGh();
-    const resumed = fetchGithubRecords({ repo: "o/r", gh: asc(b.gh), env });
+    assert.ok(Object.keys(saved.items).length >= 100 && Object.keys(saved.items).length < 250);
+    const b = storeGh(store);
+    const resumed = await fetchGithubRecords({ repo: "o/r", gh: b.gh, env });
     assert.equal(resumed.fromCache, true);
-    assert.match(b.calls[0], /since=/);
-    assert.deepEqual(resumed.records.map((r) => r.eid).sort(), full.records.map((r) => r.eid).sort());
+    assert.ok(b.calls[0].includes("since="), "resumes from the watermark");
+    assert.equal(resumed.items.length, 250);
   });
-  it("never skips an item updated mid-crawl (keyset crawl, not page-number pagination)", () => {
+  it("a mid-crawl failure never advances the watermark past unpersisted telemetry (resume still finds it)", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-pending-telemetry") };
+    const store = mkItems(250);
+    // A telemetry comment on the NEWEST issue (listed last), posted before the failing run starts.
+    const comments = [telemetryComment(250, "z1", "phase_attempt", ts(250))];
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r", gh: storeGh(store, { comments, failOnListCall: 3 }).gh, env }), /rate limited/);
+    const saved = JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8"));
+    assert.ok(!saved.watermark, "watermark must not be persisted while telemetry records are unpersisted");
+    // Resume: the comment is older than any watermark a buggy checkpoint would have saved.
+    const resumed = await fetchGithubRecords({ repo: "o/r", gh: storeGh(store, { comments }).gh, env });
+    assert.equal(resumed.items.length, 250);
+    assert.deepEqual(resumed.records.map((r) => r.eid), ["z1"]);
+    assert.equal(resumed.items.find((i) => i.number === 250).records.length, 1);
+  });
+  it("bounds the crawl by the window: API calls track the window, not the repo size", async () => {
+    const store = mkItems(3000); // 3000 items, one per hour
+    const from = ts(2990);
+    const windowItems = store.filter((i) => i.updated_at >= from).length;
+    const comments = store.slice(-5).map((i) => telemetryComment(i.number, `x${i.number}`, "phase_attempt", i.updated_at));
+    const { gh, calls } = storeGh(store, { comments });
+    const r = await fetchGithubRecords({ repo: "o/r", gh, useCache: false, since: from, env: ENV });
+    assert.equal(r.items.length, windowItems);
+    // 1 comments page + one refetch per telemetry issue + ceil(window / 100) list pages; never one call per repo item.
+    const bound = 1 + comments.length + Math.ceil(windowItems / 100) + 1;
+    assert.ok(r.apiCalls <= bound, `api calls ${r.apiCalls} exceed window bound ${bound}`);
+    assert.equal(calls.length, r.apiCalls);
+    assert.ok(calls.length < 30 && store.length > 100 * calls.length, `calls.length ${calls.length} must be far below the repo size`);
+    assert.ok(calls.some((c) => /issues\/comments\?.*since=/.test(c)), "comments come from the repo-wide since= endpoint");
+    assert.ok(!calls.some((c) => /issues\/\d+\/comments$/.test(c) && !comments.some((x) => x.issue_url.endsWith(c.match(/issues\/(\d+)\//)[1]))), "no comment call for items without telemetry");
+    assert.equal(r.records.length, comments.length);
+  });
+  it("re-reads every part of an issue whose telemetry was touched in the window, and only those", async () => {
+    const store = mkItems(20);
+    const comments = [telemetryComment(7, "e1", "phase_attempt", ts(1)), telemetryComment(7, "e2", "run_terminal", ts(15), { reason: "merged" }),
+      telemetryComment(9, "e1", "phase_attempt", ts(2))];
+    const { gh, calls } = storeGh(store, { comments });
+    const r = await fetchGithubRecords({ repo: "o/r", gh, useCache: false, since: ts(10), env: ENV });
+    assert.deepEqual(r.records.filter((x) => x.issue === 7).map((x) => x.event).sort(), ["phase_attempt", "run_terminal"], "the pre-window part is fetched too");
+    assert.equal(calls.filter((c) => /issues\/7\/comments$/.test(c)).length, 1);
+    assert.equal(calls.filter((c) => /issues\/9\/comments$/.test(c)).length, 0, "issue 9 has no telemetry in the window");
+  });
+  it("accepts an async gh and awaits it", async () => {
+    const store = mkItems(5);
+    const { gh } = storeGh(store);
+    const r = await fetchGithubRecords({ repo: "o/r", gh: async (a) => gh(a), useCache: false, env: ENV });
+    assert.equal(r.items.length, 5);
+  });
+  it("records the coverage floor, crawls only the gap for a wider window and resets on --refresh", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-floor") };
+    const store = mkItems(100);
+    const w1 = storeGh(store);
+    const narrow = await fetchGithubRecords({ repo: "o/r", gh: w1.gh, env, since: ts(90) });
+    assert.equal(narrow.items.length, 11);
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(90));
+    // same or narrower window: incremental from the watermark, floor unchanged
+    const same = storeGh(store);
+    await fetchGithubRecords({ repo: "o/r", gh: same.gh, env, since: ts(95) });
+    assert.ok(/since=/.test(same.calls[0]) && !same.calls[0].includes(`since=${ts(95)}`), "resumes from the watermark, not the window start");
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(90));
+    // wider window: the uncovered gap is crawled (from the new start), then the floor is lowered
+    const wide = storeGh(store);
+    const r = await fetchGithubRecords({ repo: "o/r", gh: wide.gh, env, since: ts(50) });
+    assert.ok(wide.calls[0].includes(`since=${ts(50)}`));
+    assert.equal(r.items.length, 51, "the pre-window gap is not silently treated as covered");
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(50));
+    // no --since after a windowed run: full history is crawled and the floor becomes null
+    const all = storeGh(store);
+    assert.equal((await fetchGithubRecords({ repo: "o/r", gh: all.gh, env })).items.length, 100);
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, null);
+    // --refresh ignores the cache and its floor
+    const fresh = storeGh(store);
+    await fetchGithubRecords({ repo: "o/r", gh: fresh.gh, env, refresh: true, since: ts(80) });
+    assert.equal(JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8")).coveredFrom, ts(80));
+  });
+  it("does not trust a legacy cache (no coveredFrom) for a window and never lowers the floor on failure", async () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-legacy") };
+    const store = mkItems(250);
+    mkdirSync(cacheDir("o/r", env), { recursive: true });
+    writeFileSync(join(cacheDir("o/r", env), "cache.json"), JSON.stringify({ v: 1, watermark: ts(250), items: {} }));
+    const g = storeGh(store, { failOnListCall: 2 });
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r", gh: g.gh, env, since: ts(10) }), /rate limited/);
+    const saved = JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8"));
+    assert.equal(saved.watermark, ts(250), "failed gap crawl keeps the old watermark");
+    assert.ok(!("coveredFrom" in saved) || saved.coveredFrom == null || saved.coveredFrom === undefined);
+    const h = storeGh(store);
+    const r = await fetchGithubRecords({ repo: "o/r", gh: h.gh, env, since: ts(10) });
+    assert.ok(h.calls[0].includes(`since=${ts(10)}`));
+    assert.equal(r.items.length, 241);
+  });
+  it("reports progress through onProgress and backs off when the rate limit is low", async () => {
+    const store = mkItems(6000);
+    const events = [];
+    await fetchGithubRecords({ repo: "o/r", gh: storeGh(store).gh, useCache: false, env: ENV, onProgress: (e) => events.push(e) });
+    assert.ok(events.some((e) => e.phase === "comments") && events.some((e) => e.phase === "issues" && e.done === 6000));
+    const slept = [];
+    const base = storeGh(store).gh;
+    const gh = (args) => (args.join(" ") === "api rate_limit" ? JSON.stringify({ resources: { core: { remaining: 3, reset: 1_000_100 } } }) : base(args));
+    await fetchGithubRecords({ repo: "o/r", gh, useCache: false, env: ENV, rateCheck: true, now: () => 1_000_000_000, sleep: async (ms) => { slept.push(ms); } });
+    assert.ok(slept.length > 0 && slept[0] === 101000, `slept ${slept}`);
+  });
+  it("never skips an item updated mid-crawl (keyset crawl, not page-number pagination)", async () => {
     const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-midcrawl") };
     const ts = (n) => new Date(Date.UTC(2026, 9, 1) + n * 60000).toISOString().replace(/\.\d{3}Z$/, "Z");
     const store = Array.from({ length: 250 }, (_, i) => ({ number: i + 1, updated_at: ts(i + 1), created_at: ts(0), state: "open", comments: 0, labels: [], user: { type: "Bot" } }));
@@ -252,6 +385,7 @@ describe("cache", () => {
     // listing call an already-served item is bumped, which moves it to the end of the ordering.
     const gh = (args) => {
       const path = args.find((a) => a.startsWith("repos/"));
+      if (/issues\/comments\?/.test(path)) return "[]";
       const q = new URLSearchParams(path.split("?")[1]);
       listCalls++;
       const since = q.get("since");
@@ -261,31 +395,32 @@ describe("cache", () => {
       if (listCalls === 1) store[4].updated_at = ts(++maxUpdated);
       return out;
     };
-    const first = fetchGithubRecords({ repo: "o/r", gh, env });
+    const first = await fetchGithubRecords({ repo: "o/r", gh, env });
     assert.equal(first.items.length, 250, "every item is cached after the crawl, none skipped by the shift");
     assert.equal(new Set(first.items.map((i) => i.number)).size, 250);
     // The bumped item moved past the crawl cursor, so the next incremental run (and its overlap window) still sees it.
     store[9].updated_at = ts(++maxUpdated); // another item updated after the first run
-    const second = fetchGithubRecords({ repo: "o/r", gh, env });
+    const second = await fetchGithubRecords({ repo: "o/r", gh, env });
     assert.equal(second.fromCache, true);
     assert.equal(second.items.length, 250);
     assert.equal(second.items.find((i) => i.number === 10).updatedAt, store[9].updated_at);
     assert.equal(second.items.find((i) => i.number === 5).updatedAt, store[4].updated_at);
   });
-  it("terminates and drains a full page whose items all share one updated_at", () => {
+  it("terminates and drains a full page whose items all share one updated_at", async () => {
     const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-sameTs") };
     const store = Array.from({ length: 230 }, (_, i) => ({ number: i + 1, updated_at: "2026-10-02T00:00:00Z", created_at: "2026-10-01T00:00:00Z", comments: 0, labels: [], user: { type: "Bot" } }));
     const gh = (args) => {
+      if (/issues\/comments\?/.test(args.find((a) => a.startsWith("repos/")))) return "[]";
       const q = new URLSearchParams(args.find((a) => a.startsWith("repos/")).split("?")[1]);
       const per = Number(q.get("per_page")), page = Number(q.get("page") ?? 1);
       const since = q.get("since");
       return JSON.stringify(store.filter((i) => !since || i.updated_at >= since).slice((page - 1) * per, page * per));
     };
-    assert.equal(fetchGithubRecords({ repo: "o/r", gh, env }).items.length, 230);
+    assert.equal((await fetchGithubRecords({ repo: "o/r", gh, env })).items.length, 230);
   });
-  it("rejects an unsafe repo before any gh call", () => {
+  it("rejects an unsafe repo before any gh call", async () => {
     const { gh, calls } = fakeGh();
-    assert.throws(() => fetchGithubRecords({ repo: "o/r; rm -rf /", gh }), /invalid repo/);
+    await assert.rejects(() => fetchGithubRecords({ repo: "o/r; rm -rf /", gh }), /invalid repo/);
     assert.equal(calls.length, 0);
   });
 });
@@ -298,6 +433,32 @@ describe("cli", () => {
     assert.throws(() => parseArgs(["--bogus"]), /unknown argument/);
     assert.throws(() => parseSince("yesterday"), /--since must be/);
   });
+  it("resolves --since to a crawl lower bound (date as is, version via release time minus a margin)", () => {
+    assert.equal(sinceToTimestamp("2026-10-01").since, "2026-10-01T00:00:00Z");
+    assert.equal(sinceToTimestamp(undefined).since, null);
+    const v = sinceToTimestamp("v1.16.0", [{ v: "1.16.0", t: Date.parse("2026-10-05T00:00:00Z") / 1000 }]);
+    assert.equal(v.since, "2026-10-04T00:00:00Z");
+    const unknown = sinceToTimestamp("1.99.0", []);
+    assert.equal(unknown.since, null);
+    assert.match(unknown.note, /full history/);
+  });
+  it("prints progress to stderr only, throttled, and keeps --json stdout parseable", async () => {
+    const out = [];
+    let t = 0;
+    const print = makeProgressPrinter((x) => out.push(x), () => t);
+    print({ phase: "issues", done: 100, total: null });
+    t += 500; print({ phase: "issues", done: 200, total: null });
+    t += 2000; print({ phase: "issues", done: 300, total: null });
+    assert.equal(out.length, 2);
+    const { gh } = fakeGh();
+    const realOut = process.stdout.write, realErr = process.stderr.write;
+    let stdout = "", stderr = "";
+    process.stdout.write = (c) => { stdout += c; return true; };
+    process.stderr.write = (c) => { stderr += c; return true; };
+    try { assert.equal(await runStats(["--repo", "o/r", "--json", "--no-cache", "--no-local"], { gh, env: ENV, releaseTimes: [] }), 0); } finally { process.stdout.write = realOut; process.stderr.write = realErr; }
+    assert.ok(JSON.parse(stdout).groups, "stdout is only the JSON report");
+    assert.match(stderr, /forgedock stats: (comments|issues) /);
+  });
   it("--help exits 0 and importing the module did not run it", () => {
     const r = spawnSync(process.execPath, [join(here, "index.mjs"), "--help"], { encoding: "utf8" });
     assert.equal(r.status, 0);

package/commands/orchestrate/phase-4-execution.md

@@ -2586,7 +2586,7 @@ Do not ask the user questions — you are running autonomously in the background
 
    Run the release block only at the end of Step 3 below, once the outcome is settled (merged or labelled terminal state, or the fallback's label write verified), not right after `review-pr` returns.
 
-   **Step 3 — outcome.** On `REVIEW_RESULT: status: COMPLETE` (merged), drive `work-on:close` and let item 6.6 wake dependents as normal. If `review-pr` returns another result with its own labelled terminal state (CHANGES REQUESTED, or `needs-human` for genuine blockers), that verdict applies and the issue is `GATED` or failed per the existing rules. `REREVIEW_MARKER=LOST` (another actor claimed this head first) and `REREVIEW_STATE=CLAIMED` take no action: leave the issue as it is and re-check next cycle. Before applying the terminal fallback for `STALE`, re-read the PR state and the issue labels once more: a merged or closed PR, or an issue that already advanced, means skip the fallback and report the state (forge#3428). If dispatch failed, the skill did not resolve, the issue is still at `workflow:in-review` with no `needs-human` after the retry, Step 1 printed `STALE`, or Step 2 printed `REREVIEW_MARKER=UNVERIFIED` and the re-check below found no live claim, apply the **terminal fallback** defined in `commands/work-on.md` Phase 0A.1 (labels re-read first, comment with the reason, add `needs-human` and remove `workflow:in-review` in one edit, verify the write), classify the issue `GATED`, and surface it to the operator in the run summary as `GATED: re-review could not run (#{PRED}, PR #{REREVIEW_PR}): <reason>`. For `REREVIEW_MARKER=UNVERIFIED`, first re-check for another actor's fresh claim (forge#3429): re-run the Step 1 CLAIMED/STALE/DONE classification for this head (with the SHARED HELPERS pasted at the top of that block). Map the result, reading the printed `FIRST_CLAIM_ID` (the lowest-id, winning claim, the same `.[0]` row that decides ownership everywhere else): if `FIRST_CLAIM_ID` equals this actor's own `CLAIM_ID` (the value Step 2 printed; an empty value never matches), the winning claim is our own unverified one, so go to the fallback (do not stand down on it). If `FIRST_CLAIM_ID` is another actor's id, the winning claim is not ours: classify it with the mapping below, exactly as the router's Claim pre-check step 4 does for `LOST` (forge#3431), so a `STALE` foreign winner (a crashed earlier claimant) goes to the fallback and never strands the issue, even though our own row still exists. Otherwise (and for a foreign winner) `CLAIMED` (another actor's live claim) and `NONE` (merged, closed, or advanced past in-review) stand down like `LOST` (no dispatch, no fallback, re-check next cycle); `UNREADABLE` writes nothing (fail closed, classify `GATED` this cycle without the fallback, as in Step 1); `STALE` and `PENDING` go to the fallback. The reason is `re-review claim could not be recorded` and the report line is `GATED: re-review could not run (#{PRED}, PR #{REREVIEW_PR}): marker write failed`; because the claim is written first, `UNVERIFIED` now means `review-pr` was NOT dispatched. Do not leave the issue `PENDING`. A failed label write is reported as such, not as done. The verified per-head claim bounds this to one re-review per PR head across the orchestrator and the router (no loop). Never review inline.
+   **Step 3 — outcome.** On `REVIEW_RESULT: status: COMPLETE` (merged), drive `work-on:close` and let item 6.6 wake dependents as normal. If `review-pr` returns another result with its own labelled terminal state (CHANGES REQUESTED, or `needs-human` for genuine blockers), that verdict applies and the issue is `GATED` or failed per the existing rules. **`base-conflict` mapping (forge#3516)**: `REVIEW_RESULT: status: BLOCKED` whose blocker contains `base-conflict` carries no label, so it is neither COMPLETE nor a labelled terminal state and must not fall through. Only the verified claim owner (`REREVIEW_MARKER=VERIFIED`) maps it, mirroring `commands/work-on.md` Phase 0A.1 "Base-conflict mapping": re-read the issue labels (closed, `needs-human`, or past `workflow:in-review` means skip and report; idempotent), and unless `DRY_RUN=true` (then record "would set workflow:remediating") run `transition-label.sh {PRED} -R {GH_REPO} remediating` and re-read the labels to verify. `needs-human` keeps precedence over `workflow:remediating` in `classify_predecessor_state`, and item 6.4 dispatches the base-sync remediation on the next cycle, bounded by `FORGE:BASESYNC_REMEDIATION`. If the transition fails or is unverified, apply the terminal fallback (`needs-human`) and do not post the release as settled. Never treat it as GATED-by-human or merge manually. `REREVIEW_MARKER=LOST` (another actor claimed this head first) and `REREVIEW_STATE=CLAIMED` take no action: leave the issue as it is and re-check next cycle. Before applying the terminal fallback for `STALE`, re-read the PR state and the issue labels once more: a merged or closed PR, or an issue that already advanced, means skip the fallback and report the state (forge#3428). If dispatch failed, the skill did not resolve, the issue is still at `workflow:in-review` with no `needs-human` after the retry, Step 1 printed `STALE`, or Step 2 printed `REREVIEW_MARKER=UNVERIFIED` and the re-check below found no live claim, apply the **terminal fallback** defined in `commands/work-on.md` Phase 0A.1 (labels re-read first, comment with the reason, add `needs-human` and remove `workflow:in-review` in one edit, verify the write), classify the issue `GATED`, and surface it to the operator in the run summary as `GATED: re-review could not run (#{PRED}, PR #{REREVIEW_PR}): <reason>`. For `REREVIEW_MARKER=UNVERIFIED`, first re-check for another actor's fresh claim (forge#3429): re-run the Step 1 CLAIMED/STALE/DONE classification for this head (with the SHARED HELPERS pasted at the top of that block). Map the result, reading the printed `FIRST_CLAIM_ID` (the lowest-id, winning claim, the same `.[0]` row that decides ownership everywhere else): if `FIRST_CLAIM_ID` equals this actor's own `CLAIM_ID` (the value Step 2 printed; an empty value never matches), the winning claim is our own unverified one, so go to the fallback (do not stand down on it). If `FIRST_CLAIM_ID` is another actor's id, the winning claim is not ours: classify it with the mapping below, exactly as the router's Claim pre-check step 4 does for `LOST` (forge#3431), so a `STALE` foreign winner (a crashed earlier claimant) goes to the fallback and never strands the issue, even though our own row still exists. Otherwise (and for a foreign winner) `CLAIMED` (another actor's live claim) and `NONE` (merged, closed, or advanced past in-review) stand down like `LOST` (no dispatch, no fallback, re-check next cycle); `UNREADABLE` writes nothing (fail closed, classify `GATED` this cycle without the fallback, as in Step 1); `STALE` and `PENDING` go to the fallback. The reason is `re-review claim could not be recorded` and the report line is `GATED: re-review could not run (#{PRED}, PR #{REREVIEW_PR}): marker write failed`; because the claim is written first, `UNVERIFIED` now means `review-pr` was NOT dispatched. Do not leave the issue `PENDING`. A failed label write is reported as such, not as done. The verified per-head claim bounds this to one re-review per PR head across the orchestrator and the router (no loop). Never review inline.
 
    This satisfies #1809 Q2 (the orchestrator auto-dispatches remediation against the gated issue itself — the exact gap forge#1812's item 6.5/6.6 left open, since those items only ever track and wake *dependents*, never the gated PR's own remediation) — and closes forge#2243 (the gap that #1812's fix left open for *leaf* issues with no dependents: because this item's `$PRED` binding was never made explicit and self-contained, it was only ever reached while walking a dependent's predecessor list, so a `needs-human` issue that has no dependents never got remediation dispatched and its CHANGES-REQUESTED PR re-reviewed the same unchanged commit forever). The remediation agent's outcome is picked up on the **next** completion-monitoring cycle of this same Step 4B loop: if it lands (`workflow:merged`), item 6.6 below fires normally and wakes any `blocked-on-human-merge` dependents (if any exist — a leaf issue simply has none to wake); if it holds/re-escalates, the issue simply remains `GATED` and item 6.5 continues tracking its dependents (if any) unchanged.
 

package/commands/review-pr-agents/protocols.md

@@ -42,6 +42,25 @@ Pipeline agents MUST NOT use `find` (unbounded or filesystem-wide) to locate pro
 
 ---
 
+## SELF-REVIEW MODE (build-time, local diff) <!-- Added: forge#3971 -->
+
+`work-on:build` Phase B5.6 runs the same domain personas on the builder's staged diff before any PR exists, so the builder can fix adversarial-completeness findings while the plan and code are warm. The personas, the Evidence-Based Review Protocol (sections 1-7) and the Structured Findings Protocol apply unchanged; only the transport differs. This mode is entered only when the dispatch prompt says `MODE: SELF-REVIEW`. It is never the official review and never satisfies a review gate.
+
+**Inputs the dispatcher supplies**: `[AGENT_DOMAIN]` (the marker domain), `[ISSUE_NUMBER]`, `[GH_REPO]`, `[WORKTREE_PATH]`, `[PR_BASE]`, `[TREE_HASH]` (the staged tree, `git write-tree`), and `[DOMAIN_DIFF_SLICE]` (the slice of `git diff --cached origin/[PR_BASE]`, scoped exactly as in Per-Agent Input Scoping; the Security agent gets the full diff).
+
+**Substitutions** (persona text that names a PR still applies, translated):
+- No `gh pr *` call is ever made: there is no PR. Read the slice from `[DOMAIN_DIFF_SLICE]` (materialize `SLICE_FILE` with the same heredoc, using `[ISSUE_NUMBER]` and `[AGENT_DOMAIN]` in the path in place of `[PR_NUMBER]` and the SHA), and list changed files with `git -C "[WORKTREE_PATH]" diff --cached --name-only "origin/[PR_BASE]"` wherever a persona runs `gh pr diff [PR_NUMBER] --name-only`. Reads of other repo files happen inside `[WORKTREE_PATH]` with the usual bounded-output rules.
+- No `Reviewed-SHA` staleness check. The pin is the tree: include exactly one line `Tree: [TREE_HASH]` (outside the marker) in the persisted body.
+- Persist Before Post still applies, but the post is `gh issue comment [ISSUE_NUMBER] -R [GH_REPO] --body-file "$REVIEW_BODY_PATH"`, never `gh pr comment`.
+
+**Marker**: the body carries exactly one `<!-- FORGE:SELFREVIEW-AGENT:{domain} -->` marker and NEVER a `FORGE:REVIEW-AGENT` marker or any other FORGE phase marker. `/review-pr`, `scripts/review-finalize.sh` and `scripts/verify-phase-trail.sh` match only `FORGE:REVIEW-AGENT:*`, so a self-review comment never counts as a panel member or as review evidence.
+
+**Findings**: the same `<!-- REVIEW-FINDINGS-START -->` block, the same prefixes, confidence, severity, `**Failure scenario**` and `**Scope**` rules. Report the full list, including POSSIBLE and LOW (the builder acts only on CONFIRMED and LIKELY at MEDIUM or above and records the rest). Return the verdict and one line per finding to the dispatcher as usual; completion is read from the posted comment's `Tree:` line, not from a notification.
+
+**Do not**: edit any file, run `git add`/`git commit`/`git push`, post a verdict, label, or review marker, or create issues. A self-review agent is read-only.
+
+---
+
 ## Evidence-Based Review Protocol (ALL Agents Follow) <!-- allowlist:check-protocol-restatements -->
 
 Every agent MUST follow this protocol:

package/commands/review-pr-staging.md

@@ -471,7 +471,7 @@ if [ -n "$TRUSTED_SCRIPT" ] && [ -n "${ALL_PR_NUMBERS:-}" ] && [ -n "${PR_NUMBER
     # Reviewed = trusted FORGE:REVIEW_ROUTE (a real review mode) whose sha is the PR's FINAL head, plus at least one review-agent comment
     # carrying the full-length `Reviewed-SHA: <head>` line and a findings block (same predicate as review-pr.md Phase 5; a 7-char substring or a comment with no findings block never counts), and no degraded/blocked review marker. A PR pushed to after its review has a stale sha: the exact-head gate gives it no credit, and only the delta branch below (shared resolver `scripts/review-delta.sh`) may credit the commits an earlier trusted complete panel covered or a trusted `FORGE:REVIEW-CARRIED` base sync carried; everything else stays UNREVIEWED.
     _ROUTE=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW_ROUTE mode=(?!spec-evolution-blocked)[^ ]+ spec=review-pr.md sha=${_HEAD7} -->") || { SCOPE_MODE=full; break; }
-    _AGENT=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->)<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${_HEAD}(\\r?\\n|$)") || { SCOPE_MODE=full; break; }
+    _AGENT=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${_HEAD}(\\r?\\n|$)") || { SCOPE_MODE=full; break; }
     _DEGRADED=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:(REVIEW_DEGRADED|REVIEW_BLOCKED)") || { SCOPE_MODE=full; break; }
     case "$_ROUTE$_AGENT$_DEGRADED" in ''|*[!0-9]*) SCOPE_MODE=full; break ;; esac
     if [ "$_ROUTE" -ge 1 ] && [ "$_AGENT" -ge 1 ] && [ "$_DEGRADED" -eq 0 ] && [ "$(printf '%s' "$_J" | jq '.commits|length')" -lt 100 ]; then
@@ -1044,7 +1044,7 @@ for AGENT_DOMAIN in $LAUNCHED_REVIEW_AGENTS; do
   AGENT_COMMENT_COUNT=0
   if [ -n "$REVIEW_SHA_FULL" ] && [ -n "$TRUSTED_SCRIPT" ]; then
     AGENT_COMMENT_COUNT=$(gh api --paginate "repos/${GH_REPO}/issues/${PR_NUMBER}/comments" 2>/dev/null \
-      | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA:[ ]${REVIEW_SHA_FULL}(\\r?\\n|$)" 2>/dev/null || echo 0)
+      | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA:[ ]${REVIEW_SHA_FULL}(\\r?\\n|$)" 2>/dev/null || echo 0)
   fi
   case "$AGENT_COMMENT_COUNT" in ''|*[!0-9]*) AGENT_COMMENT_COUNT=0 ;; esac   # fail closed: counts as missing
   if [ "${AGENT_COMMENT_COUNT:-0}" -lt 1 ]; then
@@ -1054,7 +1054,7 @@ done
 
 if [ -n "$MISSING_AGENT_COMMENTS" ]; then
   echo "REVIEW DELIVERY FAILURE: missing findings comment(s) for:${MISSING_AGENT_COMMENTS}"
-  echo "Recover each agent's returned verdict, findings, and durable body path before rerunning review."
+  echo "A comment without a REVIEW-FINDINGS-START block counts as missing. Re-dispatch the missing agent once with the note: structured findings block required. A second miss is a degraded panel. Recover each agent's returned verdict, findings, and durable body path before rerunning review."
   exit 1
 fi
 ```
@@ -1086,7 +1086,7 @@ bash "$RF" classify --pr "$PR_NUMBER" --repo "$GH_REPO" --context "$CTX" --out-d
 cat "$OUT_DIR/note-list.txt" 2>/dev/null
 ```
 
-Read `FINDINGS_KEPT`, `FINDINGS_DROPPED_STALE`, `FINDINGS_PREEXISTING` and `NOTES_DEMOTED_NO_SCENARIO` for the summary. With no kept finding and no unstructured finding in the trusted reviewer bodies, skip to Phase 8.
+Read `FINDINGS_KEPT`, `FINDINGS_DROPPED_STALE`, `FINDINGS_PREEXISTING` and `NOTES_DEMOTED_NO_SCENARIO` for the summary. Findings come only from `FINDING:` markers, never from free text. If `AGENTS_WITHOUT_BLOCK` is non-empty those agents are undelivered (no findings block): re-dispatch them once with the note "structured findings block required", else take the degraded-panel path; `CLEAN_STRUCTURED` is withheld meanwhile. With no kept finding and `CLEAN_STRUCTURED=true`, skip to Phase 8. A marker-less finding is classified with `classify-finding.sh --unstructured` (empty or unparseable severity is `NOTE unstructured`, never ISSUE).
 
 ### 7B: Note disposition (same damper and classifier as `/review-pr` §6B.5)