fix(billing): hide budget-complete prompt for free zero-budget plans

[sjh9714]

Summary

• Hide the completed-budget prompt for FREE users who have no recurring budget.
• Keep the warning for users who have an actual recurring budget and exhaust it.
• Update the useUsageState regression test for the FREE zero-budget case reported in Always asking for payment (FREE PLAN) #2129.

Problem

FREE plan users with cycleBudgetUsd=0 and remainingUsd=0 were treated as if they should see the completed-budget/payment prompt. That made a zero-recurring-budget FREE state look like an exhausted paid or included budget cycle, which matches the user-visible complaint in #2129.

Solution

useUsageState() now derives shouldShowBudgetCompletedMessage from the existing recurring-budget exhaustion check only. This keeps paid/included-budget exhaustion behavior unchanged while preventing FREE zero-budget users from seeing the budget-complete prompt.

Submission Checklist

If a section does not apply to this change, mark the item as N/A with a one-line reason. Do not delete items.

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy
• Diff coverage >= 80% — changed lines (Vitest + cargo-llvm-cov merged via diff-cover) meet the gate enforced by .github/workflows/coverage.yml. Run pnpm test:coverage and pnpm test:rust locally; PRs below 80% on changed lines will not merge.
• N/A: Coverage matrix updated — behaviour-only hook change, no feature row added/removed/renamed in docs/TEST-COVERAGE-MATRIX.md
• N/A: All affected feature IDs from the matrix are listed in the PR description under ## Related — no matrix feature row applies
• No new external network dependencies introduced (mock backend used per Testing Strategy)
• N/A: Manual smoke checklist updated if this touches release-cut surfaces (docs/RELEASE-MANUAL-SMOKE.md) — hook-only billing banner state change
• Linked issue closed via Closes #NNN in the ## Related section

Impact

Runtime impact is limited to frontend billing/banner state. FREE users with no recurring budget no longer see the budget-complete prompt solely because both budget fields are zero. Users with a positive recurring budget still see the existing completed-budget warning after exhaustion.

Related

• Closes: Fixes Always asking for payment (FREE PLAN) #2129
• Follow-up PR(s)/TODOs: N/A

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Keep this section for AI-authored PRs. For human-only PRs, mark each field N/A.

Linear Issue

• Key: N/A
• URL: N/A

Commit & Branch

• Branch: codex/GH-2129-free-plan-budget-banner
• Commit SHA: 178f217d7461838b284a44f089694c9033b0ba20

Validation Run

• pnpm --filter openhuman-app format:check — attempted; Prettier passed, Rust fmt blocked by missing cargo (see Validation Blocked)
• pnpm typecheck
• Focused tests:
  • pnpm --dir app exec vitest run src/hooks/useUsageState.test.ts --config test/vitest.config.ts
  • pnpm --dir app exec vitest run src/hooks/useUsageState.test.ts src/pages/__tests__/Conversations.render.test.tsx --config test/vitest.config.ts
• Rust fmt/check (if changed): N/A, no Rust files changed
• Tauri fmt/check (if changed): N/A, no Tauri files changed

Additional validation:

• Red check: pnpm --dir app exec vitest run src/hooks/useUsageState.test.ts --config test/vitest.config.ts failed before the production change with expected true to be false for shouldShowBudgetCompletedMessage.
• pnpm --dir app exec prettier --check src/hooks/useUsageState.ts src/hooks/useUsageState.test.ts
• pnpm lint (passed with existing repo-wide warnings)
• pnpm test:coverage (297 test files passed, 2873 tests passed)
• node scripts/codex-pr-preflight.mjs --strict-path --lightweight (blocked on expected Codex path; see Validation Blocked)

Validation Blocked

• command: node scripts/codex-pr-preflight.mjs --strict-path --lightweight

• error: [FAIL] expected repo path :: expected /workspace/openhuman, got /Users/sungjh/.config/superpowers/worktrees/openhuman/fix-free-plan-budget-banner

• impact: Local desktop worktree path differs from the Codex web path expected by the strict preflight. Required files, branch naming, remote, and changed-file readability checks passed.

• command: pnpm --filter openhuman-app format:check

• error: sh: cargo: command not found

• impact: Prettier completed successfully before the Rust fmt substep. This PR changes only TypeScript files; pnpm --dir app exec prettier --check src/hooks/useUsageState.ts src/hooks/useUsageState.test.ts passed.

Behavior Changes

• Intended behavior change: FREE users with zero recurring budget no longer see the completed-budget prompt solely because both usage budget values are zero.
• User-visible effect: the payment/budget-complete banner is suppressed for that FREE zero-budget state.

Parity Contract

• Legacy behavior preserved: paid/included recurring budget exhaustion still sets isBudgetExhausted and shouldShowBudgetCompletedMessage; routed-away chat workload suppression remains unchanged.
• Guard/fallback/dispatch parity checks: existing hook tests cover paid exhaustion, remaining-credit zero-budget behavior, routed-away suppression, and conservative missing-settings behavior.

Duplicate / Superseded PR Handling

• Duplicate PR(s): none found for #2129, FREE PLAN, asking for payment, completed budget, or budgetComplete.
• Canonical PR: this PR
• Resolution (closed/superseded/updated): N/A

Summary by CodeRabbit

• Bug Fixes
  • Fixed the budget completed message to display only when a recurring budget is exhausted, removing incorrect display for users with low remaining balances.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ef358168-49aa-4b75-a749-eb9be0b69580

📥 Commits

Reviewing files that changed from the base of the PR and between 65d92bf and 178f217.

📒 Files selected for processing (2)

• app/src/hooks/useUsageState.test.ts
• app/src/hooks/useUsageState.ts

---

📝 Walkthrough

Walkthrough

This PR refines the budget completed message logic in useUsageState to only show the warning when a recurring budget is actually exhausted, rather than also triggering for free users with zero recurring budget. The corresponding test is updated to validate this narrowed behavior.

Changes

Budget Completed Message Behavior

Layer / File(s)	Summary
Budget completed message logic and tests app/src/hooks/useUsageState.ts, app/src/hooks/useUsageState.test.ts	rawShouldShowBudgetCompletedMessage now directly equals rawBudgetExhausted with updated comments clarifying the message is only for exhausted recurring budgets. The test case for free users with zero recurring budget is renamed and its assertion updated to expect false instead of true.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• tinyhumansai/openhuman#2053: Both PRs update useUsageState's shouldShowBudgetCompletedMessage behavior to suppress the "budget completed" UI under routing/exhausted conditions.

Suggested labels

working

Poem

🐰 Free users need not fret and stare,
No message nags when budgets aren't there,
Only the truly exhausted now see,
The warning that says "pay me, please!"
A cleaner path through the checkout spree. 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: hiding the budget-complete prompt for free zero-budget plans, which directly addresses the fix implemented in the PR.
Linked Issues check	✅ Passed	The PR successfully addresses issue #2129 by modifying useUsageState logic to prevent the budget-complete prompt from showing for FREE-plan users with zero recurring budget while preserving warnings for paid budgets.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the billing/banner state logic in useUsageState hook and its test, with no unrelated modifications beyond the stated objective.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[graycyrus]

Looks good, nice work!