fix(tests): order test spans by start sequence, not by started_at alone - #4392

On a clean checkout on Windows with Python 3.10, 3.11 or 3.12, pytest fails 37 tests across the tracing, MCP-tracing and runtime-symmetry suites, all with the same error:

KeyError: ('trace_...', 'span_...')
tests/testing_processor.py:162: KeyError

Nothing is wrong with the library. The test helper's span ordering depends on clock resolution.

Mechanism

Three steps, each verifiable on its own.

1. started_at ties. It comes from datetime.now() via agents.tracing.util.time_iso. On Windows the resolution of that call changed in Python 3.13, measured on this machine over a 1000-call burst:

So before 3.13, a parent span and the child it opens almost always carry the identical started_at.

2. A tie resolves to the wrong order. get_ordered_spans sorted on that field alone:

return sorted(spans, key=lambda x: x.started_at or 0)

sorted is stable, so a tie preserves insertion order, and spans are inserted in on_span_end. A child ends before its parent, so a tie puts the child first, which is the exact reverse of what the consumer needs.

3. The consumer requires parent-first. fetch_normalized_spans looks the parent up while attaching each span:

nodes[(trace_id, parent_id)].setdefault("children", []).append(span)

Reduced to three spans, with nothing else running:

get_ordered_spans() order:
  0: name='child'   started_at=2026-08-13T13:06:13.769939+00:00  parent=45147e
  1: name='parent'  started_at=2026-08-13T13:06:13.769939+00:00  parent=-

all started_at identical: True
spans appearing before their parent: [('child', 'parent')]
fetch_normalized_spans() -> KeyError: ('trace_4f489b…', 'span_89ba…')

Why CI does not catch it

tests-windows runs the full suite, but pins python-version: "3.13", the one version on Windows where the clock is fine. The Linux matrix covers 3.10 through 3.14 and is unaffected because datetime.now() there has microsecond resolution. So the gap is Windows on any supported version below 3.13, which no job covers.

I have not touched the workflow matrix in this PR; widening it is a separate decision and this fix stands on its own.

Fix

on_span_start already fires for every span and was discarding it. Record the start sequence there and use it only to break timestamp ties:

self._start_order.setdefault(span.span_id, len(self._start_order))
...
return sorted(
    spans,
    key=lambda x: (x.started_at or "", self._start_order.get(x.span_id, 0)),
)

Timestamp order stays primary, so behaviour is unchanged wherever the clock already separates spans. The map is cleared in clear() alongside the other per-test state.

Verification

Same machine, same checkout, the six affected test files:

Whole suite on Python 3.12 goes from 42 failed / 5620 passed to 5 failed / 5657 passed. The 5 that remain are unrelated to span ordering, they fail with and without this change, and some are flaky between runs; I have not chased them here.

ruff check, ruff format --check and mypy are clean on both files.

The regression test

tests/tracing/test_span_ordering.py freezes time_iso rather than relying on a coarse clock, so it reproduces the ordering deterministically on every platform instead of only where the bug happens to bite. Verified red before green: both cases fail with KeyError against the unfixed helper on Python 3.13, where the real bug cannot otherwise be observed at all.

One case asserts the ordering contract directly (no span precedes its parent) and the other asserts the tree fetch_normalized_spans builds from it, so a future change that satisfies one but not the other still fails.