fix(codex): preserve established-empty history

[Yuxin-Qiao]

Summary

• preserve a completed Codex scan with no rows as an established empty history
• expose known-zero token snapshots only after the requested history coverage is established
• keep incomplete, pending catch-up, buffered retry, expanded-scope, and unpriced states unavailable
• add cache hydration and local-day regression coverage

User impact

This fixes the Codex usage/spend dashboard remaining unavailable after a completed local scan has established that the selected history is empty, without turning incomplete scans into fabricated zeroes.

Validation

• swift test --disable-sandbox --filter 'CostUsageFetcherTests|CostUsageFetcherCacheSnapshotTests|CostUsageTokenSnapshotDaySelectionTests'
• 45 tests in 3 suites passed
• git diff --check

Verification evidence

Redacted local fixture only; no Keychain, network, or real account was used.

• Fixture: a temporary empty CODEX_HOME with sessions and archived_sessions directories.
• After-fix fresh scan: swift run --disable-sandbox CodexBarCLI cost --provider codex --format json --days 7 --refresh --json-only --no-color returned source=local, historyCoverageIsEstablished=true, sessionTokens=0, sessionCostUSD=0, last30DaysTokens=0, last30DaysCostUSD=0, and daily=[].
• A new process against the same fixture, without --refresh, returned the same zero fields and historyCoverageIsEstablished=true, demonstrating cache hydration of the established-empty result.

Latest CI (2026-08-16)

• Head aef668ecb3b8db696a8090c42ddec33de5a254ff is green in CI run 31862906701.
• The earlier aggregate failure was superseded by this successful rerun; no code change is indicated.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 15, 2026, 2:55 PM ET / 18:55 UTC.

ClawSweeper review

What this changes

The PR makes completed empty local Codex history scans report known-zero token and cost totals, including when the completed result is hydrated from cache.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

The PR is a focused, proof-backed fix for established-empty Codex history; no blocking correctness or security defect was found, so it merits normal maintainer merge review.

Priority: P2
Reviewed head: aef668ecb3b8db696a8090c42ddec33de5a254ff

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Focused implementation, direct local behavior proof, regression coverage, and green replacement CI support normal merge review.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The PR body supplies redacted after-fix CLI output for a fresh empty local scan and a separate-process cached hydration run.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body supplies redacted after-fix CLI output for a fresh empty local scan and a separate-process cached hydration run.
Evidence reviewed	5 items	Current main lacks the proposed empty-history path: Current main only hydrates a cached Codex report when it has day rows, so an otherwise valid empty cache does not produce a snapshot. PR gates zeroes on completed coverage: The branch verifies scan time, timezone, roots, no pending or buffered retry work, and no expanded requested window before treating an empty cache as established. Regression coverage: The branch covers fresh completed-empty scans, cache hydration, pending catch-up, buffered fork retries, and token-snapshot zero versus unavailable semantics.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar scans local Codex session files into a cached daily usage report, then converts that report into the token and cost snapshot displayed by the app. This change distinguishes completed empty history from incomplete scan state.

flowchart LR
  A[Codex session files] --> B[Local history scanner]
  B --> C[Usage cache]
  C --> D[Coverage validation]
  D --> E[Token and cost snapshot]
  E --> F[Menu bar usage display]

Loading

Before merge

• Complete next step (P2) - No mechanical repair is needed; the remaining action is normal maintainer merge review.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	production +58/-4, tests +169/-9 across 5 files	The code change is confined to the fetcher and is covered across fresh-scan, cache-hydration, and unavailable-state cases.

Technical review

Best possible solution:

Merge the narrow cache-coverage fix while retaining unavailable output for incomplete, buffered, or out-of-window scans.

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

Yes—source establishes the prior empty-cache path, and the PR provides redacted after-fix CLI evidence for both a fresh scan and cache hydration.

Is this the best way to solve the issue?

Yes—the branch narrowly exposes zeroes only after coverage is established and preserves unavailable results for incomplete states.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This corrects a limited-scope Codex usage-display state without evidence of a broader outage.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body supplies redacted after-fix CLI output for a fresh empty local scan and a separate-process cached hydration run.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body supplies redacted after-fix CLI output for a fresh empty local scan and a separate-process cached hydration run.

Evidence

What I checked:

• Current main lacks the proposed empty-history path: Current main only hydrates a cached Codex report when it has day rows, so an otherwise valid empty cache does not produce a snapshot. (Sources/CodexBarCore/CostUsageFetcher.swift:823, f15f142a7787)
• PR gates zeroes on completed coverage: The branch verifies scan time, timezone, roots, no pending or buffered retry work, and no expanded requested window before treating an empty cache as established. (Sources/CodexBarCore/CostUsageFetcher.swift:843, aef668ecb3b8)
• Regression coverage: The branch covers fresh completed-empty scans, cache hydration, pending catch-up, buffered fork retries, and token-snapshot zero versus unavailable semantics. (Tests/CodexBarTests/CostUsageFetcherCacheSnapshotTests.swift:79, aef668ecb3b8)
• Real behavior proof and CI: The PR body records redacted fresh-scan and separate-process cache-hydration CLI output with known-zero fields; supplied check context shows the replacement lint-build-test run succeeded. (aef668ecb3b8)
• Feature-history routing: Available file history records Peter Steinberger as the dominant contributor and Yuxin Qiao as a prior contributor on the central fetcher path. (Sources/CodexBarCore/CostUsageFetcher.swift, 0e453c4a5b2a)

Likely related people:

• Peter Steinberger: Available feature history attributes the largest share of recorded work on the central usage-fetcher path to Peter Steinberger. (role: primary historical contributor; confidence: medium; commits: 0e453c4a5b2a; files: Sources/CodexBarCore/CostUsageFetcher.swift)
• Yuxin Qiao: Available history records prior contributions on the central fetcher path in addition to this proposed fix. (role: prior area contributor; confidence: medium; commits: aef668ecb3b8; files: Sources/CodexBarCore/CostUsageFetcher.swift)

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.

History

Review history (4 earlier review cycles)

• reviewed 2026-08-14T14:39:26.595Z sha 290bb3a :: needs real behavior proof before merge. :: none
• reviewed 2026-08-14T16:17:05.615Z sha aef668e :: needs real behavior proof before merge. :: none
• reviewed 2026-08-14T18:28:29.510Z sha aef668e :: needs maintainer review before merge. :: none
• reviewed 2026-08-15T03:53:29.174Z sha aef668e :: needs maintainer review before merge. :: none

[Yuxin-Qiao]

@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 exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31828916493
• Updated: 2026-08-14T18:30:11.826Z

[steipete]

Thanks @Yuxin-Qiao! This landed via #2978, which reconciled your established-empty contract with the #2961 partial-spend contract that merged in the meantime — both invariants hold together (established-empty shows zeroes, valid partial pricing stays, incomplete states remain unavailable), proven by the combined 46 fetcher/cache tests plus the 140-test SpendDashboard suite. Closing as superseded; the changelog credits you.