fix(providers): honor resolved terminal fetch errors

[steipete]

An unavailable final Antigravity source could replace a useful earlier API, transport, or sign-in error when it stopped fallback. The pipeline had already selected the right error through its provider resolver, but its terminal return discarded that result.

Use the resolved error for terminal failures, matching exhausted fallback chains. Cancellation remains authoritative; routing and per-attempt diagnostics still receive each original error, and later substantive failures retain their existing precedence. This extracts the bounded repair from #3683; that broader proposal remains open.

Validation: reproduced 13 failing assertions before the fix; 110 tests in ProviderFetchErrorTests, AntigravityCLIHTTPSFetchStrategyTests, and supporting provider coverage now pass. make check reports zero violations. Independent P2 review is clean. Tests use synthetic strategies and injected transports; no live accounts, cookie imports, or Keychain reads were used.

Thanks @hhh2210 for the original proposal.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 16, 2026, 10:15 PM ET / September 17, 2026, 02:15 UTC.

ClawSweeper review

What this changes

The PR makes terminal provider failures use the existing error-selection policy, with regression tests and Antigravity documentation.

Merge readiness

✅ Ready for maintainer review

This is a useful, bounded repair that remains absent from current main and v0.60.4. No actionable correctness or security defects were found; the broader related proposal does not supersede it.

Priority: P2
Reviewed head: 83f5fb0494863854b49170a8c70289e05de164c1

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused repair with relevant regression coverage and no identified blocking defect.
Proof confidence	🌊 off-meta tidepool	Not applicable: The OWNER-authored PR is exempt from the ordinary contributor proof gate. Its reported synthetic tests exercise terminal error selection and cancellation in the production pipeline; no live-provider run is claimed, and no authority boundary changes.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The OWNER-authored PR is exempt from the ordinary contributor proof gate. Its reported synthetic tests exercise terminal error selection and cancellation in the production pipeline; no live-provider run is claimed, and no authority boundary changes.
Evidence reviewed	8 items	Repository policy: Read the complete root AGENTS.md; no nested AGENTS.md or maintainer-notes directory was found. Applied the focused-test, existing-helper, and prompt-free validation guidance. Tests and builds were not executed under the read-only review contract. Introduced repair and preserved invariants: The pinned introduced diff changes only the terminal failure return in production. Cancellation returns first, shouldFallback still receives the original error, and attempt diagnostics retain the original localized description. Existing policy and reachable terminal failure: Antigravity is the only production caller supplying a custom fallback-error resolver. It preserves earlier substantive failures against discovery markers, while later substantive failures remain authoritative. Offline fetch can throw notRunning after availability succeeds and always stops fallback.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar tries provider usage sources in sequence and sends the resulting usage or error to its menu-bar app and CLI. The shared fetch pipeline selects the surfaced error while retaining each source’s original diagnostic.

flowchart TD
 A[Usage refresh] --> B[Ordered provider sources]
 B --> C[Fetch pipeline]
 C --> D{Fetch result}
 D -->|Success| E[Usage display]
 D -->|Failure| F[Provider error policy]
 F --> G[App and CLI error]
 C --> H[Per-source diagnostics]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production +1/-1; tests +134/-24; documentation +2/-0	The repair reuses existing production policy and concentrates growth in regression coverage.

Technical review

Best possible solution:

Use one consistent provider error-selection policy for exhausted and terminal failures while preserving cancellation, successful fallbacks, and original diagnostics.

Do we have a high-confidence way to reproduce the issue?

Yes, source establishes the defect: an earlier substantive failure followed by terminal offline notRunning loses the resolved error on current main. No runtime reproduction was executed during this read-only review.

Is this the best way to solve the issue?

Yes, returning the already-resolved error is the narrowest repair; it preserves the existing precedence contract without adding another policy or changing routing.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 094b18a2c5d7.

Labels

Label changes:

• add P2: This repairs misleading provider failure reporting with a narrow change and limited blast radius.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The OWNER-authored PR is exempt from the ordinary contributor proof gate. Its reported synthetic tests exercise terminal error selection and cancellation in the production pipeline; no live-provider run is claimed, and no authority boundary changes.

Label justifications:

• P2: This repairs misleading provider failure reporting with a narrow change and limited blast radius.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The OWNER-authored PR is exempt from the ordinary contributor proof gate. Its reported synthetic tests exercise terminal error selection and cancellation in the production pipeline; no live-provider run is claimed, and no authority boundary changes.

Evidence

What I checked:

• Repository policy: Read the complete root AGENTS.md; no nested AGENTS.md or maintainer-notes directory was found. Applied the focused-test, existing-helper, and prompt-free validation guidance. Tests and builds were not executed under the read-only review contract. (AGENTS.md:1, 83f5fb049486)
• Introduced repair and preserved invariants: The pinned introduced diff changes only the terminal failure return in production. Cancellation returns first, shouldFallback still receives the original error, and attempt diagnostics retain the original localized description. (Sources/CodexBarCore/Providers/ProviderFetchPlan.swift:380, 83f5fb049486)
• Existing policy and reachable terminal failure: Antigravity is the only production caller supplying a custom fallback-error resolver. It preserves earlier substantive failures against discovery markers, while later substantive failures remain authoritative. Offline fetch can throw notRunning after availability succeeds and always stops fallback. (Sources/CodexBarCore/Providers/Antigravity/AntigravityProviderDescriptor.swift:225, 83f5fb049486)
• Still necessary on current main: Fetched main still folds the provider error and then discards that selection when a source stops fallback. (Sources/CodexBarCore/Providers/ProviderFetchPlan.swift:380, 094b18a2c5d7)
• Latest release comparison: The v0.60.4 source also returns the original terminal error, so the inspected latest release does not contain this repair. (Sources/CodexBarCore/Providers/ProviderFetchPlan.swift:380, 937b20813cf4)
• Regression coverage and reported validation: Inspected tests cover resolved terminal errors, original routing and diagnostics, default-resolver compatibility, explicit cancellation, task cancellation, and both terminal and continuing Antigravity failures. The captured PR body reports 13 failing assertions before the repair, 110 passing tests afterward, and clean make check; these results were not independently rerun. (Tests/CodexBarTests/ProviderFetchErrorTests.swift:32, 83f5fb049486)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

The terminal-error repair is now on main through #3701, merged as e56bb5b. An unavailable final source now preserves the error selected by the existing provider policy, while cancellation and later substantive failures keep their existing precedence. Each source still records its original diagnostic.

Validation: make test-fast FILTER='ProviderFetchErrorTests|AntigravityCLIHTTPSFetchStrategyTests|ProviderArchitectureGatekeeperTests' passed 110 tests after reproducing 13 failing assertions on the prior implementation. make check, independent P2 review, and every macOS/Linux CI check passed: https://github.com/steipete/CodexBar/actions/runs/35173592826. All provider inputs were synthetic.

Thanks @hhh2210. This extracts only the terminal resolver repair; the broader first-error/per-source diagnostic proposal in #3683 remains open.