Add opt-in ccusage fallback for incomplete Codex history

[Yoroin]

Summary

• Add an opt-in Codex-only ccusage bridge for native history scans whose coverage is not yet established.
• Preserve multi-account isolation by forwarding the selected CODEX_HOME.
• Keep native results on missing helpers, timeouts, invalid JSON, non-zero exits, or lower-token fallback output.
• Add optional universal helper packaging, architecture checks, signing, tests, and MIT provenance documentation.

Changes after review

• Preserve native completeness independently: fallback results now keep historyCoverageIsEstablished=false while exposing historyFallbackCoverageIsEstablished=true.
• Dashboard and CLI can use fallback coverage without claiming that the native archive catch-up has completed.
• Packaged helpers now require an explicit version and SHA-256 digest, verify the digest before signing, and record verified provenance beside the helper.
• Added regression coverage for native/fallback flags, dashboard behavior, CLI JSON, and digest mismatch handling.

Validation

• CCUsageCodexBridgeTests: 6/6 passed.
• CostUsageFetcherTests: 15/15 passed.
• Targeted CLI and dashboard tests passed.
• Package helper tests passed.
• Shell syntax, git diff check, and SwiftFormat lint passed.
• Real-archive smoke run completed against a real local Codex archive with ccusage 20.0.19. The uploaded evidence is intentionally redacted:
  • provider=codex
  • historyCoverageIsEstablished=false
  • historyFallbackCoverageIsEstablished=true
  • dailyDays=2
  • fallback totals present=true
• No credentials, account identifiers, session identifiers, prompts, raw logs, or local filesystem paths are included here.

Design notes

• CodexBar does not download the helper or search PATH. Use CODEXBAR_CCUSAGE_PATH locally or CODEXBAR_CCUSAGE_SOURCE when packaging.
• Native catch-up status remains authoritative; the fallback is only used after an incomplete native scan and a successful, non-regressive ccusage result.
• This PR remains Draft so maintainers can decide whether the preferred long-term direction is this optional bridge, native semantic-stall recovery, or both.

Related to #2815.

[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 9, 2026, 9:34 PM ET / August 10, 2026, 01:34 UTC.

ClawSweeper review

What this changes

This draft adds an opt-in, locally supplied or package-bundled ccusage executable as a Codex-only fallback when the built-in local-history scan remains incomplete.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep this draft open for maintainer product sign-off. The prior coverage-state and packaged-helper provenance findings are addressed, and the PR now includes redacted real-archive output; current main still has no Codex-history ccusage fallback.

Priority: P2
Reviewed head: dbcb0035edc6019d8941d34e8d229c68a458676d
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch is focused, addresses the prior concrete findings, and includes credible redacted real-archive proof; only product acceptance of the new helper boundary remains.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (live_output): The PR body supplies redacted after-fix output from a real local Codex archive and ccusage run, showing the intended independent native and fallback coverage states.
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 output from a real local Codex archive and ccusage run, showing the intended independent native and fallback coverage states.
Evidence reviewed	5 items	Current main remains native-only: Current main computes Codex history coverage from catch-up state and has no ccusage fallback implementation; the only ccusage mentions are unrelated Cursor documentation comments. Follow-up addresses prior blockers: The submitted head separates fallback coverage from native coverage and validates a package helper SHA-256 before signing. Real behavior evidence: The PR body reports a redacted after-fix run against a real local Codex archive using ccusage 20.0.19, with native coverage false, fallback coverage true, two daily rows, and fallback totals present.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar scans local Codex archives into token and cost snapshots consumed by the dashboard and CLI. This change conditionally runs a local helper after native scan incompleteness, then publishes separate native and fallback coverage state to those consumers.

flowchart LR
A[Codex local archive] --> B[Native history scan]
B --> C{Native coverage complete?}
C -->|Yes| D[Native cost snapshot]
C -->|No| E[Optional ccusage helper]
E --> F{Valid non-regressive report?}
F -->|Yes| G[Fallback cost snapshot]
F -->|No| D
D --> H[Dashboard and CLI]
G --> H

Loading

Decision needed

Question	Recommendation
Should CodexBar support a user- or packager-supplied ccusage executable as a fallback for incomplete native Codex history scans?	Approve the opt-in bridge: Accept the fallback with its explicit helper provenance, selected-account scope, and clear user-facing activation policy.

Why: This adds feature, configuration, package, and executable-processing surface that the repository vision explicitly reserves for sign-off; code review cannot choose that supported product boundary.

Before merge

• Resolve merge risk (P2) - If a release bundles the helper, users with incomplete Codex history will take a new executable fallback path without a per-user setting; maintainers need to explicitly accept that compatibility and privacy boundary.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch scope	16 files, +844 / -3 lines	The proposal crosses core scanning, app packaging, dashboard and CLI contracts, tests, and third-party licensing.

Merge-risk options

Maintainer options:

1. Approve the supported helper contract (recommended)
   Require explicit maintainer sign-off on automatic bundled-helper behavior and the local override trust model before merge.
2. Pause for native-only remediation
   Leave the draft paused if maintainers do not want an external executable in the Codex-history recovery path.

Technical review

Best possible solution:

If sponsored, retain the explicit helper path, selected CODEX_HOME forwarding, bounded subprocess execution, checksum-before-signing packaging, and separate coverage flags; document whether bundled helpers are enabled automatically or require a visible user opt-in.

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

Yes, at source level: the linked report identifies incomplete native coverage, and the submitted focused test creates an incomplete Codex scan then verifies the fallback snapshot and independent coverage flags.

Is this the best way to solve the issue?

Unclear: the implementation is bounded and preserves native coverage truth, but whether an executable fallback is preferable to native catch-up recovery requires maintainer direction.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a bounded Codex local-history reliability improvement with a nontrivial new runtime boundary.
• merge-risk: 🚨 compatibility: A successful fallback changes shown Codex totals and coverage behavior for users whose native scan is incomplete.
• merge-risk: 🚨 security-boundary: The application can execute a supplied or bundled helper with access to the selected Codex home.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit 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 output from a real local Codex archive and ccusage run, showing the intended independent native and fallback coverage states.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body supplies redacted after-fix output from a real local Codex archive and ccusage run, showing the intended independent native and fallback coverage states.

Evidence

What I checked:

• Current main remains native-only: Current main computes Codex history coverage from catch-up state and has no ccusage fallback implementation; the only ccusage mentions are unrelated Cursor documentation comments. (Sources/CodexBarCore/CostUsageFetcher.swift:335, c94fe8d86585)
• Follow-up addresses prior blockers: The submitted head separates fallback coverage from native coverage and validates a package helper SHA-256 before signing. (Sources/CodexBarCore/CostUsage/CCUsageCodexBridge.swift:92, dbcb0035edc6)
• Real behavior evidence: The PR body reports a redacted after-fix run against a real local Codex archive using ccusage 20.0.19, with native coverage false, fallback coverage true, two daily rows, and fallback totals present. (dbcb0035edc6)
• Native catch-up provenance: Recent merged history specifically covers bounded Codex catch-up and fork accuracy, making it the relevant ownership trail for the underlying incomplete-history behavior. (Sources/CodexBar/UsageStore+CodexCostCatchUp.swift:145, 4f99e6aba8c3)
• Repository direction: The repository VISION.md requires sign-off for new features, package/toolchain changes, and behavior affecting user privacy. (VISION.md:9, c94fe8d86585)

Likely related people:

• Xu Xiang: Authored the recent merged fixes for bounded Codex cost catch-up and appending fork progress. (role: introduced recent native catch-up fixes; confidence: high; commits: 2920019bc16d, 4f99e6aba8c3; files: Sources/CodexBar/UsageStore+CodexCostCatchUp.swift, Sources/CodexBarCore/CostUsageFetcher.swift)
• Peter Steinberger: Repository history shows extensive contribution on the cost-usage surfaces, and the bounded catch-up refactor credits a co-author contribution. (role: recent area contributor; confidence: medium; commits: 2920019bc16d, c94fe8d86585; files: Sources/CodexBarCore/CostUsageFetcher.swift, Sources/CodexBarCore/CostUsageModels.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 (2 earlier review cycles)

• reviewed 2026-08-09T16:36:48.393Z sha ba573b6 :: needs real behavior proof before merge. :: [P1] Keep native scan completeness independent from fallback data | [P2] Verify the packaged helper's immutable provenance
• reviewed 2026-08-09T17:20:42.062Z sha ba573b6 :: needs real behavior proof before merge. :: [P1] Preserve the native coverage state | [P2] Pin the packaged ccusage artifact

[Yoroin]

@clawsweeper re-review

Updated the PR body with redacted real-archive smoke evidence and pushed the follow-up fixes for native coverage separation and version/SHA-256 helper provenance.

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

Re-review progress:

• State: Failed
• Detail: Durable publication exhausted its retry budget and was retained for operator dead-letter recovery.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31348106467
• Updated: 2026-08-10T01:49:38.971Z