cctally 1.28.0 → 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``,
@@ -4184,58 +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
-    # write-once ``period`` discriminator + the integer threshold; the envelope
-    # id mirrors the dispatch payload's
-    # ``budget:<week_start_at>:<period>:<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, period, 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.
     #
-    # Period generalization (calendar-period-codex-budgets, spec §5/§6): the
-    # ``week_start_at`` key column carries either a subscription-week instant
-    # OR a calendar period-start instant (back-compat misnomer, like
-    # ``weekly_usd``); the ``period`` discriminator (#137) tells them apart.
-    # ``period`` is read FROM THE ROW (snapshotted at crossing), never live
-    # config that may have changed since (the Codex P0-4 lesson) — so a user who
-    # fires subscription-week alerts then switches ``budget.period`` keeps the
-    # historical row's noun (Symptom 1 fix). ``COALESCE(period,
-    # 'subscription-week')`` renders a pre-011 NULL-sentinel row with the
-    # vendor-default noun and keeps the ``id`` non-``None``.
+    # 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,
-               COALESCE(period, 'subscription-week') AS period,
+        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']}:{r['period']}:{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"],
-                "period":          r["period"],
-                "period_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
 
@@ -4354,75 +4386,19 @@ def _envelope_rows_project_budget(conn, descriptor, limit, severity_for) -> list
     return out
 
 
-def _envelope_rows_codex_budget(conn, descriptor, limit, severity_for) -> list[dict]:
-    # Sixth axis (calendar-period-codex-budgets, spec §6): per-vendor Codex
-    # equiv-actual-$ budget threshold crossings over a CALENDAR period
-    # (calendar-week / calendar-month — Codex has no Anthropic subscription
-    # week). Keyed on ``period_start_at`` (the resolved period-window start
-    # instant, stored as the ``isoformat(timespec="seconds")`` ``+00:00`` offset
-    # form, NOT a ``Z`` suffix) + the integer threshold; the envelope id mirrors
-    # the dispatch payload's ``codex_budget:<period_start_at>:<threshold>`` shape
-    # (``_build_alert_payload_codex_budget``). NO ``reset_event_id`` segment —
-    # rolling to the next period yields a fresh ``period_start_at`` so the new
-    # window naturally gets fresh rows under ``UNIQUE(period_start_at,
-    # threshold)``. ``budget_usd`` / ``spent_usd`` / ``consumption_pct`` are
-    # rendered FROM THE ROW (snapshotted at crossing), never live config that may
-    # have changed since (the Codex P0-4 lesson). The ``period`` discriminator is
-    # the write-once ``period`` discriminator (#137) is read FROM THE ROW
-    # (snapshotted at crossing) — mirroring how the dispatched payload sourced it
-    # from config-at-fire-time — never live ``budget.codex.period`` that may have
-    # changed since (the Codex P0-4 lesson; Symptom 1 fix). ``COALESCE(period,
-    # 'calendar-month')`` renders a pre-011 NULL-sentinel row with the
-    # vendor-default civil-period noun (Codex has no subscription week) and keeps
-    # the ``id`` non-``None``. The id gains the ``period`` segment so a
-    # calendar-week ↔ calendar-month coinciding-instant collision (now distinct
-    # coexisting rows under ``UNIQUE(period_start_at, period, threshold)``) gets
-    # distinct React keys.
-    rows = conn.execute(
-        f"""
-        SELECT period_start_at,
-               COALESCE(period, 'calendar-month') AS period,
-               threshold, crossed_at_utc, alerted_at,
-               budget_usd, spent_usd, consumption_pct
-        FROM {descriptor.milestone_table}
-        WHERE alerted_at IS NOT NULL
-        ORDER BY alerted_at DESC
-        LIMIT ?
-        """,
-        (limit,),
-    ).fetchall()
-    out: list[dict] = []
-    for r in rows:
-        threshold = int(r["threshold"])
-        out.append({
-            "id": (
-                f"codex_budget:{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": {
-                "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"]),
-            },
-        })
-    return out
-
-
 # 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_codex_budget,
+    "codex_budget": _envelope_rows_budget_family,
 }
 
 
@@ -4433,8 +4409,9 @@ 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``,
-    ``project_budget_milestones``, and ``codex_budget_milestones`` rows with
+    ``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
@@ -5228,6 +5205,19 @@ def _qs_int(q: dict, key: str, default: int) -> int:
         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
@@ -5523,9 +5513,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         per-request Host allowlist (`host_allowed_for_transcripts`,
         anti-DNS-rebinding). Spec §5.
 
-        Both `_require_transcripts_allowed` (the GET-route 403 gate) and the
-        `transcriptsEnabled` client signal in `_serve_api_data` route through
-        this predicate so the two are contractually identical — a future
+        `_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()
@@ -6059,7 +6050,12 @@ 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(
@@ -7247,6 +7243,34 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         """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).
 
@@ -7258,23 +7282,15 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         import urllib.parse as _u
         q = _u.parse_qs(self.path.partition("?")[2])
-        sort = (q.get("sort", ["recent"]) or ["recent"])[0]
+        sort = _qs_str(q, "sort", "recent")
         limit = _qs_int(q, "limit", 50)
         offset = _qs_int(q, "offset", 0)
-        try:
-            conn = open_cache_db()
-        except (sqlite3.DatabaseError, OSError) as exc:
-            self._respond_json(500, {"error": f"cache unavailable: {exc}"})
+        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
-        try:
-            body = self._conversation_query().list_conversations(
-                conn, sort=sort, limit=limit, offset=offset)
-        except Exception as exc:  # noqa: BLE001
-            self.log_error("/api/conversations failed: %r", exc)
-            self._respond_json(500, {"error": f"{type(exc).__name__}: {exc}"})
-            return
-        finally:
-            conn.close()
         self._respond_json(200, body)
 
     def _handle_get_conversation_detail(self, path: str) -> None:
@@ -7296,22 +7312,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self.send_error(404, "conversation not found")
             return
         q = _u.parse_qs(query_str)
-        after = (q.get("after", [None]) or [None])[0]
+        after = _qs_str(q, "after", None)
         limit = _qs_int(q, "limit", 500)
-        try:
-            conn = open_cache_db()
-        except (sqlite3.DatabaseError, OSError) as exc:
-            self._respond_json(500, {"error": f"cache unavailable: {exc}"})
-            return
-        try:
-            body = self._conversation_query().get_conversation(
-                conn, session_id, after=after, limit=limit)
-        except Exception as exc:  # noqa: BLE001
-            self.log_error("/api/conversation failed: %r", exc)
-            self._respond_json(500, {"error": f"{type(exc).__name__}: {exc}"})
+        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
-        finally:
-            conn.close()
         if body is None:
             self.send_error(404, "conversation not found")
             return
@@ -7325,23 +7333,15 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         import urllib.parse as _u
         q = _u.parse_qs(self.path.partition("?")[2])
-        query = (q.get("q", [""]) or [""])[0]
+        query = _qs_str(q, "q", "")
         limit = _qs_int(q, "limit", 50)
         offset = _qs_int(q, "offset", 0)
-        try:
-            conn = open_cache_db()
-        except (sqlite3.DatabaseError, OSError) as exc:
-            self._respond_json(500, {"error": f"cache unavailable: {exc}"})
-            return
-        try:
-            body = self._conversation_query().search_conversations(
-                conn, query, limit=limit, offset=offset)
-        except Exception as exc:  # noqa: BLE001
-            self.log_error("/api/conversation/search failed: %r", exc)
-            self._respond_json(500, {"error": f"{type(exc).__name__}: {exc}"})
+        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
-        finally:
-            conn.close()
         self._respond_json(200, body)
 
     def _handle_get_project_detail(self) -> None:
@@ -7516,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:
@@ -7535,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"
@@ -7742,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
@@ -7981,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()