async-handler-pattern

What problem does it solve?

This Skill prevents orchestration deadlocks and subtle race conditions when a Claude workflow transition handler must start an asynchronous LLM call and later complete via callback or engine timer.

Core Features & Use Cases

• Correct AwaitingLLM orchestration flow: returns Status -> AwaitingLLM immediately, registers AwaitingLLMTransitions[awaitId], and completes via ClaudeCompleteHandlerOutput so the engine can safely produce tokens.
• Safe dynamic binding in handlers: uses $ClaudeCurrentWid and $ClaudeCurrentAwaitId only within the awaiting handler, then copies values into a closure to avoid Missing["NotInHandler"] failures.
• Timeouts, restore, and double-fire safety: configures AwaitingLLMTimeout / DefaultAwaitingLLMTimeout, re-installs timers after ClaudeSnapshotWorkflow + ClaudeRestoreWorkflow, and relies on silent discard when callback and timer fire out of order.
• Diagnostics for real symptoms: resolves cases where workflows get stuck in AwaitingLLM, timeout firing stops working, snapshot restore never completes, or callback fires twice.
• Observability compatibility: works with ClaudeOrchestrator_observability.wl so traceTransitions can show AwaitingLLM and handler logs include AwaitingLLM status.

Quick Start

Use this skill when your ClaudeOrchestrator handler mentions AwaitingLLM and your workflow gets stuck, times out incorrectly, or fails to complete after snapshot restore.