cctally 1.69.3 → 1.71.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.71.0] - 2026-07-17
+
+### Added
+- Transcript retention: the dashboard's background sync thread now runs a throttled (at most once every 24 hours) prune of conversation transcripts older than the new `conversation.retention_days` config key (default 180; set to `off`/`0` to keep transcripts forever), bounding `cache.db`'s otherwise-unbounded growth. Only transcript rows are pruned — cost/usage history and Codex analytics metadata are untouched and everything pruned is re-derivable from the JSONL. Eligibility is decided per conversation from the authoritative message rows (a conversation with any recent activity is kept whole), never a rollup. (#313)
+- `cctally cache-sync --prune-conversations` prunes >retention-day transcripts on demand and reports the rows removed per provider. (#313)
+- `cctally db vacuum [--db {cache,stats,all}]` reclaims the disk space a prune freed (SQLite `VACUUM`); it is never automatic, runs under an exclusive lock so a running dashboard makes it fail promptly rather than race, and refuses when free disk is below ~2x the file size. (#313)
+
+### Fixed
+- Dashboard CPU peg: `cctally dashboard` no longer pegs a CPU core under sustained active use on large caches. The Codex quota-projection reconcile — which ran unconditionally on every dashboard tick and every `codex-*` command, re-loading the entire quota history (~2.9s) — now short-circuits to an O(1) no-op when the Codex physical state is unchanged and the stored projection is intact; `codex-daily` with no fresh Codex data drops from ~3.2s to well under a second. The dashboard sync thread also caps its CPU duty at 50% of one core via a work-proportional cooldown, so a slow rebuild can no longer keep the thread busy back-to-back. (#313)
+- Dashboard: the #294 S5 source selector no longer causes the mobile topbar to scroll sideways on the narrowest phones. The active-source status chip sits in the non-shrinkable action cluster, and adding it pushed that cluster past a 320px-wide viewport; it now hides at ≤360px (freshness is still on the global sync chip and a degraded source stays flagged in the selector and panels), and both the source selector and its status chip drop out of the condensed one-row header once you scroll, matching how the workspace switcher and doctor chip already collapse there. (#294)
+
+## [1.70.0] - 2026-07-17
+
+### Added
+- `cctally setup` now adds `statusLine.refreshInterval: 30` to a cctally-pointing Claude Code `statusLine` block that lacks one, so status-line-fed usage keeps recording on a 30-second timer while a coordinator session waits on a long-running subagent (Claude Code's event-driven status-line updates go quiet then). Ownership is add-when-absent / never-mutate / never-remove: setup never creates a `statusLine` block, never changes a `refreshInterval` you set yourself, and `--uninstall` leaves it. Surfaced in install / `--status` / `--dry-run` (text plus the `--json` `statusline_refresh {state, value, action}` object). (#311)
+- `cctally doctor` gains a `hooks.statusline_refresh_interval` check that WARNs when a recognized cctally `statusLine` command is missing its `refreshInterval`, and is OK (with a per-state summary) otherwise. (#311)
+
+### Changed
+- Retuned the status-line usage-persist throttle from 60s to 25s so it sits below the new 30s `statusLine.refreshInterval` timer; a 60/60 pairing beat-frequency-throttled every other tick and oscillated the effective cadence between 60 and 120 seconds. (#311)
+
+### Fixed
+- Status-line usage persistence now skips sessions running a bracketed model variant such as `claude-opus-4-8[1m]` (the 1M-context variant), whose `rate_limits` describe a separate account usage pool. Persisting those poisoned the default-pool snapshots — the reset-aware high-water-mark clamp latched the foreign value and froze all subsequent genuine writes. The guard is persist-only, so a `[1m]` session still renders its own true pool numbers on the status line. (#311)
+
 ## [1.69.3] - 2026-07-17
 
 ### Fixed
@@ -23,6 +46,7 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [1.69.0] - 2026-07-17
 
 ### Added
+- Dashboard source selector and source-aware UX (#294 S5): a Header Claude/Codex/All radiogroup (cycle with `v`) drives every panel, modal, alert filter, and share default at once, rendering each provider's native vocabulary (Codex token counters and quota windows, no `$ / 1%` or subscription-week copy) and hiding — never zero-filling — panels a source doesn't publish, with a Help-overlay note pointing at where the equivalent lives (Codex forecast/trend → the quota panel, cache-report → the hero counters). Alerts and toasts read the per-source projections (a Codex budget alert can't double-toast), the alert settings regroup into global-notifier / Claude / Codex controls with a CLI pointer for Codex quota rules, a per-source status chip surfaces freshness and degraded warnings, and every share render, composer section, preset, and history row carries and displays the source it was captured under — a mid-flow selector switch never restamps an open share flow, and `all` composes provider-labelled sections rather than a blended snapshot. The Claude-only user's data and flows are unchanged except that new share artifacts and history now say "Claude".
 - Dashboard source-aware backend read model (#294 S4): `/api/data` now appends
   immutable Claude, Codex, and labelled all-source states; provider-owned
   session/project/quota details use opaque qualified routes backed by bounded

package/bin/_cctally_cache.py

@@ -725,6 +725,13 @@ def _clear_codex_derived_rows(conn: sqlite3.Connection) -> None:
     conn.execute("DELETE FROM codex_conversation_events")
     conn.execute("DELETE FROM codex_session_files")
     conn.execute("DELETE FROM codex_source_roots")
+    # F3: this clears the Codex physical quota state, so any stored
+    # quota-projection certificate would become stale-valid (its cache
+    # sequence unchanged) and let the reconcile short-circuit skip over
+    # now-deleted data. Invalidate it in the same transaction.
+    conn.execute(
+        "DELETE FROM cache_meta WHERE key='codex_quota_projection_certificate'"
+    )
 
 
 def _bump_codex_physical_mutation_seq(conn: sqlite3.Connection) -> None:
@@ -1388,6 +1395,30 @@ def _bump_mutation_seq(conn: sqlite3.Connection) -> int:
     return int(row[0])
 
 
+def _force_retention_prune_after_replay(conn: sqlite3.Connection) -> None:
+    """#313 P3 (F9): run an UNTHROTTLED transcript retention prune after a
+    from-zero replay (a ``--rebuild`` or a truncation/requalification re-ingest,
+    both of which replay from offset 0 and restore >retention-day rows the
+    throttled prune already trimmed). Best-effort — a prune failure must never
+    break a sync. The caller invokes this only after the sync released its
+    provider flock, so the orchestrator can re-acquire it. No-op when retention
+    is disabled (``conversation.retention_days`` 0)."""
+    try:
+        import _lib_conversation_retention as retention
+        from _cctally_config import resolve_retention_days
+        retention_days = resolve_retention_days(_cctally().load_config())
+        if retention_days <= 0:
+            return
+        retention._maybe_prune_conversation_retention(
+            conn,
+            now_utc=dt.datetime.now(dt.timezone.utc),
+            retention_days=retention_days,
+            force=True,
+        )
+    except Exception:
+        pass
+
+
 def sync_cache(
     conn: sqlite3.Connection,
     *,
@@ -2340,13 +2371,20 @@ def sync_cache(
         # and the flock is still held, so the short busy_timeout keeps it from
         # stalling the lock under heavy-reader contention.
         _maybe_truncate_wal(conn, _cctally_core.CACHE_DB_PATH)
-        return stats
+        # #313 P3 (F9): a rebuild or a truncation escalation replays from offset
+        # 0 and restores >retention-day transcript rows. Force an unthrottled
+        # prune AFTER the flock releases below (early lock-contended / deferred
+        # returns above never reach here, so a no-op sync does not prune).
+        did_from_zero_replay = rebuild or stats.files_reset_truncated > 0
     finally:
         try:
             fcntl.flock(lock_fh, fcntl.LOCK_UN)
         except OSError:
             pass
         lock_fh.close()
+    if did_from_zero_replay:
+        _force_retention_prune_after_replay(conn)
+    return stats
 
 
 def backfill_conversation_messages(conn: sqlite3.Connection) -> int:
@@ -3491,6 +3529,17 @@ def sync_codex_cache(
     """
     stats = CodexIngestStats()
     project_after_unlock = False
+    did_from_zero_replay = False
+    # #313 P1 review (F4/F1): when the CACHE certificate is current we cannot
+    # yet decide whether to skip the reconcile — reconcile's own short-circuit
+    # ALSO requires the stats-side quota_projection_state signatures to match
+    # (F1: stats.db can be wiped/recovered while cache.db persists). That
+    # cross-DB read must happen AFTER the Codex flock releases (see the design
+    # comment near the reconcile trigger below), so capture the material for the
+    # deferred stats-side check here. ``None`` means "no deferred check pending"
+    # (the seq-advanced / no-roots / stale-cert branches decide immediately).
+    deferred_cert_roots: "set[str] | None" = None
+    deferred_cert_sigs: "dict[str, str] | None" = None
     c = _cctally()
     _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
     _cctally_core.CACHE_LOCK_CODEX_PATH.touch()
@@ -3505,6 +3554,18 @@ def sync_codex_cache(
             stats.lock_contended = True
             return stats
 
+        # F4 (#313): the reconcile trigger gate is "did the Codex physical
+        # mutation sequence advance during this sync", NOT rows_changed —
+        # rows_changed counts only inserted accounting rows and misses
+        # quota-only / metadata-only / prune-only batches that bump the
+        # sequence. Capture the baseline before any clear/prune/ingest bump.
+        from _cctally_quota import (
+            codex_physical_mutation_seq,
+            load_codex_quota_projection_certificate,
+            _cache_root_keys,
+        )
+        seq_before = codex_physical_mutation_seq(conn)
+
         if rebuild:
             # Clear INSIDE the lock — see sync_cache() for the full
             # rationale. Done before the existing SELECT so delta
@@ -3892,7 +3953,56 @@ def sync_codex_cache(
         # Codex cache flock in ``finally`` below.  cache.db and stats.db are not
         # cross-database atomic: after this committed ingest, a projection
         # interruption is repaired by the next full reconciliation.
-        project_after_unlock = True
+        #
+        # F4 (#313): reconcile when the physical mutation sequence advanced this
+        # sync (a genuine quota/metadata/prune change — NOT rows_changed, which
+        # misses quota-only batches). A pure no-op with an already-coherent
+        # certificate skips even the O(1) reconcile call.
+        #
+        # A no-op sync must STILL reconcile when there are Codex roots but the
+        # projection certificate is missing/stale at the current sequence — a
+        # lost/failed certificate write (best-effort I/O; can fail under a
+        # cache.db lock storm) leaves the dashboard's Codex source "unavailable"
+        # and is recovered by the next unchanged-file sync re-stamping the
+        # certificate. Claude-only users (no Codex roots) always skip.
+        #
+        # F1 (#313 P1 review): even when the CACHE certificate looks current, the
+        # STATS-side quota_projection_state may have been independently
+        # wiped/recovered (this user has a documented stats.db corruption
+        # history). The cache cert alone does NOT prove stats.db still holds the
+        # projection, so the skip decision on that branch is DEFERRED to the
+        # post-flock stats-side signature check below — making the gate's
+        # skip-condition identical to reconcile's own short-circuit-condition.
+        cur_seq = codex_physical_mutation_seq(conn)
+        if cur_seq != seq_before:
+            project_after_unlock = True
+        else:
+            active_roots = _cache_root_keys(conn)
+            if not active_roots:
+                project_after_unlock = False
+            else:
+                certificate = load_codex_quota_projection_certificate(conn)
+                certificate_current = (
+                    certificate is not None
+                    and certificate[0] == cur_seq
+                    and active_roots <= set(certificate[1])
+                )
+                if certificate_current:
+                    # The CACHE certificate is current, but that alone does NOT
+                    # prove stats.db still holds the projection (F1). Defer the
+                    # stats-side signature match until AFTER the Codex flock
+                    # releases below — only then may the reconcile be skipped.
+                    project_after_unlock = False
+                    deferred_cert_roots = set(active_roots)
+                    assert certificate is not None
+                    deferred_cert_sigs = dict(certificate[1])
+                else:
+                    project_after_unlock = True
+        # #313 P3 (F9): a Codex rebuild or a truncation/requalification
+        # re-ingest replays from offset 0 and restores >retention-day
+        # codex_conversation_events. Force an unthrottled prune after the flock
+        # releases (below), so restored old rows don't persist for up to 24h.
+        did_from_zero_replay = rebuild or stats.files_reset_truncated > 0
     finally:
         try:
             fcntl.flock(lock_fh, fcntl.LOCK_UN)
@@ -3900,9 +4010,29 @@ def sync_codex_cache(
             pass
         lock_fh.close()
 
+    if deferred_cert_roots is not None:
+        # F1: the gate's skip-condition must be IDENTICAL to
+        # reconcile_codex_quota_projection's own short-circuit-condition, which
+        # additionally requires the stats-side quota_projection_state signatures
+        # to match the cache certificate for every active root. Read stats.db
+        # HERE — after the Codex flock released in the ``finally`` above — so the
+        # cross-DB read never widens the Codex flock's critical section (the
+        # design invariant documented near the reconcile trigger). A wiped/stale
+        # stats projection (mismatch) forces the reconcile so it self-heals.
+        from _cctally_quota import _stats_projection_signatures_match
+        stats_conn = _cctally_core.open_db()
+        try:
+            if not _stats_projection_signatures_match(
+                stats_conn, deferred_cert_roots, deferred_cert_sigs or {}
+            ):
+                project_after_unlock = True
+        finally:
+            stats_conn.close()
     if project_after_unlock:
         from _cctally_quota import reconcile_codex_quota_projection
         reconcile_codex_quota_projection()
+    if did_from_zero_replay:
+        _force_retention_prune_after_replay(conn)
     return stats
 
 
@@ -4253,6 +4383,41 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
             )
         return 0
 
+    # --prune-conversations: on-demand, UNTHROTTLED transcript retention prune
+    # (#313 P3). Removes >retention-day conversation transcripts (re-derivable
+    # from JSONL). Reclaim the freed disk space with `cctally db vacuum`.
+    if getattr(args, "prune_conversations", False):
+        from _cctally_config import resolve_retention_days
+        import _lib_conversation_retention as retention
+        retention_days = resolve_retention_days(_cctally().load_config())
+        if retention_days <= 0:
+            eprint(
+                "[cache-sync] transcript retention is disabled "
+                "(conversation.retention_days=0); nothing pruned."
+            )
+            return 0
+        result = retention._maybe_prune_conversation_retention(
+            conn,
+            now_utc=dt.datetime.now(dt.timezone.utc),
+            retention_days=retention_days,
+            force=True,
+        )
+        if result is None:
+            eprint(
+                "[cache-sync] prune-conversations skipped: another process "
+                "holds the maintenance or a provider lock; retry shortly."
+            )
+            return 1
+        eprint(
+            f"[cache-sync] pruned transcripts older than {retention_days}d: "
+            f"claude {result.claude_sessions} session(s) / "
+            f"{result.claude_messages} message(s), "
+            f"codex {result.codex_conversations} conversation(s) / "
+            f"{result.codex_events} event(s). "
+            f"Run `cctally db vacuum` to reclaim the freed space."
+        )
+        return 0
+
     # Note: when --rebuild is set we delegate the DELETE to sync_cache /
     # sync_codex_cache, which execute it AFTER acquiring the flock. A
     # pre-sync DELETE here would wipe the cache even when the subsequent

package/bin/_cctally_config.py

@@ -327,11 +327,76 @@ ALLOWED_CONFIG_KEYS = (
     "budget.codex.alert_thresholds",
     "budget.codex.projected_enabled",
     "telemetry.enabled",
+    "conversation.retention_days",
 )
 
 
 _CODEX_BUDGET_LEAF_PREFIX = "budget.codex."
 
+_DEFAULT_CONVERSATION_RETENTION_DAYS = 180
+
+
+def _validate_retention_days_value(raw: object) -> int:
+    """Validate a ``config set`` value for ``conversation.retention_days`` (F8).
+
+    Accept a non-negative integer; ``off`` / ``0`` canonicalize to integer 0
+    (disabled — keep transcripts forever). Reject booleans, negatives, and
+    non-numeric input by raising ``ValueError`` (the caller maps that to exit 2).
+    """
+    if isinstance(raw, bool):
+        raise ValueError(
+            "conversation.retention_days must be a non-negative integer or 'off'"
+        )
+    if isinstance(raw, str):
+        text = raw.strip().lower()
+        if text == "off":
+            return 0
+        try:
+            value = int(text, 10)
+        except (TypeError, ValueError):
+            raise ValueError(
+                "conversation.retention_days must be a non-negative integer "
+                f"or 'off', got {raw!r}"
+            )
+    elif isinstance(raw, int):
+        value = raw
+    else:
+        raise ValueError(
+            "conversation.retention_days must be a non-negative integer or 'off'"
+        )
+    if value < 0:
+        raise ValueError(
+            "conversation.retention_days must be >= 0 (use 'off' or 0 to disable)"
+        )
+    return value
+
+
+def resolve_retention_days(config: dict) -> int:
+    """Effective conversation transcript retention in days (F8).
+
+    Default is ``180``; ``0`` disables retention (keep forever). Any malformed
+    persisted value (non-int, boolean, negative, un-parseable string) degrades
+    to the safe 180 default rather than raising.
+    """
+    default = _DEFAULT_CONVERSATION_RETENTION_DAYS
+    block = config.get("conversation") if isinstance(config, dict) else None
+    if not isinstance(block, dict):
+        return default
+    stored = block.get("retention_days")
+    if stored is None:
+        return default
+    if isinstance(stored, bool):
+        return default
+    if isinstance(stored, int):
+        return stored if stored >= 0 else default
+    if isinstance(stored, str):
+        try:
+            value = int(stored.strip(), 10)
+        except (TypeError, ValueError):
+            return default
+        return value if value >= 0 else default
+    return default
+
 
 def _config_codex_leaf_value(config: dict, key: str) -> object:
     """Read one nested Codex budget leaf with its public default.
@@ -794,6 +859,10 @@ def _config_known_value(config: dict, key: str) -> "object":
             except ValueError:
                 return True
         return True
+    if key == "conversation.retention_days":
+        # Effective transcript-retention window in days (default 180; 0 = keep
+        # forever). Malformed persisted data surfaces the safe default (F8).
+        return resolve_retention_days(config)
     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.
@@ -1422,6 +1491,32 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 rendered = str(normalized)
             print(f"{key}={rendered}")
         return 0
+    if key == "conversation.retention_days":
+        # Validate first; rejection short-circuits before lock acquisition (F8).
+        try:
+            normalized = _validate_retention_days_value(raw)
+        except ValueError as exc:
+            print(f"cctally: {exc}", file=sys.stderr)
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("conversation")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: conversation config error: conversation must be "
+                    "an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block["retention_days"] = normalized
+            config["conversation"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"conversation": {"retention_days": normalized}}, indent=2))
+        else:
+            print(f"{key}={normalized}")
+        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":
@@ -1862,6 +1957,19 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key == "conversation.retention_days":
+        # Mirror the display.tz branch: drop the leaf; if the `conversation`
+        # block ends up empty, drop it too. Next get resolves the 180 default.
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("conversation")
+            if isinstance(block, dict) and "retention_days" in block:
+                del block["retention_days"]
+                if not block:
+                    config.pop("conversation", None)
+                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.

package/bin/_cctally_core.py

@@ -61,7 +61,8 @@ def _init_paths_from_env() -> None:
     """
     global APP_DIR, LEGACY_APP_DIR, LOG_DIR, DEV_MODE
     global DB_PATH, CACHE_DB_PATH
-    global CACHE_LOCK_PATH, CACHE_LOCK_CODEX_PATH, CONFIG_LOCK_PATH
+    global CACHE_LOCK_PATH, CACHE_LOCK_CODEX_PATH, CACHE_LOCK_MAINTENANCE_PATH
+    global CONFIG_LOCK_PATH
     global CONFIG_PATH, MIGRATION_ERROR_LOG_PATH, CHANGELOG_PATH
     global HOOK_TICK_LOG_DIR, HOOK_TICK_LOG_PATH, HOOK_TICK_LOG_ROTATED_PATH
     global HOOK_TICK_THROTTLE_PATH, HOOK_TICK_THROTTLE_LOCK_PATH
@@ -100,6 +101,10 @@ def _init_paths_from_env() -> None:
 
     CACHE_LOCK_PATH = APP_DIR / "cache.db.lock"
     CACHE_LOCK_CODEX_PATH = APP_DIR / "cache.db.codex.lock"
+    # #313 P3 (F7): dedicated maintenance flock serializing the transcript
+    # retention prune across processes, held ABOVE the two provider flocks so a
+    # rebuild/reingest cannot land between candidate selection and deletion.
+    CACHE_LOCK_MAINTENANCE_PATH = APP_DIR / "cache.db.maintenance.lock"
     CONFIG_LOCK_PATH = APP_DIR / "config.json.lock"
 
     CONFIG_PATH = APP_DIR / "config.json"
@@ -243,13 +248,37 @@ def _real_prod_data_dir() -> pathlib.Path:
 #
 # STATUSLINE_PERSIST_THROTTLE_SECONDS: min seconds between statusline
 #   persist attempts (keyed off STATUSLINE_OBSERVE_MARKER_PATH liveness).
+#   Retuned 60.0 -> 25.0 for #311: the setup-managed statusLine.refreshInterval
+#   timer fires the statusline on a 30s cadence, and the throttle MUST be
+#   strictly LESS than that interval. When interval <= throttle, phase jitter
+#   produces beat-frequency skips (a tick at 59.9s of marker age is throttled;
+#   the next persist waits ~120s), so a 60/60 pairing oscillates 60<->120s.
+#   With interval 30 > throttle 25, every tick whose predecessor's record
+#   completed promptly (within interval - throttle = 5s) passes the gate.
+#   CADENCE QUALIFIER: the marker is touched at persist COMPLETION, so a tick
+#   observes marker age = 30 - d where d is the previous record's duration;
+#   if d > 5s (the record kernel can run cmd_sync_week JSONL scans) that tick
+#   throttles and the cycle degrades to skip-one-tick (~60s), self-correcting
+#   on the next tick. Exact-30s is NOT an invariant (no attempt-start marker
+#   exists — one would let a hung/failed record claim liveness and suppress
+#   the OAuth backfill). Still strictly better than the 60/60 beat's 60-120s.
 # OAUTH_BACKFILL_STALE_SECONDS: the OAuth poll only backfills once the
 #   observation marker is at least this stale (i.e. the statusline has
 #   NOT fed recently). Strictly greater than the persist throttle so the
-#   statusline is the primary writer and OAuth only covers its absence.
+#   statusline is the primary writer and OAuth only covers its absence
+#   (300 > 25 still holds).
 # OAUTH_BACKOFF_BASE_SECONDS / OAUTH_BACKOFF_CAP_SECONDS: the headerless
 #   exponential 429 backoff (base * 2**consecutive_429, capped).
-STATUSLINE_PERSIST_THROTTLE_SECONDS = 60.0
+STATUSLINE_PERSIST_THROTTLE_SECONDS = 25.0
+# STATUSLINE_REFRESH_INTERVAL_DEFAULT (#311): the value `cctally setup`
+# writes into Claude Code's settings.json `statusLine.refreshInterval` when a
+# recognized cctally statusLine block lacks one. Claude Code re-runs the
+# statusline command on this fixed timer "in addition to the event-driven
+# updates", which keeps the usage-persistence feeder ticking while a parent
+# session waits on a long subagent (event-driven updates go quiet then). MUST
+# exceed STATUSLINE_PERSIST_THROTTLE_SECONDS (30 > 25) — see the pairing rule
+# above. Add-when-absent only; a user-set value is never mutated.
+STATUSLINE_REFRESH_INTERVAL_DEFAULT = 30
 OAUTH_BACKFILL_STALE_SECONDS = 300.0
 OAUTH_BACKOFF_BASE_SECONDS = 60.0
 OAUTH_BACKOFF_CAP_SECONDS = 3600.0

package/bin/_cctally_dashboard.py

@@ -1068,6 +1068,86 @@ def _load_recorded_five_hour_windows(*args, **kwargs):
     return sys.modules["cctally"]._load_recorded_five_hour_windows(*args, **kwargs)
 
 
+def _next_deadline(t0: float, interval: float, work: float) -> float:
+    """Monotonic deadline for the next sync iteration (#313 P2 / F10).
+
+    The iteration's work ended at ``t0 + work``; cool down from there for
+    ``max(interval, work)``. So the period is ``work + max(interval, work)``:
+
+    - work >= interval  → period = ``2 * work``  → CPU duty capped at 50% of one
+      core, scale-independent (a slow rebuild on a huge cache can never peg a
+      full core — the exact #313 symptom).
+    - work <  interval  → period = ``work + interval`` — byte-identical to the
+      prior loop (rebuild then a fixed ``interval`` sleep), so normal-cadence
+      behavior and its goldens are unchanged.
+
+    NOTE (spec deviation): the spec §3 pseudocode's ``deadline = t0 + max(
+    interval, work)`` cools down from ``t0`` (before the work), which for
+    work >= interval yields a ZERO cooldown (period = work, 100% duty) — it does
+    not meet the spec's own stated "period = 2*work / duty <= 50%" property or
+    §1's "<= 50% of one core" success criterion, and would leave the peg unfixed
+    (in fact worse than the old work+interval cadence). This formula cools down
+    from the work's END, which is what those properties require.
+    """
+    return (t0 + work) + max(interval, work)
+
+
+def _dashboard_sync_loop(
+    *,
+    stop,
+    interval: float,
+    run_iteration,
+    take_sync_request,
+    monotonic=time.monotonic,
+    sleep=time.sleep,
+) -> None:
+    """Run the dashboard's automatic sync loop with a work-proportional cooldown.
+
+    ``run_iteration`` performs one whole automatic iteration (rebuild plus any
+    orphan self-heal / retention maintenance the thread does), so its measured
+    duration — not just the rebuild — drives the deadline (F10). The manual
+    ``POST /api/sync`` refresh is a separate synchronous path under ``sync_lock``
+    and is unaffected; ``take_sync_request`` is the TUI force-refresh flag that
+    breaks the cooldown early.
+    """
+    while not stop.is_set():
+        t0 = monotonic()
+        run_iteration()
+        work = monotonic() - t0
+        deadline = _next_deadline(t0, interval, work)
+        while not stop.is_set() and monotonic() < deadline:
+            if take_sync_request():
+                break
+            sleep(min(0.1, max(0.0, deadline - monotonic())))
+
+
+def _dashboard_maybe_prune_retention() -> None:
+    """#313 P3 (F7): throttled transcript retention prune driven from the
+    dashboard sync thread. Runs once per iteration INSIDE the measured cooldown
+    work (Task 6), so its cost paces the deadline. Opens a dedicated cache
+    connection (no provider flock, no open transaction) for the orchestrator.
+    No-op when retention is disabled; never raises (a prune failure must not
+    crash the sync thread)."""
+    try:
+        c = sys.modules["cctally"]
+        from _cctally_config import resolve_retention_days
+        import _lib_conversation_retention as retention
+        retention_days = resolve_retention_days(c.load_config())
+        if retention_days <= 0:
+            return
+        conn = c.open_cache_db()
+        try:
+            retention._maybe_prune_conversation_retention(
+                conn,
+                now_utc=dt.datetime.now(dt.timezone.utc),
+                retention_days=retention_days,
+            )
+        finally:
+            conn.close()
+    except Exception:
+        pass
+
+
 def _make_run_sync_now(*args, **kwargs):
     return sys.modules["cctally"]._make_run_sync_now(*args, **kwargs)
 
@@ -6623,23 +6703,38 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
 
     class _DashboardSyncThread(_c_for_subclass._TuiSyncThread):
         def _run(self) -> None:
-            last_heal = _time.monotonic()
-            while not self._stop.is_set():
+            last_heal = [_time.monotonic()]
+
+            def run_iteration() -> None:
                 _run_sync_now(skip_sync=self._skip_sync)
                 # Self-heal removed-worktree orphans on a ~60s cadence (far
                 # rarer than the sync tick — a deleted worktree is not urgent).
                 # Non-blocking on the flock, so a contended tick just retries
-                # next cadence; gated off under --no-sync.
+                # next cadence; gated off under --no-sync. Runs INSIDE the
+                # measured iteration so its cost counts toward the cooldown
+                # deadline (#313 P2 / F10).
                 if (not self._skip_sync
-                        and _time.monotonic() - last_heal >= 60.0):
-                    last_heal = _time.monotonic()
+                        and _time.monotonic() - last_heal[0] >= 60.0):
+                    last_heal[0] = _time.monotonic()
                     _dashboard_self_heal_orphans(skip_sync=self._skip_sync)
-                for _ in range(int(max(1, self._interval * 10))):
-                    if self._stop.is_set():
-                        return
-                    if self._ref.take_sync_request():
-                        break
-                    _time.sleep(0.1)
+                # #313 P3 (F7): throttled transcript retention prune, inside the
+                # measured iteration so its cost is in the cooldown work. Gated
+                # off under --no-sync (frozen mode makes no cache writes).
+                if not self._skip_sync:
+                    _dashboard_maybe_prune_retention()
+
+            # Work-proportional cooldown (F10): sleep to t0 + max(interval, work)
+            # so a slow rebuild cannot peg a full core. The manual POST /api/sync
+            # refresh runs synchronously under sync_lock, independent of this
+            # cooldown, so a user force-refresh is always immediate.
+            _dashboard_sync_loop(
+                stop=self._stop,
+                interval=self._interval,
+                run_iteration=run_iteration,
+                take_sync_request=self._ref.take_sync_request,
+                monotonic=_time.monotonic,
+                sleep=_time.sleep,
+            )
 
     sync_thread = (
         None if args.no_sync