Files
archived-orca/src/shared/repo-ref-maintenance.ts
T
OrcaWinandOrcaWin 7d6603aa17 [comment audit] Complete repository-wide comment cleanup (#33249)
* [comment audit] Align legacy failure-read counts with cached display

* [comment audit] Condense shared provider lifecycle and browser recovery comments [skip ci]

* [comment audit] Condense shared generation, path and preview comments [skip ci]

* [comment audit] Condense host, file and Git contract rationale [skip ci]

* [comment audit] Tighten Git lifecycle and provider contract comments [skip ci]

* [comment audit] Clarify shared host authority and launch isolation [skip ci]

* [comment audit] simplify local access mobile and native chat contracts [skip ci]

* [comment audit] simplify native chat presentation and state contracts [skip ci]

* [comment audit] simplify native runtime and provider contracts [skip ci]

* [comment audit] simplify migration and orchestration contracts [skip ci]

* [comment audit] simplify plugin trust and process capture rationale [skip ci]

* [comment audit] simplify terminal delivery and remote compatibility rationale [skip ci]

* [comment audit] clarify remote recovery and launch wire rationale [skip ci]

* [comment audit] shorten shared RPC compatibility and runtime evidence comments [skip ci]

* [comment audit] simplify secure storage shell startup and sidebar rationale [skip ci]

* [comment audit] clarify sidebar, skill and SSH invariants [skip ci]

* [comment audit] condense structured chat delivery and timing rationale [skip ci]

* [comment audit] condense terminal replay and telemetry invariants [skip ci]

* [comment audit] clarify launch permission and terminal delivery rationale [skip ci]

* [comment audit] clarify workspace ownership and layout contracts [skip ci]

* [comment audit] wait for fitted and painted SSH terminal links

* [comment audit] clarify layout persistence and session ownership [skip ci]

* [comment audit] clarify host routing and workspace lifecycle contracts [skip ci]

* [comment audit] clarify startup persistence and app lifetime comments [skip ci]

* [comment audit] clarify recovery and activity boundaries [skip ci]

* [comment audit] condense activity and artifact invariants [skip ci]

* [comment audit] condense automation authority contracts [skip ci]

* [comment audit] simplify automation scheduling and history contracts [skip ci]

* [comment audit] clarify browser chrome and annotation lifecycles [skip ci]

* [comment audit] clarify browser routing and retained guest ownership [skip ci]

* [comment audit] clarify browser recovery and document ownership comments [skip ci]

* [comment audit] restore hosted runners required by native IME fixtures

* [comment audit] shorten preview, palette and dashboard invariants [skip ci]

* [comment audit] clarify terminal preview, dashboard and retention comments [skip ci]

* [comment audit] clarify diff-note recovery and editor lifecycle comments [skip ci]

* [comment audit] shorten rich-text and combined-diff ownership comments [skip ci]

* [comment audit] shorten autosave, draft recovery and model ownership comments [skip ci]

* [comment audit] shorten save-queue, notebook and Markdown constraints [skip ci]

* [comment audit] shorten Monaco, PDF and rich Markdown safeguards [skip ci]

* [comment audit] clarify rich Markdown source and selection safeguards [skip ci]

* [comment audit] clarify editor loading and emulator stream lifetimes [skip ci]

* [comment audit] trim emulator and feature tour narration [skip ci]

* [comment audit] clarify floating workspace and GitHub cache ownership [skip ci]

* [comment audit] trim provider controls and Linear filter explanations [skip ci]

* [comment audit] clarify pairing and chat resume lifetimes [skip ci]

* [comment audit] clarify chat delivery and transcript lifetimes [skip ci]

* [comment audit] clarify session options and host-owned status [skip ci]

* [comment audit] clarify draft durability and live-status precedence [skip ci]

* [comment audit] Trim chat send and model ownership explanations [skip ci]

* [comment audit] Shorten transcript ownership and send recovery comments [skip ci]

* [comment audit] Simplify native chat composer and transcript hook comments [skip ci]

* [comment audit] Shorten native chat scroll and structured session explanations [skip ci]

* [comment audit] Trim workspace picker and onboarding commentary [skip ci]

* [comment audit] Simplify pet rendering, review cache and quick open comments [skip ci]

* [comment audit] Trim sidebar and session history explanations [skip ci]

* [comment audit] Condense session resume and review checks comments [skip ci]

* [comment audit] Shorten checks state and file explorer refresh comments [skip ci]

* [comment audit] Trim plugin bridge and source-control action rationale [skip ci]

* [comment audit] Trim source-control listing and review rationale [skip ci]

* [comment audit] Shorten sidebar lifecycle and explorer safeguards [skip ci]

* [comment audit] Condense Settings account and appearance rationale [skip ci]

* [comment audit] Trim pairing and repository Settings explanations [skip ci]

* [comment audit] Condense Settings search SSH and terminal safeguards [skip ci]

* [comment audit] Shorten Settings voice and provider ownership comments [skip ci]

* [comment audit] Condense Settings draft persistence and host-state rationale [skip ci]

* [comment audit] Trim Settings hooks and sidebar setup rationale [skip ci]

* [comment audit] Condense sidebar deletion and board-filter safeguards [skip ci]

* [comment audit] Condense worktree cards, host ownership and Markdown contracts [skip ci]

* [comment audit] Condense sidebar drag, folder and filtering contracts [skip ci]

* [comment audit] Condense sidebar parity, sleep and host ownership contracts [skip ci]

* [comment audit] Prune focus-read baseline after comment cleanup

* [comment audit] Clarify sidebar visibility, board drops and agent evidence [skip ci]

* [comment audit] Tighten sidebar listing, drag and reveal contracts [skip ci]

* [comment audit] Clarify viewport geometry and skill update safeguards [skip ci]

* [comment audit] Tighten skill inventory, usage and host status comments [skip ci]

* [comment audit] Clarify usage ownership and resource kill safeguards [skip ci]

* [comment audit] Tighten tab selection, rename and search contracts [skip ci]

* [comment audit] Tighten tab-strip geometry and drag ownership comments [skip ci]

* [comment audit] Tighten Tasks recovery, pagination and mutation comments [skip ci]

* [comment audit] Tighten provider loading and terminal recovery comments [skip ci]

* [comment audit] Tighten completion, cadence and PTY ownership comments [skip ci]

* [comment audit] Clarify terminal restore and parked-pane boundaries [skip ci]

* [comment audit] Tighten PTY startup and replay explanations [skip ci]

* [comment audit] Clarify PTY identity and delivery ownership [skip ci]

* [comment audit] Shorten remote reconnect and input replay rationale [skip ci]

* [comment audit] Condense terminal parking clipboard and file link comments [skip ci]

* [comment audit] Clarify IME ownership and trim trace history [skip ci]

* [comment audit] Shorten pane recovery and parked watcher explanations [skip ci]

* [comment audit] Condense snapshot replay and visibility recovery rationale [skip ci]

* [comment audit] Shorten terminal parking and keyboard ownership rationale [skip ci]

* [comment audit] Trim renderer lifecycle and menu rationale [skip ci]

* [comment audit] Condense workspace cleanup ownership and settlement notes [skip ci]

* [comment audit] Clarify renderer hook evidence and source ownership [skip ci]

* [comment audit] Tighten IPC ownership and reconnect explanations [skip ci]

* [comment audit] Trim renderer focus, paste and attention comments [skip ci]

* [comment audit] Shorten scroll, locale and agent lifecycle comments [skip ci]

* [comment audit] Trim agent launch, resume and ownership commentary [skip ci]

* [comment audit] Shorten account, browser and editor comments [skip ci]

* [comment audit] Clarify host-mirror waits, previews and input ownership [skip ci]

* [comment audit] Condense launch recovery and editor tokenization comments [skip ci]

* [comment audit] Condense workspace selection and terminal pane rationale [skip ci]

* [comment audit] Condense terminal fitting and rendering recovery comments [skip ci]

* [comment audit] Condense terminal input and host routing explanations [skip ci]

* [comment audit] Condense ownership and sleeping-session recovery rationale [skip ci]

* [comment audit] Condense structured launch and terminal link explanations [skip ci]

* [comment audit] Condense terminal ownership and workspace file routing rationale [skip ci]

* [comment audit] Condense session persistence and workspace activation rationale [skip ci]

* [comment audit] Condense workspace routing and browser ownership rationale [skip ci]

* [comment audit] Condense mirror recovery and layout authority rationale [skip ci]

* [comment audit] Condense runtime transport and file safety rationale [skip ci]

* [comment audit] Condense runtime graph and structured session rationale [skip ci]

* [comment audit] Condense browser creation and remote tab recovery rationale [skip ci]

* [comment audit] Condense snapshot authority and publisher recovery rationale [skip ci]

* [comment audit] Condense frame, startup and provider cache rationale [skip ci]

* [comment audit] Condense host twin and agent lifecycle rationale [skip ci]

* [comment audit] Condense browser authority and editor cleanup rationale [skip ci]

* [comment audit] Condense editor buffer identity and review cache rationale [skip ci]

* [comment audit] Condense provider lifetime and repository ownership rationale [skip ci]

* [comment audit] Condense reconnect, hydration and terminal retirement rationale [skip ci]

* [comment audit] Condense recovery, reconciliation and persistence rationale [skip ci]

* [comment audit] Condense cleanup ownership and listing admission rationale [skip ci]

* [comment audit] Condense teardown ordering and terminal ownership rationale [skip ci]

* [comment audit] Condense recovery ledger and web host-boundary rationale [skip ci]

* [comment audit] Condense web reconnect and credential lifecycle rationale [skip ci]

* [comment audit] Condense cloud rollout and assignment safety rationale [skip ci]

* [comment audit] Condense relay session and database recovery rationale [skip ci]

* [comment audit] Condense relay placement and protocol compatibility rationale [skip ci]

* [comment audit] Condense build and packaging constraints [skip ci]

* [comment audit] Condense CI gates and validation isolation rationale [skip ci]

* [comment audit] Condense catalog identity and browser validation rationale [skip ci]

* [comment audit] Condense mobile browser and frame-budget rationale [skip ci]

* [comment audit] Shorten mobile route and browser test explanations [skip ci]

* [comment audit] Condense editor and session seam test rationale [skip ci]

* [comment audit] Trim session and terminal closure history [skip ci]

* [comment audit] Shorten terminal browser and census explanations [skip ci]

* [comment audit] Preserve root-only E2E diagnostic baseline

* [comment audit] Condense mobile seam and HTML preview test rationale [skip ci]

* [comment audit] Condense preview instrumentation and render harness rationale [skip ci]

* [comment audit] Condense bundle contracts and native-build constraints [skip ci]

* [comment audit] Shorten native packaging and CI routing rationale [skip ci]

* [comment audit] Condense release tooling and benchmark constraints [skip ci]

* [comment audit] Condense packaging and platform gate rationale [skip ci]

* [comment audit] Shorten mobile route and history rationale [skip ci]

* [comment audit] Condense mobile browser and component rationale [skip ci]

* [comment audit] Shorten drawer and workspace-form rationale [skip ci]

* [comment audit] Trim mobile review and editor-document explanations [skip ci]

* [comment audit] Condense editor lifecycle and Markdown explanations [skip ci]

* [comment audit] Trim mobile file, diagnostics and dictation commentary [skip ci]

* [comment audit] Simplify mobile host-list and workspace-view explanations [skip ci]

* [comment audit] Clarify mobile shell lifetime and bridge delivery constraints [skip ci]

* [comment audit] Condense bridge stream, native request and audio rationale [skip ci]

* [comment audit] Reduce bridge schema and page-client commentary [skip ci]

* [comment audit] Tighten mobile page bridge contracts [skip ci]

* [comment audit] Clarify mobile cache and session constraints [skip ci]

* [comment audit] Condense mobile route and lifecycle rationale [skip ci]

* [comment audit] Tighten mobile shell hook timing rationale [skip ci]

* [comment audit] Clarify route handoff and notification compatibility [skip ci]

* [comment audit] Clarify push registration and dictation cleanup constraints [skip ci]

* [comment audit] Condense keyboard geometry and native media ownership rationale [skip ci]

* [comment audit] Tighten mobile chat scroll and composer concurrency rationale [skip ci]

* [comment audit] Condense mobile reply compatibility and upload ownership rationale [skip ci]

* [comment audit] Condense optimistic echo and scroll ownership rationale [skip ci]

* [comment audit] Tighten stream replay and queued session ownership rationale [skip ci]

* [comment audit] Condense mobile composer and reply-schema constraints [skip ci]

* [comment audit] Clarify mobile transcript recovery and session ownership [skip ci]

* [comment audit] Clarify mobile queue and source-control compatibility [skip ci]

* [comment audit] Condense storage and task launch constraints [skip ci]

* [comment audit] Clarify task schemas and terminal document ownership [skip ci]

* [comment audit] Tighten terminal input and viewport rationale [skip ci]

* [comment audit] Shorten terminal and RPC recorder contracts [skip ci]

* [comment audit] Condense recorder engine and connection contracts [skip ci]

* [comment audit] Shorten host credential and relay recovery comments [skip ci]

* [comment audit] Tighten pairing recovery and bundle transport rationale [skip ci]

* [comment audit] Clarify RPC delivery and workspace catalog boundaries [skip ci]

* [comment audit] Condense catalog and relay entry contracts [skip ci]

* [comment audit] Shorten shutdown and SSH relay delivery contracts [skip ci]

* [comment audit] Condense WSL relay and E2E regression rationale [skip ci]

* [comment audit] Shorten cross-version harness and renderer fixture explanations [skip ci]

* [comment audit] Condense paired-host and E2E lifecycle rationale [skip ci]

* [comment audit] Shorten layout oracle and regression explanations [skip ci]

* [comment audit] Condense paired recovery and ownership regression contracts [skip ci]

* [comment audit] Shorten restart, sidebar and SSH lifecycle contracts [skip ci]

* [comment audit] Condense terminal rendering and IME regression rationale [skip ci]

* [comment audit] Shorten terminal recovery and benchmark contracts [skip ci]

* [comment audit] Condense tooling and Windows lifecycle proof rationale [skip ci]

* [comment audit] Condense workflow routing and release rationale [skip ci]

* [comment audit] Condense mobile security and installer contracts [skip ci]

* [comment audit] Shorten native rationale and stylesheet workarounds [skip ci]

* [comment audit] Shorten Windows visibility probe rationale [skip ci]

* [comment audit] Condense embedded release and signing rationale [skip ci]

* [comment audit] Retain current main test behavior in final reconciliation [skip ci]

* [comment audit] Complete final comment review across current source inventory

* [comment audit] Handle consolidated audit reports before final CI

* [comment audit] Preserve credential storage census detail [skip ci]

* [comment audit] Scale broad changed E2E selections with verified timing shards

* [comment audit] Align E2E assertions with browser close and settled session metadata

* [comment audit] Match existing E2Es to current resource and windowing contracts

* [comment audit] Observe the shared server outage notice in reconnect coverage

* [comment audit] Make existing renderer probes measure settled tab and PTY work

* [comment audit] Align palette E2E selector with task search

* [comment audit] Refresh remaining palette search selectors

* [comment audit] Keep selector correction within selected audit specs

* [comment audit] Await emoji fixture settings inside renderer evaluation

* [comment audit] Cancel fixture fit retries between terminal tests

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-10-25 04:05:46 -07:00

338 lines
12 KiB
TypeScript

import { countLooseRefs } from './loose-ref-count'
import { PackedRefsLockGate } from './packed-refs-lock-gate'
import { RepoMaintenanceSchedule } from './repo-maintenance-schedule'
import {
LOOSE_REF_PACK_THRESHOLD,
REF_MAINTENANCE_ATTEMPT_DEADLINE_MS,
REF_MAINTENANCE_CLEAN_COOLDOWN_MS,
REF_MAINTENANCE_FAILURE_COOLDOWN_MS,
REF_MAINTENANCE_PACKED_COOLDOWN_MS,
REF_MAINTENANCE_QUIET_PERIOD_MS,
PACKED_REFS_LOCK_WAIT_MS,
REF_MAINTENANCE_LOCKED_COOLDOWN_MS,
RefMaintenanceInterrupted,
RefMaintenanceRepoLocked,
type RefMaintenanceOutcome,
type RefMaintenanceSpan,
type RepoRefMaintenanceOptions,
type RepoRefMaintenanceTarget
} from './repo-ref-maintenance-policy'
/** Give up until the next real activity rather than re-arming forever. */
const MAX_DEFERRALS = 6
/** Each deferral doubles the wait, so a busy app is retried rarely, not hammered. */
const MAX_DEFERRAL_BACKOFF_MULTIPLIER = 8
/** Armed repos are evicted oldest-first past this; the next write on one re-arms it. */
const MAX_TRACKED_REPOS = 64
type TrackedRepo = {
target: RepoRefMaintenanceTarget
timer: ReturnType<typeof setTimeout> | null
deferrals: number
superseded?: boolean
}
const noopSpan: RefMaintenanceSpan = { setAttribute: () => {} }
export class RepoRefMaintenance {
private readonly tracked = new Map<string, TrackedRepo>()
private readonly phases: RepoMaintenanceSchedule
private readonly now: () => number
private readonly isAppBusy: () => boolean
private readonly observe: NonNullable<RepoRefMaintenanceOptions['observe']>
private readonly quietPeriodMs: number
private readonly looseRefThreshold: number
private readonly onError: (error: unknown) => void
// One app-wide pack avoids starving foreground Git; keep its slot until interrupted work has stopped.
private inFlight: Promise<void> | null = null
private inFlightAbort: AbortController | null = null
private inFlightTracked: TrackedRepo | null = null
private readonly lockGate = new PackedRefsLockGate()
// Overlapping ref operations share the pause; only the last release reopens maintenance.
private suspensions = 0
private lastAttempt: Promise<void> = Promise.resolve()
private disposed = false
constructor(options: RepoRefMaintenanceOptions = {}) {
this.now = options.now ?? Date.now
this.phases = new RepoMaintenanceSchedule(this.now)
this.isAppBusy = options.isBusy ?? (() => false)
this.observe = options.observe ?? ((attempt) => attempt(noopSpan))
this.quietPeriodMs = options.quietPeriodMs ?? REF_MAINTENANCE_QUIET_PERIOD_MS
this.looseRefThreshold = options.looseRefThreshold ?? LOOSE_REF_PACK_THRESHOLD
this.onError = options.onError ?? (() => {})
}
/** Restart the quiet countdown on every write so maintenance cannot interrupt the burst that armed it. */
arm(target: RepoRefMaintenanceTarget): void {
if (this.disposed) {
return
}
// Invalidation survives eviction of the replacement quiet-period timer.
if (this.inFlightTracked?.target.key === target.key) {
this.inFlightTracked.superseded = true
}
const existing = this.tracked.get(target.key)
if (existing?.timer) {
clearTimeout(existing.timer)
}
const tracked: TrackedRepo = { target, timer: null, deferrals: existing?.deferrals ?? 0 }
this.tracked.delete(target.key)
while (this.tracked.size >= MAX_TRACKED_REPOS) {
const oldest = this.tracked.keys().next()
if (oldest.done) {
break
}
const evicted = this.tracked.get(oldest.value)
if (evicted?.timer) {
clearTimeout(evicted.timer)
}
this.tracked.delete(oldest.value)
}
this.tracked.set(target.key, tracked)
this.schedule(target.key, tracked)
}
/** Resolves once the attempt started by the most recent timer has settled. */
whenAttemptSettled(): Promise<void> {
return this.lastAttempt
}
/** Wait out the short rewrite instead of killing the pack: concurrent ref edits succeed during pruning,
* while killing can strand packed-refs.lock (observed roughly one in five kills). */
awaitPackedRefsLockRelease(): Promise<void> {
return this.lockGate.whenReleased(PACKED_REFS_LOCK_WAIT_MS)
}
/** User ref work proves app-wide activity; postpone all armed repos without resolving individual targets. */
postponeAll(): void {
if (this.disposed) {
return
}
for (const [key, tracked] of this.tracked) {
if (tracked.timer) {
clearTimeout(tracked.timer)
}
tracked.deferrals = 0
this.schedule(key, tracked)
}
}
/** Block new attempts until release and await any packed-refs rewrite; ongoing pruning can finish concurrently. */
async pause(_reason: string): Promise<() => void> {
this.suspensions += 1
let released = false
try {
await this.awaitPackedRefsLockRelease()
} catch {
// The wait cannot reject, but a release must exist even if it did.
}
return () => {
if (!released) {
released = true
this.suspensions -= 1
}
}
}
dispose(): void {
this.disposed = true
this.inFlightAbort?.abort(new RefMaintenanceInterrupted('disposed'))
for (const tracked of this.tracked.values()) {
if (tracked.timer) {
clearTimeout(tracked.timer)
}
}
this.tracked.clear()
this.phases.clear()
}
private isBusy(tracked: TrackedRepo): boolean {
return tracked.superseded || this.isAppBusy() || (tracked.target.isBusy?.() ?? false)
}
private schedule(key: string, tracked: TrackedRepo, delayMs = this.quietPeriodMs): void {
const timer = setTimeout(() => {
tracked.timer = null
this.lastAttempt = this.attempt(key).catch((error) => this.onError(error))
}, delayMs)
// Never hold the process open for maintenance.
timer.unref?.()
tracked.timer = timer
}
/** Charge only activity/failed probes against the give-up budget; waiting behind other packs or requested yields
* ends independently and must not starve maintenance until the next fetch. */
private defer(key: string, tracked: TrackedRepo, counted: boolean): void {
// Do not overwrite a fresher arm from a fetch that landed during the probe.
if (this.disposed || tracked.superseded || this.tracked.has(key)) {
return
}
if (counted) {
if (tracked.deferrals >= MAX_DEFERRALS) {
return
}
tracked.deferrals += 1
}
this.tracked.set(key, tracked)
const multiplier = Math.min(2 ** tracked.deferrals, MAX_DEFERRAL_BACKOFF_MULTIPLIER)
this.schedule(key, tracked, this.quietPeriodMs * multiplier)
}
private async attempt(key: string): Promise<void> {
const tracked = this.tracked.get(key)
if (!tracked || this.disposed) {
return
}
this.tracked.delete(key)
const refDueAt = this.phases.refDueAt(key)
const indexDueAt = tracked.target.maintainPackIndex ? this.phases.indexDueAt(key) : refDueAt
const nextDueAt = Math.min(refDueAt, indexDueAt)
if (this.now() < nextDueAt) {
this.tracked.set(key, tracked)
this.schedule(key, tracked, nextDueAt - this.now())
return
}
if (this.inFlight !== null) {
this.defer(key, tracked, false)
return
}
if (this.suspensions > 0 || this.isBusy(tracked)) {
this.defer(key, tracked, true)
return
}
const abort = new AbortController()
const deadline = setTimeout(
() => abort.abort(new RefMaintenanceInterrupted('attempt deadline', true)),
REF_MAINTENANCE_ATTEMPT_DEADLINE_MS
)
deadline.unref?.()
this.inFlightTracked = tracked
const run = this.observe((span) => this.packIfNeeded(key, tracked, span, abort.signal))
this.inFlight = run
this.inFlightAbort = abort
try {
await run
} finally {
clearTimeout(deadline)
if (this.inFlight === run) {
this.inFlight = null
this.inFlightAbort = null
this.inFlightTracked = null
}
}
}
private async packIfNeeded(
key: string,
tracked: TrackedRepo,
span: RefMaintenanceSpan,
signal: AbortSignal
): Promise<void> {
span.setAttribute('repo.maintenance_key', key)
const canWrite = () => !signal.aborted && this.suspensions === 0 && !this.isBusy(tracked)
// Probes are cancellable; admitted index and ref writers finish before releasing the slot.
const optedOut = await this.phases.probeOptOut(tracked.target, signal, span, canWrite)
if (signal.aborted) {
return this.yieldTo(key, tracked, span, signal)
}
if (typeof optedOut === 'object') {
this.defer(key, tracked, true)
throw optedOut.error
}
if (optedOut) {
return
}
if (this.suspensions > 0 || this.isBusy(tracked)) {
return this.yieldTo(key, tracked, span, signal)
}
const indexOutcome = await this.phases.maintain(tracked.target, signal, span, canWrite)
if (indexOutcome === 'deferred' || !canWrite()) {
return this.yieldTo(key, tracked, span, signal)
}
if (this.now() < this.phases.refDueAt(key)) {
span.setAttribute('repo.maintenance_outcome', 'index_only' satisfies RefMaintenanceOutcome)
// Keep the arm for its ref phase; the write that armed it may have left loose refs.
if (!this.disposed && !this.tracked.has(key)) {
this.tracked.set(key, tracked)
this.schedule(key, tracked, this.phases.refDueAt(key) - this.now())
}
return
}
const refsDirectory = await tracked.target.resolveRefsDirectory(signal)
if (!canWrite()) {
return this.yieldTo(key, tracked, span, signal)
}
if (!refsDirectory) {
this.phases.settleRefs(key, span, 'unresolved', REF_MAINTENANCE_CLEAN_COOLDOWN_MS)
return
}
const budget = this.looseRefThreshold + 1
const before = await countLooseRefs(refsDirectory, budget, signal)
if (!canWrite()) {
return this.yieldTo(key, tracked, span, signal)
}
span.setAttribute('git.loose_ref_count', before.count)
span.setAttribute('git.loose_ref_threshold', this.looseRefThreshold)
// A saturated walk stopped early, so `count` is a floor -- never read it as "clean".
if (!before.saturated && before.count < this.looseRefThreshold) {
this.phases.settleRefs(key, span, 'below_threshold', REF_MAINTENANCE_CLEAN_COOLDOWN_MS)
return
}
const startedAt = this.now()
let partial = false
try {
// Only admission cancels; pause waits out the rewrite instead of killing the writer.
await tracked.target.packRefs(this.lockGate, signal, canWrite)
} catch (error) {
span.setAttribute('repo.maintenance_error', String(error))
if (!canWrite()) {
return this.yieldTo(key, tracked, span, signal)
}
if (error instanceof RefMaintenanceRepoLocked) {
this.phases.settleRefs(key, span, 'locked', REF_MAINTENANCE_LOCKED_COOLDOWN_MS)
return
}
partial = true
} finally {
this.lockGate.setHeld(false)
}
span.setAttribute('git.pack_refs_ms', this.now() - startedAt)
if (!canWrite()) {
return this.yieldTo(key, tracked, span, signal)
}
// Judge the remaining backlog: concurrent ref movement may report failure after packing almost everything.
const after = await countLooseRefs(refsDirectory, budget, signal)
if (!canWrite()) {
return this.yieldTo(key, tracked, span, signal)
}
span.setAttribute('git.loose_ref_count_after', after.count)
if (partial && (after.saturated || after.count >= this.looseRefThreshold)) {
this.phases.settleRefs(key, span, 'failed', REF_MAINTENANCE_FAILURE_COOLDOWN_MS)
return
}
span.setAttribute('git.pack_refs_partial', partial)
this.phases.settleRefs(key, span, 'packed', REF_MAINTENANCE_PACKED_COOLDOWN_MS)
}
/** Retry ineligible work; back off only for activity or deadlines. */
private yieldTo(
key: string,
tracked: TrackedRepo,
span: RefMaintenanceSpan,
signal: AbortSignal
): void {
if (!signal.aborted || tracked.superseded) {
span.setAttribute('repo.maintenance_outcome', 'deferred' satisfies RefMaintenanceOutcome)
this.defer(key, tracked, true)
return
}
if (signal.reason instanceof RefMaintenanceInterrupted && signal.reason.deadline) {
this.phases.settleRefs(key, span, 'timed_out', REF_MAINTENANCE_FAILURE_COOLDOWN_MS)
return
}
span.setAttribute('repo.maintenance_outcome', 'interrupted' satisfies RefMaintenanceOutcome)
this.defer(key, tracked, false)
}
}