Module index_lock_wait 

Waiting for a foreign index.lock under the classification rules and Git’s backoff schedule. What: Waiting for a foreign index.lock under the classification rules: a proven-alive owner is waited for up to this process’s wait limit (CLI_GIT_LOCK_WAIT_SECONDS, 30 minutes by default), a dead or evidence-free owner is retried on Git’s backoff schedule until the unproven budget runs out. Why: An index writer must not run beside a landing, and a lock nobody can prove alive must not block forever. Nothing here deletes a lock; the caller decides what the failure means (src/index-lock/index-lock-wait.ts).

In TS you’d write (pseudocode):

await waitForIndexLock({ realIndexPath, timeoutMs, consequence, attempt });

Structs

BackoffState

What: Git’s backoff position: step is Git’s n, multiplier the wait base in milliseconds. Why: BackoffState in the incumbent.

Enums

WaitFailure

What: What one attempt found, or why the wait ended without a result. Why: The caller reports the owner and the consequence; the attempt itself is the lock check.

Constants

BACKOFF_MAX_MULTIPLIER

Git’s BACKOFF_MAX_MULTIPLIER: the backoff stops growing here.

INITIAL_BACKOFF

Backoff before the first wait.

PROVEN_BY_DESCRIPTOR_POLL_CAP_MS

Longest single poll while only an open descriptor proves the owner alive; each poll repeats the open-holder scan, so it polls less often.

PROVEN_BY_PID_FILE_POLL_CAP_MS

Longest single poll while a PID file proves the owner alive, so its release is noticed promptly.

Traits

WaitEffects

What: The side effects of a wait, injected so tests can drive a fake clock and fake holders. Why: The host implementation reads /proc, sleeps and writes standard error; tests script each step.

Functions

jittered_wait

What: One jittered wait from Git’s formula (750 + rand() % 500) * backoff / 1000, rounded down. Why: Jitter spreads retrying processes apart; random is a value in [0, 1).

live_holder_timeout_message

What: The diagnostic text of a live-owner timeout. Why: The person needs the lock path, the owner to look at, the limit and its setting, and what was not done.

next_backoff

What: The next backoff: multiplier += 2n + 1, capped at BACKOFF_MAX_MULTIPLIER. Why: Adding 2n + 1 makes the multiplier the square of the step, which is Git’s schedule.

unproven_owner_message

What: The diagnostic text of an unproven-owner failure. Why: The person needs the lock path, the owner state, the budget, what was not done, and the evidence.

unproven_progress_line

What: The notice a wait behind a lock with no proven live owner repeats. Why: The wait retries on Git’s backoff schedule and is silent otherwise, so the person learns what is held, why no process is named, how long the wait has lasted and where it gives up.

wait_for_index_lock

What: Wait until the lock is gone, or fail once a dead or unproven owner outlasts timeout_ms or a live owner outlasts this process’s wait limit. Why: A live holder gets one diagnostic and the process’s wait limit; other holders get the budget, which includes the evidence gathering because a /proc scan is not free.

wait_for_index_lock_within

What: The wait with an explicit limit on the time spent behind a proven-alive owner. Why: The default wait and the tests share one loop; only the limit differs.