Session token usage grows unbounded via cache.read and causes unrecoverable context-window errors

[wang1970]

Description

Long-running sessions can grow their recorded token usage without a practical upper bound, especially through tokens.cache.read, until most models/providers fail with a context-window error and the session becomes unrecoverable.

In my real session, OpenCode reported approximately 56,128,248 total tokens while the persisted conversation data was small:

session tokens:
  input:        14,774,671
  output:           77,881
  reasoning:        20,400
  cache.read:   41,255,296
  cache.write:           0
  total:        56,128,248

stored rows for that session:
  message: 224 rows, ~0.52 MB JSON data
  part:   1042 rows, ~2.33 MB JSON data

After this, continuing the same session fails with:

Your input exceeds the context window of this model. Please adjust your input and try again.

The issue is not that the saved message JSON itself is tens of millions of tokens. The large number appears to come from cumulative session usage accounting. In particular, tokens_cache_read can grow very large over repeated turns.

Relevant code path observed in source:

packages/core/src/session/projector.ts
  tokens_input:       SessionTable.tokens_input + value.tokens.input
  tokens_output:      SessionTable.tokens_output + value.tokens.output
  tokens_reasoning:   SessionTable.tokens_reasoning + value.tokens.reasoning
  tokens_cache_read:  SessionTable.tokens_cache_read + value.tokens.cache.read
  tokens_cache_write: SessionTable.tokens_cache_write + value.tokens.cache.write

This makes session-level usage an ever-growing lifetime counter. That is fine for statistics, but it becomes dangerous if any compaction / routing / provider request / context-window logic treats cumulative session usage, especially cache.read, as if it represented the current prompt/context size.

Impact:

• Long sessions eventually hit provider context-window errors.
• Auto compaction does not reliably save an already-overflowed session.
• Once overflowed, the same session can repeatedly fail and effectively becomes unusable.
• opencode stats can become slow/hang on large databases/sessions.
• This affects providers/models with smaller context windows especially badly when using an auto model/router.

Expected behavior:

• Current context-window checks should be based on the actual messages that will be sent to the provider, not lifetime cumulative usage counters.
• cache.read should not be counted as current prompt/context tokens for overflow decisions.
• Auto compaction should trigger before the provider rejects the request.
• If a provider returns a known context-window error, OpenCode should attempt a safe compact/prune/retry or suggest/fork a new session instead of leaving the session dead.
• There should be a hard cap / safety guard for long-running sessions, e.g. archive/fork/reset usage or force compaction before sending.

Plugins

Only a local/custom provider/router was used (providerID: 9090, modelID: auto). No plugin-specific behavior is required to reproduce the core issue: repeated turns can accumulate session usage far beyond any real model context window.

OpenCode version

1.15.13

Steps to reproduce

1. Use OpenCode with a provider/model that reports token usage including cache read tokens.
2. Keep a long-running session active for many turns, especially with repeated cache hits or provider-side prompt caching.
3. Inspect the SQLite session row, for example:

select
  tokens_input,
  tokens_output,
  tokens_reasoning,
  tokens_cache_read,
  tokens_cache_write
from session
where id = '<session id>';

4. Observe that cumulative tokens_cache_read and total session tokens can grow to tens of millions even when the stored message/part JSON is only a few MB.
5. Continue the same session until the provider rejects the next request with a context-window error:

Your input exceeds the context window of this model. Please adjust your input and try again.

6. Try enabling aggressive compaction settings such as:

{
  "compaction": {
    "auto": true,
    "prune": true,
    "tail_turns": 1,
    "preserve_recent_tokens": 4000,
    "reserved": 12000
  }
}

The already-overflowed session still remains difficult/impossible to continue.

Screenshot and/or share link

No public share link, because the affected session contains private project data. Sanitized measurements are included above.

Related existing issues that look adjacent but do not mention the cache.read/cumulative-session-usage aspect:

• compaction loop and hitting context limit 200k on single request #29450 compaction loop and hitting context limit 200k on single request
• Auto-compaction enabled by default, but context_length_exceeded errors still occur in agent workflows #8089 Auto-compaction enabled by default, but context_length_exceeded errors still occur in agent workflows
• [BUG]: /compact can exceed model context before summarization on large sessions #29857 /compact can exceed model context before summarization on large sessions
• prompt is too long unrecoverable #4845 prompt is too long unrecoverable

Operating System

Windows 11

Terminal

Windows Terminal / PowerShell

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Multi-step tool calls overwrite token counts instead of accumulating (output, reasoning, cache.write lost) #21913: Multi-step tool calls overwrite token counts instead of accumulating — discusses related token counting bugs in processor.ts including cache.read handling, with proposed fixes that overlap with the root cause described here.
• Unusable sessions after 1.14.24 upgrade. New messages on session with just 161.2k context are now triggering compaction but never succeeds. It claims to have over 1M context. Conversations before 1.14.24 are now unrecoverable because of this. #24249: Unusable sessions after context overflow — describes the same end symptom of sessions becoming unrecoverable due to context/compaction issues.

[wang1970]

Thanks for the pointers. I checked both suggested issues and I think this report is related but not a straight duplicate.

Clarification:

• Multi-step tool calls overwrite token counts instead of accumulating (output, reasoning, cache.write lost) #21913 is about per-assistant-message multi-step accounting in processor.ts: whether fields are overwritten vs accumulated within one assistant message. It explicitly treats cache.read as a per-step/session snapshot-like value that should not be summed within one multi-step message.
• This issue is about session-level persisted counters in the projector/database growing unbounded across many turns, especially session.tokens_cache_read. In my case the stored session row reached:

total ~= 56,128,248
input = 14,774,671
output = 77,881
reasoning = 20,400
cache.read = 41,255,296

while the persisted content was only:

message: 224 rows, ~0.52 MB
part:    1042 rows, ~2.33 MB

So the main distinction is: cache.read may be reasonable as a provider usage/cost metric, but it should not be allowed to make the session's effective context accounting / compaction threshold / context display / recovery behavior look like tens of millions of tokens when the actual stored prompt material is only a few MB.

• Unusable sessions after 1.14.24 upgrade. New messages on session with just 161.2k context are now triggering compaction but never succeeds. It claims to have over 1M context. Conversations before 1.14.24 are now unrecoverable because of this. #24249 looks like the same end symptom (session becomes unrecoverable after context/compaction overflow), but it does not identify the cache.read-dominated session counter growth. My report adds a concrete 1.15.13 measurement and the breakdown showing that the inflated value is dominated by cached reads rather than actual message text.

If this should be merged into one of those issues, the key extra signal to preserve is: session-level cumulative tokens_cache_read can dominate token totals and make context/compaction behavior diverge from real prompt size. A likely fix is to separate billing/usage totals from effective-context accounting, and exclude/handle cache-read tokens differently for context-window/compaction decisions.

[wang1970]

Bump — this issue has been open for 10 days without any maintainer response.

To add urgency: the unbounded cache.read accumulation is not just a cosmetic counting bug. It directly causes massive token over-consumption in real usage. Sessions that should have only consumed a few hundred thousand tokens are being accounted as tens of millions, which triggers premature context overflow, failed compaction, and forces expensive re-sends of entire conversation histories.

For anyone hitting the same problem: every long session is silently burning tokens at an inflated rate. This is a cost and usability regression that affects all OpenCode users with non-trivial session lengths.

Could a maintainer take a look? The core fix seems straightforward — separate billing/usage totals from effective-context accounting, or exclude cache.read from context-window/compaction decisions. Happy to help test or provide more data if needed.

[Necmttn]

The fix likely needs two counters, not one corrected sum. Keep cumulative billing/usage counters separate from the active context-window counters used for eligibility and compaction decisions.

cache.read can be meaningful for cost and provider accounting, but it should not make the next prompt look like it contains 41M active tokens. A good regression would assert that repeated cached turns increase billed/cache usage while active context stays bounded by retained messages plus current tool/schema overhead.

---

Generated with ax.

[AdityaPagare619]

Same thing on my end. Session had 937M cache read tokens but only ~41MB of
actual data. The cumulative counter was way out of sync with reality.

This made the context overflow from Bug #3 worse — the session thought it
was already over the limit when the actual context was still manageable.