What Does This Do

Adds default-on scope and continuation lifecycle diagnostics to instrumentation tests.

The diagnostic records continuation and scope events during each test, waits briefly for asynchronous cleanup, and fails with an actionable timeline when it detects problems such as:

• A continuation that was never released
• A scope that was never closed
• A continuation resolved more than once
• Activation after resolution
• Cleanup performed from an unexpected thread
• Cleanup occurring after the test boundary

The timeline includes elapsed time, thread transitions, ownership state, and relevant call sites so the missing lifecycle edge can be identified without reconstructing it from a trace timeout.

  flowchart LR
      A[Capture continuation] --> B[Resume context]
      B --> C[Run asynchronous work]
      C --> D[Close scope]
      D --> E[Release continuation]
      E --> F[Write complete trace]

      C -. missing cleanup .-> G[Test ends]
      G --> H[Diagnostic failure]
      H --> I[Timeline with thread and callsite]

      style E fill:#d5f5e3,stroke:#239b56
      style H fill:#fadbd8,stroke:#c0392b

How is it enabled?

The diagnostic runs automatically for both instrumentation-test harnesses:

• Spock tests extending InstrumentationSpecification
• JUnit tests extending AbstractInstrumentationTest

A narrow opt-out is available only for tests that are incompatible with the diagnostic itself:

@TrackScopeContinuations(
enabled = false,
reason = "Explain the incompatibility and removal condition")

The reason is mandatory. The opt-out is not intended for unresolved continuation leaks.

Additional behavior

• Allows a bounded quiescence period for legitimate asynchronous cleanup.
• Recognizes iteration scopes registered for deferred cleanup without ignoring unrelated iteration-scope leaks.
• Keeps recording isolated to the test harness.
• Preserves an original test failure while attaching diagnostic failures as additional evidence.
• Includes focused tests for lifecycle classification, reporting, configuration, stack filtering, and concurrent snapshots.
• Adds a troubleshooting skill that guides an LLM from the emitted timeline to the broken ownership edge and a compact human-readable diagram.

Motivation

Strict trace writing can reveal that asynchronous work is still pending, but it does not explain where ownership was lost.

This diagnostic connects capture, activation, scope closure, and continuation resolution into one timeline, making continuation failures reproducible and actionable for both humans and automated integration work.

Fixed issues leveraging that:

• Fix continuation cleanup when TimerTask is cancelled #12464
• Prevent duplicate Kotlin coroutine continuation release #12466
• Prevent OkHttp TaskRunner from retaining request contexts #12468
• Prevent Pekko stream lifecycle context retention #12470
• Prevent OkHttp connection pools from retaining request contexts #12492
• Fix Java HTTP async continuation lifecycle #12498
• Prevent Netty periodic purge tasks from inheriting context #12499
• Close ServiceTalk captured context scope in test #12500
• Wait for Reactor Kafka test pipelines to finish #12501
• Test async RUM timer propagation as application code #12502
• Prevent Netty idle timers from retaining request context #12503
• Use context swap for Akka and Pekko HTTP flows #12507
• Avoid abandoning Guidewire test continuations #12518
• Prevent Couchbase Netty initialization from capturing context #12520
• Avoid duplicate context capture in OpenSearch executors #12521
• Fix Hystrix async error tests without relaxing trace validation #12570

Additional Notes

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
  Use solves instead, and assign the PR milestone to the issue
• Update the CODEOWNERS file on source file addition, migration, or deletion
• Update public documentation with any new configuration flags or behaviors
• Once approved, use merge queue to merge the PR

Jira ticket: [PROJ-IDENT]