cctally 1.63.0 → 1.65.0

package/bin/_lib_doctor.py

@@ -169,6 +169,14 @@ class DoctorState:
     # from the env; surfaced in the install.mode check. Defaulted (placed last)
     # so existing constructors stay valid and the prod path is unchanged.
     channel: str = "prod"
+    # Anonymous install-count telemetry (spec 2026-07-07): the resolved opt-out
+    # state + precedence reason from `resolve_telemetry_state`, computed by
+    # `doctor_gather_state` WITHOUT minting an install_id (read-only H1). Drives
+    # the always-OK `telemetry.state` check — a diagnostic surface, never a
+    # health failure. Defaulted (placed last) so existing constructors stay
+    # valid and default to the enabled (opt-out) posture.
+    telemetry_enabled: bool = True
+    telemetry_reason: str = "enabled"
 
 
 @dataclasses.dataclass(frozen=True)
@@ -1178,6 +1186,27 @@ def _check_safety_update_available(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_telemetry(s: DoctorState) -> CheckResult:
+    """Anonymous install-count telemetry opt-out state (spec 2026-07-07).
+
+    A read-only DIAGNOSTIC surface — "is telemetry on, and if off, why" — that
+    is ALWAYS ``ok``, never WARN/FAIL. Being disabled (env kill switch,
+    DO_NOT_TRACK, a dev checkout, or ``telemetry.enabled = false``) is a valid
+    user choice, not a health problem, so this check must never change doctor's
+    severity counts or exit code. The gather layer resolves `enabled`/`reason`
+    via `resolve_telemetry_state` WITHOUT minting an install_id.
+    """
+    enabled = bool(s.telemetry_enabled)
+    reason = s.telemetry_reason
+    return CheckResult(
+        id="telemetry.state", title="State",
+        severity="ok",
+        summary=f"{'enabled' if enabled else 'disabled'} ({reason})",
+        remediation=None,
+        details={"enabled": enabled, "reason": reason},
+    )
+
+
 # Each entry is (category_id, category_title, ((check_id, evaluator_fn_name), ...)).
 # The dotted check_id is the stable JSON-contract ID (spec §5.2) AND the
 # fingerprint identity-slice key (spec §5.5). When an evaluator raises,
@@ -1226,6 +1255,9 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("safety.update_suppress", "_check_safety_update_suppress"),
         ("safety.update_available", "_check_safety_update_available"),
     )),
+    ("telemetry", "Telemetry", (
+        ("telemetry.state", "_check_telemetry"),
+    )),
 )
 
 

package/bin/_lib_perf.py

@@ -0,0 +1,180 @@
+"""Opt-in backend phase-instrumentation collector (issue #276, Session A).
+
+Stdlib-only. A thread-local nested-phase timing collector, gated on the
+CCTALLY_PERF_TRACE env var. Near-noop when off: phase() returns a shared
+_NULL_PHASE singleton — no allocation, no perf_counter, no stack push.
+
+Two renderers sit on the same phase tree:
+  * flush_stderr(root)  — CLI indented outline (stdout stays byte-identical).
+  * stash_last(root)    — the dashboard freezes the completed tree (to_dict)
+                          into a process-global slot for the loopback
+                          /api/debug/backend endpoint to read.
+
+This surface is a diagnostic, NOT a consumer contract: phase names, nesting,
+and fields may change without a version bump.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+
+_FALSEY = {"", "0", "false", "no", "off"}
+_ENABLED = os.environ.get("CCTALLY_PERF_TRACE", "").strip().lower() not in _FALSEY
+
+
+def enabled() -> bool:
+    return _ENABLED
+
+
+def set_enabled(value: bool) -> None:
+    """Flip tracing at runtime (tests; not used by the dashboard, which reads
+    the env at import time)."""
+    global _ENABLED
+    _ENABLED = bool(value)
+
+
+_tls = threading.local()
+
+
+def _stack():
+    s = getattr(_tls, "stack", None)
+    if s is None:
+        s = []
+        _tls.stack = s
+    return s
+
+
+class Phase:
+    __slots__ = ("name", "elapsed_ms", "count", "meta", "children", "_start", "_stack")
+
+    def __init__(self, name, stack):
+        self.name = name
+        self.elapsed_ms = 0.0
+        self.count = None
+        self.meta = None
+        self.children = []
+        self._start = 0.0
+        self._stack = stack
+
+    def set_count(self, n):
+        self.count = int(n)
+
+    def set_meta(self, **kw):
+        if self.meta is None:
+            self.meta = {}
+        self.meta.update(kw)
+
+    def __enter__(self):
+        self._start = time.perf_counter()
+        self._stack.append(self)
+        return self
+
+    def __exit__(self, *exc):
+        self.elapsed_ms = (time.perf_counter() - self._start) * 1000.0
+        # Identity-aware unwind. If a nested phase leaked (its __exit__ was
+        # skipped — e.g. an exception escaped a manually CM-bracketed region),
+        # drop the leaked frames sitting above us so we never append a phase to
+        # its OWN children (which would make to_dict() self-recurse) and never
+        # strand a stack that hides the real root. Pop down to and including
+        # self; if self is not on the stack (double __exit__, or an ancestor
+        # already unwound us), do nothing.
+        stack = self._stack
+        if self not in stack:
+            return False
+        while stack and stack[-1] is not self:
+            stack.pop()               # discard a leaked descendant frame
+        stack.pop()                   # pop self
+        if stack:
+            stack[-1].children.append(self)
+        else:
+            _tls.root = self          # outermost phase closed -> the build root
+        return False
+
+    def to_dict(self):
+        d = {"name": self.name, "elapsed_ms": round(self.elapsed_ms, 3)}
+        if self.count is not None:
+            d["count"] = self.count
+        if self.meta:
+            d["meta"] = dict(self.meta)
+        if self.children:
+            d["children"] = [c.to_dict() for c in self.children]
+        return d
+
+
+class _NullPhase:
+    """Shared no-op returned when tracing is off. No allocation per phase()."""
+
+    def set_count(self, n):
+        pass
+
+    def set_meta(self, **kw):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+_NULL_PHASE = _NullPhase()
+
+
+def phase(name):
+    if not _ENABLED:
+        return _NULL_PHASE
+    return Phase(name, _stack())
+
+
+def current_root():
+    return getattr(_tls, "root", None)
+
+
+def reset_thread():
+    _tls.stack = []
+    _tls.root = None
+
+
+def flush_stderr(root):
+    if root is None:
+        return
+    lines = []
+
+    def walk(p, depth):
+        indent = "  " * depth
+        extra = ""
+        if p.count is not None:
+            extra += f"  (count={p.count})"
+        if p.meta:
+            extra += "  " + " ".join(f"{k}={v}" for k, v in p.meta.items())
+        lines.append(f"{indent}{p.name}  {p.elapsed_ms:.1f}ms{extra}")
+        for c in p.children:
+            walk(c, depth + 1)
+
+    walk(root, 0)
+    sys.stderr.write("backend-perf:\n" + "\n".join(lines) + "\n")
+
+
+# ── process-global last-completed-tree slot (dashboard -> endpoint) ──────────
+# The writer freezes the tree with to_dict() then binds the module global in
+# ONE statement; once bound the dict is never mutated (the next build binds a
+# fresh dict). Assignment is atomic under the GIL, so the HTTP reader thread
+# always sees a whole, immutable "last completed build".
+_LAST_BACKEND_PERF = None
+
+
+def stash_last(root, *, generation=None, generated_at=None):
+    global _LAST_BACKEND_PERF
+    if root is None:
+        return
+    _LAST_BACKEND_PERF = {
+        "generated_at": generated_at,
+        "generation": generation,
+        "phases": root.to_dict(),
+    }
+
+
+def last_backend_perf():
+    return _LAST_BACKEND_PERF

package/bin/_lib_transcript_access.py

@@ -55,6 +55,29 @@ def is_loopback(host: str) -> bool:
         return False
 
 
+def debug_backend_allowed(peer_ip, host) -> bool:
+    """Gate for the loopback-only ``/api/debug/backend`` diagnostic endpoint
+    (issue #276, Session A).
+
+    STRICTER than the transcript gate — it never opens to the LAN. Two checks:
+
+      * PRIMARY: the TCP peer (``client_address[0]``) must be a loopback
+        literal. This is the unspoofable signal — the dashboard can bind
+        ``0.0.0.0`` (``dashboard.bind = lan``), and a ``Host``-header-only
+        check would let a LAN client connect to the LAN socket while sending
+        ``Host: 127.0.0.1``. The peer address cannot be spoofed that way.
+      * DEFENSE-IN-DEPTH: the ``Host`` authority must ALSO be an IP-literal
+        loopback (anti-DNS-rebinding) — a hostname ``Host`` (a rebinding
+        vector) is rejected even from a loopback peer.
+
+    ``dashboard.expose_transcripts`` is NEVER consulted — this surface is
+    loopback-only, ALWAYS. Fail closed on a missing/empty peer or Host.
+    """
+    if not is_loopback(peer_ip):
+        return False
+    return is_loopback(authority_host(host))
+
+
 def transcripts_allowed(bind_host, expose: bool) -> bool:
     """Are transcripts served AT ALL on this bind? Loopback bind always; a
     non-loopback (LAN) bind only under the explicit ``expose`` opt-in."""

package/bin/cctally

@@ -214,6 +214,10 @@ make_week_ref = _cctally_core.make_week_ref
 _get_latest_row_for_week = _cctally_core._get_latest_row_for_week
 _reset_aware_floor = _cctally_core._reset_aware_floor
 get_latest_usage_for_week = _cctally_core.get_latest_usage_for_week
+# Re-exported so the telemetry kernel's ``c._is_dev_checkout()`` accessor
+# call resolves on the ``cctally`` module (and tests can monkeypatch it
+# there). The canonical definition lives in _cctally_core.
+_is_dev_checkout = _cctally_core._is_dev_checkout
 
 # === Path constants — re-exported from _cctally_core ================
 #
@@ -982,6 +986,8 @@ _is_update_check_due = _cctally_update._is_update_check_due
 _do_update_check = _cctally_update._do_update_check
 _spawn_background_update_check = _cctally_update._spawn_background_update_check
 cmd_update_check_internal = _cctally_update.cmd_update_check_internal
+_spawn_background_telemetry_beat = _cctally_update._spawn_background_telemetry_beat
+cmd_telemetry_beat_internal = _cctally_update.cmd_telemetry_beat_internal
 SKIP_USE_STATE_LATEST = _cctally_update.SKIP_USE_STATE_LATEST
 _format_update_command = _cctally_update._format_update_command
 _prerelease_note = _cctally_update._prerelease_note
@@ -1009,6 +1015,36 @@ _should_show_update_banner = _cctally_update._should_show_update_banner
 _format_update_banner = _cctally_update._format_update_banner
 
 
+# Anonymous install-count telemetry kernel (spec 2026-07-07). Eagerly
+# re-exported so tests reach the pure functions via the ``cctally``
+# namespace (mirroring the ``_check_npm_latest_version`` re-export above)
+# and so the kernel's moved bodies that call ``c.resolve_client_version``
+# / ``c.resolve_os_family`` / ``c._release_read_latest_release_version``
+# through the ``_cctally()`` accessor pick up any test monkeypatch on the
+# cctally module. Path constants (TELEMETRY_INSTALL_ID_PATH etc.) live on
+# _cctally_core and are read via ``_core()`` at call time; tests patch
+# them through ``monkeypatch.setattr(_cctally_core, "X", v)`` (conftest's
+# ``redirect_paths()`` covers the set).
+_cctally_telemetry = _load_sibling("_cctally_telemetry")
+resolve_telemetry_state = _cctally_telemetry.resolve_telemetry_state
+telemetry_token = _cctally_telemetry.telemetry_token
+current_period = _cctally_telemetry.current_period
+resolve_client_version = _cctally_telemetry.resolve_client_version
+resolve_os_family = _cctally_telemetry.resolve_os_family
+build_beat_payload = _cctally_telemetry.build_beat_payload
+read_install_id = _cctally_telemetry.read_install_id
+ensure_install_id = _cctally_telemetry.ensure_install_id
+reset_install_id = _cctally_telemetry.reset_install_id
+do_telemetry_beat = _cctally_telemetry.do_telemetry_beat
+telemetry_beat_due = _cctally_telemetry.telemetry_beat_due
+first_beat_grace_elapsed = _cctally_telemetry.first_beat_grace_elapsed
+mark_first_seen = _cctally_telemetry.mark_first_seen
+touch_last_beat = _cctally_telemetry.touch_last_beat
+notice_already_shown = _cctally_telemetry.notice_already_shown
+mark_notice_shown = _cctally_telemetry.mark_notice_shown
+cmd_telemetry = _cctally_telemetry.cmd_telemetry
+
+
 # Phase F #22: ``bin/_cctally_dashboard.py`` is loaded eagerly per spec §4.8
 # carve-out — ``tests/test_dashboard_*.py`` and ``tests/test_share_*.py``
 # reach into ~25 dashboard symbols via ``ns["X"]`` direct-dict reads and
@@ -2853,6 +2889,20 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         # (it runs before the wrapper sets CCTALLY_DATA_DIR, so APP_DIR is
         # still cctally-dev at this point). Same rationale class as doctor.
         return
+    if command in ("_update-check", "_telemetry-beat"):
+        # Both hidden workers are detached and have already done their one job
+        # in their own command handler; neither must re-enter this hook.
+        # Without the guard the ``_update-check`` worker would fall through to
+        # the telemetry gate below and (throttle-bounded) spawn a
+        # ``_telemetry-beat`` — a worker spawning another worker. And
+        # ``do_telemetry_beat`` stamps its throttle marker FIRST on every
+        # non-disabled run (arm/grace/sent/failed), so ``telemetry_beat_due()``
+        # already reads False right after a worker run and the parent gate is
+        # bounded to <=1 spawn/window regardless — this early-return is the
+        # belt-and-suspenders that keeps the two dedicated workers symmetric
+        # and fully hook-free (an internal worker never needs banners or
+        # background spawns anyway).
+        return
     # Self-heal: reconcile current_version with the running binary's
     # CHANGELOG. Cheap (one CHANGELOG read, write only on the first
     # command after a manual upgrade). Runs before load_config so a
@@ -2865,6 +2915,54 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         sys.stderr.write(_format_update_banner(state) + "\n")
     if _is_update_check_due(config):
         _spawn_background_update_check()
+    # Anonymous install-count telemetry (spec 2026-07-07). Broad-but-
+    # throttled, placed after the same early-returns that guard the update
+    # check so it inherits every side-effect skip (read-only/no-mutation
+    # commands, the CCTALLY_DISABLE_UPDATE_CHECK test seam, and the
+    # ``_telemetry-beat`` self-re-entry guard above). The env kill switches
+    # (CCTALLY_DISABLE_TELEMETRY / DO_NOT_TRACK), the config opt-out, and
+    # the dev-checkout guard all live inside ``resolve_telemetry_state`` —
+    # do not re-check them here.
+    enabled, _reason = resolve_telemetry_state(config)
+    if enabled and telemetry_beat_due():
+        _spawn_background_telemetry_beat()
+    _maybe_print_telemetry_notice(command, config)
+
+
+def _maybe_print_telemetry_notice(command: str | None, config) -> None:
+    """One-time interactive notice that anonymous install-count telemetry
+    is active (spec review finding #2). Banner-gated (NOT beat-gated): it
+    prints once to an interactive stderr and, once marked, never again.
+    Fully best-effort — the whole body is wrapped so any failure is
+    swallowed and can't perturb the parent command.
+
+    Gates (all must hold to print):
+      - telemetry enabled (opt-outs / config / dev-checkout suppress it);
+      - not already shown (the ``TELEMETRY_NOTICE_SHOWN`` marker);
+      - command not in ``_BANNER_SUPPRESSED_COMMANDS`` — the same quiet
+        set the update banner honours (record-usage / hook-tick / blocks /
+        etc.), so machine-consumed one-liners stay clean;
+      - stderr is a real TTY — never pollute piped or redirected output.
+    """
+    try:
+        enabled, _reason = resolve_telemetry_state(config)
+        if not enabled or notice_already_shown():
+            return
+        if command in _BANNER_SUPPRESSED_COMMANDS:
+            return
+        if not (sys.stderr and sys.stderr.isatty()):
+            return
+        docs = "https://github.com/omrikais/cctally/blob/main/docs/telemetry.md"
+        sys.stderr.write(
+            "cctally counts anonymous active installs to gauge real usage.\n"
+            "What's sent: a rotating, un-linkable token + version + OS family.\n"
+            "No identity, no paths, no usage data, no IP stored. Auto-expires monthly.\n"
+            "Opt out anytime:  cctally telemetry off   (or CCTALLY_DISABLE_TELEMETRY=1)\n"
+            f"How it works:     {docs}\n"
+        )
+        mark_notice_shown()
+    except Exception:
+        pass
 
 
 if __name__ == "__main__":

package/bin/cctally-npm-postinstall.js

@@ -36,5 +36,9 @@ process.stdout.write(
   '  cctally setup\n' +
   '\nThis installs additive Claude Code hooks (~/.claude/settings.json)\n' +
   'and bootstraps the local SQLite cache (~/.local/share/cctally/).\n' +
+  '\ncctally counts anonymous active installs (a rotating monthly token +\n' +
+  'version + OS family; no identity, paths, or usage data). Opt out with\n' +
+  '`cctally telemetry off`, CCTALLY_DISABLE_TELEMETRY=1, or DO_NOT_TRACK=1.\n' +
+  'How it works: https://github.com/omrikais/cctally/blob/main/docs/telemetry.md\n' +
   '\nDetails: https://github.com/omrikais/cctally#installation\n\n'
 );