fix(orb): wire backfillOrbInstallations to an admin backfill route

[bitfathers94]

fix(orb): wire backfillOrbInstallations to an admin backfill route

The registry reconciliation backfillOrbInstallations promises in its doc
comment -- recovering installs whose installation webhook fired before the
receiver secret was configured -- had no caller anywhere in src/, so the
capability never ran. Expose it through a bearer-gated
POST /v1/internal/orb/installations/backfill admin route alongside the
existing /v1/internal/orb/installations endpoints, returning { backfilled }.

Closes #8882

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.01%. Comparing base (8a3d2c9) to head (36bb958).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8917      +/-   ##
==========================================
- Coverage   93.84%   91.01%   -2.84%     
==========================================
  Files         803       97     -706     
  Lines       80084    24931   -55153     
  Branches    24277     4671   -19606     
==========================================
- Hits        75157    22691   -52466     
+ Misses       3562     1975    -1587     
+ Partials     1365      265    -1100     

Flag	Coverage Δ
backend	95.20% <100.00%> (+0.07%)	⬆️

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.20% <100.00%> (+<0.01%)	⬆️

... and 706 files with indirect coverage changes

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-26 13:43:25 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR wires the previously-dead-code `backfillOrbInstallations` function to a new bearer-gated `POST /v1/internal/orb/installations/backfill` route, matching the pattern of the existing `/v1/internal/orb/installations` endpoints. The route is a one-line handler delegating to the existing function, and the test exercises the real path (stubbing GitHub's list-installations fetch) verifying both the recovered install lands at registered=0 and the already-registered install is untouched, plus a 401 check. This is a narrow, well-targeted fix that closes #8882 exactly as described.

Nits — 4 non-blocking

• The route handler at src/api/routes.ts:4518 doesn't wrap `backfillOrbInstallations` in try/catch — confirm errors thrown there (e.g. GitHub API failure) are handled by a global error middleware rather than crashing unhandled, since the sibling routes shown don't show explicit try/catch either so this is likely consistent with existing convention.
• The new `pkcs8Pem()` test helper generates a fresh RSA keypair per test run (test/integration/orb-onboarding.test.ts:5) — this is a bit slow for a unit/integration test file; consider hoisting it once via `beforeAll` if this test suite runs frequently.
• Consider adding a doc-comment cross-reference from the new route to the `backfillOrbInstallations` JSDoc so future readers land in installations.ts for the full recovery semantics.
• If there's an existing pattern for rate-limiting the internal admin routes against repeated invocation (e.g. this hitting GitHub's API on every call), verify it's not needed here — GitHub app installation-list endpoints are typically low-volume so likely fine.

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	#8882
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: 41 registered-repo PR(s), 32 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	bitfathers94; Gittensor profile; 41 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor

Linked issue satisfaction

Addressed
The PR adds a bearer-gated POST /v1/internal/orb/installations/backfill route that calls backfillOrbInstallations and returns { backfilled }, giving the function a real reachable caller as required, and includes an integration test that stubs GitHub's API to verify a webhook-missed installation is recovered plus an auth-check test.

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: 41 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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.