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.

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.