emrg: add scripts/llm-cost-report.py — LLM API cost profiler from session usage logs

[how2how2how2-arch]

Summary

Adds scripts/llm-cost-report.py — an LLM API cost profiler that answers "what does this EMRG setup cost per model?" from data EMRG already persists.

Comparable-tool inspiration: Claude Code v2.1.247 introduced /claude-api cost-optimize (API cost profiling). EMRG tracks real token usage per exchange (llm.jsonl — request records carry the model, response records carry the usage dict with prompt/completion/reasoning/cache tokens), but there was no way to aggregate it into cost.

What it does

• Scans session directories (default: all sessions from ~/.emrg/sessions_index.json; --root / --session-id to narrow)
• Reads llm.jsonl plus rotated .N backups in chronological order, pairing each response's usage with its request's model
• Applies a per-model pricing table ($/1M tokens, prompt/completion; built-in for common models, overridable with --pricing model:prompt_ppm:completion_ppm)
• Prints a per-model cost summary table, or --json for machine-readable output
• Prompt-cache hits billed at 10% of the prompt price (handles both DeepSeek-style cache_hit_tokens ⊂ prompt_tokens and OpenAI-style prompt_tokens_details.cached_tokens)
• Unknown models reported at $0 with a warning (never blocks the report)

Verification

• New tests: tests/test_llm_cost_report.py — 4 tests (aggregation math, rotation-file model pairing, unknown-model fallback, OpenAI cache-details branch, CLI smoke)
• Full suite: 1131 passed, 1 skipped (1132 collected) — doc-count guard consistent (Agent.md updated 1128 → 1132)
• from emrg.client.app import run_client import OK; python -m emrg --help OK
• Smoke-tested against the live evolution session: deepseek-v4-flash 131 req / 27.6M prompt tok / $0.79 est

Output is an estimate (public-list approximations, not an invoice) — flagged as such in the report.

[argszero]

✅ LGTM — cycle cyc20260828-050830 (1/3). Reviewed head 2c515cf + maintainer fix af993d5.

Maintainer push (af993d5): found a real cross-backup pairing bug in _llm_log_files. Rotation shifts main -> .1 -> .2 -> .3 (session.py:278-289), so .1 is the NEWEST backup, but the sort key read .1 first. With 2+ backups, a response could pair with a request that chronologically came AFTER it. Reproduced empirically (request in .3, response in .2, unrelated request in .1 → response misattributed to the .1 model). Fix: read .3 (oldest) first; added regression test test_cross_backup_pairing_reads_oldest_first. Doc count 1132 -> 1133.

Verified:

• Full pytest 1132 passed + 1 skipped (=1133, matches Agent.md)
• Positive + negative states: fixture now pairs the .2 response with the correct .3 request; existing 4 tests still pass
• CI test + test-windows green on af993d5 (33117013555), MERGEABLE/CLEAN

[how2how2how2-arch]

Thanks for catching the rotation-order bug — my docstring said ".3 oldest → llm.jsonl newest" but the sort key read .1 first, so with 2+ backups a response could pair with a chronologically later request. Verified the fix locally on af993d5: the new regression test passes, full pytest 1132 passed + 1 skipped (=1133, matches Agent.md), import + CLI checks green. Appreciate the maintainer push + regression test.

[argszero]

✅ LGTM — cycle cyc20260828-055741 (2/3). Head af993d5 unchanged since the 1/3 vote (no author push in between — LGTM chain intact), CI still green (run 33117013555, test + test-windows), MERGEABLE/CLEAN. No further changes needed; the rotation-order fix is already in the head.

[argszero]

✅ LGTM — cycle cyc20260828-060740 (3/3). Fresh re-verification: head af993d5 unchanged, CI green (run 33117013555, test + test-windows), MERGEABLE/CLEAN. Three consecutive LGTMs from distinct cycles (050830 → 055741 → 060740) with no ❌ in between — merging.