[Juliusolsson05]

Refs #993.

The evidence

On 2026-09-18 a dev build and the installed app ran against ~/.config/agent-code simultaneously, while agent-code.process-lock.json did not exist at all — with the dev process actively writing control history and layout mutations.

The mechanism

defaultIsLockOwnerActive answered 'inactive' — delete the file and take over — in two very different situations: the owner pid is gone, and the owner pid is alive but ps printed a command line that does not contain the recorded argv0.

The second is a guess, and there are ordinary reasons for it to fail while the owner is very much alive and writing: the bundle replaced in place by an update, the app renamed or moved, a dev binary at a path that has since changed, or ps rendering the argv differently than process.argv[0] spelled it.

Acting on it puts two mains on one state directory, and it leaves the lock file unable to describe either. Once the incumbent's lock is overwritten the file carries the successor's token: the incumbent's release no longer matches and is a silent no-op, while the successor's release deletes the file although the incumbent is still running.

The fix: ask the kernel, don't guess

A first version routed the mismatch into the existing five-minute 'inconclusive' grace window. Review showed that does almost nothing — the window is measured from the lock's startedAt, which is when the incumbent acquired the lock, i.e. roughly its uptime. Every reason for a mismatch is permanent for the life of that process and never resolves by waiting, so anything older than five minutes was stolen from exactly as before. The app packages macOS only and /bin/ps is always on the Finder-launched PATH, so 'inconclusive' had become almost exclusively "argv0 mismatch" — the one input for which waiting is guaranteed not to help.

There is no need to guess at all. The question the heuristic was groping for is "is this pid the process that wrote the lock, or a recycled number wearing it?", and the kernel answers it exactly: a process cannot have started after the lock its own acquisition wrote.

classifyLockOwner now reads ps -o lstart= (under LC_ALL=C, as mitmproxyReaper already does for the same field) and compares against the lock's startedAt:

• started later → a reused pid, and nothing else → take over immediately
• started at or before → the genuine owner, however its command line now reads → refuse, at any age, no window involved
• neither question answerable → the bounded window, which is now only "ps said nothing at all"

A two-second tolerance covers lstart's one-second resolution.

Also fixed

• Impossible timestamps unbounded the windows. A clock corrected backwards leaves a recorded time in the future; a negative age is below every threshold forever, so the window never opened and the user had to delete a JSON file by hand. Clamping to zero does not fix it either — the age stays pinned at zero until the real clock catches up. An impossible timestamp is not evidence of freshness, so it now makes the lock immediately eligible for cleanup, with a one-minute jitter margin because filesystem mtimes carry sub-millisecond precision that Date.now() does not.
• Two clauses that could never decide anything are gone: any command line containing the full argv0 necessarily contains its basename, and an empty basename is accepted by includes from every string. Mutation testing found both unreachable.

What was ruled out

Recorded in the code so the next reader does not redo it:

• ps truncation — ps -p <pid> -o command= does not truncate when piped on macOS 25.6 (measured; the reviewer independently confirmed with ~3,650 characters of argv).
• The shutdown gate — onQuitAllowed runs only on the re-entered will-quit after teardown settled. A rejected drain keeps the quit prevented and never releases.
• The crash hooks — every uncaughtException arm releases and then process.exit(1).
• The startup-throw path — keeps the journal and lock and calls app.quit(); verified not a hole.

Tests

This file had no tests, which is how a concurrency guard this load-bearing drifted. classifyLockOwner is exported and reads the world through an injectable probe, so every branch is reachable — including the 'active' half, which nothing could previously reach, and which a mutation could previously delete outright with the suite green. Acquisition and release are driven against a real directory.

mutation	result
live-pid mismatch steals again (the bug)	3 failed
drop the executable match	3 failed
a dead pid treated as alive	1 failed
reused pid kept as the owner	1 failed
no tolerance on lstart rounding	1 failed
unanswerable probes steal	1 failed
grace window shrunk to nothing	1 failed
grace window never expires	1 failed
future timestamps blow the window open	2 failed
no jitter tolerance	1 failed
release ignores the token	2 failed
acquire writes a constant token	1 failed
fresh unparseable lock treated stale	1 failed
restored	65 passed

npx tsc -b clean.

Why Refs and not Fixes

The mechanism does not reproduce the reported snapshot exactly: under this story the successor holds a valid lock for as long as both mains run, so the reported moment — both live and the file already absent — needs the successor to have exited. It is one way to reach that state, not a proven account of the incident.

Two of the issue's suspects remain untouched: no dev-plus-installed reproduction was run, and install-time migration was not investigated. requestSingleInstanceLock being per-bundle-id is unchanged and remains a residual.

🤖 Generated with Claude Code

[Juliusolsson05]

Review round addressed. Finding 1 was the one that mattered and it was right: the grace window is anchored to the incumbent's uptime, and every reason for an argv0 mismatch is permanent, so five minutes bought essentially nothing. My own test asserting the self-heal was documenting the surviving steal.

Your discriminator is the fix. ps -o lstart= against the lock's startedAt — a process cannot have started after the lock its own acquisition wrote. Later → reused pid, take over immediately. At or before → the genuine owner at any age, no window involved. Neither answerable → the bounded window, which now means only "ps said nothing at all". Two-second tolerance for lstart's one-second resolution. The heuristic is gone from the decision entirely.

5b — clamping to zero would not have fixed it. I tried that first: the age stays pinned at zero until the real clock catches up, which may be years. An impossible timestamp is not evidence of freshness, so it now makes the lock immediately eligible for cleanup — with a one-minute jitter margin, because without one the freshest possible lock (the create/write race, mtime a hair ahead of Date.now()) becomes instantly stale. That margin is its own test; removing it fails.

3 — the injectable probe closes all ten. And chasing M4/M6 turned up something better than a test: both clauses are unreachable. Any command line containing the full argv0 necessarily contains its basename, and an empty basename is accepted by includes from every string. They are deleted rather than covered.

4 — you are right, it is not "whichever". The comment now says the successor's release is what deletes the file while the incumbent runs on.

2 — pinned in both directions now; shrinking the window to a second fails.

6 — the probe removes the checkout-path coupling entirely. Good catch; that would have been a miserable failure to debug.

7 — I have retitled to Refs #993 and said so in the body. You are right that the mechanism does not reproduce the reported snapshot: under this story the successor holds a valid lock while both mains run, so the reported moment needs the successor to have exited already. The body now lists which suspects remain untouched (no dev-plus-installed repro, install-time migration uninvestigated) and records that the startup-throw path is verified not a hole, which is worth keeping whoever closes the issue.

65 tests, 13 mutations caught, npx tsc -b clean.