cctally 1.27.1 → 1.29.0

package/bin/_cctally_dashboard.py

@@ -12,8 +12,13 @@ exposure:
   ``--host`` / ``dashboard.bind`` config / ``--tz`` overrides; binds
   the ``ThreadingHTTPServer``; spins up the snapshot sync thread, the
   update-check thread, and the SSE hub; opens a browser when
-  ``--open`` is set; handles ``SIGINT`` / ``SIGTERM`` for clean
-  shutdown.
+  ``--open`` is set; blocks on ``_dashboard_wait_for_signal`` for
+  ``SIGINT`` / ``SIGTERM`` (lost-wakeup-proof per #154) then runs
+  clean shutdown.
+- ``_dashboard_wait_for_signal`` — main-thread shutdown wait built on
+  ``signal.set_wakeup_fd`` + ``select`` so a single SIGINT/SIGTERM
+  always tears the server down, immune to the ``threading.Event.wait()``
+  lost-wakeup race (#154).
 - ``DashboardHTTPHandler`` — the stdlib ``BaseHTTPRequestHandler``
   subclass that serves the static React bundle plus the entire
   ``/api/*`` surface (``data``, ``events``, ``sync``, ``refresh``,
@@ -286,7 +291,7 @@ from _lib_subscription_weeks import _compute_subscription_weeks
 from _lib_blocks import _group_entries_into_blocks
 from _cctally_config import save_config, _load_config_unlocked
 from _cctally_db import _render_migration_error_banner
-from _cctally_cache import get_entries
+from _cctally_cache import get_entries, open_cache_db
 
 
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
@@ -347,6 +352,12 @@ def _build_alert_payload_project_budget(*args, **kwargs):
     )
 
 
+def _build_alert_payload_codex_budget(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_codex_budget(
+        *args, **kwargs
+    )
+
+
 def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
@@ -4178,41 +4189,85 @@ def _envelope_rows_five_hour(conn, descriptor, limit, severity_for) -> list[dict
     return out
 
 
-def _envelope_rows_budget(conn, descriptor, limit, severity_for) -> list[dict]:
-    # Third axis (issue #19): equiv-$ budget threshold crossings. Budget
-    # alerts are keyed by the effective (post-reset) week_start_at + the
-    # integer threshold; the envelope id mirrors the dispatch payload's
-    # ``budget:<week_start_at>:<threshold>`` shape
-    # (``_build_alert_payload_budget``). No ``reset_event_id`` segment —
-    # a mid-week reset re-anchors ``week_start_at`` so the new window
-    # naturally gets fresh rows under ``UNIQUE(week_start_at, threshold)``.
+def _envelope_rows_budget_family(conn, descriptor, limit, severity_for) -> list[dict]:
+    # Unified vendor-tagged budget axis (#143). ONE mapper backs BOTH the
+    # ``budget`` (``vendor='claude'``, issue #19) and ``codex_budget``
+    # (``vendor='codex'``, calendar-period-codex-budgets spec §6) axes —
+    # ``descriptor.vendor`` drives the ``WHERE vendor=?`` row filter + the
+    # ``COALESCE(period, <vendor-default-noun>)`` default, ``descriptor.id`` the
+    # envelope id prefix, ``descriptor.milestone_table`` (now ``budget_milestones``
+    # for both) the source table.
+    #
+    # Budget alerts are keyed by ``period_start_at`` (the resolved period-window
+    # start instant — a subscription-week start for claude OR a calendar
+    # period-start for codex) + the write-once ``period`` discriminator (#137) +
+    # the integer threshold. No ``reset_event_id`` segment: a mid-week reset
+    # (claude) or a period rollover (codex) re-anchors ``period_start_at`` so the
+    # new window naturally gets fresh rows under
+    # ``UNIQUE(vendor, period_start_at, period, threshold)``.
+    #
+    # All numbers + the ``period`` noun are read FROM THE ROW (snapshotted at
+    # crossing), never live config that may have changed since (the Codex P0-4
+    # lesson; Symptom 1 fix) — a user who fires alerts then switches
+    # ``budget.period`` keeps the historical row's noun. ``COALESCE(period, …)``
+    # renders a pre-011 NULL-sentinel row with the vendor-default noun and keeps
+    # the ``id`` non-``None``; the id's ``period`` segment gives a calendar-week ↔
+    # calendar-month coinciding-instant collision (now distinct coexisting rows)
+    # distinct React keys.
+    #
+    # Byte-stable identity: the envelope id ==
+    # ``f"{descriptor.id}:{period_start_at}:{period}:{threshold}"`` matches the
+    # pre-#143 ``budget:…`` / ``codex_budget:…`` strings exactly (same instant
+    # value, renamed key column). The per-vendor context dict KEY ORDER matches
+    # the pre-#143 envelopes verbatim: the claude/``budget`` axis still emits BOTH
+    # the legacy ``week_start_at`` AND ``period_start_at`` (same instant value) so
+    # no existing TS consumer of ``context.week_start_at`` breaks; the
+    # codex/``codex_budget`` axis emits ``period_start_at`` only.
+    vendor = descriptor.vendor
+    default_noun = "subscription-week" if vendor == "claude" else "calendar-month"
     rows = conn.execute(
         f"""
-        SELECT week_start_at, threshold, crossed_at_utc, alerted_at,
+        SELECT period_start_at,
+               COALESCE(period, ?) AS period,
+               threshold, crossed_at_utc, alerted_at,
                budget_usd, spent_usd, consumption_pct
         FROM {descriptor.milestone_table}
-        WHERE alerted_at IS NOT NULL
+        WHERE vendor = ? AND alerted_at IS NOT NULL
         ORDER BY alerted_at DESC
         LIMIT ?
         """,
-        (limit,),
+        (default_noun, vendor, limit),
     ).fetchall()
     out: list[dict] = []
     for r in rows:
         threshold = int(r["threshold"])
+        if vendor == "claude":
+            ctx = {  # key order byte-stable with the pre-#143 budget envelope
+                "week_start_at":   r["period_start_at"],
+                "period":          r["period"],
+                "period_start_at": r["period_start_at"],
+                "budget_usd":      float(r["budget_usd"]),
+                "spent_usd":       float(r["spent_usd"]),
+                "consumption_pct": float(r["consumption_pct"]),
+            }
+        else:
+            ctx = {  # key order byte-stable with the pre-#143 codex_budget envelope
+                "period":          r["period"],
+                "period_start_at": r["period_start_at"],
+                "budget_usd":      float(r["budget_usd"]),
+                "spent_usd":       float(r["spent_usd"]),
+                "consumption_pct": float(r["consumption_pct"]),
+            }
         out.append({
-            "id":         f"budget:{r['week_start_at']}:{threshold}",
+            "id": (
+                f"{descriptor.id}:{r['period_start_at']}:{r['period']}:{threshold}"
+            ),
             "axis":       descriptor.id,
             "threshold":  threshold,
             "severity":   severity_for(threshold),
             "crossed_at": r["crossed_at_utc"],
             "alerted_at": r["alerted_at"],
-            "context": {
-                "week_start_at":   r["week_start_at"],
-                "budget_usd":      float(r["budget_usd"]),
-                "spent_usd":       float(r["spent_usd"]),
-                "consumption_pct": float(r["consumption_pct"]),
-            },
+            "context":    ctx,
         })
     return out
 
@@ -4221,16 +4276,23 @@ def _envelope_rows_projected(conn, descriptor, limit, severity_for) -> list[dict
     # Fourth axis (issue #121): projected-pace threshold crossings. Like
     # budget, projected alerts re-anchor ``week_start_at`` on a mid-week
     # reset, so there is NO ``reset_event_id`` segment — the new window gets
-    # fresh rows under ``UNIQUE(week_start_at, metric, threshold)``. The
-    # ``metric`` discriminator (``weekly_pct`` | ``budget_usd``) drives the
-    # frontend's metric-aware context renderer; ``denominator`` +
-    # ``projected_value`` are rendered FROM THE ROW (the values snapshotted at
-    # crossing), never live config that may have changed since (Codex P0-4).
-    # The envelope id mirrors the dispatch payload's
-    # ``projected:<week_start_at>:<metric>:<threshold>`` shape.
+    # fresh rows under ``UNIQUE(week_start_at, period, metric, threshold)``. The
+    # ``metric`` discriminator (``weekly_pct`` | ``budget_usd`` |
+    # ``codex_budget_usd``) drives the frontend's metric-aware context renderer;
+    # ``denominator`` + ``projected_value`` are rendered FROM THE ROW (the values
+    # snapshotted at crossing), never live config that may have changed since
+    # (Codex P0-4). The envelope id mirrors the dispatch payload's
+    # ``projected:<week_start_at>:<period>:<metric>:<threshold>`` shape. The
+    # write-once ``period`` discriminator (#137) carries no symptom-1 label here
+    # — projected's ``context`` is metric-driven, never a live-config period
+    # noun — so ``COALESCE(period, 'subscription-week')`` is purely for a stable
+    # non-``None`` id segment on a pre-011 NULL-sentinel row (the calendar-week ↔
+    # calendar-month within-metric collision otherwise shares a React key).
     rows = conn.execute(
         f"""
-        SELECT week_start_at, metric, threshold, projected_value,
+        SELECT week_start_at,
+               COALESCE(period, 'subscription-week') AS period,
+               metric, threshold, projected_value,
                denominator, crossed_at_utc, alerted_at
         FROM {descriptor.milestone_table}
         WHERE alerted_at IS NOT NULL
@@ -4244,7 +4306,10 @@ def _envelope_rows_projected(conn, descriptor, limit, severity_for) -> list[dict
         threshold = int(r["threshold"])
         metric = str(r["metric"])
         out.append({
-            "id":         f"projected:{r['week_start_at']}:{metric}:{threshold}",
+            "id": (
+                f"projected:{r['week_start_at']}:{r['period']}"
+                f":{metric}:{threshold}"
+            ),
             "axis":       descriptor.id,
             "metric":     metric,
             "threshold":  threshold,
@@ -4323,12 +4388,17 @@ def _envelope_rows_project_budget(conn, descriptor, limit, severity_for) -> list
 
 # Keyed by ``AlertAxisDescriptor.id`` — the registry decides which axes run,
 # in what order; this table supplies the bespoke heterogeneous row-mapper.
+# ``budget`` (vendor='claude') and ``codex_budget`` (vendor='codex') share the
+# one ``_envelope_rows_budget_family`` mapper (#143) — it reads
+# ``descriptor.vendor`` for the row filter + default noun and ``descriptor.id``
+# for the envelope id prefix, so the two axes stay distinct on the wire.
 _ENVELOPE_AXIS_MAPPERS = {
     "weekly": _envelope_rows_weekly,
     "five_hour": _envelope_rows_five_hour,
-    "budget": _envelope_rows_budget,
+    "budget": _envelope_rows_budget_family,
     "projected": _envelope_rows_projected,
     "project_budget": _envelope_rows_project_budget,
+    "codex_budget": _envelope_rows_budget_family,
 }
 
 
@@ -4339,20 +4409,25 @@ def _build_alerts_envelope_array(
     """Return the ``alerts`` array for the SSE snapshot envelope.
 
     Union of ``percent_milestones``, ``five_hour_milestones``,
-    ``budget_milestones``, ``projected_milestones``, and
-    ``project_budget_milestones`` rows with ``alerted_at IS NOT NULL``,
-    ordered newest-first by ``alerted_at``, capped at ``limit`` (default 100).
-    Single source of truth for both the dashboard panel (slices to 10
-    client-side) and the modal (renders all 100). Forward-only semantics: only
-    rows the alert-dispatch path stamped get included; pre-deploy crossings
-    stay NULL and are intentionally invisible (spec §4.3).
-
-    All five axes share the same envelope schema; the ``axis`` field
+    ``budget_milestones`` (vendor-tagged — backs BOTH the ``budget`` and
+    ``codex_budget`` axes since #143), ``projected_milestones``, and
+    ``project_budget_milestones`` rows with
+    ``alerted_at IS NOT NULL``, ordered newest-first by ``alerted_at``, capped at
+    ``limit`` (default 100). Single source of truth for both the dashboard panel
+    (slices to 10 client-side) and the modal (renders all 100). Forward-only
+    semantics: only rows the alert-dispatch path stamped get included; pre-deploy
+    crossings stay NULL and are intentionally invisible (spec §4.3).
+
+    All six axes share the same envelope schema; the ``axis`` field
     (``weekly`` / ``five_hour`` / ``budget`` / ``projected`` /
-    ``project_budget``) discriminates. The ``projected`` axis additionally
-    carries a top-level ``metric`` (``weekly_pct`` | ``budget_usd``) so the
-    frontend can pick its metric-aware context renderer; ``project_budget``
-    carries the project basename + ``$spent of $budget`` in its context.
+    ``project_budget`` / ``codex_budget``) discriminates. The ``projected`` axis
+    additionally carries a top-level ``metric`` (``weekly_pct`` | ``budget_usd``
+    | ``codex_budget_usd``) so the frontend can pick its metric-aware context
+    renderer; ``project_budget``
+    carries the project basename + ``$spent of $budget`` in its context;
+    ``budget`` + ``codex_budget`` carry a ``period`` discriminator
+    (subscription-week / calendar-week / calendar-month) so the frontend renders
+    a period-aware "Month" / "Calendar week" / "Week" label.
 
     Per-axis ``LIMIT`` is applied at the SQL level (each query may yield
     up to ``limit``) and the union is re-sorted + sliced — important for
@@ -4792,6 +4867,15 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # getter's ``project_alerts_enabled`` (default False) — the frontend
         # SettingsOverlay seeds a single on/off toggle from it.
         "project_alerts_enabled": bool(_budget_cfg.get("project_alerts_enabled")),
+        # Codex budget toggle mirrors (#134). The frontend SettingsOverlay
+        # seeds two toggles (alerts + projected) + a disabled-with-hint empty
+        # state from these three flags. ``_budget_cfg["codex"]`` is ``None`` by
+        # default (no Codex budget) → all three default false/absent safely;
+        # the ``_BudgetConfigError`` fallback dict above lacks a ``codex`` key,
+        # so ``.get("codex")`` → ``None`` is likewise safe.
+        "codex_budget_configured":     _budget_cfg.get("codex") is not None,
+        "codex_budget_alerts_enabled": bool((_budget_cfg.get("codex") or {}).get("alerts_enabled")),
+        "codex_projected_enabled":     bool((_budget_cfg.get("codex") or {}).get("projected_enabled")),
         # Alert-dispatch notifier mirror (Phase B). `notifier` is the
         # validated backend selector ("auto"/"command"/etc.). The raw
         # `command_template` is NEVER mirrored — it routinely holds secrets
@@ -5106,6 +5190,34 @@ _DASHBOARD_SYNC_LOCK_TIMEOUT_SECONDS = 2.0
 # Pre-extract location: bin/cctally L17694.
 
 
+def _qs_int(q: dict, key: str, default: int) -> int:
+    """Parse a single query-string int with a fallback.
+
+    ``q`` is a ``urllib.parse.parse_qs`` mapping (list-valued). A missing key,
+    an empty value, or a non-integer spelling all fall back to ``default`` —
+    the kernels clamp bounds, so this only needs to be permissive, not strict.
+    """
+    vals = q.get(key, [None])
+    raw = vals[0] if vals else None
+    try:
+        return int(raw) if raw is not None else default
+    except (TypeError, ValueError):
+        return default
+
+
+def _qs_str(q: dict, key: str, default: str | None) -> str | None:
+    """Parse a single query-string value with a fallback.
+
+    ``q`` is a ``urllib.parse.parse_qs`` mapping (list-valued). A missing key
+    or an empty list falls back to ``default``. The string sibling of
+    ``_qs_int`` — collapses the ``(q.get(key, [default]) or [default])[0]``
+    idiom the conversation handlers hand-respelled (a ``None`` default is fine,
+    so the reader's ``after`` cursor routes through it too).
+    """
+    vals = q.get(key, [default])
+    return vals[0] if vals else default
+
+
 class DashboardHTTPHandler(BaseHTTPRequestHandler):
     """Routes:
         GET /                       → dashboard.html
@@ -5146,6 +5258,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     # path leaves this None and only sees the `config.json` view, which
     # is the Codex H4 finding. Set by cmd_dashboard before serve_forever.
     cctally_host: "str | None" = None
+    # Conversation viewer (Plan 2, spec §5): the resolved
+    # `dashboard.expose_transcripts` opt-in. False = transcript endpoints
+    # are served only over loopback; True = LAN devices reach them at the
+    # bind's IP literal (anti-DNS-rebinding still rejects hostnames). Set by
+    # cmd_dashboard before serve_forever; the per-request gate
+    # (`_require_transcripts_allowed`) ANDs this with the request Host.
+    cctally_expose_transcripts: bool = False
 
     # Silence the default per-request access log — noisy in the parent
     # terminal, and we pipe it through our own logger in cmd_dashboard.
@@ -5218,6 +5337,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._handle_share_history_get()
         elif path == "/api/doctor":
             self._handle_get_doctor()
+        elif path == "/api/conversations":
+            self._handle_get_conversations()
+        elif path == "/api/conversation/search":
+            self._handle_get_conversation_search()
+        elif path.startswith("/api/conversation/"):
+            self._handle_get_conversation_detail(path)
         else:
             self.send_error(404, "not found")
 
@@ -5377,6 +5502,38 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         else:
             self._respond_json(403, {"error": reason})
 
+    @staticmethod
+    def _transcript_gate():
+        """Lazy-load the pure transcript-access gate kernel (Plan 2, §5)."""
+        return sys.modules["cctally"]._load_sibling("_lib_transcript_access")
+
+    def _transcripts_visible_to_request(self) -> bool:
+        """Single source of truth for "may transcripts be served to THIS
+        request?" Composes the bind gate (`transcripts_allowed`) with the
+        per-request Host allowlist (`host_allowed_for_transcripts`,
+        anti-DNS-rebinding). Spec §5.
+
+        `_require_transcripts_allowed` (the GET-route 403 gate) and the
+        `transcriptsEnabled` client signal on BOTH the `/api/data` route
+        (`_serve_api_data`) and the SSE stream (`_serve_api_events`) route
+        through this predicate so they are contractually identical — a future
+        one-line drift can never re-introduce the enabled-then-403 desync.
+        """
+        ta = self._transcript_gate()
+        expose = bool(type(self).cctally_expose_transcripts)
+        return (ta.transcripts_allowed(type(self).cctally_host, expose)
+                and ta.host_allowed_for_transcripts(
+                    self.headers.get("Host", ""), expose))
+
+    def _require_transcripts_allowed(self) -> bool:
+        """True if transcripts may be served to THIS request; else emit 403 and
+        return False. Spec §5.
+        """
+        if not self._transcripts_visible_to_request():
+            self._respond_403("transcripts not exposed")
+            return False
+        return True
+
     def _handle_post_settings(self) -> None:
         """Persist a settings update and trigger an immediate SSE broadcast.
 
@@ -5384,8 +5541,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         "update"?: {"check"?: {"enabled"?: bool, "ttl_hours"?: int}},
         "cache_report"?: {"anomaly_threshold_pp"?: int},
         "budget"?: {"weekly_usd"?: number|null, "alerts_enabled"?: bool,
-        "alert_thresholds"?: int[], "projected_enabled"?: bool}}`` — every
-        top-level key is optional; any subset may be sent together
+        "alert_thresholds"?: int[], "projected_enabled"?: bool,
+        "codex"?: {"alerts_enabled"?: bool, "projected_enabled"?: bool}}}``
+        — every top-level key is optional; any subset may be sent together
         (combined save). Unknown top-level keys are rejected with 400.
 
         Per-block validation:
@@ -5412,6 +5570,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             block and validated via ``_get_budget_config(merged)`` (issue
             #19, projected toggle #121); ``_BudgetConfigError`` → 400.
             Budget is its OWN config block, distinct from ``alerts``.
+            ``budget.codex`` (#134) is a nested partial-merge: only the two
+            toggles (``alerts_enabled`` / ``projected_enabled``) are
+            dashboard-writable — ``amount_usd`` / ``period`` /
+            ``alert_thresholds`` stay CLI-only and are preserved from the
+            persisted block. A non-dict ``budget.codex`` → 400; toggling
+            ``budget.codex.*`` when no Codex budget is configured → 400
+            (fail-closed; amounts are never invented from the dashboard).
 
         Atomic merged write: if all touched blocks validate, the merged
         config is persisted in a single ``save_config`` call inside the
@@ -5755,6 +5920,36 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 ):
                     if leaf in budget_in:
                         merged_budget[leaf] = budget_in[leaf]
+                # Nested partial-merge for the Codex sub-block (#134). Mirrors
+                # the ``update.check`` nested-dict merge below: only the two
+                # alert toggles (``alerts_enabled`` / ``projected_enabled``) are
+                # dashboard-writable — ``amount_usd`` / ``period`` /
+                # ``alert_thresholds`` stay CLI-only (ignored if sent), and the
+                # merge preserves them from the persisted block rather than
+                # replacing the whole ``codex`` dict (the clobber regression).
+                if "codex" in budget_in:
+                    incoming_codex = budget_in["codex"]
+                    if not isinstance(incoming_codex, dict):
+                        self._respond_json(
+                            400, {"error": "budget.codex must be an object"}
+                        )
+                        return
+                    existing_codex = merged_budget.get("codex")
+                    if existing_codex is None:
+                        # Fail closed: the dashboard only TOGGLES an existing
+                        # Codex budget — amounts are CLI-only — so it must never
+                        # invent one. The frontend disables the toggle, this
+                        # backstops a direct POST.
+                        self._respond_json(400, {"error": (
+                            "no Codex budget configured — set one via the CLI "
+                            "first (cctally budget set <amount> --vendor codex)"
+                        )})
+                        return
+                    merged_codex = dict(existing_codex)
+                    for sub in ("alerts_enabled", "projected_enabled"):
+                        if sub in incoming_codex:
+                            merged_codex[sub] = bool(incoming_codex[sub])
+                    merged_budget["codex"] = merged_codex
                 merged["budget"] = merged_budget
                 # Final validation against the merged block.
                 # _BudgetConfigError → 400 (no partial write — save_config
@@ -5855,12 +6050,32 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             touched = (
                 set(budget_in.keys()) if isinstance(budget_in, dict) else set()
             )
-            if touched & {"weekly_usd", "alerts_enabled", "alert_thresholds"}:
+            # ``period`` included (#143 §5.4 fold-in): switching budget.period
+            # via the dashboard while already over a threshold must reconcile
+            # forward-only, exactly like the CLI `config set budget.period` path
+            # (`_cctally_config.py`) — else the next record-usage tick would
+            # instant-popup retroactive alerts under the new period window.
+            if touched & {"weekly_usd", "alerts_enabled", "alert_thresholds", "period"}:
                 _cctally()._reconcile_budget_on_config_write(validated_budget)
             if touched & {"project_alerts_enabled", "alert_thresholds"}:
                 _cctally()._reconcile_project_budget_milestones_on_write(
                     validated_budget
                 )
+            # Codex actual-spend reconcile (#134). Key it on the ``alerts_enabled``
+            # SUB-leaf specifically — NOT ``"codex" in touched``. The helper
+            # (`_reconcile_codex_budget_on_config_write`) is itself gated on
+            # alerts_enabled && amount && thresholds, so a coarse "codex touched"
+            # check would run it whenever alerts is already True — meaning a
+            # ``projected_enabled``-only toggle would latch (silently suppress) a
+            # still-unfired actual-spend crossing. Keying on the sub-leaf means
+            # flipping alerts ON latches already-crossed thresholds (intended),
+            # while toggling projected reconciles nothing (projected stays
+            # live-pace, Q4).
+            codex_in = budget_in.get("codex")
+            if isinstance(codex_in, dict) and "alerts_enabled" in codex_in:
+                _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.
@@ -5959,25 +6174,30 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         axis = body.get("axis", "weekly")
         if axis not in (
             "weekly", "five_hour", "budget", "projected", "project_budget",
+            "codex_budget",
         ):
             self._respond_json(
                 400,
                 {"error": (
                     "axis must be 'weekly', 'five_hour', 'budget', "
-                    f"'projected' or 'project_budget', got {axis!r}"
+                    "'projected', 'project_budget' or 'codex_budget', "
+                    f"got {axis!r}"
                 )},
             )
             return
         # ``metric`` discriminates the projected axis (weekly_pct vs
-        # budget_usd); the other axes ignore it. Validate only when it
-        # matters so a stray metric on a weekly/budget test isn't a 400.
+        # budget_usd vs codex_budget_usd); the other axes ignore it. Validate
+        # only when it matters so a stray metric on a weekly/budget test isn't
+        # a 400.
         metric = body.get("metric", "weekly_pct")
-        if axis == "projected" and metric not in ("weekly_pct", "budget_usd"):
+        if axis == "projected" and metric not in (
+            "weekly_pct", "budget_usd", "codex_budget_usd",
+        ):
             self._respond_json(
                 400,
                 {"error": (
-                    "metric must be 'weekly_pct' or 'budget_usd', "
-                    f"got {metric!r}"
+                    "metric must be 'weekly_pct', 'budget_usd' or "
+                    f"'codex_budget_usd', got {metric!r}"
                 )},
             )
             return
@@ -6031,6 +6251,22 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 spent_usd=26.0,
                 consumption_pct=104.0,
             )
+        elif axis == "codex_budget":
+            # Synthetic Codex budget payload — mirrors the CLI
+            # ``alerts test --axis codex-budget`` branch (NO DB writes,
+            # test/real divergence contract, NO real budget.codex entry
+            # required). A $200 calendar-month budget reads plausibly; spent
+            # scaled to the threshold so the body line reads as the
+            # at-crossing snapshot the dashboard would render (R4).
+            payload = _build_alert_payload_codex_budget(
+                threshold=threshold,
+                crossed_at_utc=now_utc_iso(),
+                period_start_at=dt.date.today().replace(day=1).isoformat(),
+                period="calendar-month",
+                budget_usd=200.0,
+                spent_usd=200.0 * threshold / 100.0,
+                consumption_pct=float(threshold),
+            )
         elif axis == "projected":
             # Synthetic projected-pace payload — mirrors the CLI
             # cmd_alerts_test projected branch (NO DB writes, test/real
@@ -6039,10 +6275,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # value (so the body reads plausibly, e.g. weekly 100% → "~100% of
             # cap", budget 100% → "$300 of $300"). denominator is the
             # at-crossing target the row would carry (Codex P0-4): 100.0 for
-            # weekly_pct, $300 for budget_usd.
+            # weekly_pct, $300 for budget_usd, $200 for codex_budget_usd
+            # (matching the codex_budget axis test-alert budget).
             if metric == "budget_usd":
                 denominator = 300.0
                 projected_value = 300.0 * threshold / 100.0
+            elif metric == "codex_budget_usd":
+                denominator = 200.0
+                projected_value = 200.0 * threshold / 100.0
             else:  # weekly_pct
                 denominator = 100.0
                 projected_value = float(threshold)
@@ -6901,6 +7141,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             display_tz_pref_override=type(self).display_tz_pref_override,
             runtime_bind=type(self).cctally_host,
         )
+        # Conversation viewer (Plan 2, spec §5): inject the client signal
+        # PER-REQUEST and Host-aware — NOT inside snapshot_to_envelope (the
+        # request-independent SSE snapshot has no Host header). Routes through
+        # the SAME predicate as the transcript GET-route gate so a LAN-hostname
+        # request that the transcript GETs would 403 shows
+        # transcriptsEnabled=false, never enabled-then-403 (the pass-2 P2
+        # finding) — one predicate, two consumers, desync impossible.
+        env["transcriptsEnabled"] = self._transcripts_visible_to_request()
         body = json.dumps(env, ensure_ascii=False).encode("utf-8")
         self.send_response(200)
         self.send_header("Content-Type", "application/json; charset=utf-8")
@@ -6990,6 +7238,112 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         self.end_headers()
         self.wfile.write(body)
 
+    @staticmethod
+    def _conversation_query():
+        """Lazy-load the pure conversation query kernel (Plan 2, §3)."""
+        return sys.modules["cctally"]._load_sibling("_lib_conversation_query")
+
+    def _run_conversation_query(self, kernel_call, log_label):
+        """Open cache.db, run ``kernel_call(conn)``, close — with the uniform
+        500 envelopes the three conversation routes share (#151).
+
+        Collapses the triplicated open-cache → try/except/finally → 500
+        scaffold to one site. Returns ``(ok, body)``: ``ok=False`` means a 500
+        has ALREADY been sent and the caller must just ``return``; ``ok=True``
+        carries the kernel result (which may itself be ``None`` — the reader's
+        404 sentinel — so the explicit flag, not ``body is None``, signals
+        failure). An ``open_cache_db`` failure is a ``cache unavailable:`` 500;
+        a kernel exception is logged as ``<log_label> failed: %r`` and returned
+        as a ``{type}: {msg}`` 500 — byte-identical to the inlined handlers.
+        """
+        try:
+            conn = open_cache_db()
+        except (sqlite3.DatabaseError, OSError) as exc:
+            self._respond_json(500, {"error": f"cache unavailable: {exc}"})
+            return False, None
+        try:
+            body = kernel_call(conn)
+        except Exception as exc:  # noqa: BLE001
+            self.log_error("%s failed: %r", log_label, exc)
+            self._respond_json(500, {"error": f"{type(exc).__name__}: {exc}"})
+            return False, None
+        finally:
+            conn.close()
+        return True, body
+
+    def _handle_get_conversations(self) -> None:
+        """``GET /api/conversations`` — the browse rail (spec §3.1).
+
+        Gated first (loopback / Host allowlist). ``sort``/``limit``/``offset``
+        are read from the query string; the kernel clamps bounds. Cache-open
+        failures are 500s, never 5xx-with-stacktrace.
+        """
+        if not self._require_transcripts_allowed():
+            return
+        import urllib.parse as _u
+        q = _u.parse_qs(self.path.partition("?")[2])
+        sort = _qs_str(q, "sort", "recent")
+        limit = _qs_int(q, "limit", 50)
+        offset = _qs_int(q, "offset", 0)
+        ok, body = self._run_conversation_query(
+            lambda conn: self._conversation_query().list_conversations(
+                conn, sort=sort, limit=limit, offset=offset),
+            "/api/conversations")
+        if not ok:
+            return
+        self._respond_json(200, body)
+
+    def _handle_get_conversation_detail(self, path: str) -> None:
+        """``GET /api/conversation/<session-id>`` — the reader (spec §3.2).
+
+        The id is percent-decoded so clients that encode reserved chars
+        round-trip. Unknown id → 404. ``after``/``limit`` page the items.
+        """
+        if not self._require_transcripts_allowed():
+            return
+        import urllib.parse as _u
+        # ``path`` is already query-stripped by ``do_GET`` (``self.path.split("?")``),
+        # so the cursor params (?after=/?limit=) live ONLY on the raw ``self.path``.
+        # Sibling handlers read ``self.path`` directly — the detail route must too,
+        # or every request re-serves the head and pagination is dead.
+        query_str = self.path.partition("?")[2]
+        session_id = _u.unquote(path[len("/api/conversation/"):])
+        if not session_id:
+            self.send_error(404, "conversation not found")
+            return
+        q = _u.parse_qs(query_str)
+        after = _qs_str(q, "after", None)
+        limit = _qs_int(q, "limit", 500)
+        ok, body = self._run_conversation_query(
+            lambda conn: self._conversation_query().get_conversation(
+                conn, session_id, after=after, limit=limit),
+            "/api/conversation")
+        if not ok:
+            return
+        if body is None:
+            self.send_error(404, "conversation not found")
+            return
+        self._respond_json(200, body)
+
+    def _handle_get_conversation_search(self) -> None:
+        """``GET /api/conversation/search?q=...`` — cross-session FTS/LIKE
+        search (spec §3.3). Matched BEFORE the ``<id>`` reader in ``do_GET``.
+        """
+        if not self._require_transcripts_allowed():
+            return
+        import urllib.parse as _u
+        q = _u.parse_qs(self.path.partition("?")[2])
+        query = _qs_str(q, "q", "")
+        limit = _qs_int(q, "limit", 50)
+        offset = _qs_int(q, "offset", 0)
+        ok, body = self._run_conversation_query(
+            lambda conn: self._conversation_query().search_conversations(
+                conn, query, limit=limit, offset=offset),
+            "/api/conversation/search")
+        if not ok:
+            return
+        self._respond_json(200, body)
+
     def _handle_get_project_detail(self) -> None:
         """Return ProjectDetail JSON for ``GET /api/project/<key>?weeks=N``
         (spec §5.3 / §6.5).
@@ -7162,6 +7516,16 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         except OauthUsageConfigError:
             cfg_oauth = dict(sys.modules["cctally"]._OAUTH_USAGE_DEFAULTS)
 
+        # Conversation viewer (Plan 2, spec §5): resolve the transcript gate
+        # ONCE per SSE connection. `_transcripts_visible_to_request()` reads
+        # this client's `Host` header + the class-level expose flag — both
+        # constant for the connection's lifetime, so no per-tick FS/header
+        # reads. The SSE `update` envelope MUST carry `transcriptsEnabled`:
+        # the client replaces the whole snapshot on every tick, so without it
+        # the steady-state UI loses the gate (the ViewSwitcher disappears
+        # ~15s after bootstrap). Mirrors `/api/data`'s per-request injection.
+        transcripts_enabled = self._transcripts_visible_to_request()
+
         q = self.hub.subscribe()
         try:
             while True:
@@ -7181,6 +7545,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     display_tz_pref_override=type(self).display_tz_pref_override,
                     runtime_bind=type(self).cctally_host,
                 )
+                env["transcriptsEnabled"] = transcripts_enabled
                 msg = (
                     "event: update\n"
                     + "data: " + json.dumps(env, ensure_ascii=False) + "\n\n"
@@ -7388,6 +7753,82 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
 # === cmd_dashboard (dashboard subcommand entry point) =====================
 # Pre-extract location: bin/cctally L21478.
 
+def _dashboard_wait_for_signal(
+    signals,
+    *,
+    on_signal=None,
+    timeout=None,
+):
+    """Block the calling (main) thread until one of ``signals`` is delivered.
+
+    The wait is driven by a self-pipe wakeup fd (``signal.set_wakeup_fd``)
+    rather than a ``threading.Event``: CPython's C-level signal trampoline
+    writes the signum to the pipe on EVERY delivery, *before* (and
+    independent of) the Python-level handler running, so the ``select``
+    below unblocks on the very first signal. This eliminates the lost-wakeup
+    that races ``threading.Event.wait()`` — a single SIGTERM that arrives as
+    the main thread enters the wait is dropped ~0.04-0.07% of the time,
+    never waking an Event-based loop, and recovery needs a *second* signal
+    (issue #154; surfaced during #153 triage). A timed-poll
+    (``while not stop.wait(0.5)``) does NOT fix it: on the miss the flag is
+    never set, so it polls forever — the pipe buffer is the fix, not the
+    timeout.
+
+    ``on_signal`` (optional) is invoked from the Python-level handler on each
+    delivery — a belt-and-suspenders secondary signal for callers that still
+    want one; the wakeup does NOT depend on it running. ``timeout`` is
+    ``None`` (block forever) in production; tests pass a finite bound so a
+    regressed mechanism fails loudly instead of hanging.
+
+    Returns ``True`` if woken by a signal, ``False`` if ``timeout`` elapsed.
+    MUST be called from the main thread (``set_wakeup_fd`` / ``signal.signal``
+    both require it). Restores the prior signal dispositions and wakeup fd on
+    return, so it is safe to call repeatedly and inside a test process.
+    """
+    import os
+    import selectors
+    import signal
+
+    prev_handlers = {sig: signal.getsignal(sig) for sig in signals}
+    read_fd, write_fd = os.pipe()
+    os.set_blocking(read_fd, False)
+    os.set_blocking(write_fd, False)
+    # Arm the wakeup fd BEFORE installing the Python handlers: by the time a
+    # handler can fire, the C trampoline already has a pipe to write to, so a
+    # signal racing the setup can't slip through a gap and be lost. (A signal
+    # before this point still hits the prior disposition — pre-existing, not
+    # our shutdown wait.)
+    prev_wakeup_fd = signal.set_wakeup_fd(write_fd)
+
+    def _handler(signum, frame):
+        if on_signal is not None:
+            on_signal()
+
+    sel = selectors.DefaultSelector()
+    sel.register(read_fd, selectors.EVENT_READ)
+    try:
+        for sig in signals:
+            signal.signal(sig, _handler)
+        woke = bool(sel.select(timeout))
+        if woke:
+            # Drain the wakeup byte(s); the pipe is non-blocking so an empty
+            # read raises BlockingIOError rather than blocking.
+            try:
+                os.read(read_fd, 4096)
+            except BlockingIOError:
+                pass
+        return woke
+    finally:
+        # Order matters: restore the wakeup fd before closing write_fd so the
+        # signal machinery never points at a closed descriptor.
+        signal.set_wakeup_fd(prev_wakeup_fd)
+        for sig, handler in prev_handlers.items():
+            signal.signal(sig, handler)
+        sel.close()
+        os.close(read_fd)
+        os.close(write_fd)
+
+
 def cmd_dashboard(args: argparse.Namespace) -> int:
     """Launch the live web dashboard."""
     import signal as _signal
@@ -7515,6 +7956,14 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     # in the doctor SSE block + /api/doctor reflects the actual --host
     # the process is serving, not just the config-only view the CLI sees.
     DashboardHTTPHandler.cctally_host = args.host
+    # Conversation viewer (Plan 2, spec §5): the resolved
+    # `dashboard.expose_transcripts` opt-in. Read off the already-loaded
+    # `config` the same way `dashboard.bind` is resolved above (the
+    # `_config_known_value` shim surfaces the boolean default of False for
+    # an absent or hand-edited-junk value).
+    DashboardHTTPHandler.cctally_expose_transcripts = bool(
+        _config_known_value(config, "dashboard.expose_transcripts")
+    )
     DashboardHTTPHandler.run_sync_now = staticmethod(
         lambda: _run_sync_now(skip_sync=args.no_sync)
     )
@@ -7619,14 +8068,14 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
                 file=sys.stderr,
             )
 
-    stop = threading.Event()
-    def _handler(signum, frame):
-        stop.set()
-    _signal.signal(_signal.SIGINT, _handler)
-    _signal.signal(_signal.SIGTERM, _handler)
-
+    # Block the main thread until SIGINT/SIGTERM. The wait is driven by a
+    # self-pipe wakeup fd (signal.set_wakeup_fd) rather than a
+    # threading.Event, so a single signal unblocks it unconditionally — the
+    # C-level signal trampoline writes to the pipe before (and independent
+    # of) any Python-level handler running, so the wakeup can't be lost to
+    # the Event.wait() entry race (#154). timeout=None → block forever.
     try:
-        stop.wait()
+        _dashboard_wait_for_signal((_signal.SIGINT, _signal.SIGTERM))
     finally:
         if sync_thread is not None:
             sync_thread.stop()