feat(async): latency causes — capture, classify, and harden

[arkerone]

What & why

Makes the async kind answer which code is slow, what the latency is, and why — then hardens that classification against an empirical audit.

Each topOperations[] entry now decomposes its lifetime into runMs (on CPU) / waitMs (the real latency) / scheduleDelayMs, and carries a classified latencyCause (event-loop-blocked | gc-pause | downstream-async | io-wait | cpu-bound | background | unknown) with causeConfidence/causeEvidence. A new cross-kind event-loop-blocked-async detector ties a slow async op to the synchronous CPU frame blocking the loop — the answer to "the await was slow but the I/O wasn't".

Audit-driven hardening

The classification was tested against real, purpose-built programs (event-loop blocking, CPU-bound, I/O, downstream chains, orphans, multi-blockers, a realistic HTTP server under load). The audit found and this PR fixes:

• GC blanket (dominant bug): ±20ms padding around every GC event made dense sub-millisecond scavenges tile the timeline, so ~100% of waits were spuriously gc-pause (it even stole event-loop-blocked). Now uses each pause's actual duration → gc-pause is correctly rare.
• Priority not implemented: a blocked event loop now actually outranks a coincidental GC/downstream overlap (the documented behaviour).
• Coincidental overlap → false positive (R7): event-loop-blocked now requires the loop to have still been stalled when the callback became runnable (firstRunAtMs); a stall that ended before the op ran is treated as coincidental.
• Orphans pollute the headline: resources still in flight at capture end are excluded from topOperations/byKindLatency (their capture-clamped duration is fictional) and remain in orphans[].
• Multiplexed handles: keep-alive sockets / intervals (one asyncId serving many activations over ~the whole capture) are classified background instead of reporting a capture-length aggregate waitMs as a single critical finding. The runCount > 1 discriminator preserves genuine single long operations.
• Per-stall blocking frame (R3): the detector attributes the culprit per stall (new eventLoop.stallIntervals[].topFrame, matched by firstRunAtMs) instead of stamping one globally-dominant frame on every blocked op; it stands down entirely when no CPU hotspot identifies a culprit (no placeholder (event-loop) findings).

A separate investigation kept the CPU kind's gc.correlatedHotspots ±lookaround unchanged — verified it is intentional and correct there (it finds the allocating frame near a pause; during a stop-the-world GC no JS runs, so exact windows would find nothing).

Validation

On a realistic HTTP server under concurrent load, the tool correctly surfaces sync-crypto + event-loop-stall + event-loop-blocked-async all pointing at the blocking pbkdf2Sync handler (not the innocent await), json-on-hot-path on the downstream CPU, zero gc-pause blanket, and zero misleading multi-second findings on keep-alive connections.

Commits (atomic, by layer)

1. feat(core) capture async latency decomposition signals
2. feat(core) classify async latency cause + per-stall blocking frames
3. feat(detectors) event-loop-blocked-async + long-await latency guidance
4. refactor(cli) gate async quality warning on ambiguousRatio
5. docs(async) docs, skill, example, README
6. chore changeset

Notes

• Report-shape additions (waitMs, latencyCause, byKindLatency, stallIntervals[].topFrame, …) are additive and optional within schema v2.
• The async kind remains experimental / opt-in (--kind async); attach mode stays partial by design.
• Detector catalogue: 18 → 19 built-ins (3 cross-kind).

Test plan

• npm run build && npm test — all suites green (core, detectors, cli; incl. new regression tests for the GC fix, readiness gate, priority, orphan exclusion, multiplexed→background, no-culprit stand-down, and per-stall attribution).
• npm run typecheck (5/5) and npm run check (Biome clean).

🤖 Generated with Claude Code