cctally 1.96.1 → 1.97.0

package/bin/_lib_pricing.py

@@ -53,7 +53,7 @@ def _chip_for_model(name: str) -> str:
 # Date the embedded pricing snapshots below were last verified against
 # vendor sources. Bump whenever CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING
 # is synced. Read by `pricing-check` + the release pre-flight staleness nudge.
-PRICING_SNAPSHOT_DATE = "2026-07-31"
+PRICING_SNAPSHOT_DATE = "2026-08-13"
 PRICING_STALENESS_DAYS = 60  # release pre-flight WARNs past this age
 
 # Canonical machine-readable pricing source (Claude values + Codex values).
@@ -68,25 +68,20 @@ LITELLM_PRICES_URL = (
 # Guarded by `stale_allowlist_entries` (tests/test_pricing_check.py): an entry
 # that no longer corresponds to a real divergence fails the suite.
 #
-# claude-sonnet-5 (#274): LiteLLM tracks the $2/$10-per-MTok *introductory* rate
-# (in effect through 2026-08-31); we deliberately embed the durable *standard*
-# $3/$15 rate because the table is date-blind and the promo expires soon (see
-# the CLAUDE_MODEL_PRICING note below). The non-vacuity guard forces these four
-# entries out once LiteLLM reverts to the standard rate post-cutover.
+# claude-mythos-preview (#560): Anthropic's Project Glasswing launch priced the
+# historical Preview at $25/$125 per MTok after its credit period. LiteLLM
+# currently mirrors successor Mythos 5's lower $10/$50 rate onto the Preview
+# identifier. Retained Preview rows therefore keep the explicit historical
+# rate rather than being rewritten to the successor's rate.
 PRICING_DRIFT_ALLOWLIST: list[dict] = [
     {
-        "model": "claude-sonnet-5",
+        "model": "claude-mythos-preview",
         "field": field,
-        # Structured cutover date (#279 S7 W7): the intro rate is in effect
-        # THROUGH 2026-08-31, so this suppression is valid through then and
-        # `expired_allowlist_entries` flags it the day after. Keep the prose in
-        # `reason`; the date here is what the offline expiry check + the cron read.
-        "expires": "2026-08-31",
         "reason": (
-            "LiteLLM tracks the claude-sonnet-5 introductory rate "
-            "($2/$10 per MTok, through 2026-08-31); we deliberately embed the "
-            "durable standard $3/$15 rate (the table is date-blind). Remove "
-            "once LiteLLM reverts post-cutover (#274)."
+            "Anthropic priced historical Claude Mythos Preview at $25/$125 "
+            "per MTok after its Project Glasswing credit period; LiteLLM "
+            "currently mirrors successor Mythos 5's $10/$50 rate onto the "
+            "Preview identifier (#560)."
         ),
     }
     for field in (
@@ -99,23 +94,19 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = [
 
 # Anthropic API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured/verified: 2026-07-28. PRICING_SNAPSHOT_DATE has since moved to
-#   2026-07-31 for the Codex-side gpt-5.6-terra/-luna correction (#441); these
-#   Claude values were NOT re-verified that day.
-# - Verified by maintainer against docs.claude.com/en/docs/about-claude/pricing;
-#   update in PRs touching this table.
+# - Captured/verified: 2026-08-13 against LiteLLM plus Anthropic's current
+#   pricing page and model launch pages.
+# - Vendor sources: https://platform.claude.com/docs/en/about-claude/pricing,
+#   https://www.anthropic.com/news/claude-sonnet-5,
+#   https://www.anthropic.com/news/claude-fable-5-mythos-5, and
+#   https://www.anthropic.com/glasswing. Update in changes touching this table.
 #   2026-06-10: added claude-fable-5 ($10/$50 per MTok; 1M context, no
 #   long-context premium) — issue #172.
-#   2026-07-01: added claude-sonnet-5 ($3/$15 per MTok; 1M context, flat-rate
-#   across the full window — no long-context premium, same shape as
-#   claude-sonnet-4-6). Embedded the STANDARD rate, not the $2/$10 introductory
-#   rate in effect through 2026-08-31, because the table is date-blind and
-#   $3/$15 is the durable post-cutover price.
-#   2026-07-06 (#274): LiteLLM published a sonnet-5 entry at the $2/$10
-#   introductory rate, so the deliberate standard-rate choice now surfaces as
-#   value_drift on all four cost fields. Suppressed via PRICING_DRIFT_ALLOWLIST
-#   above (the non-vacuity guard forces removal once LiteLLM reverts to the
-#   standard rate after 2026-08-31).
+#   2026-07-01 (#274, superseded by #560): initially added claude-sonnet-5 at
+#   the then-announced future $3/$15 standard rate, preferring it over the
+#   launch promotion because this table is date-blind. LiteLLM's $2/$10 row was
+#   temporarily suppressed on all four fields. Anthropic later cancelled that
+#   transition; the 2026-08-13 entry below records the replacement decision.
 #   2026-07-24: added claude-opus-5 ($5/$25 per MTok — identical to Opus
 #   4.5/4.6/4.7/4.8; $6.25 5-minute cache write and $0.50 cache read at the
 #   standard 1.25x/0.1x multipliers). 1M context at standard pricing, so NO
@@ -139,6 +130,12 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = [
 #   cache multipliers stack on the fast base rate. This snapshot bump is the
 #   pricing-fingerprint bust for safe conversation-rollup rederivation; durable
 #   journaled milestones and weekly snapshots are not rewritten.
+#   2026-08-13 (#560): Sonnet 5's $2/$10 launch pricing is now permanent, so
+#   replaced the cancelled $3/$15 rate and removed its four temporary drift
+#   suppressions. Added Mythos 5 at $10/$50 from Anthropic's launch/current
+#   pricing pages and historical Mythos Preview at the explicit $25/$125
+#   Project Glasswing rate. The snapshot bump re-arms the existing conversation
+#   rollup pricing fingerprint; immutable journaled/stored facts stay unchanged.
 # Anthropic prices a cache WRITE by TTL: 1.25x base input for a 5-minute write,
 # 2x for a 1-hour write; reads are 0.1x under both. Documented as applying
 # consistently across all supported models, so the 1h rate is DERIVED from
@@ -241,6 +238,18 @@ CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "cache_creation_input_token_cost": 1.25e-06,
         "cache_read_input_token_cost": 1e-07,
     },
+    "claude-mythos-5": {
+        "input_cost_per_token": 1e-05,
+        "output_cost_per_token": 5e-05,
+        "cache_creation_input_token_cost": 1.25e-05,
+        "cache_read_input_token_cost": 1e-06,
+    },
+    "claude-mythos-preview": {
+        "input_cost_per_token": 2.5e-05,
+        "output_cost_per_token": 1.25e-04,
+        "cache_creation_input_token_cost": 3.125e-05,
+        "cache_read_input_token_cost": 2.5e-06,
+    },
     "claude-opus-4-1": {
         "input_cost_per_token": 1.5e-05,
         "output_cost_per_token": 7.5e-05,
@@ -344,10 +353,10 @@ CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "cache_read_input_token_cost": 3e-07,
     },
     "claude-sonnet-5": {
-        "input_cost_per_token": 3e-06,
-        "output_cost_per_token": 1.5e-05,
-        "cache_creation_input_token_cost": 3.75e-06,
-        "cache_read_input_token_cost": 3e-07,
+        "input_cost_per_token": 2e-06,
+        "output_cost_per_token": 1e-05,
+        "cache_creation_input_token_cost": 2.5e-06,
+        "cache_read_input_token_cost": 2e-07,
     },
 }
 
@@ -389,9 +398,10 @@ _unknown_model_warnings: set[str] = set()
 # Codex (OpenAI) API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
 # - Captured: 2026-07-19 — the last FULL Codex sync. PRICING_SNAPSHOT_DATE has
-#   since moved for two targeted syncs (2026-07-24, the Claude-side opus-5 sync;
-#   2026-07-31, the gpt-5.6-terra/-luna correction logged below). Codex values
-#   outside those two corrections were NOT re-verified on those days.
+#   since moved for three targeted syncs (2026-07-24, the Claude-side opus-5
+#   sync; 2026-07-31, the gpt-5.6-terra/-luna correction logged below; and
+#   2026-08-13, the Claude-side Sonnet/Mythos sync above). Codex values outside
+#   the one Codex correction were NOT re-verified on those days.
 # - As of the 2026-07-19 sync this carries every openai-provider
 #   gpt-5* model the LiteLLM snapshot lists, so `pricing-check`'s scope finds
 #   nothing missing. Models absent from this table still fall back to `gpt-5`

package/bin/_lib_share.py

@@ -381,7 +381,7 @@ PALETTE_LIGHT = {
         "#dc2626",  # red-600
         "#0891b2",  # cyan-600
     ),
-    "ref_warn": "#d97706",           # amber-600
+    "ref_warn": "#b45309",           # amber-700
     "ref_alarm": "#dc2626",          # red-600
     "table_header_bg": "#f3f4f6",
     "table_row_alt": "#f9fafb",
@@ -903,7 +903,10 @@ def _render_bar_chart_svg(chart: BarChart, *, palette: dict,
                 seg_bot_y = iy + scale_y(y_running)
                 seg_h = seg_bot_y - seg_top_y
                 color = series_palette[k_idx % len(series_palette)]
-                elements.append(svg_rect(bx, seg_top_y, bar_w, seg_h, fill=color))
+                elements.append(svg_rect(
+                    bx, seg_top_y, bar_w, seg_h,
+                    fill=color, stroke=palette["bg"],
+                ))
                 y_running += seg_v
         else:
             by = iy + scale_y(p.y_value)
@@ -1965,7 +1968,9 @@ def _merge_inventories(
 # original project labels.
 #
 # Half two — unambiguous classes, scanned document-wide. Only identifier
-# classes that cannot plausibly occur as legitimate artifact content.
+# classes that cannot plausibly occur as legitimate artifact content. The two
+# reveal-basename exceptions are masked at typed project sites before the
+# complete document reaches this unchanged detector, then restored afterward.
 #
 # Original project labels are deliberately NOT in half two. A project
 # legitimately named `cctally` collides with the static branding string this
@@ -2177,11 +2182,10 @@ def _scan_forbidden_classes(text: str) -> "list[tuple[str, str]]":
     """Return `(class label, matched value)` per unambiguous class in `text`.
 
     The matched value is carried out of the scan, not just the class name.
-    Naming only the class leaves the user nothing to act on: the accepted
-    limitation in `docs/share-gotchas.md` is that a project whose basename is
-    itself a canonical UUID or a 32-character hex token cannot be rendered in
-    reveal mode, and "canonical UUID" alone does not tell that user which of
-    their directories to rename.
+    Naming only the class leaves the user nothing to act on when an untyped
+    field leaks a value. The narrow reveal-basename exception is handled by
+    provenance-aware masking before a complete document reaches this scanner;
+    direct scanner calls remain fail-closed.
     """
     findings: list[tuple[str, str]] = []
     match = _UUID_RE.search(text)
@@ -2238,11 +2242,12 @@ def _verify_output(
     handler's exception converter turns it into the generic 500 envelope and
     the CLI converts it to a stderr refusal and exit 3.
 
-    Takes NO privacy mode. Both halves are mode-independent — half one
-    compares against the allowlist preparation itself built under whichever
-    mode was asked for, and half two's classes are forbidden in reveal mode
-    too, because reveal discloses a project's basename and never its path.
-    The parameter existed and was read by nothing.
+    Takes NO privacy mode. Both halves are mode-independent — half one compares
+    against the allowlist preparation itself built under whichever mode was
+    asked for, while the entry points mask the two provenance-qualified reveal
+    basename shapes before calling this unchanged document-wide detector. A
+    direct call still rejects every forbidden class. The former mode parameter
+    was read by nothing.
     """
     # Half one — provenance. Every project display value the prepared snapshot
     # carries must be one preparation was allowed to write. This catches a
@@ -2280,6 +2285,127 @@ def _verify_output(
             )
 
 
+def _reveal_basename_token(label: str) -> "str | None":
+    """Return the narrowly exemptible token from one raw project label.
+
+    The exception is for a directory whose BASENAME is exactly a UUID or a
+    source-root-shaped token. A label that merely contains either shape is not
+    eligible. Parent qualifiers added later by `disambiguate_basenames` do not
+    broaden this decision because eligibility is derived from the raw label.
+    """
+    segments = _path_segments(label)
+    basename = segments[-1] if segments else label
+    if _UUID_RE.fullmatch(basename) or _SOURCE_ROOT_KEY_RE.fullmatch(basename):
+        return basename
+    return None
+
+
+def _width_safe_hex_mask(token: str, ordinal: int) -> str:
+    """Build a detector-safe token that never under-reserves SVG width.
+
+    Helvetica's ``g``/``h`` are each 556 units wide: equal to digits and at
+    least as wide as every lowercase hex letter. ``H``/``N`` are each 722
+    units wide, at least as wide as every uppercase hex letter. Hyphens retain
+    their real width. The binary ordinal makes equal-shaped UUID/source-root
+    masks unique without introducing another hexadecimal run. NUL sentinels
+    keep the placeholder distinct from every ordinary renderer string; they
+    exist only in the intermediate Python value and add safe width headroom.
+    """
+    chars = [
+        char if char == "-" else ("H" if char.isupper() else "g")
+        for char in token
+    ]
+    slots = [index for index, char in enumerate(chars) if char != "-"]
+    bits = f"{ordinal + 1:b}"
+    for index, bit in zip(reversed(slots), reversed(bits)):
+        if token[index].isupper():
+            chars[index] = "N" if bit == "1" else "H"
+        else:
+            chars[index] = "h" if bit == "1" else "g"
+    return "\x00" + "".join(chars) + "\x00"
+
+
+def _mask_reveal_basename_mapping(
+    snaps: "Sequence[ShareSnapshot]",
+    mapping: "dict[_ProjectAnonKey, str]",
+    *,
+    reveal_projects: bool,
+    reserved_strings: "Sequence[str]" = (),
+) -> "tuple[dict[_ProjectAnonKey, str], tuple[tuple[str, str], ...]]":
+    """Mask only provenance-qualified UUID/hex basenames before rendering.
+
+    This is deliberately a mapping transformation, not a document allowlist.
+    Untyped fields retain their bytes and therefore remain visible to the
+    unchanged document-wide detector. The returned substitutions are applied
+    only after that detector accepts the complete document.
+    """
+    if not reveal_projects:
+        return mapping, ()
+
+    raw_tokens: dict[_ProjectAnonKey, set[str | None]] = {}
+    reserved: set[str] = set(mapping.values()) | set(reserved_strings)
+    for snap in snaps:
+        def _record_token(site: _ProjectDisplaySite) -> "str | None":
+            if site.keyed and site.value:
+                key = _project_anon_key(site.value, site.identity)
+                raw_tokens.setdefault(key, set()).add(
+                    _reveal_basename_token(site.value))
+            return site.value
+
+        # Visit every typed site directly. `_project_label_by_key` is a display
+        # helper and intentionally keeps only the first label per identity;
+        # security eligibility must instead hear every raw label.
+        _map_project_display(snap, _record_token)
+        _walk_strings(snap, reserved, set())
+
+    eligible_by_key: dict[_ProjectAnonKey, str] = {}
+    eligible: dict[str, str] = {}
+    for key, displayed in mapping.items():
+        candidates = raw_tokens.get(key, set())
+        token = next(iter(candidates)) if len(candidates) == 1 else None
+        if token is not None and token in displayed:
+            eligible_by_key[key] = token
+            eligible.setdefault(token, "")
+    if not eligible:
+        return mapping, ()
+
+    substitutions: list[tuple[str, str]] = []
+    ordinal = 0
+    for token in sorted(eligible):
+        while True:
+            placeholder = _width_safe_hex_mask(token, ordinal)
+            ordinal += 1
+            if all(placeholder not in value for value in reserved):
+                break
+        eligible[token] = placeholder
+        substitutions.append((placeholder, token))
+        reserved.add(placeholder)
+
+    masked: dict[_ProjectAnonKey, str] = {}
+    for key, displayed in mapping.items():
+        token = eligible_by_key.get(key)
+        placeholder = eligible.get(token or "")
+        masked[key] = (
+            displayed.replace(token, placeholder, 1)
+            if token is not None and placeholder is not None
+            else displayed
+        )
+    return masked, tuple(substitutions)
+
+
+def _verify_and_restore_reveal_basenames(
+    text: str,
+    *,
+    inventory: SensitiveInventory,
+    substitutions: "Sequence[tuple[str, str]]",
+) -> str:
+    """Verify the masked complete document, then restore approved basenames."""
+    _verify_output(text, inventory=inventory)
+    for placeholder, token in substitutions:
+        text = text.replace(placeholder, token)
+    return text
+
+
 def _encode_probe_identity_key() -> str:
     """A syntactically valid IdentityV1 key, for the detector's own tests.
 
@@ -3633,7 +3759,7 @@ def _print_stylesheet() -> str:
 
     THE DATA COLOURS ARE MAPPED TOO (#503 S2 review F1/F2), because they
     are not legible on white: dark `ref_warn` #fbbf24 measures 1.67:1
-    where its light counterpart #d97706 measures 3.19:1, dark `ref_alarm`
+    where its light counterpart #b45309 measures 5.02:1, dark `ref_alarm`
     #f87171 measures 2.77:1 against 4.83:1, and dark `series_primary`
     #60a5fa measures 2.54:1 against 5.17:1. A reference LABEL is mapped
     alongside its LINE, so the colour that encodes severity stays paired;
@@ -3708,18 +3834,20 @@ def _print_stylesheet() -> str:
     """
     light = PALETTE_LIGHT
     dark = PALETTE_DARK
-    # Data roles, mapped index-wise so a re-picked palette stays paired.
-    data_pairs = [(dark[role], light[role])
-                  for role in ("series_primary", "series_secondary",
-                               "ref_warn", "ref_alarm")]
-    data_pairs += list(zip(dark["series_palette"], light["series_palette"]))
-    seen: set = set()
+    # Fill and stroke roles are mapped separately. A dark source value may
+    # intentionally mean different things in those channels: #fbbf24 is both
+    # the warning stroke/text and the fourth stacked-series fill, whose light
+    # counterparts are #b45309 and #d97706 respectively (#524). Deduplicating
+    # them in one value-only map silently assigns one role the other's target.
+    fill_pairs = [(dark[role], light[role])
+                  for role in ("series_primary", "series_secondary")]
+    fill_pairs += list(zip(dark["series_palette"], light["series_palette"]))
     fills = []
-    strokes = []
-    for dark_value, light_value in data_pairs:
-        if dark_value in seen:
+    fill_seen: set = set()
+    for dark_value, light_value in fill_pairs:
+        if dark_value in fill_seen:
             continue
-        seen.add(dark_value)
+        fill_seen.add(dark_value)
         # `rect` is the only element this kernel currently fills with a
         # data colour, but `path` and `polyline` are filled elements too,
         # so a future filled area chart would otherwise print dark. Named
@@ -3730,6 +3858,16 @@ def _print_stylesheet() -> str:
             f' svg path[fill="{dark_value}"],'
             f' svg polyline[fill="{dark_value}"]'
             f' {{ fill: {light_value} !important; }}')
+
+    stroke_pairs = [(dark[role], light[role])
+                    for role in ("series_primary", "series_secondary",
+                                 "ref_warn", "ref_alarm")]
+    strokes = []
+    stroke_seen: set = set()
+    for dark_value, light_value in stroke_pairs:
+        if dark_value in stroke_seen:
+            continue
+        stroke_seen.add(dark_value)
         strokes.append(
             f' svg line[stroke="{dark_value}"] {{ stroke: {light_value} !important; }}'
             f' svg polyline[stroke="{dark_value}"] {{ stroke: {light_value} !important; }}'
@@ -3996,8 +4134,9 @@ def compose(sections: tuple[ComposedSection, ...], *, opts: ComposeOptions) -> s
 
     The second complete-document boundary that owns the privacy contract
     (#503 S1). `sections` must carry RAW snapshots: `compose()` prepares them
-    itself under `opts.reveal_projects`, stitches, and then verifies the whole
-    composed document. Callers must not pre-scrub — a pre-scrubbed section
+    itself under `opts.reveal_projects`, stitches, verifies the whole composed
+    document, and only then restores provenance-qualified reveal basenames.
+    Callers must not pre-scrub — a pre-scrubbed section
     reaching a second aliasing pass merges two distinct projects that each
     mapped locally to `project-1` into one alias.
     """
@@ -4009,10 +4148,15 @@ def compose(sections: tuple[ComposedSection, ...], *, opts: ComposeOptions) -> s
     # a handler-only fix would miss the CLI `source=all` path.
     merged = _merged_project_mapping(
         [sec.snap for sec in sections], reveal_projects=opts.reveal_projects)
+    render_mapping, reveal_substitutions = _mask_reveal_basename_mapping(
+        [sec.snap for sec in sections], merged,
+        reveal_projects=opts.reveal_projects,
+        reserved_strings=(opts.title,),
+    )
     prepared = tuple(
         ComposedSection(
             snap=_prepare(sec.snap, reveal_projects=opts.reveal_projects,
-                          mapping=merged),
+                          mapping=render_mapping),
             drift_detected=sec.drift_detected,
         )
         for sec in sections
@@ -4040,10 +4184,13 @@ def compose(sections: tuple[ComposedSection, ...], *, opts: ComposeOptions) -> s
         body = _stitch_svg(prepared, opts=opts)
     else:
         raise ValueError(f"unknown format: {fmt!r}")
-    _verify_output(body, inventory=_merge_inventories([
-        (raw.snap, out.snap) for raw, out in zip(sections, prepared)
-    ]))
-    return body
+    return _verify_and_restore_reveal_basenames(
+        body,
+        inventory=_merge_inventories([
+            (raw.snap, out.snap) for raw, out in zip(sections, prepared)
+        ]),
+        substitutions=reveal_substitutions,
+    )
 
 
 def _stitch_html(sections: tuple[ComposedSection, ...], *,
@@ -4255,8 +4402,8 @@ def render(snap: ShareSnapshot, *, format: str, theme: str, branding: bool,
     responsible for emitting the result (stdout/file/clipboard/open).
 
     One of the two complete-document boundaries that own the privacy contract
-    (#503 S1). It runs inventory -> prepare -> render -> verify. The gate goes
-    here and in `compose()`, not in `_render_fragment` and not in
+    (#503 S1). It runs inventory -> prepare/mask -> render -> verify -> restore.
+    The gate goes here and in `compose()`, not in `_render_fragment` and not in
     `_wrap_document`, because composition bypasses the latter and a fragment
     is not a complete document.
 
@@ -4270,11 +4417,19 @@ def render(snap: ShareSnapshot, *, format: str, theme: str, branding: bool,
     snapshot renumbers aliases on the legacy path, so preparation refuses it.
     """
     inventory_source = snap
-    prepared = _prepare(snap, reveal_projects=reveal_projects)
+    resolved = _resolved_project_labels(
+        snap, reveal_projects=reveal_projects)
+    render_mapping, reveal_substitutions = _mask_reveal_basename_mapping(
+        [snap], resolved, reveal_projects=reveal_projects)
+    prepared = _prepare(
+        snap, reveal_projects=reveal_projects, mapping=render_mapping)
     out = _render_prepared(prepared, format=format, theme=theme,
                            branding=branding)
-    _verify_output(out, inventory=_inventory_for(inventory_source, prepared))
-    return out
+    return _verify_and_restore_reveal_basenames(
+        out,
+        inventory=_inventory_for(inventory_source, prepared),
+        substitutions=reveal_substitutions,
+    )
 
 
 def _render_prepared(snap: ShareSnapshot, *, format: str, theme: str,

package/bin/cctally

@@ -1864,7 +1864,34 @@ def _sum_cost_for_range(
     by the per-account ``sync-week`` cost materialization + per-account budget
     ladders so a snapshot / budget carries genuinely per-account cost.
     """
+    return _sum_cost_and_tokens_for_range(
+        start, end, mode, project, skip_sync=skip_sync, account_key=account_key,
+    )[0]
+
+
+def _sum_cost_and_tokens_for_range(
+    start: dt.datetime,
+    end: dt.datetime,
+    mode: str = "auto",
+    project: str | None = None,
+    *,
+    skip_sync: bool = False,
+    account_key: "str | None" = None,
+) -> "tuple[float, int]":
+    """Sum USD cost and #104 total tokens over ONE walk of the same entries.
+
+    #556 S1 §3.3. The two halves must describe the SAME entry set, so they are
+    accumulated together rather than by a second read: a separate read runs on
+    another connection with its own end-boundary semantics and can legitimately
+    disagree with this one.
+
+    Tokens follow the #104 convention (`input + output + cache_create +
+    cache_read`). `cache_creation_1h_input_tokens` is deliberately absent — it
+    is a TTL SUBDIVISION of `cache_creation_input_tokens` (#195), so adding it
+    would double-count every 1-hour cache write.
+    """
     total = 0.0
+    tokens = 0
     for entry in get_entries(start, end, project=project, skip_sync=skip_sync,
                              account_key=account_key):
         total += _calculate_entry_cost(
@@ -1873,7 +1900,14 @@ def _sum_cost_for_range(
             mode=mode,
             cost_usd=entry.cost_usd,
         )
-    return total
+        usage = entry.usage
+        tokens += (
+            int(usage.get("input_tokens", 0) or 0)
+            + int(usage.get("output_tokens", 0) or 0)
+            + int(usage.get("cache_creation_input_tokens", 0) or 0)
+            + int(usage.get("cache_read_input_tokens", 0) or 0)
+        )
+    return total, tokens
 
 
 def _bridge_z_into_tz(args: argparse.Namespace,