[immakermatty]

Status: ready for review

Fixes #272.

Why

Since #270 (F36 addendum of 2026-10-08), setup.forget() starts the shell setup cache's background read right away. That read holds the Folder's operation lock (withFolderReadLock). A Folder mutation never waited for anyone (withFolderOperationLock refuses at once). So a person's change right after a profile change, or the "used by agents" toggle after a sign-in, could be answered 400 operation-failed, recoveryMayBeRequired: true although it would have succeeded a moment later.

On 2026-10-11 the same race failed the required Linux CI often enough to block merges:

• a rerun of main 342db2f;
• PR Browser: the hub alone ends a remote tab, kept by holder files and working agents (F47 step 1) #316 three times.

Details and evidence are in #272.

What changes

This is direction 1 of #272, in src/folder/lock.ts:

• withFolderReadLock counts its holds per state directory (resolved path) while it holds the lock. The count drops only after the lock is released, so a waiting mutation never sees zero while the read still holds the lock.
• withFolderOperationLock takes a new optional waitForOwnReadsMs (default 3 s). On a busy refusal it retries only while this process's own short read holds the lock, until that bound.

What does not change

• The kernel lock stays exclusive.
• A holder in another process, or this process's own mutation, is still refused at once.
• No caller changes; every caller gets the default.
• Reads behave as before (they already waited for each other).

Verification

New tests in tests/folder-lock.test.ts:

• a mutation waits for an in-process read and runs after it, while any other holder is refused at once (< 500 ms);
• the wait is bounded: past it the mutation fails as busy, and it goes through at once once the read is done.

bun run check locally: static checks pass. In the test run, one unrelated timing test failed under machine load (guarded-process, "Fixture start timed out" at 3 s); that file passes 3/3 alone. The real gate is this PR's Linux CI. If it is green here, it also unblocks #316.

Risk

A mutation can now take up to 3 s longer when its own Launchpad's background read is slow; before, it failed. Nothing waits on another process.

🤖 Generated with Claude Code

[agentrozjedemeai]

APPROVED on bcce02a (base 342db2f). The own-read count starts only after acquisition and ends after release; the mutation retries only a busy lock while that count is positive, preserving immediate refusal for unrelated holders and other mutations. Focused macOS folder-lock tests: 10 passed; exact-head Linux CI static checks and both test shards passed. No unresolved review threads. Non-blocking test hardening: replace the 30 ms startup sleeps in the two new tests with an explicit read-acquired signal to avoid scheduler-dependent assertions under load.