fix(github): self-heal a stale cached installation token on read-path GitHub calls

[bitfathers94]

fix(github): self-heal a stale cached installation token on read-path GitHub calls

fetchPullRequestFreshness minted an installation token and fed the
(possibly-stale, shared-cache) token straight into fetchLivePullRequestResult
with no retry, so a single 401 was classified status: "stale", reason:
"unavailable" -- failing the reopen-guard/gate-override re-check closed for
what every write helper transparently retries via withInstallationTokenRetry
(#6191).

Route the shared backfill.ts read helpers (fetchLivePullRequestResult,
fetchLiveIssueState, fetchLivePullRequestHeadSha) through
withInstallationTokenRetry when given an installationId: a 401 then evicts the
stale token, re-mints once, and succeeds. Public-token / no-installation reads
omit the id and fetch with the passed token exactly as before.
fetchPullRequestFreshness passes the id only when it actually holds an
installation token.

Closes #8892

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 90.88%. Comparing base (62e6d25) to head (05bd03a).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8995      +/-   ##
==========================================
+ Coverage   90.56%   90.88%   +0.32%     
==========================================
  Files          96       98       +2     
  Lines       22490    23912    +1422     
  Branches     3884     4442     +558     
==========================================
+ Hits        20367    21732    +1365     
- Misses       1945     1952       +7     
- Partials      178      228      +50     

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

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

Files with missing lines	Coverage Δ
src/github/backfill.ts	95.86% <100.00%> (ø)
src/github/pr-freshness.ts	100.00% <100.00%> (ø)

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-26 15:47:25 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR routes three read-path GitHub fetch helpers (fetchLiveIssueState, fetchLivePullRequestHeadSha, fetchLivePullRequestResult) through withInstallationTokenRetry when an installationId is supplied, and fetchPullRequestFreshness now passes its installationId only when it actually minted an installation token (not the public-token fallback). The wiring is correct: withInstallationTokenRetry is imported and used consistently, the public-token/no-installation path is preserved byte-for-byte via the `installationId === undefined` branch, and pr-freshness.ts's `installationToken !== undefined ? args.installationId : undefined` correctly withholds the id when only the public-token fallback is in play. Tests exercise the actual 401-then-retry path with a genuine stale/fresh token store swap and verify the public-token path is unaffected, which is real coverage of the fixed behavior, not a fabricated scenario.

Nits — 4 non-blocking

• The three near-identical `run = (accessToken) => ...; installationId === undefined ? run(token) : withInstallationTokenRetry(...)` blocks in backfill.ts could be factored into one small helper to avoid the repeated ternary shape across fetchLiveIssueState, fetchLivePullRequestHeadSha, and fetchLivePullRequestResult.
• Comments on the three new `installationId` parameters in backfill.ts repeat almost the same explanation verbatim ('See fetchLiveIssueState...') — consider consolidating into a single doc comment on one canonical function and referencing it briefly from the others.
• Consider extracting a tiny `withOptionalInstallationRetry(env, installationId, run, token)` helper in backfill.ts shared by the three read functions to cut duplication.
• The PR is narrowly scoped to the read-path self-heal fix and closes fix(github): read-path GitHub calls in backfill.ts/pr-freshness.ts never self-heal a stale cached installation token #8892 as claimed — no scope creep observed.

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	#8892
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
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 diff routes fetchPullRequestFreshness and the three backfill.ts read helpers (fetchLivePullRequestResult, fetchLiveIssueState, fetchLivePullRequestHeadSha) through withInstallationTokenRetry when an installation token is held, matching the write-path convention, and adds explicit tests (both a new self-heal test file and an added pr-freshness.test.ts case) proving a 401 is retried once with a

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).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Add a concise scope and risk note.
• Then work through the remaining 1 step 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.