diff --git a/docs/KNOWN_FAILURE_MODES.md b/docs/KNOWN_FAILURE_MODES.md
index f403c49d..8a3cba71 100644
--- a/docs/KNOWN_FAILURE_MODES.md
+++ b/docs/KNOWN_FAILURE_MODES.md
@@ -222,6 +222,9 @@ Agent assumes host filesystem layout, not container layout.
 - Requests never return
 - Agent appears stuck
 - Eventually fails with timeout
+- OpenCode shows a retry notice for a streamed-response read timeout: `Timed out
+  waiting for response data` on OpenCode 2.0.22 (the version the kit installs),
+  `SSE read timed out` on 1.18.x
 
 ### Root Cause
 
@@ -229,17 +232,45 @@ Agent assumes host filesystem layout, not container layout.
 - Network routing issues inside container
 - DNS resolution failures
 - Proxy misconfiguration
+- Streamed-response read timeout: the response sent no data for longer than the
+  provider's `chunkTimeout`. OpenCode before 1.18.27 has no default for this option
+  (unset means no idle timeout; 1.18.27 and later default to 5 minutes), so on those
+  versions the 2-minute value the `usai-provider` kit sets is what makes it fire.
+  Common during long reasoning or while the model generates a large tool call (such
+  as writing a long file), or when a hop on the path (sandbox proxy, Zscaler, USAi,
+  the upstream model) stalls. OpenCode retries automatically, so an occasional one
+  is harmless.
 
 ### Fix
 
-Set explicit timeouts in config:
+The `usai-provider` kit sets both timeouts under the provider's `options` in its
+[`opencode.jsonc`](https://github.com/GSA-TTS/agentic-coding-patterns/blob/main/integrations/isolation/acq-kits/usai-provider/files/home/usai-config/opencode.jsonc):
+`timeout` (whole request, 10 minutes) and `chunkTimeout` (gap between streamed
+chunks, 2 minutes); check that file for the current values. If the read timeout
+recurs, raise `chunkTimeout` in the project's `opencode.json`. The example below
+uses 5 minutes, the default OpenCode 1.18.27 and later ship; `false` disables the
+idle timeout entirely. A higher value makes a truly hung stream take longer to fail
+over to the retry. Do not set it to a few seconds: normal model pauses would then
+abort nearly every long response.
+
 ```json
 {
-  "requestTimeout": 30000,
-  "chunkTimeout": 5000
+  "provider": {
+    "usai": {
+      "options": {
+        "chunkTimeout": 300000
+      }
+    }
+  }
 }
 ```
 
+If the retries run out (OpenCode 2.0.22 gives up after three retries of a timed-out
+request, while other retryable errors follow a separate policy; 1.18.17 through the
+1.18.x line stop after five; earlier releases keep retrying until you abort), note
+the model, the time, and what the agent was doing, so a slow model can be told
+apart from a network stall.
+
 Check network connectivity from inside container:
 ```bash
 acq exec <sandbox> -- curl -I https://api.gsa.usai.gov/api/v1/models