# context: specs

Constants at the top of `context.py`: `DAYS=30`, `CHARS_PER_TOKEN=4`, `IMAGE_TOKENS=1500`, `THRESHOLDS=(150k, 250k)`, `CURVE_TURNS=(1,10,25,50,100,200)`, `CURVE_POINTS=20`, `TOP_TOOLS=5`, `MAX_READOUT_BYTES=400`.

## X-scan: what is read
Every `*.jsonl` under the root modified at or after since; lines with `timestamp >= since` (R-window). One file is one context thread; files under `subagents/` belong to their parent `sessionId`. API calls dedup by request id, last usage wins (R-claude-dedup), `<synthetic>` skipped. `tool_use` blocks dedup by id.

## X-ctx: context per turn
ctx = `input_tokens + cache_read_input_tokens + cache_creation_input_tokens` of one call. The curve is the main thread only (not subagent files, not sidechain lines), in log order; `peak_ctx` is its max. `curve` in detail is downsampled to `CURVE_POINTS`; `curve_median` is the median ctx at each of `CURVE_TURNS` over sessions that reached it.

## X-peak
`over_150k` / `over_250k`: sessions whose `peak_ctx` reaches the threshold.

## X-compact
Each `compact_boundary` line is one compaction; before/after = `compactMetadata.preTokens` / `postTokens`, else the ctx of the calls just before and after it.

## X-cache
Shares of ctx tokens over all calls (main and subagents): cache read, cache write, uncached input. Cache write cost = C-cache-ttl list price (5m/1h split when logged), via `schemas/cost.py`.

## X-reread
In one thread, a `Read` with the same (file_path, offset, limit) as an earlier one, with no `Edit`/`Write`/`MultiEdit`/`NotebookEdit` to that file in between, is a re-read; its result tokens are wasted. Pitfall: a file changed outside the agent (git checkout, a script) is legitimately re-read.

## X-size, X-tools
Result tokens = ceil(chars / `CHARS_PER_TOKEN`), `IMAGE_TOKENS` per image (as M-size). Top `TOP_TOOLS` tool names by summed result tokens.

## X-readout
`readout`: sessions, peak_p50, over_150k, over_250k, compactions, cache_read_share, cache_write_usd, reread_tok, up to 3 `findings` (facts), `detail` = `context.json`. Findings are dropped from the end until the compact JSON is under `MAX_READOUT_BYTES`.

## X-ex: worked example (../tests/test_context.py)
since 2026-10-01. s1 main: a Sep 30 call (dropped); r1 (logged twice) ctx 1010, Read /a 100 tok; r2 1205, Read /a again = re-read 100 tok; r3 1201 Edit /a; r4 1251 Read /a (not a re-read: edited); compaction 1300 -> 300; r5 300, Bash 1000 tok. s1 subagent: cache write 160000, Read /a (own thread, not a re-read). s2: one call, ctx 260000. Peaks: s1 1251 (subagent excluded), s2 260000 -> over_150k 1, over_250k 1. Re-reads 1 / 100 tok. Tools: Bash 1000, Read 203, Edit 1.