Explicit Identity Across Boundaries
Never rely on "latest" or "current" when crossing process or async boundaries.
Pattern
Pass explicit identifiers through the entire pipeline. "Most recent" is a race condition.
DO Pass --session-id $ID when spawning processes Store IDs in state files for later correlation Use full UUIDs, not partial matches Keep different ID types separate (don't collapse concepts) DON'T Query for "most recent session" at execution time Assume the current context will still be current after await/spawn Collapse different ID types: session_id = Claude Code session (human-facing) root_span_id = Braintrust trace (query key) turn_span_id = Braintrust turn within session Example // BAD: race condition at session boundaries spawn('analyzer', ['--learn']) // defaults to "most recent"
// GOOD: explicit identity spawn('analyzer', ['--learn', '--session-id', input.session_id])
Source Sessions 1c21e6c8: Defined session_id vs root_span_id distinction 6a9f2d7a: Fixed wrong-session attribution via explicit passing a541f08a: Confirmed pattern prevents race at session boundaries