[Feature]: Cross-repo queue health federation and comparative pressure index

[greatjourney589]

Problem

QueueHealth and QueueTrendReport are computed per-repo in isolation (src/services/burden-forecast.ts, src/services/queue-trends.ts). An operator or maintainer who has multiple registered repositories has no way to see a ranked, comparative view of queue pressure across all of them in a single request. They must call /api/repos/:repo/queue-health N times and manually sort the results.

This creates three concrete failure modes:

1. Triage latency – maintainers with 5+ repos cannot quickly identify which repo is at critical burden level and needs attention first.
2. Trend blindspot – per-repo trend windows (7 d / 14 d / 30 d) cannot be compared laterally; a growing queue in repo A may be invisible while repo B's static queue dominates attention.
3. Operator dashboard gap – src/services/operator-dashboard.ts currently surfaces installation-level counts but not a prioritized queue pressure index, so the weekly value report (src/services/weekly-value-report.ts) cannot include a top-N critical repos metric.

Area

REST API

Proposal

Add a GET /api/queue-health/federation endpoint (secured with the existing private-token auth from src/auth/security.ts) that:

1. Loads all registered, installed repositories via listRepositories in src/db/repositories.ts.
2. Calls loadOrComputeBurdenForecastResponse for each repo (already exists in src/services/burden-forecast.ts) concurrently with Promise.all, respecting the existing 6-hour staleness threshold.
3. Merges per-repo QueueTrendReport windows (from getRepoQueueTrendSnapshot in src/db/repositories.ts) into a single FederatedQueueIndex response shape.
4. Ranks repos by a composite pressure score: burdenScore * (1 + stalePullRequestRate) + pullRequestGrowth_7d.
5. Exposes the top-N (default 10, max 25, controlled by ?limit=) worst repos with their burdenScore, level, stalePullRequestRate, 7-day pullRequestGrowth, and a one-line summary.

New files:

• src/services/queue-federation.ts — buildFederatedQueueIndex(repos, forecasts, trends): FederatedQueueIndex
• migrations/0024_queue_federation_cache.sql — optional queue_federation_snapshots table to cache the federated result (TTL-based, same 6-hour pattern as burden forecast)

Changed files:

• src/api/routes.ts — add route GET /api/queue-health/federation
• src/openapi/schemas.ts — add FederatedQueueIndex, FederatedRepoEntry Zod schemas
• src/openapi/spec.ts — document the new endpoint
• src/services/operator-dashboard.ts — include federated pressure index in operator dashboard payload
• src/services/weekly-value-report.ts — add top_critical_repos metric using the federated index
• src/mcp/server.ts — expose new MCP tool queue_health_federation returning the top-N list
• src/signals/engine.ts — export compositeQueuePressureScore(forecast, trend): number helper consumed by federation

Acceptance criteria

• GET /api/queue-health/federation returns HTTP 200 with a valid FederatedQueueIndex JSON body for an operator with ≥2 registered repos.
• Repos are sorted descending by composite pressure score; level: "critical" repos always appear before level: "high" repos at equal score.
• The endpoint is inaccessible to unauthenticated callers (returns 401) and to contributor-session callers (returns 403).
• The MCP tool queue_health_federation returns the same ranked list as the REST endpoint.
• The weekly value report includes a top_critical_repos metric when ≥1 repo has level: "critical" or level: "high".
• Stale cached forecasts (> 6 hours) are surfaced with freshness: "stale" but are not excluded from the index.
• OpenAPI spec validates against the new schemas with no additional additionalProperties violations.

Test scenarios

• Unit – buildFederatedQueueIndex: given 3 repo forecasts with burden scores 80/50/20 and matching trend windows, assert the ranking order and composite score values.
• Unit – tie-breaking: two repos with identical composite scores but different level values — assert critical sorts above high.
• Unit – missing trend: one repo has no trend snapshot (status: "unavailable") — assert it still appears in the index with pullRequestGrowth: null and does not crash.
• Integration – route auth: unauthenticated request → 401; contributor session → 403; operator token → 200.
• Integration – limit param: ?limit=2 with 5 repos → response contains exactly 2 entries; ?limit=0 → 422.
• Integration – weekly report metric: seeded DB with 1 critical repo → generated report includes top_critical_repos metric with that repo.
• MCP – queue_health_federation: tool call returns structured output matching FederatedQueueIndex schema; forbidden output words (wallet, reward, trust score) absent.
• Public/private boundary: federated index must not include privateTrustEnabled flags, raw trust scores, or per-contributor data.

Boundaries

• This does not restore GitHub Pages, VitePress, site/, or CNAME.
• This does not require storing user PATs or adding a non-GitHub identity provider.
• This does not expose wallet details, raw trust scores, private rankings, or reward estimates publicly.
• This does not auto-close, auto-merge, rewrite contributor work, or label PRs outside the confirmed-miner policy.
• Public GitHub output will be tested against forbidden language (wallet, hotkey, raw trust score, payout, reward estimate, farming, private reviewability, public score estimate).