fix(claude): surface desktop usage diagnostics

[IvGolovach]

Summary

Closes #558 by making Claude Desktop detection explicit without fabricating token totals from undocumented local app storage.

This PR adds Claude diagnostics to tokscale clients and to explicit empty tokscale models --client claude --json reports when Claude Desktop app data is present but only Claude Code JSONL usage roots are scannable. It also documents the boundary between Claude Code local usage, Claude Desktop consumer chat data, tokscale usage quota bars, and Anthropic Admin Usage/Cost APIs.

Why

Claude Code usage is countable when local JSONL assistant messages include structured message.usage metadata. Claude Desktop consumer chat storage and Claude data exports do not expose a documented stable per-message token ledger, so importing Desktop app data as usage would risk silently fabricated totals. The better behavior is to tell users what Tokscale found, what it scanned, and why Desktop chat usage is not counted as a local transcript source.

Docs checked: Claude Code costs, Claude data export, Usage and Cost Admin API, and Claude pricing.

Diff scope

• Add a Claude diagnostics module that detects known Claude Desktop storage locations on macOS, Windows-style home directories, and Linux-style config directories.
• Surface claude_desktop_not_scanned diagnostics in tokscale clients JSON/text output and in explicit empty Claude model reports.
• Keep stats-cache.json out of session imports and report it as informational because it is aggregate data without stable per-message/session attribution.
• Add an Opus 4.7 Claude parser regression proving usage-bearing JSONL still counts tokens and provider attribution correctly.
• Guard future Claude Opus 4.x minor model IDs from degrading to legacy claude-opus-4 pricing while preserving valid same-minor fuzzy/date fallback behavior.
• Update README to document the Claude Code versus Claude Desktop versus Anthropic Admin API boundary.

Branch integrity

Base branch: main.

Validated base SHA: fcab5fbda431dfe6efd76660e6bb44c45d2d32e1.

Ahead/behind against fetched origin/main: 0 behind / 1 ahead.

Merge-base SHA: fcab5fbda431dfe6efd76660e6bb44c45d2d32e1.

Fast-forward safety: origin/main is an ancestor of this branch, and the PR diff was computed against the fetched base.

Commit integrity

Introduced commit: 6f0480ed9d898a30d2575ef904dcadabb3af7563 fix(claude): surface desktop usage diagnostics.

The PR contains one logical change. The final diff contains only Claude diagnostics, Claude README notes, Claude parser regression coverage, and pricing resolver coverage needed for the same Claude usage-reporting issue.

Diff hygiene

Changed files:

M README.md
A crates/tokscale-cli/src/claude_diagnostics.rs
M crates/tokscale-cli/src/main.rs
M crates/tokscale-cli/tests/cli_tests.rs
M crates/tokscale-core/src/pricing/lookup.rs
M crates/tokscale-core/src/sessions/claudecode.rs

git diff --check origin/main...HEAD: PASS, no output.

Validation mode and proof

Validation mode: Mode 3 — shared runtime pricing resolver plus CLI report diagnostics.

Local validation:

cargo fmt --all -- --check: PASS
cargo test -p tokscale-cli claude_desktop_diagnostic: PASS, 3 tests
cargo test -p tokscale-cli models: PASS, 44 tests
cargo test -p tokscale-cli clients: PASS, 24 tests
cargo test -p tokscale-core opus_4: PASS, 12 tests
cargo test -p tokscale-core claude: PASS, 70 tests
cargo test -p tokscale-core pricing::lookup::tests: PASS, 137 tests
/opt/homebrew/Cellar/rust/1.94.0/bin/cargo-clippy clippy -p tokscale-cli --all-targets -- -D warnings: PASS
/opt/homebrew/Cellar/rust/1.94.0/bin/cargo-clippy clippy -p tokscale-core --all-targets -- -D warnings: PASS
git diff --check origin/main...HEAD: PASS

Full workspace test suite: not run locally because targeted CLI/core tests cover the changed surfaces and required remote CI will validate the final PR SHA.

Ledger and version proof

Ledger: not applicable — not required for this change family.

Version: not applicable — no release manifests changed; repository release workflow owns version bumps.

Migration notes

Not applicable — no database migration changed.

CI context confirmation

Pending — required GitHub Actions checks will run after the PR is opened.

CI context names unchanged.

Runtime safety

No database writes, auth changes, network sync behavior, queues, migrations, or submission semantics changed.

No invariant regression introduced.

Documentation integrity

README now documents that claude is Claude Code token accounting, not consumer Claude Desktop chat accounting, and explains where tokscale usage and Anthropic Admin Usage/Cost APIs fit.

Rollback plan

Rollback: revert this PR.

DB downgrade: not applicable.

Data repair: not applicable.

Operational caveats: none known.

Known residual risks

This PR does not claim to count Claude Desktop consumer chat tokens. It intentionally avoids doing so until Anthropic exposes a stable, documented per-message token ledger or official personal usage export/API for that surface.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
tokscale	Ignored	Preview	May 31, 2026 10:15pm

[cubic-dev-ai]

No issues found across 6 files

_{Re-trigger cubic}