Module path_locks 

Process-wide per-path advisory locks.

These in-process mutexes serialize concurrent operations on the same file path while letting operations on different paths run fully in parallel.

Why this exists: tools like ctx_read and ctx_edit would otherwise contend on the single global cache write-lock for the entire duration of their disk I/O. When several agents (or sub-agents) hammer files concurrently, that global lock becomes a bottleneck and edits can time out waiting for it (see issue #320). A per-path lock keeps the contention scoped to the one file that actually needs serialization, so unrelated reads/edits never block each other.

Lock ordering (see LOCK_ORDERING.md, L17): the inner registry mutex is held only long enough to clone the per-path Arc<Mutex<()>>, then released before the per-path lock itself is acquired. Never hold the registry mutex across the per-path lock, and never acquire a per-path lock while holding the global cache write-lock.

Functions

per_file_lock

Returns the shared advisory lock for path, creating it on first use.