cctally 1.12.0 → 1.14.0

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(
@@ -910,13 +1006,18 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
 
 
 def _claude_sessions_to_json(sessions: list[ClaudeSessionUsage]) -> str:
-    """Serialize Claude sessions to JSON per spec A2.8.
+    """Serialize Claude sessions to JSON (spec A2.8, amended by issue #104).
 
     Per-session: sessionId, projectPath, sourcePaths (list), firstActivity
     / lastActivity ISO strings, modelsUsed, token counts
     (input/cacheCreation/cacheRead/output/total), totalCost, modelBreakdowns
     (camelCased token field names, cost).
 
+    `totalTokens` (per-session + totals) sums ALL four token components
+    (input + output + cacheCreation + cacheRead) per issue #104 — matching
+    `daily`/`monthly` and ccusage v20. (The field name/shape is unchanged;
+    only the value definition widened to include cache.)
+
     totals: same 6 numeric fields aggregated across sessions.
     """
     sess_list: list[dict[str, Any]] = []
@@ -977,6 +1078,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 +1087,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 +1213,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 +1380,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 +1401,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 +1556,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.
@@ -2006,12 +2123,23 @@ def _render_codex_session_table(
     # auto-detect so the narrow layout renders regardless of terminal width.
     if force_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[3] += remainder  # grow Models column
+        # Issue #99 / #102: the prior bare-`8` floor could scale a column
+        # below its header label, and headers are padded (never truncated)
+        # in the header render — so the header row grew wider than the box
+        # border and the grid misaligned on narrow terminals. Mirror the
+        # sibling renderers (`_render_claude_session_table` + the project
+        # renderer) via the shared `_scale_down_col_widths` chokepoint:
+        # numeric columns are protected at their widest DATA value while
+        # text columns (incl. header labels) absorb the squeeze and may
+        # truncate, keeping every box line the same width. Grows the Models
+        # column (index 3) with any slack, preserving prior behavior.
+        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=3,
+        )
 
     def _split_cell(text: str) -> list[str]:
         return text.split("\n") if text else [""]
@@ -2053,13 +2181,17 @@ def _render_codex_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 #99 / #102 (a)). Previously
+    # the header padded without truncating, so a label wider than its
+    # scaled column overflowed the box border.
     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))
@@ -2075,11 +2207,14 @@ def _render_codex_session_table(
             parts = [_dim(V)]
             for i, (text, cfn) in enumerate(cells):
                 content = split_cells[i][li] if li < len(split_cells[i]) else ""
-                # Truncate with ellipsis if cell content exceeds column width
+                # Ellipsis-truncate only TEXT cells. Numeric (right-aligned)
+                # cells are NEVER truncated \u2014 a wrong number is worse than
+                # honest overflow (issue #102 (b)); _scale_down_col_widths
+                # floors numeric columns at their full number width so this
+                # normally never overflows. Mirrors the sibling renderers.
                 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)
@@ -2099,6 +2234,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 +2245,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()
@@ -2166,9 +2304,10 @@ def _render_claude_session_table(
     for s in sessions:
         short_models = sorted({_short_model_name(m) for m in s.models})
         models_text = "\n".join(f"- {m}" for m in short_models) if short_models else ""
-        # Spec A2.8: Total Tokens = input + output (cache shown separately,
-        # not summed). Parallels `_render_codex_session_table` line ~4644.
-        session_total = s.input_tokens + s.output_tokens
+        # Issue #104: Total Tokens = all four components (input + output +
+        # cache), matching daily/monthly + ccusage v20. Read the single
+        # source of truth on the aggregate rather than recomputing.
+        session_total = s.total_tokens
         data_cells = [
             (_date_cell(s.last_activity), None),
             (s.project_path, None),
@@ -2191,8 +2330,8 @@ def _render_claude_session_table(
                 mb_cc = int(mb["cache_create"])
                 mb_cr = int(mb["cache_read"])
                 mb_output = int(mb["output"])
-                # Spec A2.8: Total Tokens = input + output only.
-                mb_total = mb_input + mb_output
+                # Issue #104: per-model Total Tokens sums all four components.
+                mb_total = mb_input + mb_output + mb_cc + mb_cr
                 mb_cost = float(mb["cost"])
                 bd_cells = [
                     (f"{arrow} {name}", _gray),
@@ -2213,8 +2352,8 @@ def _render_claude_session_table(
     tot_cc = sum(s.cache_creation_tokens for s in sessions)
     tot_cr = sum(s.cache_read_tokens for s in sessions)
     tot_output = sum(s.output_tokens for s in sessions)
-    # Spec A2.8: Total Tokens = input + output only.
-    tot_tokens = tot_input + tot_output
+    # Issue #104: Total Tokens footer sums all four components.
+    tot_tokens = sum(s.total_tokens for s in sessions)
     tot_cost = sum(s.cost_usd for s in sessions)
     footer_cells = [
         ("Total", _yellow),
@@ -2250,6 +2389,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 +2457,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 +2481,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 +2545,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 +2560,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 +2715,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 +2777,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 +2792,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 +2995,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