free tier: FreeUsageLimitError depends on request size — long sessions always fail while new sessions succeed #58751

Description

On the free tier (opencode/* models, no Go subscription, $0 Console balance) FreeUsageLimitError is not a simple "daily messages exhausted" state. It depends on the size of the individual request: a session with a large assembled context is rejected on every turn, while a new session on the same account succeeds in the same minute.

2026-10-25 00:06 local (UTC+8), same account, same machine, same model opencode/deepseek-v4.1-flash-free:

• ses_08a6d445… (July session: 985 user messages, 14,966 assistant messages, 45.9M input tokens, last successful request 126k tokens on 23 Oct 18:21, assembled context now ≈447k tokens, estimated from the 1.79 MB context payload) → Free usage limit reached…, idle outcome failed
• ses_e9155f04… (new session, 23k tokens per request) → normal answer 18 seconds later

So the quota is not "this account is blocked". The same account can still make small requests while a large session is refused.

Environment

• opencode 2.1.4, desktop app (bundled CLI), macOS (Darwin 25.6.0, arm64)
• Model: opencode/deepseek-v4.1-flash-free, agent build
• Shell: zsh; using the desktop app, not the TUI
• Plugins: 3 local plugins configured under ~/.config/opencode/plugins/*.ts; all three fail to load in 2.1.4 (Plugin must export a default definition), so effectively none are active
• Free tier only: no OpenCode Go subscription, no paid balance

Reproduction

1. Use only free opencode/* models.
2. Let one session grow until its assembled request context is several hundred thousand tokens. Mine has 99 context items / 1.79 MB (GET /api/session/{id}/context), and auto-compaction keeps it around that size.
3. Send any prompt to that session → Free usage limit reached. Connect a provider or subscribe to OpenCode Go to keep going, or switch models. Stored as an assistant message with error type provider.free-limit, followed by an idle message with outcome: "failed".
4. In the same minute, create a new session and send a prompt → it succeeds.

Expected Behavior

Either the request succeeds, or the error says what was exhausted and when it resets. The outcome should not depend on how much history a session carries.

Actual Behavior

The large session is rejected every time; small requests pass. Inside a single session the result flips with context size:

The last two rows are 6 seconds apart at the same size, which looks like a rolling bucket at its boundary rather than a hard per-request cap.

Usage history from the same machine (session_message, providerID=opencode):

20–21 Oct: heavy use, zero errors. 24 Oct: blocked from the first attempt. 25 Oct 00:06: works again, then ~730k input tokens in 45 minutes exhausts it. Something changed on the service side around 21–23 Oct, and the remaining allowance now behaves like a small bucket that refills over minutes/hours.

Additional Context

Client mapping: a QuotaExceeded error whose body contains FreeUsageLimitError becomes provider.free-limit with the message above. That is different from the "You've used today's free messages, they reset at …" copy, and I never see a reset time in this path.

How the numbers above were read (no instrumentation, just local state):

sqlite3 ~/.local/share/opencode/opencode.db "
select datetime(time_created/1000,'unixepoch','localtime') t,
       json_extract(data,'$.tokens.input') + coalesce(json_extract(data,'$.tokens.cache.read'),0) ctx,
       case when data like '%provider.free-limit%' then 'FAIL' else 'OK' end st
from session_message
where type='assistant' and json_extract(data,'\$.model.providerID')='opencode'
order by time_created desc limit 10;"

Related issues, and how this one differs:

• session: titles never generated in v2 (no auto trigger + free-tier rejection) #58176, session: automatic titles fail with 403 FreeTierError when using free models #58521 — titles never generated on free tier (tool-less request rejected with 403 FreeTierError). Separate problem.
• Free models report "Free usage limit reached" despite zero usage #58284, [BUG] FreeUsageLimitError raised with no free usage in the 24h window (free plan, $0 balance) — reset window not exposed to CLI/API #58205, Free models hit daily usage limit after only 20 seconds of use #58713, [Bug] Free usage limit immediately exceeded on the very first prompt after a fresh install/session #58641, Free usage limit error despite zero Console usage #58536 — "limit reached with zero usage". Here usage is real and the rejection correlates with per-request context size, reproducibly.
• [FEATURE]:Show exact free usage limit reset time #52894 — show the free-usage reset time.

Questions:

1. Is the free allowance documented anywhere (tokens or requests, per day or rolling window)?
2. Is rejecting a request because of its assembled context size intentional?
3. Can the client expose the remaining allowance and reset time in this error path, as [FEATURE]:Show exact free usage limit reset time #52894 asks?