cctally 1.95.4 → 1.96.0

package/bin/_cctally_share.py

@@ -284,6 +284,32 @@ def _share_period_label(
     )
 
 
+def _share_resolve_period_start(
+    period_start: dt.datetime,
+    *,
+    since_explicit: bool,
+    displayed_dates: "list[dt.date]",
+    display_tz: str,
+) -> dt.datetime:
+    """Keep a requested start, otherwise start at the first displayed day.
+
+    ``_parse_cli_date_range`` uses 2020-01-01 as the query sentinel when
+    ``--since`` is absent. That remains the correct read bound, but it is not
+    a period the user selected. Share artifacts therefore replace only that
+    defaulted presentation bound with the first civil day they actually
+    render. Empty artifacts retain the query bound because there is no
+    content-derived boundary to state (#527).
+    """
+    if since_explicit or not displayed_dates:
+        return period_start
+    first = min(displayed_dates)
+    zone = _resolve_tz(
+        display_tz,
+        fallback=period_start.tzinfo or dt.timezone.utc,
+    )
+    return dt.datetime(first.year, first.month, first.day, tzinfo=zone)
+
+
 def _share_display_zone(tz: "ZoneInfo | None"):
     """The concrete zone `_share_display_tz_label` names, as a tzinfo.
 
@@ -484,6 +510,7 @@ def _build_daily_snapshot(
     period_end: dt.datetime,
     display_tz: str,
     version: str,
+    since_explicit: bool,
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally daily`.
 
@@ -504,11 +531,12 @@ def _build_daily_snapshot(
     - `top_model` is the first entry of `model_breakdowns` (sorted by cost
       desc per upstream ccusage parity); empty → "—".
 
-    `period_start` / `period_end` / `display_tz` are passed by the
-    caller (they reflect the CLI's `--since` / `--until` window which
-    may extend past the data window). `theme` and `reveal_projects`
-    flow into the subtitle directly so the builder owns the canonical
-    subtitle shape — no post-build re-stamp at the gate site.
+    `period_start` / `period_end` / `display_tz` are passed by the caller.
+    An explicit range may extend past the data window; when `--since` was
+    omitted, `since_explicit=False` replaces only the share artifact's
+    sentinel start with the first displayed day (#527). `theme` and
+    `reveal_projects` flow into the subtitle directly so the builder owns the
+    canonical subtitle shape — no post-build re-stamp at the gate site.
     """
     _lib_share = _share_load_lib()
     columns = (
@@ -528,13 +556,16 @@ def _build_daily_snapshot(
 
     snap_rows: list = []
     chart_pts: list = []
+    displayed_period_dates: list[dt.date] = []
     for i, r in enumerate(rows):
         # `BucketUsage.bucket` is typed `str` (YYYY-MM-DD); guard against
         # empty / unparseable but skip the dead `dt.date` branch.
         bucket = getattr(r, "bucket", None)
         if isinstance(bucket, str) and bucket:
             try:
-                date_str = dt.date.fromisoformat(bucket).isoformat()
+                parsed_date = dt.date.fromisoformat(bucket)
+                date_str = parsed_date.isoformat()
+                displayed_period_dates.append(parsed_date)
             except ValueError:
                 date_str = bucket
         else:
@@ -564,6 +595,12 @@ def _build_daily_snapshot(
         _lib_share.Totalled(label="Days", value=str(len(chart_pts))),
         _lib_share.Totalled(label="Avg / day", value=f"${avg_cost:,.2f}"),
     )
+    period_start = _share_resolve_period_start(
+        period_start,
+        since_explicit=since_explicit,
+        displayed_dates=displayed_period_dates,
+        display_tz=display_tz,
+    )
     if rows:
         title = (
             f"Daily usage — {period_start.date().isoformat()} → "
@@ -595,6 +632,7 @@ def _build_monthly_snapshot(
     period_end: dt.datetime,
     display_tz: str,
     version: str,
+    since_explicit: bool,
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally monthly`.
 
@@ -613,11 +651,12 @@ def _build_monthly_snapshot(
     - `Δ vs prior` is computed on `cost_usd` between consecutive ASC-sorted
       months, matching the plan's intent.
 
-    `period_start` / `period_end` / `display_tz` are passed by the
-    caller (the CLI's `--since` / `--until` window may extend past
-    the data window). `theme` / `reveal_projects` flow into the
-    subtitle directly so the builder owns the canonical subtitle
-    shape — no post-build re-stamp at the gate site.
+    `period_start` / `period_end` / `display_tz` are passed by the caller.
+    An explicit range may extend past the data window; when `--since` was
+    omitted, `since_explicit=False` replaces only the share artifact's
+    sentinel start with the first displayed month (#527). `theme` /
+    `reveal_projects` flow into the subtitle directly so the builder owns the
+    canonical subtitle shape — no post-build re-stamp at the gate site.
     """
     # Caller MUST pass rows in chronological order so the BarChart bars
     # line up left-to-right with time. view.aggregated is newest-first.
@@ -632,12 +671,20 @@ def _build_monthly_snapshot(
     )
     snap_rows: list = []
     chart_pts: list = []
+    displayed_period_dates: list[dt.date] = []
     prev_cost: float | None = None
     for i, r in enumerate(rows):
         # `BucketUsage.bucket` is typed `str` ("YYYY-MM"); guard against
         # empty / unparseable but skip the dead `dt.date` branch.
         bucket = getattr(r, "bucket", None)
         month_str = bucket if isinstance(bucket, str) and bucket else "—"
+        if isinstance(bucket, str):
+            try:
+                displayed_period_dates.append(
+                    dt.date.fromisoformat(f"{bucket}-01")
+                )
+            except ValueError:
+                pass
         cost_usd = float(getattr(r, "cost_usd", 0.0) or 0.0)
         total_tokens = int(getattr(r, "total_tokens", 0) or 0)
         if prev_cost is not None and prev_cost > 0:
@@ -668,6 +715,12 @@ def _build_monthly_snapshot(
         _lib_share.Totalled(label="Months", value=str(len(chart_pts))),
         _lib_share.Totalled(label="Avg / month", value=f"${avg_cost:,.2f}"),
     )
+    period_start = _share_resolve_period_start(
+        period_start,
+        since_explicit=since_explicit,
+        displayed_dates=displayed_period_dates,
+        display_tz=display_tz,
+    )
     if rows:
         title = (
             f"Monthly usage — {period_start.strftime('%Y-%m')} → "
@@ -703,6 +756,7 @@ def _build_weekly_snapshot(
     display_tz: str,
     version: str,
     breakdown_model: bool,
+    since_explicit: bool,
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally weekly`.
 
@@ -780,6 +834,7 @@ def _build_weekly_snapshot(
 
     snap_rows: list = []
     chart_pts: list = []
+    displayed_period_dates: list[dt.date] = []
     stacks: dict[str, list] = {}
     for i, r in enumerate(rows):
         # `BucketUsage.bucket` is typed `str` ("YYYY-MM-DD"); guard against
@@ -787,7 +842,9 @@ def _build_weekly_snapshot(
         bucket = getattr(r, "bucket", None)
         if isinstance(bucket, str) and bucket:
             try:
-                week_label = dt.date.fromisoformat(bucket).isoformat()
+                parsed_date = dt.date.fromisoformat(bucket)
+                week_label = parsed_date.isoformat()
+                displayed_period_dates.append(parsed_date)
             except ValueError:
                 week_label = bucket
         else:
@@ -852,6 +909,12 @@ def _build_weekly_snapshot(
         _lib_share.Totalled(label="Avg %/wk", value=f"{avg_pct:.1f}%"),
         _lib_share.Totalled(label="Peak %", value=f"{peak_pct:.1f}%"),
     )
+    period_start = _share_resolve_period_start(
+        period_start,
+        since_explicit=since_explicit,
+        displayed_dates=displayed_period_dates,
+        display_tz=display_tz,
+    )
     title = (
         f"Weekly usage — last {len(rows)} weeks"
         if rows
@@ -1438,6 +1501,7 @@ def _build_session_snapshot(
     version: str,
     top_n: int | None,
     tz: "ZoneInfo | None",
+    since_explicit: bool,
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally session`.
 
@@ -1528,6 +1592,7 @@ def _build_session_snapshot(
     augmented = _session_disambiguate_labels(sorted_sessions)
     snap_rows: list = []
     chart_pts: list = []
+    displayed_period_dates: list[dt.date] = []
     for idx, s in enumerate(sorted_sessions):
         bare_label = (
             os.path.basename(s.project_path or "")
@@ -1545,6 +1610,9 @@ def _build_session_snapshot(
         last_str = format_display_dt(
             s.last_activity, tz, fmt="%Y-%m-%d %H:%M", suffix=False,
         )
+        displayed_period_dates.append(
+            s.last_activity.astimezone(_share_display_zone(tz)).date()
+        )
         models_text = ", ".join(s.models) if s.models else "—"
         snap_rows.append(_lib_share.Row(cells={
             "session": _lib_share.TextCell(sid_short),
@@ -1576,6 +1644,12 @@ def _build_session_snapshot(
         _lib_share.Totalled(label="Sum", value=f"${sum_cost:,.2f}"),
         _lib_share.Totalled(label="Sessions", value=str(len(chart_pts))),
     )
+    period_start = _share_resolve_period_start(
+        period_start,
+        since_explicit=since_explicit,
+        displayed_dates=displayed_period_dates,
+        display_tz=display_tz,
+    )
     if sorted_sessions:
         if truncated:
             title = f"Top {len(snap_rows)} sessions"

package/bin/_cctally_store.py

@@ -748,7 +748,7 @@ def stats_open_time_guard(
             except (BlockingIOError, OSError):
                 if time.monotonic() >= deadline:
                     raise _cctally_db.StatsDbMaintenanceError(
-                        _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+                        _stats_open_maintenance_timeout_message()
                     )
                 time.sleep(0.02)
         _cctally_core.note_stats_maintenance_acquired()
@@ -829,6 +829,18 @@ _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG = (
 )
 
 
+def _stats_open_maintenance_timeout_message() -> str:
+    """Name a confirmed detached rebuild when it owns the maintenance wait."""
+    request = _read_stats_heal_request()
+    if (
+        request
+        and request.get("forensicsDisposition") == "confirmed"
+        and _stats_heal_worker_active()
+    ):
+        return str(_cctally_db.StatsHealDeferred("pending"))
+    return _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+
+
 def _flock_bounded(lock_fh, operation: int, timeout_s: float) -> bool:
     """Poll for ``operation`` on ``lock_fh`` until ``timeout_s`` expires.
 
@@ -953,10 +965,10 @@ def _pending_stats_publication_never_replaced(db_path) -> bool:
     reads that as "replaced". The proxy is used only across processes, where
     that cleanup cannot reach, so the weaker property is the one it needs.
 
-    A marker carrying no `scratchPath` cannot prove it published, so it is
-    treated as never-replaced. No released binary has ever written one — the
-    marker and this field ship together — so the branch exists only to keep an
-    unreadable marker from wedging every open.
+    A marker carrying no `scratchPath` proves neither outcome and therefore
+    still owes a verdict. No released binary has ever written one — the marker
+    and this field ship together — but failing closed keeps that malformed
+    state from silently accepting unvalidated live bytes.
 
     **In-place publication** answers with the publication's own stamp, because
     it attaches the scratch read-only and the scratch survives commit and
@@ -973,16 +985,9 @@ def _pending_stats_publication_never_replaced(db_path) -> bool:
         return True
     if str(state.get("status") or "") != "pending":
         return False
-    if str(state.get("mechanism") or "replace") == "in_place":
-        import _cctally_journal
+    import _cctally_journal
 
-        return _cctally_journal.in_place_publication_proven_predecessor(
-            db_path, state
-        )
-    scratch = state.get("scratchPath")
-    if not isinstance(scratch, str) or not scratch:
-        return True
-    return pathlib.Path(scratch).exists()
+    return _cctally_journal._pending_publication_owes_nothing(db_path, state)
 
 
 def _stats_publication_failed_error(
@@ -1411,7 +1416,7 @@ def stats_open_guarded(
                 lock_fh, fcntl.LOCK_SH, _STATS_OPEN_MAINTENANCE_WAIT_S
             ):
                 raise _cctally_db.StatsDbMaintenanceError(
-                    _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+                    _stats_open_maintenance_timeout_message()
                 )
             if marker.exists():
                 fcntl.flock(lock_fh, fcntl.LOCK_UN)
@@ -1425,7 +1430,7 @@ def stats_open_guarded(
                     lock_fh, fcntl.LOCK_EX, _STATS_OPEN_RESUME_WAIT_S
                 ):
                     raise _cctally_db.StatsDbMaintenanceError(
-                        _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+                        _stats_open_maintenance_timeout_message()
                     )
                 try:
                     if marker.exists():
@@ -1450,7 +1455,7 @@ def stats_open_guarded(
                     lock_fh, fcntl.LOCK_EX, _STATS_OPEN_RESUME_WAIT_S
                 ):
                     raise _cctally_db.StatsDbMaintenanceError(
-                        _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+                        _stats_open_maintenance_timeout_message()
                     )
                 # Recovery calls `rebuild_stats_index`, whose in-place publisher
                 # reopens the live destination through `stats_open_guarded`.
@@ -1496,7 +1501,7 @@ def stats_open_guarded(
                     lock_fh, fcntl.LOCK_SH, _STATS_OPEN_MAINTENANCE_WAIT_S
                 ):
                     raise _cctally_db.StatsDbMaintenanceError(
-                        _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+                        _stats_open_maintenance_timeout_message()
                     )
                 if marker.exists() or pending.exists():
                     fcntl.flock(lock_fh, fcntl.LOCK_UN)
@@ -1516,7 +1521,7 @@ def stats_open_guarded(
                     lock_fh, fcntl.LOCK_EX, _STATS_OPEN_RESUME_WAIT_S
                 ):
                     raise _cctally_db.StatsDbMaintenanceError(
-                        _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+                        _stats_open_maintenance_timeout_message()
                     )
                 try:
                     _resolve_stats_publication_marker(db_path)
@@ -1526,7 +1531,7 @@ def stats_open_guarded(
                     lock_fh, fcntl.LOCK_SH, _STATS_OPEN_MAINTENANCE_WAIT_S
                 ):
                     raise _cctally_db.StatsDbMaintenanceError(
-                        _STATS_OPEN_MAINTENANCE_TIMEOUT_MSG
+                        _stats_open_maintenance_timeout_message()
                     )
                 if marker.exists() or pending.exists():
                     fcntl.flock(lock_fh, fcntl.LOCK_UN)
@@ -2538,7 +2543,7 @@ def cmd_stats_corruption_heal_internal(args) -> int:
         heal_id = str(request.get("healId") or "")
         try:
             outcome = _run_stats_corruption_heal(request)
-        except Exception as exc:
+        except (_cctally_db.StatsRebuildDeferred, Exception) as exc:
             # Retryable: the marker stays so a later detection is admitted
             # once its retry window expires.
             _record_stats_heal_outcome(heal_id, "failed", error=exc)

package/bin/_cctally_tui.py

@@ -4304,10 +4304,18 @@ def _tui_empty_snapshot(now_utc: dt.datetime) -> DataSnapshot:
     )
 
 
+def _stats_open_failure_is_corruption(exc: BaseException) -> bool:
+    """Keep epoch deferral distinct from heal deferral and read failures."""
+    c = _cctally()
+    if isinstance(exc, c.StatsRebuildDeferred):
+        return isinstance(exc, c.StatsHealDeferred)
+    return True
+
+
 def _tui_stats_retry_degraded_snapshot(
     *,
     now_utc: dt.datetime,
-    exc: Exception,
+    exc: BaseException,
     precompute_envelope: bool,
     runtime_bind: "str | None",
 ) -> DataSnapshot:
@@ -4333,7 +4341,7 @@ def _tui_stats_retry_degraded_snapshot(
             SyncFailureAttribution(
                 leg="stats-open",
                 database="stats",
-                corruption=True,
+                corruption=_stats_open_failure_is_corruption(exc),
             ),
         ),
         doctor_payload=doctor_payload,
@@ -6724,9 +6732,7 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
                     SyncFailureAttribution(
                         leg="stats-open",
                         database="stats",
-                        corruption=isinstance(
-                            exc, _cctally().StatsHealDeferred
-                        ),
+                        corruption=_stats_open_failure_is_corruption(exc),
                     ),
                 ),
                 generated_at=dt.datetime.now(dt.timezone.utc),

package/bin/_lib_dashboard_settings_contract.py

@@ -0,0 +1,86 @@
+"""Which settings leaves ``POST /api/settings`` may write.
+
+Single source of truth for the dashboard settings contract (#513 S1). Kept
+pure and dependency-free -- it imports nothing -- so the documentation test
+can read the contract without loading the dashboard, and so there is no cycle
+with ``_cctally_config``.
+
+Three states, not two. A leaf the endpoint persists is ``WRITABLE``. A leaf
+it deliberately accepts and does not persist is ``KNOWN_IGNORED``: there are
+exactly four, pinned by #134 (the Codex partial-merge contract, where amounts
+stay CLI-only) and #143 (``budget.period`` drives the forward-only reconcile
+without being stored here). Anything absent from the map is unknown to this
+endpoint and is rejected with the offending dotted path as ``field``.
+
+The third state matters because two states would force ``budget.period`` to
+be described as either writable or rejected, and it is neither.
+"""
+
+WRITABLE = "writable"
+KNOWN_IGNORED = "known_ignored"
+
+#: Fully-qualified dotted path -> disposition. Order is the endpoint's block
+#: order and is not significant; membership is.
+SETTINGS_LEAF_DISPOSITIONS = {
+    "display.tz": WRITABLE,
+    "alerts.enabled": WRITABLE,
+    "alerts.projected_enabled": WRITABLE,
+    "alerts.notifier": WRITABLE,
+    "dashboard.cache_failure_markers": WRITABLE,
+    "dashboard.live_tail": WRITABLE,
+    "dashboard.lan_auth": WRITABLE,
+    "update.check.enabled": WRITABLE,
+    "update.check.ttl_hours": WRITABLE,
+    "update.channel": WRITABLE,
+    "cache_report.anomaly_threshold_pp": WRITABLE,
+    "budget.weekly_usd": WRITABLE,
+    "budget.alerts_enabled": WRITABLE,
+    "budget.alert_thresholds": WRITABLE,
+    "budget.projected_enabled": WRITABLE,
+    "budget.project_alerts_enabled": WRITABLE,
+    "budget.codex.alerts_enabled": WRITABLE,
+    "budget.codex.projected_enabled": WRITABLE,
+    # #143: answered 200 and drives the forward-only reconcile, never stored.
+    "budget.period": KNOWN_IGNORED,
+    # #134: CLI-only amounts, preserved from the persisted block on a merge.
+    "budget.codex.amount_usd": KNOWN_IGNORED,
+    "budget.codex.period": KNOWN_IGNORED,
+    "budget.codex.alert_thresholds": KNOWN_IGNORED,
+}
+
+
+def _ancestors(path):
+    """Yield every proper dotted prefix of ``path``, outermost first."""
+    parts = path.split(".")
+    for i in range(1, len(parts)):
+        yield ".".join(parts[:i])
+
+
+#: Every interior path a request may descend through, derived from the leaf
+#: paths so a new leaf can never forget to register its parent.
+SETTINGS_OBJECT_PATHS = frozenset(
+    parent
+    for path in SETTINGS_LEAF_DISPOSITIONS
+    for parent in _ancestors(path)
+)
+
+#: The six blocks the endpoint accepts at the top level.
+SETTINGS_TOP_LEVEL_BLOCKS = frozenset(
+    path.split(".")[0] for path in SETTINGS_LEAF_DISPOSITIONS
+)
+
+#: Blocks that are NOT a valid no-op when sent empty. A named block carrying
+#: no leaves is an ordinary partial-PUT no-op everywhere else -- notably
+#: ``{"cache_report": {}}``, which is what a combined save sends when the user
+#: never opened that tab, and which must keep answering 200.
+SETTINGS_REQUIRED_LEAVES = {"display": frozenset({"display.tz"})}
+
+
+def disposition_for(path):
+    """Return ``WRITABLE``, ``KNOWN_IGNORED``, or ``None`` for an unknown path."""
+    return SETTINGS_LEAF_DISPOSITIONS.get(path)
+
+
+def is_object_path(path):
+    """True when ``path`` is an interior node a request may descend through."""
+    return path in SETTINGS_OBJECT_PATHS

package/bin/_lib_journal.py

@@ -259,8 +259,10 @@ def reusable_bootstrap_name(candidate_digest, candidate_size, existing):
 
     Reusing an older match instead would stamp the cursor behind a bootstrap the
     cursor does not cover, and the next ingest would fold that stale bootstrap's
-    records into stats.db. Writing a fresh segment is the pre-reuse behaviour and
-    restores the pre-reuse invariant, because a minted name always sorts last.
+    records into stats.db. Writing a fresh segment invokes the caller's
+    monotonic name selector, which compares wall time with the published
+    bootstrap set and mints after the canonically newest segment when the clock
+    moved backwards (#509).
 
     Returns None when the newest bootstrap does not match, which covers the
     ordinary first-cutover path, the genuinely-differing-export path, and the

package/bin/_lib_render.py

@@ -28,6 +28,8 @@ Sibling dependencies (loaded at module-load time via ``_load_lib``):
     used across every breakdown-aware table).
   * ``_lib_display_tz`` — ``_resolve_tz`` (IANA tz resolution for the
     Codex session-table date columns).
+  * ``_lib_share`` — ``disambiguate_basenames`` (the single project-label
+    collision algorithm shared with artifact preparation).
 
 ``bin/cctally`` back-references via module-level callable shims
 (spec §5.5; same precedent as ``bin/_cctally_record.py``'s 34 shims):
@@ -98,6 +100,7 @@ _lib_pricing = _load_lib("_lib_pricing")
 _short_model_name = _lib_pricing._short_model_name
 
 _lib_display_tz = _load_lib("_lib_display_tz")
+_lib_share = _load_lib("_lib_share")
 _resolve_tz = _lib_display_tz._resolve_tz
 
 # JSON wire-format kernel — the additive camelCase schemaVersion stamp
@@ -2722,11 +2725,11 @@ def _project_disambiguate_labels(rows: list[dict]) -> dict[int, str]:
     """Return ``{row_index: disambiguated_label}`` for project rows whose
     bare ``display_key`` collides with another row's basename.
 
-    When two projects share a basename (e.g., two ``app`` directories under
-    different parents), suffix the colliding rows with the parent-directory
-    segment ("(work)" / "(personal)") so they remain visually and
-    semantically distinct. Prefer ``key.git_root`` as the disambiguation
-    source when present; fall back to ``key.bucket_path`` for no-git rows.
+    ``_lib_share.disambiguate_basenames`` owns the collision algorithm. This
+    adapter identifies the colliding project identities in the row-shaped
+    renderer input, deduplicates repeated rows for one canonical bucket, and
+    fans the kernel labels back out. Prefer ``key.git_root`` as the kernel
+    path when present; fall back to ``key.bucket_path`` for no-git rows.
 
     Used by:
       - ``_render_project_table`` (terminal table render).
@@ -2737,20 +2740,45 @@ def _project_disambiguate_labels(rows: list[dict]) -> dict[int, str]:
     Rows that do not collide are absent from the returned dict; callers
     fall back to ``key.display_key`` for those.
     """
-    display_counts: dict[str, int] = {}
-    for r in rows:
-        dk = r["key"].display_key
-        display_counts[dk] = display_counts.get(dk, 0) + 1
-    augmented: dict[int, str] = {}
-    for idx, r in enumerate(rows):
-        if display_counts[r["key"].display_key] > 1:
-            source_path = r["key"].git_root or r["key"].bucket_path
-            if source_path:
-                parent = (
-                    os.path.basename(os.path.dirname(source_path)) or "/"
-                )
-                augmented[idx] = f"{r['key'].display_key} ({parent})"
-    return augmented
+    identity_to_unique: dict[str, int] = {}
+    unique_projects: list[tuple[str, str]] = []
+    row_unique_indices: list[int] = []
+    display_groups: dict[str, list[int]] = {}
+
+    for row in rows:
+        key = row["key"]
+        identity = key.bucket_path
+        unique_idx = identity_to_unique.get(identity)
+        if unique_idx is None:
+            unique_idx = len(unique_projects)
+            identity_to_unique[identity] = unique_idx
+            source_path = key.git_root or key.bucket_path
+            unique_projects.append((key.display_key, source_path))
+            display_groups.setdefault(key.display_key, []).append(unique_idx)
+        row_unique_indices.append(unique_idx)
+
+    colliding_unique = {
+        unique_idx
+        for unique_indices in display_groups.values()
+        if len(unique_indices) > 1
+        for unique_idx in unique_indices
+    }
+    if not colliding_unique:
+        return {}
+
+    ordered_unique = sorted(colliding_unique)
+    kernel_labels = _lib_share.disambiguate_basenames(
+        [unique_projects[unique_idx][1] for unique_idx in ordered_unique]
+    )
+    labels_by_unique = {
+        unique_idx: kernel_labels[kernel_idx]
+        for kernel_idx, unique_idx in enumerate(ordered_unique)
+    }
+    return {
+        row_idx: labels_by_unique[unique_idx]
+        for row_idx, unique_idx in enumerate(row_unique_indices)
+        if unique_idx in labels_by_unique
+    }
 
 
 def _render_project_table(
@@ -3214,4 +3242,3 @@ def _render_five_hour_blocks_table(
     print(_boxed_table(headers, rows, aligns, compact=args.compact))
     glyph = " · ⚡ = block crossed weekly reset" if has_crossed else ""
     print(f"\n{len(block_dicts)} blocks · cost: ${total_cost:.2f}{glyph}")
-