v2-refactor-temp/docs/breaking-changes/2026-08-08-trace-retention-bounded.md
The AI trace data captured under Settings → Developer Mode is now bounded instead of growing for the lifetime of a topic. Each topic's trace history file is capped (8 MiB, oldest spans dropped first), and a single span keeps at most its 200 most recent log events or 2 MiB of them, whichever comes first. An individual event larger than 2 MiB is dropped instead of bypassing the memory budget. Previously nothing aged out: measured trace files reached 66 MB for one topic and 185 MB across a two-day session, with individual spans holding ~20 MB of captured request/response bodies.
Developer-mode users who open the trace pane on a long Claude Code session will see the oldest turns disappear from the trace list over time, and very large spans show a truncated event list rather than every captured body. In exchange the trace pane stops stalling the app while it is open — the old viewer re-read and re-sent the entire trace file several times a second. Users who never enable developer mode are unaffected; trace capture is off for them.
Nothing — automatic. Existing oversized trace files are trimmed on the next flush rather than deleted. Settings → Developer Mode → clear trace local data still removes everything at once.
Developer-mode-only surface; safe to fold into a single "trace viewer performance" line rather than listing the individual caps.