docs(failure-modes): document sse read timeouts and fix chunktimeout example

[basiliskus]

Summary

docs/KNOWN_FAILURE_MODES.md §9 recommended "chunkTimeout": 5000 (5 seconds) and a
requestTimeout key that OpenCode does not read. Copied as-is, the 5-second value would
abort nearly every long model response with SSE read timed out.

This replaces the example with the timeouts the usai-provider kit actually sets
(timeout 10 min, chunkTimeout 2 min under provider.usai.options), adds the
SSE read timed out retry symptom and its causes (long reasoning,
large tool-call generation, or a stall on the proxy/Zscaler/USAi path), notes that
OpenCode retries automatically (capped at five since 1.18.17), that chunkTimeout has no
default before 1.18.27 so the kit's 2 minutes is what introduces the idle timeout, and shows
how to raise or disable it per project.

Related Issues

Fixes #521

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• I have read CONTRIBUTING.md
• My commits follow the Conventional Commits format
• I have tested my changes locally
• I have updated documentation as needed
• I have not included any secrets, API keys, or sensitive information

Test Results

• Pinned markdownlint (npx --prefix .github/linters markdownlint-cli2 docs/KNOWN_FAILURE_MODES.md): 0 errors.
• Kit defaults read from the pinned usai-provider kit (agentic-coding-patterns
  6c6753c, v1.9.0), files/home/usai-config/opencode.jsonc.
• Version boundaries checked against OpenCode source at tags: chunkTimeout gains its
  300000 default in packages/opencode/src/provider/provider.ts at v1.18.27 (absent through
  v1.18.26); RETRY_MAX_RETRIES = 5 appears in packages/opencode/src/session/retry.ts at
  v1.18.17 (absent at v1.18.16). The devenv-opencode:1.0.0 image used by acq runs
  OpenCode 1.18.23 (opencode --version in a live sandbox), so it has the retry cap but no
  chunkTimeout default.
• Provider retry (attempt N): … is Paseo's wording (found in its app bundle), not
  OpenCode's TUI, hence the generic symptom text.

Additional Notes

Upstream context: anomalyco/opencode#17578 (large tool calls stalling the stream) and
anomalyco/opencode#51879 (open; would stop SSE keep-alive comments from resetting the
timer, which may make these timeouts appear more often).

AI-assisted; reviewed by the author.

[wz-gsa]

AI-assisted review (OpenCode), advisory — needs a human to confirm before it drives a change. Reviewed head 13332e33, current main at 16795300.

The core correction is right: requestTimeout is not the OpenCode provider key, 5 seconds is an unsafe streamed-chunk gap for normal long responses, and the current usai-provider config still sets timeout: 600000 plus chunkTimeout: 120000 under provider.usai.options. CI is fully green. One documentation-correctness blocker remains because the evidence and retry wording target OpenCode 1.18.x while the kit users receive now is 2.0.22.

Blocker — “1.18.17 and later give up after five” is false for current OpenCode 2.x

docs/KNOWN_FAILURE_MODES.md:266-268 says:

OpenCode 1.18.17 and later give up after five; earlier releases keep retrying until you abort

That was verified correctly for the old image: RETRY_MAX_RETRIES = 5 appears in v1.18.17's packages/opencode/src/session/retry.ts and is still present in v1.18.23/v1.18.27. But the patterns repo's current pinned OpenCode kit installs 2.0.22, not 1.18.23:

integrations/isolation/acq-kits/opencode/spec.yaml:
  OPENCODE_VERSION="2.0.22"

OpenCode 2 moved retry policy to packages/core/src/session/runner/retry.ts. In v2.0.22:

// general retry schedule
Schedule.recurs(10)

// timeout-specific cap
const MAX_TIMEOUT_RETRIES = 3
const isTimeout = (error) =>
  error.reason._tag === "Transport" && error.reason.code === "Timeout"

The chunk timeout enters exactly that timeout-specific path: packages/ai/src/route/transport/http.ts:125-127 raises a TransportError with code: "Timeout" when streamed data does not arrive before chunkTimeout. So current OpenCode gives a streamed timeout three retries after the initial attempt, not five; general non-timeout retryable failures use a separate ten-retry schedule.

This matters because §9 is operational guidance telling a user when retries are exhausted. “1.18.17 and later” includes 2.0.22 but gives the wrong bound for the software the current kit installs.

Please version-scope the statement instead of extending the 1.x rule indefinitely. For example:

OpenCode 1.18.17 through the 1.18.x line cap retries at five. Current OpenCode
2.0.22 caps transport-timeout retries at three (other retryable failures use a
separate policy). If retries run out, note the model, time, and operation...

or avoid hard-coding the retry count in the durable troubleshooting text and point readers at the installed version's retry behavior.

Related stale symptom wording — should update in the same edit

The exact v2.0.22 transport message is now “Timed out waiting for response data” (http.ts:127), not the v1-era SSE read timed out string. The issue title and reproduction correctly describe the v1.18 experience, and existing old sandboxes can still show it, so retaining the phrase as a legacy symptom is useful. But the doc should not imply that exact string is guaranteed in current 2.x. Something like “OpenCode reports a streamed-response read timeout (v1.18 may show SSE read timed out; v2 reports Timed out waiting for response data)” keeps both generations useful.

What still verifies clean on v2.0.22

The timeout guidance itself carries forward:

• DEFAULT_HTTP_TIMEOUT_MS = 300_000 is applied to headerTimeout and chunkTimeout when unset (packages/ai/src/schema/options.ts:55-67).
• Whole-request timeout remains unbounded when unset (packages/ai/src/route/transport/http.ts:112-113).
• chunkTimeout: false disables the idle timeout (timeoutDuration: false → infinity, line 142-143).
• The kit's explicit 120-second value therefore intentionally overrides the 5-minute default, exactly as the PR says.
• Raising it to 300000 or setting false is valid in v2's generated provider settings type.

No new issue needed: #521 already tracks this documentation defect, and this correction belongs in the same PR.

---

Method: compared the PR text to the current patterns usai-provider config and opencode kit pin; downloaded and searched OpenCode v2.0.22 source; traced chunkTimeout through the HTTP transport into the v2 retry policy; compared the relevant v1.18.16/17/23/27 tags to establish where the old five-retry claim is valid. No live timed-out request was generated, so UI rendering beyond the source error text is unverified.

[wz-gsa]

Verified the operational values against both repositories and upstream OpenCode source. The USAi kit currently sets timeout: 600000 and chunkTimeout: 120000; the replacement example nests chunkTimeout under provider.usai.options and removes the nonexistent requestTimeout. At OpenCode v1.18.26 chunkTimeout is unset unless configured; v1.18.27 changes the source to options["chunkTimeout"] ?? 300_000, exactly the documented five-minute default. The stream wrapper emits the literal SSE read timed out notice. Comparing v1.18.16...v1.18.17 shows RETRY_MAX_RETRIES = 5 and the meta.attempt > RETRY_MAX_RETRIES stop condition were introduced together, supporting the version boundary and earlier-unbounded statement. All checks pass and the PR is mergeable. No findings. AI-assisted review (OpenCode), formally approved with the maintainer’s explicit authorization; a human owns the merge.

[wz-gsa]

The head is still unchanged at 13332e33, and the current document still says "OpenCode 1.18.17 and later give up after five". My earlier blocker therefore remains. The later approval under my account came from a concurrent review that verified the v1.18 evidence but did not check the current kit's OpenCode 2.0.22 retry policy. In 2.0.22, streamed chunk timeouts are TransportError(code: "Timeout") and are capped by MAX_TIMEOUT_RETRIES = 3; general retryable failures use a separate 10-retry schedule. Please address the version-scoping and current v2 error text in the existing review before merge. No new issue needed; quickstart#521 already tracks the documentation defect.

[basiliskus]

Addressed in 20a904e. §9 now scopes both by version: OpenCode 2.0.22 (what the pinned kit installs) reports Timed out waiting for response data and caps timed-out requests at three retries (MAX_TIMEOUT_RETRIES, other retryable errors on a separate policy); 1.18.x keeps SSE read timed out and the five-retry cap from 1.18.17. Verified against v2.0.22 packages/core/src/session/runner/retry.ts and packages/ai/src/route/transport/http.ts.

[wz-gsa]

Re-review of 20a904ea: the version-scoping blocker is closed.

Verified directly against upstream source rather than only the PR text:

• OpenCode 2.0.22 raises TransportError(code: "Timeout") with message Timed out waiting for response data when the streamed chunk timer expires (packages/ai/src/route/transport/http.ts:125-127).
• Its timeout-specific retry path uses MAX_TIMEOUT_RETRIES = 3; other retryable errors use a separate ten-retry schedule (packages/core/src/session/runner/retry.ts:42-60,84).
• OpenCode 1.18.17 and 1.18.27 both define RETRY_MAX_RETRIES = 5, so limiting that statement to the 1.18.x line is accurate.
• The timeout semantics remain correct: 300000 ms is the default chunk/header timeout in 2.0.22, whole-request timeout is unbounded when unset, and false disables the idle timeout.
• Current usai-provider still explicitly sets timeout: 600000 and chunkTimeout: 120000, so the replacement example accurately shows a project-level override rather than pretending to be the kit default.

The doc now names both generations' actual symptom text and does not generalize 1.x retry behavior into 2.x. CI is fully green. Approving.

No new issue was needed; #521 already tracks the documentation defect this PR closes.