fix(stats): accept UUID task IDs in cf stats --task (#744)

[frankbria]

Closes #744

Problem

v2 task IDs are UUID strings, but cf stats tokens --task and cf stats export --task typed the --task option as Optional[int]. Typer rejected any real v2 UUID at coercion time (is not a valid integer, exit 2), so per-task cost/token reporting and export were broken for every v2 task.

Fix

Type-only widening — no logic change:

• stats_commands.py: tokens() / export_data() --task → Optional[str]
• token_repository.py: get_task_token_summary / get_batch_token_usage → Union[int, str]
• metrics_tracker.py: get_task_token_summary passthrough → Union[int, str]

token_usage.task_id is already TEXT (schema_manager.py:172), so UUID rows round-trip unchanged; SQLite ?-binding never cared about the annotation. The break was purely Typer's int coercion.

Acceptance criteria (from #744)

• --task is str; get_task_token_summary/get_batch_token_usage accept Union[int, str]
• cf stats tokens --task <uuid> returns a saved UUID-keyed row

Tests

tests/cli/test_stats_task_uuid.py (new):

• cf stats tokens --task <uuid> → exit 0, correct totals (was exit 2 pre-fix)
• cf stats export --task <uuid> → writes the UUID-keyed record
• repository get_task_token_summary(<uuid>) → aggregated row

Verified live end-to-end: cf stats tokens --task <uuid> and cf stats export both render/export the saved UUID-keyed row. All 32 tests across changed modules pass; ruff clean.

Known limitations

• None. Legacy int task IDs still work (widened, not replaced).
• CLI docstring examples still show --task 1 (a valid str) — left as-is.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 47 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 21fd0490-66b7-4700-8ce7-66fb43c9ca2b

📥 Commits

Reviewing files that changed from the base of the PR and between dbcc7ec and 3e637ec.

📒 Files selected for processing (4)

• codeframe/cli/stats_commands.py
• codeframe/lib/metrics_tracker.py
• codeframe/platform_store/repositories/token_repository.py
• tests/cli/test_stats_task_uuid.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/744-stats-task-uuid

---

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Review

Clean, minimal type-widening fix — no logic changes, and it's consistent with how TokenUsage.task_id already handles Union[int, str] in codeframe/core/models.py:685 (v2 UUID strings vs. legacy int task IDs). Confirmed:

• token_usage.task_id is TEXT in the schema (schema_manager.py:172), so both int and str bind fine — this widening doesn't change runtime behavior, only removes Typer's premature int coercion at the CLI boundary.
• Traced all callers of get_task_token_summary / get_batch_token_usage (metrics_tracker.py, stats_commands.py, database.py passthrough) — none assume int-only behavior, so nothing else breaks.
• No prior reviews/comments to reconcile with (CodeRabbit hit its rate limit and produced no actual review content on this PR).

No bugs found. One trivial, non-blocking nit: the Returns docstring for get_task_token_summary (token_repository.py:176) still says "task_id": int — now stale since it can be a UUID string too. Not worth a follow-up commit on its own, just flagging for whenever that docstring is next touched.

Test coverage is solid for the fix's scope: CLI exit-code regression (tokens/export), and a repository-level UUID round-trip check. Good call locking in the pre-fix failure mode (exit 2) as the regression being guarded against.