fix: atomic lock create so a live holder is never stolen (lost update)

[vreshch]

Verdict: A - REAL data-integrity lost-update bug

The e2e "30 concurrent vault-add" test (e2e/integrity.test.ts:279) failing once and passing on rerun is NOT a flake. Under CPU contention the advisory file lock silently lets two writers into the critical section and drops committed writes, while every vault add still exits 0. This is the same class of bug as cli#252/#231.

Root cause

src/lib/fs/file-lock.ts acquired the lock with writeFileSync(lockPath, "<pid> <at>", { flag: 'wx' }). The wx create is atomic for the inode but not for the content: the file exists (O_CREAT|O_EXCL) before its <pid> <at> bytes are written.

A concurrent holderOf() that reads the lock in that window sees empty content, Number.parseInt yields NaN, and holderOf returns null. The acquire/takeover logic then treated a null holder as "not a live holder" and proceeded to takeOverStale, which unlinkQuiet(path)'d a live, fresh holder's lock and let the second writer in. The pid-liveness gate from cli#252 was bypassed because it never ran on a null holder.

Cross-process read-race proof (one writer create/unlink loop + one reader loop on the same path, 8s):

reader: emptyContentReads=169808 totalSeen=534559

~32% of concurrent reads observed the lock file mid-create with empty content.

Instrumented subprocess repro (30 concurrent vault add, 40 runs, 2 cores under load) - every lost-write run is preceded by a stole holder=null takeover, all with addFail=0:

run 4:  [TAKEOVER pid=... stole holder=null ...]
run 4:  LOST want 30 got 18 missing cli1,cli12,cli16,cli17,cli18,cli4,cli7,other4,other5,other6,other8,other9
run 24: LOST want 30 got 24 missing cli14,cli18,cli19,cli6,cli9,other3
RUNS=40 lost=5 takeovers=16

Fix

1. Atomic lock create - createLockExclusive writes the full <pid> <at> to a unique temp then linkSyncs it into place. link is atomic and fails EEXIST if held (still the mutex), so the content is always complete the instant the lock inode appears. No reader can ever see an empty lock.
2. Defense in depth - a null holder is now treated as "unknown, refuse", never "absent/crashed". A lock is taken over only when a holder is positively proven crashed (dead pid / our own pid / past the 60s hard-stale bound).

Tests (deterministic, before-fail / after-pass)

• never steals a lock whose content reads empty (mid-create window) - reproduces the exact null-holder state and asserts a fresh acquirer refuses. Fails on old code (true), passes after (false).
• lock content is always complete the instant the file appears - 5000 acquire cycles, the lock never reads empty/half-written.
• The stochastic 30-process e2e test is kept.

Verification

• npm run verify green (type-check + e2e types + eslint + prettier + 444 unit tests + build).
• New unit test proven to fail on the pre-fix source (git stash of the fix -> test returns true).
• Stochastic subprocess repro (30 concurrent adds x many runs, under CPU load) -> zero lost writes after the fix.

[github-actions]

🎉 PR Validation ✅ PASSED

Commit: 12cf9310d44fc18e4de71c4e97ea05df5db6ea5b
Branch: fix/vaults-json-concurrency

Checks:

• ✅ Release guard (no version/changelog changes)
• ✅ Dependencies installed
• ✅ Type check passed
• ✅ Linting passed
• ✅ Format check passed
• ✅ Tests + coverage passed
• ✅ Build successful

Ready to merge! ✨

---

🔗 View workflow run
⏰ Generated at: 2026-07-08T23:27:59.076Z