fix(combo): failover when upstream SSE is truncated mid-lifecycle

[Chewji9875]

Summary

Fix combo silent-stop fallback: when a combo target's upstream SSE stream
ends mid-lifecycle without a recognised terminator (data: [DONE],
message_stop, finish_reason, or terminal usage), the combo now
fails over to the next target instead of returning a half-finished
stream that hangs the downstream SSE parser.

Before this fix the streaming quality validator in
open-sse/services/combo/validateQuality.ts had a !sawAnyBytes gate
that any byte — even unparseable garbage or a partial data: payload —
satisfied. The validator returned valid: true, the combo passed the
truncated stream through, and OpenCode (or any OpenAI-compatible SSE
client) hung waiting for events that never came.

The gate is now tightened to require the stream to have either seen a
recognised terminator (sawTerminator) or any parseable SSE framing
(sawStructuredSSE). Only when neither is true does the stream get
classified as invalid for combo failover. The #3399/#3685 pass-through
contract for ping/metadata/[DONE]-only streams is preserved.

Related Issues

• Closes #N/A (user-reported from local dashboard log id
  1784230812441-bf3789; no public GitHub issue exists)
• Preserves contracts from fix: server-side context cache pinning, stop proxy message leaks, persist context_cache_protection toggle #3399 (ping-only pass-through) and
  Streaming combo returns "[Proxy Error] The upstream API returned an empty response" instead of failing over #3685 (incomplete Claude lifecycle pass-through)

Validation

• node --import tsx/esm --test tests/unit/validate-response-quality.test.ts — 12/12 pass
• node --import tsx/esm --test tests/unit/combo-quality-validator-reasoning.test.ts — pass
• node --import tsx/esm --test tests/unit/masked-200-exhaustion-fallback-6427.test.ts — pass
• node --import tsx/esm --test tests/unit/combo-streaming-empty-content-failover.test.ts tests/unit/combo-empty-content-failover-5085.test.ts tests/unit/combo-response-validation-failover.test.ts tests/unit/combo-response-validation.test.ts — 20/20 pass
• prettier --write on touched files (clean)
• eslint on touched files (clean)
• npm run lint (full repo)
• npm run test:unit (full repo)
• npm run test:coverage
• Coverage is still >= 60% for statements, lines, functions, and branches
• SonarQube PR analysis is green or any remaining issues are explicitly documented below

Tests Added Or Updated

• tests/unit/validate-response-quality.test.ts — 4 new regression
  tests:
  1. Incomplete lifecycle (bytes with no terminator and no structured SSE) → valid: false (the bug, reproduced from the user log)
  2. data: [DONE] only (no content) → still valid: true
     (regression guard for Streaming combo returns "[Proxy Error] The upstream API returned an empty response" instead of failing over #3685)
  3. event: ping only (no content, no terminator) → still valid: true
     (regression guard for fix: server-side context cache pinning, stop proxy message leaks, persist context_cache_protection toggle #3399)
  4. OpenAI finish_reason-only chunk (no content delta, no trailing
     [DONE]) → valid: true (isolates the new finish_reason check)

Coverage Notes

The touched files (open-sse/services/combo/validateQuality.ts and
tests/unit/validate-response-quality.test.ts) are covered by the new
test cases and the existing combo-streaming-empty-content-failover
suite. The new flags (sawTerminator, sawStructuredSSE) and the
tightened done-branch guard are exercised by all four new tests; the
existing #3685 tests continue to confirm the pass-through contract for
incomplete Claude lifecycles.

Reviewer Notes

• Blast radius: change is scoped to the streaming branch of
  validateResponseQuality (lines ~106–327). Non-streaming path is
  untouched. All three combo call sites
  (combo.ts::handleComboChat, combo.ts::handleRoundRobinCombo,
  runtimeUnits.ts) share the validator, so the fix propagates
  automatically.
• Public contracts preserved: the #3399 (ping/metadata
  pass-through) and #3685 (incomplete Claude lifecycle
  pass-through) contracts are explicitly preserved via sawStructuredSSE
  and sawTerminator; see the comment block at the flag declaration
  in validateQuality.ts.
• New tracking in parseAccumulatedSse:
  • data: [DONE] is now marked as a terminator (previously skipped)
  • OpenAI finish_reason in any choice delta is now tracked
  • Terminal usage-only chunks (no choices, not a Responses API
    event) are now tracked
  • Claude message_stop and message_delta with stop_reason are
    co-located with the existing hasLifecycleEnd updates
• Risk: low. The new gate is strictly tighter than the previous one
  (more streams are now classified as invalid); the four new tests are
  designed to catch any over-tightening regression. The 27 existing
  validator / combo-quality / failover tests still pass.
• Manual validation: no manual steps required to validate — the
  four new tests reproduce the user's exact failure mode at the unit
  level.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[diegosouzapw]

Thanks for tracking down log 1784230812441-bf3789 — the root cause is real and still present on release/v3.8.49 tip: the generic silent-stop gate in validateResponseQuality (!anyContentFound && !sse.hasContentBlock && !sawAnyBytes) lets ANY byte, even unparseable garbage, bypass combo failover. I reproduced this with your own regression test against the current release tip (fails as expected) and confirmed your fix (tightening to require a recognised terminator or structured SSE frame) resolves it.

One issue: this branch predates two fixes that already merged into release/v3.8.49 — issue #7285 (OpenAI-shape stream truncated without finish_reason, OpenAiLifecycleFlags) and issue #1382 (Claude real-content vs. empty-content_block nuance, SseLifecycleFlags.hasRealContent). Your diff deletes both and replaces them with an older, coarser implementation, which would be a regression if merged as-is. The base also carries some unrelated CI-infra commits (.mergify.yml, config/quality/quality-baseline.json, a check-test-masking test) that don't belong in this PR and are already superseded on release.

We're going to rebase your fix onto the current file — keeping the #7285/#1382 logic intact and adding your sawTerminator/sawStructuredSSE tracking alongside it, plus your 4 new regression tests. I validated that combination locally: all 51 tests across the touched area (yours + the #7285/#1382/#6427/failover suites) pass green. You'll be credited as co-author on the landed commit. Appreciate the sharp bug catch and the clean TDD test — this was a real gap.

[diegosouzapw]

Merged into release/v3.8.49 — thank you for the contribution, @Chewji9875! 🎉 Validated in the final R3 merge-train (full static gates + unit suite on a dedicated 32-core box) before landing.