feat(sakana): surface pay-as-you-go credit balance

[ss251]

Summary

• Fetch Sakana subscription quota and the optional pay-as-you-go tab concurrently with the same normalized cookie header.
• Keep subscription quota authoritative: PAYG network, status, redirect, and parse failures only omit the optional enrichment.
• Give the optional request a finite five-second lifetime and only a shared 200 ms merge budget after the required result is ready.
• Parse the server-rendered credit balance, recent usage total, and date-range label, including React hydration comments.
• Render an Extra usage card in the live menu and matching text-descriptor rows; both fetch and render paths obey the optional-usage setting, so cached values disappear immediately when disabled.
• Document the two-request behavior and add the 0.38.1 changelog entry with thanks to @ss251.

Proof

• Exact integrated head: 89bcd8552358e81612399bd9221dd5b639d01ae0.
• swift test --filter 'SakanaUsageFetcherTests|MenuDescriptorSakanaTests' — 27/27 passed.
• make check — repository guards, links, locale parity, SwiftFormat, and SwiftLint passed with zero violations.
• make test — all 46 sharded groups passed on the reviewed Sakana code head; exact integrated-head CI reruns the complete matrix.
• Structured autoreview — clean, 0.86 confidence, no accepted/actionable findings on the exact branch diff.
• ./Scripts/compile_and_run.sh — production bundle built, signed, packaged, launched, and remained running from this exact checkout.
• The contributor verified authenticated Sakana billing markup and the required ?tab=payAsYouGo route: feat(sakana): surface pay-as-you-go credit balance #1825 (comment).
• Maintainer live-auth boundary: the existing Chrome profile reaches Sakana's explicit 403 REGION RESTRICTED page in the UK and has no Sakana session; the exact bundled CLI therefore reports no available Sakana fetch strategy. No authenticated claim is inferred from synthetic data.

Risk

Low to medium and provider-scoped. The required subscription result never waits more than the bounded enrichment budget, optional failures remain contained, the optional task is cancelled on required failure/caller cancellation, and cached optional rows obey the current setting at render time.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 4, 2026, 5:54 AM ET / 09:54 UTC.

Summary
The branch adds best-effort Sakana pay-as-you-go credit balance fetching, parsing, snapshot storage, menu rendering, docs, and focused tests.

Reproducibility: not applicable. as a bug reproduction: this is a feature PR. Source review and tests show the intended fetch/render paths, but real menu/toggle proof is still incomplete.

Review metrics: 2 noteworthy metrics.

• Changed surface: 12 files, 755 additions, 32 deletions. The provider-scoped change still spans fetch logic, shared snapshot schema, menu UI, docs, and tests.
• New authenticated request: 1 optional Sakana billing-tab GET. Maintainers should explicitly notice the new same-cookie provider request because CI cannot prove the live privacy and provider-behavior tradeoff.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
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 current-head app proof, such as a screenshot or recording, showing the Sakana Extra usage card.
• Show that disabling optional credits and extra usage hides the Sakana PAYG rows without waiting for a refetch; redact private account data before posting.
• Refresh or remove the stale 0.38.1 changelog entry after rebasing onto current main.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: Live CLI output demonstrates the authenticated PAYG fetch/parser path, but the current PR still lacks redacted after-fix proof from a real built app showing the visible menu card and opt-out toggle behavior. 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.

Mantis proof suggestion
A short visible app proof would materially help because the remaining evidence gap is the menu card and opt-out UI behavior, not parser unit coverage. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify Sakana Extra usage appears in the freshly built app menu and disappears immediately when optional credits and extra usage is disabled.

Risk before merge

• [P1] Existing Sakana users with optional credits and extra usage enabled will make one additional authenticated same-origin billing-tab request after upgrade; it is gated and bounded, but maintainers still need to accept that provider/privacy change.
• [P1] The branch still lacks redacted after-fix proof that the current built app shows the Extra usage card and hides cached PAYG rows when optional credits and extra usage is disabled.
• [P1] The PR head is behind the 0.38.2 changelog bump, so its release note is currently filed under a version that has already shipped.

Maintainer options:

1. Require menu proof and request acceptance (recommended)
   Ask for redacted current-head proof from a freshly built app showing the Sakana Extra usage card and opt-out hiding behavior, then have a maintainer explicitly accept the added optional billing-tab request.
2. Accept the provider-scoped request
   Maintainers may decide the same-origin optional request is acceptable with the current setting gate and merge after ordinary checks once the proof and release-note gaps are handled.
3. Pause the new scrape
   If the extra authenticated tab scrape is not worth the privacy or maintenance surface, narrow or close the PR rather than carrying a new PAYG parser.

Next step before merge

• [P1] Human action remains: contributor proof of the visible menu behavior, maintainer acceptance of the added Sakana billing request, and release-note refresh against current main.

Security
Cleared: No concrete security or supply-chain regression was found; the sensitive behavior is a documented same-origin Sakana cookie request gated by the existing optional-usage setting.

Review findings

• [P3] Move the note out of the shipped 0.38.1 bucket — CHANGELOG.md:6

Review details

Best possible solution:

Land after maintainer acceptance of the extra same-origin Sakana billing request, redacted current-head app proof of the visible menu behavior, and a release-note refresh against the current unreleased version.

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

Not applicable as a bug reproduction: this is a feature PR. Source review and tests show the intended fetch/render paths, but real menu/toggle proof is still incomplete.

Is this the best way to solve the issue?

Mostly yes: the implementation follows existing provider fetch, snapshot, bounded-task, and menu-card patterns, and prior review defects appear addressed. The remaining gaps are proof, maintainer acceptance of the added optional request, and stale release-note placement rather than a broad redesign.

Full review comments:

• [P3] Move the note out of the shipped 0.38.1 bucket — CHANGELOG.md:6
  Current main already has 0.38.2 — Unreleased and 0.38.1 — 2026-07-04, but this PR head still adds the Sakana note under 0.38.1 — Unreleased. Rebase and move the note to the current unreleased bucket, or leave release-note placement to the maintainer, so a new feature is not filed under a shipped release.
  Confidence: 0.93

Overall correctness: patch is correct
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 93cb1233b305.

Label changes

Label justifications:

• P2: This is a normal provider-scoped feature with bounded blast radius rather than an urgent regression or release blocker.
• merge-risk: 🚨 compatibility: Merging changes existing Sakana refresh behavior by adding a second authenticated console request for users with optional extras enabled.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp 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: Live CLI output demonstrates the authenticated PAYG fetch/parser path, but the current PR still lacks redacted after-fix proof from a real built app showing the visible menu card and opt-out toggle behavior. 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 applied: AGENTS.md was read fully and its provider/testing/concurrency guidance affected the review, especially avoiding live provider probes and checking optional async enrichment carefully. (AGENTS.md:1, 93cb1233b305)
• Current main lacks PAYG support: Current main has no Sakana PAYG snapshot or payAsYouGo symbols in the Sakana provider, shared snapshot, menu, tests, or docs paths, so this PR is not already implemented on main. (Sources/CodexBarCore/Providers/Sakana/SakanaUsageFetcher.swift, 93cb1233b305)
• Fetch opt-out is wired: The PR head forwards context.includeOptionalUsage into SakanaUsageFetcher.fetchUsage, and the fetcher creates the optional PAYG task only when that flag is true. (Sources/CodexBarCore/Providers/Sakana/SakanaProviderDescriptor.swift:57, 89bcd8552358)
• Optional fetch is bounded and best-effort: The PR head bounds PAYG collection with a 200 ms shared budget and a five-second optional fetch lifetime, cancels the optional task after collection, and returns nil for failed PAYG responses. (Sources/CodexBarCore/Providers/Sakana/SakanaUsageFetcher.swift:223, 89bcd8552358)
• PAYG parsing is provider-scoped: The PAYG request is same-origin HTTPS, sends the normalized Sakana cookie header, parses the credit balance/usage/date label from the PAYG tab, and returns nil rather than failing the primary quota fetch when parsing or response checks fail. (Sources/CodexBarCore/Providers/Sakana/SakanaUsageFetcher.swift:278, 89bcd8552358)
• Live menu path is gated: The live menu-card model maps Sakana PAYG into a provider-cost section only for Sakana and only while optional credits and extra usage are enabled. (Sources/CodexBar/MenuCardView.swift:823, 89bcd8552358)

Likely related people:

• steipete: Authored the merged hardened Sakana provider PR and several current PAYG branch repair commits around bounded refresh and live menu rendering, plus owner review comments on the fixed paths. (role: feature owner and recent area contributor; confidence: high; commits: 87635bcc755b, 38dbb1d71232, 8b4cf0da77fa; files: Sources/CodexBarCore/Providers/Sakana/SakanaUsageFetcher.swift, Sources/CodexBarCore/Providers/Sakana/SakanaProviderDescriptor.swift, Sources/CodexBar/MenuCardView.swift)
• LeoLin990405: The merged Sakana provider PR preserved their original provider, parser, and test commits before maintainer hardening. (role: original implementation contributor; confidence: medium; commits: 3585d1b2729a, 3676c209a069, f23516ec71ba; files: Sources/CodexBarCore/Providers/Sakana/SakanaUsageFetcher.swift, Sources/CodexBarCore/Providers/Sakana/SakanaProviderDescriptor.swift, Tests/CodexBarTests/SakanaUsageFetcherTests.swift)
• ss251: Authored this PAYG implementation work and the merged Sakana UTC reset-time fix, so they have current provider-specific context beyond opening this PR. (role: recent Sakana contributor; confidence: high; commits: 0bae5719be08, d9b7d8895e37, 8fb8c74259dd; files: Sources/CodexBarCore/Providers/Sakana/SakanaUsageFetcher.swift, Tests/CodexBarTests/SakanaUsageFetcherTests.swift, Tests/CodexBarTests/MenuDescriptorSakanaTests.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.

Review history (5 earlier review cycles)

• reviewed 2026-07-04T06:15:39.648Z sha 56a01cc :: found issues before merge. :: [P2] Render the PAYG rows through the live menu card | [P2] Drop the partial Gemini helper change from this branch
• reviewed 2026-07-04T08:09:59.801Z sha bf0875d :: needs real behavior proof before merge. :: none
• reviewed 2026-07-04T08:33:40.505Z sha bf0875d :: needs real behavior proof before merge. :: none
• reviewed 2026-07-04T08:38:23.058Z sha bf0875d :: needs real behavior proof before merge. :: none
• reviewed 2026-07-04T09:49:30.258Z sha 89bcd85 :: needs real behavior proof before merge. :: none

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0bae5719be

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ss251]

Addressed both P2 findings from the automated review:

• PAYG fetch now respects the optional-usage opt-out. fetchUsage takes an includeOptionalUsage flag (default true, wired from context.includeOptionalUsage in the descriptor's fetch strategy — same pattern DeepSeek/MiniMax/OpenCodeGo already use for this setting) and skips the second ?tab=payAsYouGo request entirely when it's false, rather than making the request and discarding the result. New test asserts exactly one request is made in that mode.
• Removed the menu-bar-text wiring for the balance. You're right that .secondary already has a real meaning for Sakana (show the weekly window), and reusing it for "show PAYG balance instead" would silently override that for anyone who picked Weekly as their menu bar metric. Rather than inventing a new preference value to disambiguate, I just removed sakanaBalanceDisplayText and its call site — the balance is still fully visible via the Balance:/Recent usage: rows in the dropdown menu, which don't have this collision.

18/18 Sakana tests pass, swiftformat/swiftlint --strict clean, full test-target build green.

[ss251]

@clawsweeper re-review

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

[ss251]

Addressed the two new P2 findings from the re-review, plus the requested real behavior proof:

• supportsCredits reverted to false. Confirmed it's read in exactly one place in the app (MenuCardView+Costs.swift's creditsLine), which has no Sakana branch and would fall back to the static creditsHint string instead of the fetched balance — a real bug. Reverting is a zero-side-effect fix; the balance is still fully visible via the explicit Balance:/Recent usage: menu rows, which don't have this ambiguity.
• Optional PAYG fetch is now bounded independent of the caller's timeout. Wrapped in BoundedTaskJoin with a fixed 5s grace period, mirroring OpenRouterUsageFetcher's existing boundedKeyFetch pattern for its own optional /key enrichment call (same _forTesting shape, same "operation that ignores cancellation" regression test). A slow console response can now add at most ~5s, never the full timeout a second time, and can never delay already-parsed quota windows past that bound.

Real behavior proof — built this exact branch (with both fixes applied) into the codexbar CLI and ran it against a live Sakana account:

{
  "provider": "sakana",
  "source": "web",
  "usage": {
    "identity": { "loginMethod": "Standard $20/mo", "providerID": "sakana" },
    "primary": { "usedPercent": 0, "windowMinutes": 300 },
    "secondary": { "usedPercent": 18, "windowMinutes": 10080, "resetsAt": "2026-07-05T18:30:00Z" },
    "sakanaPayAsYouGo": { "creditBalance": 0, "periodUsageTotal": 0, "periodLabel": "Jun 02, 2026 - Jul 01, 2026" },
    "updatedAt": "2026-07-01T21:08:07Z"
  }
}

sakanaPayAsYouGo.creditBalance matches the account's actual $0.00 pay-as-you-go balance shown on console.sakana.ai/billing?tab=payAsYouGo at the same time. (secondary.resetsAt still shows the pre-fix local-time-shifted value here — that fix lives in the separate #1827/#1826 branch, not this one.)

19/19 Sakana tests pass, lint clean.

@clawsweeper re-review

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

[ss251]

Addressed the Codex render-path finding (and rebased on top of @steipete's concurrent-enrichment rework).

Fix: the Balance: / Recent usage: rows now gate on settings.showOptionalCreditsAndExtraUsage at the render layer in MenuDescriptor, not just at the fetch layer. Previously, toggling "Show optional credits and extra usage" off only rebuilt the menu without an immediate refetch, so a previously-fetched sakanaPayAsYouGo lingered in the cached snapshot and the rows stayed visible until the next refresh cleared the field. Now the opt-out takes effect immediately regardless of cached snapshot contents — the required 5-hour/weekly quota windows are unaffected.

Added MenuDescriptorSakanaTests covering both paths: rows present when the setting is on, hidden when off (while asserting the quota windows still render).

swift test (Sakana + menu + diagnostic suites, 50 tests) green, swift build --build-tests clean, lint/format clean.

@clawsweeper re-review

[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: 56a01cc116

ℹ️ 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".

[steipete]

Landed as 97c0035.

Proof on exact PR head 89bcd85:

• Sakana fetcher, menu descriptor, and live menu-card model tests passed 27/27
• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer make check passed with zero violations
• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer make test passed all 46/46 shards
• exact-head CI passed all checks; zero unresolved review threads
• production bundle built, signed, launched, and remained running; authenticated rendering could not be claimed locally because this Mac has no Sakana fetch strategy/session

Subscription quota remains authoritative; optional PAYG failures are bounded and contained, and both fetch and render obey the optional-usage setting. Thanks @ss251!