docs: document synchronous event listener behavior

[coji]

Problem

Event listeners are called synchronously in the worker's hot path. A slow or error-throwing listener blocks job execution and lease renewal. This is intentional (ensures error propagation) but undocumented — users may add expensive listeners without realizing the impact.

Tasks

• Add warning to Events API docs about synchronous execution
• Document that listeners should be fast and non-blocking
• Consider adding an async option in a future version → Decided against async emit. See fix: async event listeners silently drop Promises #136 for runtime Promise detection instead.

Decision (from Codex review)

• on() stays synchronous — async emit would push user callback latency into the worker hot path
• Listener type stays void — changing to Promise<void> would be misleading
• Runtime Promise detection + .catch() forwarding to onError tracked in fix: async event listeners silently drop Promises #136
• withLogPersistence() async listener bug also tracked in fix: async event listeners silently drop Promises #136

References

• events.ts L308 — synchronous listener loop
• Found by Codex code review
• Fix: docs: document synchronous event listener behavior (#126) #135