OTel nest parents, dims, and attribution docs

[susheem-k]

Summary

• OTel-style nest parents: open a Context span before the boundary body so nested LLM/tool nodes set parent_envelope_id correctly (not last-finished).
• Flat dims: dict[str, str] on envelopes; pass trace-level dims via chronicle.record(..., dims={...}) for session/message correlation (dashboard owns lookup).
• Docs: boundaries on decision nodes (not full agent), dims, multi-turn session_id/message_id in README + onboarding.
• Fixture + tests for a parent calling the same sub-agent twice (each with nested llm + tool). Tree/waterfall kept as debug helpers; shared product viz stays with the control plane / TokenOps (see RFC: Chronicle depends on shared control plane; TokenOps stays above Chronicle #30).

Sample nesting (ASCII waterfall)

Same sub-agent twice under one parent; each researcher has its own llm + tool envelopes (fixtures/traces/parent-calls-subagent-twice):

Trace: trace-parent-calls-subagent-twice
  total: 164.5ms   [0ms ──► 164.5ms]
  resource/dims: message_id=msg_042 session_id=sess_subagent_x2 ...

orchestrator#1   ███████████████████████████████████████████████████████    164.5ms  custom
  researcher#1   █████████████████████████                                   74.8ms  custom
    llm#1         ██████████████                                             42.3ms  llm
    web_search#1                ██████████                                   31.7ms  tool
  researcher#2                                  ████████████████████████     72.3ms  custom
    llm#2                                       █████████████                40.5ms  llm
    web_search#2                                              ██████████     30.9ms  tool

Tree form of the same run:

└─ orchestrator#1 (custom)
   ├─ researcher#1 (custom)
   │  ├─ llm#1 (llm)
   │  └─ web_search#1 (tool)
   └─ researcher#2 (custom)
      ├─ llm#2 (llm)
      └─ web_search#2 (tool)

Decision-nodes-only pattern (no full-agent wrap; sequential siblings):

├─ planner#1 (llm)       parent=—
├─ web_search#1 (tool)   parent=—
└─ summarizer#1 (llm)    parent=—

Relation to #40

Partial fix only — does not fully close #40.

Done here	Still open for #40 / follow-ups
Nest parents (parent_span_id from Context stack)	Shared product visualization layer (with TokenOps / control plane)
Trace/envelope dims + record(..., dims=)	Dashboard/control-plane lookup by session_id / message_id
Docs: nodes, dims, multi-turn attribution	Production feedback → MessageID → TraceID end-to-end
Debug ASCII tree/waterfall	SQL indexes (explicitly deferred)

Refs #40

Test plan

• pytest tests/test_nest_attribution.py tests/test_execution_graph.py tests/test_otel.py
• Full pytest on CI
• Skim README Quick start + onboarding Step 2/3 for clarity