Summary

Add a dedicated offline cache regression guard for Reasonix's DeepSeek prompt-cache path.

This PR introduces npm run cache:guard, backed by a synthetic DeepSeek driver that runs real CacheFirstLoop flows without making network calls. The guard captures each outbound chat request, renders a deterministic cache surface, estimates adjacent-request cache-hit ratios, and fails when a transition that should stay warm unexpectedly changes the immutable prefix or drops below the configured hit-ratio threshold.

Why this is necessary

Prompt-cache regressions are expensive but easy to miss:

• They usually do not break functional correctness, so normal unit tests can stay green while every tool-call iteration becomes a cache miss.
• A tiny request-shape change, such as losing an empty reasoning_content: "" field on historical thinking-mode assistant messages, can invalidate DeepSeek's prefix cache even when the rendered conversation looks semantically identical.
• These regressions are most visible only through production billing or provider usage fields, which is too late for PR review.
• Reasonix has several legitimate cache-break paths, such as MCP tool hot-add and Flash -> Pro one-shot escalation. A guard needs to distinguish expected one-time breaks from accidental persistent cache churn.

The new tool gives CI a cheap, deterministic check for this class of cost regressions before code is merged.

What it covers

The built-in scenarios exercise the main cache-sensitive dialogue shapes:

• plain multi-turn dialogue
• single tool-call round trip
• multiple tool calls in one assistant step
• thinking-mode reasoning retention / pruning behavior
• long-session resume with more than 200 retained messages
• MCP-like tool hot-add, allowing exactly one expected cache break and requiring the next turn to warm again
• Flash -> Pro one-shot escalation, allowing the model-switch breaks and requiring the restored Flash path to warm again

The cache surface intentionally includes model, tool schemas, system messages, normalized conversation messages, and field presence for reasoning_content, so the earlier high-cost failure mode is covered directly.

Usage

npm run cache:guard

Optional flags:

npm run cache:guard -- --threshold=0.92
npm run cache:guard -- --json
npm run cache:guard -- --keep-temp

The default threshold is 85%, chosen so naturally larger multi-tool continuations remain valid while structural prefix regressions still fail loudly.

CI integration

Adds a Cache guard step to the main CI workflow after lint/typecheck and before build/test coverage. This makes the guard run on both PRs and pushes to main.

Verification

• npm run cache:guard passes; lowest built-in scenario hit ratio: 87.1%.
• npm run test -- tests/cache-guard.test.ts passes: 3 tests.
• npm run typecheck passes.
• npm run lint exits 0; it still reports the existing src/cli/ui/PlanPanel.tsx import-type warning unrelated to this PR.
• Pre-push npm run verify passes: build, lint, typecheck, and full test suite (315 test files, 4044 tests passed, 9 skipped).