Document PerfTrace open-span cap and single-primary nesting

Operators reading PERFTRACE need the fixed memory limits and the
active-turn ownership rule for permission and subagent spans.

Author: TheGreatAxios

docs/PERFTRACE.md

@@ -36,8 +36,22 @@ turn
 ```
 
 Tags on spans pass through a hard allowlist (`provider_id`, `model_id`,
-`transport`, token/byte/count numbers, short opaque ids). Everything else is
-stripped at write time — see `src/perf/sanitize.ts`.
+`transport`, `decision` allow/deny, token/byte/count numbers, short opaque ids).
+Everything else is stripped at write time — see `src/perf/sanitize.ts`.
+
+## Limits and concurrency
+
+| Limit | Value | Behavior |
+|---|---|---|
+| Completed ring | `RING_CAPACITY` (4096) | Oldest completed span dropped |
+| Open spans | `OPEN_SPAN_CAPACITY` (1024) | Oldest **open** span dropped so a leaked `start()` cannot grow without bound |
+| Snapshot | — | Shallow copies of spans/tags; consumers cannot poison the ring |
+
+**Single-primary turn nesting:** `permission.wait` and `subagent` nest under the
+process-wide active turn id (`src/perf/active-turn.ts`). One run-sink reactor
+observer owns that slot. Concurrent multi-observer setups are unsupported —
+later observers overwrite the nesting parent. `clear()`, observer `reset()`, and
+turn close null the slot.
 
 ## API surface
 
@@ -53,7 +67,8 @@ import { dumpSpans } from "../src/perf/dump.js";
 - `dumpSpans(spans, { dir, sessionId })` — write a privacy-strict JSON file
 
 The ring holds `RING_CAPACITY` (4096) completed spans. Older entries are
-evicted; open spans are not stored in the ring until they end.
+evicted; open spans live in a separate map capped at `OPEN_SPAN_CAPACITY` (1024)
+until they end (or are dropped if over cap).
 
 ## Reading a dump after a slow run