merge(local): Phase A — subagent hang hardening (chunkTimeout + retry budget)

Merges local/timeout-and-retry into local/integration.

Phase A addresses root causes #1 and #3 of subagent hangs:
  #1 No default chunk timeout on SSE streams
  #3 SessionRetry.retryable didn't match SSE/transport errors

Commits (10 total, each diamond-reviewed by default + codex-5.3):
  2463766 config(provider): chunkTimeout=false support
  90682b8 feat(message-v2): SSEStallError tagged error + cause-chain detection
  ae30ab3 fix(message-v2): throw SSEStallError class at provider SSE timeout site
  04c345a test(provider): failing tests for resolveChunkTimeout (RED)
  65917b4 test(provider): A.1.3 review fix — extended-thinking cross tests + tighter stall
  2d6ed17 feat(provider): resolveChunkTimeout + wrapSSE wiring (GREEN)
  1b8f62d test(retry): failing tests for transport retries + budget cap (RED)
  1ec5a36 test(retry): A.2.1 review fix — verify terminal Exit is Cause.done
  2176730 feat(retry): transport error matching + retry budget cap (GREEN)
  facd7c1 fix(retry): use plain Cause.done + Pull.isDoneCause (review fix)

Changes:
  - chunkTimeout config accepts number | false (parallel to timeout)
  - DEFAULT_CHUNK_TIMEOUT_MS=120_000 applied automatically
  - EXTENDED_THINKING_CHUNK_TIMEOUT_MS=600_000 for anthropic,
    google-vertex-anthropic, amazon-bedrock
  - SSEStallError class in provider.ts; NamedError schema in message-v2.ts
  - hasSSEStallCause walks error cause chain (depth 8) and is checked
    before APICallError in MessageV2.fromError
  - SessionRetry.retryable matches: ETIMEDOUT, ECONNRESET, ECONNREFUSED,
    EAI_AGAIN, socket hang up, and SSEStallError instances
  - TRANSPORT_RETRY_CAP=5 enforces a hard stop on transport-class non-API
    errors via Cause.done(meta.attempt)

Tests (all live-clock, no TestClock deadlock): 54 pass, 0 fail.
Typecheck clean from packages/opencode.

Phase-final review verdict: spec APPROVED (codex-5.3),
quality APPROVED (default/Opus).

Non-blocking followups tracked:
  - openrouter→anthropic routing gets 120s default (widening logic or docs)
  - SDK types.gen.ts:1333 noisy duplicate union member
  - no end-to-end integration test (planned for Phase C)
  - TRANSPORT_RETRY_CAP not yet user-configurable
  - docs at packages/web/src/content/docs/config.mdx not yet updated
  - AbortSignal.any reason-fidelity needs Bun/Node version matrix test

No push. Branch stays local.

Author: tesdal

packages/opencode/src/config/provider.ts

@@ -98,9 +98,14 @@ export class Info extends Schema.Class<Info>("ProviderConfig")({
           description:
             "Timeout in milliseconds for requests to this provider. Default is 300000 (5 minutes). Set to false to disable timeout.",
         }),
-        chunkTimeout: Schema.optional(PositiveInt).annotate({
+        chunkTimeout: Schema.optional(
+          Schema.Union([PositiveInt, Schema.Literal(false)]).annotate({
+            description:
+              "Timeout in milliseconds between streamed SSE chunks for this provider. If no chunk arrives within this window, the request is aborted. Defaults to 120000 (120s) for most providers, 600000 (10min) for Anthropic-family providers (to accommodate extended thinking). Set to false to disable.",
+          }),
+        ).annotate({
           description:
-            "Timeout in milliseconds between streamed SSE chunks for this provider. If no chunk arrives within this window, the request is aborted.",
+            "Timeout in milliseconds between streamed SSE chunks for this provider. If no chunk arrives within this window, the request is aborted. Defaults to 120000 (120s) for most providers, 600000 (10min) for Anthropic-family providers (to accommodate extended thinking). Set to false to disable.",
         }),
       }),
       [Schema.Record(Schema.String, Schema.Any)],

packages/opencode/src/provider/provider.ts

@@ -31,13 +31,41 @@ import { ModelID, ProviderID } from "./schema"
 
 const log = Log.create({ service: "provider" })
 
+export class SSEStallError extends Error {
+  readonly _tag = "SSEStallError"
+  constructor(message: string) {
+    super(message)
+    this.name = "SSEStallError"
+  }
+}
+
 function shouldUseCopilotResponsesApi(modelID: string): boolean {
   const match = /^gpt-(\d+)/.exec(modelID)
   if (!match) return false
   return Number(match[1]) >= 5 && !modelID.startsWith("gpt-5-mini")
 }
 
-function wrapSSE(res: Response, ms: number, ctl: AbortController) {
+const DEFAULT_CHUNK_TIMEOUT_MS = 120_000
+const EXTENDED_THINKING_CHUNK_TIMEOUT_MS = 600_000
+const EXTENDED_THINKING_PROVIDERS: ReadonlySet<string> = new Set([
+  "anthropic",
+  "google-vertex-anthropic",
+  "amazon-bedrock",
+])
+
+export function resolveChunkTimeout(providerID: string, value: unknown): number {
+  if (value === false) return 0
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0) return 0
+    return value
+  }
+  if (value !== undefined) log.warn("unrecognized chunkTimeout value, using provider default", { providerID, value })
+  return EXTENDED_THINKING_PROVIDERS.has(providerID)
+    ? EXTENDED_THINKING_CHUNK_TIMEOUT_MS
+    : DEFAULT_CHUNK_TIMEOUT_MS
+}
+
+export function wrapSSE(res: Response, ms: number, ctl: AbortController) {
   if (typeof ms !== "number" || ms <= 0) return res
   if (!res.body) return res
   if (!res.headers.get("content-type")?.includes("text/event-stream")) return res
@@ -47,7 +75,7 @@ function wrapSSE(res: Response, ms: number, ctl: AbortController) {
     async pull(ctrl) {
       const part = await new Promise<Awaited<ReturnType<typeof reader.read>>>((resolve, reject) => {
         const id = setTimeout(() => {
-          const err = new Error("SSE read timed out")
+          const err = new SSEStallError(`SSE read timed out after ${ms}ms`)
           ctl.abort(err)
           void reader.cancel(err)
           reject(err)
@@ -1429,13 +1457,13 @@ const layer: Layer.Layer<
         if (existing) return existing
 
         const customFetch = options["fetch"]
-        const chunkTimeout = options["chunkTimeout"]
+        const resolvedChunkTimeout = resolveChunkTimeout(model.providerID, options["chunkTimeout"])
         delete options["chunkTimeout"]
 
         options["fetch"] = async (input: any, init?: BunFetchRequestInit) => {
           const fetchFn = customFetch ?? fetch
           const opts = init ?? {}
-          const chunkAbortCtl = typeof chunkTimeout === "number" && chunkTimeout > 0 ? new AbortController() : undefined
+          const chunkAbortCtl = resolvedChunkTimeout > 0 ? new AbortController() : undefined
           const signals: AbortSignal[] = []
 
           if (opts.signal) signals.push(opts.signal)
@@ -1468,7 +1496,7 @@ const layer: Layer.Layer<
           })
 
           if (!chunkAbortCtl) return res
-          return wrapSSE(res, chunkTimeout, chunkAbortCtl)
+          return wrapSSE(res, resolvedChunkTimeout, chunkAbortCtl)
         }
 
         const bundledLoader = BUNDLED_PROVIDERS[model.api.npm]

packages/opencode/src/session/message-v2.ts

@@ -56,6 +56,11 @@ export const APIError = NamedError.create(
   }),
 )
 export type APIError = z.infer<typeof APIError.Schema>
+export const SSEStallError = NamedError.create(
+  "SSEStallError",
+  z.object({ message: z.string() }),
+)
+export type SSEStallError = z.infer<typeof SSEStallError.Schema>
 export const ContextOverflowError = NamedError.create(
   "ContextOverflowError",
   z.object({ message: z.string(), responseBody: z.string().optional() }),
@@ -415,6 +420,7 @@ export const Assistant = Base.extend({
       StructuredOutputError.Schema,
       ContextOverflowError.Schema,
       APIError.Schema,
+      SSEStallError.Schema,
     ])
     .optional(),
   parentID: MessageID.zod,
@@ -938,6 +944,20 @@ export const filterCompactedEffect = Effect.fnUntraced(function* (sessionID: Ses
   return filterCompacted(stream(sessionID))
 })
 
+// Legacy substring fallback for rare paths where the tagged class gets stripped
+// during cross-realm rethrow. Primary signal is `name`/`_tag` set by SSEStallError.
+const SSE_STALL_MESSAGE_RE = /SSE (read|chunk) time(d out|out)/
+
+function hasSSEStallCause(e: unknown, depth = 0): boolean {
+  if (depth > 8) return false
+  if (!e || typeof e !== "object") return false
+  const err = e as { name?: string; _tag?: string; message?: string; cause?: unknown }
+  if (err.name === "SSEStallError" || err._tag === "SSEStallError") return true
+  if (typeof err.message === "string" && SSE_STALL_MESSAGE_RE.test(err.message)) return true
+  if (err.cause) return hasSSEStallCause(err.cause, depth + 1)
+  return false
+}
+
 export function fromError(
   e: unknown,
   ctx: { providerID: ProviderID; aborted?: boolean },
@@ -988,6 +1008,11 @@ export function fromError(
         },
         { cause: e },
       ).toObject()
+    case hasSSEStallCause(e):
+      return new SSEStallError(
+        { message: e instanceof Error ? e.message : String(e) },
+        { cause: e instanceof Error ? e : undefined },
+      ).toObject()
     case APICallError.isInstance(e):
       const parsed = ProviderError.parseAPICallError({
         providerID: ctx.providerID,

packages/opencode/src/session/retry.ts

@@ -13,11 +13,22 @@ export const RETRY_INITIAL_DELAY = 2000
 export const RETRY_BACKOFF_FACTOR = 2
 export const RETRY_MAX_DELAY_NO_HEADERS = 30_000 // 30 seconds
 export const RETRY_MAX_DELAY = 2_147_483_647 // max 32-bit signed integer for setTimeout
+export const TRANSPORT_RETRY_CAP = 5
+
+const TRANSPORT_PATTERNS = ["ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "socket hang up"]
 
 function cap(ms: number) {
   return Math.min(ms, RETRY_MAX_DELAY)
 }
 
+function transportMessage(error: Err) {
+  if (MessageV2.SSEStallError.isInstance(error)) return error.data.message
+  const msg = error.data?.message
+  if (typeof msg !== "string") return undefined
+  if (!TRANSPORT_PATTERNS.some((pattern) => msg.includes(pattern))) return undefined
+  return msg
+}
+
 export function delay(attempt: number, error?: MessageV2.APIError) {
   if (error) {
     const headers = error.data.responseHeaders
@@ -76,6 +87,9 @@ export function retryable(error: Err) {
     }
   }
 
+  const transport = transportMessage(error)
+  if (transport) return transport
+
   const json = iife(() => {
     try {
       if (typeof error.data?.message === "string") {
@@ -111,7 +125,11 @@ export function policy(opts: {
     Effect.succeed((meta: Schedule.InputMetadata<unknown>) => {
       const error = opts.parse(meta.input)
       const message = retryable(error)
+      const transport = transportMessage(error)
       if (!message) return Cause.done(meta.attempt)
+      if (transport && !MessageV2.APIError.isInstance(error) && meta.attempt > TRANSPORT_RETRY_CAP) {
+        return Cause.done(meta.attempt)
+      }
       return Effect.gen(function* () {
         const wait = delay(meta.attempt, MessageV2.APIError.isInstance(error) ? error : undefined)
         const now = yield* Clock.currentTimeMillis

packages/opencode/test/provider/chunk-timeout.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test"
+import { resolveChunkTimeout, SSEStallError, wrapSSE } from "../../src/provider/provider"
+
+describe("provider.resolveChunkTimeout", () => {
+  test("returns 120s default when undefined for generic provider", () => {
+    expect(resolveChunkTimeout("github-copilot", undefined)).toBe(120_000)
+  })
+
+  test("returns 600s default for Anthropic", () => {
+    expect(resolveChunkTimeout("anthropic", undefined)).toBe(600_000)
+  })
+
+  test("returns 600s default for google-vertex-anthropic", () => {
+    expect(resolveChunkTimeout("google-vertex-anthropic", undefined)).toBe(600_000)
+  })
+
+  test("returns 600s default for amazon-bedrock", () => {
+    expect(resolveChunkTimeout("amazon-bedrock", undefined)).toBe(600_000)
+  })
+
+  test("returns 0 when explicitly disabled with false", () => {
+    expect(resolveChunkTimeout("github-copilot", false)).toBe(0)
+  })
+
+  test("returns the user value when a positive number", () => {
+    expect(resolveChunkTimeout("github-copilot", 60_000)).toBe(60_000)
+  })
+
+  test("explicit positive number wins over extended-thinking default", () => {
+    expect(resolveChunkTimeout("anthropic", 30_000)).toBe(30_000)
+  })
+
+  test("false wins over extended-thinking default (returns 0)", () => {
+    expect(resolveChunkTimeout("anthropic", false)).toBe(0)
+  })
+
+  test("falls back to provider default for non-numeric junk", () => {
+    // Defensive branch — config schema prevents this, but runtime check guards misconfig.
+    expect(resolveChunkTimeout("github-copilot", "not-a-number" as never)).toBe(120_000)
+  })
+})
+
+describe("provider.wrapSSE — SSEStallError integration", () => {
+  test("throws SSEStallError when chunk read exceeds timeout", async () => {
+    const stream = new ReadableStream<Uint8Array>({
+      pull() {
+        return new Promise<void>(() => {}) // never resolves — forces stall
+      },
+    })
+    const res = new Response(stream, { headers: { "content-type": "text/event-stream" } })
+    const ctl = new AbortController()
+    const wrapped = wrapSSE(res, 2, ctl)
+    const reader = wrapped.body!.getReader()
+
+    await expect(reader.read()).rejects.toBeInstanceOf(SSEStallError)
+  })
+
+  test("does not wrap non-SSE responses", () => {
+    const res = new Response("hello", { headers: { "content-type": "text/plain" } })
+    const ctl = new AbortController()
+    expect(wrapSSE(res, 50, ctl)).toBe(res)
+  })
+
+  test("returns original response when ms <= 0", () => {
+    const res = new Response(new ReadableStream(), { headers: { "content-type": "text/event-stream" } })
+    const ctl = new AbortController()
+    expect(wrapSSE(res, 0, ctl)).toBe(res)
+    expect(wrapSSE(res, -1, ctl)).toBe(res)
+  })
+})

packages/opencode/test/session/message-v2-sse-stall.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test"
+import { APICallError } from "ai"
+import { SSEStallError } from "../../src/provider/provider"
+import { ProviderID } from "../../src/provider/schema"
+import { MessageV2 } from "../../src/session/message-v2"
+
+const providerID = ProviderID.make("github-copilot")
+
+describe("session.message-v2.fromError — SSEStallError", () => {
+  test("preserves SSEStallError for plain Error with SSEStallError name", () => {
+    const error = new Error("SSE read timed out")
+    error.name = "SSEStallError"
+
+    const result = MessageV2.fromError(error, { providerID })
+
+    expect(result.name).toBe("SSEStallError")
+    expect(result.data.message).toBe("SSE read timed out")
+  })
+
+  test("MessageV2.SSEStallError.isInstance returns true", () => {
+    const error = new Error("SSE read timed out")
+    error.name = "SSEStallError"
+
+    const result = MessageV2.fromError(error, { providerID })
+
+    expect(MessageV2.SSEStallError.isInstance(result)).toBe(true)
+  })
+
+  test("detects SSE stall by timeout message without SSEStallError name", () => {
+    const error = new Error("SSE chunk timeout after 120000ms")
+
+    const result = MessageV2.fromError(error, { providerID })
+
+    expect(result.name).toBe("SSEStallError")
+    expect(result.data.message).toBe("SSE chunk timeout after 120000ms")
+  })
+
+  test("detects SSE stall through two-deep cause chain", () => {
+    const stall = new SSEStallError("SSE read timed out")
+    const middle = new Error("middle")
+    middle.cause = stall
+    const outer = new Error("outer")
+    outer.cause = middle
+
+    const result = MessageV2.fromError(outer, { providerID })
+
+    expect(result.name).toBe("SSEStallError")
+  })
+
+  test("detects SSE stall when APICallError wraps SSEStallError", () => {
+    const stall = new SSEStallError("SSE read timed out")
+    const apiError = new APICallError({
+      message: "stream error",
+      url: "https://api.githubcopilot.com/chat/completions",
+      requestBodyValues: {},
+      cause: stall,
+    })
+
+    const result = MessageV2.fromError(apiError, { providerID })
+
+    expect(result.name).toBe("SSEStallError")
+    expect(MessageV2.APIError.isInstance(result)).toBe(false)
+  })
+})