Add Neuralwatt provider

[jrimmer]

Summary

CodexBar can now query Neuralwatt's official GET /v1/quota endpoint with API-key authentication and render prepaid USD credit balance. The provider is wired through settings, config/environment resolution, managed token accounts, CLI, widgets, and provider documentation.

Maintainer audit

Exact head: b00c39edf

Rebased onto current main at 129f6962e; contributor authorship remains preserved in 1e0e869fc.

Maintainer hardening on top of the contributor branch:

• preserves transport cancellation instead of converting it to a provider error;
• injects transport in tests and verifies endpoint overrides are rejected before secret lookup;
• rejects malformed successful quota responses and treats known zero-credit balances as exhausted;
• removes unrelated generated documentation churn and broken dashboard/status links;
• refreshes the generated parser hash;
• avoids a duplicate static credits section while keeping the prepaid balance in the primary metric;
• serializes app and CLI multi-account quota refreshes at Neuralwatt's documented one-request-per-second rate, preserving prior snapshots on cancellation;
• recognizes NEURALWATT_API_KEY in diagnostics and hides the unsupported generic Spend lane;
• documents that subscription kWh quota is separate from prepaid credit balance and is not currently shown.

Provider isolation audit: Neuralwatt identity, plan, and usage fields come only from the Neuralwatt response. API-key resolution is provider-scoped. No browser-cookie or keychain path is added.

Official contract and product decision

Neuralwatt's quota API documentation confirms that prepaid credit balance and an active subscription's kWh allowance are separate quota pools. It also notes that lifetime USD cost can exceed prepaid credits because subscription usage is billed separately.

This branch deliberately keeps the contributor's balance-only product semantics. That is the smallest UI change, but it can show $0 / exhausted while an active subscription still has usable kWh. Surfacing both pools is more accurate for subscription users, at the cost of adding a second unit and quota window to the menu model. Recommendation: do not merge until we surface active subscription allowance alongside prepaid credits, or explicitly accept balance-only semantics as the product contract.

Runtime proof

The contributor supplied redacted live CLI output from the original branch, confirming the endpoint/auth path. No authorized Neuralwatt credential is available in the maintainer environment, so the rebased exact head could not be independently exercised live. The original proof therefore remains useful but is not exact-head proof.

Validation

• exact-head focused Neuralwatt, multi-account rate-limit/cancellation, diagnostics, and provider-picker suites: passed;
• exact-head make check: passed;
• exact-head full make test: 44/44 shards passed;
• exact-head structured autoreview: no accepted/actionable findings;
• exact-head ./Scripts/package_app.sh: passed and produced CodexBar.app;
• git diff --check origin/main...HEAD: passed;
• exact-head GitHub CI run 28517756757: Linux builds and lint passed; the four macOS shards and aggregate job were canceled by maintainer coordination to free runner capacity. No exact-head CI failure was observed, but this is not a terminal-green rollup.

Integration state

The branch is mergeable against current main, including the landed cost-scanner changes from #1797 and the subsequent widget fix. Unrelated behind drift is intentionally preserved; rebase only if a real conflict or semantic overlap appears. Exact local proof is complete, while CI remains intentionally canceled pending the product/live-proof decision. No changelog entry is included on the contributor branch; the maintainer should add one with contributor thanks if the product decision is resolved and the PR is landed.

---

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 1, 2026, 12:41 PM ET / 16:41 UTC.

Summary
The PR adds a built-in Neuralwatt API-key provider for GET /v1/quota, wiring provider registration, settings/config/env/token accounts, CLI/widgets/docs, menu rendering, and focused tests.

Reproducibility: not applicable. this is a new provider feature rather than a bug report. Source inspection and mock tests cover the intended paths, but exact-head live Neuralwatt behavior is not proven.

Review metrics: 2 noteworthy metrics.

• Changed surface: 36 files, +1450/-12. The branch spans provider parsing, app settings, menu rendering, widgets, CLI, tests, and docs, so cross-surface provider fit matters before merge.
• Credential surface: 1 provider ID, 2 env vars, 1 token-account entry. The new API-key and endpoint override path affects provider routing and secret resolution, not only UI copy.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted exact-head live CLI output, logs, or a recording for b00c39edf, with API keys and private account/network details removed.
• [P1] Get maintainer acceptance of balance-only semantics or add subscription kWh display before merge.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: The PR describes original-branch redacted CLI proof, but it does not include inspectable exact-head live output, logs, or recording for b00c39edf; add redacted proof and remove API keys/private account or network details. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] The external-contributor real behavior proof gate remains open because no inspectable exact-head Neuralwatt CLI output, logs, or recording for b00c39edf is present.
• [P1] Balance-only rendering can show exhausted prepaid credits while an active subscription still has usable kWh unless maintainers explicitly accept that product contract.
• [P1] The new provider ID, API key setting, endpoint override, and token-account injection path affect credential and provider routing behavior, so maintainer auth/provider review is still needed.
• [P1] Exact-head macOS CI was intentionally canceled, leaving no terminal-green macOS rollup for the current head.

Maintainer options:

1. Accept Balance-Only Provider Contract
   Maintainers can explicitly accept prepaid-credit-only UI semantics, then require redacted exact-head live Neuralwatt output before landing.
2. Surface Subscription Allowance
   If balance-only output would mislead subscription users, add an active kWh allowance window and focused menu/parser tests before merge.
3. Pause Provider Intake
   If the quota contract or live proof cannot be confirmed, keep this provider paused rather than landing ambiguous usage display behavior.

Next step before merge

• [P1] Human review is needed for the quota product contract and exact-head live proof; automation cannot provide Neuralwatt credentials or choose the provider semantics.

Security
Cleared: The diff adds an HTTPS API-key provider using existing config and token-account patterns, with no dependency, workflow, release-script, or permission changes.

Review details

Best possible solution:

Land only after redacted exact-head live proof and maintainer acceptance of balance-only semantics, or update the provider to show active subscription kWh alongside prepaid balance.

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

Not applicable: this is a new provider feature rather than a bug report. Source inspection and mock tests cover the intended paths, but exact-head live Neuralwatt behavior is not proven.

Is this the best way to solve the issue?

Unclear until maintainer product acceptance. The implementation follows existing provider patterns, but balance-only display versus subscription-kWh display remains a product contract choice.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 101c17801949.

Label changes

Label justifications:

• P3: This is an optional new provider integration with limited blast radius for existing users unless they opt in.
• merge-risk: 🚨 auth-provider: The diff adds a new API-key provider, endpoint override handling, and token-account injection path that affects credential and provider routing behavior.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR describes original-branch redacted CLI proof, but it does not include inspectable exact-head live output, logs, or recording for b00c39edf; add redacted proof and remove API keys/private account or network details. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; provider isolation, focused CLI/parser tests, no unrequested live credential probes, and release-owned changelog guidance are relevant to this PR review. (AGENTS.md:1, 101c17801949)
• Not implemented on current main: Current main has no neuralwatt, NeuralWatt, or Neuralwatt matches in Sources, Tests, docs, or README, so this PR is not obsolete or already implemented. (101c17801949)
• Provider registration and fetch path: Exact head registers .neuralwatt as an API-token provider and routes usage loading through NeuralWattUsageFetcher.fetchUsage(...).toUsageSnapshot(). (Sources/CodexBarCore/Providers/NeuralWatt/NeuralWattProviderDescriptor.swift:36, b00c39edf95b)
• Credential routing: The branch adds provider-scoped token resolution for NEURALWATT_API_KEY, which is the main auth/provider-routing surface touched by the PR. (Sources/CodexBarCore/Providers/ProviderTokenResolver.swift:108, b00c39edf95b)
• Endpoint override validation: Endpoint overrides are validated as HTTPS or bare host before the request is built, reducing credential-leak risk from malformed override values. (Sources/CodexBarCore/Providers/NeuralWatt/NeuralWattSettingsReader.swift:25, b00c39edf95b)
• Balance-only implementation: toUsageSnapshot() renders prepaid credits as the primary window and leaves subscription renewal/secondary windows unset, while preserving per-key allowance as an extra window. (Sources/CodexBarCore/Providers/NeuralWatt/NeuralWattUsageFetcher.swift:230, b00c39edf95b)

Likely related people:

• steipete: Recent current-main provider work added Sakana through the same registry/config/widget surfaces, and this PR branch includes steipete-authored Neuralwatt hardening for parser behavior, duplicate credits, and rate limiting. (role: recent provider framework contributor and branch hardening author; confidence: high; commits: 87635bcc755b, f992734e69e2, a2e33776fd4c; files: Sources/CodexBarCore/Providers/ProviderDescriptor.swift, Sources/CodexBar/UsageStore+TokenAccounts.swift, Sources/CodexBarCore/TokenAccountSupportCatalog+Data.swift)
• Zihao-Qi: Blame for the provider registry, menu card rendering, menu preferences, and token-account catalog scaffolding points to the current-main shared implementation history. (role: current-main shared provider/menu scaffolding contributor; confidence: medium; commits: 3091ff966fff, 8eb852493103, 9a65637e53a7; files: Sources/CodexBarCore/Providers/ProviderDescriptor.swift, Sources/CodexBar/MenuCardView.swift, Sources/CodexBar/MenuDescriptor.swift)
• mvanhorn: The closest recent built-in API quota provider pattern is the merged Chutes provider, authored by mvanhorn and hardened in follow-up commits. (role: adjacent API quota provider contributor; confidence: medium; commits: de6cd3aff9f8, 02c4c2daa710; files: Sources/CodexBarCore/Providers/Chutes/ChutesProviderDescriptor.swift, Sources/CodexBarCore/Providers/Chutes/ChutesUsageStats.swift, Tests/CodexBarTests/ChutesProviderTests.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dbab6f7a73

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jrimmer]

@clawsweeper re-review

Added redacted runtime proof from a live Neuralwatt CLI fetch to the PR body, and addressed the inline review feedback. Current head: 31ebe87.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fb5e47fb3b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 38b564c39c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".