feat(review): add fast open-PR reconciliation to catch silently-lost webhooks

[JSONbored]

Summary

Closes #3812 (the new-capability deliverable; the two adjacent zero-trace bug fixes from the same issue already shipped separately).

• Two contributor PRs (fix(signals): classify Rust prost/tonic underscore protobuf stubs as generated #3782, feat(review): add review.auto_merge_summary read-only conditions table (#2051) #3793 on JSONbored/gittensory) had zero trace anywhere — no audit event, no local pull_requests row — for ~2 hours on 2026-07-06, until an operator manually forced a sweep whose open-PR discovery side effect happened to surface them. The only organic re-discovery path, backfillRegisteredRepositories, skips any repo whose sync is "fresh" (up to 6 hours), so a silently-lost webhook could go unnoticed for hours.
• Adds a dedicated, MUCH tighter reconciliation (flag-gated by GITTENSORY_PR_RECONCILIATION, default OFF, every 10 minutes): a cheap list-only GitHub read (GET /pulls?state=open, PR numbers only — never a full detail fetch) diffed against the local pull_requests table for every acting-autonomy repo (the same repo-selection fanOutAgentRegateSweepJobs uses).
• On divergence: emits a structured open_pr_reconciliation_divergence log (Sentry-visible) and a gittensory_open_pr_reconciliation_missing_total{repo=...} counter, then immediately catches up every missing PR number — fetches its full live payload, upserts it, and enqueues a normal agent-regate-pr job, i.e. the exact same pipeline a real "PR opened" webhook would have fed it into (reviewed, labeled, gated like any other PR).
• A registered-but-uninstalled repo is never reconciled (mirrors fix(review): skip open-PR refresh for uninstalled registry repos in the regate sweep #3797/#sweep-uninstalled-budget-waste) since it can never get a per-PR fan-out regardless.
• Fails safe at every level: a catch-up fetch/upsert/enqueue failure is logged and skipped (the next tick retries it); a per-repo scan error is logged and the scan continues; a total scan failure is logged and the function returns an empty result rather than throwing into the queue.
• New reconcile-open-prs job type, wired end-to-end: types.ts, wrangler.jsonc/worker-configuration.d.ts (new flag, regenerated via cf-typegen), env.d.ts (widened test/runtime override, matching every other togglable flag), src/index.ts (10-minute cron enqueue, flag-gated), src/queue/processors.ts (job handler), src/selfhost/maintenance-admission.ts (registered as a deferrable maintenance job type).
• reconcileOpenPullRequests (the list-diff itself) lives in src/github/backfill.ts, reusing that file's existing low-level GitHub-fetch primitives (githubJsonWithHeaders, hasNextPage, repoAdmissionKeyForToken) rather than introducing new ones.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes. (Touches several files because a brand-new job type requires wiring at every one of its standard touch points, per this repo's own per-job-type checklist.)
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics. (This feature emits internal structured logs/metrics only — no public GitHub-facing surface beyond the normal regate pipeline it hands off to.)
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A — no auth/session/CORS surface touched.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — no API/OpenAPI/MCP surface changed; this is an internal queue job.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — backend-only change, no UI touched.)
• Visible UI changes include a UI Evidence section below. (N/A — no visible UI change.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• Flag defaults to OFF, matching every other convergence capability's own default-OFF convention (*-wire.ts pattern) — this PR's deploy is byte-identical until the flag is explicitly set.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-07 02:28:46 UTC}

13 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): src/selfhost/maintenance-admission.ts (matched src/selfhost/**), wrangler.jsonc (matched wrangler.jsonc), wrangler.jsonc (matched **/wrangler.jsonc).

Review summary
Adds a flag-gated (GITTENSORY_PR_RECONCILIATION, default OFF) 10-minute cron job that list-diffs GitHub's open PR numbers against the local pull_requests table for every acting-autonomy repo and catches up any PR number the local table is missing by fetching, upserting, and enqueuing a normal agent-regate-pr job — the same pipeline a real webhook would trigger. The implementation is properly fail-safe at every layer (per-page, per-repo, and top-level try/catch, all logged and non-throwing), correctly excludes registered-but-uninstalled repos from reconciliation, is fully wired end-to-end (types.ts, index.ts cron, queue/processors.ts dispatch, maintenance-admission classification, wrangler.jsonc/worker-configuration.d.ts/env.d.ts), and is thoroughly tested including pagination, partial-failure, and fail-open edge cases. No correctness defects are visible in the diff.

Nits — 7 non-blocking

• src/review/pr-reconciliation.ts catchUpMissingPullRequest calls createInstallationToken separately for every missing PR in a repo instead of once per repo, adding avoidable token-creation calls when several PRs are missing at once.
• src/review/pr-reconciliation.ts watchedRepos and src/github/backfill.ts reconcileOpenPullRequests each independently look up the repository row (via listRepositories and getRepository respectively), a redundant DB read per repo per tick.
• watchedRepos (src/review/pr-reconciliation.ts) nests to depth 5 across the two Map-building loops plus the try/catch — consider extracting the per-repo settings check into a small helper for readability.
• The console.error structured-log calls in pr-reconciliation.ts match the codebase's existing logging convention, but worth confirming these are intentionally treated as production logs (not debug leftovers) given how many were added in one file.
• Cache the installation token per repo (hoist createInstallationToken above the per-PR loop in runOpenPrReconciliation) rather than re-deriving it inside catchUpMissingPullRequest for every missing PR number.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#3812
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 (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 51 registered-repo PR(s), 43 merged, 348 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 51 PR(s), 348 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 51 PR(s), 348 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

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 93.57%. Comparing base (56421ce) to head (58627f0).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3840      +/-   ##
==========================================
+ Coverage   93.56%   93.57%   +0.01%     
==========================================
  Files         339      340       +1     
  Lines       33445    33508      +63     
  Branches    12242    12255      +13     
==========================================
+ Hits        31292    31355      +63     
  Misses       1528     1528              
  Partials      625      625              

Files with missing lines	Coverage Δ
src/github/backfill.ts	96.81% <100.00%> (+0.04%)	⬆️
src/index.ts	94.93% <100.00%> (+0.13%)	⬆️
src/queue/processors.ts	94.53% <100.00%> (+<0.01%)	⬆️
src/review/pr-reconciliation.ts	100.00% <100.00%> (ø)
src/selfhost/maintenance-admission.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

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