fix(github): reuse an existing repo-docs branch ref instead of failing (#8310)

[galuis116]

Summary

Closes #8310.

openRepoDocPullRequest always targets the fixed loopover/repo-docs branch (deliberately stable, per the file's header comment, so repeat runs update one PR instead of piling up duplicates). But it only checks for an open PR on that branch before deciding to create the ref:

// src/github/repo-doc-pr.ts:167
const existingOpenPrs = await octokit.request("GET /repos/{owner}/{repo}/pulls", { ..., state: "open", ... });

When a maintainer closes the repo-doc PR without deleting its branch -- GitHub offers a "Delete branch" button but never forces it, and a PR closed via the API or a bot deletes nothing -- the ref survives. The open-only lookup then finds nothing, the function proceeds, and POST /git/refs 422s "Reference already exists". The outer try/catch turns that into { opened: false, reason }, so every subsequent refresh for that repo fails permanently -- both the scheduled sweep and the on-demand loopover_refresh_repo_docs tool.

Change

When the create reports that specific failure, fall back to PATCH /repos/{owner}/{repo}/git/refs/{ref} with { sha: commitSha, force: true }, then continue into the existing PR-open path unchanged. This branch is exclusively owned by this feature and never shared with contributor work, so force-updating it to the freshly built commit is safe.

Deliberately narrow, matching the issue's constraints:

• Only a 422 whose message matches Reference already exists recovers. Any other create-ref failure (e.g. an invalid sha) still propagates to the outer catch's fail-safe, so nothing is silently force-pushed over.
• The "reuse only an OPEN PR" behaviour at line 167 is untouched -- a closed PR still results in a new pull request (reused: false); only the underlying ref is reused.
• Reuses the module's existing githubErrorStatus helper and the shared errorMessage helper rather than hand-rolling status/message extraction.

Tests

• the 422 path force-updates the ref (asserting the PATCH body carries { sha, force: true }) and still opens a fresh PR with reused: false
• an unrelated create-ref 422 issues no PATCH and degrades to opened: false, pinning the fail-safe

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• 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 (Closes #8310).

Validation

• git diff --check
• npm run actionlint - no workflow files touched.
• npm run typecheck
• npx vitest run test/unit/repo-doc-pr.test.ts - 33 pass (was 31).
• Changed-line coverage verified locally with the v8 provider: no uncovered statements and no partial branches on the diff (both arms of the new isRefAlreadyExistsError guard are exercised by the two tests above).
• npm run test:coverage (full) / test:workers / build:mcp / ui:* - not run: this is a scoped change to one backend module plus its unit test, touching no worker, MCP, or UI surface.
• npm audit --audit-level=moderate - no dependency changes.
• New or changed behavior has unit tests for new branches and fallback paths.

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 - no auth logic changes; the write still goes through the same makeInstallationOctokit / withInstallationTokenRetry chokepoint, and the unrelated-failure test is the negative path.
• API/OpenAPI/MCP behavior is updated and tested where needed - no contract change; loopover_refresh_repo_docs simply stops failing on this case.
• UI changes use live API data or real empty/error/loading states - n/a, no UI change.
• Visible UI changes include a UI Evidence section - n/a: no visible UI/frontend/docs/extension change.
• Public docs/changelogs are updated where needed - n/a.

Notes

• The force-update is confined to loopover/repo-docs. Because the recovery is gated on both the 422 status and the "Reference already exists" message, an unrelated 422 can never reach the force: true call.

[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 89.62%. Comparing base (8dffb03) to head (2dc4872).
⚠️ Report is 18 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8474      +/-   ##
==========================================
- Coverage   92.47%   89.62%   -2.86%     
==========================================
  Files         791       98     -693     
  Lines       79321    22792   -56529     
  Branches    23954     3900   -20054     
==========================================
- Hits        73355    20427   -52928     
+ Misses       4839     2187    -2652     
+ Partials     1127      178     -949     

Flag	Coverage Δ
shard-1	53.48% <40.00%> (-4.55%)	⬇️
shard-2	50.00% <40.00%> (-0.09%)	⬇️
shard-3	100.00% <100.00%> (+45.61%)	⬆️

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

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

... and 693 files with indirect coverage changes

[loopover-orb]

This repository reviews pull requests one-shot: the PR must be correct as originally opened. Pushing an additional commit closes it automatically instead of restarting review — open a fresh pull request with every fix included.