Stream-start timeout is shown to the user as a raw error instead of failing over

[code-yeongyu]

Summary

When the provider accepts a request but never emits a first stream event, the session's visible outcome is the watchdog string Provider stream start timed out after <n>ms (optionally with the retry.provider.streamStartTimeoutMs hint). Same-model retries may run, but the turn does not fail over unless retry.fallbackChains has an explicit key for the current model. There is no shipped default chain. Start-time model-profile rungs are not used mid-session. The process stays up; this is not an uncaughtException crash.

Observed

• Assistant / error line: Provider stream start timed out after 180000ms (bare prefix; current builds also append a setting hint).
• 180000 is not the shipped start default (300000, clamped to the idle timeout). It is an explicit retry.provider.streamStartTimeoutMs or min(300000, idle) where idle is 180000 via httpIdleTimeoutMs or retry.provider.timeoutMs.
• No transparent switch to another model. Session remains on the failed turn.

Expected

1. Process and session stay alive.
2. Dead request is aborted at the stream-start bound; same-model retry spends the configured budget without shrinking that bound.
3. If another model is available (configured retry.fallbackChains or a later model-profile / category rung), switch to it and show the fallback notice. A successful fallback answer is the outcome.
4. If nothing else can serve, show a recovery message: provider never started streaming, N attempts spent, configure /fallback and/or raise retry.provider.streamStartTimeoutMs (0 disables). Do not leave the raw watchdog interpolation as the only visible line.
5. Failed stall assistants must not remain the visible answer while retry or fallback continues.

Related

• senpi#1183 (open): same error class escaping as uncaughtException on an older build. Different symptom; stub seam today handles the timeout as an assistant error with zero uncaughtException.
• senpi#723 (closed): retry after stream-start timeout re-billed cache.
• PRs that already touched this area: fix: bound provider stream start so dead upstreams fail fast instead of freezing sessions #451 (watchdog), fix(coding-agent): escalate repeated provider-stream stalls to the fallback chain #453 / fix(coding-agent): retry provider stream stalls on the shared bounded budget #845 (stall retry budget), fix(coding-agent): harden provider retry watchdogs #1117 (continuation watchdog), fix(retry-fallback): give chainless models a wildcard escape lane #1180 (wildcard lane, later removed), fix(agent): name the stream-start knob in timeout errors #1274 (setting name in the error), fix: make provider retry and stream-start timeouts tolerant of slow thinking models #1276 (90s→300s, retries 3→5), fix: remove implicit wildcard fallback and Cursor expansion #1380 (explicit-only chains — why no_chain fires).

Notes for maintainers

Decision point: RetryFallbackController.nextCandidate returns undefined and logs no_chain when resolveChainKey finds no exact/base key. DEFAULT_FALLBACK_CHAINS is empty. TUI prints Error: ${message.errorMessage} for assistant stopReason: "error".

[code-yeongyu]

Fixed by #1744, merged as 759d3f0612147096898a82dc4e6bb8e9559765d2.

What changed. The watchdog's own wording is a classifier token, so it stays on the assistant message where the retry engine reads it — and it is no longer what the user is shown. packages/ai/src/utils/retry.ts gains a table with one row per stall watchdog (stream-start, idle, WebSocket liveness, Responses completion), each mapping to what the provider actually failed to do in plain words plus the setting that widens that bound where one exists, and describeProviderStallForUser() renders it. The interactive transcript, print mode and the session's end-of-turn text all read that single definition, so the four surfaces cannot drift apart. The recovery sentence depends on real state: a configured chain that ran out says so, no configured chain points at the fallback command.

Failover. A stall now hands the turn to the next candidate and that candidate's answer becomes the turn's outcome, rather than the user being left with a timeout string and having to switch models by hand. When nothing is left to try, the turn ends with the plain-language explanation naming what stalled.

Evidence. Four tests, RED before the fix: the session stays alive and never shows the raw watchdog string as the turn's outcome; the stall stays classified for the retry engine while only the user copy is rewritten (so the fix cannot silently break retry classification); the turn is handed to the next candidate and its answer is the outcome; and the no-candidate case explains the stall in plain language. Tests ran on a second machine, and CI on the merge head reported 27 checks with zero failing and zero pending.

Interaction with #1739. That work landed first and touches the same two files (retry.ts, agent-session.ts) for the throughput-degraded class. The merge auto-resolved the code cleanly; only four changelog files conflicted and both entries were kept. I verified on the merged tree that both features are present and intact: the throughput predicate, the watchdog module, the degraded session event, and this PR's stall describer.

Scope note. #1183 reported the same error class exiting the process through an uncaught exception on an older version. This change is about the surfacing and failover path; the process-liveness assertion is covered by the first test here, but if the uncaught-exception path still reproduces on its own repro steps, that issue should stay open on its own merits.