cctally 1.77.0 → 1.79.0

package/bin/_cctally_dashboard.py

@@ -356,6 +356,10 @@ from _lib_blocks import _group_entries_into_blocks
 # #279 S2 F3: stdlib-logging chokepoint — server errors reach stderr via
 # the real log_error override below (leaf import, no cycle).
 import _lib_log
+from _lib_dashboard_json import (
+    encode_dashboard_json,
+    encode_dashboard_json_bytes,
+)
 from _cctally_config import save_config, _load_config_unlocked
 from _cctally_db import _render_migration_error_banner
 from _cctally_cache import (
@@ -800,12 +804,20 @@ def _codex_partial_source_detail(snapshot, row: Mapping, *, resource: str,
     return detail
 
 
-def _source_safe_claude_session_detail(detail, *, key: str) -> dict[str, Any]:
+def _source_safe_claude_session_detail(
+    detail, *, key: str, project_key: str | None = None, label: str | None = None,
+) -> dict[str, Any]:
     """Adapt the existing Claude session detail builder to S4's safe route."""
     payload = _session_detail_to_envelope(detail)
     return {
         "detail_kind": "claude_session",
         "key": key,
+        "label": label or "Claude session",
+        "project_label": payload["project_label"],
+        "project_key": (
+            dashboard_resource_key("project", "claude", project_key)
+            if project_key else None
+        ),
         "started_utc": payload["started_utc"],
         "last_activity_utc": payload["last_activity_utc"],
         "duration_min": payload["duration_min"],
@@ -817,20 +829,32 @@ def _source_safe_claude_session_detail(detail, *, key: str) -> dict[str, Any]:
         "cache_hit_pct": payload["cache_hit_pct"],
         "cost_per_model": payload["cost_per_model"],
         "cost_total_usd": payload["cost_total_usd"],
+        "privacy_note": (
+            "Native session identity and source files are withheld to preserve "
+            "opaque identity. Cache rebuild history belongs to the private "
+            "conversation-detail surface and is intentionally not exposed by "
+            "this qualified accounting route."
+        ),
     }
 
 
-def _source_safe_claude_project_detail(detail: Mapping, *, key: str) -> dict[str, Any]:
+def _source_safe_claude_project_detail(
+    detail: Mapping, *, key: str, label: str,
+) -> dict[str, Any]:
     """Drop legacy raw bucket/session identifiers from a Claude project drill."""
     return {
         "detail_kind": "claude_project",
         "key": key,
+        "label": label,
         "window_weeks": detail.get("window_weeks"),
         "window_cost_usd": detail.get("window_cost_usd"),
         "window_attributed_pct": detail.get("window_attributed_pct"),
         "models": detail.get("models", []),
         "sessions": [
             {
+                "key": dashboard_resource_key(
+                    "session", "claude", item.get("session_id"),
+                ),
                 "started_at": item.get("started_at"),
                 "last_activity_at": item.get("last_activity_at"),
                 "primary_model": item.get("primary_model"),
@@ -859,13 +883,73 @@ def _source_safe_claude_block_detail(detail: Mapping, *, key: str) -> dict[str,
     }
 
 
-def _claude_session_id_for_source_key(snapshot, key: str) -> str | None:
+def _claude_session_row_for_source_key(snapshot, key: str):
     for row in getattr(snapshot, "sessions", ()) or ():
         session_id = getattr(row, "session_id", None)
         if isinstance(session_id, str) and session_id and (
             dashboard_resource_key("session", "claude", session_id) == key
         ):
-            return session_id
+            return row
+    return None
+
+
+def _claude_session_id_for_source_key(snapshot, key: str) -> str | None:
+    """Resolve a qualified session key without exposing its native identity.
+
+    The published source bundle contains the bounded dashboard rows.  A project
+    drill can legitimately link to a recent session outside that panel slice,
+    so fall back to the compact ``session_files`` identity index and compare
+    opaque hashes.  This never scans transcript entries or returns a raw ID to
+    the client.
+    """
+    row = _claude_session_row_for_source_key(snapshot, key)
+    if row is not None:
+        return getattr(row, "session_id", None)
+    try:
+        conn = open_cache_db()
+    except (sqlite3.DatabaseError, OSError):
+        return None
+    try:
+        rows = conn.execute(
+            "SELECT DISTINCT session_id FROM session_files "
+            "WHERE session_id IS NOT NULL AND session_id <> '' "
+            "ORDER BY session_id"
+        )
+        for (session_id,) in rows:
+            if (
+                isinstance(session_id, str)
+                and dashboard_resource_key(
+                    "session", "claude", session_id,
+                ) == key
+            ):
+                return session_id
+    except sqlite3.Error:
+        return None
+    finally:
+        conn.close()
+    return None
+
+
+def _claude_project_key_for_path(snapshot, project_path: object) -> str | None:
+    """Map one private project path back to its public display key."""
+    if not isinstance(project_path, str) or not project_path:
+        return None
+    env = getattr(snapshot, "projects_envelope", None)
+    if not isinstance(env, Mapping):
+        return None
+    candidates: list[object] = []
+    current = env.get("current_week")
+    if isinstance(current, Mapping):
+        candidates.extend(current.get("rows") or ())
+    trend = env.get("trend")
+    if isinstance(trend, Mapping):
+        candidates.extend(trend.get("projects") or ())
+    for row in candidates:
+        if not isinstance(row, Mapping) or row.get("bucket_path") != project_path:
+            continue
+        project_key = row.get("key")
+        if isinstance(project_key, str) and project_key:
+            return project_key
     return None
 
 
@@ -906,19 +990,39 @@ def _claude_block_start_for_source_key(snapshot, key: str) -> dt.datetime | None
     return None
 
 
-def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[str, Any]:
+def _build_claude_source_detail(
+    snapshot, *, resource: str, key: str, row: Mapping,
+    window_weeks: int = 4,
+) -> dict[str, Any]:
     """Map a bounded legacy row to its existing, cache-only detail builder."""
     now_utc = getattr(snapshot, "generated_at", None) or _command_as_of()
     if resource == "session":
-        session_id = _claude_session_id_for_source_key(snapshot, key)
-        if session_id is None:
+        session_row = _claude_session_row_for_source_key(snapshot, key)
+        session_id = (
+            getattr(session_row, "session_id", None)
+            if session_row is not None
+            else _claude_session_id_for_source_key(snapshot, key)
+        )
+        if not isinstance(session_id, str) or not session_id:
             raise SourceResourceNotFound()
         detail = sys.modules["cctally"]._tui_build_session_detail(
             session_id, now_utc=now_utc,
         )
         if detail is None:
             raise SourceResourceNotFound()
-        return _source_safe_claude_session_detail(detail, key=key)
+        project_key = (
+            getattr(session_row, "project_key", None)
+            if session_row is not None
+            else _claude_project_key_for_path(
+                snapshot, getattr(detail, "project_path", None),
+            )
+        )
+        return _source_safe_claude_session_detail(
+            detail,
+            key=key,
+            project_key=project_key,
+            label=str(row.get("title") or row.get("label") or "Claude session"),
+        )
 
     if resource == "project":
         project_key = _claude_project_key_for_source_key(snapshot, key)
@@ -932,7 +1036,7 @@ def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[st
             detail = _project_detail_for_window(
                 conn,
                 project_key=project_key,
-                weeks_back=1,
+                weeks_back=window_weeks,
                 now_utc=now_utc,
                 current_week=getattr(snapshot, "current_week", None),
                 projects_envelope=getattr(snapshot, "projects_envelope", None),
@@ -947,7 +1051,9 @@ def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[st
             conn.close()
         if detail is None:
             raise SourceResourceNotFound()
-        return _source_safe_claude_project_detail(detail, key=key)
+        return _source_safe_claude_project_detail(
+            detail, key=key, label=project_key,
+        )
 
     start_at = _claude_block_start_for_source_key(snapshot, key)
     if start_at is None:
@@ -984,7 +1090,7 @@ def _build_claude_source_detail(snapshot, *, resource: str, key: str) -> dict[st
 
 
 def build_source_detail(*, snapshot, source: str, resource: str,
-                        key: str) -> dict[str, Any]:
+                        key: str, window_weeks: int = 4) -> dict[str, Any]:
     """Resolve one qualified opaque key to a provider-native read-only detail.
 
     The frozen published bundle is the first bounded key index.  Claude then
@@ -992,9 +1098,24 @@ def build_source_detail(*, snapshot, source: str, resource: str,
     the native S1-S3 adapter detail without a Claude fallback or a rollout
     parse.  Every branch preserves the generic handler errors above it.
     """
-    row = source_detail_lookup(snapshot.source_bundle, source, resource, key)
+    try:
+        row = source_detail_lookup(snapshot.source_bundle, source, resource, key)
+    except SourceResourceNotFound:
+        # A Claude project drill can expose a recent session outside the
+        # dashboard panel's bounded published slice.  The provider adapter
+        # resolves that opaque key against session_files below; all other
+        # resources retain the strict frozen-bundle membership gate.
+        if source != "claude" or resource != "session":
+            raise
+        row = {}
     if source == "claude":
-        return _build_claude_source_detail(snapshot, resource=resource, key=key)
+        return _build_claude_source_detail(
+            snapshot,
+            resource=resource,
+            key=key,
+            row=row,
+            window_weeks=window_weeks,
+        )
     try:
         detail = _build_codex_source_detail(snapshot, resource=resource, key=key)
         if resource == "session":
@@ -3934,7 +4055,7 @@ def _handle_get_project_detail_impl(handler, *,
     except (TypeError, ValueError):
         weeks = None
     if weeks not in {1, 4, 8, 12}:
-        body = json.dumps({"error": "invalid weeks param"}).encode("utf-8")
+        body = encode_dashboard_json_bytes({"error": "invalid weeks param"})
         handler.send_response(400)
         handler.send_header("Content-Type", "application/json; charset=utf-8")
         handler.send_header("Content-Length", str(len(body)))
@@ -3977,9 +4098,9 @@ def _handle_get_project_detail_impl(handler, *,
         )
     except Exception as exc:
         handler.log_error("/api/project failed: %r", exc)
-        body = json.dumps(
+        body = encode_dashboard_json_bytes(
             {"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)))
@@ -3987,16 +4108,16 @@ def _handle_get_project_detail_impl(handler, *,
         handler.wfile.write(body)
         return
     if detail is None:
-        body = json.dumps(
+        body = encode_dashboard_json_bytes(
             {"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")
+    body = encode_dashboard_json_bytes(detail, ensure_ascii=False)
     handler.send_response(200)
     handler.send_header("Content-Type", "application/json; charset=utf-8")
     handler.send_header("Content-Length", str(len(body)))
@@ -4314,6 +4435,7 @@ _GET_ROUTES = (
     ("prefix", "/api/session/", "_handle_get_session_detail", None, True),
     ("prefix", "/api/project/", "_handle_get_project_detail", None, False),
     ("prefix", "/api/block/", "_handle_get_block_detail", None, True),
+    ("prefix", "/api/milestones/", "_handle_get_milestones_week", None, True),
     ("exact", "/api/update/status", "_handle_get_update_status", None, False),
     ("prefix", "/api/update/stream/", "_handle_get_update_stream", None, True),
     ("exact", "/api/share/templates", "_handle_share_templates_get", None, False),
@@ -4456,7 +4578,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         _respond_json plus an explicit Allow header.
         """
         if self.path.split("?", 1)[0] == "/api/settings":
-            encoded = json.dumps({"error": "method not allowed"}).encode("utf-8")
+            encoded = encode_dashboard_json_bytes(
+                {"error": "method not allowed"}
+            )
             self.send_response(405)
             self.send_header("Allow", "POST")
             self.send_header("Content-Type", "application/json")
@@ -5105,6 +5229,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         # compatible. `enabled` must be a JSON bool; `ttl_hours` an int
         # (bools rejected — see _validate_update_check_ttl_hours_value).
         update_check_validated: "dict | None" = None
+        update_channel_validated: "str | None" = None
         if "update" in payload:
             update_in = payload["update"]
             if not isinstance(update_in, dict):
@@ -5113,13 +5238,28 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 )
                 return
             for inner in update_in.keys():
-                if inner != "check":
+                if inner not in ("check", "channel"):
                     self._respond_json(
                         400,
                         {"error": f"unknown update settings key: {inner}",
                          "field": f"update.{inner}"},
                     )
                     return
+            # Release channel opt-in (beta-channel, spec 2026-07-21 §3). Enum
+            # {stable,beta}; 400 on invalid. Mirrors the config-key validator.
+            if "channel" in update_in:
+                try:
+                    update_channel_validated = (
+                        _cctally()._validate_update_channel_value(
+                            update_in["channel"]
+                        )
+                    )
+                except ValueError as exc:
+                    self._respond_json(
+                        400,
+                        {"error": str(exc), "field": "update.channel"},
+                    )
+                    return
             check_in = update_in.get("check", {})
             if not isinstance(check_in, dict):
                 self._respond_json(
@@ -5275,7 +5415,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     self._respond_json(400, {"error": str(exc)})
                     return
 
-            if update_check_validated is not None:
+            if (
+                update_check_validated is not None
+                or update_channel_validated is not None
+            ):
                 # Same hand-edited-junk guard as alerts: a non-dict
                 # `update` or `update.check` block in config.json should
                 # surface as a recoverable 400, not a 500.
@@ -5289,18 +5432,22 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     )
                     return
                 merged_update = dict(existing_update or {})
-                existing_check = merged_update.get("check")
-                if existing_check is not None and not isinstance(
-                    existing_check, dict
-                ):
-                    self._respond_json(
-                        400, {"error": "update.check must be an object",
-                              "field": "update.check"}
-                    )
-                    return
-                merged_check = dict(existing_check or {})
-                merged_check.update(update_check_validated)
-                merged_update["check"] = merged_check
+                if update_check_validated is not None:
+                    existing_check = merged_update.get("check")
+                    if existing_check is not None and not isinstance(
+                        existing_check, dict
+                    ):
+                        self._respond_json(
+                            400, {"error": "update.check must be an object",
+                                  "field": "update.check"}
+                        )
+                        return
+                    merged_check = dict(existing_check or {})
+                    merged_check.update(update_check_validated)
+                    merged_update["check"] = merged_check
+                if update_channel_validated is not None:
+                    # Partial-PUT: preserve the sibling `update.check` block.
+                    merged_update["channel"] = update_channel_validated
                 merged["update"] = merged_update
 
             if cache_report_validated is not None:
@@ -5408,11 +5555,17 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 _cctally()._reconcile_codex_budget_on_config_write(
                     validated_budget
                 )
-        if update_check_validated is not None:
-            # Echo the full merged check block (cooked defaults included)
-            # so the SettingsOverlay can repaint without a follow-up GET.
-            out["update"] = {
-                "check": {
+        if (
+            update_check_validated is not None
+            or update_channel_validated is not None
+        ):
+            # Echo the touched update leaves (cooked defaults included) so the
+            # SettingsOverlay can repaint without a follow-up GET. The channel
+            # echo uses the read-surface name `configured_channel` (spec §3
+            # naming), mirrored from the merged config via the single resolver.
+            out_update: dict = {}
+            if update_check_validated is not None:
+                out_update["check"] = {
                     "enabled": _config_known_value(
                         merged, "update.check.enabled"
                     ),
@@ -5420,7 +5573,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                         merged, "update.check.ttl_hours"
                     ),
                 }
-            }
+            if update_channel_validated is not None:
+                out_update["configured_channel"] = (
+                    _cctally().resolve_update_channel(merged)
+                )
+            out["update"] = out_update
         if cache_report_validated is not None:
             # Echo the full cooked block (resolved defaults included) so
             # the dashboard composer can repaint without a follow-up GET
@@ -5689,7 +5846,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     # ---- helpers ----
 
     def _respond_json(self, status: int, body: dict) -> None:
-        encoded = json.dumps(body).encode("utf-8")
+        encoded = encode_dashboard_json_bytes(body)
         self.send_response(status)
         self.send_header("Content-Type", "application/json")
         self.send_header("Content-Length", str(len(encoded)))
@@ -5760,7 +5917,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # transcriptsEnabled=false, never enabled-then-403 (the pass-2 P2
             # finding) — one predicate, two consumers, desync impossible.
             env["transcriptsEnabled"] = visible
-            body = json.dumps(env, ensure_ascii=False).encode("utf-8")
+            body = encode_dashboard_json_bytes(env, ensure_ascii=False)
             self.send_response(200)
             self.send_header("Content-Type", "application/json; charset=utf-8")
             self.send_header("Content-Length", str(len(body)))
@@ -5795,9 +5952,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 runtime_bind=type(self).cctally_host,
             )
             report = _ld.run_checks(state)
-            body = json.dumps(
+            body = encode_dashboard_json_bytes(
                 _ld.serialize_json(report), ensure_ascii=False,
-            ).encode("utf-8")
+            )
             self.send_response(200)
             self.send_header("Content-Type", "application/json; charset=utf-8")
             self.send_header("Content-Length", str(len(body)))
@@ -5845,9 +6002,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         if detail is None:
             self.send_error(404, "session not found")
             return
-        body = json.dumps(
+        body = encode_dashboard_json_bytes(
             _session_detail_to_envelope(detail), ensure_ascii=False
-        ).encode("utf-8")
+        )
         self.send_response(200)
         self.send_header("Content-Type", "application/json; charset=utf-8")
         self.send_header("Content-Length", str(len(body)))
@@ -5894,14 +6051,28 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 "error": "source capability unavailable",
             })
             return
-        try:
-            snap = self.snapshot_ref.get()
-            detail = build_source_detail(
-                snapshot=snap,
-                source=source,
-                resource=resource,
-                key=key,
+        detail_kwargs = {
+            "source": source,
+            "resource": resource,
+            "key": key,
+        }
+        if resource == "project":
+            query = _urlparse.parse_qs(
+                _urlparse.urlsplit(self.path).query,
+                keep_blank_values=True,
             )
+            raw_weeks = query.get("weeks")
+            if raw_weeks is not None:
+                if len(raw_weeks) != 1 or raw_weeks[0] not in {"1", "4", "8", "12"}:
+                    self._respond_json(400, {
+                        "code": "source_capability_unavailable",
+                        "error": "source capability unavailable",
+                    })
+                    return
+                detail_kwargs["window_weeks"] = int(raw_weeks[0])
+        try:
+            detail_kwargs["snapshot"] = self.snapshot_ref.get()
+            detail = build_source_detail(**detail_kwargs)
         except SourceResourceNotFound:
             self._respond_json(404, {
                 "code": "source_resource_not_found",
@@ -6049,7 +6220,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         try:
             start_at = parse_iso_datetime(decoded, "start_at")
         except ValueError:
-            body = json.dumps({"error": "invalid start_at"}).encode("utf-8")
+            body = encode_dashboard_json_bytes({"error": "invalid start_at"})
             self.send_response(400)
             self.send_header("Content-Type", "application/json; charset=utf-8")
             self.send_header("Content-Length", str(len(body)))
@@ -6097,7 +6268,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 None,
             )
             if target is None:
-                body = json.dumps({"error": "block not found"}).encode("utf-8")
+                body = encode_dashboard_json_bytes({"error": "block not found"})
                 self.send_response(404)
                 self.send_header("Content-Type", "application/json; charset=utf-8")
                 self.send_header("Content-Length", str(len(body)))
@@ -6127,7 +6298,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self.log_error("/api/block failed: %r", exc)
             self.send_error(500, "block detail failed")
             return
-        body = json.dumps(detail, ensure_ascii=False).encode("utf-8")
+        body = encode_dashboard_json_bytes(detail, ensure_ascii=False)
         self.send_response(200)
         self.send_header("Content-Type", "application/json; charset=utf-8")
         self.send_header("Content-Length", str(len(body)))
@@ -6135,6 +6306,117 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         self.end_headers()
         self.wfile.write(body)
 
+    def _send_milestones_json(self, status: int, body: dict) -> None:
+        payload = encode_dashboard_json_bytes(body, ensure_ascii=False)
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _handle_get_milestones_week(self, path: str) -> None:
+        """GET /api/milestones/<source>/week/<key> — one week's/cycle's
+        complete milestone-history payload (spec §2, hero-modal history).
+
+        Dedicated route (deliberately NOT the /api/source/ family, whose
+        not-found semantics are scoped to the current frozen bundle). Wire is
+        snake_case via ``encode_dashboard_json_bytes`` (the dashboard
+        convention — NOT the CLI camelCase envelope). Read-only, per-request
+        connections, no sync/migration writes from the assembly; the multi-read
+        assembly runs inside one transaction per DB. 400 malformed key/source;
+        404 ``{code: "unknown_key", reason}`` for keys that don't resolve.
+        """
+        import re as _re
+        import types as _types
+        import urllib.parse as _urlparse
+        from _cctally_cache import open_cache_db
+
+        tail = path[len("/api/milestones/"):]
+        parts = tail.split("/week/", 1)
+        if len(parts) != 2 or not parts[1]:
+            self._send_milestones_json(400, {"error": "invalid path"})
+            return
+        source, raw_key = parts[0], parts[1]
+        if source not in ("claude", "codex"):
+            self._send_milestones_json(400, {"error": "invalid source"})
+            return
+        key = _urlparse.unquote(raw_key)
+        c = sys.modules["cctally"]
+        try:
+            if source == "claude":
+                # Claude key is a week_start_date (YYYY-MM-DD).
+                if not _re.fullmatch(r"\d{4}-\d{2}-\d{2}", key):
+                    self._send_milestones_json(400, {"error": "invalid week key"})
+                    return
+                conn = open_db()
+                try:
+                    conn.execute("BEGIN")
+                    detail = c.build_claude_week_detail(conn, key)
+                    conn.commit()
+                finally:
+                    conn.close()
+                if detail is None:
+                    self._send_milestones_json(404, {
+                        "error": "unknown week", "code": "unknown_key",
+                        "reason": "unknown",
+                    })
+                    return
+                self._send_milestones_json(200, {**detail, "source": "claude", "key": key})
+                return
+
+            # Codex: opaque server-issued cycle key. Resolve across all codex
+            # roots (keys are unique per cycle, so a client-supplied index key
+            # matches its exact cycle without needing the hero-cycle identity —
+            # this also keeps a just-closed former-current cycle fetchable when
+            # the live hero cycle is momentarily unavailable, spec §2).
+            from _cctally_dashboard_sources import resolve_dashboard_source_semantics
+            speed = resolve_dashboard_source_semantics(
+                load_config(), display_tz_name="UTC",
+            ).speed
+            now_utc = _command_as_of()
+            stats_conn = open_db()
+            cache_conn = open_cache_db()
+            try:
+                # Stable read across BOTH DBs for a single response (spec §2):
+                # the cache conn supplies the physical cost correlation, so it
+                # gets the same BEGIN/commit envelope as the stats conn.
+                stats_conn.execute("BEGIN")
+                cache_conn.execute("BEGIN")
+                roots = tuple(sorted({
+                    str(r[0]) for r in stats_conn.execute(
+                        "SELECT DISTINCT source_root_key FROM quota_window_blocks "
+                        "WHERE source='codex'"
+                    )
+                }))
+                identity = _types.SimpleNamespace(source_root_keys=roots, resets_at=None)
+                result = c.build_codex_cycle_detail(
+                    stats_conn, cache_conn, identity=identity, key=key,
+                    speed=speed, now_utc=now_utc,
+                )
+                stats_conn.commit()
+                cache_conn.commit()
+            finally:
+                stats_conn.close()
+                cache_conn.close()
+            if isinstance(result, tuple):
+                _none, reason = result
+                self._send_milestones_json(404, {
+                    "error": "unknown cycle", "code": "unknown_key",
+                    "reason": reason,
+                })
+                return
+            if result is None:
+                self._send_milestones_json(404, {
+                    "error": "unknown cycle", "code": "unknown_key",
+                    "reason": "unknown",
+                })
+                return
+            self._send_milestones_json(200, {**result, "source": "codex", "key": key})
+        except Exception as exc:  # noqa: BLE001
+            self.log_error("/api/milestones failed: %r", exc)
+            self.send_error(500, "milestones detail failed")
+
     def _serve_api_events(self) -> None:
         import queue as _queue
         self.send_response(200)
@@ -6189,7 +6471,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 env["transcriptsEnabled"] = transcripts_enabled
                 msg = (
                     "event: update\n"
-                    + "data: " + json.dumps(env, ensure_ascii=False) + "\n\n"
+                    + "data: "
+                    + encode_dashboard_json(env, ensure_ascii=False)
+                    + "\n\n"
                 )
                 self.wfile.write(msg.encode("utf-8"))
                 self.wfile.flush()
@@ -6357,9 +6641,19 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             _w.status() if _w is not None
             else {"current_run_id": None}
         )
+        # Beta-channel (spec 2026-07-21 §3): carry the configured release
+        # channel (from config, not cached state) so the badge/modal keep the
+        # `(beta)` marker + exact-version command after an execvp refresh, when
+        # the client polls /api/update/status instead of the SSE envelope.
+        try:
+            _c = _cctally()
+            configured_channel = _c.resolve_update_channel(_c.load_config())
+        except Exception:
+            configured_channel = "stable"
         body = {
             "state": state,
             "suppress": suppress,
+            "configured_channel": configured_channel,
             **worker_status,
         }
         self._respond_json(200, body)
@@ -6387,7 +6681,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         try:
             for ev in worker.stream(run_id):
                 ev_type = ev.get("type", "message")
-                ev_data = json.dumps(
+                ev_data = encode_dashboard_json(
                     {k: v for k, v in ev.items() if k != "type"},
                     ensure_ascii=False,
                 )