cctally 1.9.0 → 1.10.0

package/bin/_cctally_dashboard.py

@@ -1026,6 +1026,7 @@ def _build_share_panel_data(panel: str, options: dict,
     if panel == "blocks":      return _build_blocks_share_panel_data(options, snap)
     if panel == "sessions":    return _build_sessions_share_panel_data(options, snap)
     if panel == "current-week": return _build_current_week_share_panel_data(options, snap)
+    if panel == "projects":    return _build_projects_share_panel_data(options, snap)
     raise ValueError(f"unknown share panel: {panel!r}")
 
 
@@ -1526,6 +1527,151 @@ def _build_sessions_share_panel_data(options: dict,
     return {"sessions": sessions}
 
 
+def _build_projects_share_panel_data(options: dict,
+                                      snap: "DataSnapshot | None") -> dict:
+    """Projects panel_data — per-project rollup over a selectable window.
+
+    Reuses ``DataSnapshot.projects_envelope`` already populated by the
+    sync thread, so the share artifact matches what the dashboard panel
+    is showing. ``options.windowWeeks`` (spec §5.4 + §7.3) selects the
+    aggregation window:
+
+      - ``windowWeeks=1`` (default): current_week only (PANEL share flow).
+      - ``windowWeeks ∈ {4, 8, 12}``: sum across the trend window
+        (MODAL share flow — supplies its active window pill).
+
+    Output shape (consumed by `_build_projects_recap` / `_visual` /
+    `_detail` builders below — see bin/_lib_share_templates.py):
+
+      {
+        "rows": [
+          {
+            "key":            "<disambiguated display_key>",
+            "bucket_path":    "<absolute path>",
+            "cost_usd":       <float>,
+            "attributed_pct": <float | None>,
+            "sessions_count": <int>,
+          },
+          ...                                       # desc by cost
+        ],
+        "total_cost_usd": <float>,
+        "period_start":   <dt.datetime UTC>,
+        "period_end":     <dt.datetime UTC>,
+        "window_weeks":   <int>,
+      }
+
+    The Privacy invariant per spec §7.4 lives at the share-render gate
+    (`_lib_share._scrub`), NOT here. This panel_data carries REAL
+    display_keys + bucket_paths; downstream `_scrub` rewrites them
+    when ``reveal_projects=false``.
+    """
+    env: dict = getattr(snap, "projects_envelope", None) or {} if snap else {}
+    if not env:
+        # First-tick / sub-build failure → render a minimal "no data"
+        # shape. _build_project_snapshot already handles empty rows
+        # downstream via "no data" title.
+        now = _share_now_utc()
+        return {
+            "rows":           [],
+            "total_cost_usd": 0.0,
+            "period_start":   now - dt.timedelta(days=7),
+            "period_end":     now,
+            "window_weeks":   1,
+        }
+    weeks_back_raw = options.get("windowWeeks", 1)
+    try:
+        weeks_back = int(weeks_back_raw)
+    except (TypeError, ValueError):
+        weeks_back = 1
+    if weeks_back not in {1, 4, 8, 12}:
+        weeks_back = 1
+    cw = env.get("current_week", {}) or {}
+    trend = env.get("trend", {}) or {}
+
+    # `effective_weeks` is the actual number of weeks of data the artifact
+    # represents. For the 1-week (panel) path it's always 1. For multi-week
+    # (modal) the trend envelope may carry fewer weeks than requested on
+    # thin-history dashboards (fresh installs, post-rebuild), so clamp to
+    # whatever history exists — otherwise the share artifact would label
+    # itself "Last 12 weeks" and render a 12-week date range while only
+    # (say) 3 weeks of rows were aggregated. The period bounds and the
+    # `window_weeks` returned downstream both ride on `effective_weeks`.
+    rows: list[dict]
+    if weeks_back == 1:
+        effective_weeks = 1
+        rows = [
+            {
+                "key":            r["key"],
+                "bucket_path":    r["bucket_path"],
+                "cost_usd":       float(r["cost_usd"]),
+                "attributed_pct": r.get("attributed_pct"),
+                "sessions_count": int(r.get("sessions_count", 0) or 0),
+            }
+            for r in (cw.get("rows") or [])
+        ]
+        total_cost = float(cw.get("total_cost_usd", 0.0) or 0.0)
+    else:
+        # Multi-week: sum across the trailing `weeks_back` slices of
+        # trend.projects[i].weekly_cost. attributed_pct sums each
+        # project's weekly_pct (None when no week has a snapshot).
+        n_weeks = len(trend.get("weeks") or [])
+        # The trend window is already clamped to <= 12; we take the
+        # trailing `weeks_back` slices.
+        take = min(weeks_back, n_weeks)
+        # On a brand-new dashboard with zero trend weeks, fall back to a
+        # single-week (current_week) period so the artifact's labelling
+        # still names a real range instead of "Last 0 weeks".
+        effective_weeks = max(1, take)
+        rows = []
+        running_total = 0.0
+        for tp in trend.get("projects") or []:
+            wc = (tp.get("weekly_cost") or [])[-take:]
+            wp = (tp.get("weekly_pct") or [])[-take:]
+            ws = (tp.get("sessions_per_week") or [])[-take:]
+            cost = float(sum(wc))
+            running_total += cost
+            valid_pct = [float(p) for p in wp if p is not None]
+            attributed = sum(valid_pct) if valid_pct else None
+            # Sum per-week distinct session counts. Slight over-count when a
+            # single session spans a week boundary; the envelope's per-week
+            # bucketing has no session-id sets to union, so this is the
+            # cheapest reasonable approximation and matches the modal's
+            # client-side derivation (envelope.ts → ProjectsModal.tsx).
+            rows.append({
+                "key":            tp["key"],
+                "bucket_path":    tp["bucket_path"],
+                "cost_usd":       cost,
+                "attributed_pct": attributed,
+                "sessions_count": int(sum(ws)),
+            })
+        rows.sort(key=lambda r: (-r["cost_usd"], r["key"]))
+        total_cost = running_total
+
+    # Compute window bounds from the *effective* span — see the
+    # `effective_weeks` note above. The rows in this panel_data are
+    # week-to-date (current_week.rows are aggregated through "now"; the
+    # multi-week branch sums weekly_cost slices, with the trailing slice
+    # also week-to-date), so clip `period_end` to min(reset_at, now).
+    # Without the clip a mid-week export advertises a future reset date
+    # in the rendered period/frontmatter and disagrees with the live
+    # dashboard's "spent this week" KPI, which is symmetrically clipped
+    # by `_build_current_week_share_panel_data`'s use of `now`.
+    cw_start_iso = cw.get("week_start_at") or _share_now_utc_iso()
+    cw_start = parse_iso_datetime(cw_start_iso, "projects.cw_start")
+    week_end = cw_start + dt.timedelta(days=7)
+    now = _share_now_utc()
+    period_end = week_end if week_end <= now else now
+    period_start = cw_start - dt.timedelta(days=7 * (effective_weeks - 1))
+
+    return {
+        "rows":           rows,
+        "total_cost_usd": total_cost,
+        "period_start":   period_start,
+        "period_end":     period_end,
+        "window_weeks":   effective_weeks,
+    }
+
+
 
 
 # === Dashboard server core: _SnapshotRef + SSEHub + envelope builders =====
@@ -2310,6 +2456,888 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
     return rows
 
 
+# --- Projects panel / modal (spec 2026-05-19-projects-panel-design.md) ------
+#
+# Per-tick projects envelope builder. Runs on the sync thread that
+# populates ``DataSnapshot``; the dashboard's pure ``snapshot_to_envelope``
+# reads it back unchanged and assigns to ``envelope["projects"]`` so the
+# serializer stays DB-free.
+#
+# See spec §5.2 (envelope shape), §6.2 (signatures), §6.4 (memoization),
+# §9.2 (R-PROJ1..R-PROJ5 reconcile invariants).
+#
+# Identity:
+#   - ``key``         = disambiguated ``ProjectKey.display_key`` via
+#                       ``_lib_render._project_disambiguate_labels``.
+#                       Stable within a single envelope (a `foo` collision
+#                       resolves to `foo (parent_dir)`).
+#   - ``bucket_path`` = canonical equality key (``ProjectKey.bucket_path``)
+#                       — the absolute on-disk path. Privacy-sensitive;
+#                       _lib_share._scrub strips it on the share path.
+
+# Per-tick memo (spec §6.4 + memory: *Pre-probe before sync_cache*).
+# Keyed on (max(session_entries.id), current_week.week_start_at,
+# weeks_back); single entry, in-process only. Bounded per-tick cost on
+# large caches: subsequent calls within the same sync tick hit the
+# memo and skip the aggregation walk.
+_PROJECTS_ENV_MEMO: dict = {"key": None, "value": None}
+
+
+def _projects_reset_memo() -> None:
+    """Clear the projects envelope memo. Used by unit tests that want to
+    measure the inner aggregation cost in isolation."""
+    _PROJECTS_ENV_MEMO["key"] = None
+    _PROJECTS_ENV_MEMO["value"] = None
+
+
+def _projects_week_start_monday_utc(ts: "dt.datetime") -> "dt.datetime":
+    """Anchor ``ts`` to its containing ISO-Monday 00:00 UTC subscription
+    week start. Fallback shape used when no snapshot anchor is available
+    — mirrors ``cmd_project``'s Monday fallback (bin/cctally:4711)."""
+    base = ts.astimezone(dt.timezone.utc)
+    return (base - dt.timedelta(days=base.weekday())).replace(
+        hour=0, minute=0, second=0, microsecond=0,
+    )
+
+
+def _projects_week_label(week_start: "dt.datetime") -> str:
+    """Render a `wk Mon DD` label for the trend chart x-axis.
+
+    Per spec §5.2's `weeks[].week_label` example (`"wk Apr 22"`).
+    UTC-anchored so JSON output is tz-agnostic.
+    """
+    return f"wk {week_start.strftime('%b %d')}"
+
+
+def _projects_iter_session_entries(conn: "sqlite3.Connection",
+                                   *,
+                                   since: "dt.datetime",
+                                   until: "dt.datetime"):
+    """Read ``session_entries`` joined with ``session_files`` over
+    [since, until]. Yields rows directly off the passed conn — no
+    cache.db monkeypatch, no production ``get_claude_session_entries``
+    pipeline. The fixture DBs co-locate both schemas in one file; the
+    production wiring opens both DBs and ATTACHes cache.db as a schema
+    on the stats conn (see ``_run_dashboard_sync_tick``).
+    """
+    since_iso = since.astimezone(dt.timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    until_iso = until.astimezone(dt.timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    cur = conn.execute(
+        "SELECT e.id, e.timestamp_utc, e.model, e.input_tokens, "
+        "       e.output_tokens, e.cache_create_tokens, e.cache_read_tokens, "
+        "       e.cost_usd_raw, e.source_path, "
+        "       sf.session_id, sf.project_path "
+        "FROM session_entries e "
+        "LEFT JOIN session_files sf ON sf.path = e.source_path "
+        "WHERE e.timestamp_utc >= ? AND e.timestamp_utc <= ? "
+        "ORDER BY e.timestamp_utc ASC, e.id ASC",
+        (since_iso, until_iso),
+    )
+    for row in cur:
+        yield row
+
+
+def _build_projects_envelope(
+    conn: "sqlite3.Connection",
+    *,
+    now_utc: "dt.datetime",
+    current_week: "Any | None" = None,
+    weeks_back: int = 12,
+) -> dict:
+    """Build the ``projects.{current_week, trend}`` envelope block.
+
+    Reuses ``cmd_project``'s identity model — per-(``ProjectKey``, week)
+    rollup over ``session_entries`` with display-key disambiguation via
+    ``_project_disambiguate_labels`` — but emits the simpler envelope
+    shape from spec §5.2 (no per-model breakdowns, no first/last seen
+    per session, no per-row $/1%; just cost / attributed_pct / sessions).
+
+    Week boundaries follow ``cmd_project``'s Monday-anchored UTC
+    fallback (``bin/cctally:4711``); ``weekly_usage_snapshots`` rows are
+    matched by ``week_start_date`` (date-only) for ``attributed_pct``.
+
+    ``current_week`` is passed through opaquely — if non-None and
+    carrying a ``.week_start_at`` UTC datetime, that boundary supplants
+    the Monday fallback for the current week's bucket. None (the
+    default) preserves the fallback.
+
+    Determinism: same conn + same ``now_utc`` ⇒ byte-identical JSON
+    (R-PROJ5 invariant). Per-tick memoized on
+    ``(max(session_entries.id), cw_week_start, weeks_back)``.
+    """
+    c = _cctally()
+
+    # ---- Pre-probe gate / memoization (spec §6.4) -----------------------
+    # `attributed_pct` and trend `total_pct` are functions of
+    # `weekly_usage_snapshots.weekly_percent`, which the throttled OAuth
+    # refresh path can advance between session_entries writes. Probe
+    # `MAX(weekly_usage_snapshots.id)` so the memo invalidates on that
+    # surface too (mirrors the operational-error guard the attribution
+    # SELECT uses below).
+    cur = conn.execute("SELECT COALESCE(MAX(id), 0) FROM session_entries")
+    max_id = cur.fetchone()[0]
+    try:
+        cur = conn.execute(
+            "SELECT COALESCE(MAX(id), 0) FROM weekly_usage_snapshots"
+        )
+        max_wus_id = cur.fetchone()[0]
+    except sqlite3.OperationalError:
+        max_wus_id = 0
+    cw_key: "dt.datetime | None" = None
+    if current_week is not None:
+        cw_key = getattr(current_week, "week_start_at", None)
+    memo_key = (max_id, max_wus_id, cw_key, weeks_back)
+    cached = _PROJECTS_ENV_MEMO.get("value")
+    if cached is not None and _PROJECTS_ENV_MEMO.get("key") == memo_key:
+        return cached
+
+    # ---- Week-start anchor (current subscription week) ------------------
+    # ``TuiCurrentWeek.week_start_at`` is NOT a valid Monday lookup key
+    # after ``_apply_midweek_reset_override`` — it is shifted to the
+    # in-week reset instant (e.g. Friday 13:00 UTC) while the bucket
+    # aggregator below snaps every entry to its containing ISO-Monday
+    # via ``_week_for``. Using ``cw_key`` directly as the bucket-lookup
+    # key strands all current-week activity in an empty bucket and emits
+    # ``rows: []`` with ``total_cost_usd: 0.0``. Snap to the canonical
+    # Monday-UTC week anchor here so the lookup keys align — same
+    # invariant the weekly handling notes call out for
+    # ``weekly_usage_snapshots``/``percent_milestones`` cross-table
+    # joins. Regression: ``tests/fixtures/dashboard/reset-week/`` +
+    # ``test_current_week_rows_populated_after_midweek_reset``.
+    if cw_key is not None:
+        cw_start = _projects_week_start_monday_utc(cw_key)
+    else:
+        cw_start = _projects_week_start_monday_utc(now_utc)
+
+    # Build a list of canonical Monday-anchored week starts ending with
+    # cw_start, oldest → newest, of length ``weeks_back``. Clamping to
+    # actual history happens after the entry walk reveals what weeks
+    # have any activity.
+    weeks_full = [
+        cw_start - dt.timedelta(days=7 * (weeks_back - 1 - i))
+        for i in range(weeks_back)
+    ]
+    cw_end = cw_start + dt.timedelta(days=7)
+    since_dt = weeks_full[0]
+    until_dt = cw_end  # exclusive end; SQL is `>= since AND <= until`
+
+    # ---- Bucket entries per (ProjectKey, week_start) --------------------
+    # `_resolve_project_key` is the production resolver; we use git-root
+    # mode (default for `cmd_project --group` absent) — matches the
+    # CLI's default.
+    _resolve_project_key = c._resolve_project_key
+    resolver_cache: dict = {}
+
+    # buckets[(bucket_path, week_start)] -> {key, cost, sessions, ...}
+    buckets: dict[tuple[str, dt.datetime], dict] = {}
+    # Track total cost per week across ALL entries (attribution denominator).
+    total_cost_by_week: dict[dt.datetime, float] = {}
+    # Track first-seen ProjectKey instance per bucket_path so we can pass
+    # the dict to `_project_disambiguate_labels` (which keys on `key.bucket_path`
+    # equality via ProjectKey.__eq__).
+    key_by_bucket: dict[str, Any] = {}
+
+    def _week_for(ts: dt.datetime) -> "dt.datetime | None":
+        wstart = _projects_week_start_monday_utc(ts)
+        if wstart < weeks_full[0] or wstart > weeks_full[-1]:
+            return None
+        return wstart
+
+    # Orphan handling: `_projects_iter_session_entries` LEFT JOINs
+    # `session_files` so entries whose source_path has no
+    # `session_files` row return `project_path = NULL`. Below,
+    # `_resolve_project_key(None, ...)` maps that to the
+    # `(unknown)` bucket — same identity the drill-down's explicit
+    # orphan scan in `_project_detail_for_window` (see the
+    # ``if unknown_bucket:`` branch around the
+    # `orphan_cur` SELECT) collects via a NULL-side LEFT JOIN. The
+    # two paths converge on the same `(unknown)` source_path set.
+    for row in _projects_iter_session_entries(
+        conn, since=since_dt, until=until_dt,
+    ):
+        (entry_id, ts_iso, model, input_tok, output_tok,
+         cache_create, cache_read, cost_raw, source_path,
+         session_id, project_path) = row
+        if model == "<synthetic>":
+            continue
+        # Parse timestamp; assume Z / +00:00 — production iterators do
+        # the same via `parse_iso_datetime`.
+        ts = parse_iso_datetime(ts_iso, "session_entries.timestamp_utc")
+        wstart = _week_for(ts)
+        if wstart is None:
+            continue
+
+        # Entry cost via the shared pricing chokepoint.
+        entry_cost = _calculate_entry_cost(
+            model,
+            {
+                "input_tokens": input_tok or 0,
+                "output_tokens": output_tok or 0,
+                "cache_creation_input_tokens": cache_create or 0,
+                "cache_read_input_tokens": cache_read or 0,
+            },
+            mode="auto",
+            cost_usd=cost_raw,
+        )
+
+        # Project-key identity (`git_root` mode = production default).
+        pkey = _resolve_project_key(project_path, "git-root", resolver_cache)
+        bkey = (pkey.bucket_path, wstart)
+        b = buckets.get(bkey)
+        if b is None:
+            b = {
+                "key": pkey,
+                "cost_usd": 0.0,
+                "sessions": set(),
+                "first_seen": ts,
+                "last_seen": ts,
+            }
+            buckets[bkey] = b
+        b["cost_usd"] += entry_cost
+        if session_id:
+            b["sessions"].add(session_id)
+        elif source_path:
+            # Fallback: treat one source_path as one session when
+            # session_files.session_id is NULL (lazy population).
+            b["sessions"].add(source_path)
+        if ts < b["first_seen"]:
+            b["first_seen"] = ts
+        if ts > b["last_seen"]:
+            b["last_seen"] = ts
+        total_cost_by_week[wstart] = (
+            total_cost_by_week.get(wstart, 0.0) + entry_cost
+        )
+        # Remember first-seen ProjectKey for each bucket_path so the
+        # disambiguator pass below sees consistent ProjectKey instances.
+        if pkey.bucket_path not in key_by_bucket:
+            key_by_bucket[pkey.bucket_path] = pkey
+
+    # ---- Load weekly_usage_snapshots for attribution --------------------
+    # weekly_percent keyed by week_start (UTC datetime, Monday). We
+    # match on `week_start_date` (date-only) since that's the canonical
+    # cross-table key per the CLAUDE.md weekly handling notes.
+    #
+    # We use the LATEST snapshot per week_start_date — NOT MAX — because
+    # the "weekly_percent is monotonic within a week" invariant breaks
+    # on weeks that receive an in-place credit (see CLAUDE.md "In-place
+    # 5h credit" / `week_reset_events` notes). MAX would lock attribution
+    # to the pre-credit high-water mark even after Anthropic credits the
+    # week back down, overstating Used % on the Projects panel/modal
+    # forever. The "latest row" pattern matches `_select_last_known_snapshot`
+    # (bin/cctally:1162-1168) and the doctor credited-week check
+    # (bin/cctally:8706-8714).
+    #
+    # Portable per-key-latest pattern: read rows ordered by capture-
+    # ascending and let later rows overwrite. The final value per key
+    # is the most-recent snapshot.
+    weekly_pct_by_week: dict[dt.datetime, float] = {}
+    try:
+        cur = conn.execute(
+            "SELECT week_start_date, weekly_percent "
+            "FROM weekly_usage_snapshots "
+            "ORDER BY captured_at_utc ASC, id ASC"
+        )
+        rows = cur.fetchall()
+    except sqlite3.OperationalError:
+        # No weekly_usage_snapshots table — leaves attributed_pct = None
+        # throughout (acceptable per spec §2.7).
+        rows = []
+    for week_date_str, weekly_pct in rows:
+        try:
+            wd = dt.date.fromisoformat(week_date_str)
+        except (TypeError, ValueError):
+            continue
+        # Snap the date to UTC Monday 00:00 (matches the bucketing key).
+        wstart = dt.datetime.combine(
+            wd, dt.time(0, 0, 0), tzinfo=dt.timezone.utc,
+        )
+        # Snap to Monday (snapshot rows that captured a non-Monday week
+        # boundary still align to the same canonical bucket as the entry
+        # walk, since the bucketing is Monday-anchored).
+        wstart = _projects_week_start_monday_utc(wstart)
+        if weekly_pct is not None:
+            weekly_pct_by_week[wstart] = float(weekly_pct)
+
+    # ---- Disambiguate display_keys across the union of projects --------
+    # `_project_disambiguate_labels` expects a list of dicts each with a
+    # `key` field that's a ProjectKey. Sort by bucket_path for stable
+    # indexing.
+    bucket_paths_sorted = sorted(key_by_bucket.keys())
+    disambig_rows = [
+        {"key": key_by_bucket[bp]} for bp in bucket_paths_sorted
+    ]
+    augmented_by_idx = c._project_disambiguate_labels(disambig_rows)
+    display_key_by_bucket: dict[str, str] = {}
+    for idx, bp in enumerate(bucket_paths_sorted):
+        pkey = key_by_bucket[bp]
+        display_key_by_bucket[bp] = augmented_by_idx.get(
+            idx, pkey.display_key,
+        )
+
+    # ---- Determine actual weeks emitted (clamp to history) -------------
+    weeks_with_activity = sorted(
+        ws for ws in {ws for (_bp, ws) in buckets.keys()}
+    )
+    if weeks_with_activity:
+        # Window = inclusive [oldest_active_week, cw_start]. Always emits
+        # cw_start (panel + trend share the same current_week column).
+        oldest = min(weeks_with_activity[0], cw_start)
+        trend_weeks = []
+        w = oldest
+        while w <= cw_start:
+            trend_weeks.append(w)
+            w += dt.timedelta(days=7)
+    else:
+        trend_weeks = [cw_start]
+
+    # ---- current_week.rows ---------------------------------------------
+    cw_rows = []
+    cw_pct = weekly_pct_by_week.get(cw_start)
+    cw_total_cost = total_cost_by_week.get(cw_start, 0.0)
+    for bp in bucket_paths_sorted:
+        b = buckets.get((bp, cw_start))
+        if b is None:
+            continue
+        if cw_pct is not None and cw_total_cost > 0:
+            attributed = (b["cost_usd"] / cw_total_cost) * cw_pct
+        else:
+            attributed = None
+        cw_rows.append({
+            "key":              display_key_by_bucket[bp],
+            "bucket_path":      bp,
+            # NOTE: NOT rounded — `round(..., 6)` introduces ~1e-6 error
+            # that breaks the R-PROJ1/R-PROJ2 1e-9 reconcile tolerance.
+            # The JSON serializer emits up to 17 significant digits;
+            # network bandwidth is negligible (KB-scale payloads).
+            "cost_usd":         b["cost_usd"],
+            "attributed_pct":   attributed,
+            "sessions_count":   len(b["sessions"]),
+        })
+    # Desc by cost (ties broken by key for byte-stability across runs).
+    cw_rows.sort(key=lambda r: (-r["cost_usd"], r["key"]))
+
+    cw_block = {
+        "week_label":      _projects_week_label(cw_start),
+        "week_start_date": cw_start.date().isoformat(),
+        "week_start_at":   _iso_z(cw_start),
+        "total_cost_usd":  cw_total_cost,
+        "rows":            cw_rows,
+    }
+
+    # ---- trend.weeks[] + trend.projects[] ------------------------------
+    trend_weeks_blocks = []
+    for w in trend_weeks:
+        wpct = weekly_pct_by_week.get(w)
+        trend_weeks_blocks.append({
+            "week_start_date": w.date().isoformat(),
+            "week_label":      _projects_week_label(w),
+            "total_cost_usd":  total_cost_by_week.get(w, 0.0),
+            "total_pct":       wpct,
+        })
+
+    trend_projects = []
+    for bp in bucket_paths_sorted:
+        weekly_cost: list[float] = []
+        weekly_pct_arr: list[float | None] = []
+        sessions_per_week: list[int] = []
+        first_seen_per_week: list[str | None] = []
+        last_seen_per_week: list[str | None] = []
+        for w in trend_weeks:
+            b = buckets.get((bp, w))
+            if b is None:
+                weekly_cost.append(0.0)
+                weekly_pct_arr.append(None)
+                sessions_per_week.append(0)
+                first_seen_per_week.append(None)
+                last_seen_per_week.append(None)
+                continue
+            week_total = total_cost_by_week.get(w, 0.0)
+            week_pct = weekly_pct_by_week.get(w)
+            if week_pct is not None and week_total > 0:
+                attributed = (b["cost_usd"] / week_total) * week_pct
+            else:
+                attributed = None
+            weekly_cost.append(b["cost_usd"])
+            weekly_pct_arr.append(attributed)
+            sessions_per_week.append(len(b["sessions"]))
+            first_seen_per_week.append(_iso_z(b["first_seen"]))
+            last_seen_per_week.append(_iso_z(b["last_seen"]))
+        # Skip projects with zero total cost across the entire window
+        # (the bucket-loop only enters projects that have at least one
+        # entry, so this is mainly a safety check).
+        if all(c == 0.0 for c in weekly_cost):
+            continue
+        trend_projects.append({
+            "key":                 display_key_by_bucket[bp],
+            "bucket_path":         bp,
+            "weekly_cost":         weekly_cost,
+            "weekly_pct":          weekly_pct_arr,
+            "sessions_per_week":   sessions_per_week,
+            "first_seen_per_week": first_seen_per_week,
+            "last_seen_per_week":  last_seen_per_week,
+        })
+    # Stable sort: desc by total window cost, ties broken by key.
+    trend_projects.sort(
+        key=lambda p: (-sum(p["weekly_cost"]), p["key"]),
+    )
+
+    trend_block = {
+        "window_weeks": len(trend_weeks),
+        "weeks":        trend_weeks_blocks,
+        "projects":     trend_projects,
+    }
+
+    result = {
+        "current_week": cw_block,
+        "trend":        trend_block,
+    }
+    _PROJECTS_ENV_MEMO["key"] = memo_key
+    _PROJECTS_ENV_MEMO["value"] = result
+    return result
+
+
+def _project_detail_for_window(
+    conn: "sqlite3.Connection",
+    *,
+    project_key: str,
+    weeks_back: int,
+    now_utc: "dt.datetime",
+    current_week: "Any | None" = None,
+    projects_envelope: "dict | None" = None,
+) -> "dict | None":
+    """Build the drill payload for ``GET /api/project/<key>?weeks=N``
+    (spec §5.3).
+
+    Resolves ``project_key`` against the same disambiguated display
+    keys the envelope emits. Returns ``None`` on miss → caller maps to
+    HTTP 404. Top-N sessions by ``last_activity`` desc (cap=5 per spec
+    §5.3); models list is desc by cost. ``window_attributed_pct`` is
+    the across-window sum of ``(project_cost_in_week / week_total) *
+    week_pct`` — ``None`` when no contributing week has a snapshot.
+
+    Identity invariant (CLAUDE.md spec §9.2 R-PROJ3 + Codex F6):
+    ``project_key`` is matched against the DISAMBIGUATED display_key
+    (`foo (repos)` etc.), NOT a substring filter — the CLI
+    ``--project <pattern>`` form does NOT reliably round-trip
+    disambiguated keys. The reconcile harness asserts this by
+    ``bucket_path`` identity, not pattern.
+
+    Performance — two layered optimizations make this O(project-rows-
+    in-window) instead of O(all-rows-in-window):
+
+    1. ``projects_envelope`` (HTTP path passes ``snap.projects_envelope``):
+       reuse the sync thread's already-built envelope for the
+       ``project_key`` → ``bucket_path`` resolution and the trend-pct
+       lookup, instead of rebuilding. On an active dashboard, the
+       per-process memo on ``_build_projects_envelope`` invalidates
+       every time ``session_entries.id`` advances — between the sync
+       tick and the user's click, that's almost always — so the memo
+       saves nothing on the HTTP path. Plumbing the snapshot's
+       envelope through skips ~1-2s of redundant work per drill.
+
+    2. SQL-side bucket filter: resolve ``bucket_path`` → set of
+       ``session_files.path`` once (cheap — ``session_files`` is
+       ~8k rows vs ``session_entries`` 150k+), stage into a TEMP TABLE,
+       and INNER JOIN the entries walk so the engine only touches this
+       project's rows. Eliminates the Python-side
+       ``if pkey.bucket_path != bucket_path: continue`` filter that
+       previously discarded ~99% of rows after paying for parse +
+       resolve + cost-compute on each.
+    """
+    c = _cctally()
+
+    # Resolve the projects envelope: prefer the snapshot-provided one
+    # (sync thread already built it for this tick) over rebuilding
+    # locally. ``None`` keeps the legacy behavior for callers that
+    # don't have a snapshot (tests, the reconcile harness).
+    if projects_envelope is not None:
+        env = projects_envelope
+    else:
+        env = _build_projects_envelope(
+            conn,
+            now_utc=now_utc,
+            current_week=current_week,
+            weeks_back=weeks_back,
+        )
+
+    # Resolve project_key → bucket_path via the envelope's identity map.
+    bucket_path: "str | None" = None
+    matching_trend: "dict | None" = None
+    for tp in env["trend"]["projects"]:
+        if tp["key"] == project_key:
+            bucket_path = tp["bucket_path"]
+            matching_trend = tp
+            break
+    if bucket_path is None:
+        # The project may have shown up in current_week (panel only)
+        # but had 0 cost across the window — fall back to that.
+        for r in env["current_week"]["rows"]:
+            if r["key"] == project_key:
+                bucket_path = r["bucket_path"]
+                break
+    if bucket_path is None:
+        return None
+
+    # ---- Window bounds (Monday-anchored UTC fallback, like the builder) -
+    cw_start = parse_iso_datetime(
+        env["current_week"]["week_start_at"],
+        "projects.current_week.week_start_at",
+    )
+    since_dt = cw_start - dt.timedelta(days=7 * (weeks_back - 1))
+    until_dt = cw_start + dt.timedelta(days=7)
+
+    # ---- Build bucket → source_paths map for SQL-side scoping ----------
+    # Walk session_files (~8k rows) once instead of session_entries
+    # (~150k+ rows). _resolve_project_key gets called at most ~distinct-
+    # project_paths times (~127 on real DBs) instead of once per entry,
+    # and most of that is hashmap lookups via resolver_cache.
+    resolver_cache: dict = {}
+    _resolve_project_key_fn = c._resolve_project_key
+    unknown_bucket = bucket_path == "(unknown)"
+    bucket_source_paths: set[str] = set()
+    sf_cur = conn.execute(
+        "SELECT path, project_path FROM session_files"
+    )
+    for sf_path, sf_project_path in sf_cur:
+        pkey = _resolve_project_key_fn(
+            sf_project_path, "git-root", resolver_cache,
+        )
+        if pkey.bucket_path == bucket_path:
+            bucket_source_paths.add(sf_path)
+    if unknown_bucket:
+        # session_entries rows whose source_path has no session_files
+        # row at all LEFT-JOIN to NULL project_path → resolve to
+        # ``(unknown)`` via _resolve_project_key. session_files-only
+        # scan misses those.
+        #
+        # This explicit orphan scan is the drill-down's mirror of the
+        # envelope's implicit orphan path: the envelope walk in
+        # `_build_projects_envelope` (see the `_projects_iter_session_entries`
+        # loop above) routes the same orphan source_paths through the
+        # LEFT-JOIN→NULL→`_resolve_project_key(None, ...)` chain into the
+        # ``(unknown)`` bucket. Both surfaces converge on the same
+        # source_path set so envelope row counts/costs and drill row
+        # counts/costs reconcile.
+        orphan_cur = conn.execute(
+            "SELECT DISTINCT e.source_path "
+            "FROM session_entries e "
+            "LEFT JOIN session_files sf ON sf.path = e.source_path "
+            "WHERE sf.path IS NULL AND e.source_path IS NOT NULL"
+        )
+        for (sp,) in orphan_cur:
+            bucket_source_paths.add(sp)
+
+    if not bucket_source_paths:
+        # Project visible in envelope but no contributing source_paths
+        # for this conn (rare edge — e.g. an envelope built off a
+        # different conn). Emit an empty drill so the 404 path stays
+        # reserved for "key unknown."
+        return {
+            "key":                    project_key,
+            "bucket_path":            bucket_path,
+            "window_weeks":           weeks_back,
+            "window_cost_usd":        0.0,
+            "window_attributed_pct":  None,
+            "models":                 [],
+            "sessions":               [],
+            "models_total":           0,
+            "sessions_total":         0,
+        }
+
+    # Stage bucket source_paths into a TEMP TABLE so the entries walk
+    # can INNER JOIN an indexed lookup. ``IN (?, ?, ?, ...)`` would
+    # collide with SQLite's parameter cap (~999 bindings) on heavy
+    # multi-cwd projects. DROP-then-CREATE makes the function
+    # re-entrant on a reused conn (the HTTP handler closes the conn
+    # per request, but tests share conns across calls).
+    conn.execute("DROP TABLE IF EXISTS temp._drill_paths")
+    conn.execute(
+        "CREATE TEMP TABLE _drill_paths(path TEXT PRIMARY KEY)"
+    )
+    conn.executemany(
+        "INSERT OR IGNORE INTO _drill_paths(path) VALUES (?)",
+        [(p,) for p in bucket_source_paths],
+    )
+
+    since_iso = since_dt.astimezone(dt.timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    until_iso = until_dt.astimezone(dt.timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+
+    # ---- Walk session_entries (project-scoped) once -------------------
+    # INNER JOIN to _drill_paths drops every row whose source_path
+    # doesn't belong to this bucket. The Python-side filter that
+    # previously discarded ~99% of rows post-resolve is gone.
+    entries_cur = conn.execute(
+        "SELECT e.id, e.timestamp_utc, e.model, e.input_tokens, "
+        "       e.output_tokens, e.cache_create_tokens, "
+        "       e.cache_read_tokens, e.cost_usd_raw, e.source_path, "
+        "       sf.session_id, sf.project_path "
+        "FROM session_entries e "
+        "INNER JOIN _drill_paths dp ON dp.path = e.source_path "
+        "LEFT JOIN session_files sf ON sf.path = e.source_path "
+        "WHERE e.timestamp_utc >= ? AND e.timestamp_utc <= ? "
+        "ORDER BY e.timestamp_utc ASC, e.id ASC",
+        (since_iso, until_iso),
+    )
+
+    # Per-model rollup: {model -> {cost_usd, sessions, in, out, cache_*}}
+    models: dict[str, dict] = {}
+    # Per-session rollup: {session_id -> {cost_usd, last_activity,
+    #                                     started_at, primary_model}}
+    sessions: dict[str, dict] = {}
+    # Aggregate scalars across the window.
+    window_cost = 0.0
+    window_input_t = 0
+    window_output_t = 0
+
+    for row in entries_cur:
+        (entry_id, ts_iso, model, input_tok, output_tok,
+         cache_create, cache_read, cost_raw, source_path,
+         session_id, project_path) = row
+        if model == "<synthetic>":
+            continue
+        # No need to call _resolve_project_key here — the INNER JOIN
+        # on _drill_paths already restricted the result set to entries
+        # whose source_path belongs to this bucket.
+        ts = parse_iso_datetime(ts_iso, "session_entries.timestamp_utc")
+        entry_cost = _calculate_entry_cost(
+            model,
+            {
+                "input_tokens": input_tok or 0,
+                "output_tokens": output_tok or 0,
+                "cache_creation_input_tokens": cache_create or 0,
+                "cache_read_input_tokens": cache_read or 0,
+            },
+            mode="auto",
+            cost_usd=cost_raw,
+        )
+        window_cost += entry_cost
+        window_input_t += int(input_tok or 0)
+        window_output_t += int(output_tok or 0)
+
+        # Per-model rollup.
+        m = models.get(model)
+        if m is None:
+            m = {
+                "model":          model,
+                "cost_usd":       0.0,
+                "sessions":       set(),
+                "tokens_input":   0,
+                "tokens_output":  0,
+            }
+            models[model] = m
+        m["cost_usd"] += entry_cost
+        m["tokens_input"] += int(input_tok or 0)
+        m["tokens_output"] += int(output_tok or 0)
+        if session_id:
+            m["sessions"].add(session_id)
+        elif source_path:
+            m["sessions"].add(source_path)
+
+        # Per-session rollup.
+        sid = session_id or source_path
+        if not sid:
+            continue
+        s = sessions.get(sid)
+        if s is None:
+            s = {
+                "session_id":       sid,
+                "started_at":       ts,
+                "last_activity_at": ts,
+                "primary_model":    model,
+                "cost_usd":         0.0,
+            }
+            sessions[sid] = s
+        else:
+            if ts < s["started_at"]:
+                s["started_at"] = ts
+            if ts > s["last_activity_at"]:
+                s["last_activity_at"] = ts
+        s["cost_usd"] += entry_cost
+
+    # Models desc by cost (ties broken by model name for stability).
+    models_list = sorted(
+        models.values(),
+        key=lambda m: (-m["cost_usd"], m["model"]),
+    )
+    models_out = []
+    for m in models_list:
+        models_out.append({
+            "model":          m["model"],
+            "cost_usd":       m["cost_usd"],
+            "sessions_count": len(m["sessions"]),
+            "tokens_input":   m["tokens_input"],
+            "tokens_output":  m["tokens_output"],
+        })
+
+    # Sessions: top-5 by last_activity_at desc (per spec §5.3).
+    sessions_sorted = sorted(
+        sessions.values(),
+        key=lambda s: s["last_activity_at"],
+        reverse=True,
+    )
+    sessions_out = []
+    for s in sessions_sorted[:5]:
+        sessions_out.append({
+            "session_id":       s["session_id"],
+            "started_at":       _iso_z(s["started_at"]),
+            "last_activity_at": _iso_z(s["last_activity_at"]),
+            "primary_model":    s["primary_model"],
+            "cost_usd":         s["cost_usd"],
+        })
+
+    # window_attributed_pct: prefer the trend projection (already
+    # computed correctly). Sum across weeks within the requested
+    # ``weeks_back`` window; None when all contributing weeks lack
+    # snapshots.
+    #
+    # IMPORTANT: when the HTTP path reuses ``snap.projects_envelope``
+    # (built by the sync thread with ``weeks_back=12``),
+    # ``matching_trend["weekly_pct"]`` is always a 12-element array even
+    # when the drill is requested with ``?weeks=1|4|8``. Slice to the
+    # trailing ``weeks_back`` entries — same pattern as
+    # ``snapshot_to_share_envelope`` at line 1629 — so the answer doesn't
+    # depend on whether the envelope was rebuilt or reused.
+    win_pct: "float | None" = None
+    if matching_trend is not None:
+        weekly_pct_arr = matching_trend.get("weekly_pct") or []
+        n = len(weekly_pct_arr)
+        take = min(weeks_back, n) if n > 0 else 0
+        sliced = weekly_pct_arr[-take:] if take > 0 else []
+        wp = [p for p in sliced if p is not None]
+        if wp:
+            win_pct = sum(wp)
+
+    # Best-effort cleanup of the per-call TEMP TABLE so a reused conn
+    # doesn't carry path state into the next drill (tests share conns;
+    # production HTTP closes the conn so this is a no-op there).
+    try:
+        conn.execute("DROP TABLE IF EXISTS temp._drill_paths")
+    except sqlite3.Error:
+        pass
+
+    return {
+        "key":                    project_key,
+        "bucket_path":            bucket_path,
+        "window_weeks":           weeks_back,
+        "window_cost_usd":        window_cost,
+        "window_attributed_pct":  win_pct,
+        "models":                 models_out,
+        "sessions":               sessions_out,
+        "models_total":           len(models_out),
+        "sessions_total":         len(sessions),
+    }
+
+
+# Test-surface impl. The HTTP handler `_handle_get_project_detail`
+# delegates here so unit tests can exercise the path parser + dispatch
+# logic without spinning up a real server. ``handler`` is anything that
+# exposes ``self.path`` (the URL path + query), ``send_response``,
+# ``send_header``, ``end_headers``, ``send_error``, and ``wfile.write``
+# — that's the BaseHTTPRequestHandler surface plus the
+# ``test_dashboard_project_endpoint._FakeHandler`` stand-in.
+def _handle_get_project_detail_impl(handler, *,
+                                    conn: "sqlite3.Connection") -> None:
+    """Shared impl for ``GET /api/project/<key>?weeks=N``.
+
+    Parses the percent-decoded key + the ``weeks`` query param,
+    validates ``weeks ∈ {1, 4, 8, 12}``, then delegates to
+    ``_project_detail_for_window``. 400 on missing/invalid weeks,
+    404 on unknown key, 200 with the detail JSON otherwise.
+    """
+    import urllib.parse as _urlparse
+    raw_path = handler.path
+    path_only, sep, query_str = raw_path.partition("?")
+    # Strip the route prefix; what remains is the percent-encoded key.
+    raw_key = path_only[len("/api/project/"):]
+    project_key = _urlparse.unquote(raw_key)
+    # Parse `weeks` from the query string.
+    query = _urlparse.parse_qs(query_str)
+    weeks_vals = query.get("weeks", [None])
+    weeks_raw = weeks_vals[0] if weeks_vals else None
+    try:
+        weeks = int(weeks_raw) if weeks_raw is not None else None
+    except (TypeError, ValueError):
+        weeks = None
+    if weeks not in {1, 4, 8, 12}:
+        body = json.dumps({"error": "invalid weeks param"}).encode("utf-8")
+        handler.send_response(400)
+        handler.send_header("Content-Type", "application/json; charset=utf-8")
+        handler.send_header("Content-Length", str(len(body)))
+        handler.end_headers()
+        handler.wfile.write(body)
+        return
+
+    # ``now_utc`` should mirror the current snapshot's generated_at so
+    # the endpoint stays consistent with the panel rows the user just
+    # clicked through. Pull it from the snapshot when available;
+    # otherwise fall back to _command_as_of (CCTALLY_AS_OF honored).
+    snap = None
+    try:
+        snap_ref = getattr(handler, "snapshot_ref", None)
+        if snap_ref is not None:
+            snap = snap_ref.get()
+    except Exception:
+        snap = None
+    if snap is not None and getattr(snap, "generated_at", None) is not None:
+        now_utc = snap.generated_at
+    else:
+        now_utc = _command_as_of()
+    current_week = getattr(snap, "current_week", None) if snap else None
+    # Reuse the sync-thread-built envelope when available. The per-process
+    # memo invalidates on every session_entries.id advance, so on an
+    # active dashboard the drill would otherwise rebuild the envelope
+    # from scratch on each click (~1-2s wasted). Plumbing it through
+    # skips that work; tests don't set ``projects_envelope`` on the
+    # fake snapshot and fall back to the legacy build path.
+    projects_envelope = getattr(snap, "projects_envelope", None) if snap else None
+
+    try:
+        detail = _project_detail_for_window(
+            conn,
+            project_key=project_key,
+            weeks_back=weeks,
+            now_utc=now_utc,
+            current_week=current_week,
+            projects_envelope=projects_envelope,
+        )
+    except Exception as exc:
+        handler.log_error("/api/project failed: %r", exc)
+        body = json.dumps(
+            {"error": "project detail failed"}
+        ).encode("utf-8")
+        handler.send_response(500)
+        handler.send_header("Content-Type", "application/json; charset=utf-8")
+        handler.send_header("Content-Length", str(len(body)))
+        handler.end_headers()
+        handler.wfile.write(body)
+        return
+    if detail is None:
+        body = json.dumps(
+            {"error": "project not found", "key": project_key},
+        ).encode("utf-8")
+        handler.send_response(404)
+        handler.send_header("Content-Type", "application/json; charset=utf-8")
+        handler.send_header("Content-Length", str(len(body)))
+        handler.end_headers()
+        handler.wfile.write(body)
+        return
+    body = json.dumps(detail, ensure_ascii=False).encode("utf-8")
+    handler.send_response(200)
+    handler.send_header("Content-Type", "application/json; charset=utf-8")
+    handler.send_header("Content-Length", str(len(body)))
+    handler.send_header("Cache-Control", "no-cache")
+    handler.end_headers()
+    handler.wfile.write(body)
+
+
 def _empty_dashboard_snapshot() -> "DataSnapshot":
     """A minimal DataSnapshot used at startup before the first sync
     completes. All panels render placeholders; the sync thread replaces
@@ -3188,12 +4216,26 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                     "duration_min": int(round(s.duration_minutes)) if s.duration_minutes else 0,
                     "model":        s.model_primary,
                     "project":      s.project_label,
+                    # Projects-panel cross-nav identity (spec §4.1).
+                    # Disambiguated display_key matching the projects
+                    # envelope's `current_week.rows[].key`; ``None`` when
+                    # the projects envelope sub-build failed, the row's
+                    # project_path is missing, or the lookup didn't
+                    # resolve (the React cell falls back to plain text).
+                    "project_key":  getattr(s, "project_key", None),
                     "cost_usd":     round(s.cost_usd, 4) if s.cost_usd is not None else None,
                 }
                 for s in snap.sessions
             ],
         },
 
+        # Projects panel + modal envelope block (spec §5.2).
+        # Populated on the sync thread; the serializer reads it back
+        # unchanged so it stays a pure renderer (no DB I/O). ``None``
+        # on first tick before sync completes; the client renders the
+        # panel-empty state in that case.
+        "projects":         getattr(snap, "projects_envelope", None),
+
         # threshold-actions T5: see prelude above for rationale.
         "alerts":           alerts_array,
         "alerts_settings":  alerts_settings,
@@ -3361,6 +4403,8 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._serve_api_events()
         elif path.startswith("/api/session/"):
             self._handle_get_session_detail(path)
+        elif path.startswith("/api/project/"):
+            self._handle_get_project_detail()
         elif path.startswith("/api/block/"):
             self._handle_get_block_detail(path)
         elif path == "/api/update/status":
@@ -4870,6 +5914,57 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         self.end_headers()
         self.wfile.write(body)
 
+    def _handle_get_project_detail(self) -> None:
+        """Return ProjectDetail JSON for ``GET /api/project/<key>?weeks=N``
+        (spec §5.3 / §6.5).
+
+        Opens the stats DB and ATTACHes cache.db so the shared builder
+        sees both schemas off one conn (same contract the sync thread
+        uses). Loopback bind + Origin parity is the entire auth
+        surface — no CSRF needed for GETs.
+        """
+        try:
+            conn = open_db()
+        except Exception as exc:
+            self.log_error("/api/project open_db failed: %r", exc)
+            self.send_error(500, "project detail failed")
+            return
+        try:
+            try:
+                c = _cctally()
+                conn.execute(
+                    "ATTACH DATABASE ? AS cache_db",
+                    (str(c.CACHE_DB_PATH),),
+                )
+                conn.execute(
+                    "CREATE TEMP VIEW IF NOT EXISTS session_entries AS "
+                    "SELECT * FROM cache_db.session_entries"
+                )
+                conn.execute(
+                    "CREATE TEMP VIEW IF NOT EXISTS session_files AS "
+                    "SELECT * FROM cache_db.session_files"
+                )
+            except Exception as exc:
+                # ATTACH/CREATE failure → fall back to the stats conn
+                # alone; the builder will see no session_entries and
+                # return None on key match. We still want to 500 here
+                # because the dashboard contract is "should have both".
+                self.log_error("/api/project ATTACH failed: %r", exc)
+                self.send_error(500, "project detail failed")
+                return
+            _handle_get_project_detail_impl(self, conn=conn)
+        finally:
+            try:
+                conn.execute("DROP VIEW IF EXISTS session_entries")
+                conn.execute("DROP VIEW IF EXISTS session_files")
+            except Exception:
+                pass
+            try:
+                conn.execute("DETACH DATABASE cache_db")
+            except Exception:
+                pass
+            conn.close()
+
     def _handle_get_block_detail(self, path: str) -> None:
         """Return BlockDetail JSON for the block whose start_time equals
         the URL-encoded ISO-8601 UTC datetime in the path tail.