fix(tracing): reliability follow-ups from v0.8.4 review (#901, #902, #903)
What does this PR do?
Three reliability follow-ups filed during the v0.8.4 release review of the trace-data-loss fix (#895), all in the observability subsystem.
#901 — reconstructed spans no longer masquerade as failures. When rehydrateFromFile force-closes an in-flight generation span (worker restart / cache eviction), the span kept status: "error", so the viewer painted it red and counted it in the session error total — a false alarm on a postmortem surface. Spans now also carry interrupted: true. The viewer renders them amber ("⚠ / Interrupted") instead of red on every surface (preview, detail, waterfall row, tree view, log view) and the session error count (errSpans) excludes them. status: "error" is kept so the boundary stays visible.
#902 — getOrCreateTrace can no longer resurrect a Trace into a cleared cache. The async rehydrate added an await where a concurrent startEventStream (e.g. setWorkspace) can abort the stream and sessionTraces.clear() while we're suspended. On resume the old code inserted the freshly built Trace into the just-cleared map — an orphan writer under a dead stream. We now capture a monotonic streamGeneration before the await and, if it changed, discard the Trace (endTrace) and defer to the live stream. Keyed on a counter (not AbortController identity) per review feedback.
#903 — long-lived traces no longer grow ses_<id>.json without bound. snapshot() rewrites the entire spans array on every event (O(n²) over a session). capSpansForSerialization bounds the on-disk projection to MAX_SERIALIZED_SPANS (default 5000, override ALTIMATE_TRACE_MAX_SPANS) via head + tail retention + one elision marker. In-memory spans are untouched; summary totals come from separate counters, so they're unaffected. The cut explicitly preserves the structural root span.
A two-model review panel (GPT-5.4 + Kimi-K2.5) reviewed the first commit; the second commit applies their MAJOR findings (stream-generation counter, explicit root preservation, amber treatment on all viewer surfaces) plus table-driven edge-case tests.
Known minor (deferred): a trace with only interrupted spans correctly contributes nothing to the error count but shows no "incomplete" hint in the summary; a dedicated incomplete banner is a small follow-up.
Type of change
- Bug fix (non-breaking change which fixes an issue)
Issue for this PR
Closes #901
Closes #902
Closes #903
How did you verify your code works?
- New
test/altimate/tracing-followups.test.ts(15 tests): interrupted flag set on rehydrate; viewer carries amber/!sp.interruptedcontract + flag in embedded data;capSpansForSerializationhead/tail/marker, no-op under cap, no-benefit guard, root-not-at-index-0, tiny caps 1–5 with marker-parent validity, exact boundary, elided-count accuracy; scope-bounded source contract for the #902 guard ordering (await → guard → insert) and thestreamGenerationbump. - Full tracing/viewer/worker sweep: 410 pass, 0 fail (22 files).
tsgotypecheck clean. Marker guard (analyze.ts --markers --base main --strict) clean —worker.tsedits wrapped inaltimate_changemarkers.
Checklist
- My code follows the style guidelines of this project
- I have added tests that prove my fix is effective
- New and existing unit tests pass locally with my changes
- I have made corresponding changes to the documentation (n/a — internal observability behavior;
ALTIMATE_TRACE_MAX_SPANSdocumented inline)
Summary by cubic
Marks reconstructed spans as interrupted (warning, not failure), guards against orphan trace writers across stream restarts, and caps on-disk spans to keep session files bounded. This removes false error counts and improves stability and performance for long sessions.
- Bug Fixes
- #901:
rehydrateFromFilesetsinterrupted: trueon force-closed generation spans; viewer shows amber "⚠ Interrupted" on all surfaces and excludes them from the session error count (keepsstatus: "error"for boundary visibility). - #902:
getOrCreateTracekeys ownership to a monotonicstreamGeneration; if the stream changed during rehydrate, it discards the trace instead of inserting into a clearedsessionTracesmap (guard placed after await, before insert). - #903: Adds
capSpansForSerializationto bound serialized spans toMAX_SERIALIZED_SPANS(default 5000; overrideALTIMATE_TRACE_MAX_SPANS) using head+tail retention with an elision marker; always preserves the root span. In-memory spans and summary totals are unaffected.
- #901:
Summary by CodeRabbit
-
New Features
- Trace serialization now automatically capped to prevent unbounded growth, preserving head and tail of trace history
- Trace viewer now visually distinguishes interrupted spans from genuine failures using distinct styling and status indicators
-
Bug Fixes
- Fixed race condition in trace cache invalidation during stream resets