[PIsberg]

Stacked on #1222: review the last two commits only. Merge #1222 first, with a merge commit.

Fixes #1221. Partly addresses #1220: a reentry under a lock that had to wait is now reported. A holder that took the mutex through tryLock or select is still not known.

Why

KotlinMutexReentrancyDetector recorded a holder when a woven lock took the mutex without waiting, and cleared it on a woven unlock. Two cases went wrong:

• False finding ([P3] Kotlin Mutex detector keeps a stale holder after an unlock in an unwoven class and can report a false reentrancy #1221). An unlock in a class outside includes= was never seen, so the holder stayed recorded. If that coroutine later locked the mutex and had to wait for another holder, the detector reported a reentry that never happened.
• Missed finding ([P3] Kotlin Mutex reentrancy is missed after a waited lock, tryLock or select acquisition #1220). A lock that had to wait never became the holder, so a reentry inside it was missed.

The hold in verdict-evidence-corpus kept the detector at PROMPT for the first reason, "until the detector checks the recorded holder against the mutex's own state". This PR adds that check.

What

• Owner token. A woven lock called without an owner is now made with a fresh token of the agent's. kotlinx compares owners by identity, so the token matches nothing else. I checked in jshell on kotlinx 1.6.4, 1.8.0 and 1.11.0 that lock, unlock(null), tryLock and a lock that waits and is granted later all behave as they do with no owner. The token's toString is "null", so the mutex prints the same as before on 1.8 and later.
• Asking the mutex. The detector keeps each token with the caller's Job. Before a later woven lock, it asks Mutex.holdsLock(token) which of them holds the mutex right now. An unlock the agent never saw therefore ends a hold like any other, and a lock that waited holds its token once it is granted.
• Unlock and tryLock no longer record anything.
• Bounds. A token is dropped once it has held the mutex and let it go. Tokens still waiting are capped at 64 per mutex, oldest dropped first; dropping one can only miss a finding.
• Recording by hand (recordAcquired, recordHolderUnknown, holderAmong(mutex, waiting)) is unchanged, so the Phase 26 fixture, example 152 and the catalog's snippet still work.
• Trust tier. KOTLIN_MUTEX_REENTRANCY is promoted to VERDICT. Its corpus pair (agent_kotlinMutex_lockedAgainByItsHolder / agent_kotlinMutex_unlockedBetweenLocks) is registered in verdict-evidence-corpus, and the HELD_ON_MODEL entry is removed. The catalog split moves to 38 VERDICT and 75 PROMPT. The corpus-backed count in the README and the corpus workflow header moves from 34 to 35.

How it was verified

• Tests first, against real kotlinx 1.11 in consumer-fixture-langs/kotlin, with the library from Detect a coroutine re-entering a kotlinx Mutex it already holds (#1007) #1222 installed:
  • lockAgainAfterAnUnseenHandOver: the mutex is unlocked and then locked by another coroutine, both in com.example.unwoven, outside includes=. Then a woven lock waits for that other holder. Reported before the fix, silent after.
  • withLockAfterWaitingForTheMutex: a supervisorScope reentry under a lock that had to wait. Missed before the fix, reported after.
  • The seven existing fixtures still pass.
• KotlinMutexReentrancyDetectorTest: 18 tests, 7 of them new (a token holds while the mutex says so, a token released unseen is dropped, a waited lock holds once granted, the bounds, hand-recording and tokens kept apart).
• DetectorTrustCoverageTest, DetectorCatalogCoverageTest, DocsIndexCoverageTest, StructuredViolationCoverageTest, DetectorAnalysisUnderConcurrentWritesTest, AgentConcurrencyUtilHooksTest: green.
• Corpus eval against a fresh isolated install: all six lanes green, 0 false positives. Both Mutex rows ran in the agent-pair lane, and the pair gates accept the new evidence line.

Checklist

• A behaviour change ships with a test that fails without the fix
• A new or changed detector is tested against the buggy code and its correctly synchronized twin, and its reported severity matches what it can actually prove
• Docs the change makes wrong are updated in this same change
• Nothing was hand-edited between VIBETAGS-START / VIBETAGS-END markers (the regenerated guardrail files carry the new @AIThreadSafe note)
• Public API changes are intentional and carry the right version bump: recordLocked and holderAmong(mutex, waiting, holds) are new, @since 1.14.2. The detector has not been released yet.
• Commits an agent authored carry the Co-Authored-By trailer
• A new dependency was proposed with a reason (none added)
• CI is green, or the failure is explained below

Anything reviewers should push back on

• The agent now changes an argument of the user's call. It's the owner, and it changes only when the caller passed none. It's invisible to lock, unlock(null), tryLock and holdsLock. From kotlinx 1.8 on, nothing visible changes: the mutex's toString, and the message of an unlock(someOwner) after an owner-less lock, both print the owner, and the token prints as null, exactly as before. On kotlinx before 1.8, both print null where they printed LOCKED. The exception type is the same.
• VERDICT. A finding now needs the mutex itself to confirm that the caller, or a coroutine suspended for it, holds the mutex, and the lock must then wait. That wait can only end through cancellation or a timeout. If you'd rather it stay at PROMPT for a release, revert the DetectorTrust row and the evidence line, and restore the hold with a new reason.
• Locked Files Guard will need lock-override if DetectorTrust or the evidence file is locked.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 42.39766% with 197 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ain/java/se/deversity/asynctest/KotlinMutexes.java	0.00%	135 Missing ⚠️
...deversity/asynctest/AgentConcurrencyUtilHooks.java	0.00%	49 Missing ⚠️
...est/diagnostics/KotlinMutexReentrancyDetector.java	94.33%	3 Missing and 3 partials ⚠️
...e/deversity/asynctest/agent/KotlinMutexWeaver.java	86.84%	3 Missing and 2 partials ⚠️
.../java/se/deversity/asynctest/AsyncTestContext.java	50.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!