fix(session): cap retry schedule at RETRY_MAX_ATTEMPTS = 3

[truenorth-lj]

Issue for this PR

Closes #21960

Prior reports (this addresses what the community has already raised, with credit to the original reporters):

• fix(session): SessionRetry.policy() retries forever with no max attempt count #21960 by @dangeReis — original detailed report with the exact same fix proposal
• Session retry loops forever — no max attempt cap or configurable limit #25733 by @Fatty911 — same root cause, also asks for a configurable limit (could be a follow-up to this PR if useful)
• [Bug]: Session processor retries indefinitely with unbounded exponential backoff — no max retries or circuit breaker #17648 — earlier observation of the same unbounded-retry behaviour

Type of change

• Bug fix (non-breaking change which fixes an issue)

What does this PR do?

Adds a hard upper bound to the retry schedule in packages/opencode/src/session/retry.ts policy().

Before: the schedule had no numeric cap on attempts. It continued as long as retryable() returned a truthy value, which meant a misclassified-retryable error (or an upstream that's permanently unhealthy but keeps emitting retryable signals) could spin without bound.

After:

export const RETRY_MAX_ATTEMPTS = 3                  // alongside existing RETRY_* constants

// inside policy() schedule step:
if (meta.attempt > RETRY_MAX_ATTEMPTS) return Cause.done(meta.attempt)

With the existing 2-4-8 s backoff this gives a wall-clock retry budget of ~14 s for a worst-case run.

Context: This PR is the standalone bug-fix half of the closed #26343. That PR additionally proposed a header-driven retry classification using custom X-Llm-Error-* headers, which @rekram1-node correctly closed as non-standard. This PR drops that part entirely — only the standalone schedule-cap remains. Any proxy can express retry semantics through the standard signals already handled by retryable():

Outcome	Standard signal
Rate limited, retry later	429 Too Many Requests + Retry-After
Provider overloaded, retry later	503 Service Unavailable + Retry-After
Budget exceeded, don't retry	402 Payment Required (4xx → no retry)
Context overflow, don't retry	400 Bad Request (4xx → no retry)

How did you verify your code works?

$ bun test packages/opencode/test/session/retry.test.ts
 31 pass
 0 fail
 41 expect() calls
$ bun run typecheck
 Tasks: 12 successful, 12 total

The new test (session.retry.policy.maxAttempts) drives the schedule RETRY_MAX_ATTEMPTS + 1 times and asserts that the set() callback was invoked exactly RETRY_MAX_ATTEMPTS times.

Screenshots / recordings

N/A — no UI changes.

Checklist

• I have read the Contributing Guidelines
• My code follows the code style of this project
• I have added tests that prove my fix is effective
• All new and existing tests pass
• No new dependencies introduced

[MidAutumnMoon]

Hi, how about making retries configurable instead of hardcode 3? I find it quite handy sometimes to be able to retry several times.

[niStee]

Hey, thanks for capping the max attempts! However, this doesn't fully fix the issue for users hitting the 429 hard monthly quota limit from the opencode proxy. The proxy returns a 429 with an 18-day retry-after header, which causes the session to politely slumber for weeks rather than triggering a fallback. We implemented a local patch on packages/opencode/src/session/retry.ts in the policy function: if (wait > 60_000) return Cause.done(meta.attempt). We highly recommend capping the max wait duration to 60s, regardless of the HTTP standard, to prevent these runaway session freezes when the proxy misuses 429 for monthly quotas!

[carlosflorencio]

Thanks for capping this — it fixes the runaway transient case. One gap that echoes @niStee's comment above: for the hard GoUsageLimitError weekly/monthly Go limit, delay() returns the full retry-after (hours), so each of the 3 attempts sleeps for ~6h. Capped at 3 that's still ~18h of silence before the schedule gives up — and over ACP the session/prompt call is synchronous, so the client gets zero frames that entire time (repro + wire capture in #21960).

Suggestion: keep the attempt cap for transient 5xx / generic 429s, but treat the account_rate_limit class (GoUsageLimitError) as non-retryable / fail-fast in retryable() — since its retry-after is hours, retrying never helps within a session. That way it halts immediately and the failure can be surfaced (TUI already has the limit message; ACP needs #27779 / #29061 to make it protocol-visible). Happy to test a build against our ACP repro harness if useful.

[niStee]

I've pushed the local commits that resolve the silent slumber and network hang gaps we discussed:

1. fix(opencode): abort retry slumber on hard quota limits or excessive delay - Capped the slumber retry loop at 60 seconds.
2. fix(core): inject 180s TTFB default timeout in ai-sdk fetch wrapper - Added a hard timeout to prevent infinite network stalls.
3. docs(spec): mark background-task-fallback-gap as resolved - Updated the v2 spec to document these root-cause network fixes.

All fixes passed secret scanning locally and are actively preventing the gpt-5.5 network hangs in my live session right now. Ready for review!

[niStee]

Follow-up: I've also pushed a commit to mirror the 180s TTFB timeout patch into the v1 provider.ts fetch wrapper (see https://github.com/niStee/opencode/commits/local-stable). This ensures that subagents using providers like opencode-go also benefit from the timeout and cleanly fallback instead of hanging indefinitely on stale connections.

[github-actions]

Automated PR Cleanup

Thank you for contributing to opencode.

Due to the high volume of PRs from users and AI agents, we periodically close older PRs using automated criteria so maintainers can focus review time on the most active and community-supported contributions.

This PR was closed because it matched the following cleanup criteria:

• The PR was created more than 1 month ago
• The PR had fewer than 2 positive reactions
• Positive reactions are counted as thumbs-up, heart, celebration, or rocket reactions on the PR

PRs created within the last month are not affected by this cleanup.

If you believe this PR was closed incorrectly, or if you are still actively working on it, please leave a comment explaining why it should be reopened. A maintainer can review and reopen it if appropriate.

Thanks again for taking the time to contribute.