feat(queue): wire an admin trigger for agent-regate-pr force re-gates

[bitfathers94]

feat(queue): wire an admin trigger for agent-regate-pr force re-gates

Add POST /v1/internal/jobs/regate-pr, a Bearer-gated operator route that
enqueues an agent-regate-pr job with force: true for a specific repo+PR.
Until now the job's force field had no production producer -- every
scheduled/webhook caller left it unset, so the fresh-opinion plumbing
(bypassing the durable review cache and the non-cacheable-reuse cooldown)
was built and tested but unreachable. This gives it a real caller.

The route trims/resolves the repo, 400s a blank repo or non-positive PR
number, and 404s a repo with no known installation. An end-to-end test
asserts the enqueued job carries force: true and that processJob threads
it straight into regatePullRequest.

Closes #8898

Validation

Verified locally on this branch before opening:

• npm run typecheck
• npx turbo run build:tsc build:verify
• npm run test:coverage — patch coverage 100.0% of changed lines

[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 91.02%. Comparing base (6aaea39) to head (8df7950).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8958      +/-   ##
==========================================
+ Coverage   90.56%   91.02%   +0.46%     
==========================================
  Files          96       97       +1     
  Lines       22490    24953    +2463     
  Branches     3884     4677     +793     
==========================================
+ Hits        20367    22713    +2346     
- Misses       1945     1975      +30     
- Partials      178      265      +87     

Flag	Coverage Δ
backend	95.24% <100.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/api/routes.ts	95.24% <100.00%> (ø)

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-26 14:35:48 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a Bearer-gated operator route POST /v1/internal/jobs/regate-pr that enqueues an agent-regate-pr job with force:true, giving the previously-unreachable force plumbing a real production caller. The route correctly trims/validates repoFullName, validates prNumber as a positive integer, 404s on uninstalled repos, and resolves installationId from the stored repo record rather than trusting client input. The included end-to-end test verifies both the enqueue payload and that processJob threads force through to regatePullRequest, which is the right shape of test for this kind of wiring change.

Nits — 5 non-blocking

• src/api/routes.ts: the route is added to the file without visible confirmation that /v1/internal/* paths bypass requiresApiToken's normal token check and instead go through a separate Bearer/INTERNAL_JOB_TOKEN middleware — worth double-checking this route isn't accidentally left open (the comment claims Bearer-gating, and requiresApiToken does return false for /v1/internal/, consistent with a separate internal-token middleware, so this is likely fine).
• HTTP status codes 400/404/202 are inline literals rather than named constants, consistent with the surrounding file's style so not a real deviation.
• No explicit check that repoFullName matches an expected repo-name shape before hitting getRepository — relies entirely on getRepository returning null for garbage input, which appears to be the existing convention elsewhere in this file.
• Consider extracting the manual-trigger route's body validation (repoFullName trim + prNumber positive-integer check) into a small helper if a similar admin trigger is added later, to avoid duplicating this validation shape.
• The JSDoc-style comment on the route is quite long (7 lines) for a single small handler — could be trimmed to the essential Bearer-gating and force-field claims.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#8898
Related work	⚠️ 1 scoped overlap	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High 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: 45 registered-repo PR(s), 37 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	bitfathers94; Gittensor profile; 45 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The PR adds a Bearer-gated POST /v1/internal/jobs/regate-pr route that validates repo/PR inputs and enqueues an agent-regate-pr job with force: true, giving the previously-unreachable force field a real producer as requested. It includes an integration test verifying the job is enqueued with force:true and that processJob threads it into regatePullRequest, satisfying both deliverables.

Review context

• Author: bitfathers94
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript
• Official Gittensor activity: 45 PR(s), 0 issue(s).
• Related work: Titles/paths share 7 meaningful terms. (PR #8967)

Contributor next steps

• Start here: Review top overlaps.
• Then work through the remaining 3 steps in the Signals table above.

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.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.