fix(server): recover from stale Homebrew provider metadata

[EMOEMOJAI]

A Homebrew-managed Codex installation can be unsupported while stale local metadata reports the same incompatible version as latest. T3 then hides the update action without explaining how to recover.

Add a targeted compatibility hint to run brew update on the environment host. Explicit provider refreshes now reread installer metadata, so the next refresh can offer the compatible release immediately; background checks keep their existing cache. The hint clears once Homebrew reports a compatible version. The existing server message reaches web/desktop and mobile without a contract change.

Fixes #13751.

Validation:

• 111 focused tests pass across provider compatibility, maintenance, managed snapshots, and the registry (Node 24, isolated PATH, canonical TMPDIR).
• Server typecheck, targeted lint, formatting, and diff checks pass.
• Verified in the actual web client using isolated Codex/Homebrew fixtures: 0.155.1 produces the hint; changing metadata to 0.157.1 and clicking Refresh exposes Update now without restarting. No real provider credentials or installations were changed. Mobile was checked through its existing message consumer, not run on a device.

Before	After

After metadata refresh:

Implemented with GPT-6-Astra through the Codex harness in T3 Code.

Summary by CodeRabbit

• Bug Fixes
  • Explicitly refreshing provider status now checks the latest installer metadata, so newly available versions and updated compatibility status appear without waiting for a periodic check.
  • When Homebrew metadata may be out of date and a provider version is incompatible, status guidance now recommends running brew update on the host before refreshing.

[macroscopeapp]

Approvability

Verdict: Approved at 471bbc1

Macroscope's review found this PR approvable — This is a localized fix that refreshes cached Homebrew metadata only when the user explicitly refreshes provider status and adds guidance to an existing compatibility message. It preserves background caching, changes no contracts or defaults, and includes focused coverage for the stale and recovered states.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 0fedc46f-606c-4c76-aaf9-ea27de41221d

📥 Commits

Reviewing files that changed from the base of the PR and between a21b42c and 471bbc1.

📒 Files selected for processing (4)

• apps/server/src/provider/makeManagedServerProvider.test.ts
• apps/server/src/provider/makeManagedServerProvider.ts
• apps/server/src/provider/providerCompatibility.test.ts
• apps/server/src/provider/providerCompatibility.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Explicit provider refreshes now reread maintenance metadata before refreshing the provider snapshot. Compatibility messages now include Homebrew metadata-refresh guidance for specified unsupported or broken version states.

Changes

Provider maintenance

Layer / File(s)	Summary
Fresh metadata on explicit refresh apps/server/src/provider/makeManagedServerProvider.ts, apps/server/src/provider/makeManagedServerProvider.test.ts	Explicit refresh resolves maintenance metadata with fresh: true before refreshing the snapshot. Periodic checks continue to use the existing snapshot path. The test checks cached metadata during periodic checks and fresh metadata after explicit refresh.
Homebrew compatibility guidance apps/server/src/provider/providerCompatibility.ts, apps/server/src/provider/providerCompatibility.test.ts	Compatibility processing adds brew update guidance when the update command starts with brew upgrade and both installed and latest version statuses are unsupported or broken. Tests cover these states and cases where the guidance is absent.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 471bb

Provider refresh remains available when Homebrew metadata lookup fails, and no issue requiring a pre-merge fix is established.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 471bb

Refresh remains restricted to authorized operators and does not run a software update. The main remaining uncertainty is how overlapping or failed metadata refreshes affect the status shown to users.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — An authorized operator's refresh can now trigger a fresh host-side maintenance probe for configured provider instances; the changed path does not grant a new update authority.

Trust Boundaries and Controls

• observed — The websocket authorization check precedes provider refresh dispatch. Homebrew upgrade advice depends on a capability produced after executable-path and Homebrew-prefix checks, rather than on a client-supplied command in the changed path.

Resilience and Maintainability Implications

• inferred — A failure in the newly required fresh-resolution step would prevent that explicit refresh's probe and leave the registry serving cached provider status. Homebrew probe failures are caught by the resolver, but concurrent fresh-cache ordering and failed-cache-read behavior remain unestablished.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: recovering from stale Homebrew provider metadata.
Description check	✅ Passed	The description explains what changed, why it changed, validation results, and UI impact with before-and-after screenshots. The checklist section is not included, but the required information is other…
Linked Issues check	✅ Passed	The changes satisfy #13751. applyProviderCompatibility adds targeted Homebrew recovery guidance when the installed and reported latest versions are both incompatible and the update command is Homebr…
Out of Scope Changes check	✅ Passed	All changed files support #13751. The production changes implement stale Homebrew metadata guidance and explicit refresh behavior. The added tests verify those behaviors and their boundaries. No unrel…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}