fix(resilience): tolerate transient network failures in model-list fetch (#78)

[ltmoerdani]

What

Fixes #78. Reporter @leiyu1980 (Windows 11 + VPN + corporate firewall, VS Code 1.129.0, extension 0.4.1) saw the Zen model list "flash briefly before disappearing" at startup, with both Go and Zen logging TypeError: fetch failed.

Why

Initial triage looked like a regression of the closed #51 picker crash (TypeScript schema change on VS Code 1.126, fixed by PR #53). Wrong instinct. Web research confirmed the real root cause:

• Node's built-in fetch (undici) defaults to headersTimeout=300s with no connect timeout. A single hung TCP connect could stall the picker for up to 5 minutes.
• nodejs/undici#5450 documents that under concurrent load, undici's socket-reuse + keep-alive race produces TypeError: fetch failed. Maintainer response: "expected behavior, use retries."
• VS Code 1.129 introduced the agent host, which dramatically increases concurrent provideLanguageModelChatInformation calls into BYOK providers — multiplying the chance of hitting that race per unit time.
• fetchModels() was written for the happy path only: no timeout, no retry, no User-Agent, no graceful cache fallback. One transient failure → bundled list or empty picker ("flash then disappear").

After the reporter replied, a second signature surfaced: their VPN/firewall was passing POST /chat/completions (with Content-Type: application/json) while dropping the bare GET /models (no headers). That points at SSL-inspecting proxies (Zscaler / Netskope / Fortinet) which treat anonymous GETs as scanner traffic.

How

Six coordinated changes in src/extension.ts:

1. Per-attempt timeout — AbortSignal.timeout(15_000) so a hung connect can't hold the picker hostage for undici's 5-minute default.
2. Exponential retry — up to 3 attempts with backoff (500ms / 1s / 2s), gated by isTransientFetchError(). Retries only on ECONNRESET, EAI_AGAIN, UND_ERR_CONNECT_TIMEOUT, HTTP 408/429/5xx, and the generic TypeError: fetch failed wrapper. Never on AbortError from the caller's CancellationToken or on HTTP 4xx.
3. User-Agent at runtime — getUserAgent() reads context.extension.packageJSON.version once, caches it, falls back to FALLBACK_USER_AGENT in test harnesses. Kills the recurring drift (header said 0.3.6 while package.json said 0.4.1).
4. CancellationToken threading — fetchModels(apiKey, token?) composes the caller's token with the timeout signal via AbortSignal.any([...]). Cancellation short-circuits to a fallback and never retries.
5. 1-hour cached snapshot — every successful fetch persists { ids, fetchedAt } to globalState under opencode.modelListCache.v1::<vendor>. On final failure, prefers the cached snapshot over the bundled fallbackModels. This is what kills the "flash then disappear" UX.
6. Accept: application/json header — makes the GET look like a legitimate API call instead of an anonymous scanner, matching what testConnection() and the chat transports already send. Specifically targeted at the reporter's VPN + corporate firewall signature.

Drive-by UX fix

While replying to the reporter, I told them to "run OpenCode Go: Refresh Models from the Command Palette". That command didn't exist. Refresh Models was only reachable as a sub-item inside the OpenCode Go: Manage Provider QuickPick, and Zen had no Manage Provider command at all — a Zen user (which is the reporter's case) had zero manual refresh path via the palette.

Three new top-level commands are now registered:

• OpenCode Go: Refresh Models — skips the Manage menu, fetches straight away
• OpenCode Zen: Manage Provider — parity with Go
• OpenCode Zen: Refresh Models — same as Go refresh, scoped to Zen

Implementation: new public refreshModels() method on OpenCodeProvider wraps the existing private refreshMetadataAndModels() + changeEmitter.fire() + toast. The "Refresh Models" action inside manage() now delegates to this method (single source of truth). No behavior change to existing opencodego.manage.

What this does NOT fix (honest caveats)

• VPN/firewall hard block to opencode.ai → user must set VS Code http.proxy. Documented in README and in the issue reply.
• Gateway outage longer than the retry budget (~3.5s) → degrades to cache (1h) then bundled.
• undici socket-reuse race itself → upstream behavior, we tolerate it via retry. Did not install a global custom dispatcher (interceptors.retry + interceptors.dns) because that affects every fetch in the extension and was deemed overkill for this MVP fix.

Verification

• npm run compile clean (after every change)
• get_errors clean on all modified files
• vsce package builds opencode-copilot-chat-0.4.2.vsix (1.06 MB, 115 files)
• Manual test A (command visibility): PASS — all 3 new commands appear in the palette
• Manual tests B–F (refresh toast, cache fallback, retry log, paritas Zen Manage): pending user / reporter

Docs

• docs/issues/35-20260720-issue78-model-list-fetch-resilience.md — root-cause investigation, 10 authoritative references, behavior matrix, what this does NOT fix
• CHANGELOG.md — new [0.4.2] — 2026-07-23 section (released), with [Resilience] entry listing all 6 changes and [Commands] entry for the parity fix
• README.md — commands table updated (Go/Zen Refresh + Zen Manage)
• docs/devlog.md — session handoff + new section for issue [BUG] Could not fetch OpenCode Zen (Agents) model list. Using bundled model list. fetch failed #78

Commits (3 — please merge with --merge, never --squash)

1. 8fcde64 — fix(resilience): make model-list fetch tolerant of transient network failures (contains Fixes #78 → auto-closes on merge)
2. a04939c — feat(commands): add top-level Refresh Models commands + Zen Manage Provider
3. 2ab0c31 — fix(resilience): send Accept header for corporate firewall compatibility (#78) + version bump 0.4.1 → 0.4.2

Notes for review

• The isTransientFetchError() classifier parses HTTP status from both an explicit .status field and the "Model list request failed (NNN): ..." message string, because fetchModels() throws a plain Error (not a typed error) on non-2xx responses.
• AbortSignal.any() and AbortSignal.timeout() require Node 20.3+, which VS Code's ^1.125.0 engine floor guarantees.
• Draft PR so the reporter's verification (Refresh Models command + cache behavior) can land before merge.

Fixes #78