chore(selfhost): beta-stable release readiness roadmap

[JSONbored]

Goal

Prepare Gittensory self-host for a beta-stable release candidate that other teams can safely run, without sharing our GitHub token budget or creating recurring rate-limit stalls.

Current state

The current self-host stack is functional and recently redeployed from main, with Redis, Qdrant, queue admission, scheduler backpressure, webhook coalescing, cache metrics, and observability improvements in place. The system now avoids blindly retrying into exhausted GitHub buckets, but rate-limit pressure can still park jobs for minutes at a time.

That means the next milestone is not simply more retry logic. The beta-stable milestone must reduce unnecessary GitHub work at the source, make token ownership explicit for external self-hosters, publish an image-first release path, and document exactly how operators should run, observe, and troubleshoot the stack.

Release target

Ship a beta/RC self-host image suitable for early external operators.

Recommended channel:

• orb-v0.1.0-rc.1 or equivalent prerelease image tag
• GitHub Release marked prerelease
• no stable claim until rate-limit behavior, docs, and onboarding have survived real external usage

Non-negotiables

• External self-hosters must use their own GitHub App installation tokens by default.
• Orb telemetry must remain available without routing all GitHub API calls through our central broker.
• Brokered Orb token mode must be explicitly managed/private-beta only.
• The default compose/env path must be image-first and safe for first-time operators.
• The queue must keep moving without wasteful polling or duplicate scheduled work.
• Rate-limit metrics must identify whether pressure comes from webhooks, background regates, status reads, brokered calls, or operator misconfiguration.
• Documentation must match the shipped image and defaults.

Child issues

• ci(release): support prerelease self-host image tags #1937
• docs(selfhost): make beta onboarding image-first #1938
• docs(orb): separate telemetry from token brokerage #1939
• fix(github): complete budget attribution for rate-limit admission #1940
• feat(github): collapse status reads with GraphQL rollups #1941
• fix(queue): eliminate duplicate scheduled work and gate jitter #1942
• docs(ops): finish self-host rate-limit dashboards and runbooks #1943
• test(selfhost): add beta smoke matrix and release checklist #1944
• perf(scheduler): phase-spread and backpressure the whole hourly job fan-out #1948 (net-new from rate-limit audit: temporal load-smoothing)
• fix(queue): coalesce scheduled RAG full re-index over pending webhook incrementals #1949 (net-new: coalesce scheduled RAG re-index over webhook incrementals)
• fix(orb): backoff + per-tick cap on retry-orb-relay fleet drains #1950 (net-new: backoff/cap on retry-orb-relay fleet drains)
• fix(selfhost): cap historical PR file hydration and cache by head SHA #2527 (net-new: scope PR-file hydration to the current review-critical set, cache by head SHA)
• fix(selfhost): wire alerting to reach an operator by default + close dead-letter blind spot #2533 (net-new from second-pass reliability audit: alerting reaches an operator by default + dead-letter blind spot)
• feat(selfhost): add automatic dead-letter job retry for self-host queues #2534 (net-new: automatic dead-letter job retry for self-host queues)
• chore(selfhost): automate Docker disk hygiene for the self-host stack #2535 (net-new: automate Docker disk hygiene)
• fix(selfhost): make the Postgres connection pool size operator-tunable #2536 (net-new: operator-tunable Postgres pool size)
• feat(github): extend the head-SHA snapshot cache to live PR reads and reviews #2537 (net-new: extend head-SHA cache to live PR reads + reviews)
• fix(github): key the GitHub response cache by installation identity, not the raw token #2538 (net-new: key the GitHub response cache by installation identity, not raw token)
• fix(github): close the remaining CI-status re-fetch gap outside the shared live-facts cache #2539 (net-new: close remaining CI-status re-fetch gap outside feat(github): collapse status reads with GraphQL rollups #1941's shared cache)
• fix(selfhost): validate AI reviewer-provider configuration and add a failure circuit breaker #2540 (net-new: validate AI reviewer-provider config + failure circuit breaker)
• feat(selfhost): add a per-analyzer circuit breaker to review-enrichment #2541 (net-new: per-analyzer circuit breaker in review-enrichment)
• docs(selfhost): close first-run onboarding gaps for admin access and GitHub App setup #2542 (net-new: close first-run onboarding gaps for admin access + GitHub App setup)
• perf(selfhost): tune Postgres autovacuum and batch the rate-limit observation writes #2543 (net-new: tune Postgres autovacuum + batch rate-limit observation writes)
• feat(gate): re-check migration-file collisions against live main before merge #2550 (net-new from self-host review-gap audit: re-check migration-file collisions against live main before merge)
• feat(gate): detect same-table/same-column collisions across differently-numbered migrations #2551 (net-new: detect same-table/same-column collisions across differently-numbered migrations)
• feat(gate): force a fresh rebase + CI recheck immediately before merge when base has advanced #2552 (net-new: force a fresh rebase + CI recheck immediately before merge when base has advanced)
• fix(review): widen the gate's hard-blocking secret scan to match REES's richer ruleset #2553 (net-new: widen the gate's hard-blocking secret scan to match REES's richer ruleset)
• docs(config): document 4 real gate knobs missing from .gittensory.yml.example #2554 (net-new: document 4 real gate knobs missing from .gittensory.yml.example)
• fix(config): wire badgeEnabled into the .gittensory.yml manifest parser #2555 (net-new: wire badgeEnabled into the .gittensory.yml manifest parser)
• fix(openapi): add 11 missing RepositorySettings fields + a structural-drift CI check #2556 (net-new: add 11 missing RepositorySettings fields to the OpenAPI schema + a structural-drift CI check)
• feat(ci): add a cf-typegen staleness check for worker-configuration.d.ts #2557 (net-new: add a cf-typegen staleness check for worker-configuration.d.ts)
• feat(review): surface the deterministic test-evidence classifier in the AI review prompt #2558 (net-new: surface the deterministic test-evidence classifier in the AI review prompt)
• feat(review): add a performance-regression instruction to the AI review system prompt #2559 (net-new: add a performance-regression instruction to the AI review system prompt)
• feat(agent-actions): generalize the review-nag cooldown into a per-command rate limit #2560 (net-new: generalize the review-nag cooldown into a per-command rate limit)
• feat(agent-actions): add an account-age throttle for ban-evasion #2561 (net-new: add an account-age throttle for ban-evasion)
• feat(agent-actions): add an install-wide contributor open-item cap across repos #2562 (net-new: add an install-wide contributor open-item cap across repos)
• feat(gate): add a lockfile-tamper-risk check #2563 (net-new: add a lockfile-tamper-risk check)
• feat(gate): add a CLA / license-compatibility gate dimension #2564 (net-new: add a CLA / license-compatibility gate dimension)
• chore(db): investigate a schema-vs-migrations drift guard #2565 (net-new: investigate a schema-vs-migrations drift guard)
• feat(review): add a security-focused review profile #2566 (net-new: add a security-focused review profile)
• feat(config): expose the dual-AI combine strategy as a per-repo .gittensory.yml setting #2567 (net-new: expose the dual-AI combine strategy as a per-repo .gittensory.yml setting)
• feat(site): add a public per-repo review-quality leaderboard #2568 (net-new: add a public per-repo review-quality leaderboard)
• chore(selfhost): investigate duplicate check-run surfaces in one-shot review mode #2691 (net-new: investigate duplicate check-run surfaces — Orb Review Agent vs Gittensory Context — in one-shot mode)

Three-hour execution order

1. Finish fix(github): complete budget attribution for rate-limit admission #1940 and feat(github): collapse status reads with GraphQL rollups #1941 first: these are the highest-impact rate-limit elimination tracks.
2. Finish fix(queue): eliminate duplicate scheduled work and gate jitter #1942 next: this prevents scheduler and gate jitter from recreating unnecessary work.
3. Finish ci(release): support prerelease self-host image tags #1937, docs(selfhost): make beta onboarding image-first #1938, and docs(orb): separate telemetry from token brokerage #1939 next: these turn the runtime into a safe beta release path for external operators.
4. Finish docs(ops): finish self-host rate-limit dashboards and runbooks #1943 and test(selfhost): add beta smoke matrix and release checklist #1944 before publishing the beta image: these make the release operable and testable.

Second-pass priority order (reliability + rate-limit audit)

A live-system audit (VPS queue/DB/rate-limit data + error telemetry + an 8-way codebase deep-dive) surfaced the following, now tracked as #2533-#2543 above. #2527 (merged) already addressed the single largest GitHub-budget driver found (uncapped historical merged-PR file hydration). Suggested execution order for the rest, grouped by why they're sequenced this way:

1. fix(selfhost): wire alerting to reach an operator by default + close dead-letter blind spot #2533, chore(selfhost): automate Docker disk hygiene for the self-host stack #2535, feat(selfhost): add automatic dead-letter job retry for self-host queues #2534, fix(selfhost): make the Postgres connection pool size operator-tunable #2536 — operational blind spots and cliff-edges first: if any later fix regresses something, these are what let us find out. Includes the alerting/dead-letter gap, Docker disk hygiene, dead-letter auto-retry, and Postgres pool sizing.
2. fix(github): key the GitHub response cache by installation identity, not the raw token #2538 — stabilize the GitHub response-cache key before adding more caches on top of a leaky one; this is a multiplier for every other GitHub-budget fix.
3. feat(github): extend the head-SHA snapshot cache to live PR reads and reviews #2537, fix(github): close the remaining CI-status re-fetch gap outside the shared live-facts cache #2539 — extend the fix(selfhost): cap historical PR file hydration and cache by head SHA #2527 caching pattern to the next-largest GitHub REST routes (bare PR reads, reviews, remaining CI-status re-fetches).
4. fix(selfhost): validate AI reviewer-provider configuration and add a failure circuit breaker #2540, feat(selfhost): add a per-analyzer circuit breaker to review-enrichment #2541 — AI-review and review-enrichment reliability: provider-config validation, circuit breakers, and observability.
5. docs(selfhost): close first-run onboarding gaps for admin access and GitHub App setup #2542 — first-run onboarding doc/config gaps, lower urgency, can proceed opportunistically.
6. perf(selfhost): tune Postgres autovacuum and batch the rate-limit observation writes #2543 — DB scale tuning, deferred until real 10x-scale signal, not urgent today.

Third-pass priority order (self-host review-gap audit)

An 8-lens audit of the self-host PR/issue review-gate system (gate rule dimensions, AI review capabilities, anti-abuse mechanisms, self-host ops, merge-time race conditions, competitive parity, config-as-code parity, and already-tracked roadmap work — cross-checked against open issues to avoid duplicates) surfaced the following, now tracked as #2550-#2568 above. This audit was directly triggered by a real production incident: PR #2479 and PR #2527 independently claimed migration number 0090, both merged clean, and only PR #2532's reactive patch caught it — the 4th occurrence of this exact bug class in project history. Suggested execution order:

1. feat(gate): re-check migration-file collisions against live main before merge #2550, feat(gate): force a fresh rebase + CI recheck immediately before merge when base has advanced #2552 — the merge-race-condition fixes are the most urgent: this is a proven, currently-recurring failure with zero systemic fix in flight (only the fix(migrations): grandfather the shipped 0090 duplicate #2532 one-off patch exists). feat(gate): detect same-table/same-column collisions across differently-numbered migrations #2551 (column-collision detection) is a smaller, cheaper companion — same category, quieter failure mode (no CI signal at all until deploy time).
2. fix(review): widen the gate's hard-blocking secret scan to match REES's richer ruleset #2553 — widen the gate's hard-blocking secret scan; high impact, small effort, security-critical, and the richer rule set already exists in review-enrichment/src/analyzers/secret-scan.ts — this is a wiring fix, not new detection work.
3. docs(config): document 4 real gate knobs missing from .gittensory.yml.example #2554, fix(config): wire badgeEnabled into the .gittensory.yml manifest parser #2555, fix(openapi): add 11 missing RepositorySettings fields + a structural-drift CI check #2556, feat(ci): add a cf-typegen staleness check for worker-configuration.d.ts #2557 — config-as-code parity quick wins: cheap, mechanical, closes silent drift between documented/DB/type/OpenAPI surfaces (the same class of bug the gate itself caught on feat(settings): add contributorOpenPrCap/contributorOpenIssueCap config (#2270) #2467).
4. feat(agent-actions): generalize the review-nag cooldown into a per-command rate limit #2560, feat(agent-actions): add an account-age throttle for ban-evasion #2561, feat(agent-actions): add an install-wide contributor open-item cap across repos #2562 — anti-abuse hardening, directly informed by the review-nag/moderation-system design discussion: generalizing the review-nag cooldown pattern to the full command surface, an account-age throttle as a cheap first step against ban-evasion, and an install-wide contributor cap for multi-repo self-host operators.
5. feat(review): surface the deterministic test-evidence classifier in the AI review prompt #2558, feat(review): add a performance-regression instruction to the AI review system prompt #2559 — small, cheap AI-review prompt improvements (test-evidence context, performance-regression instruction) — pure wiring/prompt-engineering, no new infra.
6. feat(gate): add a lockfile-tamper-risk check #2563, feat(gate): add a CLA / license-compatibility gate dimension #2564, chore(db): investigate a schema-vs-migrations drift guard #2565, feat(review): add a security-focused review profile #2566, feat(config): expose the dual-AI combine strategy as a per-repo .gittensory.yml setting #2567, feat(site): add a public per-repo review-quality leaderboard #2568 — lower-priority/speculative: real gaps but no current evidence of urgency (lockfile tamper, CLA/license, schema-drift investigation, security review profile, per-repo AI combine strategy, public quality leaderboard). Proceed opportunistically after the above.

(Several audit findings were already tracked elsewhere and are NOT duplicated here — cross-referenced for visibility: plagiarism/copycat detection (#1969), CI-run cancellation on contributor_cap/blacklist close (#2462), AI-generated inline suggestion rendering (#2139/#2140/#2141), review-memory/repeat-false-positive suppression (#1964 + #2178-#2181), changed-files summary table + finding severity taxonomy + reply-threaded Q&A (#2012).)

Done when

• All child issues are complete or explicitly deferred with a release-blocking decision.
• The self-host image can be pulled and started from documented defaults.
• External teams have a documented direct-GitHub-App path that does not use our token budget.
• The dashboard/runbook can explain queue stalls without shelling into the VPS.
• The release candidate has a smoke-tested path for Claude Code, Codex, and one-or-both provider setups.
• The release notes clearly mark the image as beta/RC.

[linear-code]

JSO-2021