forgedock 1.16.2 → 1.18.0

package/bin/stats/stats.test.mjs

@@ -0,0 +1,312 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+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 { readLocalRuns } from "./local-source.mjs";
+import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const fx = (f) => join(here, "fixtures", f);
+const load = (f) => JSON.parse(readFileSync(fx(f), "utf8"));
+const ENV = { FORGE_TRAIL_TRUSTED_ASSOCIATIONS: "OWNER,MEMBER,COLLABORATOR" };
+
+// A fake `gh`: lists the fixture issues (honouring `since`), serves comments per number. Counts every call.
+function fakeGh() {
+  const comments = { 201: load("comments-201.json"), 301: load("comments-301.json") };
+  const issues = load("issues.json");
+  const calls = [];
+  const gh = (args) => {
+    calls.push(args.join(" "));
+    const path = args.find((a) => a.startsWith("repos/"));
+    const m = /issues\/(\d+)\/comments$/.exec(path);
+    if (m) return JSON.stringify(comments[m[1]] ?? []);
+    const since = /since=([^&]+)/.exec(path)?.[1];
+    return JSON.stringify(issues.filter((i) => !since || i.updated_at >= since));
+  };
+  return { gh, calls };
+}
+
+let td;
+beforeEach(() => { td = mkdtempSync(join(tmpdir(), "stats-")); });
+afterEach(() => rmSync(td, { recursive: true, force: true }));
+
+describe("telemetry comment parsing", () => {
+  it("concatenates parts, dedupes on eid and ignores untrusted or unrelated comments", () => {
+    const recs = parseTelemetryComments(load("comments-201.json"), ENV);
+    assert.deepEqual(recs.map((r) => r.eid), ["e1", "e2", "e3", "e4", "e5"]);
+    assert.ok(!recs.some((r) => r.eid === "e90"), "untrusted User comment must not be read");
+  });
+  it("skips torn lines and keeps identical-looking events that have different eids", () => {
+    const body = "<!-- FORGE:TELEMETRY v1 -->\n```jsonl\n{\"event\":\"a\",\"eid\":\"1\"}\n{\"event\":\"a\",\"eid\":\"2\"}\n{torn\n";
+    const recs = parseTelemetryComments([{ body, user: { type: "Bot" } }], ENV);
+    assert.equal(recs.length, 2);
+  });
+  it("trusts OWNER/MEMBER/COLLABORATOR, not NONE users", () => {
+    const body = "<!-- FORGE:TELEMETRY v1 -->\n```jsonl\n{\"event\":\"a\",\"eid\":\"1\"}\n```";
+    assert.equal(parseTelemetryComments([{ body, author_association: "MEMBER", user: { type: "User" } }], ENV).length, 1);
+    assert.equal(parseTelemetryComments([{ body, author_association: "NONE", user: { type: "User" } }], ENV).length, 0);
+  });
+});
+
+describe("GitHub-only report (fresh machine)", () => {
+  it("rebuilds cost, time, flow, funnel, gates and issue flow from GitHub alone", () => {
+    const { gh } = fakeGh();
+    const report = 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);
+    assert.equal(g.cost.usdMean, 1.2);
+    assert.equal(g.time.wall.p50, 900000);
+    assert.equal(g.time.phases.build.p50, 500000);
+    assert.equal(g.flow.mergedPct, 1);
+    assert.deepEqual(g.flow.codes.map((c) => c.code), ["completed"]);
+    assert.equal(g.funnel.reviews, 1);
+    assert.equal(g.funnel.findings, 3);
+    assert.equal(g.funnel.bySeverity.HIGH.total, 2);
+    assert.equal(g.funnel.bySeverity.HIGH.ISSUE, 1);
+    assert.equal(g.funnel.bySeverity.HIGH.INPR_FIX, 1);
+    assert.equal(g.gates.acceptance.rate, 1, "duplicate eid counted once");
+    assert.equal(g.gates.malformedRate, 1);
+    assert.equal(g.gates.ci.rate, 0.5);
+    assert.deepEqual(g.issueFlow.created, { pipeline: 1 });
+    assert.equal(g.issueFlow.net, 0);
+    const u = report.groups.find((x) => x.version === "unknown");
+    assert.deepEqual(u.issueFlow.created, { "review-finding": 2, human: 1 });
+    assert.equal(u.funnel.validated, 1);
+    assert.equal(u.funnel.falsePositive, 1);
+    assert.equal(u.issueFlow.net, 2);
+    assert.equal(u.issueFlow.findingsPerMerge, 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", () => {
+    const runs = runsFromRecords(parseTelemetryComments(load("comments-201.json"), ENV));
+    assert.equal(runs.length, 1);
+    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", () => {
+  const runs = () => readLocalRuns(fx("runs"));
+  const agg = (opts = {}) => aggregate({ runs: runs() }, { releaseTimes: [], ...opts });
+
+  it("applies the cost-report counting rules", () => {
+    const r = agg();
+    assert.deepEqual(r.excluded, { unfinished: 1, noUsage: 1 });
+    const g = r.groups.find((x) => x.version === "1.16.0");
+    assert.equal(g.n, 2);
+    assert.equal(g.cost.cacheReadMean, 4500000);
+    assert.equal(g.cost.perPhase.build, 4000000);
+    assert.equal(g.cost.perPhase.remediate, 0);
+    assert.equal(g.cost.perMergedIssue, 9000000);
+    assert.equal(g.flow.mergedPct, 0.5);
+    assert.equal(g.flow.needsHumanPct, 0.5);
+    assert.equal(g.flow.remediationPct, 0.5);
+    assert.equal(g.cost.usdN, 1);
+    assert.equal(g.time.wall.p50, 1500000);
+    const legacy = r.groups.find((x) => x.version === "unknown");
+    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("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");
+    assert.equal(g.delta.cacheReadMean, 2000000 - 4500000);
+    assert.equal(g.delta.mergedPct, 0.5);
+    assert.equal(agg().groups.find((x) => x.version === "1.16.0").delta, null);
+  });
+  it("flags samples under 10 and honours --min-n", () => {
+    assert.ok(agg().groups.every((g) => g.lowN));
+    assert.equal(agg({ minN: 2 }).groups.find((x) => x.version === "1.16.0").lowN, false);
+    assert.match(renderMarkdown(agg()), /low-n/);
+  });
+  it("agrees with scripts/cost-report.sh on the same logs", { skip: spawnSync("jq", ["--version"]).status !== 0 }, () => {
+    writeFileSync(join(td, "rel.txt"), "");
+    const out = spawnSync("bash", [join(here, "..", "..", "scripts", "cost-report.sh"), "--runs-dir", fx("runs"), "--release-times", join(td, "rel.txt")], { encoding: "utf8" }).stdout;
+    const row = out.split("\n").find((l) => l.startsWith("| 1.16.0 |"));
+    assert.ok(row?.includes("| 4500k |"), row);
+    assert.ok(row?.includes("| 9000k |"), row);
+  });
+  it("--since filters by version or date", () => {
+    assert.deepEqual(agg({ ...parseSince("1.17.0") }).groups.map((g) => g.version), ["1.17.0"]);
+    assert.ok(agg({ ...parseSince("2026-10-03") }).groups.every((g) => g.version !== "1.16.0"));
+  });
+  it("estimates versions of unversioned records from release times", () => {
+    const r = aggregate({ runs: runs().filter((x) => x.issue === 105) }, { releaseTimes: [{ v: "1.15.0", t: 1 }] });
+    assert.equal(r.groups[0].version, "1.15.0~");
+  });
+});
+
+describe("n/a degradation and rendering", () => {
+  it("renders n/a, never NaN or undefined, for missing data and empty input", () => {
+    const old = { source: "local", repo: "o/r", version: "1.0.0", issue: 1, finished: true, hydrated: false, usageEvents: 1, reason: "merged", code: null, remediated: false, phases: { build: { cr: 10, out: 0, usd: null, ms: null, attempts: 1 } } };
+    const r = aggregate({ runs: [old] });
+    const md = renderMarkdown(r);
+    assert.match(md, /n\/a/);
+    assert.doesNotMatch(md, /NaN|undefined|Infinity/);
+    assert.doesNotMatch(renderCompact(r), /NaN|undefined/);
+    assert.match(renderMarkdown(aggregate({})), /No data/);
+    assert.equal(percentile([], 90), null);
+  });
+  it("json output is parseable and carries every section", () => {
+    const { gh } = fakeGh();
+    const report = 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);
+    for (const h of ["### Cost", "### Time", "### Flow", "### Review funnel", "### Gates", "### Issue flow"]) assert.ok(md.includes(h), h);
+  });
+  it("orders versions numerically", () => {
+    assert.ok(compareVersions("1.9.0", "1.10.0") < 0);
+    assert.ok(compareVersions("1.10.0~", "1.10.0") === 0);
+  });
+});
+
+describe("cache", () => {
+  it("refreshes incrementally from the updated_at watermark and survives deletion or corruption", () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache") };
+    const a = fakeGh();
+    const first = 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 });
+    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 });
+    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 });
+    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;
+    };
+    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/);
+    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.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());
+  });
+  it("never skips an item updated mid-crawl (keyset crawl, not page-number pagination)", () => {
+    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/"));
+      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 = 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 });
+    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", () => {
+    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) => {
+      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);
+  });
+  it("rejects an unsafe repo before any gh call", () => {
+    const { gh, calls } = fakeGh();
+    assert.throws(() => fetchGithubRecords({ repo: "o/r; rm -rf /", gh }), /invalid repo/);
+    assert.equal(calls.length, 0);
+  });
+});
+
+describe("cli", () => {
+  it("parses flags and rejects bad input", () => {
+    const o = parseArgs(["--since", "1.2.0", "--repo=o/r", "--json", "--refresh", "--min-n", "3"]);
+    assert.deepEqual([o.since, o.repo, o.json, o.refresh, o.minN], ["1.2.0", "o/r", true, true, 3]);
+    assert.throws(() => parseArgs(["--since"]), /needs a value/);
+    assert.throws(() => parseArgs(["--bogus"]), /unknown argument/);
+    assert.throws(() => parseSince("yesterday"), /--since must be/);
+  });
+  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);
+    assert.match(r.stdout, /--since/);
+    assert.match(r.stdout, /--refresh/);
+  });
+  it("runStats returns 2 for an unusable repo", async () => {
+    const real = process.stderr.write;
+    process.stderr.write = () => true;
+    try { assert.equal(await runStats(["--repo", "bad repo"]), 2); } finally { process.stderr.write = real; }
+  });
+});

package/commands/cleanup.md

@@ -10,7 +10,7 @@ install: extras
 
 **Input**: $ARGUMENTS
 
-Scan the entire development environment for rot and fix it. This is a maintenance command — run periodically or after large orchestration batches. It covers 6 domains: stale labels, orphaned issues, worktree/branch pruning, milestone hygiene, and Project board sync.
+Scan the entire development environment for rot and fix it. This is a maintenance command — run periodically or after large orchestration batches. It covers 6 domains: stale labels, orphaned issues and dead claims boards, worktree/branch pruning, milestone hygiene, and Project board sync.
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
@@ -46,7 +46,7 @@ All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD
 | Input | Action |
 |-------|--------|
 | `labels` or empty | Fix stale/missing workflow labels on closed issues; detect OPEN issues stuck in intermediate states (Phase 1D) |
-| `orphans` | Close open issues whose PRs are already merged |
+| `orphans` | Close open issues whose PRs are already merged (Phase 2A/2B), and close dead orchestrate claims boards (Phase 2C) |
 | `branches` | Prune worktrees and remote branches for merged PRs |
 | `milestones` | Report milestones with 0 open issues (advisory — never closes) |
 | `board` | Sync closed issues to Project board with correct terminal state |
@@ -234,6 +234,89 @@ gh issue edit $NUM {GH_FLAG} --remove-label "workflow:in-review,workflow:remedia
 
 Also check open issues with `workflow:building` — same pattern (search for merged PRs referencing them).
 
+### 2C: Close dead orchestrate claims boards <!-- Added: forge#3699 -->
+
+Each `/orchestrate` batch creates one claims board (`orchestrate: claims board for batch <id>`, label `automation`) with no PR of its own, so 2A/2B never match it. `/orchestrate` Phase 5 Step 5C closes the board on a clean finish; batches that end by compaction, freeze, crash or a fresh-context resume never reach it. This sweep is the durable safety net. Runs for `orphans` and `all`; respects `DRY_RUN`.
+
+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`.
+- Never close a board whose last lease event is an unreleased `FORGE:LEASE` younger than `BOARD_STALE_HOURS`.
+
+```bash
+BOARD_STALE_HOURS=${BOARD_STALE_HOURS:-6}
+BOARD_CUTOFF=$(date -u -d "${BOARD_STALE_HOURS} hours ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || date -u -v-${BOARD_STALE_HOURS}H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || echo "")
+BOARDS_CLOSED=0
+
+if [ -z "$BOARD_CUTOFF" ]; then
+  echo "WARNING: cannot compute BOARD_STALE_HOURS cutoff — only released boards will be closed"
+fi
+
+# REST (not `gh issue list`): it exposes author_association and user.type. Boards are created by the
+# pipeline's GitHub App, which GitHub reports as CONTRIBUTOR, so trust is the same predicate as
+# scripts/trusted-comments.sh: OWNER/MEMBER/COLLABORATOR or a Bot account.
+BOARDS=$(gh api --paginate "repos/{GH_REPO}/issues?state=open&labels=automation&per_page=100" 2>/dev/null \
+  | jq -rs '.[][] | select(.pull_request == null)
+         | select(((.title // "") | startswith("orchestrate: claims board for batch"))
+                  and ((.body // "") | contains("<!-- FORGE:COORD_ISSUE -->"))
+                  and (((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")) or ((.user.type // "") == "Bot")))
+         | "\(.number)\t\(.created_at)"' 2>/dev/null || echo "")
+
+while IFS=$'\t' read -r BNUM BCREATED; do
+  [ -z "$BNUM" ] && continue
+
+  # --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((((.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((((.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
+    REASON="last lease event is FORGE:LEASE_RELEASED"
+  elif [ -n "$BOARD_CUTOFF" ]; then
+    # ISO-8601 UTC timestamps compare correctly as strings
+    LAST_SEEN="${LAST_ACTIVITY:-$BCREATED}"
+    if [ -n "$LAST_SEEN" ] && [ "$LAST_SEEN" \< "$BOARD_CUTOFF" ]; then
+      REASON="no lease/claim activity since ${LAST_SEEN} (older than ${BOARD_STALE_HOURS}h)"
+    fi
+  fi
+
+  if [ -z "$REASON" ]; then
+    echo "KEEP: board #$BNUM has a live or recent lease"
+    continue
+  fi
+
+  if [ "${DRY_RUN:-false}" = "true" ]; then
+    echo "DRY-RUN: would close claims board #$BNUM — $REASON"
+    continue
+  fi
+
+  # Closing an already-closed issue is a no-op; a gh failure is non-fatal.
+  gh issue close "$BNUM" {GH_FLAG} --comment "Closing dead claims board — ${REASON}.
+
+Closed automatically by \`/cleanup\` Phase 2C." 2>/dev/null \
+    && { echo "Closed claims board #$BNUM ($REASON)"; BOARDS_CLOSED=$((BOARDS_CLOSED + 1)); } \
+    || echo "WARNING: failed to close claims board #$BNUM — non-fatal" # allowlist:check-command-side-effects
+done <<< "$BOARDS"
+
+echo "Claims boards closed: $BOARDS_CLOSED"
+```
+
 ---
 
 ## Phase 3: Worktree & Branch Pruning
@@ -599,6 +682,11 @@ fi
 |-------|-----------|--------|
 | #{N} | PR #{M} | Closed |
 
+### Claims Boards Closed
+| Issue | Reason | Action |
+|-------|--------|--------|
+| #{N} | LEASE_RELEASED / stale > {BOARD_STALE_HOURS}h | Closed |
+
 ### Worktrees & Branches Pruned
 | Type | Count |
 |------|-------|

package/commands/deploy-info.md

@@ -56,13 +56,15 @@ else
   # Step 2: Check for open review-finding issues referencing each PR
   OPEN_FINDINGS_SUMMARY=""
   for pr_num in $ALL_PR_NUMBERS; do
+    # Anchored post-filter (same as review-pr-staging.md): the search is a coarse candidate fetch only
+    FINDING_PR_FILTER='[.[] | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
     OPEN_FINDINGS=$(gh issue list -R {GH_REPO} \
       --label "review-finding" \
       --state open \
       --search "PR #${pr_num}" \
       --limit 20 \
-      --json number,title \
-      --jq ".[] | \"  - #\(.number): \(.title)\"" 2>/dev/null)
+      --json number,title,body 2>/dev/null \
+      | jq -r --arg n "${pr_num}" "$FINDING_PR_FILTER" 2>/dev/null)  # uses FINDING_PR_FILTER
 
     if [ -n "$OPEN_FINDINGS" ]; then
       OPEN_FINDINGS_SUMMARY="${OPEN_FINDINGS_SUMMARY}
@@ -304,13 +306,15 @@ if [ -z "$TRAIN_PR_NUMBER" ]; then
   TRAIN_STATUS="NO_TRAIN — no open staging→main PR. Run /review-pr-staging to open one."
 else
   # Step 2: Check whether the train is held (has blocking findings)
+  # Anchored post-filter (same as review-pr-staging.md): the search is a coarse candidate fetch only
+  FINDING_PR_FILTER='[.[] | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
   HELD_BY=$(gh issue list {GH_FLAG} \
     --label "review-finding" \
     --state open \
     --search "PR #${TRAIN_PR_NUMBER}" \
     --limit 20 \
-    --json number,title \
-    --jq '[.[] | "#\(.number): \(.title)"] | join("\n")' 2>/dev/null || true)
+    --json number,title,body 2>/dev/null \
+    | jq -r --arg n "${TRAIN_PR_NUMBER}" "$FINDING_PR_FILTER" 2>/dev/null | sed 's/^  - //' || true)  # uses FINDING_PR_FILTER
 
   if [ -n "$HELD_BY" ]; then
     TRAIN_STATUS="HELD"

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"