forgedock 1.17.0 → 1.19.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", () => {
@@ -93,6 +100,27 @@ describe("GitHub-only report (fresh machine)", () => {
     assert.equal(runs[0].finished, true);
     assert.equal(runs[0].phases.review.cr, 500000);
   });
+  const rec = (run, ts, event, x = {}) => ({ event, repo: "o/r", issue: 500, run, ts, eid: run + ts + event, ...x });
+  it("collapses a retried issue (two run ids) to the latest run", () => {
+    const runs = runsFromRecords([
+      rec("r_500_1", "2026-01-01T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 2000000 }),
+      rec("r_500_1", "2026-01-01T00:01:00Z", "run_terminal", { reason: "engine-error" }),
+      rec("r_500_2", "2026-01-02T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 1000000 }),
+      rec("r_500_2", "2026-01-02T00:01:00Z", "run_terminal", { reason: "merged" }),
+    ]);
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].reason, "merged");
+    assert.equal(runs[0].phases.build.cr, 1000000);
+  });
+  it("lets an unfinished latest run win over an earlier finished retried run", () => {
+    const runs = runsFromRecords([
+      rec("r_500_1", "2026-01-01T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 2000000 }),
+      rec("r_500_1", "2026-01-01T00:01:00Z", "run_terminal", { reason: "merged" }),
+      rec("r_500_2", "2026-01-02T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 1000000 }),
+    ]);
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].finished, false);
+  });
 });
 
 describe("local runs, joins, version delta and low-n", () => {
@@ -117,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");
@@ -157,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);
@@ -172,32 +209,218 @@ 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-06T13:00:00Z/);
+    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("rejects an unsafe repo before any gh call", () => {
+  // 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));
+    };
+    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 >= 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.ok(b.calls[0].includes("since="), "resumes from the watermark");
+    assert.equal(resumed.items.length, 250);
+  });
+  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" } }));
+    let listCalls = 0;
+    let maxUpdated = 250;
+    // Page-aware fake of the real API: asc by updated_at, honours since (inclusive), per_page and page. After the first
+    // 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");
+      const sorted = store.filter((i) => !since || i.updated_at >= since).sort((a, b) => a.updated_at.localeCompare(b.updated_at) || a.number - b.number);
+      const per = Number(q.get("per_page")), page = Number(q.get("page") ?? 1);
+      const out = JSON.stringify(sorted.slice((page - 1) * per, page * per));
+      if (listCalls === 1) store[4].updated_at = ts(++maxUpdated);
+      return out;
+    };
+    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 = 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", 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((await fetchGithubRecords({ repo: "o/r", gh, env })).items.length, 230);
+  });
+  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);
   });
 });
@@ -210,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/cleanup.md

@@ -241,6 +241,7 @@ Each `/orchestrate` batch creates one claims board (`orchestrate: claims board f
 A board is closed only when **all** identity checks pass and **one** closing condition holds:
 
 - Identity: title starts with `orchestrate: claims board for batch`, body contains `<!-- FORGE:COORD_ISSUE -->`, and the author is trusted: `author_association` `OWNER`, `MEMBER` or `COLLABORATOR`, or a Bot account (the pipeline's GitHub App, reported as `CONTRIBUTOR`). A look-alike issue from an outside account is never closed.
+- Lease/claim comments count only when trusted (same `author_association` `OWNER`/`MEMBER`/`COLLABORATOR` or Bot predicate as the board, mirroring `scripts/trusted-comments.sh`) and when the marker starts the comment body; an untrusted or quoted marker is ignored, so a board falls back to its trusted events or its creation time. Unlike `/orchestrate`'s no-authorship lease check (forge#2644, a bounded self-expiring dispatch refusal), cleanup's action is a destructive issue close, so it must not trust arbitrary commenters.
 - Close when the last `FORGE:LEASE*` comment is a `FORGE:LEASE_RELEASED`.
 - Close when the last `FORGE:LEASE*`/`FORGE:CLAIM*` comment is older than `BOARD_STALE_HOURS` (default 6, far above the 15 minute lease TTL).
 - Close when there is no lease/claim comment and the issue itself is older than `BOARD_STALE_HOURS`.
@@ -272,11 +273,17 @@ while IFS=$'\t' read -r BNUM BCREATED; do
 
   # --paginate emits one array per page: slurp (jq -s) and flatten BEFORE taking `last`,
   # otherwise a board with >30 comments reads a stale event from an earlier page.
+  # Lease/claim comments are trust-filtered with the same predicate as the board (OWNER/MEMBER/
+  # COLLABORATOR or Bot; mirrors scripts/trusted-comments.sh) and the marker must LEAD the body, so an
+  # outside commenter can neither post a fake FORGE:LEASE_RELEASED nor a fake fresh FORGE:LEASE/CLAIM,
+  # and a quoted marker in prose never matches.
   LAST_LEASE=$(gh api --paginate "repos/{GH_REPO}/issues/${BNUM}/comments" 2>/dev/null \
-    | jq -s '[.[][] | select(.body | contains("FORGE:LEASE"))] | last // empty
-             | {released: (.body | contains("FORGE:LEASE_RELEASED")), at: .created_at}' 2>/dev/null || echo "")
+    | jq -s '[.[][] | select((((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")) or ((.user.type // "") == "Bot")))
+                     | select((.body // "") | test("\\A\\s*<!-- FORGE:LEASE"))] | last // empty
+             | {released: (.body | test("\\A\\s*<!-- FORGE:LEASE_RELEASED")), at: .created_at}' 2>/dev/null || echo "")
   LAST_ACTIVITY=$(gh api --paginate "repos/{GH_REPO}/issues/${BNUM}/comments" 2>/dev/null \
-    | jq -rs '[.[][] | select(.body | contains("FORGE:LEASE") or contains("FORGE:CLAIM"))] | last // empty | .created_at' 2>/dev/null || echo "")
+    | jq -rs '[.[][] | select((((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")) or ((.user.type // "") == "Bot")))
+                      | select((.body // "") | test("\\A\\s*<!-- FORGE:(LEASE|CLAIM)"))] | last // empty | .created_at' 2>/dev/null || echo "")
 
   REASON=""
   if [ -n "$LAST_LEASE" ] && [ "$(echo "$LAST_LEASE" | jq -r '.released')" = "true" ]; then

package/commands/deploy-pr.md

@@ -183,6 +183,70 @@ else
 fi
 ```
 
+### 2A.5: Version Sync Pre-flight
+
+Applies ONLY when `SOURCE=$STAGING_BRANCH` and `PR_TARGET=$DEFAULT_BRANCH` (a staging deploy). Skip for every other lane. Publishing bumps the version on the default branch only, so the deploy PR fails the Deploy Version Guard until staging carries that version. The publish workflow normally syncs it; this pre-flight is the safety net when that sync failed. <!-- Added: forge#3695 -->
+
+Rule (same as the publish workflow): sync only when the default branch `package.json` version is strictly ahead of the source branch's. If the source is already at or above it, skip. The sync is a version-only commit (`package.json` and `.claude-plugin/plugin.json`), never a merge of the default branch.
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+STAGING_BRANCH=$(yq '.branches.staging // "staging"' "$CONFIG_FILE" 2>/dev/null || echo "staging")
+DEFAULT_BRANCH=$(yq '.branches.default // "main"' "$CONFIG_FILE" 2>/dev/null || echo "main")
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE" 2>/dev/null || echo "$(git rev-parse --show-toplevel)")
+
+if [ "$SOURCE" = "$STAGING_BRANCH" ] && [ "$PR_TARGET" = "$DEFAULT_BRANCH" ]; then
+  cd "$REPO_PATH"
+  git fetch origin "$SOURCE" "$DEFAULT_BRANCH" || { echo "version sync: fetch failed — continuing (version guard will report)"; }
+  MAIN_VERSION=$(git show "origin/$DEFAULT_BRANCH:package.json" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0, 'utf8')).version)")
+  SRC_VERSION=$(git show "origin/$SOURCE:package.json" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0, 'utf8')).version)")
+
+  # Numeric semver compare in node (never a string compare: 1.10.0 > 1.9.0).
+  if MAIN_VERSION="$MAIN_VERSION" SRC_VERSION="$SRC_VERSION" node -e "
+    const p = (v) => v.split('.').map(Number);
+    const [m, s] = [p(process.env.MAIN_VERSION), p(process.env.SRC_VERSION)];
+    for (let i = 0; i < 3; i++) { if (m[i] !== s[i]) process.exit(m[i] > s[i] ? 0 : 1); }
+    process.exit(1);
+  "; then
+    echo "$DEFAULT_BRANCH is at $MAIN_VERSION, ahead of $SOURCE ($SRC_VERSION) — version sync needed"
+    if [ "${DRY_RUN:-false}" = "true" ]; then
+      echo "[dry-run] would sync version $MAIN_VERSION to $SOURCE"
+    else
+      SYNC_DIR=$(mktemp -d)
+      git worktree add --detach "$SYNC_DIR" "origin/$SOURCE"
+      (
+        cd "$SYNC_DIR" || exit 1
+        VERSION="$MAIN_VERSION" node -e "
+          const fs = require('fs');
+          for (const f of ['package.json', '.claude-plugin/plugin.json']) {
+            const j = JSON.parse(fs.readFileSync(f, 'utf8'));
+            j.version = process.env.VERSION;
+            fs.writeFileSync(f, JSON.stringify(j, null, 2) + '\\n');
+          }
+        "
+        git add package.json .claude-plugin/plugin.json
+        git commit -m "chore: sync version $MAIN_VERSION to $SOURCE"
+        if ! git push origin "HEAD:$SOURCE"; then
+          # Push rejected (protected branch or race): fall back to a sync PR.
+          SYNC_BRANCH="chore/sync-main-into-staging-$MAIN_VERSION"
+          git push -f origin "HEAD:refs/heads/$SYNC_BRANCH" \
+            && SYNC_PR=$(gh pr create $GH_FLAG --base "$SOURCE" --head "$SYNC_BRANCH" \
+                 --title "chore: sync version $MAIN_VERSION to $SOURCE" \
+                 --body "Version-only sync so the deploy PR passes the Deploy Version Guard. Generated by deploy-pr 2A.5.") \
+            && echo "Opened sync PR $SYNC_PR — wait for CI green and merge (never bypass gating), then re-run"
+        fi
+      )
+      git worktree remove --force "$SYNC_DIR" 2>/dev/null || true
+      git fetch origin "$SOURCE" 2>/dev/null || true   # re-fetch before 2B/2C
+    fi
+  else
+    echo "$SOURCE ($SRC_VERSION) is at or above $DEFAULT_BRANCH ($MAIN_VERSION) — no version sync needed"
+  fi
+fi
+```
+
+If a sync PR was opened instead of a direct push, wait for it to pass CI and merge through the normal gates before continuing to 2B; do not create or update the deploy PR against a stale source version. Phase 2B onward and the `PR_NUMBER` handoff are unchanged.
+
 ### 2B: Gather Commit Summary (for new PR body)
 
 Skip if PR already exists.

package/commands/fix-ci.md

@@ -312,11 +312,18 @@ echo "Failure detail: ${FAILURE_DETAIL}"
 
 ### Phase 1D: Apply targeted fix
 
-Work on the PR's head branch directly. Check out the branch in the repo root (not a worktree — we push to the existing PR head):
+Work on the PR's head in a dedicated detached worktree, never in the main checkout (it is shared with the operator and other agents). The fix is pushed to the existing PR head with `HEAD:refs/heads/...`. Create the worktree once (reuse it on later attempts) and run every fix, format, test, commit and push step from inside it (`cd "$FIX_WT"`); Phase 2A removes it on every exit path:
 
 ```bash
-git checkout "$FIX_TARGET" 2>/dev/null || git checkout -b "$FIX_TARGET" "origin/${FIX_TARGET}" 2>/dev/null
-git pull origin "$FIX_TARGET" --rebase 2>/dev/null || true
+if [ -z "${FIX_WT:-}" ] || [ ! -d "$FIX_WT" ]; then
+  FIX_WT=$(mktemp -d)
+  git -C "$REPO_PATH" fetch origin "$FIX_TARGET" \
+    && git -C "$REPO_PATH" worktree add --detach "$FIX_WT" "origin/${FIX_TARGET}" \
+    || { echo "ERROR: could not create fix worktree"; rmdir "$FIX_WT" 2>/dev/null; LOOP_STATUS="blocked"; break; }
+fi
+git -C "$FIX_WT" fetch origin "$FIX_TARGET" 2>/dev/null || true
+git -C "$FIX_WT" rebase "origin/${FIX_TARGET}" 2>/dev/null || true
+cd "$FIX_WT"
 ```
 
 **Apply fix based on failure class**:
@@ -440,13 +447,14 @@ echo "Committed fix for attempt ${ATTEMPT}"
 **Push** (normal push only — no force):
 
 ```bash
-git push origin "$FIX_TARGET" 2>&1
+git -C "$FIX_WT" push origin HEAD:"refs/heads/${FIX_TARGET}" 2>&1
 PUSH_EXIT=$?
 
 if [ "$PUSH_EXIT" -ne 0 ]; then
   echo "Push failed (exit ${PUSH_EXIT}) — attempting pull-rebase then re-push..."
-  git pull origin "$FIX_TARGET" --rebase 2>&1 && \
-    git push origin "$FIX_TARGET" 2>&1
+  git -C "$FIX_WT" fetch origin "$FIX_TARGET" 2>&1 && \
+    git -C "$FIX_WT" rebase "origin/${FIX_TARGET}" 2>&1 && \
+    git -C "$FIX_WT" push origin HEAD:"refs/heads/${FIX_TARGET}" 2>&1
   PUSH_EXIT=$?
 fi
 
@@ -476,6 +484,12 @@ After the loop exits, determine the final status and report.
 ### 2A: Determine final status
 
 ```bash
+# Remove the fix worktree on every exit path (success, failure, timeout, blocked).
+cd "$REPO_PATH"
+if [ -n "${FIX_WT:-}" ] && [ -d "$FIX_WT" ]; then
+  git -C "$REPO_PATH" worktree remove --force "$FIX_WT" 2>/dev/null || true
+fi
+
 case "$LOOP_STATUS" in
   "success")
     FINAL_STATUS="success"

package/commands/milestone.md

@@ -412,11 +412,18 @@ Before shipping, ensure the milestone branch is up to date with `staging` (picks
 ```bash
 cd {REPO_PATH}
 git fetch origin {STAGING_BRANCH} milestone/{slug}
-git checkout milestone/{slug}
-git merge origin/{STAGING_BRANCH} --no-edit
-# If conflicts, report to user and STOP — do not auto-resolve
-git push origin milestone/{slug}
-git checkout {STAGING_BRANCH}
+# Never mutate the main checkout: sync in a detached worktree at the milestone tip
+SYNC_WT=$(mktemp -d)
+git worktree add --detach "$SYNC_WT" origin/milestone/{slug}
+if git -C "$SYNC_WT" merge origin/{STAGING_BRANCH} --no-edit; then
+  git -C "$SYNC_WT" push origin HEAD:refs/heads/milestone/{slug}
+  git worktree remove --force "$SYNC_WT"
+else
+  # Conflicts: report to user and STOP — do not auto-resolve
+  git -C "$SYNC_WT" merge --abort 2>/dev/null || true
+  git worktree remove --force "$SYNC_WT"
+  echo "STOP: merge conflict syncing milestone/{slug} with {STAGING_BRANCH}"; exit 1
+fi
 ```
 
 ### Step 2.5: Pre-Merge Hunk-Loss Audit (MANDATORY before creating PR)
@@ -425,6 +432,7 @@ git checkout {STAGING_BRANCH}
 
 This step identifies "at-risk hunks" — staging-only content in files the milestone also modifies — and absorbs them into the milestone branch via rebase before the PR is created. After the rebase, even a squash merge will preserve all staging content because it's now part of the milestone branch's commits.
 
+<!-- allowlist:check-spec-bash -->
 ```bash
 cd {REPO_PATH}
 git fetch origin {STAGING_BRANCH} milestone/{slug}
@@ -453,18 +461,19 @@ else
         echo "$AT_RISK" | grep '^--- a/' | sed 's|^--- a/||'
 
         echo "Rebasing milestone/{slug} onto origin/{STAGING_BRANCH} to absorb at-risk hunks..."
-        git checkout milestone/{slug}
-        git rebase origin/{STAGING_BRANCH}
+        REBASE_WT=$(mktemp -d)
+        git worktree add --detach "$REBASE_WT" origin/milestone/{slug}
+        git -C "$REBASE_WT" rebase origin/{STAGING_BRANCH}
 
         REBASE_EXIT=$?
         if [ "$REBASE_EXIT" -ne 0 ]; then
             # Capture conflicting files BEFORE aborting (after abort, unmerged state is gone)
-            CONFLICTING_FILES=$(git diff --name-only --diff-filter=U 2>/dev/null)
+            CONFLICTING_FILES=$(git -C "$REBASE_WT" diff --name-only --diff-filter=U 2>/dev/null)
             [ -z "$CONFLICTING_FILES" ] && CONFLICTING_FILES="unknown — check git status after resolving manually"
 
             # Abort the failed rebase and return to a clean state
-            git rebase --abort 2>/dev/null || true
-            git checkout {STAGING_BRANCH}
+            git -C "$REBASE_WT" rebase --abort 2>/dev/null || true
+            git worktree remove --force "$REBASE_WT"
 
             # Truncate AT_RISK to safe size for issue body (avoid shell quoting issues with large diffs)
             AT_RISK_SNIPPET=$(echo "$AT_RISK" | head -60 | sed "s/'/'\\\\''/g")
@@ -519,6 +528,7 @@ ISSUE_EOF
 ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fix(milestone): rebase conflict during hunk-loss audit for milestone/{slug}\" --body-file \"${REBASE_ISSUE_BODY_FILE}\" --label \"bug\" --label \"priority:P0\" --label \"needs-human\""))
 ```
 
+<!-- allowlist:check-spec-bash -->
 ```bash
             echo "STOP: Rebase conflict. Created issue for manual resolution (see /issue output above). Do NOT proceed to PR creation."
             echo "Run '/milestone ship {slug}' again after resolving the conflict."
@@ -526,9 +536,9 @@ ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fi
         fi
 
         # Rebase succeeded — push the rebased branch
-        git push origin milestone/{slug} --force-with-lease
+        git -C "$REBASE_WT" push origin HEAD:refs/heads/milestone/{slug} --force-with-lease
+        git worktree remove --force "$REBASE_WT"
         echo "Rebase complete. Milestone branch now includes all $AT_RISK_COUNT at-risk staging hunks."
-        git checkout {STAGING_BRANCH}
     fi
 fi
 ```
@@ -716,11 +726,18 @@ Syncs the milestone branch with the latest default branch to pick up fast-lane f
 cd {REPO_PATH}
 DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 git fetch origin $DEFAULT_BRANCH milestone/{slug}
-git checkout milestone/{slug}
-git merge origin/$DEFAULT_BRANCH --no-edit
-# If conflicts, report to user and STOP
-git push origin milestone/{slug}
-git checkout $DEFAULT_BRANCH
+# Never mutate the main checkout: sync in a detached worktree at the milestone tip
+SYNC_WT=$(mktemp -d)
+git worktree add --detach "$SYNC_WT" origin/milestone/{slug}
+if git -C "$SYNC_WT" merge origin/$DEFAULT_BRANCH --no-edit; then
+  git -C "$SYNC_WT" push origin HEAD:refs/heads/milestone/{slug}
+  git worktree remove --force "$SYNC_WT"
+else
+  # If conflicts, report to user and STOP
+  git -C "$SYNC_WT" merge --abort 2>/dev/null || true
+  git worktree remove --force "$SYNC_WT"
+  echo "STOP: merge conflict syncing milestone/{slug} with $DEFAULT_BRANCH"; exit 1
+fi
 ```
 
 Report: "Synced milestone/{slug} with latest `{DEFAULT_BRANCH}`. {N} new commits incorporated."