Chat prompt-cache bench (kkrsb)

npm run bench:chat-cache replays scripted chat turns through the real plannerTurn loop (real system prompt, real tool list, real read-only tools) and reads the provider's own cached-token count from each call. It answers "does this change keep the prompt prefix byte-stable", with a control scenario that must read 0%.

# DRY RUN (the default): prints the scenario plan, which provider keys are present (names only)
# and an estimated call count. No network call, nothing spent.
npm run bench:chat-cache

# Spend: a few cents on DeepSeek for the two-scenario check
npm run bench:chat-cache -- --real --providers deepseek --scenarios steady,control --tag before

# Every scenario on several providers
npm run bench:chat-cache -- --real --scenarios all --providers deepseek,openrouter,anthropic --tag after

# Flags: --scenarios --providers --window (trim scenario context window) --tag --verbose
# Env fallbacks: BENCH_SCENARIOS, BENCH_PROVIDERS, BENCH_WINDOW, BENCH_TAG

Scenarios: steady, resume (implies steady), memory, preamble, cap, trim, control (the first bytes of system[0] change every turn, so changed calls read 0%), reasoning. Keys are read from .env.local, .env and ~/.cyberine/.env (first one that sets a variable wins, an already exported variable wins over all three) and never printed. Defaults: scenario steady, provider deepseek, tag an ISO timestamp, window 22500 tokens. Results land in .local/research/bench/<host>/chat-cache-<tag>.json (gitignored; host is the short host token: first DNS label, lowercased, leading <user>- dropped, so niafam-m3max becomes m3max). The run prints the per-call table and a per-scenario summary: calls, hit ratio, cost and the worst call after the scenario's cold start.

Known Limitations and Deferred Work: not a selftest, not in the sweep or the promotion check; run it by hand. The first call of a scenario can read warm when an earlier run touched the same prefix, so compare the control and later calls, not call one. The call estimate assumes about two model calls per turn and the real count varies with the model's tool use. Anthropic and OpenRouter report cached tokens in their own usage shapes and are less exercised than DeepSeek. One sample per scenario, no repeats; the provider's cache is shared and time-dependent.