Add local session cost ledger

[wicolian]

Summary

Adds a local Codex session cost ledger that works alongside a managed Codex account. It exposes a clear Settings toggle for local session cost estimates, keeps the local scanner independent from the selected managed account, and avoids showing an account quota failure as a failure of valid local cost data.

Problem

Developers using organization-provided OpenAI API keys can run Codex but often do not have OpenAI organization billing or administrator access. The existing account-level quota paths cannot provide a useful spend view in that situation.

The local session ledger is the appropriate source for this case. It reads the token records Codex already writes locally and produces an API-rate estimate without calling the OpenAI billing API.

How it works

CodexBar scans JSONL session files under $CODEX_HOME/sessions when CODEX_HOME is set, otherwise ~/.codex/sessions. It takes the final token_count record from each session. For example:

rg '"type":"token_count"' \
  ~/.codex/sessions/2026/07/14/rollout-2026-07-14T16-38-08-<session>.jsonl \
  | tail -1

The record provides total input, cached input, and output token counts. Cost calculation separates cached and uncached input:

uncached_input = input_tokens - cached_input_tokens
cost = uncached_input * input_rate
     + cached_input_tokens * cached_input_rate
     + output_tokens * output_rate

Rates are per token in the calculation. The price catalog refreshes from models.dev when available and uses bundled pricing offline. The result is an API-rate estimate, not an organization invoice. Negotiated discounts, credits, taxes, and platform-side accounting can differ.

Behavior

• Shows 1-day and 30-day local token and estimated-cost totals.
• Lists the contributing conversations with cost, model, input, cached input, output, and last activity.
• Preserves per-model breakdowns for sessions that switch models.
• Uses the existing on-disk scan cache for fast refreshes.
• Keeps managed-account quota and web-dashboard behavior separate from the local ledger.
• Suppresses the generic remote quota error when valid local Codex cost data is available.
• Does not upload session content, require an Admin API key, or modify existing provider keys.

Validation

• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test --filter ProviderSettingsDescriptorTests
• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test --filter MenuCardModelCodexDegradedQuotaTests
• CodexBarCLI cost --provider codex --refresh --no-color against real local session logs
• Installed the release build locally and verified the CodexBar menu and local cost view

Closes #2174

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 17, 2026, 4:08 AM ET / 08:08 UTC.

Summary
Adds an opt-in local Codex session-cost ledger with independent account scope, offline pricing, conversation/model breakdowns, settings and menu UI, documentation, and regression tests.

Reproducibility: not applicable. as a bug reproduction: this PR adds a new opt-in capability. The submitted screenshot and claimed live CLI/app runs provide high-confidence behavioral validation of that capability.

Review metrics: 2 noteworthy metrics.

• Patch surface: 31 files; 862 additions, 103 deletions. This is a substantial but cohesive cross-layer feature spanning scanner models, settings, menu presentation, documentation, and tests.
• Review continuity: 3 prior findings resolved; 4 later cycles clean. The branch received iterative scope and accounting hardening without leaving a known actionable blocker.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #2174
Summary: This PR is the explicit implementation candidate for the linked open feature issue.

Members:

• canonical: Show local Codex session costs for organization API-key users #2174 - The issue defines the requested local-ledger behavior, links this PR as its proposed implementation, and remains open until the PR is resolved.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Risk before merge

• [P1] The exact head is not yet fully CI-validated: both Linux CLI builds remain in progress and the two macOS Swift test shards remain queued.

Maintainer options:

1. Decide the mitigation before merge
   Land the opt-in, default-off implementation once the exact head passes required checks, then let the linked feature issue close through the PR relationship.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No automated repair remains; wait for the exact-head checks and then perform normal maintainer merge review.

Security
Cleared: The patch adds no dependency or supply-chain changes, keeps session data local, defaults the feature off, and disables pricing network refresh in local-only mode.

Review details

Best possible solution:

Land the opt-in, default-off implementation once the exact head passes required checks, then let the linked feature issue close through the PR relationship.

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

Not applicable as a bug reproduction: this PR adds a new opt-in capability. The submitted screenshot and claimed live CLI/app runs provide high-confidence behavioral validation of that capability.

Is this the best way to solve the issue?

Yes. Reusing the existing cost scanner behind a Codex-specific, default-off preference is narrower and safer than changing managed-account quota behavior or adding another billing integration.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 0f27d0e3f686.

Label changes

Label changes:

• add feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The feature gives organization API-key users private, local spend visibility without requiring billing-admin access or uploading session content.

Label justifications:

• P2: This is a bounded opt-in product improvement with meaningful user value but no urgent regression, data-loss, security, or availability impact.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The feature gives organization API-key users private, local spend visibility without requiring billing-admin access or uploading session content.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The screenshot directly shows the installed app's local-cost UI, supplemented by a reported CLI run against real session logs and release-build verification.
• proof: sufficient: Contributor real behavior proof is sufficient. The screenshot directly shows the installed app's local-cost UI, supplemented by a reported CLI run against real session logs and release-build verification.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The screenshot directly shows the installed app's local-cost UI, supplemented by a reported CLI run against real session logs and release-build verification.

Evidence reviewed

What I checked:

• Provider-specific opt-in: The branch adds a Codex-only local-session estimate toggle, while the persisted preference defaults to false and does not enable cost summaries for other providers. (Sources/CodexBar/Providers/Codex/CodexProviderImplementation.swift:76, 6321d01d60c6)
• Managed/local scope separation: Effective cost enablement and token-cost scope logic distinguish the selected managed account from the ambient local Codex home, addressing the earlier account-scope review findings. (Sources/CodexBar/UsageStore+TokenCost.swift:32, 6321d01d60c6)
• Offline local mode: The fetcher accepts an explicit pricing-refresh policy, and local-ledger mode disables network pricing refresh while retaining cached or bundled pricing. (Sources/CodexBarCore/CostUsageFetcher.swift:65, 6321d01d60c6)
• Focused regression coverage: New and extended tests cover the Codex-specific preference, managed-versus-local scope, session breakdown accounting, degraded remote quota presentation, cache behavior, and network-free pricing. (Tests/CodexBarTests/CodexLocalSessionCostSettingsTests.swift:1, 6321d01d60c6)
• Prior review continuity: The three findings raised on the first review cycle—managed-account scope, provider-specific preference, and complete contributing-source accounting—were addressed; four later review cycles reported no findings. (6321d01d60c6)
• Real behavior proof: The PR body reports a CLI run against real local session logs and an installed release-build check, with a screenshot directly showing the resulting CodexBar menu and local-cost view. (6321d01d60c6)

Likely related people:

• steipete: Authored the branch's scope, refresh, isolation, and hardening follow-ups and repeatedly integrated current main, making them the clearest routing candidate for final merge review. (role: feature owner and recent area contributor; confidence: high; commits: 57eabcadf44f, 4cc44da5ab6f, 8557f8128872; files: Sources/CodexBar/UsageStore+TokenCost.swift, Sources/CodexBar/UsageStore.swift, Sources/CodexBarCore/CostUsageFetcher.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-15T07:17:16.313Z sha 4c3f7c8 :: found issues before merge. :: [P1] Preserve the selected managed account's cost scope | [P1] Use a Codex-specific preference for this toggle | [P2] Include every source contributing to conversation totals
• reviewed 2026-07-17T01:31:16.194Z sha cd032ea :: needs maintainer review before merge. :: none
• reviewed 2026-07-17T04:09:32.321Z sha c30750b :: needs maintainer review before merge. :: none
• reviewed 2026-07-17T05:28:32.482Z sha 22eddb3 :: needs maintainer review before merge. :: none
• reviewed 2026-07-17T07:01:21.331Z sha d6d75ee :: needs maintainer review before merge. :: none

[steipete]

Maintainer verification

• Merged current origin/main, including Fix copied-prefix Codex subagent accounting #2228, fix: retain incomplete JSONL tails #2168, and the unified usage/spend dashboard; regenerated the Codex parser hash where required.
• make check: passed (format, strict lint, locale/docs/package/signing/sharding gates; 0 lint violations).
• Focused tests passed after the final conflict resolution: CodexLocalSessionCostSettingsTests, UsageStoreCachedTokenHydrationTests, CostUsageFetcherCacheSnapshotTests, and CodexSubagentAccountingIntegrationTests (27 tests total). Earlier focused fetcher/settings/menu/cache/manual-refresh suites and full make test also passed.
• Exact PR-head CI run 29565191154: all required checks green on 6321d01d60c6d755e7b9b0335bcd8ca842431cd8, including Linux builds/tests, lint, both macOS shards, aggregate gate, and GitGuardian.
• Autoreview repeated. Accepted findings were fixed. One cached-hydration finding was rejected with direct code and regression-test proof: non-empty managed/profile homes return no ambient cached snapshot. Final merged-main staged review could not ingest incoming binary dashboard screenshots; its three source conflict resolutions were manually reviewed and covered by the focused tests above.
• Merge commit: 63215da4257565ff65c10a7d57d2550fc265011b.