feat(statusline): add current-month total cost placeholder

[Brusdeylins]

Summary

Adds a new %Y statusline placeholder showing the cumulative cost (USD) across all Claude Code sessions of the current calendar month — complementing %X, which only reflects the current session (cost.total_cost_usd).

Example: ∑ month: $1223.47

Data source & pricing

Claude Code's local session transcripts (~/.claude/projects/**/*.jsonl, honoring CLAUDE_CONFIG_DIR) — the same source ccusage uses. These logs carry no precomputed costUSD field, so cost is computed from each entry's message.usage token counts × per-model price:

• input + output tokens, plus cache tokens: read 0.1×, 5-minute write 1.25×, 1-hour write 2× of the model's input price.
• Prices cross-checked against the LiteLLM model_prices_and_context_window.json table (Opus 4.x $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5 per 1M).
• Only entries of the current month (local time) are summed; duplicate messages (same id+requestId across session logs, e.g. after resume/fork) are de-duplicated.

Note on accuracy vs. ccusage: ccusage prices all cache_creation_input_tokens at the flat 1.25× rate (it doesn't read LiteLLM's cache_creation_input_token_cost_above_1hr). This implementation splits the cache_creation.ephemeral_5m/ephemeral_1h breakdown and charges 1-hour cache writes at 2× — matching Anthropic's real billing and LiteLLM's above_1hr value, so it is more accurate than ccusage for Claude Code traffic (which uses 1-hour caching heavily). No current Claude model carries a >200k long-context premium, so per-request token tiering is intentionally omitted.

Performance (non-blocking)

The statusline renders very frequently, and a full transcript scan takes ~1.5s. So the scan never runs in the render path:

• The result is cached in the temp directory (MonthCostCache: month/cost/timestamp).
• A render serves the last cached value immediately; when the cache is missing, stale, or from a previous month, it spawns a detached background process (ase statusline --refresh-month-cost) that recomputes and rewrites the cache. The next render picks up the fresh value.
• TTL is configurable via --month-cost-ttl <seconds> (default 300).
• Whole files not modified this month are stat-skipped to keep the scan bounded.

Robustness

Missing/empty logs, unreadable files, malformed JSON lines, and unknown models all degrade gracefully — the placeholder simply renders nothing, never an error.

Verification

• npm --prefix tool start build — lint + tsc green.
• Unit-level, synthetic JSONL in a temp CLAUDE_CONFIG_DIR: hand-computed total $0.17725 matched computeMonthCost() to 1e-9, exercising the 5m/1h cache split, month filtering (previous-month entry excluded), dated model-id suffix resolution, unknown/<synthetic> model skipped, no-usage line skipped, and cross-file de-duplication.
• End-to-end CLI: --refresh-month-cost writes the cache; %Y then renders ∑ month: $0.18; %X %Y render side by side; empty logs suppress %Y.
• Real data: rendered $1223.47 for the current month against the local transcript archive; confirmed the render reads the cache (fast) rather than scanning.

Docs

%Y, its data source, caching behavior, and --month-cost-ttl are documented in docs/usage-tool.md; the statusline argument hint lists %Y.

🤖 Generated with Claude Code

[rse]

Here need a blank line, I think. It is very confusing that the tmux stuff is at the end of the %Y stuff.

[rse]

This both can become a maintenance issue (when new models occur or prices change) and does not support any models in Github Copilot.

[rse]

Really under the OS temp directory like /tmp or $TMPDIR? I would have expected ~/.ase/xxx or something like this but not the temp directory.

[rse]

At least here we would have to check the "agent harness": "claude" vs. "copilot". For copilot this at least should expand to the empty string or perhaps even "N.A." or something like this.