feat(github): cache PR reviews with webhook-based invalidation

[JSONbored]

Advances #2537

Problem

The head-SHA file cache (#2527) deliberately left GET /pulls/{n}/reviews uncached ("reviews are more volatile than files" — true at a fixed head, but reviews only actually change on a pull_request_review webhook, not on every sweep tick). Live rate-limit observation flagged this as one of the largest remaining contributors to REST call volume.

Changes

• New migration 0094_pull_request_reviews_invalidated.sql: purely additive reviews_invalidated_at column on pull_request_detail_sync_state.
• fetchAndStorePullRequestDetails (src/github/backfill.ts) now skips the reviews fetch when a prior sync already covers every review-invalidating event: reviewsSyncedAt is compared against reviewsInvalidatedAt (not headSha, since reviews are independent of the head — the core distinction from the files cache). A row whose last review sync itself failed is excluded from the cache-hit path so a transient failure can't poison the cache into never retrying.
• New markPullRequestReviewsInvalidated (src/db/repositories.ts), called from the webhook handler on a pull_request_review event with action submitted/dismissed/edited — best-effort, never blocks the webhook.
• Broadened the existing sync-state row lookup (previously gated on !forceFiles && headSha) since review caching never depends on headSha or the files-only forceFiles flag — the old gate would have silently disabled review caching whenever headSha was momentarily unknown.

Scope decision: bare PR-state caching deferred

Issue #2537 also asked for a cache on bare PR-state reads (state/mergeable_state/head SHA). After auditing every live-PR-read call site in the codebase, each one turned out to be a documented act-boundary or freshness-guard that intentionally requires a live, uncached read:

• src/services/agent-action-executor.ts's freshness guard: "every supported live action mutates PR state... it must still target the reviewed, open head" — runs immediately before every merge/close/approve/label mutation.
• The draft-dodge-close and reopen-reclose re-checks in src/queue/processors.ts, both explicitly commented "Live re-check... re-verify immediately before the mutation."
• The @gittensory gate-override command's head-SHA refresh — security-sensitive, human-triggered, wants the literal current commit.
• The scheduled sweep-resync path — explicitly exists to catch a lost webhook; caching it would be self-defeating.
• mergeable_state already has per-pass caching via the existing LiveGithubFacts/cachedLiveMergeState mechanism.

Caching any of these would risk exactly the regression issue #2537's own acceptance criteria forbids ("No regression in any decision that depends on a live PR state"). Rather than force-fit a cache onto call sites that don't have safe surface area for one, I'm filing this as a follow-up with the reasoning documented here, and shipping only the reviews cache, which has no such risk.

Test plan

• npm run db:migrations:check — 97 migrations OK, contiguous through 0094
• npm run typecheck clean
• npm run test:coverage (unsharded) green, 100% branch coverage on all new/changed lines
• npm audit --audit-level=moderate — 0 vulnerabilities
• New tests: cache miss on first sync; cache hit skips the real fetch and leaves existing review rows untouched; invalidation forces a re-fetch; reviews stay cached across a head-SHA change (the core distinguishing behavior vs. files); a previously-failed review sync is never treated as a valid cache hit; markPullRequestReviewsInvalidated creates a row when absent and updates only its own column when one exists; webhook hook fires on submitted/dismissed/edited and not on an unrelated action

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-02 22:18:27 UTC}

8 files · 1 AI reviewer · 1 blocker · readiness 91/100 · CI green · blocked

⏸️ Suggested Action - Manual Review

• Possible leaked secret in the diff (generic_secret_assignment) — Remove the secret from the diff, rotate the exposed credential, then re-run the gate.

Review summary
The change adds a schema-backed review invalidation timestamp, wires webhook invalidation for review submit/dismiss/edit events, and changes detail backfill to reuse cached review rows only when the last successful review sync strictly postdates the invalidation marker. The main cache decision is correctly separated from head SHA and force-files behavior, and the migration/schema/repository parity is present. The most notable detail is the conservative timestamp handling around racing invalidations, which keeps ties stale instead of treating them as fresh.

Nits — 5 non-blocking

• nit: `src/db/repositories.ts:1174` puts a long design note inside the repository function; consider shortening the comment and moving the historical rationale to the PR/tests so the data-access layer stays easier to scan.
• nit: `test/unit/backfill-reviews-cache-scoping.test.ts` uses very large inline fixtures and repeated repo/PR setup; a small helper for seeded PR plus sync-state would make the regression cases easier to audit without changing coverage.
• nit: `src/github/backfill.ts:1998` relies on lexicographic ISO timestamp comparison; this is valid for `nowIso()` output, but a short helper name like `isReviewCacheFresh` would centralize that assumption and make future timestamp-format changes less risky.
• In `src/github/backfill.ts`, extract the `reviewsUpToDate` comparison into a small helper covered by the cache-hit, stale-invalidation, and equality/tie cases already present in `test/unit/backfill-reviews-cache-scoping.test.ts`.
• In `test/unit/backfill-reviews-cache-scoping.test.ts`, factor the repeated `seedRegisteredRepo` + `upsertPullRequestFromGitHub` + sync-state setup into focused helpers so the race and failure regressions stand out.

Concerns raised — review before merging

• Possible leaked secret in the diff (generic_secret_assignment) — Remove the secret from the diff, rotate the exposed credential, then re-run the gate.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (size label size:L; no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 64 registered-repo PR(s), 55 merged, 522 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 64 PR(s), 522 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 64 PR(s), 522 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• No action.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.06%. Comparing base (23f3a66) to head (5042e60).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2633   +/-   ##
=======================================
  Coverage   96.05%   96.06%           
=======================================
  Files         234      234           
  Lines       26280    26299   +19     
  Branches     9531     9535    +4     
=======================================
+ Hits        25244    25264   +20     
  Misses        425      425           
+ Partials      611      610    -1     

Files with missing lines	Coverage Δ
src/db/repositories.ts	96.57% <100.00%> (+0.02%)	⬆️
src/db/schema.ts	69.46% <ø> (ø)
src/github/backfill.ts	96.79% <100.00%> (+0.02%)	⬆️
src/queue/processors.ts	92.34% <100.00%> (+0.06%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.