Expand description
FileLock — cross-process advisory file lock for the editing tools.
Why (issue #17): the edit tool’s read→modify→write cycle is not atomic
across processes. Parallel agents (subagents) sharing one working tree
observed torn files and silently lost edits when two editors touched the
same file concurrently. A plain in-process mutex cannot help — subagents
are separate processes — so this is a kernel-level flock (via fs4,
already in the dependency tree through tantivy).
The lock is taken on a stable lock file keyed by the canonical target
path ($TMPDIR/theway-file-locks/<sha256>.lock), NOT on the target file
itself. Locking the target inode is broken by design here: editors commit
via temp-file + rename, which swaps inodes on every write, so an editor
that opens the path late locks the new inode and bypasses editors still
queued on the old one (observed as a lost edit in the concurrent-edit
regression test). The hashed lock file never moves, so every editor of the
same path contends on the same inode regardless of rename churn.
Lock files live under the system temp dir (not next to the target), so agent runs leave no litter in the edited tree, and they persist between acquisitions — removing a lock file while waiters hold it would let a fresh lock file be created and bypass them (the classic unlink race).
The lock is released when the guard drops (the kernel releases flock on
close, so a crashed editor never leaves a stale lock behind).
Structs§
- File
Lock - Exclusive advisory lock for one target path. RAII: drops → unlock.