Overview

Cache the derived Trace.branches view by len(trace.nodes) so repeated trace properties reuse the same branch materialization. Token-limit evaluation keeps using the existing Trace API and preserves its current semantics.

What changed

• Add a private branch cache and cached node count to Trace.
• Return a shallow copy of the cached branch list while the node count is unchanged, preserving caller isolation.
• Rebuild the view after nodes are appended.
• Let num_branches reuse the cached branch count when warm, while retaining its cheap leaf scan on cold count-only access.

Why

prompt_len, completion_len, and total_tokens each read Trace.branches. Token-limit checks can therefore reconstruct the same graph paths three times. Caching the derived view at its owner removes those repeated graph walks for every caller without adding topology-specific counting logic to the interception server.

The public property still returns an independent outer list, so caller operations such as sorting, popping, or clearing do not mutate the internal cache.

Performance

Median wall time with all three token limits enabled:

A cache miss represents the normal case after the trace grows; a hit represents repeated reads at the same node count.

Warm num_branches reads improve from 346.4 µs to 0.659 µs for a 10k-node linear trace and from 100.2 µs to 0.672 µs for a shared-prefix trace with 1k leaves. Cold count-only reads continue using graph.leaves and avoid materializing full branch paths.