Port upstream 0.67.0: cost --period and period-aware serve /cost (stacked on #648)

[Finesssee]

Summary

Part B of upstream 0.67.0 item 1: wires the CostReportingPeriod core (#648) into codexbar cost and serve /cost. Stacked on #648.

• codexbar cost --period month-to-date|all. --days is now Option<u32> so "explicitly passed" is detectable: --days N (clamped to 1..=365) always selects a rolling window and wins over --period; with neither flag the saved cost_reporting_period applies, which is rolling:30 by default, so an unconfigured install behaves as before.
• Text headings use the period label (Last 30 days, Month to date, All, Today). The empty-scan messages now say "in the selected period" instead of repeating a day count.
• JSON adds reportingPeriod (raw string), historyLabel, and a totals object for the selected window (inputTokens, outputTokens, cachedTokens, reasoningTokens, totalTokens, totalCost; null when a scan found nothing without a known zero). Existing cost, tokens, sessions_count, spendContract fields keep their meaning; days_scanned is the resolved day count.
• --remote / --summary-only keep the 1..=365 protocol: month to date is sent as its current day count, All is rejected unless --days N is passed.
• serve /cost resolves the saved period on every request and feeds it to the scanner, Antigravity, Muse and the days_scanned/totals fields, plus reportingPeriod/historyLabel. Daily chart rows follow the period (All charts the latest 365 days).
• Shared helpers live in a new rust/src/cli/cost_period.rs (resolve_period, window_days, stamp_period, cost_totals_json); CostReportingPeriod::label() is added to the core.
• docs/CLI.md documents the flags, JSON fields and the compatibility surfaces.

Upstream reference

• Release bullet (0.67.0): "Costs: select calendar month-to-date or all available history across menus, Usage & Spend, CLI, HTTP cost output, widgets" (upstream Feature request: calendar month-to-date option for the cost reporting period steipete/CodexBar#2087, Feature Request: Add calendar-month usage view for Cursor ID (month-to-date) steipete/CodexBar#2859, Feature request: All-time cumulative usage & cost view (a "lifetime bill") steipete/CodexBar#1708; 9f76e1194).
• Tag-pinned reads at v0.67.0 (GET only): Sources/CodexBarCLI/CLICostCommand.swift (decodeCostReportingPeriod, costTotals, reportingPeriod, historyLabel), CLIServeCommand.swift (/cost period resolution), docs/cost-reporting-periods.md, docs/cli.md.

Ported / Deferred

Ported: everything above.

Not changed on purpose (documented compatibility surfaces, 30-day meaning kept): the dashboard cost line ("last 30 days"), dashboard/snapshot.rs and source.rs 30-day handling, and the Prometheus gauge codexbar_cost_last_30_days_usd. The dashboard page reads only the daily arrays from /cost, so its bar charts now span the selected period and are self-labelled by their first/last dates.

Deferred or divergent:

• No /cost response cache exists locally (upstream caches responses, so its cache key folds in the period identity). Each request re-resolves the saved period, and the scanners' disk caches are already keyed by the resolved day range (Port upstream 0.67.0: add CostReportingPeriod core and range-aware cost scanners #648), so a period or month change never reuses another window's entries. No cache-key test applies.
• totals omits upstream's provenance, coverage and incompleteRequestCount (no local equivalent). Token key is cachedTokens rather than upstream's cacheReadTokens because the local Claude count includes cache creation.
• --days above 365 is now clamped to 365 (upstream behavior; the spend contract and host summaries already clamped or rejected it).
• --group-by session uses the rolling conversation index, so All lists the latest 365 days at most (heading reports the window used).
• spendContract.daily still clamps to 1..=365 days, so under All it reports the latest year.
• Pinned cost time zone: unchanged from Port upstream 0.67.0: add CostReportingPeriod core and range-aware cost scanners #648 (local zone).

Validation

Run with +1.98.0 on E-cores, target dir slot-5:

• cargo fmt --all: clean
• cargo clippy -p codexbar --all-targets -- -D warnings: pass
• cargo clippy --workspace --all-targets -- -D warnings: the Tauri crate build script failed with a stale-path error inside the slot-5 target dir (failed to read plugin permissions ... doubao-agent-icon ... app_hide.toml), unrelated to this change; the Tauri crate is untouched and does not reference CostArgs or /cost.
• cargo test -p codexbar cli:: -- --test-threads=4: 208 passed, 0 failed
• cargo test -p codexbar -- --test-threads=4 (full): 2199 passed, 0 failed, 1 ignored; doc/integration 1 passed
• New tests: clap parse (--days/--period absent vs given), resolver matrix (--days beats --period, both absent uses saved, invalid --period, host summary rejects All), JSON payload stamp/totals (rolling, month to date, token-history providers), label().
• Smoke on the built binary: cost --period weekly exits with "--period must be month-to-date or all"; cost -p codex --period all --summary-only is rejected with the override hint; cost -p claude --period month-to-date --json reports reportingPeriod: month-to-date, historyLabel: Month to date, days_scanned: 29, period start 2026-09-01; --days 7 and --period all headings read Last 7 days and All.
• No file crossed 1000 lines (cli/cost.rs 840, cli/cost_period.rs 189, serve/data.rs 227).

Affected areas

rust/src/cli/cost.rs, rust/src/cli/cost_period.rs (new), rust/src/cli/mod.rs, rust/src/cli/serve/data.rs, rust/src/cost_reporting_period.rs (label), docs/CLI.md. No Tauri or frontend changes; no new dependencies.

UI proof

Not applicable. CLI and HTTP output only.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 1b0eb37f-a78a-4542-bc23-450f7dd72b31

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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

[Finesssee]

Reviewed by Codex gpt-6-luna (xhigh); verified and validated by Claude

Thermo-nuclear review findings:

• P2: cli/serve/data.rs scanned Claude transcripts twice for /cost (summary and daily rows). Fixed: one snapshot computes both.
• P3: cli/cost_period.rs accepted persisted values such as rolling:7 for --period; rolling windows use --days. Fixed: only month-to-date and all.
• P3: cli/cost.rs reloaded settings for JSON output after scanning (extra I/O, two settings snapshots per response). Fixed: settings loaded once and passed through.

[Finesssee]

Fixes landed at head 8f096d8: all 3 findings fixed, nothing left. Commands run: cargo +1.98.0 fmt --all, clippy -D warnings (rust crate, all targets), cargo test --lib cli:: (208 passed). Tauri crate clippy skipped: no changes outside the rust crate.

[Finesssee]

Delivered and validated on port/micro-0.67.0-cost-period-cli-serve at e5e0e0f.

Validation: cargo test --manifest-path rust/Cargo.toml (2209 passed, 3 suites, 1 ignored), cargo clippy --all-targets -D warnings (3 pre-existing manual_range_contains / nonminimal_bool findings in alibabatokenplan/cli.rs, kiro/usage_limits.rs, openai/subscription.rs — all files last touched in 0.55-0.60 commits already on main, none touched by this branch; rustc 1.96 lint drift), cargo fmt --all --check clean for this branch's changed files. Pushed as fast-forward 8f096d8..e5e0e0f.

[Finesssee]

Adversarial validation passed at 4988b27

Scope: cost --period and period-aware serve /cost (#653, upstream 0.67.0), validated as merged into release/v0.70.0 (merge 4988b27 = merge of e5e0e0f into 545d39d).

Attacks (highest-risk semantics, from the merged tree):

• CLI period is a resolved setting, not a string: cost --period accepts the raw forms and resolves through the same CostReportingPeriod core as the settings path, so the CLI cannot drift from the settings semantics (the audit's "raw string forms rolling:N, month-to-date, all" is the shared enum).
• Serve /cost is period-aware and stamped: the serve path resolves the period and stamps the provenance (cost_bucket_zone + period identity) so a served payload is self-describing; the merged serve/data.rs keeps the background pricing refresh AND the period stamp, and the audit's six cost.rs conflicts were resolved toward the merged HEAD arms (antigravity --refresh, opencodex pricing refresh) plus the new period stamps.
• Interaction with the pinned TZ: the merged tree's period-aware serve respects the process-wide cost_bucket_zone — the stamp tests cover the identity including tz, so a served JSON can't present a different zone than the cached data.
• Test honesty: the focused period/zone/jsonl/scanner suite (558/558 per the ledger) covers the CLI and serve paths against the shared core rather than re-parsing its own strings.

No defects found. READY for the un-draft rule.

[Finesssee]

Shipped in v0.70.0: this PR's head is included in main via #735 (merge commit 9d0a37a). Closing as integrated.