# Offline measurement agent guide
## Overview
Private scanner and codec implementations behind `src/tool_output_measurement.rs` (repository-relative). Report types, limits, and aggregation remain in that facade.
## Where to look
- `scanner.rs`: active-session discovery, bounded selection, held file handles, and file-stability checks.
- `codecs.rs`: stored result extraction, local token projection, candidate validation, and portfolio selection.
## Local conventions
- Discover active primary sessions and direct subagent sessions only. Keep discovery exclusions separate from files selected but later unreadable or unstable.
- Open files relative to held directory handles without following symlinks. Use the opened handle's identity and size for selection; preserve discovery/open and scan-time signature checks rather than reopening a pathname.
- Preserve deterministic selection: newest modification time first, then path. Enforce file-count and byte budgets as well as per-file and per-line caps.
- Parse stored records with the session event schema. Tool results require valid identity and success fields, and exactly one text field: `content` or legacy `output`.
- Compare baseline and candidates in the same Codex Responses-style tool-result item, retaining call identity and framing. These are local token estimates, not provider billing counts.
- JSON minification removes whitespace outside strings without reserializing values; preserve number spelling, escapes, and object structure. Validate the complete JSON value before and after transformation.
- Portfolio selection requires a unique candidate with fewer tokens than the baseline. A tie for best or no strict improvement keeps the original; applicable candidates are not automatically wins.
## Boundaries
- Keep scan outcomes and codec applicability distinct from measured savings; a rejected or capped candidate must not become a claimed improvement.
- Keep the existing codec and scanner checks beside their implementations; do not turn these helpers into another public API or live compression path.