cctally 1.63.0 → 1.65.0

package/bin/_cctally_dashboard.py

@@ -2600,13 +2600,35 @@ class SSEHub:
         import queue as _queue
         with self._lock:
             self._last = snapshot
-            queues = list(self._queues)
-        for q in queues:
-            try:
-                q.put_nowait(snapshot)
-            except _queue.Full:
-                # Slow client — drop this frame; the next tick re-sends.
-                pass
+            # Latest-wins coalescing (#278 §2.6): every published snapshot is a
+            # COMPLETE state replacement, so a client only ever needs the
+            # newest. On a full queue drop the STALE queued frame and enqueue
+            # the newest, so a slow subscriber (e.g. one filled by A2's rapid
+            # partial republishes) still converges to the final hydrating=false
+            # frame instead of dropping it — and a lagging client jumps to the
+            # current state rather than replaying stale frames.
+            #
+            # Held under the hub lock so concurrent producers (the sync tick +
+            # the update-check thread) can't interleave a get/put on the same
+            # queue. All ops are non-blocking (put_nowait / get_nowait), so
+            # holding the lock never back-pressures the producer, and the SSE
+            # consumer only ever get()s (never puts), so after we make room the
+            # re-put cannot lose to it.
+            for q in self._queues:
+                try:
+                    q.put_nowait(snapshot)
+                except _queue.Full:
+                    try:
+                        q.get_nowait()  # discard the oldest, stale frame
+                    except _queue.Empty:
+                        pass
+                    try:
+                        q.put_nowait(snapshot)
+                    except _queue.Full:
+                        # Defensive: a consumer racing between our get and put
+                        # could only have removed items, so this is unreachable
+                        # under the lock — but never raise out of publish().
+                        pass
 
 
 STATIC_DIR = pathlib.Path(__file__).resolve().parent.parent / "dashboard" / "static"
@@ -6205,6 +6227,11 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
 
     return {
         "envelope_version": 2,
+        # #278 Theme A: single additive first-paint hydration latch. True only
+        # on the cheap seed + A2's partial republishes (data still being
+        # assembled); False on every complete/stable snapshot. ``getattr``
+        # default keeps positionally-constructed fixture snapshots serializing.
+        "hydrating":        bool(getattr(snap, "hydrating", False)),
         "generated_at":     _iso_z(snap.generated_at),
         # last_sync_at in DataSnapshot is a monotonic float, not a wall
         # clock — the envelope's wall-clock moment is unknowable from
@@ -6567,6 +6594,112 @@ def _cached_file_sigs(conn, paths):
     return out
 
 
+# ── /api/debug/backend on-demand cache-state helpers (issue #276, Session A) ──
+# All read-only, cheap, and privacy-safe: they leak ONLY row counts, signature
+# legs (ints/tuples), pending-flag names, and the tool version — never prompt /
+# prose / paths. Computed on demand so cache_state is available even with
+# tracing off (the phase tree, by contrast, is present only when traced).
+
+# Safe cache-table names surfaced as `dataset` row counts (no content read).
+_DEBUG_CACHE_TABLES = (
+    "session_entries",
+    "session_files",
+    "conversation_messages",
+    "conversation_sessions",
+    "conversation_ai_titles",
+    "conversation_file_touches",
+    "codex_session_entries",
+    "codex_session_files",
+)
+
+
+def _debug_cache_table_counts(cache_conn) -> dict:
+    """Row counts per known cache table. Absent tables (partially-migrated /
+    fresh cache) are omitted rather than erroring."""
+    counts: dict = {}
+    for table in _DEBUG_CACHE_TABLES:
+        try:
+            row = cache_conn.execute(
+                f"SELECT COUNT(*) FROM {table}"  # noqa: S608 — fixed allowlist
+            ).fetchone()
+            counts[table] = int(row[0])
+        except sqlite3.Error:
+            pass
+    return counts
+
+
+def _debug_cache_state(cache_conn) -> dict:
+    """On-demand signature legs + pending-reingest flags + generation.
+
+    The signature legs are the canonical ``compute_signature`` fields (ints /
+    a small tuple). stats.db is opened READ-ONLY via a dispatcher-free URI
+    connection so this diagnostic never forward-migrates or creates a DB; if it
+    is absent the stats legs degrade (each ``_max_id`` / ``_reset_sig`` already
+    returns 0 on a missing table)."""
+    c = _cctally()
+    sc = c._load_sibling("_lib_snapshot_cache")
+    state: dict = {"generation": sc.current_generation()}
+    stats_conn = None
+    try:
+        stats_conn = sqlite3.connect(
+            f"{_cctally_core.DB_PATH.as_uri()}?mode=ro", uri=True
+        )
+    except sqlite3.Error:
+        stats_conn = None
+    try:
+        if stats_conn is not None:
+            sig = sc.compute_signature(
+                cache_conn, stats_conn, generation=sc.current_generation()
+            )
+            state["signature"] = {
+                "max_entry_id": sig.max_entry_id,
+                "max_wus_id": sig.max_wus_id,
+                "max_wcs_id": sig.max_wcs_id,
+                "reset_sig": list(sig.reset_sig),
+                "max_codex_id": sig.max_codex_id,
+                "entry_mutation_seq": sig.entry_mutation_seq,
+            }
+        else:
+            state["signature"] = {
+                "max_entry_id": sc._max_id(cache_conn, "session_entries"),
+                "entry_mutation_seq": sc._entry_mutation_seq(cache_conn),
+            }
+    except sqlite3.Error as exc:
+        state["signature"] = {"_error": f"{type(exc).__name__}: {exc}"}
+    finally:
+        if stats_conn is not None:
+            stats_conn.close()
+    # Pending reingest / backfill flag NAMES (never values) set in cache_meta.
+    try:
+        rows = cache_conn.execute(
+            "SELECT key FROM cache_meta "
+            "WHERE key LIKE '%_pending' AND value IS NOT NULL"
+        ).fetchall()
+        state["pending_reingest"] = sorted(r[0] for r in rows)
+    except sqlite3.Error:
+        state["pending_reingest"] = []
+    # Walk-complete sentinel presence (bool only — no timestamp leak).
+    try:
+        state["walk_complete"] = cache_conn.execute(
+            "SELECT 1 FROM cache_meta WHERE key='claude_ingest_walk_complete'"
+        ).fetchone() is not None
+    except sqlite3.Error:
+        state["walk_complete"] = False
+    return state
+
+
+def _debug_tool_version() -> str:
+    """The running tool version (latest stamped CHANGELOG header), or
+    ``"unknown"``. Safe to expose (already on the public update surface)."""
+    try:
+        v = _cctally()._load_sibling(
+            "_lib_changelog"
+        )._read_latest_changelog_version()
+        return v[0] if v else "unknown"
+    except Exception:  # noqa: BLE001 — diagnostic must never raise
+        return "unknown"
+
+
 class DashboardHTTPHandler(BaseHTTPRequestHandler):
     """Routes:
         GET /                       → dashboard.html
@@ -6693,42 +6826,58 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._handle_share_history_get()
         elif path == "/api/doctor":
             self._handle_get_doctor()
+        elif path == "/api/debug/backend":
+            # Loopback-only backend diagnostic (issue #276): last-build phase
+            # timings + on-demand cache-state. Its own stricter gate (never
+            # expose_transcripts); see _handle_get_debug_backend.
+            self._handle_get_debug_backend()
         elif path == "/api/conversations/facets":
-            self._handle_get_conversations_facets()
+            with self._perf_scope("endpoint.conversations_facets"):
+                self._handle_get_conversations_facets()
         elif path == "/api/conversations":
-            self._handle_get_conversations()
+            with self._perf_scope("endpoint.conversations"):
+                self._handle_get_conversations()
         elif path == "/api/conversation/search":
-            self._handle_get_conversation_search()
+            with self._perf_scope("endpoint.conversation_search"):
+                self._handle_get_conversation_search()
         elif path.startswith("/api/conversation/") and path.endswith("/payload"):
             # #178: on-demand load-full. Matched BEFORE the <id> reader
             # catch-all (same precedence as /api/conversation/search).
-            self._handle_get_conversation_payload(path)
+            with self._perf_gate().phase("endpoint.conversation_payload"):
+                self._handle_get_conversation_payload(path)
         elif path.startswith("/api/conversation/") and path.endswith("/media"):
             # #177 S4: on-demand media bytes. Matched BEFORE the <id> reader.
-            self._handle_get_conversation_media(path)
+            with self._perf_gate().phase("endpoint.conversation_media"):
+                self._handle_get_conversation_media(path)
         elif path.startswith("/api/conversation/") and path.endswith("/outline"):
             # #177 S5: full-session outline skeleton + stats. Matched BEFORE
             # the <id> reader catch-all (Codex F2 — same precedence as /payload).
-            self._handle_get_conversation_outline(path)
+            with self._perf_scope("endpoint.conversation_outline"):
+                self._handle_get_conversation_outline(path)
         elif path.startswith("/api/conversation/") and path.endswith("/find"):
             # #177 S6: in-conversation find → rendered-turn anchors. Matched
             # BEFORE the <id> reader catch-all (same precedence as /outline).
-            self._handle_get_conversation_find(path)
+            with self._perf_scope("endpoint.conversation_find"):
+                self._handle_get_conversation_find(path)
         elif path.startswith("/api/conversation/") and path.endswith("/events"):
             # Live-tail SSE for the open reader (spec §2). Matched BEFORE the
             # <id> reader catch-all.
-            self._handle_get_conversation_events(path)
+            with self._perf_gate().phase("endpoint.conversation_events"):
+                self._handle_get_conversation_events(path)
         elif path.startswith("/api/conversation/") and path.endswith("/export"):
             # #217 S5: whole-session Markdown export (F1/F5). Matched BEFORE the
             # <id> reader catch-all (same precedence as /outline).
-            self._handle_get_conversation_export(path)
+            with self._perf_scope("endpoint.conversation_export"):
+                self._handle_get_conversation_export(path)
         elif path.startswith("/api/conversation/") and path.endswith("/prompts"):
             # #217 S7: ordered main-thread prompt spine for session comparison
             # (F10). Matched BEFORE the <id> reader catch-all (same precedence
             # as /outline).
-            self._handle_get_conversation_prompts(path)
+            with self._perf_scope("endpoint.conversation_prompts"):
+                self._handle_get_conversation_prompts(path)
         elif path.startswith("/api/conversation/"):
-            self._handle_get_conversation_detail(path)
+            with self._perf_scope("endpoint.conversation_detail"):
+                self._handle_get_conversation_detail(path)
         else:
             self.send_error(404, "not found")
 
@@ -6924,6 +7073,95 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return False
         return True
 
+    @staticmethod
+    def _perf_gate():
+        """Lazy-load the opt-in backend phase-instrumentation collector (#276).
+        Near-noop when tracing is off (``phase()`` returns a shared singleton),
+        so the coarse ``endpoint.*`` wraps in ``do_GET`` cost nothing by
+        default."""
+        return sys.modules["cctally"]._load_sibling("_lib_perf")
+
+    @contextlib.contextmanager
+    def _perf_scope(self, name):
+        """Like ``_perf_gate().phase(name)`` but ALSO stashes the completed root
+        so the loopback ``/api/debug/backend`` surface can read a CONVERSATION
+        trace, not just the ``/api/data`` snapshot tree (Session C / M5 — the
+        Session A dead-end: no ``stash_last`` ran on a request thread). On enter
+        it ``reset_thread()``s (each conversation handler runs on its own request
+        thread, so this can't clobber the snapshot-build thread's tree) and opens
+        ``phase(name)``; on clean exit it stashes ``current_root()``. Near-noop
+        when ``CCTALLY_PERF_TRACE`` is off — ``phase()`` returns ``_NULL_PHASE``,
+        no root is pushed, so ``current_root()`` is ``None`` and ``stash_last``
+        early-returns. Used ONLY for the short-lived, assembly-relevant routes;
+        the long-lived ``/events`` SSE keeps a plain, non-stashing wrap (Codex F3)
+        so it can never overwrite the last useful assembly trace on disconnect."""
+        perf = self._perf_gate()
+        perf.reset_thread()
+        with perf.phase(name):
+            yield
+        try:
+            perf.stash_last(
+                perf.current_root(),
+                generated_at=dt.datetime.now(dt.timezone.utc).isoformat())
+        except Exception:  # noqa: BLE001 — a diagnostic stash must never 500
+            pass
+
+    def _require_debug_backend_allowed(self) -> bool:
+        """Gate for ``/api/debug/backend`` (issue #276) — STRICTER than the
+        transcript gate.
+
+        PRIMARY: the TCP peer (``client_address[0]``) must be loopback — the
+        unspoofable signal (the dashboard can bind ``0.0.0.0``, so a
+        ``Host``-only check is spoofable). DEFENSE-IN-DEPTH: the ``Host``
+        authority must ALSO be an IP-literal loopback (anti-DNS-rebinding).
+        ``expose_transcripts`` is NEVER consulted. 403 + ``False`` otherwise.
+        """
+        ta = self._transcript_gate()
+        peer = self.client_address[0] if self.client_address else ""
+        host = self.headers.get("Host")
+        if not ta.debug_backend_allowed(peer, host):
+            self._respond_403("forbidden")
+            return False
+        return True
+
+    def _handle_get_debug_backend(self) -> None:
+        """GET ``/api/debug/backend`` — loopback-only backend diagnostic (#276).
+
+        Returns the last completed snapshot build's phase-timing tree (present
+        only if the dashboard was started with ``CCTALLY_PERF_TRACE=1``; else
+        ``null`` + a ``tracing_disabled`` note) plus on-demand cache-table row
+        counts and signature legs. Leaks no prompt / prose / paths — timings,
+        counts, flag names, and safe cache-table names only. ``schemaVersion``
+        is 1 but the surface is documented UNSTABLE (a diagnostic, not a
+        consumer contract): phase names / nesting / fields may change without a
+        version bump.
+        """
+        if not self._require_debug_backend_allowed():
+            return
+        last = self._perf_gate().last_backend_perf()
+        dataset: dict = {}
+        cache_state: dict = {}
+        try:
+            conn = open_cache_db()
+            try:
+                dataset = _debug_cache_table_counts(conn)
+                cache_state = _debug_cache_state(conn)
+            finally:
+                conn.close()
+        except Exception as exc:  # noqa: BLE001 — a diagnostic must not 500 loudly
+            cache_state = {"_error": f"{type(exc).__name__}: {exc}"}
+        body = {
+            "schemaVersion": 1,
+            "version": _debug_tool_version(),
+            "generated_at": (last or {}).get("generated_at"),
+            "dataset": dataset,
+            "phases": (last or {}).get("phases"),
+            "cache_state": cache_state,
+        }
+        if body["phases"] is None:
+            body["note"] = "tracing_disabled"
+        self._respond_json(200, body)
+
     def _handle_post_settings(self) -> None:
         """Persist a settings update and trigger an immediate SSE broadcast.
 
@@ -8765,13 +9003,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         on bad input). On success returns a dict of ``list_conversations``
         kwargs: ``date_from``/``date_to`` (UTC-ISO bounds), ``projects``
         (list[str] | None), ``cost_min``/``cost_max`` (float | None),
-        ``rebuild_min`` (int | None). Empty/blank params drop to ``None``.
+        ``rebuild_min`` (int | None), ``models`` (list[str] | None — the #278
+        Theme C model-family axis). Empty/blank params drop to ``None``.
 
         Numeric axes validate strictly (a non-numeric cost / non-integer
         rebuild threshold is a hard 400). Date bounds route through the pure
         ``_lib_dashboard_dates.parse_filter_date_range`` helper, which resolves
         naive date-only bounds in ``display.tz`` and raises ``ValueError`` (→
-        400) on a malformed date. Projects accept BOTH repeated
+        400) on a malformed date. Projects AND models accept BOTH repeated
         ``?projects=a&projects=b`` and a single comma-joined ``?projects=a,b``.
         """
         def _float(name):
@@ -8806,6 +9045,15 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         if projects and len(projects) == 1 and "," in projects[0]:
             projects = [s for s in projects[0].split(",") if s] or None
 
+        # #278 Theme C: the model-family axis, mirroring projects. Accepts both
+        # repeated ?models=opus&models=sonnet and a single comma-joined
+        # ?models=opus,sonnet; blank/empty -> None. No numeric validation (enum-ish
+        # strings); an unknown/typo'd family is a PRESENT axis that resolves to
+        # zero ids in _model_clause -> zero results, never a silent unrestrict.
+        models = [m for m in q.get("models", []) if m] or None
+        if models and len(models) == 1 and "," in models[0]:
+            models = [s for s in models[0].split(",") if s] or None
+
         date_from = _qs_str(q, "date_from", "") or None
         date_to = _qs_str(q, "date_to", "") or None
         if date_from or date_to:
@@ -8832,6 +9080,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             "cost_min": cost_min,
             "cost_max": cost_max,
             "rebuild_min": rebuild_min,
+            "models": models,
         }
 
     def _handle_get_conversations(self) -> None:
@@ -8972,6 +9221,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     self.wfile.write(b": keep-alive\n\n")
                     self.wfile.flush()
 
+            # #278 Theme B: signal that this connection is ACTIVELY live-tailing
+            # (not degraded to keep-alive). The client sets `live` only on this, so
+            # passive/cache-open-failed streams fall back to the memo-backed global
+            # tick instead of stranding updates (Codex F4). Passive branch above
+            # emits only ': keep-alive', so 'ready' is unambiguous.
+            self.wfile.write(b"event: ready\ndata: {}\n\n")
+            self.wfile.flush()
+
             files = _resolve()
             # Best-effort connect ingest for immediacy, then baseline `seen`
             # from the cache's own offsets (session_files) so any pre-connect
@@ -9824,24 +10081,93 @@ def _dashboard_wait_for_signal(
 
 
 def _dashboard_initial_snapshot(args, *, pinned_now, display_tz_pref_override):
-    """#179: build the dashboard's first snapshot WITHOUT the heavy sync so the
-    HTTP port binds promptly. The background ``_DashboardSyncThread`` (started in
-    cmd_dashboard before the ThreadingHTTPServer bind) runs the first full
-    ``sync_cache`` — including any pending conversation reingest — and SSE-pushes
-    the populated snapshot on completion. ``--no-sync`` already passed
-    ``skip_sync=True`` here, so that path is byte-identical; only the normal launch
-    changes (its previously-redundant foreground sync is removed, not duplicated —
-    the background thread's first tick was always going to sync anyway)."""
-    return sys.modules["cctally"]._tui_build_snapshot(
-        now_utc=pinned_now, skip_sync=True,
-        display_tz_pref_override=display_tz_pref_override,
-        # #268 M4: precompute doctor / config / update-state on the initial
-        # snapshot too, so the envelope is pure from the very first paint AND
-        # under --no-sync (where no later sync tick would set them). One
-        # `security` fork here is negligible next to the heavy sync #179 moved
-        # to the background thread. ``getattr`` so minimal test ``args``
-        # namespaces (no ``host``) still build an initial snapshot.
-        precompute_envelope=True, runtime_bind=getattr(args, "host", None),
+    """#278 Theme A (A1): build the dashboard's first snapshot as a CHEAP
+    partial on a normal launch so the HTTP port binds in ~110ms instead of
+    waiting on the ~2.2s full aggregation. #179 already deferred the *ingest*
+    half of cold start (the background ``_DashboardSyncThread`` owns
+    ``sync_cache``); this defers the *aggregation* half too.
+
+    Normal launch (``not args.no_sync``): populate only the two sub-ms headline
+    panels — ``current_week`` + ``forecast`` — plus the real doctor +
+    envelope-config precompute, and set ``hydrating=True``; every heavy panel
+    stays at its empty default. The background thread's first tick runs the
+    full cold build + SSE-publish, and the client hydrates the heavy panels
+    from that frame. Built via the INDIVIDUAL builder helpers, NOT
+    ``_tui_build_snapshot`` — so it never calls ``store_dispatch_state`` and
+    never poisons the idle memo / accelerator caches (§1.1): the dispatch memo
+    stays empty, so the first background tick sees ``prior_key=None`` →
+    non-idle → a full cold build, and idle-reuse can never serve the partial.
+    ``_tui_build_current_week`` / ``_tui_build_forecast_view`` touch no
+    process-local cache state with their default args (Codex P3), so the seed
+    leaves every accelerator pristine.
+
+    ``--no-sync`` (§1.2): there is no background thread to fill the partial in,
+    so the cheap seed would become the PERMANENT state (heavy panels never
+    populate). Keep the full pre-bind build (``hydrating=False``) — a ~2s bind
+    in niche frozen-data mode is acceptable since nothing hydrates later.
+
+    §1.3: ``snapshot_to_envelope`` runs the REAL doctor inline PER CONNECTION
+    when ``doctor_payload is None`` and KeyErrors on an ``envelope_precompute``
+    missing ``"config"`` / the update fields, so a None-doctor seed would be
+    WRONG (worse: every SSE client's first serialization would re-run doctor).
+    The seed therefore runs BOTH precomputes for real (~110ms total). ``getattr``
+    so minimal test ``args`` namespaces (no ``host`` / ``no_sync``) still build.
+    """
+    c = _cctally()
+    tui = c._cctally_tui
+    if getattr(args, "no_sync", False):
+        # Route _tui_build_snapshot through the cctally module (its re-export)
+        # so ``monkeypatch.setitem(ns, "_tui_build_snapshot", spy)`` in tests
+        # propagates — identical to the pre-change call form.
+        return c._tui_build_snapshot(
+            now_utc=pinned_now, skip_sync=True,
+            display_tz_pref_override=display_tz_pref_override,
+            precompute_envelope=True, runtime_bind=getattr(args, "host", None),
+        )
+
+    import time as _time
+    now_utc = pinned_now or dt.datetime.now(dt.timezone.utc)
+    runtime_bind = getattr(args, "host", None)
+    base = tui._tui_empty_snapshot(now_utc)
+    errors: list[str] = []
+    cw = None
+    fc = None
+    fc_view = None
+    conn = open_db()
+    try:
+        try:
+            cw = tui._tui_build_current_week(conn, now_utc, skip_sync=True)
+        except Exception as exc:  # noqa: BLE001 — never block the bind
+            errors.append(f"current-week: {exc}")
+        try:
+            fc_view = tui._tui_build_forecast_view(conn, now_utc, skip_sync=True)
+            fc = fc_view.output if fc_view is not None else None
+        except Exception as exc:  # noqa: BLE001
+            errors.append(f"forecast: {exc}")
+    finally:
+        conn.close()
+    # §1.3: run BOTH precomputes for real so the envelope serializes cleanly
+    # without the per-connection inline-doctor fork or the config/update KeyErrors.
+    doctor_payload = None
+    envelope_precompute = None
+    try:
+        envelope_precompute = tui._tui_precompute_envelope_config(load_config())
+    except Exception as exc:  # noqa: BLE001
+        errors.append(f"envelope-precompute: {exc}")
+    try:
+        doctor_payload = tui._tui_precompute_doctor_payload(now_utc, runtime_bind)
+    except Exception as exc:  # noqa: BLE001
+        errors.append(f"doctor-precompute: {exc}")
+    return dataclasses.replace(
+        base,
+        current_week=cw,
+        forecast=fc,
+        forecast_view=fc_view,
+        last_sync_at=_time.monotonic(),
+        last_sync_error=("; ".join(errors) if errors else None),
+        doctor_payload=doctor_payload,
+        envelope_precompute=envelope_precompute,
+        hydrating=True,
     )
 
 

package/bin/_cctally_doctor.py

@@ -416,6 +416,26 @@ def doctor_gather_state(
     except (json.JSONDecodeError, OSError):
         pass
 
+    # ── Telemetry (anonymous install-count, spec 2026-07-07) ─────────
+    # Resolve the opt-out state via the pure kernel predicate — it reads env
+    # + config + the dev-checkout fact and NEVER mints an install_id / touches
+    # any marker (read-only H1 invariant). Uses the same raw config read as the
+    # safety block so doctor never auto-creates config.json; a missing/corrupt
+    # config degrades to `{}` (env/dev precedence still resolves correctly).
+    telemetry_enabled = True
+    telemetry_reason = "enabled"
+    try:
+        raw_tele_cfg: dict = {}
+        if _cctally_core.CONFIG_PATH.exists():
+            loaded = json.loads(_cctally_core.CONFIG_PATH.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                raw_tele_cfg = loaded
+        telemetry_enabled, telemetry_reason = c.resolve_telemetry_state(raw_tele_cfg)
+    except Exception:
+        # Fail-soft: any read/parse/resolution error degrades to the enabled
+        # default (the check renders OK regardless — it never FAILs/WARNs).
+        telemetry_enabled, telemetry_reason = (True, "enabled")
+
     # config.json — RAW READ, never load_config(). load_config()
     # auto-creates on first run AND silently falls back to defaults
     # on corruption — both behaviors would hide diagnostic state
@@ -518,6 +538,10 @@ def doctor_gather_state(
         is_dev_checkout=_cctally_core._is_dev_checkout(),
         # Preview channel (CCTALLY_CHANNEL=preview): surfaced in install.mode.
         channel=("preview" if _cctally_core.is_preview_channel() else "prod"),
+        # Anonymous install-count telemetry (spec 2026-07-07): read-only
+        # opt-out state, resolved above without minting an install_id.
+        telemetry_enabled=telemetry_enabled,
+        telemetry_reason=telemetry_reason,
         # Pricing-freshness check (spec §5.1): trailing-30d coverage gaps.
         pricing_coverage=pricing_coverage,
         # Conversation-sessions rollup consistency (#217 S1 / U9).

package/bin/_cctally_parser.py

@@ -2225,6 +2225,47 @@ def build_parser() -> argparse.ArgumentParser:
     cfg_unset.add_argument("key", help="Config key")
     cfg_unset.set_defaults(func=c.cmd_config)
 
+    # ---- telemetry (anonymous install-count opt-out, spec 2026-07-07) ----
+    tele_p = sub.add_parser(
+        "telemetry",
+        help="Show or change anonymous install-count telemetry",
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent("""\
+            Anonymous install-count telemetry: what it sends, and how to opt out.
+
+            cctally sends, at most once a day, a minimal beat: a one-way
+            month-rotating token (never your install id), the client version,
+            and a coarse OS family (macos/linux/windows/other). No IP, no
+            username, no paths, no session content ever leaves the machine.
+
+            Actions:
+              (none)   Show the current state, resolved reason, what gets sent,
+                       and the token that would be used this month.
+              on       Enable telemetry (sets telemetry.enabled = true).
+              off      Disable telemetry (sets telemetry.enabled = false).
+              reset    Discard the local install id and mint a fresh one.
+
+            It is also disabled by CCTALLY_DISABLE_TELEMETRY=1, the DO_NOT_TRACK
+            convention, and in dev checkouts.
+
+            Examples:
+              cctally telemetry
+              cctally telemetry --json
+              cctally telemetry off
+              cctally telemetry on
+              cctally telemetry reset
+        """),
+    )
+    tele_p.add_argument(
+        "action", nargs="?", choices=("on", "off", "reset"),
+        help="on|off|reset (omit to show current status).",
+    )
+    tele_p.add_argument(
+        "--json", dest="json", action="store_true",
+        help="Emit the status as JSON (status output only).",
+    )
+    tele_p.set_defaults(func=c.cmd_telemetry)
+
     # ---- alerts (threshold-actions Task 6) ----
     p_alerts = sub.add_parser(
         "alerts",
@@ -2649,6 +2690,26 @@ def build_parser() -> argparse.ArgumentParser:
     )
     uc.set_defaults(func=c.cmd_update_check_internal)
 
+    # ---- _telemetry-beat (internal — hidden, detached anonymous install-count worker) ----
+    tb = sub.add_parser(
+        "_telemetry-beat",
+        help=argparse.SUPPRESS,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Internal subcommand: detached anonymous install-count beat
+            worker, spawned broad-but-throttled from
+            `_post_command_update_hooks` (spec 2026-07-07). A dedicated
+            worker, decoupled from `_update-check` — it touches only the
+            telemetry markers, never update-check state. Honours every
+            opt-out (CCTALLY_DISABLE_TELEMETRY / DO_NOT_TRACK / config /
+            dev checkout) via `resolve_telemetry_state`. Always returns 0;
+            failures are swallowed.
+            """
+        ),
+    )
+    tb.set_defaults(func=c.cmd_telemetry_beat_internal)
+
     # ---- repair-symlinks (internal — hidden; npm-postinstall self-heal, issue #114) ----
     rs = sub.add_parser(
         "repair-symlinks",

package/bin/_cctally_setup.py

@@ -2138,7 +2138,25 @@ def _setup_install(args: argparse.Namespace) -> int:
     out.append("    cctally tui                # terminal dashboard")
     out.append("    cctally setup --status     # verify install state")
 
+    # Install-time telemetry disclosure (spec 2026-07-07 §4). Text summary
+    # only — the --json envelope carries a structured `telemetry` field
+    # instead (never prose). Shown unconditionally as a factual disclosure of
+    # the on-by-default, opt-out install-count beat; the opt-out command +
+    # docs link are always surfaced so the fact is discoverable even when the
+    # interactive first-run notice never fires (headless / statusline-only).
+    out.append("")
+    out.append("cctally counts anonymous active installs to gauge real usage.")
+    out.append("What's sent: a rotating, un-linkable token + version + OS family.")
+    out.append("No identity, no paths, no usage data, no IP stored. Auto-expires monthly.")
+    out.append("Opt out anytime:  cctally telemetry off   (or CCTALLY_DISABLE_TELEMETRY=1)")
+    out.append("How it works:     https://github.com/omrikais/cctally/blob/main/docs/telemetry.md")
+
     if getattr(args, "json", False):
+        # JSON-safe telemetry disclosure (spec 2026-07-07 §4): a structured
+        # field, never prose. Resolved READ-ONLY via `resolve_telemetry_state`
+        # (side-effect-free — mints no install_id, writes no config), so the
+        # envelope reports the opt-out state without arming telemetry.
+        tele_enabled, tele_reason = c.resolve_telemetry_state(c.load_config())
         envelope = {
             "schema_version": 1,
             "mode": "install",
@@ -2174,6 +2192,10 @@ def _setup_install(args: argparse.Namespace) -> int:
                 "session_cache_rows": bootstrap_rows,
                 "oauth_status": bootstrap_oauth_status,
             },
+            "telemetry": {
+                "enabled": tele_enabled,
+                "reason": tele_reason,
+            },
             "warnings_count": warnings,
             "exit_code": 0,
         }