cctally 1.95.4 → 1.96.0

package/bin/_cctally_dashboard_share.py

@@ -1283,6 +1283,14 @@ def _share_source_selection(req: dict) -> tuple[str, bool]:
     return source, explicit
 
 
+def _share_json_bool(payload: dict, key: str, *, default: bool = False) -> bool:
+    """Read a strict JSON boolean instead of applying Python truthiness."""
+    value = payload.get(key, default)
+    if not isinstance(value, bool):
+        raise TypeError(key)
+    return value
+
+
 _ACCOUNT_KEY_RE = re.compile(r"[0-9a-f]{32}|unattributed|\*")
 
 
@@ -2182,6 +2190,14 @@ def _handle_share_render_post_impl(handler) -> None:
             "field": "options.theme",
         })
         return
+    try:
+        reveal = _share_json_bool(options, "reveal_projects")
+    except TypeError:
+        handler._respond_json(400, {
+            "error": "reveal_projects must be a boolean",
+            "field": "options.reveal_projects",
+        })
+        return
     # `top_n` may be explicit-null when the UI's Top-N input is
     # cleared (Knobs.tsx:43); treat null as "use template default"
     # rather than 400-ing every preview/export until the user types
@@ -2258,7 +2274,6 @@ def _handle_share_render_post_impl(handler) -> None:
     # a default belongs here; it must resolve to anonymize, matching
     # /api/share/compose, which already defaulted closed. The kernel itself
     # has no default at all, so a fourth site cannot get this wrong.
-    reveal = bool(options.get("reveal_projects", False))
     # No pre-scrub: the kernel's `render()` / `compose()` own the privacy
     # contract and require RAW snapshots (#503 S1). Pre-scrubbing here
     # renumbers aliases on the legacy path, and in the `source=all` branch it
@@ -2409,7 +2424,14 @@ def _handle_share_compose_post_impl(handler) -> None:
     theme = req.get("theme", "light")
     fmt = req.get("format", "html")
     no_branding = bool(req.get("no_branding", False))
-    reveal_projects = bool(req.get("reveal_projects", False))
+    try:
+        reveal_projects = _share_json_bool(req, "reveal_projects")
+    except TypeError:
+        handler._respond_json(400, {
+            "error": "reveal_projects must be a boolean",
+            "field": "reveal_projects",
+        })
+        return
     sections_in = req.get("sections")
     if not isinstance(title, str) or not title:
         handler._respond_json(400, {"error": "missing title", "field": "title"})
@@ -2769,7 +2791,13 @@ def _handle_share_presets_post_impl(handler) -> None:
     # #503 S3 §1. Absent means false, which is the fail-safe direction and is
     # what makes this compatible with a caller written before the field
     # existed: an unwitting save can no longer destroy a stored recipe.
-    overwrite = bool(req.get("overwrite", False))
+    try:
+        overwrite = _share_json_bool(req, "overwrite")
+    except TypeError:
+        handler._respond_json(400, {
+            "error": "overwrite must be a boolean", "field": "overwrite",
+        })
+        return
 
     saved_at = _share_now_utc_iso()
     record = {
@@ -2867,7 +2895,13 @@ def _handle_share_presets_rename_post_impl(handler) -> None:
     panel = req.get("panel")
     from_name = req.get("from_name")
     to_name = req.get("to_name")
-    overwrite = bool(req.get("overwrite", False))
+    try:
+        overwrite = _share_json_bool(req, "overwrite")
+    except TypeError:
+        handler._respond_json(400, {
+            "error": "overwrite must be a boolean", "field": "overwrite",
+        })
+        return
 
     if not isinstance(panel, str) or not panel:
         handler._respond_json(400, {

package/bin/_cctally_db.py

@@ -9290,7 +9290,7 @@ def _process_start_identity(pid: int) -> "str | None":
             stderr=subprocess.DEVNULL,
             text=True,
             check=False,
-            env={**os.environ, "LC_ALL": "C"},
+            env={**os.environ, "LC_ALL": "C", "TZ": "UTC"},
         )
     except OSError:
         return None

package/bin/_cctally_journal.py

@@ -35,6 +35,7 @@ import os
 import pathlib
 import signal
 import sqlite3
+import stat
 import sys
 import time
 from dataclasses import dataclass, field, replace as _dc_replace
@@ -326,6 +327,134 @@ def _utc_now() -> dt.datetime:
     return dt.datetime.now(dt.timezone.utc)
 
 
+def _observation_segment_month(name: str) -> tuple[int, int] | None:
+    """Return a strict ``(year, month)`` for one monthly observation name."""
+    prefix = _lib_journal.SEGMENT_PREFIX
+    suffix = ".jsonl"
+    if not name.startswith(prefix) or not name.endswith(suffix):
+        return None
+    stamp = name[len(prefix):-len(suffix)]
+    if len(stamp) != 7 or stamp[4] != "-":
+        return None
+    year_text, month_text = stamp.split("-", 1)
+    ascii_digits = frozenset("0123456789")
+    if (
+        any(char not in ascii_digits for char in year_text)
+        or any(char not in ascii_digits for char in month_text)
+    ):
+        return None
+    year = int(year_text)
+    month = int(month_text)
+    if year < 1 or not 1 <= month <= 12:
+        return None
+    return (year, month)
+
+
+def _future_segment_refusal(
+    journal_dir, seg_name: str, future_name: str, reason: str
+) -> JournalAppendTargetStale:
+    return JournalAppendTargetStale(
+        f"append target {seg_name} is blocked by later segment {future_name} "
+        f"in {journal_dir}: {reason}; automatic recovery is limited to empty "
+        "regular files. Preserve the future segment and either wait for its "
+        "UTC month or merge its records forward, verify `cctally db rebuild "
+        "--db stats`, and only then remove it"
+    )
+
+
+def _list_append_target_candidates(journal_dir, seg_name: str) -> list[str]:
+    """Canonical-looking entries, including types recovery must reject.
+
+    ``list_segments`` intentionally exposes readable regular segment files to
+    journal consumers. Append validation has a stricter responsibility: a
+    directory, symlink, or uninspectable path with a canonical-looking future
+    name must fail closed instead of disappearing from the recovery decision.
+    """
+    try:
+        names = [
+            entry.name
+            for entry in journal_dir.iterdir()
+            if entry.name.endswith(".jsonl")
+            and (
+                entry.name.startswith(_lib_journal.BOOTSTRAP_PREFIX)
+                or entry.name.startswith(_lib_journal.SEGMENT_PREFIX)
+            )
+        ]
+    except OSError as exc:
+        raise JournalAppendTargetStale(
+            f"append target {seg_name} cannot inspect journal entries in "
+            f"{journal_dir} ({exc}); automatic recovery is limited to "
+            "inspectable empty regular files"
+        ) from exc
+    return sorted(names, key=_lib_journal.segment_sort_key)
+
+
+def _remove_empty_future_segments(
+    journal_dir, seg_name: str, segments: list[str]
+) -> list[str]:
+    """Remove a restored empty future tail while holding ``journal.lock``.
+
+    The caller has already established that ``seg_name`` is stale. Every later
+    segment is inspected before any unlink, so a mixed empty/data-bearing tail
+    remains untouched. All supported writers take the same leaf lock; this is
+    therefore a complete concurrency boundary for journal mutations.
+    """
+    target_month = _observation_segment_month(seg_name)
+    if target_month is None:
+        return segments
+    target_key = _lib_journal.segment_sort_key(seg_name)
+    later = [
+        name
+        for name in segments
+        if _lib_journal.segment_sort_key(name) > target_key
+    ]
+    if not later:
+        return segments
+
+    removable: list[pathlib.Path] = []
+    for name in later:
+        month = _observation_segment_month(name)
+        path = journal_dir / name
+        if month is None or month <= target_month:
+            raise _future_segment_refusal(
+                journal_dir, seg_name, name, "the segment name is not a later UTC month"
+            )
+        try:
+            metadata = path.lstat()
+        except OSError as exc:
+            raise _future_segment_refusal(
+                journal_dir, seg_name, name, f"the segment cannot be inspected ({exc})"
+            ) from exc
+        if not stat.S_ISREG(metadata.st_mode) or metadata.st_size != 0:
+            detail = (
+                f"the segment retains {metadata.st_size} bytes"
+                if stat.S_ISREG(metadata.st_mode)
+                else "the path is not a regular file"
+            )
+            raise _future_segment_refusal(
+                journal_dir, seg_name, name, detail
+            )
+        removable.append(path)
+
+    removed = False
+    try:
+        for path in removable:
+            try:
+                path.unlink()
+                removed = True
+            except OSError as exc:
+                raise _future_segment_refusal(
+                    journal_dir,
+                    seg_name,
+                    path.name,
+                    f"the empty segment cannot be removed ({exc})",
+                ) from exc
+    finally:
+        if removed:
+            _fsync_dir(journal_dir)
+    return _list_append_target_candidates(journal_dir, seg_name)
+
+
 def _validate_append_target(journal_dir, seg_name: str) -> None:
     """Refuse an append whose target is not the canonically-last segment.
 
@@ -343,8 +472,13 @@ def _validate_append_target(journal_dir, seg_name: str) -> None:
     a writer retry against a freshly resolved target, where silently
     redirecting a planned correction group would move it out from under a
     caller that had already reasoned about its placement (#496 S5b §2.4).
+
+    A restored future tail is the one non-transient case (#512). Empty regular
+    future segments carry no durable truth, so they are removed and the target
+    is revalidated. Any data-bearing, malformed, or non-regular later segment
+    still fails closed with the manual recovery boundary in the error.
     """
-    segments = list_segments()
+    segments = _list_append_target_candidates(journal_dir, seg_name)
     if not segments:
         return
     if seg_name == segments[-1]:
@@ -354,6 +488,14 @@ def _validate_append_target(journal_dir, seg_name: str) -> None:
             [*segments, seg_name], key=_lib_journal.segment_sort_key)
         if provisional[-1] == seg_name:
             return
+    segments = _remove_empty_future_segments(journal_dir, seg_name, segments)
+    if not segments or seg_name == segments[-1]:
+        return
+    if seg_name not in segments:
+        provisional = sorted(
+            [*segments, seg_name], key=_lib_journal.segment_sort_key)
+        if provisional[-1] == seg_name:
+            return
     raise JournalAppendTargetStale(
         f"append target {seg_name} is not the canonically-last segment "
         f"({segments[-1]}) in {journal_dir}; re-resolve and retry"
@@ -819,7 +961,7 @@ def plan_segment_elision(segments, high_water):
         summaries=summaries, covered=covered, verdict=reason)
 
 
-def _refill_elided_quota_raw(quota_raw, gaps):
+def _refill_elided_quota_raw(quota_raw, gaps, *, failures=None):
     """``(stream, complete)`` — ``quota_raw`` with the elided observations back.
 
     Reached only when the pass elided and the cache leg's own coverage verdict
@@ -840,7 +982,10 @@ def _refill_elided_quota_raw(quota_raw, gaps):
 
     ``complete`` is False when any elided segment could not be re-read IN FULL.
     The caller must then drop its covered boundary: the observations this stream
-    is missing are exactly the ones a minted certificate would claim.
+    is missing are exactly the ones a minted certificate would claim. When a
+    ``failures`` list is supplied, every caught exception appends its segment
+    name and exception class so the rebuild record distinguishes transient I/O
+    failures from implementation defects.
 
     **A short read is detected by counting, not by catching.**
     `_iter_segment_lines` reads until its own `read()` returns nothing, so a
@@ -851,6 +996,8 @@ def _refill_elided_quota_raw(quota_raw, gaps):
     """
     by_index: dict = {}
     complete = True
+    if failures is None:
+        failures = []
     for name, index, extent, expected_lines in gaps:
         recovered = []
         seen = 0
@@ -861,7 +1008,7 @@ def _refill_elided_quota_raw(quota_raw, gaps):
                 record = _lib_journal.decode_line(raw)
                 if record is not None and _is_codex_quota_obs(record):
                     recovered.append(raw)
-        except Exception:
+        except Exception as exc:
             # A vanished segment self-heals, because the pinned vector no longer
             # matches the journal and the certificate is invalid the moment it
             # is read. A transient read error on an UNCHANGED file does not: the
@@ -874,6 +1021,10 @@ def _refill_elided_quota_raw(quota_raw, gaps):
             # call site nor its caller catches anything, so one that escaped
             # would abort the whole rebuild over a re-derivable optimization.
             complete = False
+            failures.append({
+                "segment": str(name),
+                "error": type(exc).__name__,
+            })
             continue
         if seen != int(expected_lines):
             complete = False
@@ -4635,6 +4786,7 @@ def _validate_excluded_derived_fks(conn, spec, row) -> None:
 def _full_effective_selection(hw, accumulators=None):
     records = []
     evidence = []
+    coordinates = {}
     prior_high_water = None
     if hw is not None:
         for segment, offset, raw in _read_range(None, hw):
@@ -4645,16 +4797,25 @@ def _full_effective_selection(hw, accumulators=None):
                     prior_high_water,
                     evidence,
                 )
+                # Only correction records can establish a completed-to-tainted
+                # transition. Keep their exact sequence coordinates without
+                # adding one tuple for every observation in a full fallback.
+                if record.get("t") in {"correction", "correction_batch"}:
+                    coordinates[len(records)] = (
+                        segment, offset + len(raw) + 1)
                 records.append(record)
             prior_high_water = (segment, offset + len(raw) + 1)
     cutover_claude = resolve_cutover_claude_account()
     for record in records:
         _normalize_legacy_account_stamp(record, cutover_claude)
-    return _lib_journal.resolve_effective_events(
+    selected = _lib_journal.resolve_effective_events(
         records,
         protocol_prefix_evidence=evidence,
         accumulators=accumulators,
     )
+    if accumulators is not None:
+        accumulators["coordinates"] = coordinates
+    return selected
 
 
 def _selector_generation_matches(conn, state) -> bool:
@@ -4765,15 +4926,12 @@ def _coordinate_covers(covered, target) -> bool:
 #: — is decided BEFORE the gap read and the next successful tick writes the
 #: realigned prefix. One refusal is not the shape this cap exists for.
 #:
-#: The shape it exists for is a refusal that repeats. `merge_delta`'s
-#: durably-completed-batch shape refusal falls back to
-#: `_full_effective_selection`, whose loop acts only on entries whose `batch_id`
-#: is not `None` — and after a taint the winner reverts to the base journal
-#: event, whose `batch_id` IS `None`. That is issue #510, so no
-#: `CorrectionRebuildRequired` is raised and no rebuild follows to realign the
-#: durable prefix. Every later tick would then re-read and re-decode a
-#: monotonically growing range, which is the whole-prefix read spec §3.3 exists
-#: to prevent under another name.
+#: The shape it exists for is any refusal that repeats. A completed-to-tainted
+#: batch now signals from both the incremental and full-selection paths (#510),
+#: but other conservative full-selection fallbacks can still leave durable
+#: selector coverage behind the applied cursor. Every later tick would then
+#: re-read and re-decode a monotonically growing range, which is the whole-prefix
+#: read spec §3.3 exists to prevent under another name.
 #:
 #: Past the cap the tick degrades to full selection like every other degraded
 #: case, and `_observe_selector_desynchronization` reports the gap and this cap
@@ -5059,6 +5217,42 @@ def _raise_taint_transition(transition, coordinates) -> None:
     )
 
 
+def _full_taint_transition(conn, selection, accumulators):
+    """Find a stored corrected batch withdrawn by a full selection (#510)."""
+    stored_batches = {
+        row[0] for row in conn.execute(
+            "SELECT DISTINCT batch_id FROM journal_effective_events "
+            "WHERE batch_id IS NOT NULL"
+        )
+    }
+    stale_batches = stored_batches - set(selection.completed_batches)
+    if not stale_batches:
+        return None
+
+    fold = accumulators["fold"]
+    transitions = []
+    for batch_id, _kind, fingerprint in fold.violations:
+        if batch_id not in stale_batches:
+            continue
+        causal = fold.violation_available_after.get(fingerprint)
+        if causal is not None:
+            transitions.append(
+                _lib_selector_state.TaintTransition(
+                    batch_id=batch_id,
+                    causal_sequence=causal,
+                )
+            )
+    if not transitions:
+        raise JournalError(
+            "a previously completed correction batch is no longer effective "
+            "but its causal taint record could not be resolved"
+        )
+    return min(
+        transitions,
+        key=lambda item: (item.causal_sequence, item.batch_id),
+    )
+
+
 def _correction_commit_high_water(batch_id, hw=None):
     """Return the exact end offset of one completed-batch commit marker.
 
@@ -5289,6 +5483,9 @@ def _preflight_live_events(
             recovery_eligible=True,
             kind=CORRECTION_KIND_NEWLY_COMPLETED,
         )
+    transition = _full_taint_transition(conn, full, accumulators)
+    if transition is not None:
+        _raise_taint_transition(transition, accumulators["coordinates"])
     return to_apply
 
 
@@ -6833,6 +7030,10 @@ def _pending_publication_owes_nothing(destination, state) -> bool:
 
     A marker written before the mechanism field existed reads as `replace`,
     which is what those binaries did.
+
+    A replace marker with no usable scratch path proves neither outcome. It
+    therefore owes a verdict: fail closed instead of discarding the marker as
+    though the predecessor were proven.
     """
     if str(state.get("mechanism") or "replace") == "in_place":
         return in_place_publication_proven_predecessor(destination, state)
@@ -8406,7 +8607,9 @@ def _rebuild_quota_cache_leg_raw(
         # built. Elision then costs one read in the racy case rather than an
         # unmaterialized observation under a certificate claiming coverage.
         before = len(quota_raw)
-        quota_raw, refilled = _refill_elided_quota_raw(quota_raw, elision_gaps)
+        refill_failures: list = []
+        quota_raw, refilled = _refill_elided_quota_raw(
+            quota_raw, elision_gaps, failures=refill_failures)
         if not refilled:
             # A segment this pass elided could not be re-read, so its
             # observations are absent from the stream about to be replayed.
@@ -8421,6 +8624,7 @@ def _rebuild_quota_cache_leg_raw(
                 "segments": len(elision_gaps),
                 "observations": len(quota_raw) - before,
                 "complete": refilled,
+                "failures": refill_failures,
             }
     return _run_bounded_recovery(
         quota_raw, file_accounts, cutover_claude, counters,
@@ -9785,9 +9989,55 @@ def _export_quota_obs() -> list:
     return out
 
 
-def _cutover_segment_name(now_utc: dt.datetime) -> str:
-    ts = now_utc.astimezone(dt.timezone.utc).strftime("%Y%m%dT%H%M%S_%f")
-    return f"{_lib_journal.BOOTSTRAP_PREFIX}{ts}.jsonl"
+def _cutover_segment_name(
+    now_utc: dt.datetime, *, existing: "list[str] | tuple[str, ...]" = ()
+) -> str:
+    """Mint a bootstrap name that sorts after every published bootstrap.
+
+    Wall time supplies the ordinary name. A crash orphan can be later than a
+    retry after a backward clock step, so a non-newest candidate is re-minted
+    one microsecond after the canonically newest published bootstrap (#509).
+    Fail closed when that name is not parseable or cannot be advanced: writing
+    behind it would leave the segment outside the cursor, while reusing its name
+    would overwrite append-only journal truth.
+    """
+    def _name(value: dt.datetime) -> str:
+        ts = value.astimezone(dt.timezone.utc).strftime("%Y%m%dT%H%M%S_%f")
+        return f"{_lib_journal.BOOTSTRAP_PREFIX}{ts}.jsonl"
+
+    candidate = _name(now_utc)
+    bootstraps = [
+        name for name in existing
+        if name.startswith(_lib_journal.BOOTSTRAP_PREFIX)
+    ]
+    if not bootstraps:
+        return candidate
+    newest = max(bootstraps, key=_lib_journal.segment_sort_key)
+    if (_lib_journal.segment_sort_key(candidate)
+            > _lib_journal.segment_sort_key(newest)):
+        return candidate
+
+    prefix = _lib_journal.BOOTSTRAP_PREFIX
+    suffix = ".jsonl"
+    try:
+        if not newest.endswith(suffix):
+            raise ValueError("missing .jsonl suffix")
+        newest_at = dt.datetime.strptime(
+            newest[len(prefix):-len(suffix)], "%Y%m%dT%H%M%S_%f"
+        ).replace(tzinfo=dt.timezone.utc)
+        reminted = _name(newest_at + dt.timedelta(microseconds=1))
+    except (OverflowError, ValueError) as exc:
+        raise JournalError(
+            "cannot mint a cutover bootstrap after the canonically newest "
+            f"published segment {newest!r}"
+        ) from exc
+    if (_lib_journal.segment_sort_key(reminted)
+            <= _lib_journal.segment_sort_key(newest)):
+        raise JournalError(
+            "cutover bootstrap remint did not advance canonical order past "
+            f"{newest!r}"
+        )
+    return reminted
 
 
 def _encode_bootstrap_lines(lines: list) -> bytes:
@@ -9920,7 +10170,8 @@ def run_cutover(conn, *, now_utc: dt.datetime | None = None) -> "str | None":
     rows byte for byte, so it reuses that orphan rather than publishing a twin
     (#496 S5 §3) — the retry is now idempotent on disk, not only on fold. When
     the retry's export genuinely differs, no digest matches and a new segment is
-    written exactly as before."""
+    minted after every published bootstrap, including after a backward clock
+    step (#509)."""
     if now_utc is None:
         now_utc = dt.datetime.now(dt.timezone.utc)
     epoch = _cctally_core.STATS_INDEX_EPOCH
@@ -9946,7 +10197,8 @@ def run_cutover(conn, *, now_utc: dt.datetime | None = None) -> "str | None":
         reuse = _reusable_bootstrap(
             hashlib.sha256(blob).hexdigest(), len(blob))
         if reuse is None:
-            seg_name = _cutover_segment_name(now_utc)
+            seg_name = _cutover_segment_name(
+                now_utc, existing=list_segments())
             seg_size = _write_bootstrap_segment(seg_name, blob)
         else:
             seg_name, seg_size = reuse

package/bin/_cctally_parser.py

@@ -2015,7 +2015,9 @@ def _build_cache_report_parser(subparsers, name, *, help_text, xref=None, fixed_
         default=15,
         dest="anomaly_threshold_pp",
         help="Claude cache %% drop threshold (percentage points) vs. a trailing "
-             "median. Default: 15.",
+             "median. Default: 15. This flag does NOT read config.json:"
+             " cache_report.anomaly_threshold_pp, which the dashboard writes"
+             " and the dashboard and TUI read.",
     )
     pc.add_argument(
         "--anomaly-window-days",
@@ -2464,10 +2466,14 @@ def _build_config_parser(subparsers, name, *, help_text, xref=None):
         name,
         help=help_text,
         formatter_class=CLIHelpFormatter,
+        # The key count is interpolated from the runtime tuple, never
+        # written as a literal: a frozen number is exactly the drift #513
+        # exists to remove, and the next key added would make this text
+        # wrong with no check to catch it.
         description=textwrap.dedent("""\
                     Manage cctally user preferences in ~/.local/share/cctally/config.json.
 
-                    Currently supported keys:
+                    Commonly set keys:
                       display.tz       Display timezone. Values: 'local' (default; host
                                        zone via the OS locale), 'utc', or any IANA name
                                        like 'America/New_York'. Per-call --tz flag on
@@ -2478,13 +2484,18 @@ def _build_config_parser(subparsers, name, *, help_text, xref=None):
                                        loopback-only), 'lan' (binds 0.0.0.0 —
                                        LAN-accessible), or any literal IP / hostname.
 
+                    Those three are a sample, not the set. {count} keys are settable in
+                    total; run `cctally config get` to list every one with its current
+                    value, or see docs/commands/config.md for values, defaults, and
+                    which keys the dashboard can write.
+
                     Examples:
                       cctally config get
                       cctally config get display.tz
                       cctally config set display.tz America/New_York
                       cctally config set dashboard.bind lan
                       cctally config unset dashboard.bind
-                """),
+                """).format(count=len(c.ALLOWED_CONFIG_KEYS)),
     )
     cfg_sub = cfg_p.add_subparsers(dest="action", required=True)
     cfg_get = cfg_sub.add_parser("get", help="Print current value(s)")

package/bin/_cctally_refresh.py

@@ -487,16 +487,26 @@ def _get_oauth_usage_config(cfg: dict) -> dict:
 # Statusline cache bust + freshness + rate-limit handler
 # =========================================================================
 
-_STATUSLINE_OAUTH_CACHE = "/tmp/claude-statusline-usage-cache.json"
+# Kept as a module alias for backward compatibility with readers that import
+# the name. The AUTHORITATIVE value is _cctally_core.STATUSLINE_OAUTH_CACHE_PATH,
+# resolved at CALL time below.
+_STATUSLINE_OAUTH_CACHE = _cctally_core.STATUSLINE_OAUTH_CACHE_PATH
 
 
-def _bust_statusline_cache(path: str = _STATUSLINE_OAUTH_CACHE) -> str:
+def _bust_statusline_cache(path: str | None = None) -> str:
     """Best-effort delete of the statusline OAuth cache file.
 
     Returns one of: ``"busted"`` (file existed and was removed),
     ``"absent"`` (file did not exist), ``"error"`` (delete failed for
     a non-FileNotFoundError reason — logged via eprint, does NOT raise).
+
+    ``path`` defaults to None and is resolved from the kernel here rather than
+    in the signature: a default argument binds at import, so it could not be
+    redirected by patching either constant, and the only defence was a stub
+    replacing this whole function at each of ten call sites (#529 S4).
     """
+    if path is None:
+        path = _cctally_core.STATUSLINE_OAUTH_CACHE_PATH
     try:
         os.remove(path)
         return "busted"

package/bin/_cctally_reporting.py

@@ -139,6 +139,7 @@ def cmd_daily(args: argparse.Namespace) -> int:
             snap = c._build_daily_snapshot(
                 view, period_start=range_start, period_end=range_end,
                 display_tz=display_tz_str, version=c._share_resolve_version(),
+                since_explicit=getattr(args, "since", None) is not None,
             )
             if args.order == "desc":
                 snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
@@ -153,14 +154,13 @@ def cmd_daily(args: argparse.Namespace) -> int:
             )
             json_groups: list = []
             table_groups: list = []
-            # `_project_disambiguate_labels` only suffixes the immediate
-            # parent-dir basename, so two distinct git-roots like
-            # `/a/x/app` + `/b/x/app` both resolve to `app (x)`. Guarantee
-            # per-group JSON-key uniqueness with a counter suffix on any
-            # residual collision — otherwise `_bucket_by_project_to_json`'s
-            # `projects[label] = ...` silently overwrites the earlier group
-            # (data loss in --json). The table_label derives from the now-
-            # unique json_label, so section headers stay distinct too.
+            # The shared disambiguation kernel progressively qualifies paths
+            # and is total for indistinguishable inputs. Keep a defensive
+            # per-group counter anyway: JSON object keys must never rely on a
+            # label formatter remaining injective, or `projects[label] = ...`
+            # would silently overwrite an earlier group. The table label
+            # derives from the now-unique json_label, so section headers stay
+            # distinct too.
             # `json_label`s are unique by construction (the `(#N)` counter
             # above). Table labels, however, can re-collide: `_alias_for`
             # matches on `display_key` first, so a basename alias like
@@ -248,6 +248,7 @@ def cmd_daily(args: argparse.Namespace) -> int:
             period_end=range_end,
             display_tz=display_tz_str,
             version=c._share_resolve_version(),
+            since_explicit=getattr(args, "since", None) is not None,
         )
         if args.order == "desc":
             snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
@@ -322,6 +323,7 @@ def cmd_monthly(args: argparse.Namespace) -> int:
             period_end=range_end,
             display_tz=display_tz_str,
             version=c._share_resolve_version(),
+            since_explicit=getattr(args, "since", None) is not None,
         )
         if args.order == "desc":
             snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
@@ -456,6 +458,7 @@ def cmd_weekly(args: argparse.Namespace) -> int:
             display_tz=display_tz_str,
             version=c._share_resolve_version(),
             breakdown_model=bool(getattr(args, "breakdown", False)),
+            since_explicit=getattr(args, "since", None) is not None,
         )
         if args.order == "desc":
             snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
@@ -613,6 +616,7 @@ def cmd_session(args: argparse.Namespace) -> int:
             version=c._share_resolve_version(),
             top_n=top_n,
             tz=tz,
+            since_explicit=getattr(args, "since", None) is not None,
         )
         c._share_render_and_emit(snap, args)
         return 0