cctally 1.12.0 → 1.14.0

package/bin/cctally

@@ -288,6 +288,26 @@ _compute_display_block = _lib_display_tz._compute_display_block
 format_display_dt = _lib_display_tz.format_display_dt
 _argparse_tz = _lib_display_tz._argparse_tz
 
+
+def _nonneg_int(raw: str) -> int:
+    """argparse `type=` validator for non-negative integer flags (issue #89).
+
+    Used by ``--debug-samples`` so a negative N is rejected at parse time
+    rather than silently coerced inside the helper. Raises
+    ``argparse.ArgumentTypeError`` so argparse surfaces the message under
+    the standard ``argument <flag>:`` prefix.
+    """
+    try:
+        n = int(raw)
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            f"must be a non-negative integer, got '{raw}'"
+        )
+    if n < 0:
+        raise argparse.ArgumentTypeError(f"must be >= 0, got {n}")
+    return n
+
+
 _lib_alerts_payload = _load_sibling("_lib_alerts_payload")
 _alert_text_weekly = _lib_alerts_payload._alert_text_weekly
 _alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
@@ -889,6 +909,17 @@ def _migrate_legacy_data_dir() -> None:
     Removable in a future major version once early users have been on
     cctally long enough that the legacy dir is gone everywhere.
     """
+    # Dev-instance isolation (F2): the legacy ccusage-subscription rename is a
+    # PROD-only concern. Skip it whenever the data dir was relocated away from
+    # the canonical prod path — i.e. dev-checkout auto-detect (DEV_MODE) or an
+    # explicit CCTALLY_DATA_DIR override — so a dev run (APP_DIR = cctally-dev)
+    # or a per-branch override never hijacks the one-shot move into the wrong
+    # dir. "not DEV_MODE and not CCTALLY_DATA_DIR" is exactly the prod-default
+    # resolution branch, i.e. APP_DIR == ~/.local/share/cctally. Under the test
+    # suppressor DEV_MODE is False and the existing migration tests (which pin
+    # APP_DIR directly, no override) still exercise the move.
+    if _cctally_core.DEV_MODE or os.environ.get("CCTALLY_DATA_DIR", "").strip():
+        return
     if _cctally_core.APP_DIR.exists():
         return  # already migrated, or fresh install at the new path
     if not _cctally_core.LEGACY_APP_DIR.exists():
@@ -995,6 +1026,648 @@ def _sum_cost_for_range(
     return total
 
 
+def _bridge_z_into_tz(args: argparse.Namespace,
+                      config: "dict | None" = None) -> None:
+    """Promote ``-z`` / ``--timezone`` onto ``args.tz`` when ``--tz`` is unset.
+
+    Session A (spec §7.2) defines a 4-rung precedence for Claude display tz:
+    ``--tz`` > ``-z --timezone`` > ``config.display.tz`` > host-local. The
+    existing ``resolve_display_tz`` reads only ``args.tz`` and config; the
+    minimal-invasive way to fold in ``-z`` without modifying the shared
+    pure-fn layer is to set ``args.tz`` here when ``--tz`` wasn't
+    supplied. This mutates the namespace and is safe because each cmd_*
+    receives a fresh ``args`` per invocation.
+
+    Internally delegates to :func:`_resolve_claude_tz_name`, which
+    encodes the 4-rung precedence and returns the tz-name string (or
+    ``None`` for host-local fallback). This wires the resolver into the
+    production path so the 7-case test contract (spec §9.2a) is
+    exercised end-to-end, not only by unit tests (Review-A P2-A).
+
+    Validates the bridged rung-2 value via ``_argparse_tz`` so an
+    invalid tz name from ``-z`` surfaces the same canonical error as
+    ``--tz`` (argparse-time validation can't run on the alias because
+    the alias flag is plain string, not ``type=_argparse_tz``). The
+    resolver returns the raw string, so we revalidate here on the path
+    that actually bridges into ``args.tz``.
+
+    Error attribution is rung-aware (#90). A malformed value typed on
+    the command line (rung-2, ``-z``/``--timezone``) is a usage error
+    and hard-fails with the argparse-style message + exit 2. A malformed
+    ``config.display.tz`` (rung-3) is NOT promoted or hard-failed here:
+    it falls through to ``resolve_display_tz`` / ``get_display_tz_pref``
+    downstream, which warn once and default to host-local (exit 0). That
+    restores the pre-Session-A contract and matches how codex commands
+    and the dashboard already treat a malformed persisted tz pref.
+    """
+    # Short-circuit: --tz already set wins all rungs (the resolver
+    # returns args.tz unchanged anyway, but skipping avoids touching
+    # the namespace and re-validating an already-canonical value).
+    if getattr(args, "tz", None) is not None:
+        return
+    resolved = _resolve_claude_tz_name(args, config)
+    if resolved is None:
+        return
+    # ``args.tz`` is None here (short-circuited above), so ``resolved``
+    # came from rung-2 (``-z``/``--timezone``) iff ``args.timezone`` is
+    # set; otherwise it is the rung-3 ``config.display.tz`` value.
+    from_cli_alias = getattr(args, "timezone", None) is not None
+    # Validate via _argparse_tz so an invalid --timezone surfaces the
+    # canonical argparse-style error (matches --tz's type-check).
+    try:
+        canonical = _argparse_tz(resolved)
+    except argparse.ArgumentTypeError as exc:
+        if from_cli_alias:
+            # Rung-2: a value the user typed on the command line. Surface
+            # the same error --tz gives at parse time. We can't call
+            # parser.error from here, so emit-and-raise via SystemExit(2)
+            # for argparse-shape parity.
+            eprint(f"cctally: argument -z/--timezone: {exc}")
+            raise SystemExit(2) from exc
+        # Rung-3: malformed config.display.tz with no CLI tz flag. Don't
+        # mis-attribute the error to -z/--timezone or hard-fail (#90).
+        # Leave args.tz unset; resolve_display_tz / get_display_tz_pref
+        # warn once and default to host-local downstream (exit 0).
+        return
+    args.tz = canonical
+
+
+def _resolve_claude_tz_name(args: argparse.Namespace,
+                            config: "dict | None") -> "str | None":
+    """Resolve display-tz precedence for Claude reporting commands.
+
+    Returns the tz name string (or ``None`` for host-local fallback).
+    Precedence (top wins):
+      1. ``--tz`` flag (canonical cctally flag).
+      2. ``-z`` / ``--timezone`` flag (ccusage-codex sharedArgs alias).
+      3. ``config.display.tz`` (persisted user pref).
+      4. ``None`` → host-local (existing fallback in ``resolve_display_tz``).
+
+    Spec §7.2 (issue #86 Session A). Mirrors ``_resolve_codex_tz_name``'s
+    structural shape for code-review familiarity, but the rung order
+    diverges: codex's resolver falls back to upstream's ``--timezone``
+    ONLY when neither ``--tz`` nor ``display.tz`` is set, while Claude's
+    Session A contract puts ``-z --timezone`` ahead of ``display.tz``.
+    Both shapes are intentional — the Codex helper preserves drop-in
+    parity with upstream's ``ccusage-codex sharedArgs``; the Claude
+    helper expresses the Session A precedence the spec promises.
+    """
+    tz = getattr(args, "tz", None)
+    if tz is not None:
+        return tz
+    tzname = getattr(args, "timezone", None)
+    if tzname is not None:
+        return tzname
+    display = (config or {}).get("display") or {}
+    cfg_tz = display.get("tz")
+    if cfg_tz:
+        return cfg_tz
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Issue #89 — Real --debug diagnostic-sample emission
+# ---------------------------------------------------------------------------
+# Spec: docs/superpowers/specs/2026-05-23-issue-89-debug-sample-emission.md
+# Replaces the §7.6.2 placeholder note with a real ccusage-parity
+# "Pricing Mismatch Debug Report" on stderr.
+
+@dataclass
+class _MismatchModelStat:
+    total: int = 0
+    matches: int = 0
+    mismatches: int = 0
+    avg_percent_diff: float = 0.0
+
+
+@dataclass
+class _MismatchSample:
+    file: str
+    timestamp: str
+    model: str
+    original_cost: float
+    calculated_cost: float
+    difference: float
+    percent_diff: float
+    usage: dict
+
+
+@dataclass
+class _MismatchStats:
+    command_label: str | None = None
+    total_entries: int = 0
+    entries_with_both: int = 0
+    matches: int = 0
+    mismatches: int = 0
+    model_stats: dict = field(default_factory=dict)
+    discrepancies: list = field(default_factory=list)
+
+
+def _compute_pricing_mismatch_stats(entries):
+    """Walk ``entries: Iterable[UsageEntry]`` and compute the mismatch stats
+    that ``_render_pricing_mismatch_report`` consumes.
+
+    Mirrors ccusage upstream's ``detectMismatches``
+    (``~/.npm/_npx/.../node_modules/ccusage/dist/debug-DvI5DUKR.js:6-95``):
+
+    - An entry counts toward ``entries_with_both`` iff its ``cost_usd``
+      is not None AND the model has pricing in ``CLAUDE_MODEL_PRICING``.
+    - Threshold: ``percent_diff < 0.1`` is a match; anything else is a
+      mismatch and gets appended to ``discrepancies`` in iteration order.
+    - ``percent_diff`` is ``0.0`` when recorded cost is zero (parity with
+      upstream's divide-by-zero guard).
+    - Per-model ``avg_percent_diff`` updated by streaming mean recurrence
+      to match upstream's per-row accumulation.
+    """
+    stats = _MismatchStats()
+    for entry in entries:
+        # P1.1 (issue #89 review-loop): mirror ccusage upstream's
+        # ``detectMismatches`` precondition filter at debug-DvI5DUKR.js:42
+        # — synthetic entries are excluded from total_entries AND skip the
+        # _resolve_model_pricing call (which would otherwise emit a
+        # ``[cost] unknown model: <synthetic>`` warning and mutate the
+        # module-level _unknown_model_warnings set, suppressing future
+        # legitimate emissions).
+        if entry.model == "<synthetic>":
+            continue
+        stats.total_entries += 1
+        if entry.cost_usd is None:
+            continue
+        if _resolve_model_pricing(entry.model) is None:
+            continue
+        stats.entries_with_both += 1
+        calculated = _calculate_entry_cost(
+            entry.model, entry.usage, mode="calculate",
+        )
+        original = float(entry.cost_usd)
+        difference = abs(original - calculated)
+        percent_diff = (difference / original * 100) if original > 0 else 0.0
+        ms = stats.model_stats.setdefault(entry.model, _MismatchModelStat())
+        ms.total += 1
+        if percent_diff < 0.1:
+            stats.matches += 1
+            ms.matches += 1
+        else:
+            stats.mismatches += 1
+            ms.mismatches += 1
+            stats.discrepancies.append(_MismatchSample(
+                file=os.path.basename(entry.source_path),
+                timestamp=entry.timestamp.isoformat(),
+                model=entry.model,
+                original_cost=original,
+                calculated_cost=calculated,
+                difference=difference,
+                percent_diff=percent_diff,
+                usage=dict(entry.usage),
+            ))
+        # Streaming-mean update for avg_percent_diff (matches upstream).
+        ms.avg_percent_diff = (
+            ms.avg_percent_diff * (ms.total - 1) + percent_diff
+        ) / ms.total
+    return stats
+
+
+def _render_pricing_mismatch_report(stats, sample_limit):
+    """Return the report as a list of stderr lines (caller prints \\n-joined).
+
+    Matches ccusage upstream's ``printMismatchReport``
+    (debug-DvI5DUKR.js:97-145) including:
+      - Early-return ``"No pricing data found to analyze."`` when
+        ``entries_with_both == 0``.
+      - Model Statistics + Sample Discrepancies sections omitted when
+        ``mismatches == 0``.
+      - Models with ``mismatches == 0`` omitted from Model Statistics.
+      - Sample header prints the requested ``sample_limit`` (not min with
+        discrepancies length).
+    Adds ONE intentional non-upstream line: ``Command: cctally <label>``
+    under the header so the report self-identifies (issue #89 acceptance
+    re: "command in each sample's context").
+    """
+    out = []
+    if stats.entries_with_both == 0:
+        out.append("No pricing data found to analyze.")
+        return out
+
+    match_rate = stats.matches / stats.entries_with_both * 100
+    out.append("")
+    out.append("=== Pricing Mismatch Debug Report ===")
+    if stats.command_label:
+        out.append(f"Command: cctally {stats.command_label}")
+    out.append(f"Total entries processed: {stats.total_entries:,}")
+    out.append(
+        f"Entries with both costUSD and model: {stats.entries_with_both:,}"
+    )
+    out.append(f"Matches (within 0.1%): {stats.matches:,}")
+    out.append(f"Mismatches: {stats.mismatches:,}")
+    out.append(f"Match rate: {match_rate:.2f}%")
+
+    if stats.mismatches > 0 and stats.model_stats:
+        out.append("")
+        out.append("=== Model Statistics ===")
+        sorted_models = sorted(
+            stats.model_stats.items(),
+            key=lambda kv: -kv[1].mismatches,
+        )
+        for model, ms in sorted_models:
+            if ms.mismatches == 0:
+                continue
+            rate = ms.matches / ms.total * 100
+            out.append(f"{model}:")
+            out.append(f"  Total entries: {ms.total:,}")
+            out.append(f"  Matches: {ms.matches:,} ({rate:.1f}%)")
+            out.append(f"  Mismatches: {ms.mismatches:,}")
+            out.append(f"  Avg % difference: {ms.avg_percent_diff:.1f}%")
+
+    if stats.discrepancies and sample_limit > 0:
+        out.append("")
+        out.append(f"=== Sample Discrepancies (first {sample_limit}) ===")
+        for d in stats.discrepancies[:sample_limit]:
+            out.append(f"File: {d.file}")
+            out.append(f"Timestamp: {d.timestamp}")
+            out.append(f"Model: {d.model}")
+            out.append(f"Original cost: ${d.original_cost:.6f}")
+            out.append(f"Calculated cost: ${d.calculated_cost:.6f}")
+            out.append(
+                f"Difference: ${d.difference:.6f} ({d.percent_diff:.2f}%)"
+            )
+            out.append(f"Tokens: {json.dumps(d.usage)}")
+            out.append("---")
+    return out
+
+
+_DEBUG_REPORT_EMITTED = False
+
+
+def _emit_debug_samples_if_set(
+    args,
+    entries_or_loader,
+    *,
+    command_label: str,
+) -> None:
+    """Emit the §7.6.2 normative stderr report exactly once per process
+    when ``args.debug`` is True (issue #89).
+
+    ``entries_or_loader`` is either a list[UsageEntry] (eager) or a
+    zero-arg callable returning list[UsageEntry] (deferred). The deferred
+    form keeps the JSONL scan off the hot path on SQL-backed cmds whose
+    --debug is rare.
+
+    The report mirrors ccusage's ``printMismatchReport`` shape per spec
+    §7.1.2; the one-time-per-process guard ensures a single CLI
+    invocation that composes multiple cmd_* doesn't double-emit. The
+    diff two-window case (``_emit_diff_debug_samples``) bypasses this
+    guard internally for the second window then sets the guard at the
+    end.
+    """
+    global _DEBUG_REPORT_EMITTED
+    if _DEBUG_REPORT_EMITTED:
+        return
+    if not getattr(args, "debug", False):
+        return
+    sample_limit = int(getattr(args, "debug_samples", 5))
+    # Negative values are rejected at argparse parse time via _nonneg_int
+    # (§7.5); the helper assumes sample_limit >= 0.
+
+    # P1.2 (issue #89 review-loop): only the loader call is wrapped — the
+    # pure compute + render functions raising would be a programmer bug,
+    # not a transient. On loader failure we degrade gracefully with a
+    # one-line stderr notice and DO set the guard so a downstream cmd_*
+    # composition doesn't retry (and re-emit) on the same transient.
+    if callable(entries_or_loader):
+        try:
+            entries = entries_or_loader()
+        except (sqlite3.DatabaseError, OSError) as exc:
+            eprint(f"cctally --debug: report unavailable: {exc}")
+            _DEBUG_REPORT_EMITTED = True
+            return
+    else:
+        entries = entries_or_loader
+    stats = _compute_pricing_mismatch_stats(entries)
+    stats.command_label = command_label
+    for line in _render_pricing_mismatch_report(stats, sample_limit):
+        eprint(line)
+    _DEBUG_REPORT_EMITTED = True
+
+
+# ---------------------------------------------------------------------------
+# Codex --debug report (issue #92).
+#
+# Codex JSONL carries NO recorded costUSD, so the Claude-side "recorded vs
+# calculated mismatch" framing does not apply. The codex variant (chosen in
+# #92's design Q&A, option 2; #89 spec §12 precedent) is a "Codex Pricing
+# Debug Report": totals header (entries processed, models seen, total
+# computed cost) + a "Sample Top Entries" block of the N highest
+# computed-cost entries, each tagged ``Recorded cost: (none)``. Reuses the
+# process-wide ``_DEBUG_REPORT_EMITTED`` guard so one CLI invocation emits a
+# single debug report regardless of which family it ran.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _CodexCostSample:
+    file: str
+    timestamp: str
+    model: str
+    calculated_cost: float
+    usage: dict
+    is_fallback: bool
+
+
+@dataclass
+class _CodexCostStats:
+    command_label: str | None = None
+    total_entries: int = 0
+    total_cost: float = 0.0
+    model_counts: dict = field(default_factory=dict)
+    fallback_models: set = field(default_factory=set)
+    samples: list = field(default_factory=list)
+
+
+def _compute_codex_cost_stats(entries):
+    """Walk ``entries: Iterable[CodexEntry]`` and compute the totals +
+    per-entry computed-cost samples that ``_render_codex_cost_report``
+    consumes (issue #92).
+
+    Unlike the Claude ``_compute_pricing_mismatch_stats`` there is no
+    recorded cost to diff against, so every entry contributes a sample.
+    Samples are collected for all entries and sorted descending by
+    computed cost; the renderer slices to ``--debug-samples``. (Memory is
+    O(entries); acceptable for typical codex histories and symmetric with
+    the Claude helper, which retains its full discrepancy list.)
+
+    Cost + fallback resolution mirror the live aggregation path:
+    ``_calculate_codex_entry_cost`` (LiteLLM token semantics) and
+    ``_resolve_codex_pricing`` (unknown model → ``gpt-5`` fallback).
+    """
+    stats = _CodexCostStats()
+    for entry in entries:
+        stats.total_entries += 1
+        stats.model_counts[entry.model] = (
+            stats.model_counts.get(entry.model, 0) + 1
+        )
+        _, is_fallback = _resolve_codex_pricing(entry.model)
+        if is_fallback:
+            stats.fallback_models.add(entry.model)
+        cost = _calculate_codex_entry_cost(
+            entry.model,
+            entry.input_tokens,
+            entry.cached_input_tokens,
+            entry.output_tokens,
+            entry.reasoning_output_tokens,
+        )
+        stats.total_cost += cost
+        stats.samples.append(_CodexCostSample(
+            file=os.path.basename(entry.source_path),
+            timestamp=entry.timestamp.isoformat(),
+            model=entry.model,
+            calculated_cost=cost,
+            usage={
+                "input_tokens": entry.input_tokens,
+                "cached_input_tokens": entry.cached_input_tokens,
+                "output_tokens": entry.output_tokens,
+                "reasoning_output_tokens": entry.reasoning_output_tokens,
+                "total_tokens": entry.total_tokens,
+            },
+            is_fallback=is_fallback,
+        ))
+    # Stable sort: equal-cost samples keep iteration order (mirrors the
+    # Claude helper's iteration-order discrepancy list).
+    stats.samples.sort(key=lambda s: -s.calculated_cost)
+    return stats
+
+
+def _render_codex_cost_report(stats, sample_limit):
+    """Return the codex --debug report as a list of stderr lines (issue #92).
+
+    Structurally parallel to ``_render_pricing_mismatch_report`` but with
+    no match/mismatch framing (codex has no recorded cost):
+
+      - Early-return ``"No Codex usage data found to analyze."`` when
+        ``total_entries == 0``.
+      - Totals header: entries processed, models seen (count desc, ties
+        by name asc; fallback models tagged ``(N, fallback→gpt-5)``),
+        total computed cost.
+      - ``Command: cctally <label>`` self-identifier when set (parity
+        with the Claude report's one non-upstream line).
+      - Sample block omitted when ``sample_limit == 0`` or no samples;
+        header prints the requested ``sample_limit`` (upstream parity).
+        Each sample carries ``Recorded cost: (none)`` and a
+        ``(fallback→gpt-5)`` model-line marker when applicable.
+    """
+    out = []
+    if stats.total_entries == 0:
+        out.append("No Codex usage data found to analyze.")
+        return out
+
+    fallback = CODEX_LEGACY_FALLBACK_MODEL
+    parts = []
+    for model, count in sorted(
+        stats.model_counts.items(), key=lambda kv: (-kv[1], kv[0]),
+    ):
+        if model in stats.fallback_models:
+            parts.append(f"{model} ({count:,}, fallback→{fallback})")
+        else:
+            parts.append(f"{model} ({count:,})")
+
+    out.append("")
+    out.append("=== Codex Pricing Debug Report ===")
+    if stats.command_label:
+        out.append(f"Command: cctally {stats.command_label}")
+    out.append(f"Total entries processed: {stats.total_entries:,}")
+    out.append(f"Models seen: {', '.join(parts)}")
+    out.append(f"Total computed cost: ${stats.total_cost:.6f}")
+
+    if stats.samples and sample_limit > 0:
+        out.append("")
+        out.append(f"=== Sample Top Entries (first {sample_limit}) ===")
+        for s in stats.samples[:sample_limit]:
+            model_line = (
+                f"{s.model} (fallback→{fallback})"
+                if s.is_fallback else s.model
+            )
+            out.append(f"File: {s.file}")
+            out.append(f"Timestamp: {s.timestamp}")
+            out.append(f"Model: {model_line}")
+            out.append("Recorded cost: (none)")
+            out.append(f"Calculated cost: ${s.calculated_cost:.6f}")
+            out.append(f"Tokens: {json.dumps(s.usage)}")
+            out.append("---")
+    return out
+
+
+def _emit_codex_debug_samples_if_set(
+    args,
+    entries,
+    *,
+    command_label: str,
+) -> None:
+    """Emit the codex --debug report once per process when ``args.debug``
+    is True (issue #92).
+
+    ``entries`` is an eager ``list[CodexEntry]`` — each ``cmd_codex_*`` body
+    already loads them via ``get_codex_entries`` before this call, so unlike
+    the Claude helper there is no deferred-loader variant. Shares the
+    process-wide ``_DEBUG_REPORT_EMITTED`` guard with
+    ``_emit_debug_samples_if_set`` so a single CLI invocation emits one
+    report regardless of family.
+    """
+    global _DEBUG_REPORT_EMITTED
+    if _DEBUG_REPORT_EMITTED:
+        return
+    if not getattr(args, "debug", False):
+        return
+    sample_limit = int(getattr(args, "debug_samples", 5))
+    stats = _compute_codex_cost_stats(entries)
+    stats.command_label = command_label
+    for line in _render_codex_cost_report(stats, sample_limit):
+        eprint(line)
+    _DEBUG_REPORT_EMITTED = True
+
+
+def _usage_entry_from_joined(je) -> "UsageEntry":
+    """Shape a ``_JoinedClaudeEntry`` into a ``UsageEntry`` so the §7.1
+    mismatch helpers can consume both pipelines uniformly (issue #89
+    spec §7.2.1).
+
+    The joined-entry shape already carries ``source_path``, ``cost_usd``,
+    and the per-token integers; this adapter is pure shape conversion
+    with no cache re-read.
+    """
+    return UsageEntry(
+        timestamp=je.timestamp,
+        model=je.model,
+        usage={
+            "input_tokens": je.input_tokens,
+            "output_tokens": je.output_tokens,
+            "cache_creation_input_tokens": je.cache_creation_tokens,
+            "cache_read_input_tokens": je.cache_read_tokens,
+        },
+        cost_usd=je.cost_usd,
+        source_path=je.source_path,
+    )
+
+
+def _resolve_session_id_for_filter(je) -> str:
+    """Mirror ``_aggregate_claude_sessions``'s session_id resolution
+    (``bin/_lib_aggregators.py:623-627``): use ``je.session_id`` when
+    set, else fall back to the filename stem of ``je.source_path``.
+
+    Used by ``cmd_session``'s ``--id`` filter on the joined-entry list
+    (spec §7.2.1.1) so a rendered session that was assigned its id via
+    the filename-stem fallback isn't silently dropped from the --debug
+    report scope.
+    """
+    if je.session_id is not None:
+        return je.session_id
+    return os.path.splitext(os.path.basename(je.source_path))[0]
+
+
+def _project_filter_matches(key, project_patterns):
+    """Mirror ``cmd_project``'s ``--project`` predicate
+    (``bin/cctally:4792-4803``): substring match against
+    ``key.display_key`` AND ``key.git_root or key.bucket_path``.
+
+    Used by ``cmd_project``'s --debug report scope so basename-collision
+    suffixes (e.g. ``foo (repos)``) are still selectable by their path
+    segment (spec §7.2.1.2). Do NOT simplify to a raw
+    ``p in (je.project_path or "")`` substring — the report scope would
+    drift from the rendered scope.
+    """
+    if not project_patterns:
+        return True
+    dname = key.display_key.lower()
+    pname = (key.git_root or key.bucket_path or "").lower()
+    return any((p in dname) or (p in pname) for p in project_patterns)
+
+
+def _emit_diff_debug_samples(args, window_a, window_b) -> None:
+    """Two-window diff report (spec §7.2.2 Pattern D).
+
+    ``cmd_diff`` aggregates two windows; emitting a single union-report
+    would conflate per-window stats. This helper emits two separate
+    reports labeled by window token, then sets ``_DEBUG_REPORT_EMITTED``
+    so a downstream cmd_* composition doesn't double-emit.
+
+    Bypasses ``_emit_debug_samples_if_set``'s one-time guard internally
+    (it would short-circuit the second window).
+    """
+    global _DEBUG_REPORT_EMITTED
+    if _DEBUG_REPORT_EMITTED:
+        return
+    if not getattr(args, "debug", False):
+        return
+    sample_limit = int(getattr(args, "debug_samples", 5))
+    # Sync intent must match `_build_diff_result` (`skip_sync=not args.sync`).
+    # Under `diff --sync --debug` the rendered diff reflects freshly-synced
+    # JSONL while these debug stats, if they skipped sync, would be computed
+    # from the STALE cache — misleading in precisely the stale-cache case
+    # `--sync` exists to fix. So honor `--sync` here too: the first
+    # `get_entries(skip_sync=False)` runs the delta ingest, and every
+    # subsequent read (the second window here + `_build_diff_result`'s own
+    # reads) is a cheap delta no-op (file size/offset unchanged) — no
+    # redundant full walk. Without `--sync`, keep skipping (debug observes
+    # the cache as-is).
+    skip_sync = not bool(getattr(args, "sync", False))
+    try:
+        for window, label_letter, token in (
+            (window_a, "A", getattr(args, "a", "")),
+            (window_b, "B", getattr(args, "b", "")),
+        ):
+            try:
+                # Reuse the SAME half-open window accessor the rendered diff
+                # aggregation uses (`_diff_iter_claude_entries`): `ParsedWindow`
+                # exposes `start_utc`/`end_utc` (NOT `.start`/`.end`), and its
+                # `end_utc` is documented exclusive — the helper trims by 1 µs
+                # before hitting the inclusive-end shared cache reader so the
+                # debug report scopes to exactly the entries the rendered diff
+                # counts. Reading via `get_entries(window.start, window.end)`
+                # both raised AttributeError (wrong field names) and would have
+                # over-counted the exclusive end boundary.
+                entries = list(
+                    _diff_iter_claude_entries(window, skip_sync=skip_sync)
+                )
+            except (sqlite3.DatabaseError, OSError) as exc:
+                eprint(
+                    f"cctally --debug: window {label_letter} report "
+                    f"unavailable: {exc}"
+                )
+                continue
+            # `_diff_iter_claude_entries` yields `_JoinedClaudeEntry`, which
+            # has no `.usage` attribute; adapt to `UsageEntry` before the
+            # mismatch compute, mirroring cmd_project / cmd_session. The stats
+            # helper reads `entry.usage`, so passing raw joined entries here
+            # crashed every priced entry with AttributeError — and the inner
+            # `try/except` only catches DatabaseError/OSError, so the crash
+            # escaped to main()'s generic handler (exit 1, zero diff output).
+            stats = _compute_pricing_mismatch_stats(
+                _usage_entry_from_joined(je) for je in entries
+            )
+            stats.command_label = f"diff (Window {label_letter}: {token})"
+            for line in _render_pricing_mismatch_report(stats, sample_limit):
+                eprint(line)
+    finally:
+        # P1.2 (issue #89 review-loop): set the guard in finally so a
+        # downstream cmd_* composition doesn't double-emit even if one
+        # window raised — the partial output we did emit is enough.
+        _DEBUG_REPORT_EMITTED = True
+
+
+def _load_claude_config_for_args(args: argparse.Namespace) -> "dict":
+    """Load config honoring the ccusage ``--config <path>`` per-invocation override.
+
+    Thin shim over :func:`load_config` so the 10 in-scope Claude reporting
+    commands (spec §3 T1.6 / issue #88) surface the override behavior
+    uniformly. When ``args.config`` is set, reads from that explicit path
+    only — no first-run create, no writer-lock acquisition, no mutation
+    of the persisted default config at ``_cctally_core.CONFIG_PATH``.
+    Missing / unreadable / non-object-JSON paths raise ``SystemExit(2)``
+    with a clear stderr message (see ``_load_config_from_explicit_path``).
+    When ``args.config`` is unset (or absent), behavior is identical to
+    a bare ``load_config()`` call.
+    """
+    return load_config(getattr(args, "config", None))
+
+
 def _resolve_codex_tz_name(args: argparse.Namespace,
                            config: "dict | None") -> "str | None":
     """Resolve the IANA tz NAME (or None for host-local) used by Codex
@@ -1333,6 +2006,64 @@ def _supports_color_stdout() -> bool:
     return False
 
 
+def _resolve_color_enabled(args: argparse.Namespace) -> bool:
+    """Resolve effective color-on/off for the 2 real ANSI Claude cmds.
+
+    Spec §7.3 (issue #86 Session A). Precedence (top wins):
+
+      1. ``args.no_color``  → False (deny-wins; overrides ``FORCE_COLOR``
+         env AND a co-supplied ``--color`` flag).
+      2. ``args.color``     → True (overrides ``NO_COLOR`` env).
+      3. ``FORCE_COLOR``    → True.
+      4. ``NO_COLOR``       → False.
+      5. ``CI`` env with a TTY stdout → True (CI forces color, but only
+                            when stdout is itself a terminal — a piped /
+                            redirected stdout under CI stays plain text,
+                            issue #100); else ``isatty(stdout)`` with
+                            non-dumb TERM → True (the diff/project
+                            auto-detect).
+      6. else               → False (incl. a piped stdout under CI).
+
+    The helper is consumed by ``cmd_project`` and ``cmd_diff`` — the only
+    two in-scope Claude cmds whose renderers honor color. The other 8
+    in-scope cmds parse ``--color`` / ``--no-color`` as documented no-op
+    surface (spec §3 T1.5).
+
+    The rung-5 auto-detect keys on ``sys.stdout.isatty()`` ONLY — NOT the
+    shared ``_supports_color_stdout()`` (which is stdout-OR-stderr to match
+    ccusage's picocolors behavior). ``diff``'s pre-Session-A computation was
+    ``sys.stdout.isatty() and not args.no_color`` (stdout-only), and spec
+    §7.3 specifies preserving the *existing* auto-detect on the no-flag
+    rungs. Routing the fallback through the stdout-OR-stderr helper would
+    write ANSI into the pipe under ``cctally diff … | cat`` (stderr is still
+    a TTY) — a backwards-incompatible regression for plain-text consumers.
+    """
+    # Rung 1 — deny-wins: --no-color always disables.
+    if getattr(args, "no_color", False):
+        return False
+    # Rung 2 — --color overrides env (NO_COLOR auto-detect).
+    if getattr(args, "color", False):
+        return True
+    # Rung 3 — FORCE_COLOR env always enables (any value).
+    if "FORCE_COLOR" in os.environ:
+        return True
+    # Rung 4 — NO_COLOR env always disables (any value).
+    if "NO_COLOR" in os.environ:
+        return False
+    # Rung 5 — CI forces color, but ONLY with a TTY stdout; else stdout-only
+    # isatty with non-dumb TERM. Both branches key on sys.stdout.isatty()
+    # (NOT the stdout-OR-stderr _supports_color_stdout) so a piped stdout —
+    # under CI or otherwise — stays uncolored, preserving diff/project's
+    # pre-Session-A plain-text-on-pipe contract (issue #100). CI still wins
+    # over a dumb TERM when stdout is a real terminal (picocolors parity).
+    if sys.stdout.isatty():
+        if "CI" in os.environ:
+            return True
+        return os.environ.get("TERM", "").lower() != "dumb"
+    # Rung 6 — no flag, no env, non-tty stdout (incl. a piped stdout under CI).
+    return False
+
+
 def _style_ansi(text: str, code: str, enabled: bool) -> str:
     if not enabled:
         return text
@@ -1373,6 +2104,7 @@ def _boxed_table(
     aligns: list[str] | None = None,
     *,
     color_header: bool = True,
+    compact: bool = False,
 ) -> str:
     if not headers:
         return ""
@@ -1439,10 +2171,17 @@ def _boxed_table(
     def _dim(s: str) -> str:
         return _style_ansi(s, "90", color_enabled)
 
+    # Issue #91 (Shape B): ``compact`` drops the 1-space cell padding to
+    # 0 on this content-sized table (which has no proportional-width path
+    # to force). Borders and rows both key off ``pad`` so the default
+    # (``pad == 1``) reproduces the prior output byte-for-byte.
+    pad = 0 if compact else 1
+    pad_s = " " * pad
+
     def make_border(left: str, mid: str, right: str) -> str:
         return _dim(
             left
-            + mid.join(chars["h"] * (w + 2) for w in widths)
+            + mid.join(chars["h"] * (w + 2 * pad) for w in widths)
             + right
         )
 
@@ -1459,9 +2198,9 @@ def _boxed_table(
         v = _dim(chars["v"])
         return (
             v
-            + " "
-            + f" {v} ".join(styled_cells)
-            + " "
+            + pad_s
+            + f"{pad_s}{v}{pad_s}".join(styled_cells)
+            + pad_s
             + v
         )
 
@@ -1542,6 +2281,7 @@ def _layout_cache_table(
     wide_text_min: int = 15,
     narrow_text_min: int = 12,
     droppable_col_index: int | None = None,
+    compact: bool = False,
 ) -> str:
     """Shared responsive-width table layout for cache-report renderers.
 
@@ -1645,7 +2385,11 @@ def _layout_cache_table(
         term_width = int(os.environ.get("COLUMNS", "120"))
 
     border_overhead = 3 * num_cols + 1
-    compact_mode = sum(col_widths) + border_overhead > term_width
+    # Issue #91 (Shape A): the ``compact`` kwarg forces the responsive
+    # scale-down path regardless of terminal width, mirroring
+    # ``_render_project_table`` / ``_render_bucket_table``. Auto-detected
+    # width-overflow continues to trigger the same path as before.
+    compact_mode = compact or (sum(col_widths) + border_overhead > term_width)
 
     if compact_mode:
         available = term_width - border_overhead
@@ -1857,7 +2601,9 @@ def _layout_cache_table(
     return "\n".join(lines)
 
 
-def _render_cache_day_rows(rows: list[CacheRow], title: str) -> str:
+def _render_cache_day_rows(
+    rows: list[CacheRow], title: str, *, compact: bool = False,
+) -> str:
     """Render daily-mode cache report.
 
     Columns: Date, Models, Cache %, Input, Cache Create, Cache Read,
@@ -1986,12 +2732,13 @@ def _render_cache_day_rows(rows: list[CacheRow], title: str) -> str:
         wide_text_min=15,
         narrow_text_min=12,
         droppable_col_index=3,                         # Input column
+        compact=compact,
     )
 
 
 def _render_cache_session_rows(
     rows: list[CacheRow], title: str,
-    *, tz: "ZoneInfo | None" = None,
+    *, tz: "ZoneInfo | None" = None, compact: bool = False,
 ) -> str:
     """Render session-mode cache report.
 
@@ -2135,6 +2882,7 @@ def _render_cache_session_rows(
         wide_text_min=18,
         narrow_text_min=12,
         droppable_col_index=4,                                 # Input column
+        compact=compact,
     )
 
 
@@ -2144,16 +2892,20 @@ def _render_cache_report_table(
     *,
     mode: Literal["day", "session"] = "day",
     tz: "ZoneInfo | None" = None,
+    compact: bool = False,
 ) -> str:
     """Dispatcher: routes to daily or session renderer based on mode.
 
     ``tz`` is the resolved display zone (None = host local). Day-mode
     rows have no clock-instant cells (date strings only) so the parameter
     is currently consumed only by the session-mode renderer.
+
+    ``compact`` (issue #91, Shape A) forces ``_layout_cache_table``'s
+    responsive scale-down branch regardless of terminal width.
     """
     if mode == "session":
-        return _render_cache_session_rows(rows, title, tz=tz)
-    return _render_cache_day_rows(rows, title)
+        return _render_cache_session_rows(rows, title, tz=tz, compact=compact)
+    return _render_cache_day_rows(rows, title, compact=compact)
 
 
 def _trend_row_recency_seconds(row: dict[str, Any]) -> float:
@@ -2628,7 +3380,16 @@ def _backfill_five_hour_blocks(conn: sqlite3.Connection) -> int:
         now_iso = now_utc_iso()
         now_dt = parse_iso_datetime(now_iso, "now")
 
-        conn.execute("BEGIN")
+        # BEGIN IMMEDIATE (not deferred): this transaction's first DML is a
+        # READ (min_row/max_row below), so a plain deferred BEGIN takes a read
+        # snapshot and only tries to upgrade to the write lock at the first
+        # INSERT OR IGNORE. Under concurrent first-run openers, a competing
+        # commit landing between that read and the first write makes the upgrade
+        # fail with SQLITE_BUSY_SNAPSHOT *immediately* — busy_timeout cannot
+        # absorb it, and the whole backfill rolls back. Acquiring the write lock
+        # up front serializes the backfill cleanly behind busy_timeout instead.
+        # See cctally-dev#87.
+        conn.execute("BEGIN IMMEDIATE")
         try:
             for key in keys:
                 # MIN-captured row defines the immutable block boundary
@@ -3405,17 +4166,19 @@ def _load_recorded_five_hour_windows(
 
 def cmd_blocks(args: argparse.Namespace) -> int:
     """Show usage report grouped by 5-hour session blocks."""
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    _bridge_z_into_tz(args, config)
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
 
     now_utc = _command_as_of()
-    # Parse --since / --until into datetime range
+    # Parse --since / --until into datetime range. Session A (spec §7.1.1)
+    # routes through the centralized dual-form helper so YYYY-MM-DD also
+    # works and the error message matches the other in-scope cmds.
     if args.since:
         try:
-            since_date = dt.datetime.strptime(args.since, "%Y%m%d")
+            since_date = _parse_dual_form_date(args.since, "--since")
         except ValueError:
-            eprint(f"Error: --since must be YYYYMMDD format, got '{args.since}'")
             return 1
         range_start = since_date.replace(tzinfo=dt.timezone.utc)
     else:
@@ -3424,9 +4187,8 @@ def cmd_blocks(args: argparse.Namespace) -> int:
 
     if args.until:
         try:
-            until_date = dt.datetime.strptime(args.until, "%Y%m%d")
+            until_date = _parse_dual_form_date(args.until, "--until")
         except ValueError:
-            eprint(f"Error: --until must be YYYYMMDD format, got '{args.until}'")
             return 1
         # End of that day
         range_end = until_date.replace(
@@ -3439,6 +4201,10 @@ def cmd_blocks(args: argparse.Namespace) -> int:
     # Collect all entries
     all_entries = get_entries(range_start, range_end)
 
+    _emit_debug_samples_if_set(
+        args, all_entries, command_label="blocks",
+    )
+
     # Load recorded 5-hour reset timestamps. Widen both bounds by
     # BLOCK_DURATION: a window covers [R - 5h, R), so a reset R just
     # before ``range_start`` can still anchor entries near it, and a
@@ -3503,8 +4269,13 @@ def cmd_blocks(args: argparse.Namespace) -> int:
         print(_blocks_to_json(blocks))
         return 0
 
-    # Table output
-    print(_render_blocks_table(blocks, breakdown=args.breakdown, now=now_utc, tz=tz))
+    # Table output. Session A (spec §7.6.1; Review-A P2-B): thread
+    # --compact through so the renderer's scale-down branch fires
+    # regardless of terminal width when the flag is set.
+    print(_render_blocks_table(
+        blocks, breakdown=args.breakdown, now=now_utc, tz=tz,
+        compact=getattr(args, "compact", False),
+    ))
     return 0
 
 
@@ -3607,6 +4378,45 @@ def _maybe_swap_active_block_to_canonical(
     blocks[active_idx] = rebuilt
 
 
+def _try_dual_form_date(raw: str) -> dt.datetime | None:
+    """Parse ``YYYY-MM-DD`` / ``YYYYMMDD`` WITHOUT emitting an error.
+
+    Returns the parsed naive datetime, or ``None`` when ``raw`` matches
+    neither form. The non-eprinting core of ``_parse_dual_form_date``:
+    callers that have their own fallback for a non-dual-form input must
+    use this, because ``_parse_dual_form_date`` eprints before it raises
+    — so a successful fallback parse would otherwise leak a spurious
+    "must be YYYY-MM-DD" line to stderr (cache-report's ``parse_iso_datetime``
+    second-chance, issue #101).
+    """
+    for fmt in ("%Y-%m-%d", "%Y%m%d"):
+        try:
+            return dt.datetime.strptime(raw, fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def _parse_dual_form_date(raw: str, flag: str) -> dt.datetime:
+    """Parse a CLI date arg accepting both ``YYYY-MM-DD`` and ``YYYYMMDD``.
+
+    Tries ``%Y-%m-%d`` first (the more readable upstream ccusage / codex
+    sharedArgs preference), then ``%Y%m%d``. On failure, emits a stderr
+    error and raises ``ValueError``. Callers swallow the ``ValueError``
+    and return exit code 1.
+
+    Promoted from ``_resolve_codex_range._parse_date_arg`` so Claude
+    reporting commands can share the dual-form contract (issue #86
+    Session A, spec §7.1.1). Centralizes the error message so the eight
+    in-scope date-taking commands all surface the same diagnostic.
+    """
+    naive = _try_dual_form_date(raw)
+    if naive is not None:
+        return naive
+    eprint(f"Error: {flag} must be YYYY-MM-DD or YYYYMMDD format, got '{raw}'")
+    raise ValueError
+
+
 def _parse_cli_date_range(
     args: argparse.Namespace,
     *,
@@ -3639,14 +4449,11 @@ def _parse_cli_date_range(
     the given date — this avoids DST-boundary drift that would occur if
     we used today's offset (via `datetime.now().astimezone().tzinfo`).
     """
-    def _parse_date_arg(raw: str, flag: str) -> dt.datetime:
-        for fmt in ("%Y-%m-%d", "%Y%m%d"):
-            try:
-                return dt.datetime.strptime(raw, fmt)
-            except ValueError:
-                continue
-        eprint(f"Error: {flag} must be YYYY-MM-DD or YYYYMMDD format, got '{raw}'")
-        raise ValueError
+    # Local binding to the module-level dual-form helper (spec §7.1.1).
+    # Keeps the diff inside _parse_cli_date_range minimal while sharing
+    # the centralized error message with cmd_blocks, _parse_date_filter,
+    # and _parse_window_arg.
+    _parse_date_arg = _parse_dual_form_date
 
     tz: Any = None
     if tz_name:
@@ -3701,7 +4508,12 @@ def _parse_cli_date_range(
 def cmd_daily(args: argparse.Namespace) -> int:
     """Show usage report grouped by display-timezone date."""
     _share_validate_args(args)
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    # Session A (spec §7.2): bridge -z/--timezone into args.tz so the
+    # existing resolve_display_tz precedence absorbs the new alias. The
+    # canonical --tz still wins (it's set on the namespace before this
+    # bridge fires); when --tz is unset and -z is supplied, use -z.
+    _bridge_z_into_tz(args, config)
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
 
@@ -3717,6 +4529,10 @@ def cmd_daily(args: argparse.Namespace) -> int:
     # Collect entries.
     all_entries = get_entries(range_start, range_end)
 
+    _emit_debug_samples_if_set(
+        args, all_entries, command_label="daily",
+    )
+
     # Build the unified daily view (spec §5.1: gap-free; the dashboard
     # heatmap's contiguous-window materialization stays at the dashboard
     # envelope adapter so CLI byte-stability is preserved). Consume
@@ -3775,6 +4591,7 @@ def cmd_daily(args: argparse.Namespace) -> int:
         title_suffix="Daily",
         compact_split_fn=_daily_compact_split,
         breakdown=args.breakdown,
+        compact=getattr(args, "compact", False),
     ))
     return 0
 
@@ -3782,7 +4599,8 @@ def cmd_daily(args: argparse.Namespace) -> int:
 def cmd_monthly(args: argparse.Namespace) -> int:
     """Show usage report grouped by display-timezone calendar month."""
     _share_validate_args(args)
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    _bridge_z_into_tz(args, config)
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
 
@@ -3797,6 +4615,10 @@ def cmd_monthly(args: argparse.Namespace) -> int:
 
     all_entries = get_entries(range_start, range_end)
 
+    _emit_debug_samples_if_set(
+        args, all_entries, command_label="monthly",
+    )
+
     # Build the unified monthly view (spec §5.2: drops boundary-spillover
     # bucket; computes delta_cost_pct internally). Consume
     # `view.aggregated` (BucketUsage tuple, newest-first) for CLI byte-
@@ -3849,6 +4671,7 @@ def cmd_monthly(args: argparse.Namespace) -> int:
         title_suffix="Monthly",
         compact_split_fn=_monthly_compact_split,
         breakdown=args.breakdown,
+        compact=getattr(args, "compact", False),
     ))
     return 0
 
@@ -3856,7 +4679,8 @@ def cmd_monthly(args: argparse.Namespace) -> int:
 def cmd_weekly(args: argparse.Namespace) -> int:
     """Show Claude usage grouped by subscription week."""
     _share_validate_args(args)
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    _bridge_z_into_tz(args, config)
     args._resolved_tz = resolve_display_tz(args, config)
 
     now_utc = _command_as_of()
@@ -3869,8 +4693,12 @@ def cmd_weekly(args: argparse.Namespace) -> int:
 
     # Build the subscription-week list spanning the range. Boundaries are
     # anchored in `weekly_usage_snapshots` when available and otherwise
-    # extrapolated (see `_compute_subscription_weeks`).
-    weeks = _compute_subscription_weeks(conn, range_start, range_end)
+    # extrapolated (see `_compute_subscription_weeks`). Pass the
+    # `--config`-honoring resolved config (issue #88) so the no-snapshot
+    # calendar-week fallback uses the explicit override's `week_start`.
+    weeks = _compute_subscription_weeks(
+        conn, range_start, range_end, config=config,
+    )
 
     # Fetch entries and aggregate.
     # Cover each SubWeek's full [start_ts, end_ts) on the range_start side —
@@ -3889,6 +4717,10 @@ def cmd_weekly(args: argparse.Namespace) -> int:
         fetch_start = range_start
     all_entries = get_entries(fetch_start, range_end)
 
+    _emit_debug_samples_if_set(
+        args, all_entries, command_label="weekly",
+    )
+
     # Bound the usage-snapshot lookup to `<= range_end` so historical
     # `--until <past date>` queries pick the usage% that was current at
     # the end of the requested window rather than the globally latest
@@ -3966,6 +4798,7 @@ def cmd_weekly(args: argparse.Namespace) -> int:
         weeks=weeks,
         compact_split_fn=_daily_compact_split,
         breakdown=args.breakdown,
+        compact=getattr(args, "compact", False),
     ))
     return 0
 
@@ -3989,6 +4822,7 @@ def cmd_codex_daily(args: argparse.Namespace) -> int:
     range_start, range_end = range
 
     entries = get_codex_entries(range_start, range_end)
+    _emit_codex_debug_samples_if_set(args, entries, command_label="codex-daily")
     # Route through ``build_codex_daily_view`` (issue #58). The View
     # wraps ``_aggregate_codex_daily`` without changing it — preserves
     # LiteLLM token semantics, intentional dedup vs upstream, and
@@ -4048,6 +4882,7 @@ def cmd_codex_monthly(args: argparse.Namespace) -> int:
     range_start, range_end = range
 
     entries = get_codex_entries(range_start, range_end)
+    _emit_codex_debug_samples_if_set(args, entries, command_label="codex-monthly")
     # Route through ``build_codex_monthly_view`` (issue #58).
     view = build_codex_monthly_view(
         entries, now_utc=_command_as_of(), tz_name=tz_name,
@@ -4107,6 +4942,7 @@ def cmd_codex_weekly(args: argparse.Namespace) -> int:
     week_start_idx = WEEKDAY_MAP[week_start_name]
 
     entries = get_codex_entries(range_start, range_end)
+    _emit_codex_debug_samples_if_set(args, entries, command_label="codex-weekly")
     # Route through ``build_codex_weekly_view`` (issue #58).
     view = build_codex_weekly_view(
         entries, now_utc=now_utc, tz_name=tz_name,
@@ -4167,6 +5003,7 @@ def cmd_codex_session(args: argparse.Namespace) -> int:
     range_start, range_end = range
 
     entries = get_codex_entries(range_start, range_end)
+    _emit_codex_debug_samples_if_set(args, entries, command_label="codex-session")
     # Route through ``build_codex_session_view`` (issue #58). View rows
     # come descending by last_activity (aggregator default + upstream
     # parity); --order asc reverses.
@@ -4426,7 +5263,10 @@ def _project_sort_key(row: dict, sort_by: str, order: str):
 def cmd_project(args: argparse.Namespace) -> int:
     """Roll entries up by project (git-root) with per-project usage attribution."""
     _share_validate_args(args)
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    # Session A (spec §7.2): bridge -z/--timezone into args.tz so the
+    # existing resolve_display_tz precedence absorbs the new alias.
+    _bridge_z_into_tz(args, config)
     args._resolved_tz = resolve_display_tz(args, config)
 
     # Flag-combination validation (must run before any expensive work).
@@ -4477,7 +5317,7 @@ def cmd_project(args: argparse.Namespace) -> int:
         # false, which would otherwise wrongly fall through to the Monday
         # fallback for non-Monday-reset accounts).
         current_weeks = _compute_subscription_weeks(
-            conn, now, now + dt.timedelta(microseconds=1)
+            conn, now, now + dt.timedelta(microseconds=1), config=config,
         )
         if current_weeks:
             cw_start = parse_iso_datetime(
@@ -4497,7 +5337,9 @@ def cmd_project(args: argparse.Namespace) -> int:
     # Pre-compute subscription-week bounds for the query window so each entry
     # can be bucketed onto a canonical subscription-week start_ts. Mirrors
     # `_aggregate_weekly`'s bisect pattern (first-match-wins on overlap).
-    subweeks = _compute_subscription_weeks(conn, since_dt, until_dt)
+    subweeks = _compute_subscription_weeks(
+        conn, since_dt, until_dt, config=config,
+    )
     parsed_bounds: list[tuple[dt.datetime, dt.datetime]] = []
     for sw in subweeks:
         s_dt = parse_iso_datetime(sw.start_ts, "week.start_ts").astimezone(dt.timezone.utc)
@@ -4548,7 +5390,45 @@ def cmd_project(args: argparse.Namespace) -> int:
     unknown_entry_count = 0
     missing_sid_count = 0
 
-    for entry in get_claude_session_entries(scan_start, scan_end):
+    # Issue #89: materialize the joined-entry iterator once so we can
+    # (a) pre-compute the --debug report's scope (entries passing all
+    # rendered-row filters — user slice + --model + --project) BEFORE
+    # the aggregation loop runs and (b) preserve the existing
+    # aggregation semantics (denominator widened to ALL entries; visible
+    # rows only the post-filter subset). The list is small enough to
+    # hold (entries already in memory via the cache row factory).
+    joined_entries_all = list(get_claude_session_entries(scan_start, scan_end))
+
+    # Build the --debug report dataset: skip synthetic + out-of-window
+    # entries, then apply --model and --project filters (mirroring the
+    # exact predicate at the aggregation loop below). This must match
+    # the rendered scope, NOT the denominator scope.
+    if getattr(args, "debug", False):
+        filtered_for_report = []
+        for je in joined_entries_all:
+            if je.model == "<synthetic>":
+                continue
+            if _week_start_for(je.timestamp) is None:
+                continue
+            if je.timestamp < since_dt or je.timestamp > until_dt:
+                continue
+            if model_patterns:
+                mname = (je.model or "").lower()
+                if not any(p in mname for p in model_patterns):
+                    continue
+            key_for_filter = _resolve_project_key(
+                je.project_path, args.group, resolver_cache,
+            )
+            if not _project_filter_matches(key_for_filter, project_patterns):
+                continue
+            filtered_for_report.append(je)
+        _emit_debug_samples_if_set(
+            args,
+            [_usage_entry_from_joined(je) for je in filtered_for_report],
+            command_label="project",
+        )
+
+    for entry in joined_entries_all:
         # Skip synthetic entries (Claude Code internal markers) to match
         # `_aggregate_cache_by_session` / `_aggregate_claude_sessions`.
         if entry.model == "<synthetic>":
@@ -4813,13 +5693,21 @@ def cmd_project(args: argparse.Namespace) -> int:
         eprint("No project usage found in range.")
         return 0
 
+    # Session A (spec §7.3): the new --color flag overrides NO_COLOR
+    # env; --no-color overrides FORCE_COLOR env; deny-wins on the
+    # --color + --no-color clash. _resolve_color_enabled returns the
+    # effective bool; pass it as ``color=`` so the renderer skips its
+    # internal _supports_color_stdout() auto-detect (which would
+    # re-consult NO_COLOR and incorrectly disable color when the user
+    # passed --color under NO_COLOR=1).
     print(_render_project_table(
         sorted_rows,
         title=title,
         breakdown=args.breakdown,
         weeks_missing_snapshot=len(weeks_missing_snapshot),
         weeks_in_range=len(weeks_in_range),
-        no_color=args.no_color,
+        color=_resolve_color_enabled(args),
+        compact=args.compact,
     ))
     return 0
 
@@ -4909,7 +5797,10 @@ def cmd_diff(args: argparse.Namespace) -> int:
 
     # Validation already happened via _argparse_tz; resolve now to a ZoneInfo
     # (or None for "local") and derive the IANA name for window resolution.
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    # Session A (spec §7.2): bridge -z/--timezone into args.tz so the
+    # existing resolve_display_tz precedence absorbs the new alias.
+    _bridge_z_into_tz(args, config)
     tz_obj = resolve_display_tz(args, config)
     args._resolved_tz = tz_obj
     tz_name = (tz_obj.key if tz_obj is not None else _local_tz_name())
@@ -4934,16 +5825,12 @@ def cmd_diff(args: argparse.Namespace) -> int:
         print(f"diff: {exc}", file=sys.stderr)
         return 2
 
-    threshold = NoiseThreshold(
-        show_all=bool(args.show_all),
-        user_override=(args.min_delta_usd is not None
-                       or args.min_delta_pct is not None),
-    )
-    if args.min_delta_usd is not None:
-        threshold = dataclasses.replace(threshold, min_delta_usd=args.min_delta_usd)
-    if args.min_delta_pct is not None:
-        threshold = dataclasses.replace(threshold, min_delta_pct=args.min_delta_pct)
-
+    # Validate the remaining CLI surface (`--only` / `--with`) BEFORE the
+    # `--debug` emission below. `_emit_diff_debug_samples` prints reports and,
+    # under `--sync`, runs a cache ingest (a local-state mutation). A
+    # fail-fast usage error like `diff ... --only bogus --debug --sync` must
+    # not print unrelated debug output or touch the cache before returning
+    # exit 2 — so the validation gate has to precede the debug scan.
     sections_requested = ["overall", "models", "projects", "cache"]
     if args.only is not None:
         sections_requested = [s.strip() for s in args.only.split(",") if s.strip()]
@@ -4970,6 +5857,23 @@ def cmd_diff(args: argparse.Namespace) -> int:
                 )
                 return 1
 
+    # Issue #89 spec §7.2.2 Pattern D: emit one --debug report per window
+    # before any rendering, with window-A then window-B labels. Runs only
+    # after the validation gate above so a usage error fails fast without
+    # debug output or a cache sync.
+    if getattr(args, "debug", False):
+        _emit_diff_debug_samples(args, window_a, window_b)
+
+    threshold = NoiseThreshold(
+        show_all=bool(args.show_all),
+        user_override=(args.min_delta_usd is not None
+                       or args.min_delta_pct is not None),
+    )
+    if args.min_delta_usd is not None:
+        threshold = dataclasses.replace(threshold, min_delta_usd=args.min_delta_usd)
+    if args.min_delta_pct is not None:
+        threshold = dataclasses.replace(threshold, min_delta_pct=args.min_delta_pct)
+
     try:
         result = _build_diff_result(
             window_a, window_b,
@@ -5002,12 +5906,18 @@ def cmd_diff(args: argparse.Namespace) -> int:
         print(_diff_render_json(result, options=options))
         return 0
 
-    color = sys.stdout.isatty() and not args.no_color
+    # Session A (spec §7.3): route through the new color resolver so
+    # the bool --color flag overrides NO_COLOR env, --no-color overrides
+    # FORCE_COLOR env, and deny-wins on the --color + --no-color clash.
+    # The old computation (sys.stdout.isatty() and not args.no_color)
+    # only honored --no-color + isatty; the resolver supersedes both
+    # with the full spec §7.3 precedence.
+    color = _resolve_color_enabled(args)
     width = args.width or shutil.get_terminal_size().columns
     width = max(80, min(width, 160))
     print(_diff_render_full_output(
         result, color=color, width=width, raw_aggregates=result.raw_totals,
-        tz=tz_obj,
+        tz=tz_obj, compact=args.compact,
     ))
     return 0
 
@@ -5015,7 +5925,8 @@ def cmd_diff(args: argparse.Namespace) -> int:
 def cmd_session(args: argparse.Namespace) -> int:
     """Show Claude usage grouped by sessionId (merges resumed-across-files sessions)."""
     _share_validate_args(args)
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    _bridge_z_into_tz(args, config)
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
 
@@ -5029,6 +5940,27 @@ def cmd_session(args: argparse.Namespace) -> int:
     range_start, range_end = range
 
     entries = get_claude_session_entries(range_start, range_end)
+
+    # Issue #89: --debug report describes the joined-entry list filtered
+    # by --id (post-fallback session_id resolution) when set, matching
+    # the rendered scope of `sessions`.
+    # `is not None`, not truthiness: an explicit empty `--id ''` must still
+    # engage the filter (→ empty render), not silently fall through to
+    # "describe/show all sessions" (code-review finding). Mirrored on the
+    # post-aggregation filter below.
+    if getattr(args, "id", None) is not None:
+        joined_for_report = [
+            je for je in entries
+            if _resolve_session_id_for_filter(je) == args.id
+        ]
+    else:
+        joined_for_report = entries
+    _emit_debug_samples_if_set(
+        args,
+        [_usage_entry_from_joined(je) for je in joined_for_report],
+        command_label="session",
+    )
+
     # Unified view-model kernel (spec §6.5). `limit=None` keeps the
     # full aggregator output — `cctally session` has no `--limit` flag
     # and emits every session in the requested range. `view.aggregated`
@@ -5044,6 +5976,16 @@ def cmd_session(args: argparse.Namespace) -> int:
     )
     sessions = list(view.aggregated)
 
+    # Session A (spec §7.4): exact-string filter on sessionId. Applied
+    # AFTER aggregation (so resume-merged sessions across multiple JSONL
+    # files are matched against their post-merge id) and BEFORE the
+    # `--order asc` reversal and the JSON / share / table render
+    # branches. Unknown id → empty `sessions` list, which falls through
+    # to the existing "no sessions" branch (table: "No Claude session
+    # data found."; JSON: `{"sessions": []}`).
+    if getattr(args, "id", None) is not None:  # explicit '' still filters
+        sessions = [s for s in sessions if s.session_id == args.id]
+
     # Shareable-reports gate: --format short-circuits the JSON / table
     # dispatch via `_share_render_and_emit`. The mutex in
     # `_add_share_args` keeps `--format` and `--json` from coexisting.
@@ -5075,8 +6017,17 @@ def cmd_session(args: argparse.Namespace) -> int:
         # sub-rows aren't in the share spec scope). Same convention as
         # cmd_daily / cmd_project.
         display_tz_str = _share_display_tz_label(tz)
+        # Session A (spec §7.4): `_build_session_snapshot` reads
+        # `view.aggregated`, so the `--id` filter applied to the local
+        # `sessions` list above would otherwise be ignored for share
+        # exports (HTML/Markdown/SVG). Hand the builder a view whose
+        # `aggregated` is the filtered list so `--id` is honored across
+        # every output path. The builder reads only `aggregated` (never
+        # `rows` / `total_sessions`), so the parallel-tuple mismatch from
+        # the replace is inert here.
+        share_view = dataclasses.replace(view, aggregated=tuple(sessions))
         snap = _build_session_snapshot(
-            view,
+            share_view,
             period_start=range_start,
             period_end=range_end,
             display_tz=display_tz_str,
@@ -5101,10 +6052,14 @@ def cmd_session(args: argparse.Namespace) -> int:
         print("No Claude session data found.")
         return 0
 
+    # Session A (spec §7.6.1; Review-A P2-B): thread --compact through
+    # so the renderer's scale-down branch fires regardless of terminal
+    # width when the flag is set.
     print(_render_claude_session_table(
         sessions,
         breakdown=args.breakdown,
         tz=tz,
+        compact=getattr(args, "compact", False),
     ))
     return 0
 
@@ -7178,19 +8133,19 @@ def _latest_seven_day_and_window(
 
 
 def _parse_date_filter(value: str, flag_name: str) -> str:
-    """Parse ``YYYYMMDD`` into a ``YYYY-MM-DD`` ISO date for SQL ``WHERE`` clauses.
+    """Parse ``YYYY-MM-DD`` or ``YYYYMMDD`` into an ISO date for SQL ``WHERE`` clauses.
 
     Used by ``cmd_five_hour_blocks`` ``--since``/``--until``. Mirrors the
-    upstream ccusage convention. Raises ``ValueError`` with a subcommand-only
-    error prefix on bad input; the caller is responsible for printing to
-    stderr and choosing the exit code.
+    upstream ccusage convention. Routes through the centralized
+    ``_parse_dual_form_date`` (spec §7.1.1) so the dual-form contract and
+    error message are shared with cmd_blocks / cmd_daily / etc.
+
+    The helper already eprints its own diagnostic and raises a bare
+    ``ValueError``; we propagate that bare exception so callers can
+    return an exit code without double-printing (Review-A P1-1; mirrors
+    the bare-re-raise pattern used by ``cmd_cache_report``).
     """
-    try:
-        return dt.datetime.strptime(value, "%Y%m%d").date().isoformat()
-    except ValueError as e:
-        raise ValueError(
-            f"five-hour-blocks: {flag_name} expects YYYYMMDD (got '{value}')"
-        ) from e
+    return _parse_dual_form_date(value, flag_name).date().isoformat()
 
 
 def _load_breakdown(
@@ -7219,7 +8174,10 @@ def _load_breakdown(
 def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
     """List API-anchored 5h blocks with rollup totals + 7d-drift columns."""
     _share_validate_args(args)
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    # Session A (spec §7.2): bridge -z/--timezone into args.tz before
+    # resolve_display_tz so the new alias precedence lands.
+    _bridge_z_into_tz(args, config)
     args._resolved_tz = resolve_display_tz(args, config)
     # Pin "now" once (CCTALLY_AS_OF for fixture-pinned harnesses; mirrors
     # cmd_five_hour_breakdown). Used by the active-predicate to gate
@@ -7228,6 +8186,9 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
     conn = open_db()
     try:
         # Date filter parsing — same convention as cmd_blocks.
+        # _parse_date_filter routes through _parse_dual_form_date, which
+        # eprints its own diagnostic and raises a bare ValueError on bad
+        # input (Review-A P1-1 — dedup stderr by NOT re-emitting here).
         try:
             since_iso = (
                 _parse_date_filter(args.since, "--since")
@@ -7237,8 +8198,7 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
                 _parse_date_filter(args.until, "--until")
                 if args.until else None
             )
-        except ValueError as e:
-            print(str(e), file=sys.stderr)
+        except ValueError:
             return 2
 
         where: list[str] = []
@@ -7266,6 +8226,31 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
             params,
         ).fetchall()
 
+        # Issue #89: --debug report scope = the time range spanned by
+        # the rendered block rows. When `rows` is empty, pass an empty
+        # list to short-circuit the loader entirely.
+        if rows:
+            # rows are ORDER BY block_start_at DESC; first row is newest,
+            # last row is oldest. The rendered window is
+            # [oldest_block_start, newest_block_start + BLOCK_DURATION).
+            oldest_start_iso = rows[-1]["block_start_at"]
+            newest_start_iso = rows[0]["block_start_at"]
+            block_window_start = parse_iso_datetime(
+                oldest_start_iso, "block_start_at",
+            )
+            block_window_end = parse_iso_datetime(
+                newest_start_iso, "block_start_at",
+            ) + BLOCK_DURATION
+            _emit_debug_samples_if_set(
+                args,
+                lambda: get_entries(block_window_start, block_window_end),
+                command_label="five-hour-blocks",
+            )
+        else:
+            _emit_debug_samples_if_set(
+                args, [], command_label="five-hour-blocks",
+            )
+
         # Detect truncation: cap applied AND there's at least one older
         # block beyond the cap. Probe with LIMIT 1 OFFSET <cap> over the
         # SAME filter set (none here, but kept symmetric for clarity).
@@ -7868,18 +8853,28 @@ def _resolve_cache_report_window(
         # Full-ISO args carry an explicit time component or tz marker.
         if "T" in raw or "+" in raw or "Z" in raw:
             return parse_iso_datetime(raw, flag)
-        # Date-only: try YYYY-MM-DD then YYYYMMDD (matching
-        # _parse_cli_date_range's precedent for daily/weekly/monthly).
-        for fmt in ("%Y-%m-%d", "%Y%m%d"):
+        # Date-only: route through the centralized dual-form helper
+        # (spec §7.1.1) so YYYY-MM-DD / YYYYMMDD parsing and the error
+        # message stay consistent with cmd_blocks / cmd_daily / etc.
+        naive = _try_dual_form_date(raw)
+        if naive is None:
+            # Second-chance (issue #101): the pre-Session-A code fell
+            # through to parse_iso_datetime here, so space-separated
+            # datetimes (`2026-05-01 12:30:00`) and ISO week-dates
+            # (`2026-W18-1`) — both accepted by datetime.fromisoformat but
+            # rejected by the dual-form parser — kept working. cache-report
+            # is the only date-taking command with this fallthrough; the
+            # other commands accept YYYY-MM-DD / YYYYMMDD only. Returned
+            # verbatim: a full datetime carries its own time component, so
+            # the is_upper_bound end-of-day expansion is NOT applied (it's
+            # for bare date-only forms). On TOTAL failure (neither dual-form
+            # nor ISO), fall back to the centralized dual-form diagnostic
+            # rather than parse_iso_datetime's more generic message.
             try:
-                naive = dt.datetime.strptime(raw, fmt)
-                break
+                return parse_iso_datetime(raw, flag)
             except ValueError:
-                continue
-        else:
-            # Not a date-only form either — fall back to parse_iso_datetime
-            # so callers still get a consistent error message.
-            return parse_iso_datetime(raw, flag)
+                _parse_dual_form_date(raw, flag)  # eprints + raises ValueError
+                raise  # unreachable — the call above always raises here
         if is_upper_bound:
             naive = naive.replace(
                 hour=23, minute=59, second=59, microsecond=999999,
@@ -8131,15 +9126,47 @@ def _sort_cache_rows(
 
 
 def cmd_cache_report(args: argparse.Namespace) -> int:
-    config = load_config()
+    config = _load_claude_config_for_args(args)
+    # Session A (spec §7.2): bridge -z/--timezone into args.tz so the
+    # existing resolve_display_tz precedence absorbs the new alias. The
+    # canonical --tz still wins (it's set on the namespace before this
+    # bridge fires); when --tz is unset and -z is supplied, use -z.
+    _bridge_z_into_tz(args, config)
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
 
     now_utc = _command_as_of()
-    since, until = _resolve_cache_report_window(
-        args, now_utc=now_utc,
-        tz_name=(tz.key if tz is not None else None),
+    # Session A (spec §7.1.1): the dual-form helper eprints its own
+    # diagnostic and raises a bare ValueError; catch it here so main()'s
+    # generic ``Error: {exc}`` fallback doesn't double-print an empty
+    # trailer. Mirrors the catch-and-return-1 shape in cmd_blocks.
+    #
+    # Session A note (Review-A P2-D): cache-report's argparse alias
+    # surface lands in Implementor 2's scope (B-series). The try/except
+    # here only routes _resolve_cache_report_window's bare ValueError
+    # around main()'s generic Error: handler — no parser-level changes.
+    try:
+        since, until = _resolve_cache_report_window(
+            args, now_utc=now_utc,
+            tz_name=(tz.key if tz is not None else None),
+        )
+    except ValueError as exc:
+        # Centralized helper already eprinted on the dual-form path; for
+        # the legacy parse_iso_datetime path (full-ISO mis-format) the
+        # ValueError carries the message, so eprint it.
+        msg = str(exc)
+        if msg:
+            eprint(f"Error: {msg}")
+        return 1
+
+    # Issue #89 Pattern C: deferred loader scoped to the rendered window
+    # (project filter mirrors what the cache-aggregator uses).
+    _emit_debug_samples_if_set(
+        args,
+        lambda: get_entries(since, until, project=args.project),
+        command_label="cache-report",
     )
+
     mode = "session" if getattr(args, "by_session", False) else "day"
     top_key = "sessions" if mode == "session" else "days"
 
@@ -8193,11 +9220,20 @@ def cmd_cache_report(args: argparse.Namespace) -> int:
         return 0
 
     title = _build_cache_report_title(args, mode)
-    print(_render_cache_report_table(rows, title, mode=mode, tz=tz))
+    print(_render_cache_report_table(rows, title, mode=mode, tz=tz, compact=args.compact))
     return 0
 
 
 def cmd_range_cost(args: argparse.Namespace) -> int:
+    # Session A (spec §7.2 / §7.6 row note): range-cost has no --tz of
+    # its own — start/end carry their own zone via ISO 8601. Calling the
+    # bridge keeps the alias-surface contract uniform across the 10
+    # in-scope cmds: -z/--timezone lands on args.tz unchanged (no
+    # downstream consumer), so this is a documented no-op for this
+    # command. The bridge still runs _resolve_claude_tz_name so the §9.2a
+    # production-path coverage is exercised here too.
+    config = _load_claude_config_for_args(args)
+    _bridge_z_into_tz(args, config)
     start_dt = parse_iso_datetime(args.start, "--start")
     if args.end:
         end_dt = parse_iso_datetime(args.end, "--end")
@@ -8214,7 +9250,17 @@ def cmd_range_cost(args: argparse.Namespace) -> int:
     last_match: dt.datetime | None = None
     model_buckets: dict[str, dict[str, Any]] = {}
 
-    for entry in get_entries(start_dt, end_dt, project=args.project):
+    # Issue #89: keep the loaded list around so the --debug report can
+    # describe the same dataset as the rendered output. Project filter is
+    # applied at the loader (SELECT-time), so the scope is the same.
+    # P2.2 (issue #89 review-loop): get_entries already returns
+    # list[UsageEntry] per bin/_cctally_cache.py:1224 — no list() wrap.
+    entries_list = get_entries(start_dt, end_dt, project=args.project)
+    _emit_debug_samples_if_set(
+        args, entries_list, command_label="range-cost",
+    )
+
+    for entry in entries_list:
         cost = _calculate_entry_cost(
             entry.model, entry.usage, mode=args.mode, cost_usd=entry.cost_usd,
         )
@@ -8319,7 +9365,7 @@ def cmd_range_cost(args: argparse.Namespace) -> int:
         ])
 
         aligns = ["left"] + ["right"] * (len(headers) - 1)
-        print(_boxed_table(headers, rows, aligns))
+        print(_boxed_table(headers, rows, aligns, compact=args.compact))
         return 0
 
     # Default: print cost
@@ -8689,6 +9735,10 @@ def doctor_gather_state(
         effective_update_reason=effective_update_reason,
         now_utc=now_utc,
         cctally_version=cctally_version,
+        # Dev-instance isolation (§4): which data dir resolved + how.
+        dev_mode=_cctally_core.DEV_MODE,
+        app_dir=str(_cctally_core.APP_DIR),
+        is_dev_checkout=_cctally_core._is_dev_checkout(),
     )
 
 
@@ -8733,6 +9783,110 @@ def _argparse_has_arg(parser, option_string: str) -> bool:
     return False
 
 
+def _add_ccusage_alias_args(parser, *, ansi_emit: bool) -> None:
+    """Attach the Session A ccusage alias surface to a Claude-cmd subparser.
+
+    Sibling to ``_add_codex_shared_args`` (declared inside ``build_parser``)
+    but tailored for Claude commands. Every flag is guarded with
+    ``_argparse_has_arg`` so existing per-parser declarations
+    (cache-report's ``--offline``, project / five-hour-blocks / diff's
+    ``--no-color``) do NOT cause ``argparse.ArgumentError`` — the helper
+    just skips the duplicate. This makes future collisions self-healing
+    when a contributor adds a Session A-managed flag directly on a
+    subparser.
+
+    Args:
+      parser:    the subparser to mutate.
+      ansi_emit: ``True`` for project + diff (the 2 real ANSI emitters).
+                 ``False`` for the other 8 in-scope cmds. Controls only
+                 the ``--color`` help text and whether ``--no-color`` is
+                 attempted as a fresh add (when ``ansi_emit=True`` we
+                 skip ``--no-color`` entirely — those parsers already
+                 declared it themselves).
+
+    Spec §7.1.2 / issue #86 Session A.
+    """
+
+    def _maybe_add(opt: str, *args, **kwargs):
+        if _argparse_has_arg(parser, opt):
+            return
+        parser.add_argument(opt, *args, **kwargs)
+
+    def _maybe_add2(opt1: str, opt2: str, *args, **kwargs):
+        # Two-form add (short + long) — skip if EITHER is present.
+        if _argparse_has_arg(parser, opt1) or _argparse_has_arg(parser, opt2):
+            return
+        parser.add_argument(opt1, opt2, *args, **kwargs)
+
+    _maybe_add2(
+        "-z", "--timezone", default=None, metavar="TZ",
+        help="Alias for --tz (drop-in compat with ccusage). When both "
+             "are supplied, --tz wins.",
+    )
+    _maybe_add2(
+        "-O", "--offline",
+        action=argparse.BooleanOptionalAction, default=False,
+        help="Accepted for ccusage drop-in compat; cctally is always offline.",
+    )
+    _maybe_add(
+        "--compact", action="store_true",
+        help="Force compact table layout regardless of terminal width.",
+    )
+    _maybe_add(
+        "--config", default=None, metavar="PATH",
+        help="Read config from PATH for this invocation only (no "
+             "mutation of the default config at "
+             "~/.local/share/cctally/config.json). Missing or invalid "
+             "PATH errors out with a clear message.",
+    )
+    _maybe_add2(
+        "-d", "--debug", action="store_true",
+        help="Emit a stderr 'Pricing Mismatch Debug Report' "
+             "(totals + per-model stats + sample discrepancies, "
+             "matching ccusage's --debug shape).",
+    )
+    _maybe_add(
+        "--debug-samples", type=_nonneg_int, default=5, metavar="N",
+        help="Cap on sample-discrepancy rows in the --debug report "
+             "(default 5; N=0 suppresses the sample block; "
+             "negatives rejected at parse time).",
+    )
+    _maybe_add(
+        "--single-thread", action="store_true",
+        help="Accepted for ccusage drop-in compat; cctally ingestion "
+             "is already single-threaded via the session-entry cache.",
+    )
+    if ansi_emit:
+        _maybe_add(
+            "--color", action="store_true", default=False,
+            help="Force ANSI color output (overrides NO_COLOR env). When "
+                 "neither --color nor --no-color is set, color is auto-"
+                 "detected from isatty() and NO_COLOR/FORCE_COLOR env.",
+        )
+        # --no-color already declared on these parsers; do nothing here.
+    else:
+        # No-op-for-compat surface (spec §7.3): these flags parse but do
+        # NOT flow through the color resolver on this command. Color (where
+        # the renderer emits any) follows the auto-detect — isatty() plus
+        # NO_COLOR / FORCE_COLOR env — so the help must NOT claim "no ANSI
+        # is emitted" (daily/monthly/weekly/blocks/session/cache-report DO
+        # emit auto-detected ANSI on a TTY; only the no-color env vars
+        # suppress it). Force/suppress color on the 2 real ANSI commands
+        # (project, diff) instead, or use NO_COLOR=1 / FORCE_COLOR=1.
+        _maybe_add(
+            "--color", action="store_true", default=False,
+            help="Accepted for ccusage drop-in compat; does not control "
+                 "this command's color. Color auto-detects from isatty() "
+                 "and honors NO_COLOR / FORCE_COLOR env.",
+        )
+        _maybe_add(
+            "--no-color", action="store_true", default=False,
+            help="Accepted for ccusage drop-in compat; does not suppress "
+                 "this command's color. Use NO_COLOR=1 env (or pipe stdout) "
+                 "to disable auto-detected ANSI.",
+        )
+
+
 def _add_share_args(parser, *, has_status_line: bool = False) -> None:
     """Attach shareable-reports flags + format/json mutex to a subparser.
 
@@ -8887,7 +10041,7 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     p.add_argument(
-        "--version",
+        "-v", "--version",
         action="store_true",
         default=argparse.SUPPRESS,
         help="Print cctally version (from CHANGELOG.md latest release header) and exit",
@@ -9472,9 +10626,14 @@ def build_parser() -> argparse.ArgumentParser:
              "Adds SessionId, Last Activity, and Project identity columns.",
     )
     pc.add_argument(
-        "--offline",
-        action="store_true",
-        help="Use cached pricing data in ccusage.",
+        "-O", "--offline",
+        action=argparse.BooleanOptionalAction, default=False,
+        help="Use cached pricing data in ccusage. Session A (spec §7.1.2)"
+             " promotes the existing flag to BooleanOptionalAction + -O"
+             " short form so the ccusage drop-in alias surface (-O,"
+             " --offline, --no-offline) all work on cache-report; the"
+             " behavior under each is unchanged (cctally is always"
+             " offline — args.offline still lands as a bool).",
     )
     pc.add_argument(
         "--project",
@@ -9521,6 +10680,10 @@ def build_parser() -> argparse.ArgumentParser:
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    # Session A (spec §7.6): ansi_emit=False; existing `--offline` is
+    # skipped by the helper's `_argparse_has_arg` guard (the collision
+    # case spec §7.1.2 calls out explicitly).
+    _add_ccusage_alias_args(pc, ansi_emit=False)
     pc.set_defaults(func=cmd_cache_report)
 
     # -- range-cost --
@@ -9575,6 +10738,12 @@ def build_parser() -> argparse.ArgumentParser:
         dest="total_only",
         help="Print numeric USD total only.",
     )
+    # Session A (spec §7.6): ansi_emit=False. range-cost has no --tz of
+    # its own (ISO timestamps carry zone info), but the helper-added
+    # -z/--timezone still lands on the namespace; the bridge promotes
+    # it onto args.tz where the rest of the pipeline treats it as a
+    # documented no-op (cmd_range_cost does not consume args.tz).
+    _add_ccusage_alias_args(rc, ansi_emit=False)
     rc.set_defaults(func=cmd_range_cost)
 
     # -- blocks --
@@ -9619,6 +10788,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    _add_ccusage_alias_args(bl, ansi_emit=False)
     bl.set_defaults(func=cmd_blocks)
 
     # -- five-hour-blocks --
@@ -9666,7 +10836,8 @@ def build_parser() -> argparse.ArgumentParser:
     fhb.add_argument(
         "--no-color",
         action="store_true",
-        help="Disable ANSI color output (currently a no-op — table is plain text).",
+        help="Accepted for ccusage drop-in compat; this command emits "
+             "plain-text output and no ANSI is suppressed.",
     )
     fhb.add_argument(
         "--tz",
@@ -9676,6 +10847,12 @@ def build_parser() -> argparse.ArgumentParser:
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    # Session A (spec §7.6 / §7.6.3): ansi_emit=False. fhb already
+    # declares --no-color (refreshed to no-op text in spec §7.6.3); the
+    # helper's --no-color add is short-circuited by the existing-arg
+    # guard. The helper's --color add lands as a parsed-and-ignored
+    # no-op (the renderer emits plain text).
+    _add_ccusage_alias_args(fhb, ansi_emit=False)
     _add_share_args(fhb)
     fhb.set_defaults(func=cmd_five_hour_blocks)
 
@@ -9747,6 +10924,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    _add_ccusage_alias_args(dy, ansi_emit=False)
     _add_share_args(dy)
     dy.set_defaults(func=cmd_daily)
 
@@ -9800,6 +10978,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    _add_ccusage_alias_args(mo, ansi_emit=False)
     _add_share_args(mo)
     mo.set_defaults(func=cmd_monthly)
 
@@ -9835,6 +11014,7 @@ def build_parser() -> argparse.ArgumentParser:
     we.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
                     help="Display timezone: local, utc, or IANA name. "
                          "Overrides config display.tz for this call.")
+    _add_ccusage_alias_args(we, ansi_emit=False)
     _add_share_args(we)
     we.set_defaults(func=cmd_weekly)
 
@@ -9885,6 +11065,22 @@ def build_parser() -> argparse.ArgumentParser:
                  "config display.tz for this call. Takes precedence over "
                  "upstream's --timezone for drop-in parity.",
         )
+        # Issue #92: codex parity for the #89 --debug surface. Codex JSONL
+        # has no recorded costUSD to diff against, so the report is the
+        # codex variant ("Codex Pricing Debug Report": totals + top-N
+        # highest computed-cost entries), wired via
+        # _emit_codex_debug_samples_if_set in each cmd_codex_* body.
+        parser.add_argument(
+            "-d", "--debug", action="store_true",
+            help="Emit a stderr 'Codex Pricing Debug Report' (totals + "
+                 "the N highest computed-cost sample entries).",
+        )
+        parser.add_argument(
+            "--debug-samples", type=_nonneg_int, default=5, metavar="N",
+            help="Cap on top-entry sample rows in the --debug report "
+                 "(default 5; N=0 suppresses the sample block; "
+                 "negatives rejected at parse time).",
+        )
 
     # -- codex-daily --
     cd = sub.add_parser(
@@ -10039,6 +11235,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_project.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
                            help="Display timezone: local, utc, or IANA name. "
                                 "Overrides config display.tz for this call.")
+    # Session A (spec §7.6): ansi_emit=True. project is one of the two
+    # real ANSI emitters. The helper skips its --no-color add (already
+    # declared at p_project above) and adds the new bool --color flag
+    # whose precedence flows through _resolve_color_enabled (§7.3).
+    _add_ccusage_alias_args(p_project, ansi_emit=True)
     _add_share_args(p_project)
     p_project.set_defaults(func=cmd_project)
 
@@ -10073,6 +11274,14 @@ def build_parser() -> argparse.ArgumentParser:
     diff_p.add_argument("--json", dest="emit_json", action="store_true")
     diff_p.add_argument("--width", type=int, help=argparse.SUPPRESS)
     diff_p.add_argument("--debug-now", action="store_true", help=argparse.SUPPRESS)
+    # Session A (spec §7.6): ansi_emit=True. diff is the other real
+    # ANSI emitter. The helper skips its --no-color add (declared
+    # above) and adds the new bool --color flag wired through
+    # _resolve_color_enabled (§7.3). Note: --debug here collides with
+    # diff's existing `--debug-now` (SUPPRESS'd internal flag) but
+    # `--debug-now` is a different option string; the helper still
+    # adds plain `--debug` cleanly.
+    _add_ccusage_alias_args(diff_p, ansi_emit=True)
     diff_p.set_defaults(func=cmd_diff)
 
     # -- session --
@@ -10111,6 +11320,14 @@ def build_parser() -> argparse.ArgumentParser:
     se.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
                     help="Display timezone: local, utc, or IANA name. "
                          "Overrides config display.tz for this call.")
+    se.add_argument(
+        "-i", "--id", default=None, metavar="SESSION_ID", dest="id",
+        help="Filter to a single session by exact-string sessionId. "
+             "Match is against the post-resume-merge id (sessions "
+             "resumed across multiple JSONL files collapse to one id). "
+             "Unknown id → exit 0 with the empty-render branch.",
+    )
+    _add_ccusage_alias_args(se, ansi_emit=False)
     _add_share_args(se)
     se.set_defaults(func=cmd_session)
 
@@ -10255,6 +11472,9 @@ def build_parser() -> argparse.ArgumentParser:
                     help="Skip confirmations")
     sp.add_argument("--json", action="store_true",
                     help="Emit machine-readable output")
+    sp.add_argument("--force-dev", action="store_true", dest="force_dev",
+                    help="Allow setup to run from a dev checkout (writes "
+                         "dev-pointing hooks into ~/.claude/settings.json)")
     # Legacy bespoke-hook migration flags (install-mode only — see cmd_setup
     # post-parse validation). Spec Section 2 mode×flag matrix.
     mig_group = sp.add_mutually_exclusive_group()
@@ -12302,10 +13522,19 @@ def main(argv: list[str] | None = None) -> int:
     # works without a subcommand (`cctally --version`).
     if getattr(args, "version", False):
         v = _lib_changelog._read_latest_changelog_version()
-        if v is None:
-            print("cctally unknown")
-        else:
-            print(f"cctally {v[0]}")
+        base = "cctally unknown" if v is None else f"cctally {v[0]}"
+        # Dev-instance isolation (§4, P3): append the dev marker + resolved
+        # data dir whenever running from a checkout — keyed on
+        # _is_dev_checkout(), NOT DEV_MODE, so the CCTALLY_DATA_DIR
+        # override-on-checkout case (DEV_MODE False) still shows the marker
+        # instead of masquerading as the installed binary. Prod (no .git)
+        # output is unchanged. The override case is labelled distinctly so
+        # the user can tell auto-detect (cctally-dev) from an explicit dir.
+        if _cctally_core.DEV_MODE:
+            base += f" (dev — {_cctally_core.APP_DIR})"
+        elif _cctally_core._is_dev_checkout():
+            base += f" (dev checkout, custom data dir — {_cctally_core.APP_DIR})"
+        print(base)
         return 0
     if not getattr(args, "func", None):
         parser.error("a subcommand is required")