[PIsberg]

Part of #1007 (the Mutex reentrancy third of it; runBlocking shipped earlier, races across suspensions stay open there).

Why

kotlinx.coroutines.sync.Mutex is not reentrant. A coroutine that calls lock() or withLock() on a mutex it already holds suspends forever: no exception, no stack trace, a test that hangs until its timeout. The library had no view of it, because a Mutex call never passed through a woven site.

What

• KotlinMutexWeaver (agent) replaces Mutex lock, tryLock, unlock and withLock call sites, and their $default bridges, in woven classes with static hooks.
• KotlinMutexes (lib) reads the caller's Job from the continuation, records the holder, and hands the finding to the new KotlinMutexReentrancyDetector (detector 149) when the holder, or a scope it is suspended in, waits on the mutex again.
• Each of the six hooks calls ControlledSchedule.point() first, like runBlockingEntered, because every call the agent replaces must also be a scheduling point (controlledSchedule: woven atomic and collection hooks are not scheduling points #1023).
• Wiring: DetectorType, AsyncTestConfig, DetectorRegistry, DetectorFeeds, DetectorTrust, AsyncTestContext.

Known limits, filed

• [P3] Kotlin Mutex detector keeps a stale holder after an unlock in an unwoven class and can report a false reentrancy #1221 (P3): an unlock in an unwoven class leaves a stale holder, and a later waiting lock from that coroutine is reported. includes= clears it.
• [P3] Kotlin Mutex reentrancy is missed after a waited lock, tryLock or select acquisition #1220 (P3): a holder that waited, or took the mutex with tryLock or select, is not known, so a reentry under it is missed.
• Races across suspensions: still [P3] Kotlin coroutine model: runBlocking on a dispatcher, Mutex reentrancy, races across suspensions #1007.

Verified

• Library fast tier 3,931 tests, agent 117 tests: green.
• Kotlin fixture against real kotlinx (KotlinMutexReentrancyIsReportedTest, KotlinMutexWithoutReentryIsNotReportedTest: both directions, invariant 10) and consumer fixture 287 tests incl. new Phase26KotlinMutexFixtureTest: green.
• examples/152-kotlin-mutex-reentrancy: 3 tests green under Maven and Gradle; shows the real hang under a timeout, the recorded finding, and the fixed twin passing.
• Static gate chain (mvn install -DskipTests -Djacoco.skip=true) and tools/guardrail-drift.sh re-run on this exact tree: green.
• Class diagram regenerated (tools/generate-architecture-diagrams.sh); the only new nodes are KotlinMutexes and KotlinMutexReentrancyDetector.

Expected red

Locked Files Guard fails: DetectorType is @AILocked and gains a constant, with its config flag, registry field, factory row and ifIssue call in the same commit (invariant 3). Needs lock-override from whoever merges (invariant 14).

Docs

• docs/JVM_LANGUAGES.md: the three coroutine rules and what is still open.
• docs/agent/attaching.md: how the Mutex weaving works.
• docs/CHANGELOG.md: ### Added entry.
• Counts: detectors 148 to 149 everywhere DetectorCatalogCoverageTest reads; agent-fed 48 to 49 (docs/DETECTOR_CATALOG.md, docs/analysis/corpus-eval.md); README "code you did not modify" 52 to 53; examples 150 to 151 in eight places (two workflow comments, two skill files). The CI example sample stays 38 (every 4th of 151).
• Generated guardrail files regenerated from the new annotations.

Guardrails considered

• AsyncTestAgent's @AICore note now describes KotlinMutexWeaver's stack shape, so the frames-stay-valid argument covers the new weaver.
• KotlinMutexReentrancyDetector carries @AIThreadSafe (what makes its per-mutex state safe: weak-keyed map, volatile weak holder, description written before count) and @AITestDriven, as every detector does.
• Nothing else: KotlinMutexes and the hooks hold no PII, licence state or security boundary, so no safety annotation applies.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 38.20598% with 186 lines in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!