Replace the PID file atomically and treat contention as another instance [patch]

[matt-edmondson]

Fixes #181
Fixes #182

Both issues come from the same concurrent PID-file race, and both triage comments recommend fixing them together. They also rewrite the same two methods (WritePidFile and the read in IsAlreadyRunning), so separate PRs would conflict with each other.

What was wrong

• Simultaneous launches can tear the PID file, and a torn file reads as "no instance running", so every instance launches #181: WritePidFile wrote in place with File.WriteAllText. Two instances starting together could tear the file: the shorter record, then the tail of the longer one. The torn file failed to parse, fell through to the legacy integer path, and read as "no instance". Every racing instance launched, and so did the next launch after them.
• ShouldLaunch/ExitIfAlreadyRunning throw an unhandled IOException when another instance is writing the PID file at the same time #182: IsAlreadyRunning caught only not-found and format errors, and WritePidFile caught nothing. A sharing violation from a concurrent writer, or a locked or unreadable file, went through ShouldLaunch() as an unhandled IOException and crashed the app at startup.

Change

• Atomic replace. WritePidFile writes to <pid>.<guid>.tmp beside the PID file and moves it over the PID file: File.Move(…, overwrite: true) on .NET Core 3.0 and later, File.Replace/File.Move on netstandard. Readers see either the old file or the new one. The replace is retried up to 5 times with a short linear backoff while another instance holds the file. The temp file is always cleaned up.
• Contention means another instance. The read retries on IOException/UnauthorizedAccessException. If the file stays inaccessible, it reads as AnotherInstance. If WritePidFile still can't replace the file, ShouldLaunch() returns false rather than throwing.
• Torn files from older versions. Only the leading JSON value is parsed (Utf8JsonReader + Deserialize(ref reader)). A record followed by garbage still names the instance that wrote it, and the full identity check still applies to it. Legacy plain-integer files and all the existing malformed-content cases behave as before.
• Recheck fails closed. A new internal PidFileState (NoInstance / AnotherInstance / Unreadable) lets the post-sleep recheck in ShouldLaunch() tell the cases apart. Content that can't be parsed right after we wrote a whole file came from a racing instance, so it no longer counts as "no instance". The first check still treats unparseable content as stale, so a leftover corrupt file doesn't block launch forever. IsAlreadyRunning() keeps its signature and existing behaviour.
• One README feature bullet was updated to describe the atomic write and the contention behaviour.

Tests

Five new tests. All five fail with the library change reverted and pass with it:

Test	Covers
IsAlreadyRunning_WithGarbageSuffixedPidFileForRunningInstance_ShouldReturnTrue	#181: a torn file describing a live process reads as that instance
ShouldLaunch_WithGarbageSuffixedPidFileForRunningInstance_ShouldReturnFalse	#181 acceptance: a garbage-suffixed PID file for a live instance doesn't grant a second launch
ShouldLaunch_WhenPidFileBecomesUnreadableDuringRaceWindow_ShouldReturnFalse	#181: unparseable content during the recheck window doesn't grant a launch
WritePidFile_WhileBeingRead_ReaderNeverSeesAPartialFile	#181 acceptance: the file is only ever replaced atomically (2000 reads racing a writer)
ShouldLaunch_WhenPidFileIsHeldExclusively_ShouldReturnFalseWithoutThrowing	#182 acceptance: an exclusively held PID file gets a bool back, not an exception

• dotnet test: 31/31 passed on Linux (net10.0), three runs in a row with no flakes. The build is clean on every target framework with the repo's analyzers, including a CA1508 finding fixed along the way.
• Windows-specific sharing behaviour (the MoveFileEx replace failing while a reader has the file open) is covered by the retry logic, but I have only run it on Linux. The race tests tolerate sharing violations and don't count them as partial reads, so they should hold on the Windows and macOS CI legs.

This PR merges cleanly with #185 (for #180) in either order. I checked this with a local git merge-tree.

🤖 Generated with Claude Code

https://claude.ai/code/session_018x3sGQTDEmvXP1cRdbmmkx

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
95.2% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud