cctally 1.4.0 → 1.5.0

package/bin/cctally

@@ -30,9 +30,11 @@ import dataclasses
 import datetime as dt
 import fcntl
 import hashlib
+import io
 import json
 import os
 import pathlib
+import queue
 import re
 import secrets
 import math
@@ -42,6 +44,7 @@ import sqlite3
 import subprocess
 import tempfile
 import textwrap
+import threading
 import time
 import traceback
 import urllib.error
@@ -76,6 +79,7 @@ SETUP_SYMLINK_NAMES = (
     "cctally-release",
     "cctally-sync-week",
     "cctally-tui",
+    "cctally-update",
 )
 
 # Hook events we register entries for (Section 1 of spec).
@@ -216,6 +220,43 @@ def _release_read_latest_release_version() -> tuple[str, str] | None:
     return (m.group(1), m.group(2))
 
 
+_FORMULA_VERSION_RE = re.compile(
+    rf'/v({_SEMVER_NUM}\.{_SEMVER_NUM}\.{_SEMVER_NUM}'
+    rf'(?:-[a-zA-Z][a-zA-Z0-9-]*\.{_SEMVER_NUM})?)\.tar\.gz'
+)
+
+
+def _release_extract_formula_version(text: str) -> str | None:
+    """Extract the SemVer string from a homebrew formula's archive URL.
+
+    Returns the matched version (e.g. `"1.3.0"`, `"1.0.0-rc.1"`) or
+    ``None`` if no `/vX.Y.Z[.tar.gz]` substring is found. Used by Phase 6's
+    monotonic-version gate (issue #30) — the gate refuses to write a lower
+    version on top of a higher one. A formula that does not match is
+    treated as unversioned (gate allows the write).
+    """
+    m = _FORMULA_VERSION_RE.search(text)
+    return m.group(1) if m else None
+
+
+def _release_semver_sort_key(
+    parsed: tuple[int, int, int, str | None, int | None],
+) -> tuple:
+    """Total-order sort key for `_release_parse_semver` output.
+
+    SemVer §11.4: a stable release has higher precedence than a pre-release
+    of the same MAJOR.MINOR.PATCH. Naive tuple comparison breaks because
+    Python rejects ``None < str`` at runtime. The key returned here makes
+    stable releases sort *after* their pre-releases by inverting the
+    "has-prerelease" axis: stable → ``(maj, min, pat, 1, "", 0)``,
+    pre-release → ``(maj, min, pat, 0, id, n)``.
+    """
+    maj, min_, pat, pre_id, pre_n = parsed
+    if pre_id is None:
+        return (maj, min_, pat, 1, "", 0)
+    return (maj, min_, pat, 0, pre_id, pre_n)
+
+
 def _release_brew_archive_url(version: str) -> str:
     """Return the GitHub auto-archive URL for a version tag.
 
@@ -1537,6 +1578,7 @@ def _release_run_phase_npm(
 def _release_run_phase_brew(
     version: str,
     brew_clone: pathlib.Path | None,
+    allow_downgrade: bool = False,
 ) -> int:
     """Phase 6 — render ``Formula/cctally.rb`` and push to the brew tap.
 
@@ -1551,6 +1593,13 @@ def _release_run_phase_brew(
         version (idempotency under ``--resume``).
       - Dirty working tree — refuses with exit 2 and points the operator
         at ``--resume``.
+      - **Monotonic-version gate (issue #30).** Refuses with exit 2 when
+        the existing on-disk formula's URL pins a *higher* SemVer than
+        ``version``. Catches the f02b2f1 regression class — operator
+        runs Phase 6 from a stale CHANGELOG / fixture leak / accidental
+        old branch and would otherwise silently write a lower version
+        over a higher one. Override via ``allow_downgrade=True``
+        (operator-driven, for genuine yank/revert cases).
       - Push failure — auth-fallback parity with Phase 4: prints the
         exact recovery command and returns 0. Phases 1-5 already
         succeeded, the release IS published from the user's
@@ -1560,7 +1609,7 @@ def _release_run_phase_brew(
     Returns:
       - ``0`` on success, graceful skip, idempotent short-circuit, OR
         push fallback.
-      - ``2`` on dirty-working-tree refusal.
+      - ``2`` on dirty-working-tree refusal OR downgrade-gate refusal.
     """
     print("phase 6: brew formula bump")
     if brew_clone is None:
@@ -1610,6 +1659,57 @@ def _release_run_phase_brew(
             f"  local formula already at v{version}; re-pushing to tap…"
         )
     else:
+        # Monotonic-version gate (issue #30). The brew tap regressed
+        # from v1.3.0 → v1.0.0 twice in one day via this code path; the
+        # equality fingerprint above (`local_at_version`) is False on a
+        # downgrade, so without this gate we'd silently overwrite a
+        # higher version. Compare the existing formula's URL-pinned
+        # SemVer against `version` (SemVer-aware so prereleases sort
+        # below their stable counterpart per §11.4); refuse with exit 2
+        # when the on-disk version is strictly higher. Unparseable
+        # formulas are treated as unversioned and allowed through.
+        if formula_path.exists():
+            existing_text = formula_path.read_text(encoding="utf-8")
+            existing_v = _release_extract_formula_version(existing_text)
+            if existing_v is not None:
+                try:
+                    existing_key = _release_semver_sort_key(
+                        _release_parse_semver(existing_v)
+                    )
+                    target_key = _release_semver_sort_key(
+                        _release_parse_semver(version)
+                    )
+                except ValueError:
+                    existing_key = target_key = None
+                if (
+                    existing_key is not None
+                    and target_key is not None
+                    and existing_key > target_key
+                    and not allow_downgrade
+                ):
+                    print(
+                        f"  refuse: existing formula pins v{existing_v}, "
+                        f"target is v{version} (downgrade).\n"
+                        "  Common causes: stale CHANGELOG.md in this clone, "
+                        "fixture leak into a real `release.brewClone`, or an "
+                        "accidental old branch.\n"
+                        "  Verify intent, then re-run with "
+                        "`--allow-formula-downgrade` to override "
+                        "(yank / revert cases). See issue #30.",
+                        file=sys.stderr,
+                    )
+                    return 2
+                if (
+                    existing_key is not None
+                    and target_key is not None
+                    and existing_key > target_key
+                    and allow_downgrade
+                ):
+                    print(
+                        f"  WARNING: writing v{version} over existing v{existing_v} "
+                        "(--allow-formula-downgrade); intentional yank?",
+                        file=sys.stderr,
+                    )
         print(f"  computing sha256 of v{version} archive…")
         sha = _release_compute_brew_sha256(version)
 
@@ -1920,7 +2020,11 @@ def cmd_release(args: argparse.Namespace) -> int:
         print(f"phase 6: brew skipped{suffix}")
     else:
         brew_clone = _release_discover_brew_clone(args)
-        rc = _release_run_phase_brew(next_v, brew_clone)
+        rc = _release_run_phase_brew(
+            next_v,
+            brew_clone,
+            allow_downgrade=args.allow_formula_downgrade,
+        )
         if rc != 0:
             return rc
 
@@ -2069,6 +2173,36 @@ CONFIG_LOCK_PATH = APP_DIR / "config.json.lock"
 LOG_DIR = APP_DIR / "logs"
 MIGRATION_ERROR_LOG_PATH = LOG_DIR / "migration-errors.log"
 
+# === Update subcommand (Section 1 of update-subcommand spec) ===
+# Path constants for the `cctally update` feature. Centralised here
+# (alongside other APP_DIR-derived paths) so the test fixture loader in
+# tests/conftest.py:redirect_paths can monkeypatch them, and so later
+# tasks (install detection, version-check pipeline, dashboard worker)
+# don't have to revisit constant placement.
+UPDATE_STATE_PATH         = APP_DIR / "update-state.json"
+UPDATE_SUPPRESS_PATH      = APP_DIR / "update-suppress.json"
+UPDATE_LOCK_PATH          = APP_DIR / "update.lock"
+UPDATE_LOG_PATH           = APP_DIR / "update.log"
+UPDATE_LOG_ROTATED_PATH   = APP_DIR / "update.log.1"
+UPDATE_LOG_ROTATE_BYTES   = 1024 * 1024  # 1 MB; spec §1.5
+UPDATE_CHECK_LAST_FETCH_PATH = APP_DIR / "update-check.last-fetch"
+
+UPDATE_NPM_REGISTRY_URL = os.environ.get(
+    "CCTALLY_TEST_UPDATE_NPM_URL",
+    "https://registry.npmjs.org/cctally/latest",
+)
+UPDATE_BREW_FORMULA_URL = os.environ.get(
+    "CCTALLY_TEST_UPDATE_BREW_URL",
+    "https://raw.githubusercontent.com/omrikais/homebrew-cctally/main/Formula/cctally.rb",
+)
+
+UPDATE_DEFAULT_TTL_HOURS  = 24
+UPDATE_MAX_TTL_HOURS      = 720    # 30 days
+UPDATE_NETWORK_TIMEOUT_S  = 5.0
+UPDATE_NPM_PREFIX_TIMEOUT_S = 2.0
+UPDATE_NPM_PREFIX_TTL_DAYS  = 7
+UPDATE_DASHBOARD_CHECK_POLL_S = 30 * 60
+
 
 def _migrate_legacy_data_dir() -> None:
     """One-shot: ~/.local/share/ccusage-subscription → ~/.local/share/cctally.
@@ -8698,6 +8832,75 @@ class RefreshUsageMalformedError(Exception):
     required seven_day fields (utilization or resets_at)."""
 
 
+# === `cctally update` exception cluster (spec §1, §3, §5) =================
+# These live near RefreshUsage* because the version-check pipeline (Task 3)
+# is structurally analogous: a single networked refresh that can rate-limit,
+# fail to fetch, or return unparseable bodies. The base class is caught at
+# the command boundary in cmd_update_* (Task 4); subtypes let JSON-mode
+# emit a `check_status` enum value (rate_limited / fetch_failed / etc.) per
+# spec §1.2.
+
+
+class UpdateError(Exception):
+    """User-facing error from the update subcommand. Caught at command boundary.
+
+    Default rc when caught at the boundary is 1 (runtime / environment
+    failure: unknown install method, npm prefix not writable, etc.).
+    Validation errors (invalid --version syntax, --version+brew combo)
+    use the :class:`UpdateValidationError` subclass so the boundary can
+    map them to rc=2 — preserving the rc=1-vs-rc=2 distinction the
+    Task-4 inline gates exposed.
+    """
+
+
+class UpdateValidationError(UpdateError):
+    """Subclass of UpdateError marking input-validation failures (rc=2).
+
+    Two cases per spec §5.1: invalid --version syntax (must match
+    _SEMVER_RE), and --version with method=brew (no versioned formulae).
+    Carved out of UpdateError so cmd_update's try/except can branch on
+    type rather than message — the inline gates that Task 4 used both
+    returned rc=2; preserving that contract is the test invariant.
+    """
+
+
+class UpdateInProgressError(UpdateError):
+    """Another update is already running. Carries the prior PID for the operator
+    message ("Another update is in progress (PID 12345)."). Raised by
+    _acquire_update_lock when a live PID still holds update.lock.
+
+    ``prior_pid`` is ``None`` when the lock body was unparseable (no
+    ``PID=`` line, or non-integer value) — rendered as
+    "(PID unknown)" rather than a sentinel like ``0`` (which is a real
+    PID in POSIX semantics: the kernel scheduler on Linux)."""
+
+    def __init__(self, prior_pid: int | None):
+        if prior_pid is None:
+            super().__init__("Another update is in progress (PID unknown).")
+        else:
+            super().__init__(f"Another update is in progress (PID {prior_pid}).")
+        self.prior_pid = prior_pid
+
+
+class UpdateCheckNetworkError(UpdateError):
+    """DNS / connection / non-rate-limit HTTP failure during version check."""
+
+
+class UpdateCheckRateLimited(UpdateError):
+    """HTTP 429 from npm registry or GitHub raw-content host. Treated as
+    non-error (last-known `latest_version` preserved); banner predicate is
+    still evaluated against the cached value."""
+
+
+class UpdateCheckHTTPError(UpdateError):
+    """Non-200, non-429 HTTP status from a version-check endpoint."""
+
+
+class UpdateCheckParseError(UpdateError):
+    """Endpoint returned a body we couldn't parse (npm JSON missing
+    `version` field, formula ruby missing `version "X.Y.Z"` line)."""
+
+
 @dataclasses.dataclass
 class _RefreshUsageResult:
     """Outcome of a single _refresh_usage_inproc() invocation.
@@ -9206,6 +9409,67 @@ def _normalize_alerts_enabled_value(raw: str) -> bool:
     )
 
 
+# Range bound mirrors `docs/commands/update.md`: 1 hour minimum, 720 hours
+# (= 30 days) maximum. Out-of-range returns ValueError so callers in both
+# the CLI (`_cmd_config_set`) and the dashboard (`_handle_post_settings`)
+# can map to their own exit-code / HTTP-status semantics.
+_UPDATE_CHECK_TTL_HOURS_MIN = 1
+_UPDATE_CHECK_TTL_HOURS_MAX = 720
+
+
+def _normalize_update_check_enabled_value(raw: str) -> bool:
+    """Normalize the CLI string for update.check.enabled. Reuses the
+    alerts.enabled string vocabulary so users don't have to remember a
+    second set of valid words.
+    """
+    try:
+        return _normalize_alerts_enabled_value(raw)
+    except ValueError:
+        # Re-raise with the right key name in the message so the user
+        # sees `update.check.enabled` not `alerts.enabled`.
+        raise ValueError(
+            f"invalid boolean value for update.check.enabled: {raw!r} "
+            "(expected true|false|yes|no|1|0|on|off)"
+        )
+
+
+def _validate_update_check_ttl_hours_value(raw) -> int:
+    """Validate update.check.ttl_hours (int hours). Accepts an int or a
+    string of digits; rejects bools (Python ``True`` is an int subclass
+    so callers pre-validating JSON shapes must NOT pass a bool through
+    here). Range bound: ``[_UPDATE_CHECK_TTL_HOURS_MIN, _MAX]``.
+    """
+    if isinstance(raw, bool):
+        raise ValueError(
+            "invalid value for update.check.ttl_hours: "
+            f"{raw!r} (expected integer in "
+            f"[{_UPDATE_CHECK_TTL_HOURS_MIN}, {_UPDATE_CHECK_TTL_HOURS_MAX}])"
+        )
+    if isinstance(raw, int):
+        n = raw
+    elif isinstance(raw, str):
+        s = raw.strip()
+        try:
+            n = int(s, 10)
+        except ValueError:
+            raise ValueError(
+                f"invalid integer for update.check.ttl_hours: {raw!r}"
+            )
+    else:
+        raise ValueError(
+            "invalid value for update.check.ttl_hours: "
+            f"{raw!r} (expected integer in "
+            f"[{_UPDATE_CHECK_TTL_HOURS_MIN}, {_UPDATE_CHECK_TTL_HOURS_MAX}])"
+        )
+    if n < _UPDATE_CHECK_TTL_HOURS_MIN or n > _UPDATE_CHECK_TTL_HOURS_MAX:
+        raise ValueError(
+            "update.check.ttl_hours out of range: "
+            f"{n} (must be in [{_UPDATE_CHECK_TTL_HOURS_MIN}, "
+            f"{_UPDATE_CHECK_TTL_HOURS_MAX}])"
+        )
+    return n
+
+
 _CONFIG_CORRUPT_WARNED = False  # one-shot warn flag for load_config
 _ALERTS_BAD_CONFIG_WARNED = False  # one-shot warn flag for malformed alerts block
 
@@ -9386,6 +9650,1484 @@ def save_config(data: dict[str, Any]) -> None:
     os.replace(str(tmp), str(CONFIG_PATH))
 
 
+# === update-subcommand state-file / lock / log helpers (spec §1) =========
+# These live next to load_config / save_config because they share the
+# atomic-write idiom (PID-suffixed tmp + os.replace) and the schema-
+# versioned-JSON contract. Kept stdlib-only per the project's zero-dep
+# ethos.
+
+_UPDATE_STATE_SCHEMA_MAX = 1
+_UPDATE_SUPPRESS_SCHEMA_MAX = 1
+
+
+def _load_update_state() -> dict[str, Any] | None:
+    """Read ``update-state.json``. Returns None when the file is absent
+    so callers can distinguish "never checked" from "checked, no update."
+
+    Raises :class:`UpdateError` when ``_schema`` exceeds the highest
+    version this binary knows about — forward-compat invariant from
+    spec §1.7. An older cctally must NOT silently drop fields that a
+    newer cctally wrote (that would invert the suppress-versions list,
+    miss new check_status enum values, etc.).
+
+    JSON-decode errors also raise :class:`UpdateError`; the writer's
+    atomic os.replace guarantees readers never see partial bytes, so a
+    parse failure means the file was already corrupt before our read.
+    """
+    try:
+        text = UPDATE_STATE_PATH.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise UpdateError(f"update-state.json is not valid JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise UpdateError(
+            f"update-state.json must be a JSON object, got {type(data).__name__}"
+        )
+    schema = data.get("_schema", 0)
+    if not isinstance(schema, int) or schema > _UPDATE_STATE_SCHEMA_MAX:
+        raise UpdateError(
+            f"update-state.json has _schema={schema!r}; this cctally is older "
+            f"than the state file. Upgrade cctally."
+        )
+    return data
+
+
+def _save_update_state(state: dict[str, Any]) -> None:
+    """Persist ``update-state.json`` atomically.
+
+    Mirrors :func:`save_config`: PID-suffixed tmp sibling, fsync the
+    bytes, then ``os.replace`` onto the final path. POSIX rename(2) is
+    atomic on the same filesystem, so concurrent readers see either the
+    pre-rename or post-rename contents but never partial bytes.
+    Concurrent writers don't race the bytes themselves but may stomp
+    each other's logical updates — the update subcommand serializes
+    writers via ``UPDATE_LOCK_PATH`` (spec §5.3).
+    """
+    UPDATE_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    payload = (
+        json.dumps(state, indent=2, sort_keys=True) + "\n"
+    ).encode("utf-8")
+    tmp = UPDATE_STATE_PATH.with_name(
+        f"{UPDATE_STATE_PATH.name}.tmp.{os.getpid()}"
+    )
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+    try:
+        os.write(fd, payload)
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    os.replace(str(tmp), str(UPDATE_STATE_PATH))
+
+
+def _load_update_suppress() -> dict[str, Any]:
+    """Read ``update-suppress.json``. Returns a default empty record when
+    the file is absent (spec §1.3) so the banner predicate doesn't have
+    to None-guard every read. Same forward-compat schema check as
+    :func:`_load_update_state`.
+    """
+    default = {"_schema": 1, "skipped_versions": [], "remind_after": None}
+    try:
+        text = UPDATE_SUPPRESS_PATH.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return default
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise UpdateError(
+            f"update-suppress.json is not valid JSON: {e}"
+        ) from e
+    if not isinstance(data, dict):
+        raise UpdateError(
+            f"update-suppress.json must be a JSON object, got "
+            f"{type(data).__name__}"
+        )
+    schema = data.get("_schema", 0)
+    if not isinstance(schema, int) or schema > _UPDATE_SUPPRESS_SCHEMA_MAX:
+        raise UpdateError(
+            f"update-suppress.json has _schema={schema!r}; this cctally is "
+            f"older than the suppress file. Upgrade cctally."
+        )
+    return data
+
+
+def _save_update_suppress(suppress: dict[str, Any]) -> None:
+    """Persist ``update-suppress.json`` atomically. Same idiom as
+    :func:`_save_update_state`."""
+    UPDATE_SUPPRESS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    payload = (
+        json.dumps(suppress, indent=2, sort_keys=True) + "\n"
+    ).encode("utf-8")
+    tmp = UPDATE_SUPPRESS_PATH.with_name(
+        f"{UPDATE_SUPPRESS_PATH.name}.tmp.{os.getpid()}"
+    )
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+    try:
+        os.write(fd, payload)
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    os.replace(str(tmp), str(UPDATE_SUPPRESS_PATH))
+
+
+def _read_lock_pid(fd: int) -> int | None:
+    """Parse ``PID=<n>`` out of an open update.lock fd. Returns None on
+    any failure (file empty, missing PID line, non-integer value) — the
+    caller treats "unknown holder" the same as a stale lock and
+    attempts a second LOCK_NB acquire."""
+    try:
+        os.lseek(fd, 0, 0)
+        body = os.read(fd, 1024).decode("utf-8")
+    except OSError:
+        return None
+    for line in body.splitlines():
+        if line.startswith("PID="):
+            try:
+                return int(line[4:])
+            except ValueError:
+                return None
+    return None
+
+
+def _acquire_update_lock() -> int:
+    """Acquire the singleton update.lock under spec §5.3 contract.
+
+    Returns the open fd on success. Caller MUST pass the fd to
+    :func:`_release_update_lock` to drop the flock + unlink the file.
+
+    Raises :class:`UpdateInProgressError` when a *live* PID still holds
+    the lock. Stale locks (writer crashed without releasing) are
+    silently reclaimed: ``kill(pid, 0)`` raising ``ProcessLookupError``
+    is the only signal we trust for reclaim — kernel-authoritative,
+    free of read-the-file-then-stat races.
+
+    Body format (text, line-oriented for ``cat update.lock``)::
+
+        PID=12345
+        STARTED_AT_UTC=2026-05-10T13:05:23+00:00
+        COMMAND=cctally update
+    """
+    UPDATE_LOCK_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(
+        str(UPDATE_LOCK_PATH), os.O_CREAT | os.O_RDWR, 0o644
+    )
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        prior = _read_lock_pid(fd)
+        if prior is not None:
+            try:
+                os.kill(prior, 0)
+            except ProcessLookupError:
+                pass  # stale → fall through to reclaim attempt
+            else:
+                # Live PID still holds the lock — refuse.
+                os.close(fd)
+                raise UpdateInProgressError(prior)
+        # Stale (or unparseable PID): retry the non-blocking acquire.
+        # If it still fails, another process raced us into the same
+        # reclaim path; surface it as in-progress with the best PID
+        # we observed (or 0 if we couldn't read one).
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            os.close(fd)
+            raise UpdateInProgressError(prior)
+    os.ftruncate(fd, 0)
+    body = (
+        f"PID={os.getpid()}\n"
+        f"STARTED_AT_UTC={_now_utc().isoformat()}\n"
+        f"COMMAND=cctally update\n"
+    ).encode("utf-8")
+    os.write(fd, body)
+    return fd
+
+
+def _release_update_lock(fd: int) -> None:
+    """Drop the flock and close the fd. The lock file persists.
+
+    Defensive on every step: a double-release (or a release after the
+    fd has been closed by an earlier error path) must not raise.
+
+    The file at ``UPDATE_LOCK_PATH`` is deliberately NOT unlinked.
+    ``flock`` locks the inode behind the fd, not the path: unlinking
+    after release lets a peer that ``O_CREAT``ed a new inode at the
+    same path hold a "lock" on a different inode from a peer that
+    still references the old one — concurrent updates. Leaving the
+    file in place pins all acquires to a single inode; the kernel's
+    flock state is the sole synchronization primitive. ``_acquire_..``
+    handles the persistent-file case (O_CREAT + ftruncate + rewrite
+    on every acquire).
+    """
+    try:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+    except OSError:
+        pass
+    try:
+        os.close(fd)
+    except OSError:
+        pass
+
+
+def _rotate_update_log_if_needed() -> None:
+    """Rotate ``update.log`` → ``update.log.1`` when the live log
+    crosses :data:`UPDATE_LOG_ROTATE_BYTES` (1 MB, spec §1.5).
+
+    Single rotation slot: a second rotation overwrites the first.
+    Failed-install logs are preserved on disk only until the next
+    successful run grows the live log past 1 MB — operators chasing a
+    historical failure should grab ``update.log.1`` while it's still
+    around.
+
+    No-op when the file is absent or below threshold.
+    """
+    try:
+        size = UPDATE_LOG_PATH.stat().st_size
+    except FileNotFoundError:
+        return
+    if size < UPDATE_LOG_ROTATE_BYTES:
+        return
+    try:
+        UPDATE_LOG_ROTATED_PATH.unlink()
+    except FileNotFoundError:
+        pass
+    UPDATE_LOG_PATH.rename(UPDATE_LOG_ROTATED_PATH)
+
+
+def _log_update_event(log_fd, event: str, **kv: Any) -> None:
+    """Append one event line to ``update.log``.
+
+    Format: ``<iso-utc> <EVENT> k=v k=v ...``. Strings containing
+    spaces are wrapped with ``repr`` so the log stays grep-friendly;
+    integers are emitted bare so size/elapsed columns can be
+    arithmetic-parsed. ``log_fd`` is any text-mode writable file-like
+    (``open(UPDATE_LOG_PATH, "a", encoding="utf-8")`` is the production
+    caller from Task 5).
+    """
+    parts = [_now_utc().isoformat(), event]
+    for k, v in kv.items():
+        if isinstance(v, str) and " " in v:
+            parts.append(f"{k}={v!r}")
+        else:
+            parts.append(f"{k}={v}")
+    log_fd.write(" ".join(parts) + "\n")
+    log_fd.flush()
+
+
+# === Update subcommand: install-method detection (spec §2) =================
+# Path-based heuristic over `realpath(sys.argv[0])`:
+#   - "/Cellar/cctally/" substring → method="brew" (Apple Silicon, Intel,
+#     and Linuxbrew all funnel through `<root>/Cellar/cctally/`).
+#   - "<npm-prefix>/lib/node_modules/cctally/" prefix → method="npm".
+#   - Anything else (source install, pnpm/yarn-global/volta, dev symlink)
+#     → method="unknown" → manual-fallback bucket per spec §2.4.
+# `mutate=False` is the dry-run contract (§5.5): every tier still
+# computes, but tier-C cache writes to update-state.json are skipped.
+
+
+@dataclass(frozen=True)
+class InstallMethod:
+    """Resolved install method for the running cctally binary (spec §2.1).
+
+    ``method`` is one of ``"brew"``, ``"npm"``, ``"unknown"``;
+    ``realpath`` is ``os.path.realpath(sys.argv[0])`` (the resolved
+    target of any symlinks on $PATH); ``npm_prefix`` is populated only
+    when ``method == "npm"`` so callers don't have to special-case it.
+    """
+
+    method: str
+    realpath: str
+    npm_prefix: str | None
+
+
+def _resolve_npm_prefix(*, mutate: bool = True) -> str | None:
+    """Three-tier ``npm prefix -g`` resolution (spec §2.2).
+
+    Tier A: ``$npm_config_prefix`` env var (rarely set; free).
+    Tier B: cached ``install.npm_prefix`` from update-state.json,
+        7-day TTL (one ``os.stat`` via ``_load_update_state``).
+    Tier C: ``subprocess.run(["npm", "prefix", "-g"], timeout=2.0)``
+        (200–300 ms cold). Tier-C success populates tier-B only when
+        ``mutate=True``; failure (npm not on PATH, timeout, non-zero
+        exit) returns ``None`` regardless of ``mutate``.
+    """
+    # Tier A — env var short-circuit.
+    env_pref = os.environ.get("npm_config_prefix")
+    if env_pref and pathlib.Path(env_pref).is_dir():
+        return env_pref
+    # Tier B — cached state-file value within 7-day TTL.
+    state = _load_update_state()
+    if state and isinstance(state.get("install"), dict):
+        cached = state["install"].get("npm_prefix")
+        detected_iso = state["install"].get("detected_at_utc")
+        if cached and detected_iso:
+            try:
+                detected = dt.datetime.fromisoformat(detected_iso)
+                age = (_now_utc() - detected).total_seconds()
+                if age < UPDATE_NPM_PREFIX_TTL_DAYS * 86400:
+                    return cached
+            except (ValueError, TypeError):
+                # Malformed timestamp → fall through to tier C.
+                pass
+    # Tier C — subprocess. Treat any failure as "unknown npm prefix"
+    # rather than raising; the caller maps None → method="unknown".
+    try:
+        result = subprocess.run(
+            ["npm", "prefix", "-g"],
+            timeout=UPDATE_NPM_PREFIX_TIMEOUT_S,
+            capture_output=True,
+            text=True,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    prefix = result.stdout.strip()
+    if not prefix:
+        return None
+    if mutate:
+        _persist_npm_prefix_to_state(prefix)
+    return prefix
+
+
+def _persist_npm_prefix_to_state(prefix: str) -> None:
+    """Write ``install.npm_prefix`` + ``install.detected_at_utc`` to
+    update-state.json, preserving every other field. Used only by
+    tier-C of :func:`_resolve_npm_prefix` when ``mutate=True``.
+    """
+    state = _load_update_state() or {"_schema": 1}
+    state.setdefault("install", {})
+    state["install"]["npm_prefix"] = prefix
+    state["install"]["detected_at_utc"] = _now_utc().isoformat()
+    _save_update_state(state)
+
+
+def _detect_install_method(*, mutate: bool = True) -> InstallMethod:
+    """Detect how the running cctally was installed (spec §2.1).
+
+    Path-based heuristic — see module-level comment above
+    :class:`InstallMethod` for the algorithm. ``mutate=False`` honours
+    the ``--dry-run`` "touch nothing" contract: detection still runs,
+    but neither the npm-prefix tier-B cache nor the install block is
+    persisted to update-state.json.
+    """
+    real = os.path.realpath(sys.argv[0])
+    if "/Cellar/cctally/" in real:
+        method = InstallMethod(method="brew", realpath=real, npm_prefix=None)
+    else:
+        prefix = _resolve_npm_prefix(mutate=mutate)
+        if prefix:
+            nm_root = os.path.join(prefix, "lib", "node_modules", "cctally")
+            if real == nm_root or real.startswith(nm_root + os.sep):
+                method = InstallMethod(
+                    method="npm", realpath=real, npm_prefix=prefix
+                )
+            else:
+                method = InstallMethod(
+                    method="unknown", realpath=real, npm_prefix=None
+                )
+        else:
+            method = InstallMethod(
+                method="unknown", realpath=real, npm_prefix=None
+            )
+    if mutate:
+        _persist_install_method_to_state(method)
+    return method
+
+
+def _persist_install_method_to_state(method: InstallMethod) -> None:
+    """Replace the ``install`` block in update-state.json with a fresh
+    detection result, preserving every other field (e.g. ``latest_version``
+    written by the version-check pipeline in Task 3). ``current_version``
+    is also re-stamped from the CHANGELOG so the running binary's
+    self-version stays in sync with the install block.
+    """
+    state = _load_update_state() or {"_schema": 1}
+    state["install"] = {
+        "method": method.method,
+        "realpath": method.realpath,
+        "npm_prefix": method.npm_prefix,
+        "detected_at_utc": _now_utc().isoformat(),
+    }
+    cur = _release_read_latest_release_version()
+    if cur:
+        state["current_version"] = cur[0]
+    _save_update_state(state)
+
+
+def _stamp_install_success_to_state(installed_version: str | None) -> None:
+    """Stamp ``update-state.json`` with the just-installed version so the
+    post-install banner predicate + dashboard auto-close fire immediately.
+
+    Without this, both surfaces are stuck for up to ``ttl_hours`` (24h
+    default): ``_do_update_check`` touched the throttle marker before
+    install began, so ``_is_update_check_due`` returns False on every
+    subsequent boot until the TTL expires; ``current_version`` would
+    keep its pre-install value, and ``_semver_gt(latest, current)``
+    stays True. Banner re-fires on every CLI command; dashboard's
+    ``refreshUpdateState`` auto-close (``current === latest``) never
+    matches.
+
+    Falls back to ``state.latest_version`` when the caller didn't pass
+    an explicit ``--version`` — brew is always unpinned, and an
+    unpinned npm install resolves to whatever ``@latest`` advertised,
+    which is the value we just told the user about.
+    """
+    state = _load_update_state() or {"_schema": 1}
+    cur = installed_version or state.get("latest_version")
+    if cur:
+        state["current_version"] = cur
+        state["last_install_success_at_utc"] = _now_utc().isoformat()
+        _save_update_state(state)
+
+
+# === Update subcommand: version-check pipeline (spec §3) ====================
+# Per-vector parsers, TTL gate, and the chokepoint `_do_update_check` that
+# touches the throttle marker FIRST (crash safety) before attempting any
+# remote fetch. Failures preserve the prior state's `latest_version` so the
+# banner predicate can still fire on the last-known-good value.
+
+# Priority regex chain for `_check_brew_latest_version`. First match wins:
+#   1. Explicit `version "X.Y.Z"` line (homebrew's preferred form).
+#   2. Archive URL `/vX.Y.Z[-prerelease.N].tar` (auto-archive form).
+#   3. Tag form `tag: "[v]X.Y.Z"` (occasionally seen in head/url blocks).
+_BREW_VERSION_RE_LIST = (
+    re.compile(r'^\s*version\s+"([^"]+)"\s*$', re.MULTILINE),
+    re.compile(
+        r'url\s+"[^"]*/v(\d+\.\d+\.\d+(?:-[a-zA-Z][a-zA-Z0-9-]*\.\d+)?)\.tar',
+        re.MULTILINE,
+    ),
+    re.compile(
+        r'tag:\s*"v?(\d+\.\d+\.\d+(?:-[a-zA-Z][a-zA-Z0-9-]*\.\d+)?)"',
+        re.MULTILINE,
+    ),
+)
+
+
+def _update_user_agent() -> str:
+    """User-Agent for `_fetch_url` HTTP requests.
+
+    Format: ``cctally-update-check/<version>``. Sources the version from
+    the CHANGELOG (same chokepoint as every other "what version am I"
+    callsite); falls back to ``"dev"`` for pre-release / unstamped trees.
+    """
+    cur = _release_read_latest_release_version()
+    ver = cur[0] if cur else "dev"
+    return f"cctally-update-check/{ver}"
+
+
+def _fetch_url(url: str, *, timeout: float = UPDATE_NETWORK_TIMEOUT_S) -> tuple[int, bytes]:
+    """Stdlib urllib HTTP GET. Raises typed exceptions on failure.
+
+    Returns ``(status_code, body_bytes)`` on success. Maps urllib failures
+    to the four `UpdateCheck*` exception types so callers can distinguish
+    "rate-limited (try again later)" from "HTTP fetch failed (treat as
+    last-known-good)" from "DNS / network down".
+    """
+    req = urllib.request.Request(url, headers={
+        "User-Agent": _update_user_agent(),
+        "Accept": "*/*",
+    })
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return (resp.status, resp.read())
+    except urllib.error.HTTPError as e:
+        if e.code == 429:
+            raise UpdateCheckRateLimited(str(e))
+        raise UpdateCheckHTTPError(f"HTTP {e.code}: {e}")
+    except (urllib.error.URLError, TimeoutError) as e:
+        # URLError covers connection-setup failures; TimeoutError
+        # (socket.timeout's alias since 3.10) covers stalls during
+        # resp.read() — that path raises directly through http.client
+        # without urllib wrapping. Both must funnel to
+        # UpdateCheckNetworkError so _do_update_check translates them
+        # into check_status="fetch_failed" instead of letting a slow
+        # registry crash --check with an uncaught traceback.
+        raise UpdateCheckNetworkError(str(e))
+
+
+def _check_npm_latest_version() -> str:
+    """Fetch the npm-registry `latest` JSON and return its `version` field.
+
+    Endpoint: :data:`UPDATE_NPM_REGISTRY_URL` (env-overridable via
+    ``CCTALLY_TEST_UPDATE_NPM_URL`` for fixture testing). JSON decode
+    errors and missing-key errors raise :class:`UpdateCheckParseError`.
+    """
+    status, body = _fetch_url(UPDATE_NPM_REGISTRY_URL)
+    try:
+        data = json.loads(body.decode("utf-8"))
+        return data["version"]
+    except (json.JSONDecodeError, KeyError, UnicodeDecodeError) as e:
+        raise UpdateCheckParseError(f"npm registry parse failed: {e}")
+
+
+def _check_brew_latest_version() -> str:
+    """Fetch the brew formula raw blob and extract the version.
+
+    Endpoint: :data:`UPDATE_BREW_FORMULA_URL`. Applies
+    :data:`_BREW_VERSION_RE_LIST` in priority order; first match wins.
+    No regex matches → :class:`UpdateCheckParseError`.
+    """
+    status, body = _fetch_url(UPDATE_BREW_FORMULA_URL)
+    try:
+        text = body.decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise UpdateCheckParseError(f"brew formula decode failed: {e}")
+    for pattern in _BREW_VERSION_RE_LIST:
+        m = pattern.search(text)
+        if m:
+            return m.group(1)
+    raise UpdateCheckParseError("brew formula version not found")
+
+
+def _is_update_check_due(config: dict) -> bool:
+    """TTL gate (spec §3.4).
+
+    Reads ``update.check.enabled`` (default True) and
+    ``update.check.ttl_hours`` (default :data:`UPDATE_DEFAULT_TTL_HOURS`)
+    from the config. Returns False if disabled. Returns True if the
+    throttle marker (:data:`UPDATE_CHECK_LAST_FETCH_PATH`) is missing.
+    Otherwise: ``(now - mtime) >= ttl * 3600``.
+    """
+    check_cfg = (config.get("update", {}) or {}).get("check", {}) or {}
+    enabled = check_cfg.get("enabled", True)
+    if not enabled:
+        return False
+    ttl_hours = check_cfg.get("ttl_hours", UPDATE_DEFAULT_TTL_HOURS)
+    try:
+        mtime = UPDATE_CHECK_LAST_FETCH_PATH.stat().st_mtime
+    except FileNotFoundError:
+        return True
+    return (time.time() - mtime) >= ttl_hours * 3600
+
+
+def _do_update_check() -> None:
+    """Single chokepoint for a version-check fetch (spec §3.5).
+
+    Touches the throttle marker FIRST (crash-safety: if the process
+    dies mid-fetch, we still won't refetch for the full TTL window —
+    avoids hammering the registry on a flapping host). Then resolves
+    install method, ensures `current_version` is stamped from CHANGELOG,
+    preserves prior `latest_version` if any, and dispatches to the
+    per-vector check by `method.method`. On success: write
+    `check_status="ok"` + `latest_version_url`. On failure: map the
+    typed exception to a `check_status` enum (`rate_limited` /
+    `fetch_failed` / `parse_failed`); never lose the prior
+    `latest_version`. State is saved unconditionally on the way out.
+    """
+    # Touch marker FIRST — crash safety: a dead process mid-fetch must
+    # not trigger another fetch within the TTL window.
+    UPDATE_CHECK_LAST_FETCH_PATH.parent.mkdir(parents=True, exist_ok=True)
+    UPDATE_CHECK_LAST_FETCH_PATH.touch()
+
+    method = _detect_install_method(mutate=True)
+
+    state = _load_update_state() or {"_schema": 1}
+    cur = _release_read_latest_release_version()
+    if cur:
+        state["current_version"] = cur[0]
+    # Preserve prior `latest_version`; default to current_version if
+    # nothing was ever recorded (so banner predicate has a comparable).
+    state.setdefault("latest_version", state.get("current_version"))
+    state["checked_at_utc"] = _now_utc().isoformat()
+    state["check_error"] = None
+
+    try:
+        if method.method == "npm":
+            latest = _check_npm_latest_version()
+            state["latest_version"] = latest
+            state["source"] = "npm-registry"
+        elif method.method == "brew":
+            latest = _check_brew_latest_version()
+            state["latest_version"] = latest
+            state["source"] = "github-formula"
+        else:
+            # Unknown install method — no remote check possible
+            # (manual-fallback bucket per §2.4). Reset `latest_version`
+            # to `current_version` so the banner predicate's
+            # `_semver_gt(lat, cur)` returns False; preserving a prior
+            # npm/brew latest here would advertise an update that
+            # `cctally update` cannot apply (install method is now
+            # unknown). The setdefault above is insufficient because
+            # state may already carry a `latest_version` from an
+            # earlier npm/brew install before the user switched to a
+            # source checkout. Same suppression flows to the dashboard
+            # amber badge, which reads `latest_version` directly.
+            state["latest_version"] = state.get("current_version")
+            state["check_status"] = "unavailable"
+            _save_update_state(state)
+            return
+        # Success: build the public-mirror release tag URL.
+        state["latest_version_url"] = (
+            f"https://github.com/{PUBLIC_REPO}/releases/tag/v{state['latest_version']}"
+        )
+        state["check_status"] = "ok"
+    except UpdateCheckRateLimited as e:
+        state["check_status"] = "rate_limited"
+        state["check_error"] = str(e)[:200]
+    except (UpdateCheckNetworkError, UpdateCheckHTTPError) as e:
+        state["check_status"] = "fetch_failed"
+        state["check_error"] = str(e)[:200]
+    except UpdateCheckParseError as e:
+        state["check_status"] = "parse_failed"
+        state["check_error"] = str(e)[:200]
+    finally:
+        _save_update_state(state)
+
+
+def _spawn_background_update_check() -> None:
+    """Fire-and-forget the hidden `_update-check` worker.
+
+    Detached `subprocess.Popen` with `start_new_session=True` so a
+    parent exit (the user closes the shell) doesn't propagate SIGHUP
+    to the child. stdin/stdout/stderr are all `/dev/null` so the child
+    can't accidentally pollute the parent's terminal. Exceptions are
+    swallowed: a failed spawn must not break the parent command.
+    """
+    try:
+        subprocess.Popen(
+            [sys.executable, os.path.realpath(sys.argv[0]), "_update-check"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+            close_fds=True,
+        )
+    except Exception:
+        # Fire-and-forget: never let a spawn failure propagate.
+        pass
+
+
+def cmd_update_check_internal(args) -> int:
+    """Hidden ``_update-check`` subcommand handler (spec §3.6).
+
+    The detached-refresh worker — not user-facing. Logs lifecycle
+    events to ``update.log`` and rotates if needed. Always returns 0
+    (any error is logged but the process exits cleanly so the parent
+    spawn-and-forget contract holds).
+    """
+    # Ensure APP_DIR exists so log + state writes succeed on first run.
+    UPDATE_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with open(UPDATE_LOG_PATH, "a", encoding="utf-8") as log_fd:
+            _log_update_event(log_fd, "CHECK_START")
+            _do_update_check()
+            _log_update_event(log_fd, "CHECK_EXIT", rc=0)
+    except Exception as e:
+        try:
+            with open(UPDATE_LOG_PATH, "a", encoding="utf-8") as log_fd:
+                _log_update_event(log_fd, "CHECK_EXIT", rc=1, error=str(e)[:200])
+        except Exception:
+            pass
+    _rotate_update_log_if_needed()
+    return 0
+
+
+# === User-facing `cctally update` (spec §4) ===
+# `cmd_update` routes by mode flag. Mode flags are mutually exclusive
+# (argparse enforces it; the dispatcher's redundant check is defense in
+# depth for programmatic callers and a clearer error message). The
+# install path is staged across two tasks: Task 4 lands the validation
+# gates and the user-mode `--check` rendering, then raises
+# NotImplementedError for actual execution. Task 5 fills in execvp +
+# streaming.
+
+# Sentinel for `--skip` with no positional argument — argparse `const`
+# doesn't accept `None` (collides with the absent-flag default). At
+# dispatch time the sentinel is replaced with `state.latest_version`.
+SKIP_USE_STATE_LATEST = "_USE_STATE_LATEST"
+
+
+def _format_update_command(method: str, version: str | None) -> str:
+    """One-line shell recipe used by both --check renderers and the
+    install-path manual fallback. Brew has no versioned formulae, so
+    the version arg is ignored there (callers gate it earlier)."""
+    if method == "brew":
+        return "brew update --quiet && brew upgrade cctally"
+    if method == "npm":
+        v = version if version else "latest"
+        return f"npm install -g cctally@{v}"
+    return ""
+
+
+def _prerelease_note(current: str) -> str | None:
+    """Spec §1.8 — prerelease users get a one-shot informational note in
+    `--check` output. Returns the canned two-line message verbatim per
+    spec when `current` looks like a prerelease (`X.Y.Z-id.N` form), else
+    None. Wording is exact-string contract — tests pin it."""
+    if "-" not in current:
+        return None
+    return (
+        f"You're on prerelease {current}; this banner suggests stable.\n"
+        "To track prereleases, manage manually: npm install -g cctally@next"
+    )
+
+
+def _format_update_check_json(
+    state: dict[str, Any], suppress: dict[str, Any]
+) -> dict[str, Any]:
+    """JSON shape for `cctally update --check --json` (spec §4.4)."""
+    cur = state.get("current_version")
+    lat = state.get("latest_version")
+    method = (state.get("install") or {}).get("method", "unknown")
+    skipped = lat in suppress.get("skipped_versions", []) if lat else False
+    in_remind_window = False
+    remind = suppress.get("remind_after")
+    if remind is not None and lat is not None:
+        try:
+            if not _semver_gt(lat, remind["version"]):
+                until = dt.datetime.fromisoformat(remind["until_utc"])
+                if _now_utc() < until:
+                    in_remind_window = True
+        except (KeyError, ValueError):
+            pass
+    available = False
+    if cur and lat:
+        try:
+            available = (
+                _semver_gt(lat, cur)
+                and not skipped
+                and not in_remind_window
+            )
+        except ValueError:
+            available = False
+    return {
+        "_schema": 1,
+        "current_version": cur,
+        "latest_version": lat,
+        "available": available,
+        "method": method,
+        "update_command": _format_update_command(method, None),
+        "release_notes_url": state.get("latest_version_url"),
+        "check_status": state.get("check_status"),
+        "check_error": state.get("check_error"),
+        "checked_at_utc": state.get("checked_at_utc"),
+        "suppress": {
+            "skipped": skipped,
+            "remind_after_utc": (
+                remind.get("until_utc") if isinstance(remind, dict) else None
+            ),
+        },
+        "prerelease_note": _prerelease_note(cur) if cur else None,
+    }
+
+
+_UPDATE_METHOD_HUMAN_LABEL = {
+    "brew": "Homebrew",
+    "npm": "npm",
+    "unknown": "unknown",
+}
+
+
+def _format_update_check_human(
+    state: dict[str, Any], suppress: dict[str, Any]
+) -> str:
+    """Multi-line plaintext block for `cctally update --check` (spec §4.4).
+
+    Two-space-column table layout: every label left-padded to width 10
+    (`Will run` is the longest at 8 chars + 2-space gutter). Method row
+    appends `  (auto-detected)` per spec example. Up-to-date / unknown
+    variants append a fallback line below the table.
+    """
+    cur = state.get("current_version") or "unknown"
+    lat = state.get("latest_version") or "unknown"
+    method = (state.get("install") or {}).get("method", "unknown")
+    url = state.get("latest_version_url")
+    status = state.get("check_status")
+    err = state.get("check_error")
+    cooked_available = False
+    if state.get("current_version") and state.get("latest_version"):
+        try:
+            cooked_available = _semver_gt(lat, cur) and \
+                lat not in suppress.get("skipped_versions", [])
+        except ValueError:
+            cooked_available = False
+
+    method_label = _UPDATE_METHOD_HUMAN_LABEL.get(method, method)
+    lines = [
+        f"{'Current':<10}{cur}",
+        f"{'Latest':<10}{lat}",
+        f"{'Method':<10}{method_label}  (auto-detected)",
+    ]
+    will_run = _format_update_command(method, None)
+    if will_run:
+        lines.append(f"{'Will run':<10}{will_run}")
+    if url:
+        lines.append(f"{'Notes':<10}{url}")
+    if status and status != "ok":
+        status_value = status + (f" ({err})" if err else "")
+        lines.append(f"{'Status':<10}{status_value}")
+    lines.append("")
+    if method == "unknown":
+        # No remote check is possible for source / dev installs; render
+        # the manual fallback rather than the "you're up to date" lie.
+        lines.append(
+            "Automatic update unavailable for this install. Visit "
+            f"{url or 'https://github.com/' + PUBLIC_REPO + '/releases'} "
+            "to install manually."
+        )
+    elif cooked_available:
+        lines.append("Run `cctally update` to install.")
+    else:
+        lines.append("You're up to date.")
+    note = _prerelease_note(cur)
+    if note:
+        lines.append("")
+        lines.append(note)
+    return "\n".join(lines)
+
+
+def _do_update_skip(version_arg: str) -> int:
+    """`cctally update --skip [VERSION]` — record a skipped version."""
+    if version_arg == SKIP_USE_STATE_LATEST:
+        state = _load_update_state()
+        if state is None or not state.get("latest_version"):
+            print(
+                "cctally update: no version in cache to skip; run "
+                "`cctally update --check` first",
+                file=sys.stderr,
+            )
+            return 1
+        version = state["latest_version"]
+    else:
+        if not _SEMVER_RE.match(version_arg):
+            print(
+                f"cctally update: invalid version {version_arg!r} "
+                "(expected X.Y.Z[-id.N])",
+                file=sys.stderr,
+            )
+            return 2
+        version = version_arg
+    suppress = _load_update_suppress()
+    skipped = list(suppress.get("skipped_versions", []))
+    if version not in skipped:
+        skipped.append(version)
+    suppress["skipped_versions"] = skipped
+    suppress.setdefault("_schema", 1)
+    _save_update_suppress(suppress)
+    print(
+        f"Skipped cctally {version}. You won't be reminded about this version."
+    )
+    return 0
+
+
+def _do_update_remind_later(days: int) -> int:
+    """`cctally update --remind-later [DAYS]` — defer banner for N days."""
+    if not (1 <= days <= 365):
+        print(
+            f"cctally update: --remind-later must be 1..365 (got {days})",
+            file=sys.stderr,
+        )
+        return 2
+    state = _load_update_state()
+    if state is None or not state.get("latest_version"):
+        print(
+            "cctally update: no version in cache to defer; run "
+            "`cctally update --check` first",
+            file=sys.stderr,
+        )
+        return 1
+    until = (_now_utc() + dt.timedelta(days=days)).isoformat()
+    suppress = _load_update_suppress()
+    suppress["remind_after"] = {
+        "version": state["latest_version"],
+        "until_utc": until,
+    }
+    suppress.setdefault("_schema", 1)
+    _save_update_suppress(suppress)
+    print(
+        f"Will remind in {days} day{'s' if days != 1 else ''} "
+        "(or sooner if a newer version drops)."
+    )
+    return 0
+
+
+_UPDATE_CHECK_JSON_UNAVAILABLE_ENVELOPE = {
+    "_schema": 1,
+    "current_version": None,
+    "latest_version": None,
+    "available": False,
+    "method": "unknown",
+    "update_command": None,
+    "release_notes_url": None,
+    "check_status": "unavailable",
+    "check_error": "state unavailable",
+    "checked_at_utc": None,
+    "suppress": {"skipped": False, "remind_after_utc": None},
+    "prerelease_note": None,
+}
+
+
+def _do_update_check_user(*, force: bool, output_json: bool) -> int:
+    """`cctally update --check` — user-facing version-check render.
+
+    `_do_update_check()` translates known failure modes (network,
+    parse, rate-limit) into `check_status` fields on the state file
+    via its own internal try/except (Task 3, spec §3.5); any unexpected
+    exception that escapes is a real bug and is left to surface in the
+    outer error log. The post-command banner hook in `main()` already
+    isolates banner failures.
+
+    Refresh gate matches the user-facing docs (`docs/commands/update.md`):
+    `--check` refreshes when TTL has elapsed; `--force` bypasses the TTL
+    gate to refresh even on a fresh cache. Synchronous refresh here also
+    pre-empts the post-command background spawn — `_do_update_check`
+    touches `update-check.last-fetch` first, so `_is_update_check_due`
+    returns False by the time the hook runs.
+    """
+    config = load_config()
+    if force or _is_update_check_due(config):
+        _do_update_check()
+    state = _load_update_state()
+    if state is None:
+        # Still nothing on disk — try once even with a fresh TTL marker
+        # so the first invocation isn't a content-free "state unavailable".
+        _do_update_check()
+        state = _load_update_state()
+    if state is None:
+        if output_json:
+            # Emit a parseable minimal envelope so JSON consumers always
+            # get a payload; rc stays 0 (best-effort, matches the
+            # `cmd_refresh_usage` precedent that network failures are
+            # not user-actionable errors). Spec §4.4.
+            print(
+                json.dumps(_UPDATE_CHECK_JSON_UNAVAILABLE_ENVELOPE, indent=2)
+            )
+            return 0
+        print("cctally update: state unavailable", file=sys.stderr)
+        return 0
+    suppress = _load_update_suppress()
+    if output_json:
+        print(json.dumps(_format_update_check_json(state, suppress), indent=2))
+    else:
+        print(_format_update_check_human(state, suppress))
+    return 0
+
+
+def _preflight_install(method: InstallMethod, version: str | None) -> None:
+    """Validate the install plan before any subprocess runs (spec §5.1).
+
+    Ordered checks (each raises and short-circuits the rest):
+      1. method != "unknown" — manual-fallback bucket per §2.4.
+      2. version (if not None) matches `_SEMVER_RE` — `X.Y.Z` or
+         `X.Y.Z-prerelease`.
+      3. (method, version) compatibility — brew has no versioned
+         formulae; pinned-version installs must be done manually.
+      4. npm-only: the `<prefix>/bin` directory must be writable; if
+         not, surface the sudo / `npm config set prefix` recipes
+         instead of letting npm fail with EACCES inside the run.
+
+    Raises :class:`UpdateValidationError` for input-validation failures
+    (rc=2 at the boundary): invalid --version syntax, --version+brew
+    combo. Raises :class:`UpdateError` for environment / runtime
+    failures (rc=1 at the boundary): unknown install method, npm
+    prefix not writable.
+
+    Brew preflight is intentionally a no-op beyond the version-combo
+    check (codex review #2): homebrew installs into ``libexec/bin/``,
+    so ``realpath`` lands inside the keg, not the brew bin prefix; brew
+    has its own permission model and ``brew doctor`` is the diagnostic
+    users already know.
+    """
+    if method.method == "unknown":
+        raise UpdateError(
+            "Install method is 'unknown' — automatic update unavailable.\n"
+            "If you installed from source: cd <your cctally repo> && git pull && bin/symlink"
+        )
+    if version is not None and not _SEMVER_RE.match(version):
+        raise UpdateValidationError(
+            f"Invalid version: {version!r} (expected X.Y.Z or X.Y.Z-id.N)"
+        )
+    if method.method == "brew" and version is not None:
+        raise UpdateValidationError(
+            "Pinned-version install is not supported on Homebrew "
+            "(no versioned formulae).\n"
+            "To install a specific version manually:\n"
+            f"  brew uninstall cctally\n"
+            f"  brew install https://github.com/{PUBLIC_REPO}/releases/download/v{version}/cctally-{version}.tar.gz"
+        )
+    if method.method == "npm":
+        prefix_bin = os.path.join(method.npm_prefix, "bin")
+        if not os.access(prefix_bin, os.W_OK):
+            raise UpdateError(
+                f"npm prefix '{prefix_bin}' is not writable.\n"
+                f"Run with sudo: sudo npm install -g cctally@{version or 'latest'}\n"
+                "Or relocate: npm config set prefix ~/.npm-global"
+            )
+    # brew: NO preflight beyond the --version combo check above
+    # (codex review #2 amendment to spec §5.1).
+
+
+def _build_update_steps(
+    method: InstallMethod, version: str | None
+) -> list[tuple[str, list[str]]]:
+    """Build the ordered list of subprocess steps for an install plan.
+
+    Each step is ``(human_name, argv)`` where ``human_name`` is the
+    label rendered in dry-run output and the dashboard live-stream
+    modal, and ``argv`` is the list passed to ``subprocess.Popen`` (no
+    shell). Brew is two steps (``brew update`` then ``brew upgrade
+    cctally``) per spec §5.2 + Q6a — splitting them gives diagnostic
+    clarity (a stale tap manifesting as a hung ``brew update`` is
+    distinguishable from an ``upgrade`` failure). npm is one step.
+    """
+    if method.method == "brew":
+        return [
+            ("brew update", ["brew", "update", "--quiet"]),
+            ("brew upgrade cctally", ["brew", "upgrade", "cctally"]),
+        ]
+    if method.method == "npm":
+        target = f"cctally@{version}" if version else "cctally@latest"
+        return [("npm install -g", ["npm", "install", "-g", target])]
+    raise AssertionError(
+        f"step builder called with method={method.method!r} "
+        "(should have been rejected by _preflight_install)"
+    )
+
+
+def _run_streaming(
+    cmd: list[str],
+    *,
+    on_stdout: Callable[[str], None],
+    on_stderr: Callable[[str], None],
+    log_fd,
+) -> int:
+    """Run ``cmd``, line-buffer stdout/stderr to callbacks, append to log.
+
+    Two-thread pump (one per stream) → callbacks + log lines. Each log
+    line is ``<iso-utc> <STREAM> <raw-line>`` so a grep for the stream
+    label still recovers the chronological order even when stdout and
+    stderr interleave at sub-line resolution. ``proc.wait()`` is the
+    synchronization point; the pump threads are daemons so a crash in
+    the parent doesn't leave them lingering.
+
+    Used by:
+      - the CLI install path (Task 5; this file) where ``on_stdout`` /
+        ``on_stderr`` print to the parent's stdout/stderr;
+      - the dashboard ``UpdateWorker`` thread (Task 6) where the
+        callbacks push lines into a per-stream ring buffer for SSE.
+
+    Stdin is inherited from the parent — the wrapped commands
+    (``brew update``, ``npm install -g``) take no input; piping
+    ``DEVNULL`` would just add a syscall.
+    """
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        bufsize=1,
+        text=True,
+    )
+
+    def pump(stream, cb, label):
+        for line in stream:
+            cb(line.rstrip("\n"))
+            if log_fd is not None:
+                log_fd.write(f"{_now_utc().isoformat()} {label} {line}")
+                log_fd.flush()
+        stream.close()
+
+    t_out = threading.Thread(
+        target=pump, args=(proc.stdout, on_stdout, "STDOUT"), daemon=True
+    )
+    t_err = threading.Thread(
+        target=pump, args=(proc.stderr, on_stderr, "STDERR"), daemon=True
+    )
+    t_out.start()
+    t_err.start()
+    proc.wait()
+    t_out.join()
+    t_err.join()
+    return proc.returncode
+
+
+def _do_update_install(
+    *, version: str | None, dry_run: bool, output_json: bool
+) -> int:
+    """`cctally update` (no mode flag) — install execution (spec §5).
+
+    Task-4 inline gates moved into :func:`_preflight_install`. Real
+    install: acquire lock → log INSTALL_START → run each step (logging
+    STEP_START/STEP_EXIT), bail on the first non-zero rc → log
+    INSTALL_SUCCESS → release lock + rotate log in finally.
+
+    Dry-run path passes ``mutate=False`` to detection (codex review
+    fix #4), prints "Would run: ..." (or one JSON-line per step) for
+    each planned step, and exits 0 without touching the lock or
+    running any subprocesses.
+
+    Raises :class:`UpdateError` (rc=1 at boundary) for unknown method
+    / write-perm-denied; :class:`UpdateValidationError` (rc=2) for
+    invalid --version / --version+brew. The boundary distinction is
+    enforced by :func:`cmd_update`'s try/except below.
+    """
+    method = _detect_install_method(mutate=not dry_run)
+    _preflight_install(method, version)
+    steps = _build_update_steps(method, version)
+    if dry_run:
+        for name, cmd in steps:
+            if output_json:
+                print(json.dumps({"step": name, "would_run": cmd}))
+            else:
+                quoted = " ".join(shlex.quote(c) for c in cmd)
+                print(f"Would run: {quoted}")
+        return 0
+    UPDATE_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    lock_fd = _acquire_update_lock()
+    try:
+        with open(UPDATE_LOG_PATH, "a", encoding="utf-8") as log_fd:
+            _log_update_event(log_fd, "INSTALL_START", method=method.method)
+            for step_name, cmd in steps:
+                _log_update_event(log_fd, "STEP_START", name=step_name)
+                rc = _run_streaming(
+                    cmd,
+                    on_stdout=lambda line: print(line, file=sys.stdout, flush=True),
+                    on_stderr=lambda line: print(line, file=sys.stderr, flush=True),
+                    log_fd=log_fd,
+                )
+                _log_update_event(log_fd, "STEP_EXIT", name=step_name, rc=rc)
+                if rc != 0:
+                    return 1
+            _log_update_event(log_fd, "INSTALL_SUCCESS")
+            _stamp_install_success_to_state(version)
+            return 0
+    finally:
+        _release_update_lock(lock_fd)
+        _rotate_update_log_if_needed()
+
+
+# === Dashboard execvp re-entry (spec §5.7) ===
+# ORIGINAL_SYS_ARGV / ORIGINAL_ENTRYPOINT are captured at dashboard
+# server boot in cmd_dashboard. _resolve_execvp_target uses them to
+# return (entrypoint, exec_argv) for os.execvp:
+#
+#   - npm: entrypoint = <prefix>/bin/cctally → Node shim, which
+#     re-resolves CCTALLY_PYTHON before re-spawning Python (so a custom
+#     interpreter setting survives the restart).
+#   - brew: entrypoint = <brew>/bin/cctally → symlink into the
+#     post-upgrade Python script with its rewritten shebang.
+#   - Fallback when shutil.which("cctally") returned None: use
+#     sys.argv[0] directly. Loses the npm shim layer; we accept the
+#     degraded edge case rather than guess.
+ORIGINAL_SYS_ARGV: list[str] = []
+ORIGINAL_ENTRYPOINT: "str | None" = None
+
+
+def _resolve_execvp_target() -> tuple[str, list[str]]:
+    """Return (entrypoint, exec_argv) per spec §5.7.
+
+    Re-enters the npm shim by execvp'ing the PATH-resolved ``cctally``
+    (Node shim for npm, brew symlink for brew). Falls back to
+    ``sys.argv[0]`` only when ``shutil.which`` returned ``None`` at
+    dashboard boot (rare absolute-path invocation).
+    """
+    if ORIGINAL_ENTRYPOINT is not None:
+        return (
+            ORIGINAL_ENTRYPOINT,
+            [ORIGINAL_ENTRYPOINT, *ORIGINAL_SYS_ARGV[1:]],
+        )
+    return (ORIGINAL_SYS_ARGV[0], list(ORIGINAL_SYS_ARGV))
+
+
+class UpdateWorker:
+    """Single-slot dashboard-side update orchestrator (spec §5.6).
+
+    A single instance lives on the dashboard server (created in
+    cmd_dashboard, exposed as the module-level ``_UPDATE_WORKER``).
+    ``start()`` returns ``(True, run_id)`` on accept and
+    ``(False, current_run_id)`` when a run is already in progress —
+    serializes concurrent button clicks without taking the install lock
+    on the rejected path. ``_run`` runs preflight → lock → streamed
+    steps → execvp on success / error_event on failure / done on
+    non-zero subprocess exit. The ``released`` flag enforces the
+    idempotent-release contract from spec §5.6.1: success path releases
+    pre-execvp and skips the finally release; pre-execvp failure path
+    releases in finally.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._current_id: "str | None" = None
+        # run_id -> queue.Queue of event dicts. Each subscriber drains
+        # via ``stream(run_id)``; the worker thread enqueues via
+        # ``_emit``. A single subscriber per run is the dashboard
+        # contract; multi-subscriber broadcast is out of scope. The
+        # producer (``_run``) intentionally does NOT pop its entry —
+        # that would race a late consumer (#32): the worker thread can
+        # complete its finally before the consumer enters ``stream()``,
+        # leaving the consumer to look up a missing key. Cleanup
+        # ownership now belongs to ``stream()``'s finally; if no
+        # consumer ever subscribes, ``start()`` reaps stale entries on
+        # the next run.
+        self._streams: dict[str, "queue.Queue"] = {}
+
+    def start(self, version: "str | None") -> tuple[bool, str]:
+        """Begin a run. Returns (accepted, run_id).
+
+        ``accepted=False`` when another run is in progress; the
+        returned ``run_id`` is the in-progress one (so the caller can
+        surface it as ``run_id_in_progress`` to the client).
+        """
+        with self._lock:
+            if self._current_id is not None:
+                return (False, self._current_id)
+            # Reap any stale entries from prior no-consumer runs. Safe
+            # under the lock: ``_current_id is None`` here, so no live
+            # stream() generator holds a reference into the dict by
+            # run_id (only by local-variable q ref, which survives the
+            # pop).
+            self._streams.clear()
+            run_id = secrets.token_hex(8)
+            self._current_id = run_id
+            self._streams[run_id] = queue.Queue()
+        threading.Thread(
+            target=self._run, args=(run_id, version), daemon=True,
+            name="cctally-update-worker",
+        ).start()
+        return (True, run_id)
+
+    def status(self) -> dict:
+        """Return ``{"current_run_id": <run_id|None>}`` for /api/update/status."""
+        with self._lock:
+            return {"current_run_id": self._current_id}
+
+    def _emit(self, run_id: str, event: dict) -> None:
+        q = self._streams.get(run_id)
+        if q is not None:
+            q.put(event)
+
+    def stream(self, run_id: str):
+        """Generator yielding events for the given run_id.
+
+        Yields a ``{"type": "heartbeat"}`` event every 15 s of idle so
+        the SSE proxy / EventSource keep-alive stays warm. Closes
+        (returns) on the terminal events: ``execvp`` (success path),
+        ``error_event`` (preflight or other UpdateError), ``done``
+        (non-zero subprocess exit). Yields nothing and returns
+        immediately for unknown run_ids — the HTTP handler then closes
+        the SSE connection.
+        """
+        q = self._streams.get(run_id)
+        if q is None:
+            return
+        try:
+            while True:
+                try:
+                    ev = q.get(timeout=15)
+                except queue.Empty:
+                    yield {"type": "heartbeat"}
+                    continue
+                yield ev
+                if ev["type"] in ("execvp", "error_event", "done"):
+                    return
+        finally:
+            # Only reap when the worker is no longer the active producer
+            # for this run_id. A mid-run modal close unwinds this
+            # generator while ``_current_id == run_id`` and ``_run`` is
+            # still emitting — popping here would silently drop those
+            # events, and a modal reopen (slice.runId is preserved per
+            # spec §6) would re-subscribe against a missing queue.
+            # Cleanup still happens on the first ``stream()`` exit AFTER
+            # the worker terminates (its finally clears _current_id), or
+            # via ``start()``'s reap on the next run.
+            with self._lock:
+                if self._current_id != run_id:
+                    self._streams.pop(run_id, None)
+
+    def _run(self, run_id: str, version: "str | None") -> None:
+        lock_fd = None
+        released = False  # idempotent-release guard per §5.6.1
+        log_fd = None
+        try:
+            method = _detect_install_method(mutate=True)
+            _preflight_install(method, version)
+            UPDATE_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+            lock_fd = _acquire_update_lock()
+            log_fd = open(UPDATE_LOG_PATH, "a", encoding="utf-8")
+            _log_update_event(log_fd, "INSTALL_START", method=method.method)
+            for step_name, cmd in _build_update_steps(method, version):
+                self._emit(run_id, {"type": "step", "name": step_name})
+                _log_update_event(log_fd, "STEP_START", name=step_name)
+                rc = _run_streaming(
+                    cmd,
+                    on_stdout=lambda line, rid=run_id: self._emit(
+                        rid, {"type": "stdout", "data": line}
+                    ),
+                    on_stderr=lambda line, rid=run_id: self._emit(
+                        rid, {"type": "stderr", "data": line}
+                    ),
+                    log_fd=log_fd,
+                )
+                _log_update_event(log_fd, "STEP_EXIT", name=step_name, rc=rc)
+                self._emit(run_id, {"type": "exit", "rc": rc, "step": step_name})
+                if rc != 0:
+                    self._emit(run_id, {"type": "done", "success": False})
+                    return
+            _log_update_event(log_fd, "INSTALL_SUCCESS")
+            _stamp_install_success_to_state(version)
+            entrypoint, exec_argv = _resolve_execvp_target()
+            self._emit(run_id, {"type": "execvp", "argv": exec_argv})
+            try:
+                log_fd.close()
+            finally:
+                log_fd = None
+            # 0.5 s breathing room so the SSE pump flushes the final
+            # ``execvp`` event to the browser before we hand the
+            # process over to the new image. If the browser misses it
+            # the polling fallback (/api/update/status) covers reentry.
+            time.sleep(0.5)
+            _release_update_lock(lock_fd)
+            released = True
+            os.execvp(entrypoint, exec_argv)
+        except UpdateError as e:
+            self._emit(run_id, {"type": "error_event", "message": str(e)})
+        except Exception as e:
+            self._emit(
+                run_id, {"type": "error_event", "message": f"unexpected: {e!r}"}
+            )
+        finally:
+            if log_fd is not None:
+                try:
+                    log_fd.close()
+                except Exception:
+                    pass
+            if lock_fd is not None and not released:
+                try:
+                    _release_update_lock(lock_fd)
+                except Exception:
+                    pass
+            with self._lock:
+                self._current_id = None
+                # _streams[run_id] intentionally retained — see class
+                # docstring. Cleanup is owned by stream()'s finally;
+                # start() sweeps stale entries on the next run.
+
+
+# Module-level singleton. Populated by cmd_dashboard on server boot;
+# consumed by DashboardHTTPHandler's /api/update* routes. Kept None
+# for non-dashboard subcommands so a stray test that loads the script
+# without booting the dashboard sees a clean uninitialized state.
+_UPDATE_WORKER: "UpdateWorker | None" = None
+
+
+class _DashboardUpdateCheckThread(threading.Thread):
+    """Dedicated update-check polling thread (spec §3.5).
+
+    Independent of the data-sync thread so it runs even under
+    ``--no-sync`` (codex review fix #5). Wakes once per
+    :data:`UPDATE_DASHBOARD_CHECK_POLL_S` (30 min), consults
+    :func:`_is_update_check_due`, runs :func:`_do_update_check` if so.
+    The poll cadence is NOT the network-call frequency — actual TTL
+    gate (default 24 h) lives in ``_is_update_check_due``. Disabling
+    via ``update.check.enabled = false`` is honoured inside the gate
+    so the thread becomes a no-op without needing teardown.
+
+    After a successful check, republishes the current snapshot via the
+    SSE hub so long-open dashboard tabs in ``--no-sync`` mode pick up
+    the fresh ``latest_version`` written to ``update-state.json``. The
+    snapshot itself is unchanged — ``snapshot_to_envelope`` re-reads
+    the state file per envelope build, so a bare publish is enough to
+    refresh the badge for every live subscriber.
+    """
+
+    daemon = True
+
+    def __init__(
+        self,
+        stop_event: "threading.Event",
+        *,
+        hub: "SSEHub | None" = None,
+        snapshot_ref: "_SnapshotRef | None" = None,
+    ) -> None:
+        super().__init__(name="cctally-update-check")
+        self._stop = stop_event
+        self._hub = hub
+        self._ref = snapshot_ref
+
+    def run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                config = load_config()
+                if _is_update_check_due(config):
+                    _do_update_check()
+                    if self._hub is not None and self._ref is not None:
+                        snap = self._ref.get()
+                        if snap is not None:
+                            self._hub.publish(snap)
+            except Exception as e:
+                # Log but never propagate — this thread must keep
+                # ticking so a transient registry hiccup doesn't
+                # silently disable the polling cadence for the rest
+                # of the dashboard's lifetime.
+                try:
+                    UPDATE_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+                    with open(UPDATE_LOG_PATH, "a", encoding="utf-8") as log_fd:
+                        _log_update_event(
+                            log_fd, "CHECK_FAILED", error=str(e)[:200]
+                        )
+                except Exception:
+                    pass
+            self._stop.wait(UPDATE_DASHBOARD_CHECK_POLL_S)
+
+
+def cmd_update(args) -> int:
+    """`cctally update` entry point — routes by mode flag (spec §4.1)."""
+    skip_arg = getattr(args, "skip", None)
+    remind_arg = getattr(args, "remind_later", None)
+    check_arg = getattr(args, "check", False)
+    # NOTE: `args.install_version`, not `args.version` — the subparser's
+    # `--version X.Y.Z` is `dest="install_version"` to avoid colliding
+    # with the top-level `--version` flag handled in `main()`.
+    version_arg = getattr(args, "install_version", None)
+    modes = sum(bool(x) for x in [
+        check_arg,
+        skip_arg is not None,
+        remind_arg is not None,
+    ])
+    if modes > 1:
+        print(
+            "cctally update: --check / --skip / --remind-later are "
+            "mutually exclusive",
+            file=sys.stderr,
+        )
+        return 2
+    if version_arg is not None and (
+        check_arg or skip_arg is not None or remind_arg is not None
+    ):
+        print(
+            "cctally update: --version is install-mode only",
+            file=sys.stderr,
+        )
+        return 2
+    if skip_arg is not None:
+        return _do_update_skip(skip_arg)
+    if remind_arg is not None:
+        return _do_update_remind_later(remind_arg)
+    if check_arg:
+        return _do_update_check_user(
+            force=getattr(args, "force", False),
+            output_json=getattr(args, "json", False),
+        )
+    try:
+        return _do_update_install(
+            version=version_arg,
+            dry_run=getattr(args, "dry_run", False),
+            output_json=getattr(args, "json", False),
+        )
+    except UpdateValidationError as e:
+        # Input validation failure (invalid --version syntax,
+        # --version+brew combo). rc=2 preserves the Task-4 contract.
+        print(f"cctally update: {e}", file=sys.stderr)
+        return 2
+    except UpdateError as e:
+        # Runtime / environment failure (unknown install method, npm
+        # prefix not writable, lock contention). rc=1.
+        print(f"cctally update: {e}", file=sys.stderr)
+        return 1
+
+
 def get_week_start_name(config: dict[str, Any], override: str | None = None) -> str:
     if override:
         name = override.strip().lower()
@@ -13353,6 +15095,97 @@ def _args_emit_machine_stdout(args: argparse.Namespace) -> bool:
     return bool(getattr(args, "status_line", False))
 
 
+# Update-banner suppression set — parallel to ``_BANNER_SUPPRESSED_COMMANDS``
+# (migration banner) but with its own membership. ``update`` itself shouldn't
+# advertise an update; ``_update-check`` is the detached-refresh worker
+# (silent by contract). Other suppressions (record-usage, hook-tick, sync-week,
+# cache-sync, refresh-usage, tui, db) ride the existing migration set so
+# the two banners stay aligned for those commands.
+_UPDATE_BANNER_EXTRA_SUPPRESSED = frozenset({"_update-check", "update"})
+
+
+def _semver_gt(a: str, b: str) -> bool:
+    """SemVer comparison via :func:`_release_parse_semver` + the
+    SemVer-§11.4-aware sort key. ``a > b`` returns True when ``a`` is
+    a strictly higher version. Raises :class:`ValueError` on either
+    input being malformed (callers wrap in try/except)."""
+    return _release_semver_sort_key(_release_parse_semver(a)) > \
+           _release_semver_sort_key(_release_parse_semver(b))
+
+
+def _should_show_update_banner(
+    command: str | None,
+    args: argparse.Namespace,
+    state: dict[str, Any] | None,
+    suppress: dict[str, Any],
+    config: dict[str, Any],
+) -> bool:
+    """Return True iff a one-line update banner should land on stderr
+    after this command's output (spec §4.2).
+
+    Composition is the key invariant: the predicate **must** delegate
+    machine-mode detection to the existing helpers
+    (:func:`_args_emit_json`, :func:`_args_emit_machine_stdout`) so a
+    new ``--json`` dest variant or status-line flag added to any
+    subcommand inherits the suppression automatically. Adding a parallel
+    list here would silently regress that invariant — the spec
+    amendment for Codex finding #8 codifies this.
+    """
+    if command in _BANNER_SUPPRESSED_COMMANDS or command in _UPDATE_BANNER_EXTRA_SUPPRESSED:
+        return False
+    if _args_emit_json(args):
+        return False
+    if _args_emit_machine_stdout(args):
+        return False
+    if getattr(args, "format", None) is not None:
+        return False
+    if not sys.stderr.isatty():
+        return False
+    if not config.get("update", {}).get("check", {}).get("enabled", True):
+        return False
+    if state is None:
+        return False
+    cur = state.get("current_version")
+    lat = state.get("latest_version")
+    if not cur or not lat:
+        return False
+    try:
+        if not _semver_gt(lat, cur):
+            return False
+    except ValueError:
+        return False
+    if lat in suppress.get("skipped_versions", []):
+        return False
+    remind = suppress.get("remind_after")
+    if remind is not None:
+        try:
+            # Hide while the deferral is active AND the user-pinned version
+            # is still the latest. A newer drop overrides the deferral.
+            if not _semver_gt(lat, remind["version"]):
+                until = dt.datetime.fromisoformat(remind["until_utc"])
+                if _now_utc() < until:
+                    return False
+        except (KeyError, ValueError):
+            # Malformed remind_after: fail-open (banner shows). Better
+            # than silently dropping a real update reminder.
+            pass
+    return True
+
+
+def _format_update_banner(state: dict[str, Any]) -> str:
+    """One-line stderr banner. Spec §4.2.
+
+    Includes the dismissal recipe inline so the user never has to
+    consult docs to silence it.
+    """
+    cur = state["current_version"]
+    lat = state["latest_version"]
+    return (
+        f"↑ cctally {lat} available (you're on {cur}). "
+        f"Run `cctally update`. Skip: cctally update --skip {lat}"
+    )
+
+
 def _print_migration_error_banner_if_needed(args) -> None:
     """Print a one-line warning banner if the migration error log has
     entries.
@@ -14339,7 +16172,9 @@ def cmd_daily(args: argparse.Namespace) -> int:
     args._resolved_tz = tz
 
     range = _parse_cli_date_range(
-        args, tz_name=(tz.key if tz is not None else None)
+        args,
+        tz_name=(tz.key if tz is not None else None),
+        now_utc=_command_as_of(),
     )
     if isinstance(range, int):
         return range
@@ -14407,7 +16242,9 @@ def cmd_monthly(args: argparse.Namespace) -> int:
     args._resolved_tz = tz
 
     range = _parse_cli_date_range(
-        args, tz_name=(tz.key if tz is not None else None)
+        args,
+        tz_name=(tz.key if tz is not None else None),
+        now_utc=_command_as_of(),
     )
     if isinstance(range, int):
         return range
@@ -14602,7 +16439,9 @@ def cmd_codex_daily(args: argparse.Namespace) -> int:
     # (because resolve_display_tz returns None for canonical "local").
     tz_name = _resolve_codex_tz_name(args, config)
     force_compact = bool(getattr(args, "compact", False))
-    range = _parse_cli_date_range(args, tz_name=tz_name)
+    range = _parse_cli_date_range(
+        args, tz_name=tz_name, now_utc=_command_as_of(),
+    )
     if isinstance(range, int):
         return range
     range_start, range_end = range
@@ -14652,7 +16491,9 @@ def cmd_codex_monthly(args: argparse.Namespace) -> int:
     # F2 fix: see cmd_codex_daily.
     tz_name = _resolve_codex_tz_name(args, config)
     force_compact = bool(getattr(args, "compact", False))
-    range = _parse_cli_date_range(args, tz_name=tz_name)
+    range = _parse_cli_date_range(
+        args, tz_name=tz_name, now_utc=_command_as_of(),
+    )
     if isinstance(range, int):
         return range
     range_start, range_end = range
@@ -14760,7 +16601,9 @@ def cmd_codex_session(args: argparse.Namespace) -> int:
     # F2 fix: see cmd_codex_daily.
     tz_name = _resolve_codex_tz_name(args, config)
     force_compact = bool(getattr(args, "compact", False))
-    range = _parse_cli_date_range(args, tz_name=tz_name)
+    range = _parse_cli_date_range(
+        args, tz_name=tz_name, now_utc=_command_as_of(),
+    )
     if isinstance(range, int):
         return range
     range_start, range_end = range
@@ -14806,6 +16649,31 @@ def _command_as_of() -> dt.datetime:
     return dt.datetime.now(dt.timezone.utc)
 
 
+def _now_utc() -> dt.datetime:
+    """UTC now, with CCTALLY_AS_OF env override for fixture-stability.
+
+    Single time source for the `update` subcommand and its supporting
+    state machine (TTL gates, ``remind_after.until_utc`` comparisons,
+    log timestamps, install-method detection cache). Mirrors the
+    documented CCTALLY_AS_OF precedent (see CLAUDE.md — `project` has
+    a hidden `CCTALLY_AS_OF` env hook, and `_command_as_of` /
+    `_share_now_utc` reuse it for `weekly`/`forecast`/share-render).
+    Accepts ISO-8601 with `Z` or explicit offset; result is always
+    tz-aware UTC.
+
+    Raises ValueError on malformed CCTALLY_AS_OF — deliberate fail-loud
+    for the dev hook so fixture authors notice typos immediately rather
+    than silently falling back to wall-clock time.
+    """
+    override = os.environ.get("CCTALLY_AS_OF")
+    if override:
+        override = override.strip()
+        if override.endswith("Z"):
+            override = override[:-1] + "+00:00"
+        return dt.datetime.fromisoformat(override).astimezone(dt.timezone.utc)
+    return dt.datetime.now(dt.timezone.utc)
+
+
 def _load_week_snapshots(
     since: dt.datetime, until: dt.datetime
 ) -> dict[dt.datetime, float]:
@@ -15073,7 +16941,7 @@ def cmd_project(args: argparse.Namespace) -> int:
 
     # Resolve [since_dt, until_dt] in UTC.
     if args.since or args.until:
-        parsed = _parse_cli_date_range(args)
+        parsed = _parse_cli_date_range(args, now_utc=now)
         if isinstance(parsed, int):
             return parsed
         since_dt, until_dt = parsed
@@ -17011,7 +18879,9 @@ def cmd_session(args: argparse.Namespace) -> int:
     args._resolved_tz = tz
 
     range = _parse_cli_date_range(
-        args, tz_name=(tz.key if tz is not None else None)
+        args,
+        tz_name=(tz.key if tz is not None else None),
+        now_utc=_command_as_of(),
     )
     if isinstance(range, int):
         return range
@@ -19569,12 +21439,48 @@ def cmd_five_hour_breakdown(args: argparse.Namespace) -> int:
         conn.close()
 
 
+# Decimal places retained when normalizing incoming percent floats.
+# Anthropic's `rate_limits.{5h,seven_day}.utilization` is computed as
+# `tokens / cap * 100` server-side and can land one ULP off the rational
+# answer (canonical sighting: `0.07 * 100 == 7.000000000000001`). 10dp
+# is well below any meaningful consumer precision (HWM comparisons
+# clamp at 1dp; JSON exports round to 3dp; floor-snap uses 1e-9) but
+# above IEEE 754 ULP scale near 100, so the round flushes the noise
+# without distorting any meaningful value.
+_PERCENT_NORMALIZE_DECIMALS = 10
+
+
+def _normalize_percent(value: "float | int | None") -> "float | None":
+    """Flush IEEE 754 ULP noise out of an ingress percent value.
+
+    Single chokepoint applied at every site where a raw percent enters
+    cctally's runtime path (OAuth fetch, hook-tick OAuth refresh, and
+    the cmd_record_usage CLI ingress). Downstream consumers — HWM
+    files, ``weekly_usage_snapshots.{weekly,five_hour}_percent`` REAL
+    columns, ``five_hour_blocks.final_five_hour_percent``, milestone
+    crossing values, and the SSE envelope's ``used_percent`` field —
+    all read the cleaned value, so a single round here stops
+    ``5h=7.000000000000001`` style strings from reaching any log or
+    serialized surface.
+
+    ``None`` is the canonical absent-percent sentinel; preserve it
+    unchanged so the optional-5h branches stay simple.
+    """
+    if value is None:
+        return None
+    return round(float(value), _PERCENT_NORMALIZE_DECIMALS)
+
+
 def cmd_record_usage(args: argparse.Namespace) -> int:
     """Record usage data from Claude Code status line rate_limits."""
     config = load_config()
     week_start_name = get_week_start_name(config, getattr(args, "week_start_name", None))
 
-    weekly_percent = float(args.percent)
+    # ULP-noise sanitization is applied at the cmd_record_usage ingress
+    # boundary so every downstream consumer (HWM files, DB rows,
+    # five_hour_blocks rollup, milestones) reads a stable value. See
+    # `_normalize_percent` for the rationale.
+    weekly_percent = _normalize_percent(args.percent)
     resets_at = int(args.resets_at)
 
     five_hour_percent: float | None = None
@@ -19582,7 +21488,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     five_hour_window_key: int | None = None
     five_hour_resets_at_epoch: int | None = None
     if args.five_hour_percent is not None:
-        five_hour_percent = float(args.five_hour_percent)
+        five_hour_percent = _normalize_percent(args.five_hour_percent)
     if args.five_hour_resets_at is not None:
         five_hour_resets_at_epoch = int(args.five_hour_resets_at)
         five_hour_resets_at_str = dt.datetime.fromtimestamp(
@@ -20137,6 +22043,59 @@ def _settings_merge_uninstall(settings: dict) -> tuple[dict, int]:
     return settings, removed
 
 
+def _settings_merge_unwire_legacy(settings: dict) -> tuple[dict, int]:
+    """Remove legacy-bespoke hook entries from ``settings`` in place.
+
+    Mirrors _settings_merge_uninstall's structure but matches against
+    the legacy command set rather than the cctally one. Returns
+    (mutated_settings, removed_count). Empty event lists are dropped.
+    Trailing '&' is stripped before tokenizing so legacy installs that
+    background the daemon-start hook still match.
+    """
+    import shlex as _shlex
+    canonical = {(ev, tuple(_shlex.split(cmd))) for ev, cmd in _LEGACY_BESPOKE_COMMANDS}
+    canonical_raw = {(ev, cmd) for ev, cmd in _LEGACY_BESPOKE_COMMANDS}
+    hooks_root = settings.get("hooks")
+    if not isinstance(hooks_root, dict):
+        return settings, 0
+    removed = 0
+    for ev in [k for k in hooks_root.keys()]:  # snapshot keys; we may del
+        lst = hooks_root.get(ev)
+        if not isinstance(lst, list):
+            continue
+        new_list: list = []
+        for grp in lst:
+            if not isinstance(grp, dict):
+                new_list.append(grp)
+                continue
+            inner = grp.get("hooks", [])
+            if not isinstance(inner, list):
+                new_list.append(grp)
+                continue
+            kept_inner = []
+            for h in inner:
+                cmd = h.get("command", "") if isinstance(h, dict) else ""
+                stripped = cmd.strip().rstrip("&").strip() if isinstance(cmd, str) else ""
+                try:
+                    tokens = tuple(_shlex.split(stripped))
+                except ValueError:
+                    kept_inner.append(h)
+                    continue
+                if (ev, tokens) in canonical or (ev, stripped) in canonical_raw:
+                    removed += 1
+                    continue
+                kept_inner.append(h)
+            if kept_inner:
+                grp["hooks"] = kept_inner
+                new_list.append(grp)
+            # else: matcher group's only entry was ours → drop the group
+        if new_list:
+            hooks_root[ev] = new_list
+        else:
+            del hooks_root[ev]
+    return settings, removed
+
+
 def _hook_tick_log_line(line: str) -> None:
     """Append one line to hook-tick.log; create dir if missing.
 
@@ -20329,7 +22288,11 @@ def _refresh_usage_inproc(timeout_seconds: float = 5.0) -> _RefreshUsageResult:
 
     seven = api.get("seven_day") or {}
     try:
-        seven_pct = float(seven["utilization"])
+        # Normalize at the OAuth ingress so the payload JSON published
+        # on the SSE envelope (`used_percent` field) is clean even when
+        # this code path doesn't reach cmd_record_usage (e.g. payload
+        # built then a downstream cmd_record_usage call fails).
+        seven_pct = _normalize_percent(float(seven["utilization"]))
         seven_resets_iso = seven["resets_at"]
         seven_resets_epoch = _iso_to_epoch(seven_resets_iso)
     except (TypeError, ValueError, KeyError) as exc:
@@ -20345,7 +22308,7 @@ def _refresh_usage_inproc(timeout_seconds: float = 5.0) -> _RefreshUsageResult:
     warnings: list = []
     if five is not None and "utilization" in five and "resets_at" in five:
         try:
-            five_pct = float(five["utilization"])
+            five_pct = _normalize_percent(float(five["utilization"]))
             five_resets_iso = five["resets_at"]
             five_resets_epoch = _iso_to_epoch(five_resets_iso)
         except (TypeError, ValueError) as exc:
@@ -20555,7 +22518,7 @@ def _hook_tick_oauth_refresh(
         return "err(parse)", None
     seven = api["seven_day"]
     try:
-        seven_pct = float(seven["utilization"])
+        seven_pct = _normalize_percent(float(seven["utilization"]))
         seven_resets_epoch = _iso_to_epoch(seven["resets_at"])
     except (TypeError, ValueError, KeyError):
         return "err(parse)", None
@@ -20564,7 +22527,7 @@ def _hook_tick_oauth_refresh(
     five_resets_epoch: int | None = None
     if five is not None and "utilization" in five and "resets_at" in five:
         try:
-            five_pct = float(five["utilization"])
+            five_pct = _normalize_percent(float(five["utilization"]))
             five_resets_epoch = _iso_to_epoch(five["resets_at"])
         except (TypeError, ValueError):
             five_pct = None
@@ -21731,6 +23694,25 @@ def _setup_shell_rc_hint() -> str:
     return "your shell rc"
 
 
+# Legacy bespoke hook set — see docs/superpowers/specs/2026-05-09-auto-migrate-legacy-hooks-design.md
+_LEGACY_BESPOKE_HOOKS_DIR = pathlib.Path.home() / ".claude" / "hooks"
+_LEGACY_BESPOKE_COMMANDS: tuple[tuple[str, str], ...] = (
+    ("Stop",          "python3 ~/.claude/hooks/record-usage-stop.py"),
+    ("SubagentStart", "python3 ~/.claude/hooks/usage-poller-start.py"),
+    ("SubagentStop",  "python3 ~/.claude/hooks/usage-poller-stop.py"),
+)
+_LEGACY_BESPOKE_FILENAMES: tuple[str, ...] = (
+    "record-usage-stop.py",
+    "usage-poller-start.py",
+    "usage-poller-stop.py",
+    "usage-poller.py",
+)
+_LEGACY_POLLER_PID_FILE = pathlib.Path("/tmp/claude-usage-poller.pid")
+_LEGACY_POLLER_COUNT_FILE = pathlib.Path("/tmp/claude-usage-poller.count")
+_LEGACY_BACKUP_DIR_PREFIX = "cctally-legacy-hook-backup-"
+_LEGACY_POLLER_SIGTERM_GRACE_S = 0.250
+
+
 def _setup_detect_legacy_snippet() -> tuple[pathlib.Path, list[int]] | None:
     """Return (path, [line_numbers]) of the first file containing the snippet, or None."""
     for path in LEGACY_STATUSLINE_PATHS:
@@ -21746,6 +23728,314 @@ def _setup_detect_legacy_snippet() -> tuple[pathlib.Path, list[int]] | None:
     return None
 
 
+def _setup_detect_legacy_bespoke_hooks(settings: dict) -> dict:
+    """Detect legacy bespoke hook state per spec Section 1.
+
+    Detection fires when ANY of the 3 canonical settings.json command
+    strings matches an installed entry, OR ANY of the 4 canonical
+    .py files exists at its canonical path under _LEGACY_BESPOKE_HOOKS_DIR.
+
+    Returns a dict with keys:
+      detected: bool
+      settings_entries: list of {"event": str, "command": str}
+      files: list of str (rendered with ~/.claude/hooks/ prefix)
+    """
+    import shlex as _shlex
+    canonical_cmds = {(ev, cmd) for ev, cmd in _LEGACY_BESPOKE_COMMANDS}
+    canonical_tokens = {(ev, tuple(_shlex.split(cmd))) for ev, cmd in _LEGACY_BESPOKE_COMMANDS}
+
+    found_entries: list[dict] = []
+    hooks_root = settings.get("hooks", {}) if isinstance(settings, dict) else {}
+    if isinstance(hooks_root, dict):
+        for event, lst in hooks_root.items():
+            if not isinstance(lst, list):
+                continue
+            matched_for_this_event = False
+            for grp in lst:
+                if matched_for_this_event:
+                    break  # already recorded one row for this event; don't double-count
+                if not isinstance(grp, dict):
+                    continue
+                inner = grp.get("hooks", [])
+                if not isinstance(inner, list):
+                    # Mirrors the unwire helper's defensive guard: malformed
+                    # `hooks` value (None / int / dict) must not crash iteration.
+                    continue
+                for h in inner:
+                    if not isinstance(h, dict):
+                        continue
+                    raw = h.get("command", "")
+                    if not isinstance(raw, str):
+                        continue
+                    stripped = raw.strip().rstrip("&").strip()
+                    try:
+                        tokens = tuple(_shlex.split(stripped))
+                    except ValueError:
+                        continue
+                    if (event, tokens) in canonical_tokens or (event, stripped) in canonical_cmds:
+                        # Record the canonical (clean) form for stable JSON output,
+                        # not the user's possibly-decorated raw command.
+                        clean_cmd = next(
+                            cmd for ev, cmd in _LEGACY_BESPOKE_COMMANDS if ev == event
+                        )
+                        found_entries.append({"event": event, "command": clean_cmd})
+                        matched_for_this_event = True
+                        break  # one entry per matcher group is enough
+
+    found_files: list[str] = []
+    for name in _LEGACY_BESPOKE_FILENAMES:
+        p = _LEGACY_BESPOKE_HOOKS_DIR / name
+        if p.exists():
+            # Render with the ~ prefix the spec uses for stable JSON.
+            found_files.append(f"~/.claude/hooks/{name}")
+
+    return {
+        "detected": bool(found_entries) or bool(found_files),
+        "settings_entries": found_entries,
+        "files": found_files,
+    }
+
+
+def _legacy_resolve_backup_dir() -> pathlib.Path:
+    """Return ~/.claude/cctally-legacy-hook-backup-<UTC YYYYMMDD-HHMMSS>/.
+
+    Honors CCTALLY_AS_OF for fixture stability via _command_as_of(). Created
+    on demand. Idempotent within the same wall-second (mkdir(exist_ok=True)).
+
+    See spec Section 1 ("What gets touched on accept" → step 2) and
+    Section 2 ("Sequence position", step 6a). Backup dir is timestamped
+    so a re-run never overwrites a prior migration's snapshot.
+    """
+    now = _command_as_of()
+    stamp = now.strftime("%Y%m%d-%H%M%S")
+    base = pathlib.Path.home() / ".claude" / f"{_LEGACY_BACKUP_DIR_PREFIX}{stamp}"
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+def _legacy_move_files_to_backup(backup_dir: pathlib.Path) -> list[pathlib.Path]:
+    """Move present canonical .py files from `_LEGACY_BESPOKE_HOOKS_DIR` into backup_dir.
+
+    Each canonical filename is moved only if present at its canonical path;
+    missing files are silent no-ops (per spec Section 1: "Missing files are
+    silent no-ops in the move loop"). Returns the list of destination paths
+    actually written, in canonical (`_LEGACY_BESPOKE_FILENAMES`) order.
+
+    Uses `shutil.move` (canonical Python idiom): same-filesystem renames
+    go through `os.rename`, cross-device moves fall through to
+    `copy2 + unlink` atomically — and a failure on the unlink leg raises
+    `OSError` instead of silently leaving a duplicate at both src and dst
+    (which the prior hand-rolled try/except/inner-try did).
+    """
+    moved: list[pathlib.Path] = []
+    for name in _LEGACY_BESPOKE_FILENAMES:
+        src = _LEGACY_BESPOKE_HOOKS_DIR / name
+        if not src.exists():
+            continue
+        dst = backup_dir / name
+        try:
+            shutil.move(str(src), str(dst))
+        except OSError:
+            # Best-effort: a failed move is silent; spec Section 1 step 2
+            # treats the move loop's failures as no-ops (the daemon-stop
+            # follow-up handles user-facing damage control).
+            continue
+        moved.append(dst)
+    return moved
+
+
+def _legacy_stop_active_poller() -> str:
+    """Best-effort SIGTERM (then SIGKILL) the bespoke daemon if alive.
+
+    Per spec Section 1 step 3: read /tmp/claude-usage-poller.pid, send
+    SIGTERM, wait `_LEGACY_POLLER_SIGTERM_GRACE_S`, send SIGKILL if still
+    alive. All steps are best-effort and silent on failure — the daemon
+    may already be dead, the PID may be stale, the rlimits may forbid
+    signaling, or the file may simply be absent.
+
+    Returns one of:
+      "no-pid-file"       — no /tmp/claude-usage-poller.pid present
+      "stale-pid"         — PID file exists but the PID isn't a live
+                            process, parse failed, OR the live PID's
+                            cmdline doesn't reference usage-poller.py
+                            (collapsed: don't signal an unrelated process)
+      "sigterm-took"      — SIGTERM landed and the process exited within
+                            the grace window
+      "sigkill-took"      — SIGTERM did not stop it; SIGKILL landed
+      "permission-denied" — kernel refused to signal the PID (EPERM)
+    """
+    import signal as _signal
+
+    if not _LEGACY_POLLER_PID_FILE.exists():
+        return "no-pid-file"
+    try:
+        raw = _LEGACY_POLLER_PID_FILE.read_text(encoding="utf-8", errors="replace").strip()
+        pid = int(raw)
+    except (OSError, ValueError):
+        # Unreadable or non-numeric content → treat as stale (a corrupted
+        # PID file is functionally indistinguishable from a stale one;
+        # the cleanup helper will unlink it next).
+        return "stale-pid"
+
+    # Aliveness probe: signal 0 doesn't deliver but does the permission
+    # + existence check. ProcessLookupError → stale; PermissionError →
+    # we'd fail the actual signal too, surface that distinctly.
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return "stale-pid"
+    except PermissionError:
+        return "permission-denied"
+    except OSError:
+        return "stale-pid"
+
+    # Ownership probe: the PID file is at a predictable /tmp path that
+    # outlives the daemon on uncleanly exit, and macOS PIDs cycle in a
+    # narrow space — verify the live process is actually our legacy
+    # poller before signaling. ps's `-o command=` emits the full cmdline
+    # with no header on both macOS BSD ps and Linux util-linux ps.
+    try:
+        probe = subprocess.run(
+            ["ps", "-p", str(pid), "-o", "command="],
+            capture_output=True, text=True, timeout=2.0,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        # Can't verify → don't signal. Treat as stale: a corrupted /tmp
+        # sentinel is functionally equivalent to a missing process here.
+        return "stale-pid"
+    if probe.returncode != 0 or "usage-poller.py" not in probe.stdout:
+        return "stale-pid"
+
+    # Process is alive AND owned by the legacy poller. SIGTERM, then poll
+    # for exit within the grace.
+    try:
+        os.kill(pid, _signal.SIGTERM)
+    except ProcessLookupError:
+        # Race: process exited between probe and signal — treat as success.
+        return "sigterm-took"
+    except PermissionError:
+        return "permission-denied"
+    except OSError:
+        # Residual OSError after ProcessLookupError/PermissionError are caught
+        # specifically — exotic kernel refusal (ENOMEM during signal queueing,
+        # LSM denial, etc.). Map to permission-denied: spec contract forbids
+        # raising, and "we couldn't deliver the signal" is the closest existing
+        # outcome.
+        return "permission-denied"
+
+    deadline = time.monotonic() + _LEGACY_POLLER_SIGTERM_GRACE_S
+    while time.monotonic() < deadline:
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return "sigterm-took"
+        except OSError:
+            return "sigterm-took"
+        time.sleep(0.01)
+
+    # Still alive after grace → SIGKILL fallback.
+    try:
+        os.kill(pid, _signal.SIGKILL)
+    except ProcessLookupError:
+        # Exited just at the grace boundary — count as SIGTERM-took.
+        return "sigterm-took"
+    except PermissionError:
+        return "permission-denied"
+    except OSError:
+        # Same residual-OSError category as the SIGTERM site above.
+        return "permission-denied"
+    return "sigkill-took"
+
+
+def _legacy_cleanup_tmp_sentinels() -> list[str]:
+    """Unlink the bespoke poller's PID + count files. Best-effort; missing
+    files are silent no-ops (FileNotFoundError) and so are unwritable
+    parents (OSError). Returns the paths actually unlinked, as strings,
+    in canonical (pid, count) order.
+
+    Per spec Section 1 step 3 and Section 2 step 6b — runs after the
+    SIGTERM/SIGKILL helper so a successful daemon stop also clears the
+    sentinels it left on /tmp.
+    """
+    unlinked: list[str] = []
+    for p in (_LEGACY_POLLER_PID_FILE, _LEGACY_POLLER_COUNT_FILE):
+        try:
+            p.unlink()
+        except FileNotFoundError:
+            continue
+        except OSError:
+            continue
+        unlinked.append(str(p))
+    return unlinked
+
+
+def _setup_read_legacy_prompt_input(stream, reprompt: str | None = None) -> bool:
+    """Read a y/N answer from `stream` per spec Section 2 prompt rules.
+
+    Empty input (just Enter) → True (the documented default).
+    'y'/'yes' (any case) → True.
+    'n'/'no' (any case) → False.
+    EOF before any character → False (decline; explicitly NOT default-Y, so
+    non-TTY callers can't auto-accept via inherited stdin closure).
+    Anything else → re-prompt up to 3 times, then False with a stderr warning.
+
+    `reprompt`: optional text to emit to stderr before each attempt AFTER the
+    first (the caller already printed the original prompt body before calling
+    us). When None (test default), no reprompt is emitted — useful for unit
+    tests that drive `stream` from io.StringIO.
+    """
+    yes_words = {"y", "yes"}
+    no_words = {"n", "no"}
+    for attempt in range(3):
+        if attempt > 0 and reprompt is not None:
+            eprint(reprompt)
+        line = stream.readline()
+        if line == "":
+            return False  # EOF → decline
+        token = line.strip().lower()  # whitespace-only counts as "just Enter" → default-Y
+        if token == "":
+            return True
+        if token in yes_words:
+            return True
+        if token in no_words:
+            return False
+    eprint("setup: invalid responses 3 times; skipping migration")
+    return False
+
+
+def _setup_legacy_decide_action(args, detected: bool, stdin_isatty: bool) -> tuple[str, str | None]:
+    """Decide migration action without performing prompt I/O.
+
+    Returns (decision, reason) where decision is one of:
+      - "migrate" — proceed with migration
+      - "skip" — do not migrate; reason is one of "not_detected" /
+        "no_migrate_flag" / "user_declined". This helper never returns
+        "user_declined"; that reason is set by the caller after a
+        "prompt" decision yields a No answer from
+        _setup_read_legacy_prompt_input.
+      - "prompt" — caller must read user input via the prompt helper.
+
+    Spec Section 2 prompt rules: detection short-circuits, explicit flags
+    are decisive, --yes implies migrate, --json or non-TTY without a flag
+    skips silently (the JSON envelope and unattended runs both need a
+    no-blocking-input contract). When none of those hold, the caller is
+    in interactive install with detected hooks → prompt.
+    """
+    if not detected:
+        return ("skip", "not_detected")
+    if getattr(args, "no_migrate_legacy_hooks", False):
+        return ("skip", "no_migrate_flag")
+    if getattr(args, "migrate_legacy_hooks", False):
+        return ("migrate", None)
+    if getattr(args, "yes", False):
+        return ("migrate", None)
+    if not stdin_isatty:
+        return ("skip", "no_migrate_flag")
+    if getattr(args, "json", False):
+        return ("skip", "no_migrate_flag")
+    return ("prompt", None)
+
+
 def _setup_oauth_token_present() -> bool:
     try:
         return bool(_resolve_oauth_token())
@@ -21863,6 +24153,7 @@ def _setup_status(args: argparse.Namespace) -> int:
     throttle_age = _hook_tick_throttle_age_seconds()
     activity = _setup_recent_log_stats()
     legacy = _setup_detect_legacy_snippet()
+    bespoke = _setup_detect_legacy_bespoke_hooks(settings)
     data_bytes = _setup_data_dir_size_bytes()
 
     if getattr(args, "json", False):
@@ -21881,7 +24172,14 @@ def _setup_status(args: argparse.Namespace) -> int:
                 ),
             },
             "activity_24h": activity,
-            "legacy": {"statusline_snippet": str(legacy[0]) if legacy else None},
+            "legacy": {
+                "statusline_snippet": str(legacy[0]) if legacy else None,
+                "bespoke_hooks": {
+                    "detected": bespoke["detected"],
+                    "settings_entries": bespoke["settings_entries"],
+                    "files": bespoke["files"],
+                },
+            },
             "data": {"path": str(APP_DIR), "size_bytes": data_bytes},
         }
         print(json.dumps(envelope, indent=2))
@@ -21919,6 +24217,15 @@ def _setup_status(args: argparse.Namespace) -> int:
         out.append("  status-line snippet  not detected                     ✓")
     else:
         out.append(f"  status-line snippet  detected at {legacy[0]}:{legacy[1][0]}  ⚠")
+    if not bespoke["detected"]:
+        out.append("  bespoke hooks        not detected                     ✓")
+    else:
+        n_entries = len(bespoke["settings_entries"])
+        n_files = len(bespoke["files"])
+        out.append(
+            f"  bespoke hooks        detected ({n_entries} entries, {n_files} files)    ⚠"
+        )
+        out.append("                       run `cctally setup --migrate-legacy-hooks` to migrate")
     out.append("Data")
     out.append(f"  {APP_DIR}/    {_setup_format_bytes(data_bytes)}")
     _setup_emit_text(out)
@@ -22054,6 +24361,16 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
 def _setup_dry_run(args: argparse.Namespace) -> int:
     repo_root = _setup_resolve_repo_root()
     dst_dir = _setup_local_bin_dir()
+    try:
+        settings = _load_claude_settings()
+    except SetupError as exc:
+        # Malformed settings.json — preview still proceeds; legacy detection
+        # against an empty dict simply yields detected=False for entries (files
+        # detection is independent of settings). Mirror _setup_status's pattern
+        # so the user sees the same condition that would fail _setup_install.
+        eprint(f"setup: warning: {exc}")
+        settings = {}
+    detection = _setup_detect_legacy_bespoke_hooks(settings)
     sym_results = []
     for name in SETUP_SYMLINK_NAMES:
         dst = dst_dir / name
@@ -22086,12 +24403,63 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
             f"  hooks.{ev}[*] += {{ matcher: {matcher}, "
             f"command: \"{quoted} hook-tick\" }}"
         )
+    # Spec §2 mode×flag matrix — three distinct dry-run rendering paths
+    # when legacy is detected:
+    #   --dry-run --no-migrate-legacy-hooks → migration block omitted entirely
+    #   --dry-run --migrate-legacy-hooks (or --yes) → full migration plan
+    #   --dry-run (no migrate flag) → full plan prefixed with the
+    #       "would prompt; pass --migrate-legacy-hooks…" note
+    # `--yes` is treated as equivalent to `--migrate-legacy-hooks` to
+    # match `_setup_decide_legacy_migration` (bin/cctally:22094-22101).
+    no_migrate_flag = bool(getattr(args, "no_migrate_legacy_hooks", False))
+    migrate_flag = bool(getattr(args, "migrate_legacy_hooks", False))
+    yes_flag = bool(getattr(args, "yes", False))
+    show_full_migration_plan = migrate_flag or yes_flag
+    show_migration_block = detection["detected"] and not no_migrate_flag
+    if show_migration_block:
+        if not show_full_migration_plan:
+            # No-flag dry-run: prefix the block with the would-prompt note.
+            out.append(
+                "Would prompt for migration; pass --migrate-legacy-hooks to "
+                "preview the migration plan."
+            )
+        out.append("Would migrate legacy bespoke hooks:")
+        if detection["settings_entries"]:
+            out.append(
+                f"  Would remove {len(detection['settings_entries'])} "
+                f"entries from settings.json:"
+            )
+            for e in detection["settings_entries"]:
+                out.append(f"    hooks.{e['event']:13s} ← {e['command']}")
+        files_present = [f.split('/')[-1] for f in detection["files"]]
+        if files_present:
+            out.append(
+                f"  Would move {len(files_present)} files to "
+                f"~/.claude/cctally-legacy-hook-backup-<UTC ts>/:"
+            )
+            out.append(f"    {', '.join(files_present)}")
+        out.append("  Would attempt cleanup of /tmp/claude-usage-poller.{pid,count}")
     out.append("Would not modify ~/.claude/statusline-command.sh")
     out.append("Would not delete any data")
     out.append("")
     out.append("Re-run without --dry-run to apply.")
 
     if getattr(args, "json", False):
+        # Decision label mirrors `_setup_decide_legacy_migration`'s output:
+        # `migrate` (full plan / explicit opt-in or --yes), `skip`
+        # (--no-migrate-legacy-hooks), or `prompt` (no flag — install would
+        # prompt the user). When no legacy is detected the label is
+        # `not_detected` so consumers can distinguish "no-op" from
+        # "explicit skip."
+        if not detection["detected"]:
+            decision = "not_detected"
+        elif no_migrate_flag:
+            decision = "skip"
+        elif show_full_migration_plan:
+            decision = "migrate"
+        else:
+            decision = "prompt"
+        legacy_path = _setup_detect_legacy_snippet()
         envelope = {
             "schema_version": 1,
             "mode": "dry-run",
@@ -22113,6 +24481,39 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
                 ],
                 "settings_path": str(CLAUDE_SETTINGS_PATH),
             },
+            # Sibling parity with `_setup_status` and `_setup_install`
+            # JSON envelopes (`legacy.bespoke_hooks` shape). Lets the same
+            # consumer query bespoke-hook state from any of the three
+            # commands uniformly.
+            "legacy": {
+                "statusline_snippet": str(legacy_path[0]) if legacy_path else None,
+                "bespoke_hooks": {
+                    "detected": detection["detected"],
+                    "settings_entries": detection["settings_entries"],
+                    "files": detection["files"],
+                },
+            },
+            # Flag-aware preview block. `decision` records what the
+            # install path would do; `would_remove_entries` /
+            # `would_move_files` are the rendered plan (empty when
+            # decision == "skip" or "not_detected").
+            "migration_preview": {
+                "detected": detection["detected"],
+                "decision": decision,
+                "would_remove_entries": (
+                    []
+                    if decision in ("skip", "not_detected")
+                    else [
+                        {"event": e["event"], "command": e["command"]}
+                        for e in detection["settings_entries"]
+                    ]
+                ),
+                "would_move_files": (
+                    []
+                    if decision in ("skip", "not_detected")
+                    else list(detection["files"])
+                ),
+            },
             "exit_code": 0,
         }
         print(json.dumps(envelope, indent=2))
@@ -22127,6 +24528,37 @@ def _setup_emit_text(lines: list[str]) -> None:
         print(ln)
 
 
+def _setup_render_legacy_prompt(detection: dict) -> str:
+    """Return the multi-line prompt body per spec Section 2.
+
+    Renders the ⚠ header, one row per detected (event → file) settings
+    entry, an optional daemon-source line for usage-poller.py, the
+    explanation of the silent failure mode, and the [Y/n] question.
+    Caller is expected to print the body once and then dispatch to
+    `_setup_read_legacy_prompt_input` for the actual answer.
+    """
+    lines = ["⚠ Detected legacy bespoke hooks (predate `cctally setup`):"]
+    by_event = {e["event"]: e["command"] for e in detection["settings_entries"]}
+    for ev in ("Stop", "SubagentStart", "SubagentStop"):
+        cmd = by_event.get(ev, "")
+        if cmd:
+            file_part = cmd.replace("python3 ", "")
+            lines.append(f"    {file_part:38s}  →  hooks.{ev}")
+    if any("usage-poller.py" in f for f in detection["files"]):
+        lines.append("    ~/.claude/hooks/usage-poller.py            (daemon spawned by usage-poller-start.py)")
+    lines += [
+        "",
+        "  Their delegate binary isn't on PATH on this system — every fire has",
+        "  been silently failing.",
+        "",
+        "  Migrate now? Will unwire the settings.json entries and move the .py files",
+        "  to ~/.claude/cctally-legacy-hook-backup-<UTC ts>/. Reversible.",
+        "",
+        "  Migrate? [Y/n]",
+    ]
+    return "\n".join(lines)
+
+
 def _setup_install(args: argparse.Namespace) -> int:
     """Install path. Returns exit code per Section 2 of spec."""
     out: list[str] = []
@@ -22157,6 +24589,60 @@ def _setup_install(args: argparse.Namespace) -> int:
     except SetupError as exc:
         eprint(f"setup: {exc}")
         return 1
+
+    # ── Legacy bespoke hook detection + migration decision (spec §1, §2) ──
+    # Detection is read-only on the in-memory settings dict; decision is
+    # pure (no I/O); the prompt fires only when the decision helper
+    # returns "prompt" (TTY + no flag + not --json). All three must run
+    # BEFORE `_settings_merge_install` so the unwire+add land in the same
+    # atomic write at sequence position 6.
+    detection = _setup_detect_legacy_bespoke_hooks(settings)
+    decision, reason = _setup_legacy_decide_action(
+        args,
+        detected=detection["detected"],
+        stdin_isatty=sys.stdin.isatty(),
+    )
+    if decision == "prompt":
+        print(_setup_render_legacy_prompt(detection))
+        accepted = _setup_read_legacy_prompt_input(
+            sys.stdin,
+            reprompt="Please answer y or n. Migrate? [Y/n]",
+        )
+        decision = "migrate" if accepted else "skip"
+        if not accepted:
+            reason = "user_declined"
+
+    migration_summary: dict = {
+        "performed": False,
+        "reason": reason or "not_detected",
+    }
+
+    backup_dir: pathlib.Path | None = None
+    if decision == "migrate":
+        # Resolve the backup dir BEFORE mutating settings.json so a
+        # mkdir failure (parent unwriteable, name collision with a
+        # regular file, ENOSPC, …) doesn't leave the on-disk settings
+        # in a half-applied state — legacy entries gone but .py files
+        # never moved. Pre-resolving also pins the timestamp shared
+        # between the dir name and JSON envelope.
+        try:
+            backup_dir = _legacy_resolve_backup_dir()
+        except OSError as exc:
+            eprint(f"setup: cannot create migration backup dir: {exc}")
+            return 1
+        # Unwire BEFORE the merge so the same atomic write removes legacy
+        # entries and adds cctally entries (spec §2 step 6).
+        settings, n_unwired = _settings_merge_unwire_legacy(settings)
+        migration_summary = {
+            "performed": True,
+            "settings_entries_removed": n_unwired,
+            "files_moved": 0,
+            "backup_dir": None,
+            "active_poller_pid_signaled": None,
+            "active_poller_kill_outcome": None,
+            "tmp_files_unlinked": [],
+        }
+
     try:
         _settings_merge_install(settings, abs_path)
     except SetupError as exc:
@@ -22196,8 +24682,76 @@ def _setup_install(args: argparse.Namespace) -> int:
     except OSError as exc:
         eprint(f"setup: failed to write {CLAUDE_SETTINGS_PATH}: {exc}")
         return 2
+
+    # ── Post-write migration apply (spec §2 steps 6a, 6b) ──
+    # Settings.json is now durable. File moves, poller stop, and tmp
+    # cleanup are best-effort and may emit a partial-move warning, but
+    # do NOT roll back the on-disk settings.json. Per spec §2 exit-code
+    # table, partial-move failures are uniformly exit-0-with-warning.
+    if decision == "migrate":
+        # `backup_dir` was resolved early (pre-write) so the mkdir
+        # failure path can fail fast with no settings.json mutation.
+        assert backup_dir is not None
+        # Snapshot what we expected to move BEFORE the move so we can
+        # detect partial failure cleanly (post-loop, src files are gone).
+        expected_to_move = [
+            n for n in _LEGACY_BESPOKE_FILENAMES
+            if (_LEGACY_BESPOKE_HOOKS_DIR / n).exists()
+        ]
+        moved = _legacy_move_files_to_backup(backup_dir)
+        migration_summary["files_moved"] = len(moved)
+        migration_summary["backup_dir"] = str(backup_dir)
+        if len(moved) < len(expected_to_move):
+            orphans = sorted(set(expected_to_move) - {p.name for p in moved})
+            out.append(
+                f"⚠ Partial file move: {len(moved)} of {len(expected_to_move)} expected "
+                f"files moved. Orphans: {', '.join(orphans)}"
+            )
+            warnings += 1
+
+        # Active-poller stop + tmp-sentinel cleanup (best-effort, silent
+        # on failure per spec §2 step 6b). Capture the pre-stop PID for
+        # the JSON envelope since the helper itself returns only the
+        # outcome string.
+        pid_signaled: int | None = None
+        if _LEGACY_POLLER_PID_FILE.exists():
+            try:
+                pid_signaled = int(
+                    _LEGACY_POLLER_PID_FILE.read_text(encoding="utf-8", errors="replace").strip()
+                )
+            except (OSError, ValueError):
+                pass
+        kill_outcome = _legacy_stop_active_poller()
+        # Per spec §3 (`active_poller_pid_signaled` semantics): record the
+        # PID only when we actually attempted to deliver a signal. Stale-PID
+        # and no-pid-file outcomes are read-only paths, so the JSON envelope
+        # should reflect "no signal sent" with a null PID.
+        if kill_outcome not in {"sigterm-took", "sigkill-took", "permission-denied"}:
+            pid_signaled = None
+        migration_summary["active_poller_pid_signaled"] = pid_signaled
+        migration_summary["active_poller_kill_outcome"] = kill_outcome
+        migration_summary["tmp_files_unlinked"] = _legacy_cleanup_tmp_sentinels()
+
+        out.append(
+            f"✓ Migrated {migration_summary['settings_entries_removed']} legacy hook entries "
+            f"→ moved {len(moved)} files to {backup_dir}/"
+        )
+
+    # The "✓ Wrote …" line follows any migrate-summary line so the
+    # narrative reads "we did the migration, then wrote the new entries"
+    # — matches the spec's success-path sample (Section 2).
     out.append(f"✓ Wrote {len(SETUP_HOOK_EVENTS)} hook entries to {CLAUDE_SETTINGS_PATH}")
 
+    if decision == "skip" and reason in {"user_declined", "no_migrate_flag"}:
+        files_str = "{record-usage-stop,usage-poller{,-start,-stop}}.py"
+        out.append(
+            f"⚠ Legacy bespoke hooks detected (predate `cctally setup`; failing "
+            f"silently on this system). Skipped at your request. Re-run "
+            f"`cctally setup --migrate-legacy-hooks` later, or remove them yourself. "
+            f"The four `.py` files are at ~/.claude/hooks/{files_str}."
+        )
+        warnings += 1
+
     oauth = _setup_oauth_token_present()
     if oauth:
         out.append("✓ Detected OAuth token")
@@ -22254,13 +24808,22 @@ def _setup_install(args: argparse.Namespace) -> int:
 
     out.append("")
     if warnings:
-        out.append(f"cctally is ready (with {warnings} warning(s) above). Try:")
+        out.append(f"cctally is ready (with {warnings} warning(s) above).")
     else:
-        out.append("cctally is ready. Try:")
-    out.append("  cctally daily              # last 30 days")
-    out.append("  cctally dashboard          # live web dashboard")
-    out.append("  cctally tui                # terminal dashboard")
-    out.append("  cctally setup --status     # verify install state")
+        out.append("cctally is ready.")
+    out.append("")
+    # Settings.json was modified — CC caches it at session start. The
+    # warning fires unconditionally because `_setup_install` always
+    # rewrites settings.json (legacy migration, fresh install, repair).
+    out.append("⚠ Restart Claude Code for the new hooks to take effect in any currently")
+    out.append("  open sessions. New sessions launched after this point pick them up")
+    out.append("  automatically. (settings.json is cached at session start.)")
+    out.append("")
+    out.append("  Try:")
+    out.append("    cctally daily              # last 30 days")
+    out.append("    cctally dashboard          # live web dashboard")
+    out.append("    cctally tui                # terminal dashboard")
+    out.append("    cctally setup --status     # verify install state")
 
     if getattr(args, "json", False):
         envelope = {
@@ -22284,7 +24847,13 @@ def _setup_install(args: argparse.Namespace) -> int:
             "path_includes_local_bin": _setup_path_includes_local_bin(),
             "legacy": {
                 "statusline_snippet_path": str(legacy[0]) if legacy else None,
+                "bespoke_hooks": {
+                    "detected": detection["detected"],
+                    "settings_entries": detection["settings_entries"],
+                    "files": detection["files"],
+                },
             },
+            "migration": migration_summary,
             "bootstrap": {
                 "session_cache_rows": bootstrap_rows,
                 "oauth_status": bootstrap_oauth_status,
@@ -22299,7 +24868,13 @@ def _setup_install(args: argparse.Namespace) -> int:
     return 0
 
 
-ALLOWED_CONFIG_KEYS = ("display.tz", "alerts.enabled", "dashboard.bind")
+ALLOWED_CONFIG_KEYS = (
+    "display.tz",
+    "alerts.enabled",
+    "dashboard.bind",
+    "update.check.enabled",
+    "update.check.ttl_hours",
+)
 
 
 def cmd_config(args: argparse.Namespace) -> int:
@@ -22353,6 +24928,26 @@ def _config_known_value(config: dict, key: str) -> "object":
             # Hand-edited junk: surface the default rather than the bad value;
             # `cmd_dashboard` warns at server-start when it hits the same path.
             return "loopback"
+    if key in ("update.check.enabled", "update.check.ttl_hours"):
+        # Defaults mirror `_is_update_check_due` (True / 24 hours).
+        # Hand-edited junk surfaces as the default — matches dashboard.bind.
+        update_block = (
+            config.get("update") if isinstance(config, dict) else None
+        )
+        if not isinstance(update_block, dict):
+            update_block = {}
+        check_block = update_block.get("check")
+        if not isinstance(check_block, dict):
+            check_block = {}
+        if key == "update.check.enabled":
+            stored = check_block.get("enabled", True)
+            return bool(stored) if isinstance(stored, bool) else True
+        # update.check.ttl_hours
+        stored = check_block.get("ttl_hours", UPDATE_DEFAULT_TTL_HOURS)
+        try:
+            return _validate_update_check_ttl_hours_value(stored)
+        except ValueError:
+            return UPDATE_DEFAULT_TTL_HOURS
     return None
 
 
@@ -22371,10 +24966,18 @@ def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
         pairs.append((key, v if v is not None else ""))
 
     if getattr(args, "emit_json", False):
-        out: "dict[str, dict]" = {}
+        # Walk every dot-delimited segment so keys deeper than two
+        # segments (e.g. `update.check.enabled`) nest correctly. The
+        # earlier `partition` form collapsed three-segment keys into
+        # a flat tail (`{"update": {"check.enabled": ...}}`) and
+        # diverged from `config set --json` / on-disk shape.
+        out: "dict[str, object]" = {}
         for k, v in pairs:
-            head, _, tail = k.partition(".")
-            out.setdefault(head, {})[tail] = v
+            segments = k.split(".")
+            node: dict = out
+            for seg in segments[:-1]:
+                node = node.setdefault(seg, {})
+            node[segments[-1]] = v
         print(json.dumps(out, indent=2))
     else:
         for k, v in pairs:
@@ -22479,6 +25082,53 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"dashboard.bind={canonical}")
         return 0
+    if key in ("update.check.enabled", "update.check.ttl_hours"):
+        # Validate first; rejection short-circuits before lock acquisition.
+        if key == "update.check.enabled":
+            try:
+                normalized: object = _normalize_update_check_enabled_value(raw)
+            except ValueError as exc:
+                print(f"cctally: {exc}", file=sys.stderr)
+                return 2
+            inner_key = "enabled"
+        else:
+            try:
+                normalized = _validate_update_check_ttl_hours_value(raw)
+            except ValueError as exc:
+                print(f"cctally: {exc}", file=sys.stderr)
+                return 2
+            inner_key = "ttl_hours"
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing_update = config.get("update")
+            if existing_update is not None and not isinstance(existing_update, dict):
+                print(
+                    "cctally: update config error: update must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            update_block = dict(existing_update or {})
+            existing_check = update_block.get("check")
+            if existing_check is not None and not isinstance(existing_check, dict):
+                print(
+                    "cctally: update config error: update.check must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            check_block = dict(existing_check or {})
+            check_block[inner_key] = normalized
+            update_block["check"] = check_block
+            config["update"] = update_block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"update": {"check": {inner_key: normalized}}}, indent=2))
+        else:
+            if isinstance(normalized, bool):
+                rendered = "true" if normalized else "false"
+            else:
+                rendered = str(normalized)
+            print(f"{key}={rendered}")
+        return 0
     return 2  # unreachable given the gate above
 
 
@@ -22530,6 +25180,26 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key in ("update.check.enabled", "update.check.ttl_hours"):
+        # Mirror the dashboard.bind branch: drop the leaf, then prune
+        # empty `check` and empty `update` so config.json stays tidy.
+        inner_key = (
+            "enabled" if key == "update.check.enabled" else "ttl_hours"
+        )
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            update_block = config.get("update")
+            if isinstance(update_block, dict):
+                check_block = update_block.get("check")
+                if isinstance(check_block, dict) and inner_key in check_block:
+                    del check_block[inner_key]
+                    if not check_block:
+                        del update_block["check"]
+                    if not update_block:
+                        config.pop("update", None)
+                    save_config(config)
+            # idempotent: silent on missing key
+        return 0
     return 2  # unreachable given the gate above
 
 
@@ -22586,6 +25256,19 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
 
 
 def cmd_setup(args: argparse.Namespace) -> int:
+    # Migration flags are install-mode-only. Reject combinations with
+    # --status or --uninstall (per spec Section 2 mode×flag matrix). The
+    # mutex group on the parser already prevents both flags being set
+    # together; here we guard the mode-axis pairing that argparse can't
+    # express in a single mutex group.
+    mig_flag = (
+        "--migrate-legacy-hooks" if getattr(args, "migrate_legacy_hooks", False)
+        else "--no-migrate-legacy-hooks" if getattr(args, "no_migrate_legacy_hooks", False)
+        else None
+    )
+    if mig_flag and (getattr(args, "status", False) or getattr(args, "uninstall", False)):
+        eprint(f"setup: {mig_flag} is install-mode only")
+        return 2
     if getattr(args, "uninstall", False):
         return _setup_uninstall(args)
     if getattr(args, "status", False):
@@ -24472,6 +27155,17 @@ def build_parser() -> argparse.ArgumentParser:
                     help="Skip confirmations")
     sp.add_argument("--json", action="store_true",
                     help="Emit machine-readable output")
+    # Legacy bespoke-hook migration flags (install-mode only — see cmd_setup
+    # post-parse validation). Spec Section 2 mode×flag matrix.
+    mig_group = sp.add_mutually_exclusive_group()
+    mig_group.add_argument(
+        "--migrate-legacy-hooks", action="store_true", dest="migrate_legacy_hooks",
+        help="Auto-accept the legacy-bespoke-hook migration prompt (install only).",
+    )
+    mig_group.add_argument(
+        "--no-migrate-legacy-hooks", action="store_true", dest="no_migrate_legacy_hooks",
+        help="Auto-skip the legacy-bespoke-hook migration prompt (install only).",
+    )
     sp.set_defaults(func=cmd_setup)
 
     # ---- db (migration framework — spec §4) ----
@@ -24620,6 +27314,11 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Skip Phase 6 (brew formula bump). Idempotent: re-running --resume without it picks the channel back up.",
     )
+    p_release.add_argument(
+        "--allow-formula-downgrade",
+        action="store_true",
+        help="Override Phase 6's monotonic-version gate (issue #30). Use only for intentional yank/revert cases — Phase 6 normally refuses to write a formula whose URL pins a lower SemVer than the on-disk formula.",
+    )
     p_release.set_defaults(func=cmd_release)
 
     # ---- hook-tick (internal — hidden from --help, see onboarding spec §3) ----
@@ -24650,6 +27349,81 @@ def build_parser() -> argparse.ArgumentParser:
                     help=argparse.SUPPRESS)  # JSON string fed to mock fetch (tests only)
     ht.set_defaults(func=cmd_hook_tick)
 
+    # ---- update (user-facing self-update subcommand; spec §4) ----
+    sub_update = sub.add_parser(
+        "update",
+        help="Update cctally to the latest version",
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Update cctally to the latest version (npm/brew installs only).
+
+            Modes:
+              cctally update                 install the latest version
+              cctally update --check         show update info without installing
+              cctally update --skip [VER]    don't remind about VER (default: latest)
+              cctally update --remind-later [DAYS]  defer the banner (default: 7)
+            """
+        ),
+    )
+    update_modes = sub_update.add_mutually_exclusive_group()
+    update_modes.add_argument(
+        "--check", action="store_true",
+        help="Show update info without installing",
+    )
+    update_modes.add_argument(
+        "--skip", nargs="?", const=SKIP_USE_STATE_LATEST, metavar="VERSION",
+        default=None,
+        help="Skip a specific version (default: latest in cache)",
+    )
+    update_modes.add_argument(
+        "--remind-later", nargs="?", type=int, const=7, metavar="DAYS",
+        default=None,
+        help="Defer reminders by N days (default: 7)",
+    )
+    # `--version` here is local to the update subparser. The subparser's
+    # value is bound to `args.install_version` (NOT `args.version`) to
+    # avoid a namespace collision with the top-level `--version`
+    # (store_true) flag handled in `main()` before subcommand dispatch:
+    # if both used `dest="version"`, `cctally update --version 1.2.3`
+    # would set `args.version="1.2.3"`, which `main()`'s truthy check
+    # would treat as "global --version requested" and short-circuit to
+    # print the version banner before `cmd_update` ever ran.
+    sub_update.add_argument(
+        "--version", metavar="X.Y.Z", default=None, dest="install_version",
+        help="Install a specific version (npm only; brew has no versioned formulae)",
+    )
+    sub_update.add_argument(
+        "--dry-run", action="store_true",
+        help="Show what would happen, don't install",
+    )
+    sub_update.add_argument(
+        "--force", action="store_true",
+        help="Bypass TTL on --check (force a fresh remote fetch)",
+    )
+    sub_update.add_argument(
+        "--json", action="store_true",
+        help="Emit JSON output (mostly with --check)",
+    )
+    sub_update.set_defaults(func=cmd_update)
+
+    # ---- _update-check (internal — hidden, detached-refresh worker for `cctally update`) ----
+    uc = sub.add_parser(
+        "_update-check",
+        help=argparse.SUPPRESS,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Internal subcommand: detached version-check worker spawned
+            by `cctally update` (spec §3.6). Touches the throttle
+            marker, fetches the latest version from npm or homebrew
+            depending on install method, and writes update-state.json.
+            Always returns 0; failures are logged to update.log.
+            """
+        ),
+    )
+    uc.set_defaults(func=cmd_update_check_internal)
+
     # Python 3.14 leaks `==SUPPRESS==` for hidden subparsers in --help; strip
     # the pseudo-action so the row disappears entirely. (The choice still
     # appears in the `{...}` choices header — there's no clean way to hide
@@ -29128,6 +31902,35 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "five_hour_thresholds": list(_alerts_cfg["five_hour_thresholds"]),
     }
 
+    # Mirror update-state.json + update-suppress.json into the envelope
+    # so the dashboard's amber "Update available" badge repaints from
+    # the SSE channel rather than requiring a /api/update/status fetch
+    # per check. Without this mirror, a long-open dashboard tab never
+    # learns that the dashboard's `_DashboardUpdateCheckThread` wrote
+    # a fresher latest_version (24h-TTL by default) — the badge stayed
+    # hidden until manual reload. Same precedent as `alerts_settings`:
+    # cheap atomic-rename reads on the snapshot hot path. Failures
+    # produce a `null` block so a missing/corrupt state file doesn't
+    # 500 the entire envelope; the client falls back to the defensive
+    # null-state shape `coerceUpdateState` already understands.
+    try:
+        _update_state_envelope = _load_update_state()
+    except UpdateError:
+        # _load_update_state() raises on truly malformed JSON. Surface
+        # an _error sentinel so the client renders "no update info" the
+        # same way it does for unreachable /api/update/status.
+        _update_state_envelope = {"_error": "update-state.json invalid"}
+    except Exception:
+        _update_state_envelope = {"_error": "update-state.json read failed"}
+    try:
+        _update_suppress_envelope = _load_update_suppress()
+    except Exception:
+        _update_suppress_envelope = {"skipped_versions": [], "remind_after": None}
+    update_envelope = {
+        "state":    _update_state_envelope,
+        "suppress": _update_suppress_envelope,
+    }
+
     return {
         "envelope_version": 2,
         "generated_at":     _iso_z(snap.generated_at),
@@ -29257,6 +32060,13 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # threshold-actions T5: see prelude above for rationale.
         "alerts":           alerts_array,
         "alerts_settings":  alerts_settings,
+
+        # update-subcommand SSE mirror (see comment above the
+        # `_load_update_state()` block). Shape matches GET
+        # /api/update/status's payload (`{state, suppress}`) so the
+        # dashboard client's existing coerceUpdateState/Suppress logic
+        # consumes both surfaces uniformly.
+        "update":           update_envelope,
     }
 
 
@@ -29401,6 +32211,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._handle_get_session_detail(path)
         elif path.startswith("/api/block/"):
             self._handle_get_block_detail(path)
+        elif path == "/api/update/status":
+            self._handle_get_update_status()
+        elif path.startswith("/api/update/stream/"):
+            self._handle_get_update_stream(path)
         else:
             self.send_error(404, "not found")
 
@@ -29412,6 +32226,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._handle_post_settings()
         elif path == "/api/alerts/test":
             self._handle_post_alerts_test()
+        elif path == "/api/update":
+            self._handle_post_update()
+        elif path == "/api/update/dismiss":
+            self._handle_post_update_dismiss()
         else:
             self.send_error(404, "not found")
 
@@ -29543,10 +32361,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     def _handle_post_settings(self) -> None:
         """Persist a settings update and trigger an immediate SSE broadcast.
 
-        Body shape (T7 extension): ``{"display"?: {"tz": "..."}, "alerts"?: {...}}``
-        — both top-level keys are optional; either may be sent alone or
-        both together (combined save). Unknown top-level keys are
-        rejected with 400.
+        Body shape: ``{"display"?: {"tz": "..."}, "alerts"?: {...},
+        "update"?: {"check"?: {"enabled"?: bool, "ttl_hours"?: int}}}``
+        — every top-level key is optional; any subset may be sent
+        together (combined save). Unknown top-level keys are rejected
+        with 400.
 
         Per-block validation:
           * ``display.tz`` — "local", "utc", or a valid IANA zone (via
@@ -29555,11 +32374,16 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             JSON boolean (string "yes"/"true" rejected, per spec). Merged
             block is validated via ``_get_alerts_config(merged)``;
             ``_AlertsConfigError`` → 400.
+          * ``update.check.enabled`` — JSON bool; 400 on type mismatch.
+          * ``update.check.ttl_hours`` — JSON int (NOT string), in
+            ``[1, 720]``; 400 on out-of-range or non-int. Bool is rejected
+            (Python ``True`` is an int subclass, so a permissive check
+            would silently accept ``true`` for a numeric field).
 
-        Atomic merged write: if BOTH blocks validate, the merged config
-        is persisted in a single ``save_config`` call inside the
-        ``config_writer_lock``. If validation fails for one block (or
-        both), nothing is persisted — no partial commits.
+        Atomic merged write: if all touched blocks validate, the merged
+        config is persisted in a single ``save_config`` call inside the
+        ``config_writer_lock``. If any block fails validation, nothing
+        is persisted — no partial commits.
 
         Security: Origin must match the request's Host header (Host-header
         parity; see ``_check_origin_csrf``). Missing Origin → 403.
@@ -29606,7 +32430,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
 
         # Reject unknown top-level keys (forward-compat hygiene).
-        allowed_top_keys = {"display", "alerts"}
+        allowed_top_keys = {"display", "alerts", "update"}
         for k in payload.keys():
             if k not in allowed_top_keys:
                 self._respond_json(
@@ -29615,10 +32439,17 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 return
 
         # Body must touch at least one known block.
-        if "display" not in payload and "alerts" not in payload:
+        if (
+            "display" not in payload
+            and "alerts" not in payload
+            and "update" not in payload
+        ):
             self._respond_json(
                 400,
-                {"error": "body must contain at least one of: display, alerts"},
+                {"error": (
+                    "body must contain at least one of: "
+                    "display, alerts, update"
+                )},
             )
             return
 
@@ -29673,6 +32504,66 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 )
                 return
 
+        # Pre-validate update shape. Only `update.check.{enabled,ttl_hours}`
+        # is settable today; any other key under `update` or `update.check`
+        # is rejected so adding e.g. `update.banner.*` later is forward
+        # compatible. `enabled` must be a JSON bool; `ttl_hours` an int
+        # (bools rejected — see _validate_update_check_ttl_hours_value).
+        update_check_validated: "dict | None" = None
+        if "update" in payload:
+            update_in = payload["update"]
+            if not isinstance(update_in, dict):
+                self._respond_json(
+                    400, {"error": "update must be an object"}
+                )
+                return
+            for inner in update_in.keys():
+                if inner != "check":
+                    self._respond_json(
+                        400,
+                        {"error": f"unknown update settings key: {inner}",
+                         "field": f"update.{inner}"},
+                    )
+                    return
+            check_in = update_in.get("check", {})
+            if not isinstance(check_in, dict):
+                self._respond_json(
+                    400,
+                    {"error": "update.check must be an object",
+                     "field": "update.check"},
+                )
+                return
+            for leaf in check_in.keys():
+                if leaf not in ("enabled", "ttl_hours"):
+                    self._respond_json(
+                        400,
+                        {"error": f"unknown update.check key: {leaf}",
+                         "field": f"update.check.{leaf}"},
+                    )
+                    return
+            update_check_validated = {}
+            if "enabled" in check_in:
+                if not isinstance(check_in["enabled"], bool):
+                    self._respond_json(
+                        400,
+                        {"error": "update.check.enabled must be a JSON boolean",
+                         "field": "update.check.enabled"},
+                    )
+                    return
+                update_check_validated["enabled"] = check_in["enabled"]
+            if "ttl_hours" in check_in:
+                try:
+                    update_check_validated["ttl_hours"] = (
+                        _validate_update_check_ttl_hours_value(check_in["ttl_hours"])
+                    )
+                except ValueError as exc:
+                    self._respond_json(
+                        400,
+                        {"error": str(exc),
+                         "field": "update.check.ttl_hours"},
+                    )
+                    return
+
         # Acquire config_writer_lock so a concurrent `cctally config set`
         # in another shell can't interleave its write between our load
         # and save (issue #17). Lock is process-cross via fcntl.flock,
@@ -29721,6 +32612,34 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     self._respond_json(400, {"error": str(exc)})
                     return
 
+            if update_check_validated is not None:
+                # Same hand-edited-junk guard as alerts: a non-dict
+                # `update` or `update.check` block in config.json should
+                # surface as a recoverable 400, not a 500.
+                existing_update = merged.get("update")
+                if existing_update is not None and not isinstance(
+                    existing_update, dict
+                ):
+                    self._respond_json(
+                        400, {"error": "update must be an object",
+                              "field": "update"}
+                    )
+                    return
+                merged_update = dict(existing_update or {})
+                existing_check = merged_update.get("check")
+                if existing_check is not None and not isinstance(
+                    existing_check, dict
+                ):
+                    self._respond_json(
+                        400, {"error": "update.check must be an object",
+                              "field": "update.check"}
+                    )
+                    return
+                merged_check = dict(existing_check or {})
+                merged_check.update(update_check_validated)
+                merged_update["check"] = merged_check
+                merged["update"] = merged_update
+
             save_config(merged)
 
         # Build the response: subset of touched blocks.
@@ -29731,6 +32650,19 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             )
         if "alerts" in payload:
             out["alerts"] = _get_alerts_config(merged)
+        if update_check_validated is not None:
+            # Echo the full merged check block (cooked defaults included)
+            # so the SettingsOverlay can repaint without a follow-up GET.
+            out["update"] = {
+                "check": {
+                    "enabled": _config_known_value(
+                        merged, "update.check.enabled"
+                    ),
+                    "ttl_hours": _config_known_value(
+                        merged, "update.check.ttl_hours"
+                    ),
+                }
+            }
         out["saved_at"] = (
             dt.datetime.now(dt.timezone.utc)
             .strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -30094,6 +33026,194 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         finally:
             self.hub.unsubscribe(q)
 
+    # --- /api/update* (spec §5.6, §5.6.1, §5.7) ----------------------
+    # The four endpoints share the module-level singleton
+    # ``_UPDATE_WORKER`` which is created in ``cmd_dashboard``. POST
+    # routes pass through ``_check_origin_csrf`` (host-header parity);
+    # GET routes are read-only and skip CSRF intentionally so polling
+    # fallbacks survive odd Origin shapes (e.g. native browser tools).
+
+    def _read_update_post_body(self) -> "dict | None":
+        """Read + parse a small JSON body for /api/update* POSTs.
+
+        Empty body is allowed (returns ``{}``). Non-dict / malformed →
+        respond 400 and return ``None`` so the caller short-circuits.
+        Body is capped at 4 KB — same envelope as /api/settings.
+        """
+        try:
+            length = int(self.headers.get("Content-Length", "0") or "0")
+        except ValueError:
+            length = 0
+        if length < 0 or length > 4096:
+            self._respond_json(400, {"error": "body too large (<=4 KB)"})
+            return None
+        if length == 0:
+            return {}
+        try:
+            payload = json.loads(self.rfile.read(length).decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            self._respond_json(400, {"error": "malformed json"})
+            return None
+        if not isinstance(payload, dict):
+            self._respond_json(400, {"error": "expected JSON object"})
+            return None
+        return payload
+
+    def _handle_post_update(self) -> None:
+        """POST /api/update — kick off an in-process update.
+
+        Body: ``{"version"?: "X.Y.Z"}``. CSRF-gated. Returns
+        202 + ``{"run_id": ...}`` on accept; 409 + ``{"run_id_in_progress": ...}``
+        when another run is already in progress.
+        """
+        if not self._check_origin_csrf():
+            return
+        payload = self._read_update_post_body()
+        if payload is None:
+            return
+        worker = _UPDATE_WORKER
+        if worker is None:
+            self._respond_json(
+                500, {"error": "update worker not initialized"}
+            )
+            return
+        version = payload.get("version") if isinstance(payload, dict) else None
+        if version is not None and not isinstance(version, str):
+            self._respond_json(
+                400, {"error": "version must be a string"}
+            )
+            return
+        accepted, run_id = worker.start(version)
+        if accepted:
+            self._respond_json(202, {"run_id": run_id})
+        else:
+            self._respond_json(409, {"run_id_in_progress": run_id})
+
+    def _handle_post_update_dismiss(self) -> None:
+        """POST /api/update/dismiss — record a skip / remind-later.
+
+        Body: ``{"action": "skip"|"remind", "version"?: "X.Y.Z", "days"?: int}``.
+        CSRF-gated. Mutates ``update-suppress.json`` via the same
+        ``_do_update_skip`` / ``_do_update_remind_later`` helpers the
+        CLI uses, so the on-disk shape stays single-source-of-truth.
+        Returns 204 on success, 400 on invalid action / shape.
+        """
+        if not self._check_origin_csrf():
+            return
+        payload = self._read_update_post_body()
+        if payload is None:
+            return
+        action = payload.get("action")
+        # Suppress stdout/stderr from _do_update_skip /
+        # _do_update_remind_later so their CLI-style "Skipped …" /
+        # "Will remind …" prints don't pollute the dashboard server's
+        # log stream. The HTTP response is the user-facing surface.
+        with contextlib.redirect_stdout(io.StringIO()), \
+                contextlib.redirect_stderr(io.StringIO()):
+            if action == "skip":
+                ver = payload.get("version")
+                if ver is None or ver == "":
+                    rc = _do_update_skip(SKIP_USE_STATE_LATEST)
+                elif not isinstance(ver, str):
+                    self._respond_json(
+                        400, {"error": "version must be a string"}
+                    )
+                    return
+                else:
+                    rc = _do_update_skip(ver)
+            elif action == "remind":
+                days_raw = payload.get("days", 7)
+                try:
+                    days = int(days_raw)
+                except (TypeError, ValueError):
+                    self._respond_json(
+                        400, {"error": "days must be an integer"}
+                    )
+                    return
+                rc = _do_update_remind_later(days)
+            else:
+                self._respond_json(
+                    400,
+                    {
+                        "error": (
+                            "action must be 'skip' or 'remind'"
+                        )
+                    },
+                )
+                return
+        if rc != 0:
+            # Helper printed an explanation to stderr (now swallowed).
+            # Map to a generic 400; UI's polling status will show the
+            # latest state. Future surface improvement: have the
+            # helpers return a structured error so we can echo the
+            # specific reason ("no version in cache to skip") here.
+            self._respond_json(400, {"error": "dismiss failed"})
+            return
+        self.send_response(204)
+        self.end_headers()
+
+    def _handle_get_update_status(self) -> None:
+        """GET /api/update/status — return state + suppress + worker status.
+
+        Polling-fallback friendly so a browser that missed the SSE
+        execvp event can detect "no run in progress" and re-render the
+        idle modal state. ``state`` and ``suppress`` come from the
+        canonical helpers so the on-disk shape is single-source-of-truth.
+        """
+        try:
+            state = _load_update_state()
+        except UpdateError as e:
+            state = {"_error": str(e)[:200]}
+        try:
+            suppress = _load_update_suppress()
+        except UpdateError as e:
+            suppress = {"_error": str(e)[:200]}
+        worker_status = (
+            _UPDATE_WORKER.status() if _UPDATE_WORKER is not None
+            else {"current_run_id": None}
+        )
+        body = {
+            "state": state,
+            "suppress": suppress,
+            **worker_status,
+        }
+        self._respond_json(200, body)
+
+    def _handle_get_update_stream(self, path: str) -> None:
+        """GET /api/update/stream/<run_id> — SSE event stream.
+
+        Yields events from ``UpdateWorker.stream(run_id)``. Closes on
+        the worker's terminal events (``execvp`` / ``error_event`` /
+        ``done``). 404 when the worker is uninitialized; the worker's
+        own generator returns immediately on unknown run_id, so the
+        connection closes cleanly.
+        """
+        worker = _UPDATE_WORKER
+        if worker is None:
+            self.send_error(404, "update worker not initialized")
+            return
+        run_id = path.rsplit("/", 1)[-1]
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream; charset=utf-8")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "keep-alive")
+        self.send_header("X-Accel-Buffering", "no")
+        self.end_headers()
+        try:
+            for ev in worker.stream(run_id):
+                ev_type = ev.get("type", "message")
+                ev_data = json.dumps(
+                    {k: v for k, v in ev.items() if k != "type"},
+                    ensure_ascii=False,
+                )
+                msg = f"event: {ev_type}\ndata: {ev_data}\n\n"
+                self.wfile.write(msg.encode("utf-8"))
+                self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError):
+            # Browser disconnected mid-stream. The worker keeps
+            # running; subsequent reconnects can poll /api/update/status.
+            pass
+
 
 class _TuiSyncThread:
     """Daemon thread that periodically rebuilds the DataSnapshot.
@@ -31947,6 +35067,16 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     import time as _time
     import webbrowser as _wb
 
+    # 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
+    # so :class:`UpdateWorker` can read them without plumbing.
+    global ORIGINAL_SYS_ARGV, ORIGINAL_ENTRYPOINT, _UPDATE_WORKER
+    ORIGINAL_SYS_ARGV = list(sys.argv)
+    ORIGINAL_ENTRYPOINT = shutil.which("cctally")
+    _UPDATE_WORKER = UpdateWorker()
+
     # Resolve display tz (--tz overrides config.display.tz). The dashboard's
     # envelope-emitted display block (Tasks 11-12) reads this; for now,
     # stash on args so downstream selectors can pick it up uniformly.
@@ -32081,6 +35211,16 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     if sync_thread is not None:
         sync_thread.start()
 
+    # Spec §3.5 (codex review fix #5): update-check thread runs even
+    # under --no-sync (frozen-data sessions still surface new versions).
+    # Dedicated stop event so we can join cleanly on shutdown without
+    # relying on the data-sync thread's lifecycle.
+    update_check_stop = threading.Event()
+    update_check_thread = _DashboardUpdateCheckThread(
+        update_check_stop, hub=hub, snapshot_ref=ref,
+    )
+    update_check_thread.start()
+
     # HTTP server on its own thread so the main thread can block on signal.
     srv = ThreadingHTTPServer((args.host, args.port), DashboardHTTPHandler)
     srv.daemon_threads = True  # SSE handler threads may block up to 15s on keep-alive timeout — let them die with the process.
@@ -32151,6 +35291,7 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     finally:
         if sync_thread is not None:
             sync_thread.stop()
+        update_check_stop.set()
         srv.shutdown()
         http_thread.join(timeout=2)
         print("dashboard: stopped", flush=True)
@@ -32561,7 +35702,7 @@ def main(argv: list[str] | None = None) -> int:
         parser.error("a subcommand is required")
     _print_migration_error_banner_if_needed(args)
     try:
-        return int(args.func(args))
+        rc = int(args.func(args))
     except KeyboardInterrupt:
         return 130
     except DowngradeDetected as exc:
@@ -32569,7 +35710,44 @@ def main(argv: list[str] | None = None) -> int:
         return 2
     except Exception as exc:  # pragma: no cover
         eprint(f"Error: {exc}")
-        return 1
+        rc = 1
+    # Post-command update hooks (spec §4.2). Best-effort: any exception
+    # in the banner / background-spawn path must not perturb the parent
+    # command's exit code or perceived output. Runs on both success and
+    # error paths so the user sees pending-update banners even when the
+    # current command failed.
+    try:
+        _post_command_update_hooks(getattr(args, "command", None), args)
+    except Exception:
+        pass
+    return rc
+
+
+def _post_command_update_hooks(command: str | None, args) -> None:
+    """Render the update banner if applicable + spawn the background
+    refresh check if its TTL has elapsed (spec §4.2 + §3.6).
+
+    Both paths are wrapped in their own try/except by the caller so a
+    failure here can't break the parent command. Reading state /
+    suppress / config is itself best-effort: a corrupt JSON file would
+    raise, but the outer caller swallows it.
+
+    Skip-after-uninstall: ``setup --uninstall`` (with or without
+    ``--purge``) deletes ~/.local/bin/ symlinks and may wipe APP_DIR.
+    Running ``load_config()`` afterwards would recreate APP_DIR via its
+    ``ensure_dirs()`` first-run path, leaving a stub config.json behind
+    and breaking the post-purge "data dir gone" invariant. Skip the
+    hook entirely for that command — the banner is moot post-uninstall
+    anyway."""
+    if command == "setup" and getattr(args, "uninstall", False):
+        return
+    config = load_config()
+    state = _load_update_state()
+    suppress = _load_update_suppress()
+    if _should_show_update_banner(command, args, state, suppress, config):
+        sys.stderr.write(_format_update_banner(state) + "\n")
+    if _is_update_check_due(config):
+        _spawn_background_update_check()
 
 
 if __name__ == "__main__":