fix(server): keep a ready OpenCode provider through a slow version probe

[macodev00]

Fixes pingdotgg#11080.

This supersedes pingdotgg#12701. Macroscope was Not approved for raising the hardcoded OpenCode --version timeout.

What Changed

A slow opencode --version keeps the last ready, versioned snapshot: status, version, auth, and catalog. The 4 second default stays 4 seconds. T3CODE_OPENCODE_VERSION_PROBE_TIMEOUT can raise the wait. Accepted values are clamped to 1–60 seconds, and invalid values are ignored. A first probe with no prior version still errors. A missing opencode binary still errors.

The timeout is read from that environment variable on the machine running T3 Code. The OpenCode user guide mentions the variable. There is no settings-schema field and no settings form control.

Why

OpenCode health checks run opencode --version and fail the provider when it does not return within 4 seconds. That budget was added in pingdotgg#8750 to kill hung probes (pingdotgg#8681). A cold start on a loaded or ARM host can land just past it, and the provider then shows Unavailable even though it had already reported a version. pingdotgg#12701 raised the hardcoded timeout to 10 seconds. This leaves the production default at 4 seconds, makes a longer wait opt-in, and keeps an already ready provider through a timeout.

Verification

Node 24.13.1. vp was /workspace/node_modules/.bin/vp (vite-plus 1.0.0).

Server typecheck, from apps/server:

vp run typecheck

Exit 0. tsc --noEmit printed existing suggestions in unrelated files (CodexInstallation.ts, CodexAdapter.test.ts, CodexProvider.ts, ws.ts). No errors in this change.

Format, from the repo root:

vp fmt apps/server/src/provider/Layers/OpenCodeProvider.ts apps/server/src/provider/Layers/OpenCodeProvider.test.ts apps/server/src/provider/Layers/ProviderRegistry.ts apps/server/src/provider/Layers/ProviderRegistry.test.ts docs/user/providers-opencode.md

Exit 0. Finished on 5 files. The working tree stayed clean.

Lint, from the repo root:

vp lint --report-unused-disable-directives apps/server/src/provider/Layers/OpenCodeProvider.ts apps/server/src/provider/Layers/OpenCodeProvider.test.ts apps/server/src/provider/Layers/ProviderRegistry.ts apps/server/src/provider/Layers/ProviderRegistry.test.ts docs/user/providers-opencode.md

Exit 0. No findings.

From apps/server:

vp test run src/provider/Layers/OpenCodeProvider.test.ts

1 file passed, 22 tests passed.

From apps/server:

vp test run src/provider/Layers/ProviderRegistry.test.ts

1 file passed, 56 tests passed.

Limitations: these checks did not launch a slow OpenCode binary on a loaded host; the timeout and last-known-good behavior are covered by the server tests above.

Docs note (c9ac543fd, Linux, Node v24.13.1): JSDoc only, on normalizeProbeMessage and normalizedErrorMessage. CodeRabbit's 50% pair is those function declarations next to formatOpenCodeProbeError. Comments on checkOpenCodeProviderStatus are not in that pair. Re-ran from the repo root:

./node_modules/.bin/vp test run apps/server/src/provider/Layers/ProviderRegistry.test.ts apps/server/src/provider/Layers/OpenCodeProvider.test.ts

Test Files 2 passed (2), Tests 79 passed (79), 3.66s.

./node_modules/.bin/vp lint --report-unused-disable-directives apps/server/src/provider/Layers/OpenCodeProvider.ts apps/server/src/provider/Layers/ProviderRegistry.ts

Exit 0.

./node_modules/.bin/vp fmt --check apps/server/src/provider/Layers/OpenCodeProvider.ts

Exit 0. All matched files use the correct format.

./node_modules/.bin/vp run --filter t3 typecheck

Exit 0. Same pre-existing suggestions in CodexInstallation.ts, CodexAdapter.test.ts, CodexProvider.ts, and ws.ts. None in this change.

UI Changes

None. Provider health behavior only. There is no settings form change, so there are no before/after screenshots.

Checklist

• Fixes [Bug]: OpenCode provider flagged Unavailable when CLI version probe exceeds hardcoded 4s pingdotgg/t3code#11080
• Supersedes fix(server): tolerate slow OpenCode version probes pingdotgg/t3code#12701 (Macroscope Not approved for raising the hardcoded timeout)
• 4 second default unchanged
• T3CODE_OPENCODE_VERSION_PROBE_TIMEOUT clamped to 1–60 seconds
• Timeout keeps the last ready, versioned status, version, auth, and catalog
• First probe with no prior version still errors
• Missing binary still errors
• No settings schema or UI change
• Server typecheck, fmt, lint, and the two server test files recorded above

Grok 4.7, Cursor cloud agent.

  

[macodev00]

Opened upstream as pingdotgg#14575.