cctally 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.13.0] - 2026-05-25
+
+### Added
+- **Every Claude reporting command now accepts the `ccusage` flag surface, so `ccusage <cmd> [flags]` invocations paste into `cctally` unchanged.** Across all 10 reporting subcommands (`daily`, `monthly`, `weekly`, `session`, `blocks`, `five-hour-blocks`, `project`, `diff`, `range-cost`, `cache-report`): `-z`/`--timezone` aliases the existing `--tz`; the 8 date-taking commands accept `--since`/`--until` in both `YYYY-MM-DD` and `YYYYMMDD` forms; `--compact` forces compact table layout; `--color`/`--no-color` (plus the `NO_COLOR` / `FORCE_COLOR` env vars) control ANSI on the color-emitting commands (`project`, `diff`) and are accepted-but-inert elsewhere; and `-O`/`--offline`, `--single-thread`, `-d`/`--debug`, and `--config` are accepted as documented no-ops where cctally has no divergent behavior. A top-level `-v` short alias for `--version` is also added. The pass is purely additive — no existing output changes. (#86)
+- **`cctally session` gains `-i`/`--id <session-id>` to filter to a single session.** Exact-string match against the post-resume-merge `sessionId`; an unknown id renders empty and exits 0. (#86)
+- **`--config <path>` is now a real per-invocation config override.** Previously a documented no-op from the flag-alias pass, `--config` now loads configuration from the given path for that invocation only, leaving the persisted `~/.local/share/cctally/config.json` untouched. (#88)
+- **`-d`/`--debug` now emits a real "Pricing Mismatch Debug Report" on stderr for the Claude reporting commands.** The report compares each entry's recorded `costUSD` against the token-recomputed cost, surfacing totals + per-model stats + a sample of the largest discrepancies, matching ccusage's `printMismatchReport` shape. `--debug-samples N` caps the sample block (default 5; `N=0` prints totals only; negative N rejected at parse time). The report goes to stderr only — `--json` / `--format` pipelines stay byte-stable — and `diff` emits one report per window. (#89)
+- **`--compact` now reshapes output on the 5 reporting commands where it was previously accepted-but-inert: `five-hour-blocks`, `project`, `diff`, `range-cost`, and `cache-report`.** Brings them in line with the commands that already honored `--compact`. (#91)
+- **`codex-daily` / `codex-monthly` / `codex-weekly` / `codex-session` now accept `-d/--debug` + `--debug-samples N`**, extending the Claude-side `--debug` diagnostic surface to the Codex commands. Because Codex JSONL records no `costUSD` to diff against, the report is a Codex variant — a "Codex Pricing Debug Report" on stderr with totals (entries processed, models seen, total computed cost) plus a "Sample Top Entries" block of the N highest computed-cost entries (`Recorded cost: (none)` per sample; `gpt-5`-fallback models tagged `(fallback→gpt-5)`). `--debug-samples` caps the sample block (default 5; `N=0` prints totals only). (#92)
+
+### Fixed
+- **`project --compact` and `session --compact` no longer corrupt numeric values or overflow the terminal on narrow widths.** The header-width column floor added to fix box misalignment had two flip-side bugs on sub-fit terminals: (A) any cell wider than its column was ellipsis-truncated — including numeric columns, so a token count like `12,345,678` rendered as the silently-wrong `12,345,…`; and (B) when the header floors summed past the available width nothing shrank them, so the box drew WIDER than the terminal. The scale-down policy is now: numeric (right-aligned) columns are floored at their full value width and are never ellipsis-truncated (a wrong number is worse than honest overflow), while text columns — and their header labels, which now truncate the same way data cells do — absorb the squeeze so the table fits when the numbers allow and stays box-aligned when they don't. Shared `_scale_down_col_widths` + `_ellipsize` helpers centralize the policy across both renderers. The codex session renderer is intentionally left as-is (ccusage/codex parity). Regression: `tests/test_compact_rendering.py` (numeric-never-truncated + box-fits + unit coverage); project goldens regenerated. (#102)
+- **`cache-report --since/--until` again accept space-separated datetimes (`'2026-05-01 12:30:00'`) and ISO week-dates (`2026-W18-1`).** The Session A dual-form refactor replaced cache-report's date-only fallthrough with a parser that rejects anything other than `YYYY-MM-DD` / `YYYYMMDD`, silently dropping the other forms that `datetime.fromisoformat` (and the pre-refactor code) accepted — they now failed with `--since must be YYYY-MM-DD or YYYYMMDD format`. The `parse_iso_datetime` second-chance is restored for inputs the dual-form parser rejects; a full datetime is used verbatim (no `--until` end-of-day rounding), matching the old behavior. Genuinely invalid input (e.g. `26-01-01`) still surfaces the clearer centralized `YYYY-MM-DD or YYYYMMDD` diagnostic rather than the generic ISO message, and the dual-form parse is attempted silently so a successful second-chance never leaks a spurious error line to stderr. cache-report is the only date command with this leniency; `daily` / `monthly` / `weekly` / `blocks` accept the two canonical forms only. Regression: `tests/test_cache_report_since_until_fallthrough.py`. (#101)
+- **`diff` and `project` no longer emit ANSI color into a piped or redirected stdout when `CI` is set.** The `--color` resolver placed its `CI` rung above the `stdout.isatty()` check, so on a CI runner `cctally diff … | cat` (or `> out.txt`) wrote raw escape sequences into the capture — a behavior change from the pre-Session-A contract, which keyed color on `sys.stdout.isatty()` alone and always produced clean text on a pipe. The `CI` rung is now gated behind `sys.stdout.isatty()`: CI still forces color on a real terminal (over a dumb `TERM`, matching picocolors), but a non-TTY stdout stays plain text regardless of `CI`. `FORCE_COLOR` / `NO_COLOR` / `--color` / `--no-color` precedence is unchanged. Regression: `tests/test_color_resolution.py::test_ci_with_piped_stdout_stays_uncolored` + `::test_ci_with_tty_stdout_enables`. (#100)
+
 ## [1.12.0] - 2026-05-24
 
 ### Fixed

package/bin/_cctally_cache.py

@@ -661,7 +661,7 @@ def sync_cache(
             try:
                 with open(jp, "r", encoding="utf-8", errors="replace") as fh:
                     fh.seek(start_offset)
-                    for offset, entry, msg_id, req_id in _iter_jsonl_entries_with_offsets(fh):
+                    for offset, entry, msg_id, req_id in _iter_jsonl_entries_with_offsets(fh, str(jp)):
                         usage = entry.usage
                         inp = int(usage.get("input_tokens", 0) or 0)
                         out = int(usage.get("output_tokens", 0) or 0)
@@ -839,7 +839,8 @@ def iter_entries(
 
     sql = (
         "SELECT timestamp_utc, model, input_tokens, output_tokens, "
-        "cache_create_tokens, cache_read_tokens, usage_extra_json, cost_usd_raw "
+        "cache_create_tokens, cache_read_tokens, usage_extra_json, "
+        "cost_usd_raw, source_path "
         "FROM session_entries "
         "WHERE timestamp_utc >= ? AND timestamp_utc <= ?"
     )
@@ -875,6 +876,7 @@ def iter_entries(
             model=row[1],
             usage=usage,
             cost_usd=row[7],
+            source_path=row[8],
         ))
     return entries
 

package/bin/_cctally_config.py

@@ -46,6 +46,7 @@ import json
 import os
 import secrets
 import sys
+from pathlib import Path
 from typing import Any
 
 
@@ -162,17 +163,60 @@ def config_writer_lock():
         fh.close()
 
 
-def load_config() -> dict[str, Any]:
+def _load_config_from_explicit_path(path: "str | Path") -> dict[str, Any]:
+    """Read config from an explicit per-invocation override path (issue #88).
+
+    Contract differs from the default ``load_config()``:
+      - Missing file → ``SystemExit(2)`` with a clear stderr message.
+      - Unreadable / malformed JSON / non-object root → ``SystemExit(2)``
+        with a clear stderr message.
+      - Never writes, never acquires ``config_writer_lock``, never
+        creates the on-disk default config — the override is read-only
+        for this invocation.
+
+    Used by the ccusage drop-in ``--config <path>`` flag wired onto the
+    10 Claude reporting commands (spec §3 T1.6 / issue #86 Session A).
+    """
+    p = Path(path)
+    if not p.exists():
+        eprint(f"cctally: --config: file not found: {p}")
+        raise SystemExit(2)
+    try:
+        raw = p.read_text(encoding="utf-8")
+    except OSError as exc:
+        eprint(f"cctally: --config: read failed for {p}: {exc}")
+        raise SystemExit(2) from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        eprint(f"cctally: --config: invalid JSON in {p}: {exc}")
+        raise SystemExit(2) from exc
+    if not isinstance(data, dict):
+        eprint(
+            f"cctally: --config: {p} top-level must be a JSON object"
+        )
+        raise SystemExit(2)
+    return data
+
+
+def load_config(path: "str | Path | None" = None) -> dict[str, Any]:
     """Read config.json, falling back to in-memory defaults on corruption.
 
-    Concurrent-safety: readers see either the pre-rename or post-rename
-    contents thanks to save_config's atomic os.replace. On corrupt or
-    non-object JSON, emits a one-shot stderr warning and returns
-    in-memory defaults WITHOUT re-saving — the next legitimate
-    save_config call (under config_writer_lock) will overwrite the bad
-    bytes atomically. On first run (file missing), creates the file
-    with a fresh collector token under the writer lock so two parallel
-    first-run processes don't clobber each other.
+    When ``path`` is None (default): reads the persisted user config at
+    ``_cctally_core.CONFIG_PATH``, creating it on first run with a fresh
+    collector token under the writer lock. Concurrent-safety: readers see
+    either the pre-rename or post-rename contents thanks to save_config's
+    atomic os.replace. On corrupt or non-object JSON, emits a one-shot
+    stderr warning and returns in-memory defaults WITHOUT re-saving — the
+    next legitimate save_config call (under config_writer_lock) will
+    overwrite the bad bytes atomically.
+
+    When ``path`` is set (issue #88 ccusage drop-in ``--config <path>``):
+    reads from the explicit override path and bypasses the default-path
+    branch entirely. Missing / unreadable / malformed paths surface as
+    ``SystemExit(2)`` with a clear stderr message — see
+    ``_load_config_from_explicit_path``. No writes, no first-run create,
+    no mutation of the on-disk default config.
 
     DEADLOCK NOTE: `fcntl.flock` is per-fd even within the same
     process. Callers that already hold config_writer_lock MUST use
@@ -180,6 +224,8 @@ def load_config() -> dict[str, Any]:
     inside an outer lock would block forever (verified during issue
     #17 fix).
     """
+    if path is not None:
+        return _load_config_from_explicit_path(path)
     c = _cctally()
     ensure_dirs()
     parsed = _try_read_config()

package/bin/_lib_diff_kernel.py

@@ -1234,11 +1234,18 @@ def _diff_render_section_table(
     used_pct_mode_a: str,
     used_pct_mode_b: str,
     threshold: "NoiseThreshold | None" = None,
+    compact: bool = False,
 ) -> str:
     """Render one bordered table for a section. The Total row sums all rows
     (visible + hidden) — the caller passes the unfiltered aggregate map as
-    total_a/total_b so hidden rows still contribute (spec §4 invariant)."""
+    total_a/total_b so hidden rows still contribute (spec §4 invariant).
+
+    ``compact`` (issue #91, Shape B) drops the 1-space cell padding to 0 on
+    this content-sized table, which has no proportional-width path to force.
+    ``pad == 1`` (the default) reproduces the prior output byte-for-byte."""
     boxes = _diff_box_chars()
+    pad = 0 if compact else 1
+    pad_s = " " * pad
     out: list = [_diff_section_heading(section.name, width), ""]
 
     header_cells: list = ["Model" if section.name == "models"
@@ -1318,7 +1325,7 @@ def _diff_render_section_table(
         fill = fill or boxes["h"]
         parts = [left]
         for i, w in enumerate(col_w):
-            parts.append(fill * (w + 2))
+            parts.append(fill * (w + 2 * pad))
             parts.append(right if i == n_cols - 1 else mid)
         return "".join(parts)
 
@@ -1340,7 +1347,7 @@ def _diff_render_section_table(
                 # result. Spaces stay outside the ANSI escape so column rules
                 # align identically with or without color.
                 styled = _style_ansi(padded, code, enabled=bool(code))
-                parts.append(f" {styled} ")
+                parts.append(f"{pad_s}{styled}{pad_s}")
                 parts.append(boxes["v"])
             out_lines.append("".join(parts))
         return "\n".join(out_lines)
@@ -1376,11 +1383,13 @@ def _diff_render_full_output(
     width: int,
     raw_aggregates: dict,
     tz: "ZoneInfo | None" = None,
+    compact: bool = False,
 ) -> str:
     """Compose banner + window header + each section's table.
 
     ``tz`` is forwarded to ``_diff_render_window_header`` for the date
-    labels; ``tz=None`` means host-local.
+    labels; ``tz=None`` means host-local. ``compact`` (issue #91, Shape B)
+    is forwarded to each section table's pad-reduction branch.
     """
     parts: list = [
         _diff_render_banner(), "",
@@ -1395,6 +1404,7 @@ def _diff_render_full_output(
             used_pct_mode_a=result.used_pct_mode_a,
             used_pct_mode_b=result.used_pct_mode_b,
             threshold=result.threshold,
+            compact=compact,
         ))
     return "\n".join(parts)
 

package/bin/_lib_jsonl.py

@@ -39,6 +39,11 @@ class UsageEntry:
     model: str
     usage: dict[str, Any]
     cost_usd: float | None
+    source_path: str   # REQUIRED — absolute JSONL path; basename used in
+                       # --debug samples (issue #89). Always supply a
+                       # non-empty path-like string; "" is invalid per
+                       # spec R5 (no silent empty-string passthrough,
+                       # crashes loudly at construction instead).
 
 
 @dataclass
@@ -178,6 +183,7 @@ def _parse_usage_entries(
                     model=model,
                     usage=usage,
                     cost_usd=cost_usd,
+                    source_path=str(jsonl_path),
                 )
 
                 if msg_id is None or req_id is None:
@@ -195,7 +201,7 @@ def _parse_usage_entries(
     return no_key_entries
 
 
-def _iter_jsonl_entries_with_offsets(fh):
+def _iter_jsonl_entries_with_offsets(fh, path_str: str):
     """Yield (byte_offset, UsageEntry, msg_id, req_id) for each assistant
     entry starting from fh's current position.
 
@@ -269,6 +275,7 @@ def _iter_jsonl_entries_with_offsets(fh):
                 model=model,
                 usage=usage,
                 cost_usd=cost_usd,
+                source_path=path_str,
             ),
             msg_id,
             req_id,

package/bin/_lib_render.py

@@ -134,6 +134,94 @@ def _format_block_start(*args, **kwargs):
     return sys.modules["cctally"]._format_block_start(*args, **kwargs)
 
 
+def _ellipsize(content: str, width: int, unicode_ok: bool) -> str:
+    """Truncate ``content`` to ``width`` cells, marking the cut with an
+    ellipsis. Returns ``content`` unchanged when it already fits.
+
+    Used for BOTH header and (text) data cells so a column scaled below
+    its header-label width stays aligned with the border row (issue #102
+    (a)) — the header render previously padded without truncating, so a
+    label wider than its scaled column overflowed the box."""
+    if len(content) <= width:
+        return content
+    ell = "…" if unicode_ok else "..."
+    return content[: max(0, width - len(ell))] + ell
+
+
+def _scale_down_col_widths(
+    nat_widths: list[int],
+    aligns: list[str],
+    data_widths: list[int],
+    available: int,
+    *,
+    grow_idx: int,
+    min_text: int = 4,
+) -> list[int]:
+    """Allocate the per-column widths for the ``--compact`` / auto-overflow
+    scale-down branch of the project + Claude-session renderers.
+
+    Policy (issue #102 — recommendation (a) + (b)):
+
+      * **Numeric (right-aligned) columns are protected.** Their hard floor
+        is the widest DATA value (``data_widths[i]``), so the full number
+        always shows; the row render must never ellipsis-truncate a
+        right-aligned cell. A silently-wrong figure (``12,345,…``) is worse
+        than honest overflow.
+      * **Text (left-aligned) columns absorb the squeeze** and may truncate
+        — including their header label, which the header render ellipsizes
+        the same way (so a column may drop below header width while staying
+        box-aligned).
+      * When the natural widths fit, they are used verbatim and the slack
+        goes to ``grow_idx``. When shrinking is required, widths scale
+        proportionally, clamped to ``[floor, natural]``; any residual after
+        reclaiming all text slack is accepted as honest overflow rather than
+        corrupting a number.
+
+    ``data_widths[i]`` is the widest cell EXCLUDING the header, so a numeric
+    column is sized to its number — its (possibly wider, truncatable) header
+    label does not inflate the protected floor.
+    """
+    num_cols = len(nat_widths)
+    floors = [
+        min(max(data_widths[i], 1), nat_widths[i]) if aligns[i] == "right"
+        else min(min_text, nat_widths[i])
+        for i in range(num_cols)
+    ]
+    total_nat = sum(nat_widths)
+    if total_nat <= available:
+        widths = list(nat_widths)
+        slack = available - total_nat
+        if slack > 0 and 0 <= grow_idx < num_cols:
+            widths[grow_idx] += slack
+        return widths
+
+    scale = available / total_nat if total_nat > 0 else 1.0
+    widths = [
+        min(nat_widths[i], max(int(nat_widths[i] * scale), floors[i]))
+        for i in range(num_cols)
+    ]
+    overflow = sum(widths) - available
+    if overflow > 0:
+        # Reclaim from text columns (most slack above floor first); numeric
+        # columns are immovable. Residual overflow is honest (issue #102 (b)).
+        text_idx = sorted(
+            (i for i in range(num_cols) if aligns[i] != "right"),
+            key=lambda i: widths[i] - floors[i],
+            reverse=True,
+        )
+        for i in text_idx:
+            if overflow <= 0:
+                break
+            take = min(widths[i] - floors[i], overflow)
+            widths[i] -= take
+            overflow -= take
+    else:
+        slack = available - sum(widths)
+        if slack > 0 and 0 <= grow_idx < num_cols:
+            widths[grow_idx] += slack
+    return widths
+
+
 # Optional dependency: zoneinfo.ZoneInfo is referenced only as a string
 # annotation in moved code; no runtime import needed.
 
@@ -143,6 +231,7 @@ def _render_blocks_table(
     *,
     now: dt.datetime | None = None,
     tz: "ZoneInfo | None" = None,
+    compact: bool = False,
 ) -> str:
     """Render blocks as a ccusage-style ANSI table with box-drawing borders.
 
@@ -158,6 +247,11 @@ def _render_blocks_table(
 
     ``tz`` is the resolved display zone (``None`` means host local).
     Block-start cells are rendered in this zone.
+
+    ``compact`` forces the scale-down code path regardless of the actual
+    terminal width (Session A ``--compact`` flag; spec §7.6.1). Mirrors
+    the same kwarg on ``_render_bucket_table``. Auto-detected
+    width-overflow continues to trigger the same path as before.
     """
     if not blocks:
         return "No session blocks found in the specified date range."
@@ -416,10 +510,12 @@ def _render_blocks_table(
 
     # Scale down only when table exceeds terminal width.
     # ccusage does NOT expand columns when the table fits — it uses the
-    # padded content widths as-is.
+    # padded content widths as-is. Session A (spec §7.6.1): the
+    # ``compact`` kwarg forces this branch regardless of terminal width
+    # (Review-A P2-B; mirrors ``_render_bucket_table`` semantics).
     table_overhead = 3 * num_cols + 1
     available_width = term_width - table_overhead
-    if sum(col_widths) + table_overhead > term_width:
+    if compact or (sum(col_widths) + table_overhead > term_width):
         scale_factor = available_width / sum(col_widths)
         col_widths = [
             max(
@@ -977,6 +1073,7 @@ def _render_bucket_table(
     title_suffix: str,
     compact_split_fn: Callable[[str], str],
     breakdown: bool = False,
+    compact: bool = False,
 ) -> str:
     """Render bucket aggregates as a ccusage-style ANSI table.
 
@@ -985,6 +1082,8 @@ def _render_bucket_table(
       title_suffix    — banner text suffix ("Daily" or "Monthly").
       compact_split_fn — function that splits a bucket string into
                          "YYYY\\n..." for compact-mode two-line display.
+      compact         — force compact layout regardless of terminal width
+                        (Session A `--compact` flag; spec §7.6.1).
 
     Mirrors ccusage's ResponsiveTable behavior: single-line headers and dates
     when content fits the terminal; falls back to two-line compact headers
@@ -1109,7 +1208,11 @@ def _render_bucket_table(
         term_width = int(os.environ.get("COLUMNS", "120"))
 
     border_overhead = 3 * num_cols + 1
-    compact_mode = sum(col_widths) + border_overhead > term_width
+    # Session A (spec §7.6.1): `compact=True` (set by `--compact` flag on
+    # daily/monthly/weekly/blocks/...) forces compact-mode regardless of
+    # the actual terminal width. Auto-detected width-overflow continues to
+    # trigger compact mode as before.
+    compact_mode = compact or (sum(col_widths) + border_overhead > term_width)
 
     if compact_mode:
         # Scale down proportionally with narrow minimums.
@@ -1272,6 +1375,7 @@ def _render_weekly_table(
     weeks: list["SubWeek"],
     compact_split_fn: Callable[[str], str],
     breakdown: bool = False,
+    compact: bool = False,
 ) -> str:
     """Render weekly bucket aggregates as a ccusage-style ANSI table.
 
@@ -1292,6 +1396,10 @@ def _render_weekly_table(
 
     `first_col_name` and `title_suffix` are hardcoded to "Week" and
     "Weekly" respectively.
+
+    `compact` forces compact layout regardless of terminal width
+    (Session A `--compact` flag; spec \u00a77.6.1). Mirrors the same kwarg
+    on `_render_bucket_table` (Review-A P3-1).
     """
     assert len(week_pct_overlay) == len(buckets), (
         f"week_pct_overlay length {len(week_pct_overlay)} does not match "
@@ -1443,7 +1551,11 @@ def _render_weekly_table(
         term_width = int(os.environ.get("COLUMNS", "120"))
 
     border_overhead = 3 * num_cols + 1
-    compact_mode = sum(col_widths) + border_overhead > term_width
+    # Session A (spec §7.6.1): `compact=True` (set by `--compact` flag on
+    # daily/monthly/weekly/blocks/...) forces compact-mode regardless of
+    # the actual terminal width. Auto-detected width-overflow continues to
+    # trigger compact mode as before.
+    compact_mode = compact or (sum(col_widths) + border_overhead > term_width)
 
     if compact_mode:
         # Scale down proportionally with narrow minimums.
@@ -2099,6 +2211,7 @@ def _render_claude_session_table(
     title: str = "Claude Token Usage Report - Sessions",
     breakdown: bool = False,
     tz: "ZoneInfo | None" = None,
+    compact: bool = False,
 ) -> str:
     """Render Claude session aggregates matching upstream ccusage session view (11 cols).
 
@@ -2109,14 +2222,16 @@ def _render_claude_session_table(
     Structural clone of `_render_codex_session_table` with:
       - ``Reasoning`` column replaced by ``Cache Create`` (sourced from
         ``cache_creation_tokens`` instead of ``reasoning_output_tokens``).
-      - ``tz_name`` / ``force_compact`` parameters dropped — Claude-side
-        commands don't expose ``--timezone`` / ``--compact`` today; dates
-        render in local TZ via ``astimezone()`` and compact mode is
-        triggered by terminal width alone.
       - ``Session`` cell shows first 8 chars of ``session_id`` (full UUID
         lives in --json).
 
     ``breakdown`` toggles per-model sub-rows beneath each session row.
+
+    ``compact`` forces the proportional scale-down code path regardless
+    of the actual terminal width (Session A ``--compact`` flag; spec
+    §7.6.1; Review-A P2-B). Mirrors ``_render_codex_session_table``'s
+    ``force_compact`` semantics. Auto-detected width overflow continues
+    to trigger the same path.
     """
     color = _supports_color_stdout()
     unicode_ok = _supports_unicode_stdout()
@@ -2250,6 +2365,34 @@ def _render_claude_session_table(
 
     col_widths = [_wide_width(i, content_widths[i]) for i in range(num_cols)]
 
+    try:
+        term_width = os.get_terminal_size().columns
+    except (OSError, ValueError):
+        term_width = int(os.environ.get("COLUMNS", "120"))
+
+    border_overhead = 3 * num_cols + 1
+    # Session A (spec \u00a77.6.1; Review-A P2-B): the scale-down branch
+    # fires ONLY under explicit ``compact=True``. Pre-Session-A
+    # ``_render_claude_session_table`` had no auto-overflow branch
+    # (wide-by-default was the existing contract; 6 golden fixtures
+    # in tests/fixtures/session/ encode that contract). The
+    # Cross-Branch Reviewer flagged the gratuitous auto-detect arm
+    # added in fdfee047; this restores the pre-Session-A behavior
+    # while preserving the explicit-compact override.
+    if compact:
+        available = term_width - border_overhead
+        # Per-column widest DATA value (excludes the header row), so numeric
+        # columns are protected at their number width while header labels may
+        # truncate (issue #102). data_cells/footer carry the values; the
+        # header is added separately below.
+        data_widths = [0] * num_cols
+        for cells, _rt in raw_rows:
+            for i, (text, _c) in enumerate(cells):
+                data_widths[i] = max(data_widths[i], _max_line_width(text))
+        col_widths = _scale_down_col_widths(
+            col_widths, aligns, data_widths, available, grow_idx=1,
+        )
+
     def _split_cell(text: str) -> list[str]:
         return text.split("\n") if text else [""]
 
@@ -2290,13 +2433,15 @@ def _render_claude_session_table(
 
     out.append(_border_row(TL, T_DOWN, TR))
 
-    # Header
+    # Header — labels ellipsize like data cells so a column scaled below
+    # its header width stays box-aligned (issue #102 (a)).
     header_cells = [_split_cell(h) for h in headers]
     max_h = max(len(c) for c in header_cells)
     for li in range(max_h):
         parts = [_dim(V)]
         for i, cell in enumerate(header_cells):
             content = cell[li] if li < len(cell) else ""
+            content = _ellipsize(content, col_widths[i], unicode_ok)
             parts.append(f" {_cyan(_pad_cell(content, col_widths[i], aligns[i]))} ")
             parts.append(_dim(V))
         out.append("".join(parts))
@@ -2312,7 +2457,15 @@ def _render_claude_session_table(
             parts = [_dim(V)]
             for i, (text, cfn) in enumerate(cells):
                 content = split_cells[i][li] if li < len(split_cells[i]) else ""
-                padded = _pad_cell(content, col_widths[i], aligns[i])
+                # Ellipsis-truncate only TEXT cells under --compact. Numeric
+                # (right-aligned) cells are NEVER truncated — a wrong number
+                # is worse than honest overflow (issue #102 (b)); the column
+                # is floored at its full number width so this normally never
+                # overflows. Mirrors _render_codex_session_table.
+                w = col_widths[i]
+                if aligns[i] != "right":
+                    content = _ellipsize(content, w, unicode_ok)
+                padded = _pad_cell(content, w, aligns[i])
                 if cfn is not None:
                     padded = cfn(padded)
                 parts.append(f" {padded} ")
@@ -2368,6 +2521,8 @@ def _render_project_table(
     weeks_missing_snapshot: int = 0,
     weeks_in_range: int = 1,
     no_color: bool = False,
+    color: "bool | None" = None,
+    compact: bool = False,
 ) -> str:
     """Render project rollup as a ccusage-style ANSI table.
 
@@ -2381,7 +2536,12 @@ def _render_project_table(
     first for width calc, ANSI applied at render time) and same banner /
     border / separator glyphs.
     """
-    color = False if no_color else _supports_color_stdout()
+    # Session A (spec §7.3): caller may pass an explicit ``color`` bool
+    # to override the auto-detect (so the new bool ``--color`` flag can
+    # force ANSI under NO_COLOR=1 env). Legacy ``no_color`` kwarg path
+    # is preserved for callers that haven't migrated.
+    if color is None:
+        color = False if no_color else _supports_color_stdout()
     unicode_ok = _supports_unicode_stdout()
 
     def _dim(s: str) -> str:  return _style_ansi(s, "90", color)
@@ -2531,14 +2691,22 @@ def _render_project_table(
         term_width = int(os.environ.get("COLUMNS", "120"))
 
     border_overhead = 3 * num_cols + 1
-    if sum(col_widths) + border_overhead > term_width:
+    # Issue #91 (Shape A): the ``compact`` kwarg forces this scale-down
+    # branch regardless of terminal width, mirroring ``_render_blocks_table``
+    # / ``_render_bucket_table``. Auto-detected width-overflow continues to
+    # trigger the same path as before.
+    if compact or (sum(col_widths) + border_overhead > term_width):
         available = term_width - border_overhead
-        total_col = sum(col_widths)
-        scale = available / total_col if total_col > 0 else 1.0
-        col_widths = [max(int(w * scale), 8) for w in col_widths]
-        remainder = available - sum(col_widths)
-        if remainder > 0:
-            col_widths[0] += remainder  # grow Project column
+        # Per-column widest DATA value (excludes the header row): numeric
+        # columns are protected at their number width while header labels may
+        # truncate (issue #102 (a) + (b)).
+        data_widths = [0] * num_cols
+        for cells, _rt in raw_rows:
+            for i, (text, _c) in enumerate(cells):
+                data_widths[i] = max(data_widths[i], _max_line_width(text))
+        col_widths = _scale_down_col_widths(
+            col_widths, aligns, data_widths, available, grow_idx=0,
+        )
 
     def _split_cell(text: str) -> list[str]:
         return text.split("\n") if text else [""]
@@ -2585,6 +2753,7 @@ def _render_project_table(
         parts = [_dim(V)]
         for i, cell in enumerate(header_cells):
             content = cell[li] if li < len(cell) else ""
+            content = _ellipsize(content, col_widths[i], unicode_ok)
             parts.append(f" {_cyan(_pad_cell(content, col_widths[i], aligns[i]))} ")
             parts.append(_dim(V))
         out.append("".join(parts))
@@ -2599,10 +2768,12 @@ def _render_project_table(
             parts = [_dim(V)]
             for i, (text, cfn) in enumerate(cells):
                 content = split_cells[i][li] if li < len(split_cells[i]) else ""
+                # Numeric (right-aligned) cells are never ellipsized \u2014 a
+                # wrong number is worse than honest overflow (issue #102 (b));
+                # text cells truncate so the column can shrink (a).
                 w = col_widths[i]
-                if len(content) > w:
-                    ell = "\u2026" if unicode_ok else "..."
-                    content = content[: max(0, w - len(ell))] + ell
+                if aligns[i] != "right":
+                    content = _ellipsize(content, w, unicode_ok)
                 padded = _pad_cell(content, w, aligns[i])
                 if cfn is not None:
                     padded = cfn(padded)
@@ -2800,7 +2971,7 @@ def _render_five_hour_blocks_table(
                 "", "", "",
             ])
 
-    print(_boxed_table(headers, rows, aligns))
+    print(_boxed_table(headers, rows, aligns, compact=args.compact))
     glyph = " · ⚡ = block crossed weekly reset" if has_crossed else ""
     print(f"\n{len(block_dicts)} blocks · cost: ${total_cost:.2f}{glyph}")
 

package/bin/_lib_subscription_weeks.py

@@ -283,6 +283,7 @@ def _compute_subscription_weeks(
     conn: sqlite3.Connection,
     range_start: dt.datetime,
     range_end: dt.datetime,
+    config: "dict | None" = None,
 ) -> list[SubWeek]:
     """Generate the ordered list of subscription weeks overlapping [range_start, range_end].
 
@@ -292,6 +293,16 @@ def _compute_subscription_weeks(
     config-based calendar-week boundaries with every week tagged
     "extrapolated".
 
+    ``config`` (issue #88 ``--config`` surface): the resolved config dict
+    used by the no-snapshot Case-B calendar-week fallback. When the caller
+    already loaded config honoring the per-invocation ``--config <path>``
+    override (``_load_claude_config_for_args``), it MUST pass it here so the
+    fallback's ``collector.week_start`` matches the explicit override rather
+    than re-reading (and first-run-creating) the persisted default config.
+    ``None`` preserves the legacy bare-``load_config()`` behavior for callers
+    with no ``--config`` surface (dashboard) and for the monkeypatch
+    carve-out (tests reach ``load_config`` via ``ns["load_config"]``).
+
     Anthropic's reset day-of-week is not strictly stable across long spans —
     it can shift (observed: Thursday cycles in Feb, Friday cycles from Mar
     onward). A single-anchor 7-day-multiple extrapolation therefore generates
@@ -466,9 +477,16 @@ def _compute_subscription_weeks(
         return _apply_overlap_clamp_to_subweeks(weeks)
 
     # Case B: no snapshots — config-based calendar-week fallback.
-    # `load_config` stays on the _cctally() accessor per spec §3.5
-    # monkeypatch carve-out — tests reach it via ``ns["load_config"]``.
-    config = _cctally().load_config()
+    # Honor the caller's `--config <path>` override when supplied (issue
+    # #88): `cmd_weekly` / `cmd_project` pass the config resolved by
+    # `_load_claude_config_for_args` so this fallback reads the explicit
+    # path's `collector.week_start` instead of recreating / reading the
+    # persisted default. When `config is None` (dashboard, or the spec §3.5
+    # monkeypatch carve-out where tests reach `load_config` via
+    # `ns["load_config"]`), fall back to a bare `load_config()` on the
+    # `_cctally()` accessor — identical to the prior behavior.
+    if config is None:
+        config = _cctally().load_config()
     week_start_name = get_week_start_name(config)
     week_start_idx = WEEKDAY_MAP[week_start_name]
     # internal fallback: host-local intentional