fix: don't break a live lock on staleness alone (#432)

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

[arzaanxeng]

Fixes#432

Bug

breakIfAbandoned() decided a lock was abandoned if expired OR ownerGone.
That meant a same-host owner that was still alive and running could have its
lock stolen just because its critical section took longer than staleMs
(big file, slow disk, loaded machine). Two processes would then race the same
file, and whichever rename() landed last silently discarded the other's work.

Fix

• breakIfAbandoned() now checks owner liveness first: if the owner's pid is
  checkable and confirmed alive on the same host, the lock is never broken on
  staleness alone — liveness is decisive, not just one of two OR'd signals.
• withFileLock() now runs a heartbeat while the critical section is active,
  refreshing the lock file's mtime every staleMs / 3. This covers the case
  where liveness can't be checked (cross-host lock files), so staleMs still
  reflects real inactivity rather than just how long the section has run.
• Updated the header comment, which documented the old (buggy) "staleMs
  breaks regardless" behavior.

Testing

Added two regression tests in file-lock.test.ts that reproduce the exact
scenario from the issue: a live same-host holder whose lock is older than
staleMs, and a second acquirer racing it mid-critical-section. Both new
tests fail against the old code and pass with this fix. Full suite:
8/8 passing.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.