Skip to content

fix: remove a lock takeover guard left behind once the lock is held - #335

Merged
mindsers merged 1 commit into
developfrom
bugfix/lock-takeover-guard-left-behind
Oct 27, 2026
Merged

mindsers merged 1 commit into
developfrom
bugfix/lock-takeover-guard-left-behind

Conversation

@mindsers

Copy link
Copy Markdown
Owner

Context

configfile changes files in the home folder, its deployment record and its copy of the dotfiles repository. Two configfile processes must never do that at once, so the commands that change things (init, update, modules deploy, modules undeploy) take a lock first: ~/.configfile/lock, a file holding the owner's pid (src/lock.ts, withLock).

A process that dies leaves its lock behind. The next process takes it over: it removes the lock, then creates its own. Two processes doing that at once could each remove a lock the other has just created, so since #319 (released in 1.1.0) only one process at a time takes over, the one that managed to create ~/.configfile/lock.takeover (the "guard"). The guard holds its owner's pid too, and is removed at the end of the takeover.

A guard can itself be left behind by a process that died. removeStale then moves it aside, checks that it still names the dead process, and puts it back if it does not (another process created a new guard meanwhile).

Why

On CI, the test "never lets two processes hold the lock when the takeover guard was left behind" (tests/lock.test.ts, 8 processes racing for a lock and a guard both left behind) failed once on PR #334 with expected [ 'lock.takeover' ] to deeply equal []. The lock itself worked: no two processes held it at once. A guard was left behind at the end. It also fails locally about once in 30 runs.

The cause, read from the code:

  1. Process A reads the old guard: it names a dead process.
  2. Process B moves the old guard aside, then creates its own and takes the lock over.
  3. A, acting on what it read in step 1, moves B's guard aside, and sees it does not name the dead process.
  4. B finishes and removes lock.takeover: nothing is there, so nothing is removed.
  5. A puts B's guard back. It now names a process that has finished, and nobody removes it: A takes the lock right away and never goes through the takeover again.

That guard is harmless while its process number is unused: the next takeover removes a guard whose owner is dead. If another process reuses the number, the next takeover waits for it and then tells the user to delete the file.

Not confirmed with instrumentation: logging changes the timing, and the failure did not come back in 310 more runs. The new test covers the fix directly.

Change

  • src/lock.ts: a new removeGuard. The process that holds the lock removes lock.takeover, whoever it names, right after taking the lock, next to the existing cleanup of drafts left behind.
  • Removing it whoever it names is safe: a takeover only removes a lock that still names the dead process it found, and while this process holds the lock, the lock names this process. It has to be unconditional, because the guard put back names a process that is usually still running when the next process takes the lock.
  • It closes every case: the process that puts a guard back is still waiting for the lock, so it removes the guard itself once it takes the lock.
  • takeOver's comment now says a guard put back can outlive its owner.
  • CHANGELOG: an entry under Fixed.

Not done: making removeStale check whether the owner's takeover is over before putting a guard back. That needs the same check-then-act step one level down, and has the same race.

Review order

  1. src/lock.ts: the removeGuard call in withLock, then removeGuard and the takeOver comment.
  2. tests/lock.test.ts: "removes a takeover guard left behind by a process still running, once it holds the lock".
  3. CHANGELOG.md.

Tests

  • pnpm typecheck and pnpm lint are clean; pnpm vitest run: 811 tests pass.
  • The new test fails without the change (expected [ 'lock', 'lock.takeover' ] to deeply equal [ 'lock' ]) and passes with it.
  • The two race tests ("never lets two processes hold the lock…") passed 40 runs out of 40.
  • No manual test: there is no command-line change to try. The race only happens with several processes taking over at the same moment, and the new test checks the fix directly.

@mindsers
mindsers merged commit d2cd66e into develop Oct 27, 2026
11 checks passed
@mindsers
mindsers deleted the bugfix/lock-takeover-guard-left-behind branch October 27, 2026 23:43
@mindsers mindsers mentioned this pull request Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant