feat(ai_review): fmt_tokens() humanizes token counts

tests/pilot/test_ai_review.py

@@ -18,6 +18,7 @@ from ai_review import (  # noqa: E402
     build_user_prompt,
     compute_attribution,
     findings_table,
+    fmt_tokens,
     format_review_body,
     inline_comment_body,
     parse_diff_anchors,
@@ -1629,3 +1630,41 @@ def test_render_collapsible_usage_omits_lenses_when_single_primary():
     out = _render_collapsible_usage(usage, "headroom/glm-5.2:cloud", None)
     assert "Lenses" not in out
 
+
+# ---------------------------------------------------------------------------
+# fmt_tokens
+# ---------------------------------------------------------------------------
+
+
+def test_fmt_tokens_zero():
+    assert fmt_tokens(0) == "0"
+
+
+def test_fmt_tokens_small_no_short():
+    assert fmt_tokens(42) == "42"
+    assert fmt_tokens(999) == "999"
+
+
+def test_fmt_tokens_thousands():
+    assert fmt_tokens(1000) == "1,000 (1.0K)"
+    assert fmt_tokens(1234) == "1,234 (1.2K)"
+    assert fmt_tokens(9999) == "9,999 (10.0K)"
+
+
+def test_fmt_tokens_millions():
+    assert fmt_tokens(1_000_000) == "1,000,000 (1.0M)"
+    assert fmt_tokens(2_071_025) == "2,071,025 (2.1M)"
+    assert fmt_tokens(1_234_567) == "1,234,567 (1.2M)"
+
+
+def test_fmt_tokens_billions():
+    assert fmt_tokens(1_234_567_890) == "1,234,567,890 (1.2B)"
+
+
+def test_fmt_tokens_none():
+    assert fmt_tokens(None) == "?"
+
+
+def test_fmt_tokens_negative():
+    assert fmt_tokens(-1) == "?"
+