cctally 1.109.0 → 1.111.0

package/bin/_cctally_dashboard.py

@@ -278,6 +278,7 @@ import secrets
 import shutil
 import signal as _signal
 import socket
+import select
 import sqlite3
 import sys
 import threading
@@ -297,7 +298,7 @@ from _lib_retained_size import retained_size_bytes
 
 
 class _QuietThreadingHTTPServer(ThreadingHTTPServer):
-    """`ThreadingHTTPServer` that swallows client-disconnect tracebacks.
+    """Bounded HTTP threads with quiet client-disconnect handling.
 
     A backgrounded/closed/reloaded dashboard tab hangs up mid-response, so the
     per-request thread's socket write raises one of the "peer went away"
@@ -313,6 +314,111 @@ class _QuietThreadingHTTPServer(ThreadingHTTPServer):
     """
 
     daemon_threads = True
+    request_queue_size = 256
+    max_request_threads = 96
+    _reject_workers_count = 4
+    _reject_queue_size = 256
+    _busy_body = b'{"error":"server busy"}'
+    _busy_response = (
+        b"HTTP/1.1 503 Service Unavailable\r\n"
+        b"Content-Type: application/json\r\n"
+        b"Cache-Control: no-store\r\n"
+        b"Connection: close\r\n"
+        + f"Content-Length: {len(_busy_body)}\r\n\r\n".encode("ascii")
+        + _busy_body
+    )
+
+    def __init__(self, *args, **kwargs):
+        self._request_slots = threading.BoundedSemaphore(
+            self.max_request_threads)
+        self._reject_queue: queue.Queue[socket.socket] = queue.Queue(
+            maxsize=self._reject_queue_size)
+        self._reject_stop = threading.Event()
+        self._reject_start_lock = threading.Lock()
+        self._reject_workers: list[threading.Thread] = []
+        super().__init__(*args, **kwargs)
+
+    def _reject_request(self, request: socket.socket) -> None:
+        try:
+            # Read only the bounded request headers so a close with unread
+            # input does not reset a client before it sees the 503. Slow peers
+            # are confined to a fixed reject worker, never the accept loop.
+            request.settimeout(0.25)
+            received = bytearray()
+            while b"\r\n\r\n" not in received and len(received) < 8192:
+                chunk = request.recv(min(8192 - len(received), 4096))
+                if not chunk:
+                    break
+                received.extend(chunk)
+            request.sendall(self._busy_response)
+        except OSError:
+            pass  # A peer that disconnected cannot receive the overload reply.
+        finally:
+            self.shutdown_request(request)
+
+    def _reject_loop(self) -> None:
+        while not self._reject_stop.is_set():
+            try:
+                request = self._reject_queue.get(timeout=0.1)
+            except queue.Empty:
+                continue
+            try:
+                self._reject_request(request)
+            finally:
+                self._reject_queue.task_done()
+
+    def _queue_rejection(self, request: socket.socket) -> None:
+        with self._reject_start_lock:
+            if not self._reject_workers:
+                for index in range(self._reject_workers_count):
+                    worker = threading.Thread(
+                        target=self._reject_loop,
+                        name=f"cctally-http-reject-{index}", daemon=True,
+                    )
+                    worker.start()
+                    self._reject_workers.append(worker)
+        try:
+            self._reject_queue.put_nowait(request)
+        except queue.Full:
+            # This last-resort reply is nonblocking. It keeps the accept loop
+            # responsive even if the bounded reject queue also saturates.
+            try:
+                request.setblocking(False)
+                request.send(self._busy_response)
+            except OSError:
+                pass
+            finally:
+                self.shutdown_request(request)
+
+    def process_request(self, request, client_address):
+        if not self._request_slots.acquire(blocking=False):
+            self._queue_rejection(request)
+            return
+        try:
+            super().process_request(request, client_address)
+        except BaseException:
+            self._request_slots.release()
+            self.shutdown_request(request)
+            raise
+
+    def process_request_thread(self, request, client_address):
+        try:
+            super().process_request_thread(request, client_address)
+        finally:
+            self._request_slots.release()
+
+    def server_close(self):
+        self._reject_stop.set()
+        while True:
+            try:
+                request = self._reject_queue.get_nowait()
+            except queue.Empty:
+                break
+            self.shutdown_request(request)
+            self._reject_queue.task_done()
+        for worker in self._reject_workers:
+            worker.join(timeout=0.5)
+        super().server_close()
 
     def handle_error(self, request, client_address):
         exc = sys.exc_info()[1]
@@ -332,6 +438,30 @@ class _DiagnosisFlight:
     result: Any = None
     error: BaseException | None = None
     callers: int = 0
+    deadline: float = 0.0
+
+
+class _DiagnosisOverloaded(Exception):
+    """The bounded diagnosis admission has no room for another caller."""
+
+
+class _DiagnosisTimedOut(Exception):
+    """A diagnosis did not finish within its flight's deadline."""
+
+
+class _DiagnosisClientGone(Exception):
+    """The requesting peer disconnected while its diagnosis was pending."""
+
+
+def _diagnosis_peer_gone(connection: socket.socket) -> bool:
+    """Check a waiting GET socket without consuming any request bytes."""
+    try:
+        if not select.select([connection], [], [], 0)[0]:
+            return False
+        return not connection.recv(
+            1, socket.MSG_PEEK | getattr(socket, "MSG_DONTWAIT", 0))
+    except (OSError, ValueError):
+        return True
 
 
 def _diagnosis_flight_key(
@@ -360,48 +490,155 @@ class _DiagnosisAdmission:
     never retained, so this adds no stale report cache or periodic work.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, *, max_callers: int = 32, max_per_key: int = 16,
+                 max_keys: int = 8, deadline_seconds: float = 15.0) -> None:
+        if min(max_callers, max_per_key, max_keys) < 1 or deadline_seconds <= 0:
+            raise ValueError("diagnosis admission limits must be positive")
         self._changed = threading.Condition()
         self._admission = threading.BoundedSemaphore(1)
         self._flights: dict[tuple[Any, bool, bool], _DiagnosisFlight] = {}
+        self._callers = 0
+        self._max_callers = max_callers
+        self._max_per_key = max_per_key
+        self._max_keys = max_keys
+        self._deadline_seconds = deadline_seconds
 
-    def run(self, key: tuple[Any, bool, bool], build):
+    def _finish(self, key, flight, *, result=None, error=None) -> None:
+        with self._changed:
+            if flight.done.is_set():
+                return
+            flight.result = result
+            flight.error = error
+            flight.done.set()
+            if self._flights.get(key) is flight:
+                del self._flights[key]
+            self._changed.notify_all()
+
+    def _produce(self, key, flight, build, bounded_build) -> None:
+        remaining = max(0.0, flight.deadline - time.monotonic())
+        acquired = self._admission.acquire(timeout=remaining)
+        if not acquired:
+            self._finish(key, flight, error=_DiagnosisTimedOut())
+            return
+        try:
+            # A queued flight may have expired while a prior producer held the
+            # single process-wide slot. It must never start a late build.
+            if flight.done.is_set() or time.monotonic() >= flight.deadline:
+                self._finish(key, flight, error=_DiagnosisTimedOut())
+                return
+            try:
+                remaining = max(0.0, flight.deadline - time.monotonic())
+                result = (
+                    bounded_build(remaining)
+                    if bounded_build is not None else build()
+                )
+            except TimeoutError:
+                self._finish(key, flight, error=_DiagnosisTimedOut())
+            except BaseException as exc:
+                self._finish(
+                    key, flight,
+                    error=(_DiagnosisTimedOut()
+                           if time.monotonic() >= flight.deadline else exc),
+                )
+            else:
+                if time.monotonic() >= flight.deadline:
+                    self._finish(key, flight, error=_DiagnosisTimedOut())
+                else:
+                    self._finish(key, flight, result=result)
+        finally:
+            # Production passes a killable process build, so reaching the
+            # deadline retires that process tree before this slot is released.
+            # Direct in-process builds remain available only to focused unit
+            # callers whose producer is known to terminate.
+            self._admission.release()
+
+    def run(self, key: tuple[Any, bool, bool], build, *, peer_gone=None,
+            bounded_build=None):
         with self._changed:
             flight = self._flights.get(key)
             owner = flight is None
+            if self._callers >= self._max_callers:
+                raise _DiagnosisOverloaded()
             if owner:
-                flight = _DiagnosisFlight()
+                if len(self._flights) >= self._max_keys:
+                    raise _DiagnosisOverloaded()
+                flight = _DiagnosisFlight(
+                    deadline=time.monotonic() + self._deadline_seconds,
+                )
                 self._flights[key] = flight
+            elif flight.callers >= self._max_per_key:
+                raise _DiagnosisOverloaded()
             flight.callers += 1
+            self._callers += 1
             self._changed.notify_all()
-
-        if not owner:
-            flight.done.wait()
-            if flight.error is not None:
-                raise flight.error
-            return flight.result
-
         try:
-            with self._admission:
-                result = build()
-            with self._changed:
-                flight.result = result
-            return result
-        except BaseException as exc:
+            if owner:
+                try:
+                    threading.Thread(
+                        target=self._produce,
+                        args=(key, flight, build, bounded_build),
+                        name="cctally-diagnosis", daemon=True,
+                    ).start()
+                except BaseException as exc:
+                    self._finish(key, flight, error=exc)
+            while not flight.done.is_set():
+                if peer_gone is not None and peer_gone():
+                    raise _DiagnosisClientGone()
+                remaining = flight.deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                flight.done.wait(min(0.1, remaining))
+            if not flight.done.is_set():
+                self._finish(key, flight, error=_DiagnosisTimedOut())
             with self._changed:
-                flight.error = exc
-            raise
+                if flight.error is not None:
+                    raise flight.error
+                return flight.result
         finally:
             with self._changed:
-                if self._flights.get(key) is flight:
-                    del self._flights[key]
-                flight.done.set()
+                flight.callers -= 1
+                self._callers -= 1
                 self._changed.notify_all()
 
 
 _DIAGNOSIS_ADMISSION = _DiagnosisAdmission()
 
 
+class _StaticValidatorCache:
+    """Bounded validators for bytes already served by this process."""
+
+    def __init__(self, max_entries: int = 128) -> None:
+        self._lock = threading.Lock()
+        self._entries: OrderedDict[tuple[pathlib.Path, bool],
+                                   tuple[tuple[int, ...], str]] = OrderedDict()
+        self._max_entries = max_entries
+
+    @staticmethod
+    def fingerprint(stat_result: os.stat_result) -> tuple[int, ...]:
+        # ctime catches a rewrite that restores size and mtime. Device/inode
+        # distinguishes replacement of a mutable-name shell during a build.
+        return (stat_result.st_dev, stat_result.st_ino, stat_result.st_size,
+                stat_result.st_mtime_ns, stat_result.st_ctime_ns)
+
+    def get(self, key, fingerprint) -> str | None:
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None or entry[0] != fingerprint:
+                return None
+            self._entries.move_to_end(key)
+            return entry[1]
+
+    def put(self, key, fingerprint, etag: str) -> None:
+        with self._lock:
+            self._entries[key] = (fingerprint, etag)
+            self._entries.move_to_end(key)
+            if len(self._entries) > self._max_entries:
+                self._entries.popitem(last=False)
+
+
+_STATIC_VALIDATORS = _StaticValidatorCache()
+
+
 def _cctally():
     """Resolve the current ``cctally`` module at call-time (spec §5.5)."""
     return sys.modules["cctally"]
@@ -475,10 +712,6 @@ from _lib_aggregators import (
     _finalize_bucket,
 )
 from _lib_fmt import stable_sum
-# The MODULE, not just the names: #714's `pricing_snapshot_context` has to be
-# reached through the live module object so a test that swaps the snapshot is
-# seen by the request, build and sync entries below.
-import _lib_pricing
 from _lib_pricing import (_calculate_entry_cost, _chip_for_model,
                           _short_model_name, claude_usage_dict)
 from _lib_five_hour import _canonical_5h_window_key, _round_to_ten_minutes
@@ -669,6 +902,7 @@ from _cctally_dashboard_envelope import (
     _envelope_rows_projected,
     _envelope_rows_project_budget,
     _ENVELOPE_AXIS_MAPPERS,
+    _alert_account_resolver,
     _build_alerts_envelope_array,
     _build_meter_rate_change_array,
     _model_breakdowns_to_models,
@@ -2034,13 +2268,6 @@ def _make_dashboard_run_iteration(
 
     def run_iteration(batch=None) -> dict:
         warnings: list = []
-        # #714: the whole snapshot build runs on ONE pricing revision. A swap
-        # landing part-way through would publish a snapshot whose panels were
-        # priced from two different tables.
-        with _lib_pricing.pricing_snapshot_context():
-            return _run_iteration_body(batch, warnings)
-
-    def _run_iteration_body(batch, warnings: list) -> dict:
         if batch is not None and batch[1] and not skip_sync:
             with sync_lock:
                 result = _refresh_usage_inproc()
@@ -2318,103 +2545,38 @@ def _wake_schema_writer() -> None:
             _SCHEMA_WAKE_THREAD = None
 
 
-#: How often the pricing watch stats the deployed pricing file. A monotonic
-#: cadence, because a wall-clock one would re-poll or stall across a system
-#: clock change.
-_PRICING_WATCH_INTERVAL_S = 60.0
+_INSTALL_WATCH = None
 
 
-class _PricingWatch:
-    """Detect a replaced `_lib_pricing.py` and adopt it in process (#714).
+def _start_install_watch(boot):
+    """Own the install watch on its own lifecycle thread, in every mode (#868).
 
-    An installer overwrites the deployed file under a running dashboard.
-    Nothing about that reaches this process: every CLI invocation re-imports
-    and picks the new tables up, and only a long-lived process holds the old
-    ones.
-
-    STAT FIRST, PARSE SECOND. The poll compares an inode/size/mtime signature
-    and parses only when it changed, so the steady state is one `stat` a
-    minute rather than an `ast.parse` of a 1,400-line file.
-
-    NEVER RAISES OUT OF `poll_once`. The file it reads is one an installer may
-    be part-way through writing, so a half-written file is the ordinary case
-    rather than an exceptional one; a raising poll would end the thread and
-    leave the process permanently stale, which is the very condition this
-    exists to clear.
+    Not started from a git checkout, where file changes are development work,
+    not installs.
     """
-
-    def __init__(self, source_path=None, interval_s=None):
-        self.source_path = pathlib.Path(
-            source_path if source_path is not None
-            else sys.modules["_lib_pricing"].__file__)
-        self.interval_s = (_PRICING_WATCH_INTERVAL_S if interval_s is None
-                           else interval_s)
-        self._signature = None
-        self._stop = threading.Event()
-
-    def _current_signature(self):
-        try:
-            st = self.source_path.stat()
-        except OSError:
-            return None
-        return (st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns)
-
-    def poll_once(self) -> bool:
-        """One check. Returns True iff a new snapshot was adopted."""
-        try:
-            signature = self._current_signature()
-            if signature is None or signature == self._signature:
-                return False
-            self._signature = signature
-            pricing = sys.modules["_lib_pricing"]
-            candidate = pricing.read_pricing_snapshot_from_source(
-                self.source_path)
-            if not pricing.adopt_pricing_candidate(candidate):
-                return False
-            eprint("[pricing] adopted pricing revision "
-                   f"{candidate.snapshot_date} without restarting")
-            return True
-        except Exception:  # noqa: BLE001
-            # Including `PricingCandidateRejected`: a rejected candidate is a
-            # normal outcome, and the signature is already recorded so the
-            # same bad file is not re-parsed every minute.
-            return False
-
-    def run(self) -> None:
-        while not self._stop.wait(self.interval_s):
-            self.poll_once()
-
-    def stop(self) -> None:
-        self._stop.set()
-
-
-_PRICING_WATCH: "_PricingWatch | None" = None
-
-
-def _start_pricing_watch() -> "_PricingWatch | None":
-    """Own the pricing detector on a lifecycle thread that runs in BOTH modes.
-
-    Deliberately not `_DashboardSyncThread` and not the conversation sync
-    thread: `cmd_dashboard` disables both under `--no-sync`, so a detector in
-    either would silently have no owner exactly where a long-lived process is
-    most likely to run.
-    """
-    global _PRICING_WATCH
-    if _PRICING_WATCH is not None:
-        return _PRICING_WATCH
+    global _INSTALL_WATCH
+    if _cctally_core._is_dev_checkout():
+        return None
+    if _INSTALL_WATCH is not None:
+        return _INSTALL_WATCH
     try:
-        watch = _PricingWatch()
-        watch.poll_once()  # establish the baseline signature; adopts nothing
-        thread = threading.Thread(
-            target=watch.run, name="cctally-pricing-watch", daemon=True)
-        thread.start()
+        watch = InstallWatch(
+            boot, worker_fn=lambda: getattr(_cctally(), "_UPDATE_WORKER", None))
+        watch.start()
     except Exception as exc:  # noqa: BLE001
-        eprint(f"[pricing] watch not started ({exc})")
+        eprint(f"[update] install watch not started ({exc})")
         return None
-    _PRICING_WATCH = watch
+    _INSTALL_WATCH = watch
     return watch
 
 
+def _stop_install_watch() -> None:
+    global _INSTALL_WATCH
+    watch, _INSTALL_WATCH = _INSTALL_WATCH, None
+    if watch is not None:
+        watch.stop()
+
+
 def _dashboard_maybe_prune_retention() -> None:
     """#313 P3 (F7): throttled transcript retention prune driven from the
     independent conversation sync thread. Opens a dedicated transcript
@@ -2574,18 +2736,7 @@ def _conversation_sync_pass() -> str:
     therefore NO SECOND OPEN ATTEMPT AFTER A FAILED OPEN — stated that narrowly
     because a successful pass opens the store twice by design, once here and
     once inside the prune.
-
-    #714: the whole pass runs on ONE pricing revision. This pass writes
-    materialized cost, so a swap landing between the Claude leg and the Codex
-    leg would derive one store's rollup from two revisions — the ordered-write
-    guard would not even see it, because both halves are the same process.
     """
-    with _lib_pricing.pricing_snapshot_context():
-        return _conversation_sync_pass_body()
-
-
-def _conversation_sync_pass_body() -> str:
-    """The body of `_conversation_sync_pass`, run under its pricing context."""
     try:
         conn = open_conversations_db()
     except (OSError, sqlite3.DatabaseError) as exc:
@@ -3137,6 +3288,14 @@ def _DashboardUpdateCheckThread(*args, **kwargs):
     return sys.modules["cctally"]._DashboardUpdateCheckThread(*args, **kwargs)
 
 
+def capture_install_boot_state(*args, **kwargs):
+    return sys.modules["cctally"].capture_install_boot_state(*args, **kwargs)
+
+
+def InstallWatch(*args, **kwargs):
+    return sys.modules["cctally"].InstallWatch(*args, **kwargs)
+
+
 # Module-level __getattr__ — lazy-resolves a handful of cctally globals at
 # attribute-access time (used for the ``except cctally.SomeError`` sites
 # that need real class identity, and for non-callable constants that the
@@ -4807,6 +4966,7 @@ def _blocks_view_with_retained_facts(conn, view):
                 models=_model_breakdowns_to_models(
                     facts["model_breakdowns"], facts["cost_usd"],
                 ),
+                facts_source="retained",
             )
     return dataclasses.replace(
         view,
@@ -8371,19 +8531,6 @@ _GET_ROUTES = (
      ("scope", "endpoint.conversation_detail"), True),
 )
 
-#: Handlers that block for the life of a client connection rather than for one
-#: response. `_dispatch` must NOT pin a pricing revision around these: the pin
-#: would last as long as the stream, so a viewer who left a tab open would keep
-#: pricing from whichever revision was live when the tab connected — the exact
-#: staleness #714 removes. Both are streams that carry no cost of their own;
-#: the envelopes they forward are priced by the build that produced them, which
-#: has its own context.
-_STREAMING_ROUTE_HANDLERS = frozenset({
-    "_serve_api_events",
-    "_handle_get_update_stream",
-    "_handle_get_conversation_events",
-})
-
 _POST_ROUTES = (
     ("exact", "/api/auth", "_handle_post_auth", None, False),
     ("exact", "/api/sync", "_handle_post_sync", None, False),
@@ -8519,13 +8666,6 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         eleven path-taking handlers. (NOTE: returning a bool, not ``fn()`` —
         the void handlers all return None, so a None-return contract could not
         tell "handled" from "unmatched".)
-
-        #714: every matched route runs inside a pricing-snapshot context, so a
-        response is never assembled from two pricing revisions when an
-        installer replaces `_lib_pricing.py` mid-request. The two long-lived
-        streaming routes are excluded — a context entered there would pin one
-        revision for the whole life of the stream, which is minutes to hours
-        and the opposite of what the reload exists to achieve.
         """
         path = self.path.split("?", 1)[0]
         for kind, pattern, name, perf, wants_path in table:
@@ -8539,19 +8679,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 continue
             fn = getattr(self, name)
             args = (path,) if wants_path else ()
-            if name in _STREAMING_ROUTE_HANDLERS:
-                pinned = contextlib.nullcontext()
-            else:
-                pinned = _lib_pricing.pricing_snapshot_context()
-            with pinned:
-                if perf is None:
+            if perf is None:
+                fn(*args)
+            elif perf[0] == "scope":
+                with self._perf_scope(perf[1]):
+                    fn(*args)
+            else:  # "phase"
+                with self._perf_gate().phase(perf[1]):
                     fn(*args)
-                elif perf[0] == "scope":
-                    with self._perf_scope(perf[1]):
-                        fn(*args)
-                else:  # "phase"
-                    with self._perf_gate().phase(perf[1]):
-                        fn(*args)
             return True
         return False
 
@@ -10103,7 +10238,31 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 primary_model="claude-sonnet-4-6",
             )
         status = _dispatch_alert_notification(payload, mode="test")
-        self._respond_json(200, {"alert": payload, "dispatch": status})
+        # Dispatch and alerts.log keep the builder's internal snake_case key.
+        # The response is an AlertEntry-shaped toast preview, so its public
+        # account fields must follow the same R8 gate as real envelope rows.
+        # Work on a copy: removing the key from `payload` would also change
+        # what the native notifier and test log receive.
+        response_alert = {k: v for k, v in payload.items() if k != "account_key"}
+        provider = (
+            "codex" if axis == "codex_budget" or (
+                axis == "projected" and metric == "codex_budget_usd"
+            ) else "claude"
+        )
+        if _cctally_core.DB_PATH.exists():
+            try:
+                conn = _stats_ro_guarded()
+                try:
+                    response_alert.update(_alert_account_resolver(conn)(
+                        provider, payload.get("account_key"),
+                    ))
+                finally:
+                    conn.close()
+            except (OSError, sqlite3.Error):
+                # A rehearsal still works without a readable account registry;
+                # no writable DB open or synthetic milestone is needed.
+                pass
+        self._respond_json(200, {"alert": response_alert, "dispatch": status})
 
 
     # ---- share endpoints (spec §5.1) — thin delegators to the F1 sibling ----
@@ -10198,15 +10357,6 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         return False
 
     def _serve_static_file(self, path: pathlib.Path, ctype: str) -> None:
-        try:
-            body = path.read_bytes()
-        except FileNotFoundError:
-            self.send_error(404, "not found")
-            return
-        except IsADirectoryError:
-            self.send_error(404, "not found")
-            return
-
         compressible = (
             ctype.startswith("text/")
             or ctype.startswith("application/javascript")
@@ -10215,15 +10365,54 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         gzip_on = compressible and _accepts_gzip(
             self.headers.get("Accept-Encoding")
         )
-        encoded = gzip.compress(body, compresslevel=6, mtime=0) if gzip_on else body
-        etag = f'"{hashlib.sha256(encoded).hexdigest()}"'
         cache_control = (
             "public, max-age=31536000, immutable"
             if self._is_hashed_static_asset(path)
             else "no-cache"
         )
+        validator = self.headers.get("If-None-Match")
+        key = (path, gzip_on)
+        try:
+            before = _STATIC_VALIDATORS.fingerprint(path.stat())
+        except (FileNotFoundError, IsADirectoryError):
+            self.send_error(404, "not found")
+            return
+
+        # Only a validator derived from bytes previously served for this exact
+        # encoding and unchanged file identity can answer before I/O. In
+        # particular, a mutable dashboard.html replacement invalidates this.
+        if validator:
+            warm_etag = _STATIC_VALIDATORS.get(key, before)
+            if warm_etag and self._etag_matches(validator, warm_etag):
+                self.send_response(304)
+                self.send_header("ETag", warm_etag)
+                self.send_header("Cache-Control", cache_control)
+                if compressible:
+                    self.send_header("Vary", "Accept-Encoding")
+                if gzip_on:
+                    self.send_header("Content-Encoding", "gzip")
+                self.end_headers()
+                return
 
-        if self._etag_matches(self.headers.get("If-None-Match"), etag):
+        try:
+            body = path.read_bytes()
+        except FileNotFoundError:
+            self.send_error(404, "not found")
+            return
+        except IsADirectoryError:
+            self.send_error(404, "not found")
+            return
+
+        encoded = gzip.compress(body, compresslevel=6, mtime=0) if gzip_on else body
+        etag = f'"{hashlib.sha256(encoded).hexdigest()}"'
+        try:
+            after = _STATIC_VALIDATORS.fingerprint(path.stat())
+        except (FileNotFoundError, IsADirectoryError):
+            after = None
+        if after == before:
+            _STATIC_VALIDATORS.put(key, before, etag)
+
+        if after == before and self._etag_matches(validator, etag):
             self.send_response(304)
             self.send_header("ETag", etag)
             self.send_header("Cache-Control", cache_control)
@@ -10588,12 +10777,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     scope, transcripts_visible, reveal,
                 )
 
-                def _prepare_diagnosis():
-                    report = sources.build_diagnosis(
-                        scope,
-                        measured_at=now_utc,
-                        transcripts_visible=transcripts_visible,
-                    )
+                def _project_diagnosis(report):
                     scopes = {
                         result.source: diagnosis._scope_for(
                             sources, scope, result.source,
@@ -10612,10 +10796,43 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     )
                     return status, body
 
+                def _prepare_diagnosis():
+                    return _project_diagnosis(sources.build_diagnosis(
+                        scope,
+                        measured_at=now_utc,
+                        transcripts_visible=transcripts_visible,
+                    ))
+
+                def _prepare_bounded_diagnosis(remaining):
+                    return _project_diagnosis(
+                        sources.build_diagnosis_bounded(
+                            scope,
+                            measured_at=now_utc,
+                            transcripts_visible=transcripts_visible,
+                            timeout_seconds=remaining,
+                        )
+                    )
+
                 status, body = _DIAGNOSIS_ADMISSION.run(
                     flight_key,
                     _prepare_diagnosis,
+                    peer_gone=lambda: _diagnosis_peer_gone(self.connection),
+                    bounded_build=_prepare_bounded_diagnosis,
                 )
+            except _DiagnosisClientGone:
+                return
+            except _DiagnosisOverloaded:
+                self._send_diagnosis_json(503, {
+                    "error": "diagnosis busy; retry shortly",
+                    "code": "diagnosis_overloaded",
+                })
+                return
+            except _DiagnosisTimedOut:
+                self._send_diagnosis_json(503, {
+                    "error": "diagnosis timed out; retry shortly",
+                    "code": "diagnosis_timeout",
+                })
+                return
             except _DiagnosisSelectorError as exc:
                 self._send_diagnosis_json(
                     400, {"error": exc.message, "code": exc.code})
@@ -11410,7 +11627,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         as an explicit user pin; the worker resolves the selected channel
         afresh. CSRF-gated. Returns
         202 + ``{"run_id": ...}`` on accept; 409 + ``{"run_id_in_progress": ...}``
-        when another run is already in progress.
+        when another run is already in progress; 503 + ``{"error": ...}`` while
+        the install watcher holds the automatic-restart claim (#868), which
+        the unchanged client shows as a failed start.
         """
         if not self._check_origin_csrf():
             return
@@ -11432,7 +11651,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         # The dashboard has no explicit-version input. Older clients sent the
         # cached beta target here; trusting it as a pin recreates #342 whenever
         # the registry advances while the modal is open.
-        accepted, run_id = worker.start(None)
+        try:
+            accepted, run_id = worker.start(None)
+        except sys.modules["cctally"].AutomaticRestartInProgress as exc:
+            self._respond_json(503, {"error": str(exc)})
+            return
         if accepted:
             self._respond_json(202, {"run_id": run_id})
         else:
@@ -12018,16 +12241,20 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     _cctally_core.enable_quota_projection_reconciliation()
 
     # Spec §5.7: capture the un-mutated argv + PATH-resolved entrypoint
-    # at boot so the in-place ``execvp`` after a successful update
-    # re-enters the user-facing wrapper (npm Node shim → CCTALLY_PYTHON
-    # honoured; brew symlink → post-upgrade Python script). Module-level
-    # globals live in cctally (declared at L23205 pre-extract); we write
-    # them via the module-proxy so ``UpdateWorker`` (in _cctally_update)
-    # reads the right values via ``cctally.X`` at call time.
+    # at boot. ``_resolve_execvp_target`` derives the in-place restart
+    # from them: an npm install execs Python directly on its own
+    # ``bin/cctally`` (no added Node process, #868), and a brew install
+    # re-enters the symlink into the newly linked keg. Module-level
+    # globals live in cctally; we write them via the module-proxy so
+    # ``UpdateWorker`` and the install watch (in _cctally_update) read the
+    # right values via ``cctally.X`` at call time.
     _c_boot = _cctally()
     _c_boot.ORIGINAL_SYS_ARGV = list(sys.argv)
     _c_boot.ORIGINAL_ENTRYPOINT = shutil.which("cctally")
     _c_boot._UPDATE_WORKER = UpdateWorker()
+    # #868: captured before any thread starts; the install watch compares every
+    # later poll against what this process booted from.
+    _install_boot = capture_install_boot_state()
 
     # Load config for the bind-host + expose-transcripts resolution below. (#217
     # S1 / U7b: dropped the dead ``args._resolved_tz = resolve_display_tz(...)``
@@ -12112,11 +12339,9 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     _cctally_cache_module.set_conversation_derivations_suppressed(
         bool(args.no_sync))
     _dashboard_startup_schema_migration(run_derivations=not bool(args.no_sync))
-    # #714: the pricing-file watch, in EVERY mode for the same reason. Both
-    # `_DashboardSyncThread` and `_make_conversation_sync_thread` are disabled
-    # under `--no-sync`, so a detector placed in either would have no owner in
-    # the one mode a long-lived read-only dashboard runs in.
-    _start_pricing_watch()
+    # #868: in EVERY mode, because `--no-sync` disables both sync threads and a
+    # long-lived read-only dashboard is still left behind by an install.
+    _start_install_watch(_install_boot)
     _heal = _dashboard_self_heal_orphans(skip_sync=bool(args.no_sync))
     if _heal is not None and _heal.pruned_files:
         print(f"dashboard: pruned {_heal.pruned_files} orphaned cache file(s) "
@@ -12382,6 +12607,8 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     try:
         _dashboard_wait_for_signal((_signal.SIGINT, _signal.SIGTERM))
     finally:
+        # First, so a shutdown can never be followed by an automatic restart.
+        _stop_install_watch()
         if sync_thread is not None:
             sync_thread.stop()
         conversation_sync_stop.set()