feat(review): event-driven re-gate trigger on sibling PR merge

[JSONbored]

Summary

On a genuine PR merge (a pull_request webhook with action: "closed" and a merged_at
timestamp), enqueue a bounded, staggered agent-regate-pr job for each of the repo's other open
PRs. Today nothing proactively re-checks a sibling PR when a merge invalidates its gate verdict
(a newly-conflicting base, a duplicate cluster missing its winner, a linked-issue cap that just
freed up) — it either waits for the next scheduled re-gate sweep tick (bounded to 3 PRs per repo
per ~2-minute tick) or a fresh webhook on that specific PR. This closes that latency gap: a
sibling now gets its verdict refreshed within normal per-PR job latency instead of a full sweep
cycle or more.

An ordinary close without a merge changes nothing on the base branch, so it does not trigger this
fan-out (verified by a dedicated test). The fan-out itself is capped by a new MERGE_WAKE_MAX_PRS
constant (15) — smaller than the existing one-shot ISSUE_WAKE_MAX_PRS (25) budget, since a merge
is a far more frequent trigger than an issue-label change and repeated merges inside one
rate-limit window would otherwise compound. It reuses the caller's already-fetched,
already-bounded (100-row, ascending-by-PR-number) sibling list rather than re-querying, so a repo
with many open PRs cannot turn one merge into an unbounded burst, and the lowest-numbered open
siblings are re-gated first.

Scoped to the same repos the existing re-gate sweep already covers (self-host
convergence-allowlisted OR hosted agent-configured) — this is a latency improvement for repos
already receiving proactive re-gates, not a scope expansion.

Closes #4005

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.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (e.g. Closes #123) — a linked open issue is required for every contributor PR.

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.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A — no auth/cookie/CORS/session changes.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — no API/OpenAPI/MCP surface changed.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — no UI changes.)
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository. (N/A — backend-only change.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (N/A — no public-doc claims affected.)

UI Evidence

N/A — this is a backend-only change to webhook processing (src/queue/processors.ts,
src/settings/agent-sweep.ts); there is no visible UI surface.

Notes

• New constant MERGE_WAKE_MAX_PRS lives in src/settings/agent-sweep.ts alongside its sibling
  fan-out-cap constants (SWEEP_MAX_PRS, ISSUE_WAKE_MAX_PRS) for a single home for this tuning
  knob, with its own REST-budget reasoning documented next to it.
• New logic is purely additive (a new function + one new call site placed directly beside the
  existing maybeEnqueueRagReindexForMergedPr merge-triggered convergence call) — no existing
  lines were reindented or restructured.

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.73%. Comparing base (7794970) to head (5f7e4e8).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4181   +/-   ##
=======================================
  Coverage   93.73%   93.73%           
=======================================
  Files         387      387           
  Lines       36377    36387   +10     
  Branches    13319    13323    +4     
=======================================
+ Hits        34099    34109   +10     
  Misses       1621     1621           
  Partials      657      657           

Files with missing lines	Coverage Δ
src/queue/processors.ts	95.31% <100.00%> (+0.01%)	⬆️
src/settings/agent-sweep.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-08 10:25:06 UTC}

3 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/queue/processors.ts (matched src/queue/**), src/settings/agent-sweep.ts (matched src/settings/agent-sweep.ts).

Review summary
This adds an event-driven sibling re-gate trigger: when a `pull_request` webhook shows a genuine merge (`action === "closed"` with `merged_at` set), it enqueues a bounded, staggered `agent-regate-pr` job for each of the repo's other open PRs, reusing the caller's already-fetched and bounded sibling list rather than re-querying. The merge-only guard mirrors the existing `maybeEnqueueRagReindexForMergedPr` check just above it, the fan-out is capped by a new `MERGE_WAKE_MAX_PRS` (15) constant distinct from `ISSUE_WAKE_MAX_PRS` (25) with a stated rationale for the lower budget, and the failure path is caught and logged without surfacing to the gate. Three tests cover the fan-out, the no-fan-out-on-plain-close case, and the cap being enforced, and all exercise the real webhook-processing path rather than calling the helper directly.

Nits — 7 non-blocking

• src/queue/processors.ts:1735 — the constants `4005` (issue ref, in a comment) and `600` (max stagger delay, in code) are magic numbers; consider naming `600` as a constant (e.g. `MERGE_WAKE_MAX_DELAY_SECONDS`) alongside `MERGE_WAKE_MAX_PRS` in agent-sweep.ts for consistency.
• src/queue/processors.ts:6232 — the `console.error` on enqueue failure is fine and matches the RAG-reindex catch block's convention just above, but confirm this repo's logger convention doesn't prefer a structured logger over raw `console.error` elsewhere in this file.
• The `otherOpenPullRequests` list is asserted (via comment) to be a 100-row, ascending-by-number, already-bounded query reused from the caller — this diff doesn't show that call site, so it's worth confirming the list is indeed already capped at 100 and ascending, since this function's own dedup and cap logic depends entirely on that upstream guarantee.
• test/unit/queue.test.ts — the flagged 'generic_secret_assignment' lines are `GITHUB_APP_PRIVATE_KEY: await generatePrivateKeyPem()`, a generated test keypair, not a real secret; no action needed but worth a quick eyeball to confirm no static key material was pasted.
• Consider extracting the `Math.min(index * 10, 600)` stagger formula into a small named helper or constant since the same shape likely recurs for `ISSUE_WAKE_MAX_PRS`'s fan-out — reduces drift risk if the two budgets' delay curves are ever tuned independently.
• 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	#4005
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: 52 registered-repo PR(s), 43 merged, 486 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 52 PR(s), 486 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Addressed
The diff adds maybeEnqueueSiblingRegateForMergedPr, wired into the pull_request.closed handler in processors.ts, which enqueues agent-regate-pr jobs for other open PRs only when merged_at is set, bounded by a new MERGE_WAKE_MAX_PRS (15) constant reusing the caller's already-bounded sibling list, exactly matching the issue's three requirements. Tests cover the fan-out cap and the merged-vs-closed-o

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: 52 PR(s), 486 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