Summary

• Bug: runPreflightCompactionIfNeeded returned early when totalTokensFresh === true without checking the compaction threshold, so auto-compaction never triggered for sessions with fresh token counts — even at 153% of the context window
• Root cause: The early-return optimization (skip transcript estimation when fresh data is available) accidentally bypassed the threshold comparison entirely
• Fix: Restructure token resolution so fresh persisted totals (which include cacheRead from Anthropic prompt caching) are projected forward and checked against contextWindow - reserveTokens - softThreshold before deciding whether to compact

Details

When Anthropic's prompt cache absorbs nearly all tokens (100% hit rate), derivePromptTokens correctly computes input + cacheRead + cacheWrite (e.g. 99 + 305,000 + 0 = 305,099), and this is persisted as totalTokens with totalTokensFresh: true. However, runPreflightCompactionIfNeeded had this logic:

if (!shouldUseTranscriptFallback) {
    return entry;  // BUG: skips threshold check entirely
}

The fix moves the threshold check into both branches (fresh and stale), using the fresh persisted value directly when available.

Edge cases verified

• 100% cache hit (Anthropic): totalTokens=305k, contextWindow=200k — compaction now fires
• 0% cache hit: Stale tokens fall through to transcript estimation path — behavior unchanged
• Partial cache: 180k total with 166k threshold — fires correctly
• Below threshold: 50k total with 166k threshold — no compaction, as expected
• Heartbeat/CLI: Still skipped regardless of token count
• Non-Anthropic providers: No change — providers without caching have cacheRead=0, so totalTokens is just input + cacheWrite, same as before

Test plan

• shouldRunPreflightCompaction unit tests: 100% cache hit triggers, below threshold skips, partial cache boundary correct
• runPreflightCompactionIfNeeded integration tests: fresh tokens above threshold trigger compaction, below threshold skip, stale tokens use transcript fallback, heartbeat skips
• All existing compaction tests pass unchanged
• Session usage persistence tests pass (65 tests)
• Followup runner tests pass (19 tests)
• Preemptive compaction tests pass (9 tests)

Fixes openclaw#66520

🤖 Generated with Claude Code