OpenCode Free: runtime model failover and health signals for per-request availability

[cunninghamcard-bit]

Follow-up to #3409 / #3429, splitting out the layer that no static list can own.

#3429 resolves which free models are eligible (models.dev snapshot) and anonymously served (candidates ∩ /zen/v1/models at the discovery seam). The remaining layer is per-request availability, and the evidence from that thread shows why it must be reactive, at the Runtime Host execution seam:

• 429 FreeUsageLimitError is per-IP and point-in-time: the same id probed 429 and completed fine within hours, and the "healthiest" default was itself failing with a transient upstream 502 at one probe. No snapshot, listing, or pre-probe can encode this — pre-probing free models even burns the very quota it tries to measure.
• Today a quota-exhausted model fails the turn hard (Recoverable: false) and the user must switch models by hand (see the diagnostic in fix(core): derive the OpenCode Free model set from the models.dev snapshot #3429's discussion).

Proposed direction (matching the reviewer's "Runtime Host owns connection-local health and reversible fallback"):

1. On a rate-limit/availability failure from a connection with other enabled models, fall back to the next enabled model within the turn, with a visible notice and without persisting a silent default change (reversible once the original recovers).
2. Treat an empty-content 200 completion as a model failure too — the muse-spark case shows status codes alone cannot gate health.
3. Optionally: a scheduled CI probe of the derived candidates to keep the evidence-dated deny-list in fix(core): derive the OpenCode Free model set from the models.dev snapshot #3429 honest (flag recoveries and new persistent breakage), and the versioned built-in seed policy from Persisted connection catalogs keep model ids that the snapshot has retired #3354 to replace the deliberately lossy exact-match seed migration.

Per CONTRIBUTING, (1) changes user-visible execution behavior and should go through maintainer decision before implementation — this issue is that request.

_{Analysis and drafting AI-assisted (Claude Code); probes and diagnostics are from the linked PR discussion.}

[Astro-Han]

Thanks for the write-up. The same id probing 429 and finishing fine hours later makes the case against static lists better than anything I could write, and the "healthiest" default failing with a transient 502 is a nice cherry on top.

My lean is to skip the automatic in-turn fallback. Free models are a best-effort third-party service, availability is per-IP and point-in-time, and a hard failure there is expected behavior, not a bug in Maka. Failing with a clear error and letting people switch models by hand is honest, and the switch is quick.

Provenance matters here too. The execution log is append-only and attributes tool results to the model that ran. An automatic mid-turn switch would record results against a model nobody picked; a manual switch doesn't have that problem.

The bigger cost is the machinery itself: fallback chains, notices, reversibility semantics, health signals. That's a lot of surface for a failure that's expected and easy to recover from by hand.

The part I'd keep from this thread is #3429's derivation from the models.dev snapshot. Fresh candidate lists are cheap data hygiene worth doing. #3354 stands on its own.

If hard 429s turn out to hurt in practice, the smallest thing I'd consider is reclassifying FreeUsageLimitError as recoverable so the turn doesn't die. Not the same as automatic fallback, and I don't want to do it preemptively.

If you think manual switching is worse in practice than it looks on paper, I'd like to hear it.

中文对照

感谢这份分析。同一个模型 id 探测时是 429，几小时后却正常完成，这一条比任何论述都更能说明静态列表解决不了这个问题；"最健康"的默认模型在一次探测里被上游 502 击穿，也是很好的佐证。

我的倾向是不做 turn 内的自动回退。免费模型是第三方提供的尽力而为服务，可用性按 IP、按时间点变化，硬失败本来就是这种服务的常态，不是 Maka 的 bug。给出清晰的报错、让用户手动换模型，是诚实的行为，切换也很快。

溯源这一点也很重要。执行日志是 append-only 的，工具结果归因到实际运行的模型。自动在 turn 中途换模型，会把结果记到用户没选过的模型头上；手动切换没有这个问题。

更大的代价在机制本身：回退链、提示、可逆语义、健康信号。为了一个本来就会失败、而且手动就能恢复的场景，铺这么大一套东西，不值得。

这条线里我想保留的是 #3429：从 models.dev 快照推导候选集。让候选列表保持新鲜是廉价的、值得做的数据卫生。#3354 独立成立。

如果将来硬 429 在实践中真的造成明显困扰，我考虑的最小改动是把 FreeUsageLimitError 重新分类为可恢复（recoverable），让 turn 不至于直接死掉。这跟自动回退不是一回事，我也不想现在就做。

如果你认为手动切换在实践中的体验比纸面上更差，欢迎告诉我。

_{Drafted with AI assistance, reviewed by maintainer.}

[cunninghamcard-bit]

Adding a P3 from the #3429 review to this follow-up's scope (reported by @Astro-Han, non-blocking there): a previously saved quarantined default can still be reconstructed as a missing-default catalog entry, and the OpenCode Free connection-test candidate loop does not filter brokenModelIds. Execution is already vetoed by authorizeConnectionModel, so both are display/probe-path cleanups that belong with the health-seam work here.