Module worktree_copy_lock 

The settlement lock that serializes copy installation and recovery, its owner record, and inherited leases. What: The settlement lock that serializes worktree-copy installation and recovery per common Git directory, its owner record, liveness-based retirement of dead owners, and the inherited-lease check nested Git runs use. Why: Two copies into one repository must not interleave, but a commit in a linked worktree must never wait for them; only an owner proven alive may be waited for, and only an owner proven dead may be replaced.

In TS you’d write (pseudocode):

await using lease = await acquireWorktreeCopyLock(commonDir);

Structs

LockOwner

What: The identity an owner record names: a unguessable token, a process, and that process’s birth identity. Why: Liveness is judged on the process and its birth, so a reused PID is never taken for the owner.

WorktreeCopyLease

What: The disposable settlement lock: released explicitly, or removed when dropped if still held. Why: Release reports an ownership change; the drop fallback cannot report, so it only removes what it still owns.

Constants

OWNER_RECORD_NAME

What: The owner record’s file name inside a published lock directory. Why: Readers find the owner by this name.

SETTLEMENT_LOCK_NAME

What: The published name of the settlement lock inside the journal root. Why: Every process in one repository contends on this exact name.

UNPROVEN_OWNER_TIMEOUT_MS

What: How long an owner without evidence may hold the lock before acquisition gives up. Why: A malformed record must not block the repository forever, but a live owner is waited for without limit.

WORKTREE_COPY_LEASE_ENV

What: The environment variable through which nested Git runs inherit a held lease. Why: A hook that runs the wrapper inside git worktree add must forward without waiting for its own parent.

Functions

acquire_worktree_copy_lock

What: Acquires the settlement lock: waits without limit for a proven-live owner, retires a dead one, and gives an owner without evidence the bounded wait before failing. Why: Installation and recovery of one repository must never interleave, and no lock is taken from an owner that might still run.

encode_owner

What: The text of one owner record, as the incumbent writes it. Why: Other wrappers read this record, so its key order and spelling are fixed.

parse_owner

What: Parses one owner record, or names why it proves nothing. Why: Every field is checked before the owner’s process is ever consulted.

try_acquire_worktree_copy_lock

What: Takes the settlement lock if it is free or its dead owner is retired; reports a held lock instead of waiting. Why: A command that neither creates nor moves worktrees must not wait behind a copy.

validate_inherited_lease

What: Whether the environment’s lease token names the live owner of the published lock. Why: A nested Git run that carries the outer run’s token forwards without waiting for the lock it is already inside.