feat(usage): track 5m/1h cache TTL split + alwaysLoad for nerve MCP

[pufit]

Summary

Two related improvements unlocked by upgrading the Claude Agent SDK from 0.1.60 → 0.2.82 (and the bundled Claude Code CLI from 2.1.111 → 2.1.142):

1. Track the 5-minute vs 1-hour ephemeral cache TTL split. The Anthropic API returns usage.cache_creation.ephemeral_{5m,1h}_input_tokens alongside the legacy aggregate. The two TTLs are billed at different rates (5m = 1.25x base, 1h = 2.00x base), so accurate per-turn cost attribution requires the split.
2. alwaysLoad: true on the in-process nerve MCP server. Skips Claude Code's tool-search deferral for the nerve server's tools (memory_recall, task_*, plan_*, notify, ask_user, react, etc.). These tools are used in nearly every session — deferring them only added a ToolSearch round-trip on startup.

Changes

Cache TTL split

• Migration v027 adds cache_creation_5m_input_tokens and cache_creation_1h_input_tokens columns to session_usage (default 0).
• extract_cache_ttl_split() parses usage.cache_creation.ephemeral_* from the raw API dict.
• record_turn_usage accepts the split as keyword args; the engine pulls it from ResultMessage.usage and persists it per turn.
• MODEL_PRICING now carries separate cache_write_5m and cache_write_1h rates per model (Opus 4.7: $6.25 vs $10.00 per MTok).
• estimate_turn_cost / estimate_cost_from_totals prefer the split when present; fall back to the legacy aggregate at the 5-minute rate for pre-v027 rows and older API responses.
• ContextBar surfaces nested ↳5m / ↳1h rows under "Cache created" when the split arrives.

alwaysLoad

• create_session_mcp_server / create_nerve_mcp_server set alwaysLoad: True on the returned SDK config. Requires Claude Code CLI >= 2.1.121; silently ignored on older versions. The SDK transport already passes through unknown keys verbatim under --mcp-config.

Compatibility

• SDK upgrade is internal cleanup — the public API is backward-compatible, all 564 pre-existing tests pass unchanged.
• Historical session_usage rows keep their existing aggregate in cache_creation_input_tokens; the new 5m/1h columns default to 0 and only get populated from the next turn forward.
• The cost estimator's fallback bills legacy rows at the 5-minute rate — the conservative default.

Test plan

• 17 new tests in tests/test_usage_cache_ttl.py (schema, parsing, persistence, pricing arity/monotonicity, 4 cost-estimation scenarios)
• 1 new assertion in tests/test_session_mcp.py::test_nerve_server_marked_always_load
• Full suite: 582 passing (was 564)
• Frontend npm run build clean (strict TS)
• Verified live on Pi after restart — migration applied, new sessions surface the 5m/1h split in the ContextBar tooltip, and nerve MCP tools no longer appear in the deferred-tools <system-reminder> block

Generated by Nerve