feat(selfhost): add per-installation GitHub-fetch concurrency admission

[JSONbored]

Summary

PR #2847 ("prioritize live PR work under GitHub rate pressure") explicitly deferred this as needing "a dedicated design pass": QUEUE_BACKGROUND_CONCURRENCY caps how many background jobs run at all, globally — it has no notion of which installation those jobs belong to. Once an operator raises it above the default of 1, one installation's background sweep/backfill can claim every available background slot at once and starve every other installation's background work, even though GitHub's rate-limit admission is nowhere near exhausted for either installation.

This adds a third, per-installation claim-time admission check (alongside GitHub rate-limit admission and maintenance-lane admission), checked only for background jobs that make GitHub calls — never for foreground live-PR work (github-webhook, agent-regate-pr; the latter is exempted by its actual claim-priority, not by job type, since a live regate must never be deferred by this policy regardless of how the rate-limit-budget classifier sees it). A denied job is deferred with jitter, never dropped, mirroring the existing maintenance-admission mechanism's shape and metrics.

Deliberately in-process (a plain per-installation in-flight counter), not DB-backed: the queue's existing active/activeBackground counters are already per-process scalars with no cross-process aggregation, and this mirrors that same, already-supported single-process-per-deployment topology rather than introducing a new coordination mechanism.

New env knobs (documented in .env.example): GITHUB_INSTALLATION_CONCURRENCY_ENABLED (default true), GITHUB_INSTALLATION_CONCURRENCY_LIMIT (default 2), GITHUB_INSTALLATION_CONCURRENCY_DEFER_MS (default 15s).

Generic self-host engine behavior only; no repo-specific logic. Follow-up to a related PR fixing the deferred CI-state snapshot cache is coming separately (independent files, independent risk profile).

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 an issue, or this is small enough that the summary explains why an issue is not needed. (Directly implements a scoped-out follow-up explicitly named in PR fix(queue): prioritize live PR work under GitHub rate pressure #2847's own commit message.)

Validation

• git diff --check
• npm run actionlint (not run — no workflow files touched)
• npm run typecheck
• npm run test:coverage locally (unsharded); precise diff-coverage cross-reference against coverage/coverage-final.json confirms 100% branch coverage on every changed line across all touched src/** files
• npm run test:workers (not run — no Cloudflare-Workers-pool-specific code touched)
• npm run build:mcp / npm run test:mcp-pack (not run — no MCP package changes)
• npm run ui:openapi:check / npm run ui:lint / npm run ui:typecheck / npm run ui:build (not run — no apps/gittensory-ui source or API/OpenAPI surface changes; only the generated env-reference file was regenerated)
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries
• npm run selfhost:env-reference:check (regenerated after adding new env vars)
• npm run db:migrations:check (no migration needed for this PR; confirms 0108 is next-free for a following PR)

If any required check was skipped, explain why:

• Skipped checks above are for UI/MCP/Workers surfaces this PR does not touch (backend-only change to the self-host queue's admission path); CI's validate job runs them as a backstop.

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/session/CORS 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 screenshots. (N/A — no visible UI changes.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (N/A.)

Notes

• The companion deferred feature (a webhook-driven CI-state snapshot cache) is being shipped as a separate, independently-reviewable PR per a design plan covering both — different files, different risk profile, no dependency between them.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	2068381	Commit Preview URL Branch Preview URL	Jul 04 2026, 08:19 AM

[loopover-orb]

Important

🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪

🔍 Gittensory is reviewing…

AI analysis is in progress. This comment will update when the review is complete.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed · 🟪 Reviewing}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.07%. Comparing base (0da1db3) to head (2068381).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2970   +/-   ##
=======================================
  Coverage   96.06%   96.07%           
=======================================
  Files         259      260    +1     
  Lines       28663    28700   +37     
  Branches    10431    10444   +13     
=======================================
+ Hits        27536    27574   +38     
  Misses        490      490           
+ Partials      637      636    -1     

Files with missing lines	Coverage Δ
src/selfhost/installation-concurrency-admission.ts	100.00% <100.00%> (ø)
src/selfhost/metrics.ts	100.00% <ø> (ø)
src/selfhost/queue-common.ts	95.41% <100.00%> (+0.28%)	⬆️
src/selfhost/sqlite-queue.ts	99.58% <100.00%> (+0.01%)	⬆️

🚀 New features to boost your workflow:

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