cctally 1.66.0 → 1.67.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.67.0] - 2026-07-12
+
+### Added
+- Anonymized conversation sharing (#281 S4): the transcript reader gains an "Anon" toggle next to Export ▾ (on by default, remembered) that rewrites your observed project paths, home directory, and username to placeholders (`project-N`, `~`, `user`) and redacts a documented set of secret patterns (API keys, tokens, Authorization headers) before an export or per-card copy leaves your machine — with `--raw`/toggle-off restoring the exact unredacted output byte-for-byte; per-card copy is fail-closed (a scrub-plan failure leaves the clipboard untouched rather than copying raw); the guarantee is best-effort over known tokens, so review before sharing.
+- New `cctally transcript export|search` command (#281 S4): `export <session-id>` prints a whole session as Markdown (anonymized by default, `--raw` for the exact export, byte-identical to the dashboard download), and `search <query>` runs the dashboard's cross-session search with its full filter surface and a `--json` mode from the terminal.
+- CI safety net (#281 S2): the full frontend vitest estate now runs in CI — on every non-docs-only push to main (self-hosted lane) and in a new hosted-ubuntu `test-pr` lane covering same-repo code PRs plus all code PRs on the public repo — and a new markdown doc-lint (`bin/cctally-doc-lint-test`, auto-run by `cctally-test-all`, plus a `doc-lint.yml` workflow that sees md-only pushes) guards the retired stale claims from reappearing.
+- Reader smoke net (#281 S3): the conversation reader now ships a committed Playwright real-browser test suite covering the scroll, reverse-paging anchor, live-tail "↓ N new" pill, cold jump-to-turn, find-bar focus trap, and modal scroll-lock seams that JSDOM unit tests structurally cannot exercise — wired into CI on both the self-hosted push lane and the hosted PR lane (which builds a fresh bundle first) so real-browser reader regressions are caught before release.
+- Reader e2e net strengthened (#281 S5): 9 live reader scenarios including a genuine above-insertion reveal guard (jump to a late message of a large collapsed subagent thread, reveal the earlier messages, and the anchored message stays put) and a below-giants cold-jump guard.
+- `cctally setup`'s first-run cache sync now shows live progress on the terminal — a pre-sync notice, per-file counts, and a background heartbeat so a large session history no longer looks hung during the initial ingest; progress is stderr-only and TTY-gated, so `--json` output and piped/non-interactive runs are unaffected (#281 S7).
+
+### Changed
+- `cctally setup` now ends with the "restart Claude Code" step as a prominent `▶ Next step:` call-to-action (dropping the `⚠`) instead of burying it mid-output, and the README quick start plus the installation guide now clarify that the reporting commands (`daily`, `dashboard`, `tui`) work immediately after install — only auto-recording needs `cctally setup` (#281 S7).
+- `forecast` (`$/1%` median) and `diff` (multi-week average) now reset-aware-floor a credited historical week's usage %, matching every other used-% surface; uncredited weeks are unchanged (#290).
+- Conversation reader: Escape now steps back one level (reader → conversations list → dashboard) instead of ejecting straight to the dashboard, and an open outline sheet is peeled first (#289).
+- Internal (#281 S5): the conversation reader's scroll / pager / live-tail orchestration is extracted into a pure, tested state-machine module plus a thin adapter, with no behavior change beyond the #285/#286 fixes below.
+- Internal (#281 S9): the public-repo mirror switched from per-commit trailer-based replay to release-granular snapshot publishing — each release now appends one whole-tree `release vX.Y.Z` public commit (preserve+append, compare-and-swap, idempotent resume) and the per-commit trailer machinery (commit-msg hook, `--- public ---`/`Public-Skip:` grammar, message sanitizer, skip-chain metrics, ~5.8K maintainer-only lines) is retired; `.mirror-allowlist` + `_match.py` remain the unchanged privacy boundary. Maintainer-only; no user-facing behavior change.
+- Internal (#281 S6): usage-% cross-surface invariants & structural guards — a new U-PCT reconcile-test group pins the usage-% chain (statusline 7d, `weekly` Used %, `report`/`forecast` current %, the dashboard envelope, `project`, and the `record-usage` write clamp) to one reset-aware value across control / mid-week-reset / manual-credit scenarios so a divergence between any two surfaces is caught; a stdlib-`ast` guard asserts every `MAX(weekly_percent)`-over-snapshots read routes through the reset-aware floor (or is a reasoned, issue-tracked exemption); and two guards assert the `bin/cctally` re-export manifest is complete (every name a sibling consumes is re-exported) and never eager-imports a private sibling outside a tolerate-absent guard. No behavior change.
+- The `cctally tui` command is now documented as being in bugfix-only maintenance mode (#281 S10): both layout variants keep working and remain fully supported, but the terminal UI no longer tracks new dashboard features — use `cctally dashboard` for the actively-developed rich UI. No behavior change.
+- Internal (#281 S11): the golden-file test harnesses now memoize their seeded SQLite fixture trees in a content-hash-keyed cache (`bin/_fixture_cache.py`), restoring instead of rebuilding whenever nothing that determines the fixture bytes has changed; the change is strictly additive and fail-safe — any cache problem falls back to running the builder, so a cache issue can never alter a test outcome (cache-on and `CCTALLY_FIXTURE_CACHE=0` produce byte-identical goldens) — with an opt-out (`CCTALLY_FIXTURE_CACHE=0`) and a completeness/relocatability audit (`CCTALLY_FIXTURE_CACHE_VERIFY=1`). Maintainer-only; no user-facing behavior change.
+
+### Fixed
+- Internal (maintainer-only): the public-mirror snapshot publisher and its release-harness test no longer flake on a benign `git archive | tar` SIGPIPE — `tar` stops reading at the archive's end-of-archive marker and closes the pipe before `git archive` finishes writing its trailing record padding, so `git archive` is killed by SIGPIPE (returncode `-13`) while `tar` exits 0; that combination is now recognized as success (the extracted-manifest check remains the completeness backstop) rather than raising `archive|tar failed (archive=-13 tar=0)`. No user-facing behavior change.
+- The Blocks panel's per-block cost bar now renders the **fable** model in its own rose colour instead of the default grey — the gauge segment was missing its `.seg-fable` colour rule while opus/sonnet/haiku had theirs (the legend dot was already correct).
+- 5-hour block start and window times now round to the nearest 10-minute boundary for display everywhere they surface (the dashboard Blocks panel + block-detail modal, and the CLI `blocks` / `five-hour-blocks` / `five-hour-breakdown` tables), so a reset captured with sub-10-minute jitter as e.g. `10:39` shows as `10:40` instead — a long-standing display glitch; the stored timestamps stay exact, so block lookups and partitioning are unaffected.
+- A find-jump into a message inside a collapsed subagent thread no longer yanks the reader to the bottom (#291): while any jump is navigating to a message, the reader disables react-virtuoso's resize-autoscroll-to-bottom watcher, so force-opening a large collapsed thread to reveal the target keeps the viewport on the target instead of snapping to the end.
+- `transcript export` on very large caches no longer cold-starts slowly: the `cwd` lookup used for anonymization is now backed by a partial index, turning a full-table scan into an index-only lookup (#289).
+- Single-page conversations open at the top again (#285): the reader passes react-virtuoso a literal `followOutput={false}` while a top-landing is in flight, so its raw-truthy resize-autoscroll watcher can no longer pull a single-page open to the bottom (multi-page tail opens still land at the bottom with live-tail engaged).
+- Cold-tail outline/find jumps land reliably (#286): jumping to an earlier message from the bottom of a long conversation now waits for the loaded window to catch up before deciding a target is truly unreachable, instead of occasionally clearing the jump before the message finished loading, and walks the full distance to a far target in one pass.
+- Docs truth pass (#281 S1): the README privacy tagline now discloses the anonymous, opt-out install-count telemetry instead of denying it (and the "nothing leaves your machine" absolute is qualified — `cctally never uploads your session data`); the CONTRIBUTING license line is corrected from MIT to Apache-2.0; `docs/architecture.md` and `docs/runtime-data.md` are rewritten to describe the real multi-module layout, the migration framework, and the full 15-table `stats.db` schema (plus the conversation-viewer cache tables); stale claims are fixed for the pricing-dict location, the `doctor` module attribution, the superseded `search_aux` conversation index, and the 5-hour anchor wording; the `blocks` / `five-hour-blocks` / `five-hour-breakdown` trio now cross-reference each other; and the `telemetry` command doc's "no IP ever leaves" claim is made precise.
+
 ## [1.66.0] - 2026-07-10
 
 ### Added

package/README.md

@@ -16,7 +16,7 @@
   <a href="https://github.com/omrikais/cctally/stargazers"><img src="https://img.shields.io/github/stars/omrikais/cctally.svg" alt="GitHub stars"></a>
 </p>
 
-Claude Code's Pro/Max plans meter you on a weekly quota, but the only signal you get is a percentage that creeps up until you cap. `cctally` turns that percentage into something you can act on: it reads your local session logs, computes cost in-process, and shows you **how much each percent of quota is actually costing you, whether you're on track to cap this week, and exactly where the spend is going** - across a live web dashboard, a read-only conversation viewer, and a full set of CLI reports. Everything runs locally against your own `~/.claude` data. No account, no API key, no telemetry, nothing leaves your machine.
+Claude Code's Pro/Max plans meter you on a weekly quota, but the only signal you get is a percentage that creeps up until you cap. `cctally` turns that percentage into something you can act on: it reads your local session logs, computes cost in-process, and shows you **how much each percent of quota is actually costing you, whether you're on track to cap this week, and exactly where the spend is going** - across a live web dashboard, a read-only conversation viewer, and a full set of CLI reports. Everything runs locally against your own `~/.claude` data. No account, no API key, no cloud processing — cctally never uploads your session data, and its only telemetry is an anonymous, opt-out [install count](#privacy--telemetry).
 
 <p align="center">
   <img src="docs/img/dashboard-desktop.png" alt="cctally dashboard, desktop view" width="900">
@@ -37,7 +37,9 @@ npm install -g cctally && cctally setup
 git clone https://github.com/omrikais/cctally && cd cctally && ./bin/cctally setup
 ```
 
-`cctally setup` symlinks the binaries into `~/.local/bin/`, adds three additive hooks to `~/.claude/settings.json` (it never overwrites existing entries), and bootstraps the local SQLite cache. If `~/.local/bin/` isn't on your `PATH`, the script prints the line to add. The npm install needs Python 3 on `PATH` - if setup reports "python3 not found", install it (`brew install python` on macOS) and re-run.
+The reporting commands work right away — you don't need `cctally setup` first. Straight after an install, `npx cctally daily` (or, once it's global, `cctally daily`) reads your existing `~/.claude` session logs directly and prints a cost table; `cctally dashboard` and `cctally tui` work the same way. `cctally setup` is what adds *auto-recording* — the live status-line quota percentage and the hooks that keep data flowing as you work — so run it once you want continuous tracking rather than on-demand reports.
+
+`cctally setup` symlinks the binaries into `~/.local/bin/`, adds three additive hooks to `~/.claude/settings.json` (it never overwrites existing entries), and bootstraps the local SQLite cache — on a large session history that first-run sync now shows live progress instead of sitting silent. If `~/.local/bin/` isn't on your `PATH`, the script prints the line to add. The npm install needs Python 3 on `PATH` - if setup reports "python3 not found", install it (`brew install python` on macOS) and re-run.
 
 ```bash
 cctally setup --status     # verify hooks + symlinks
@@ -120,7 +122,7 @@ Get a native desktop notification the moment you cross a percent milestone, so a
 
 ## 5-hour analytics
 
-Claude Code's quota also runs on rolling 5-hour windows. `cctally blocks` and `cctally five-hour-blocks` break usage down per window - anchored to the real API resets, not a re-sizable guess - with model and project rollups and cross-reset flags, and `cctally five-hour-breakdown` drills into the per-percent milestones inside a single block.
+Claude Code's quota also runs on rolling 5-hour windows. `cctally blocks` and `cctally five-hour-blocks` break usage down per window - anchored to the real API resets where a recorded reset covers the window (`blocks` marks its heuristic fallback rows with `~`), not a re-sizable guess - with model and project rollups and cross-reset flags, and `cctally five-hour-breakdown` drills into the per-percent milestones inside a single block.
 
 <p align="center">
   <img src="docs/img/cli-five-hour-blocks.svg" alt="cctally five-hour-blocks: 5h analytics with model breakdown">
@@ -156,7 +158,7 @@ If you also use OpenAI's Codex CLI, `cctally codex daily / monthly / session` ar
 
 ## Privacy & telemetry
 
-cctally sends an anonymous, opt-out **install-count beat** — at most once a day — so the project can gauge how many people actually use it (npm and GitHub numbers are drowned in bots and mirrors). The entire payload is a one-way token that rotates every month (derived from a random local id that never leaves your machine and can't be recovered from the token), the cctally version, and a coarse OS family (`macos`/`linux`/`windows`/`other`). No identity, file paths, prompts, usage data, or stored IP — ever. Nothing leaves your machine for at least 24 hours after first run, so you always have a window to opt out first.
+cctally sends an anonymous, opt-out **install-count beat** — at most once a day — so the project can gauge how many people actually use it (npm and GitHub numbers are drowned in bots and mirrors). The entire payload is a one-way token that rotates every month (derived from a random local id that never leaves your machine and can't be recovered from the token), the cctally version, and a coarse OS family (`macos`/`linux`/`windows`/`other`). No identity, file paths, prompts, usage data, or stored IP — ever. The first beat is held for at least 24 hours after first run, so you always have a window to opt out first.
 
 Turn it off any time with `cctally telemetry off` (or `cctally config set telemetry.enabled false`, `CCTALLY_DISABLE_TELEMETRY=1`, or the community-standard `DO_NOT_TRACK=1`); it's also off automatically in dev checkouts. Run `cctally telemetry` to see the current state and exactly what would be sent. The full transparency page — token construction, retention, and an honest threat model — is [docs/telemetry.md](docs/telemetry.md).
 

package/bin/_cctally_core.py

@@ -1671,6 +1671,82 @@ def _reset_aware_floor(
     return row[0] if row and row[0] else None
 
 
+def _floored_week_max(conn, rows):
+    """Return {week_key -> per-week reset-aware-floored maximum weekly_percent}.
+
+    ``rows`` is an iterable of
+      (week_key, week_start_date, week_start_at, week_end_at,
+       captured_at_utc, weekly_percent).
+
+    Two-pass so floor resolution is independent of row order (#290): pass 1
+    buckets rows per ``week_key`` and canonicalizes each week's first non-NULL
+    (week_start_at, week_end_at) + its week_start_date; pass 2 resolves
+    ``_reset_aware_floor`` once per week (keyed on week_start_date) and drops
+    captures earlier than that floor before taking the week's maximum
+    ``weekly_percent``. ``week_key`` is the caller's aggregation key (1:1 with a
+    week); floor identity is week_start_date, so a NULL-bound legacy row cannot
+    suppress the reset-event leg for a later anchored row of the same week.
+
+    A NULL ``weekly_percent`` row is skipped. An unparseable ``captured_at_utc``
+    under an active floor is RETAINED (epoch unknown), matching
+    ``_cctally_project._load_week_snapshots``. All-NULL bounds resolve
+    credit-floor-leg-only (the reset leg is inert: unixepoch(NULL) is NULL).
+    A week whose every in-scope row is pre-floor is absent from the result.
+    """
+    # Pass 1: bucket + canonicalize bounds.
+    buckets: dict = {}
+    for wk, wsd, ws_at, we_at, cap, pct in rows:
+        if pct is None:
+            continue
+        b = buckets.get(wk)
+        if b is None:
+            buckets[wk] = {
+                "wsd": wsd, "ws_at": ws_at, "we_at": we_at,
+                "rows": [(cap, float(pct))],
+            }
+            continue
+        if b["wsd"] is None and wsd is not None:
+            b["wsd"] = wsd
+        if b["ws_at"] is None and ws_at is not None:
+            b["ws_at"] = ws_at
+        if b["we_at"] is None and we_at is not None:
+            b["we_at"] = we_at
+        b["rows"].append((cap, float(pct)))
+
+    # Pass 2: resolve floor once per week, drop pre-floor captures, take max.
+    result: dict = {}
+    for wk, b in buckets.items():
+        floor_iso = _reset_aware_floor(conn, b["wsd"], b["ws_at"], b["we_at"])
+        floor_epoch = None
+        if floor_iso:
+            try:
+                floor_epoch = int(
+                    parse_iso_datetime(
+                        floor_iso, "floored_week_max.floor"
+                    ).timestamp()
+                )
+            except ValueError:
+                floor_epoch = None
+        best = None
+        for cap, pct in b["rows"]:
+            if floor_epoch is not None and cap is not None:
+                try:
+                    cap_epoch = int(
+                        parse_iso_datetime(
+                            str(cap), "floored_week_max.cap"
+                        ).timestamp()
+                    )
+                except ValueError:
+                    cap_epoch = None
+                if cap_epoch is not None and cap_epoch < floor_epoch:
+                    continue
+            if best is None or pct > best:
+                best = pct
+        if best is not None:
+            result[wk] = best
+    return result
+
+
 def get_latest_usage_for_week(
     conn: sqlite3.Connection,
     week_ref: WeekRef,

package/bin/_cctally_dashboard.py

@@ -349,7 +349,7 @@ from _lib_display_tz import (
 from _lib_aggregators import _aggregate_daily, _aggregate_monthly, _aggregate_weekly
 from _lib_fmt import stable_sum
 from _lib_pricing import _calculate_entry_cost, _chip_for_model, _short_model_name
-from _lib_five_hour import _canonical_5h_window_key
+from _lib_five_hour import _canonical_5h_window_key, _round_to_ten_minutes
 from _lib_subscription_weeks import _compute_subscription_weeks
 from _lib_blocks import _group_entries_into_blocks
 # #279 S2 F3: stdlib-logging chokepoint — server errors reach stderr via
@@ -528,6 +528,7 @@ from _cctally_dashboard_conversation import (
     _handle_get_conversation_outline_impl,
     _handle_get_conversation_prompts_impl,
     _handle_get_conversation_export_impl,
+    _handle_get_conversation_anon_map_impl,
     _handle_get_conversation_find_impl,
     _handle_get_conversation_media_impl,
 )
@@ -1787,8 +1788,13 @@ def _build_block_detail(block: "Block",
                           if block.actual_end_time else None),
         "anchor":   block.anchor,
         "is_active": bool(block.is_active and block.entries_count > 0),
+        # ``label`` rounds the shown start to the nearest 10-min boundary
+        # (reset-jitter normalization); ``start_at`` / ``end_at`` above stay
+        # exact — they echo the canonical interval and the lookup matches
+        # ``start_at`` by exact equality (issue #76).
         "label":    format_display_dt(
-            block.start_time, display_tz, fmt="%H:%M %b %d", suffix=True,
+            _round_to_ten_minutes(block.start_time),
+            display_tz, fmt="%H:%M %b %d", suffix=True,
         ),
 
         "entries_count": block.entries_count,
@@ -3615,6 +3621,9 @@ _GET_ROUTES = (
     ("prefix+suffix", ("/api/conversation/", "/export"),
      "_handle_get_conversation_export",
      ("scope", "endpoint.conversation_export"), True),
+    ("prefix+suffix", ("/api/conversation/", "/anon-map"),
+     "_handle_get_conversation_anon_map",
+     ("scope", "endpoint.conversation_anon_map"), True),
     ("prefix+suffix", ("/api/conversation/", "/prompts"),
      "_handle_get_conversation_prompts",
      ("scope", "endpoint.conversation_prompts"), True),
@@ -5161,6 +5170,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     def _handle_get_conversation_export(self, path: str) -> None:
         return _handle_get_conversation_export_impl(self, path)
 
+    def _handle_get_conversation_anon_map(self, path: str) -> None:
+        return _handle_get_conversation_anon_map_impl(self, path)
+
     def _handle_get_conversation_find(self, path: str) -> None:
         return _handle_get_conversation_find_impl(self, path)
 

package/bin/_cctally_dashboard_conversation.py

@@ -604,20 +604,41 @@ def _handle_get_conversation_export_impl(handler, path: str) -> None:
     Blob/filename, so no ``Content-Disposition`` is needed)."""
     if not handler._require_transcripts_allowed():
         return
+    import os as _os
     import urllib.parse as _u
+    qs = handler.path.partition("?")[2]
     session_id = _u.unquote(path[len("/api/conversation/"):-len("/export")])
-    q = _u.parse_qs(handler.path.partition("?")[2])
+    q = _u.parse_qs(qs)
     scope = _qs_str(q, "scope", "all")
     if scope not in _CONV_EXPORT_SCOPES:
         handler._respond_json(400, {"error": f"unknown scope: {scope}"})
         return
+    # #281 S4: `anonymize` gets its OWN strict parse (the default parse_qs /
+    # _qs_str path silently drops blanks + first-picks duplicates). It must
+    # appear at most once and be literal `0` or `1`; blank / duplicate / any
+    # other spelling is a clean 400 HERE, BEFORE the kernel (the
+    # _run_conversation_query-collapses-kernel-exceptions-to-500 gotcha). Absent
+    # → raw (the R4 "raw export byte-unchanged" acceptance is structural).
+    avals = _u.parse_qs(qs, keep_blank_values=True).get("anonymize")
+    if avals is not None and (len(avals) != 1 or avals[0] not in ("0", "1")):
+        handler._respond_json(400, {"error": f"invalid anonymize: {avals}"})
+        return
+    anonymize = avals is not None and avals[0] == "1"
     if not session_id:
         handler.send_error(404, "conversation not found")
         return
+
+    def _kernel(conn):
+        cq = handler._conversation_query()
+        md = cq.get_conversation_export(conn, session_id, scope)
+        if md is None or not anonymize:
+            return md
+        anon = sys.modules["cctally"]._load_sibling("_lib_conversation_anon")
+        plan = cq.build_anon_plan_for_db(conn, home_dir=_os.path.expanduser("~"))
+        return anon.scrub_text(md, plan)
+
     ok, body = handler._run_conversation_query(
-        lambda conn: handler._conversation_query().get_conversation_export(
-            conn, session_id, scope),
-        "/api/conversation/export")
+        _kernel, "/api/conversation/export")
     if not ok:
         return
     if body is None:
@@ -630,6 +651,44 @@ def _handle_get_conversation_export_impl(handler, path: str) -> None:
     handler.end_headers()
     handler.wfile.write(data)
 
+def _handle_get_conversation_anon_map_impl(handler, path: str) -> None:
+    """``GET /api/conversation/<sid>/anon-map`` — the ``plan_to_wire`` JSON the
+    client-side scrubber executes for per-card copy (#281 S4, spec §5).
+
+    Same fail-closed transcript privacy gate as the sibling reader routes —
+    ``_require_transcripts_allowed()`` ONLY (no ``_check_origin_csrf``). Although
+    the plan is GLOBAL, the route probes existence (``conversation_exists``) and
+    404s on an unknown ``<sid>``, matching sibling envelope discipline — never a
+    token dump for a non-session. Contains only tokens the same gated client
+    already sees raw, so no new information exposure. Matched BEFORE the bare
+    ``<id>`` detail catch-all in ``do_GET`` (route-ordering test asserts the
+    suffix does not fall through)."""
+    if not handler._require_transcripts_allowed():
+        return
+    import os as _os
+    import urllib.parse as _u
+    session_id = _u.unquote(path[len("/api/conversation/"):-len("/anon-map")])
+    if not session_id:
+        handler.send_error(404, "conversation not found")
+        return
+    anon = sys.modules["cctally"]._load_sibling("_lib_conversation_anon")
+
+    def _kernel(conn):
+        cq = handler._conversation_query()
+        if not cq.conversation_exists(conn, session_id):
+            return None
+        plan = cq.build_anon_plan_for_db(conn, home_dir=_os.path.expanduser("~"))
+        return anon.plan_to_wire(plan)
+
+    ok, body = handler._run_conversation_query(
+        _kernel, "/api/conversation/anon-map")
+    if not ok:
+        return
+    if body is None:
+        handler.send_error(404, "conversation not found")
+        return
+    handler._respond_json(200, body)
+
 def _handle_get_conversation_find_impl(handler, path: str) -> None:
     """``GET /api/conversation/<sid>/find?q=...&kind=...`` — in-conversation
     find → document-ordered rendered-turn anchors (#177 S6). Same fail-closed

package/bin/_cctally_db.py

@@ -2400,6 +2400,16 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
             ON conversation_messages(source_path);
         CREATE INDEX IF NOT EXISTS idx_conv_turnkey
             ON conversation_messages(msg_id, req_id);
+        -- #289: partial covering index on cwd. build_anon_plan_for_db sources
+        -- anonymization tokens with `SELECT DISTINCT cwd FROM conversation_messages
+        -- WHERE cwd IS NOT NULL AND cwd != ''`; without this index that DISTINCT is
+        -- a full scan of the whole (prose-heavy) table (~20s cold on a 5.5 GB
+        -- cache). The partial `(cwd)` index matches the WHERE exactly so the
+        -- DISTINCT is answered by an ordered index-only walk. MIRRORS migration 021
+        -- (base schema here for fresh/rebuilt caches, migration for existing ones).
+        CREATE INDEX IF NOT EXISTS idx_conversation_messages_cwd
+            ON conversation_messages(cwd)
+            WHERE cwd IS NOT NULL AND cwd != '';
 
         -- #193: per-session AI-generated title, isolated from the six places
         -- that iterate conversation_messages. The explicit NOT NULL on the
@@ -3987,6 +3997,27 @@ def _020_session_entries_physical_unique(conn: sqlite3.Connection) -> None:
             lock_fh.close()
 
 
+@cache_migration("021_index_conversation_messages_cwd")
+def _021_index_conversation_messages_cwd(conn: sqlite3.Connection) -> None:
+    """#289: partial covering index on conversation_messages(cwd) to collapse the
+    full-table `SELECT DISTINCT cwd` scan in build_anon_plan_for_db (~20s cold on
+    a 5.5 GB cache) into an index-only search.
+
+    Fresh installs never run this handler: the dispatcher stamps it WITHOUT
+    running (the fresh-install branch), and `_apply_cache_schema` already created
+    the index on the fresh DB. NO self-stamp — the dispatcher central-stamps on a
+    clean return (#140). Run-twice safe: CREATE INDEX is IF NOT EXISTS. cache.db
+    is re-derivable — `cache-sync --rebuild` is the escape hatch.
+
+    No flock/BEGIN IMMEDIATE (unlike 020): a single CREATE INDEX IF NOT EXISTS is
+    atomic and touches no rows, so it needs no mutual-exclusion scaffolding.
+    """
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_conversation_messages_cwd "
+        "ON conversation_messages(cwd) WHERE cwd IS NOT NULL AND cwd != ''"
+    )
+
+
 # === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
 
 @stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")

package/bin/_cctally_five_hour.py

@@ -847,9 +847,17 @@ def _format_block_start(iso: str, tz: "ZoneInfo | None") -> str:
     Renders as ``YYYY-MM-DD HH:MM <SUFFIX>`` where the suffix is the
     zone label per ``display_tz_label``. Naive inputs are treated as
     UTC; ``tz=None`` means "host-local via bare astimezone()".
+
+    The displayed time is rounded to the nearest 10-minute boundary to
+    normalize Anthropic reset-capture jitter (e.g. a :39 recorded reset
+    renders as :40). The stored ``block_start_at`` is unchanged.
     """
     _c = _cctally()
-    return _c.format_display_dt(iso, tz, fmt="%Y-%m-%d %H:%M", suffix=True)
+    parsed = dt.datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    return _c.format_display_dt(
+        _c._round_to_ten_minutes(parsed), tz,
+        fmt="%Y-%m-%d %H:%M", suffix=True,
+    )
 
 
 def _format_hhmm_in_tz(iso: str, tz: "ZoneInfo | None") -> str:
@@ -858,9 +866,16 @@ def _format_hhmm_in_tz(iso: str, tz: "ZoneInfo | None") -> str:
     Mirrors ``_format_block_start``'s tz resolution so paired start/end
     cells in the same row stay in the same zone. Naive inputs are
     treated as UTC; ``tz=None`` means host-local. No suffix.
+
+    Rounded to the nearest 10-minute boundary for the same reset-jitter
+    normalization as ``_format_block_start`` (the paired start/end cells
+    must round together or a 5h window renders as 4h59m/5h01m).
     """
     _c = _cctally()
-    return _c.format_display_dt(iso, tz, fmt="%H:%M", suffix=False)
+    parsed = dt.datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    return _c.format_display_dt(
+        _c._round_to_ten_minutes(parsed), tz, fmt="%H:%M", suffix=False,
+    )
 
 
 def _block_is_active(

package/bin/_cctally_forecast.py

@@ -359,40 +359,54 @@ def _select_dollars_per_percent(
     if p_now >= 10.0 and p_now > 0:
         return spent_usd / p_now, "this_week"
 
-    # Path 2: trailing 4-week median.
-    # Fetch all eligible prior weeks then Python-filter (legacy rows may carry
-    # non-UTC offsets that break lexical compare against an ISO-UTC bound).
-    rows = conn.execute(
-        "SELECT week_start_at, week_end_at, MAX(weekly_percent) AS final_pct, "
-        "       MAX(captured_at_utc) AS latest_cap "
+    # Path 2: trailing 4-week median, reset-aware floored (#290).
+    import statistics
+    # Bounded candidate selection: the <=12 most-recent prior weeks. The median
+    # needs 4 eligible; 12 leaves margin so flooring a credited week below 1%
+    # can't starve it, while keeping this hot path (live forecast view +
+    # dashboard refresh) from materializing all history.
+    cand = conn.execute(
+        "SELECT DISTINCT week_start_at, week_end_at, week_start_date "
         "FROM weekly_usage_snapshots "
         "WHERE week_start_at IS NOT NULL AND week_end_at IS NOT NULL "
-        "GROUP BY week_start_at "
-        "HAVING MAX(weekly_percent) >= 1"
+        "  AND datetime(week_start_at) < datetime(?) "
+        "ORDER BY datetime(week_start_at) DESC LIMIT 12",
+        (current_week_start.isoformat(),),
     ).fetchall()
-    by_instant: dict[dt.datetime, dict] = {}
-    for r in rows:
-        try:
-            ws = parse_iso_datetime(r[0], "week_start_at")
-            we = parse_iso_datetime(r[1], "week_end_at")
-        except ValueError:
-            continue
-        slot = by_instant.get(ws)
-        final_pct = float(r[2])
-        if slot is None:
-            by_instant[ws] = {"we": we, "final_pct": final_pct}
-        else:
-            slot["final_pct"] = max(slot["final_pct"], final_pct)
-
+    we_by_ws: dict[dt.datetime, dt.datetime] = {}
+    rows_in: list = []
+    ws_iso_list = [row[0] for row in cand]
+    if ws_iso_list:
+        placeholders = ",".join("?" * len(ws_iso_list))
+        snap = conn.execute(
+            "SELECT week_start_date, week_start_at, week_end_at, "
+            "       captured_at_utc, weekly_percent "
+            "FROM weekly_usage_snapshots "
+            "WHERE week_start_at IN (" + placeholders + ")",
+            ws_iso_list,
+        ).fetchall()
+        for wsd, ws_iso, we_iso, cap_iso, pct in snap:
+            if pct is None:
+                continue
+            try:
+                ws = parse_iso_datetime(ws_iso, "week_start_at")
+                we = parse_iso_datetime(we_iso, "week_end_at")
+            except ValueError:
+                continue
+            we_by_ws.setdefault(ws, we)  # first-wins; all rows share one instant
+            rows_in.append((ws, wsd, ws_iso, we_iso, cap_iso, pct))
+    floored = c._floored_week_max(conn, rows_in)  # {ws_instant -> floored max}
     eligible: list[tuple[dt.datetime, dt.datetime, float]] = [
-        (ws, v["we"], v["final_pct"])
-        for ws, v in by_instant.items()
-        if ws < current_week_start and v["we"] < now_utc and v["final_pct"] >= 1.0
+        (ws, we_by_ws[ws], floored[ws])
+        for ws in floored
+        if ws in we_by_ws
+        and ws < current_week_start
+        and we_by_ws[ws] < now_utc
+        and floored[ws] >= 1.0
     ]
     eligible.sort(key=lambda x: x[0], reverse=True)
     prior = eligible[:4]
     if len(prior) >= 4:
-        import statistics
         values: list[float] = []
         for ws, we, final_pct in prior:
             if use_weekref_cost_cache:

package/bin/_cctally_parser.py

@@ -2400,6 +2400,96 @@ def _build_setup_parser(subparsers, name, *, help_text, xref=None):
     )
     sp.set_defaults(func=c.cmd_setup)
 
+def _build_transcript_parser(subparsers, name, *, help_text, xref=None):
+    """Build the `transcript` parser (#281 S4) — nested export|search subgroup,
+    following the `db` subgroup precedent (call-time `c = _cctally()` binding,
+    both sub-actions dispatch to `c.cmd_transcript` on `transcript_action`)."""
+    c = _cctally()
+    t_parser = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Export or search conversation transcripts from the local cache.
+
+            Subcommands:
+              export   Whole-session Markdown. ANONYMIZED BY DEFAULT (observed
+                       project paths/labels, home dir, and username → project-N/
+                       ~/user, plus documented secret patterns redacted). --raw
+                       disables the whole scrub, byte-identical to the dashboard's
+                       raw export. Best-effort over KNOWN tokens — review before
+                       sharing (see docs/commands/transcript.md).
+              search   Cross-session FTS/LIKE search. Output is RAW (a navigation
+                       surface, not a sharing artifact).
+
+            Examples:
+              cctally transcript export <session-id>
+              cctally transcript export <session-id> --scope chat --raw
+              cctally transcript export <session-id> -o session.md
+              cctally transcript search "reset window"
+              cctally transcript search needle --kind prompts --json
+            """
+        ),
+        epilog="See docs/commands/transcript.md for exit codes + the exact "
+               "is/isn't-covered redaction list.",
+    )
+    t_sub = t_parser.add_subparsers(dest="transcript_action", required=True)
+
+    t_export = t_sub.add_parser(
+        "export", help="Export a whole session as Markdown (anonymized by default)",
+        formatter_class=CLIHelpFormatter)
+    t_export.add_argument("session_id", metavar="SESSION_ID",
+                          help="Claude sessionId to export")
+    t_export.add_argument(
+        "--scope", choices=("all", "prompts", "chat", "recipe"), default="all",
+        help="Which slice to export (default: all)")
+    t_export.add_argument(
+        "--raw", action="store_true",
+        help="Disable the whole scrub (identity + secrets); byte-identical to "
+             "the dashboard raw export")
+    t_export.add_argument(
+        "-o", "--output", metavar="PATH", default=None,
+        help="Write to PATH instead of stdout (same exact bytes)")
+    t_export.set_defaults(func=c.cmd_transcript)
+
+    t_search = t_sub.add_parser(
+        "search", help="Search transcripts across sessions (raw output)",
+        formatter_class=CLIHelpFormatter)
+    t_search.add_argument("query", metavar="QUERY", help="Search text")
+    t_search.add_argument(
+        "--kind",
+        choices=("all", "prompts", "assistant", "tools", "thinking",
+                 "title", "files"),
+        default="all", help="Search facet (default: all)")
+    t_search.add_argument("--limit", type=int, default=50,
+                          help="Max results (default: 50)")
+    t_search.add_argument("--offset", type=int, default=0,
+                          help="Result offset for pagination (default: 0)")
+    t_search.add_argument("--project", action="append", default=None,
+                          metavar="LABEL",
+                          help="Filter by project label (repeatable)")
+    t_search.add_argument("--model", action="append", default=None,
+                          metavar="FAMILY",
+                          help="Filter by model family (repeatable)")
+    t_search.add_argument("--date-from", dest="date_from", default=None,
+                          metavar="YYYY-MM-DD",
+                          help="Only sessions on/after this date (display tz)")
+    t_search.add_argument("--date-to", dest="date_to", default=None,
+                          metavar="YYYY-MM-DD",
+                          help="Only sessions on/before this date (display tz)")
+    t_search.add_argument("--cost-min", dest="cost_min", type=float, default=None,
+                          metavar="USD", help="Min session cost")
+    t_search.add_argument("--cost-max", dest="cost_max", type=float, default=None,
+                          metavar="USD", help="Max session cost")
+    t_search.add_argument("--rebuild-min", dest="rebuild_min", type=int,
+                          default=None, metavar="N",
+                          help="Min cache-rebuild count")
+    t_search.add_argument("--json", action="store_true", dest="json",
+                          help="Emit JSON (schemaVersion: 1)")
+    t_search.set_defaults(func=c.cmd_transcript)
+
+
 def _build_db_parser(subparsers, name, *, help_text, xref=None):
     """Build the `db` parser (registered via _REGISTRATION; #279 S6 W3).
 
@@ -2808,6 +2898,7 @@ _REGISTRATION = (
     _Reg('project', _build_project_parser, "Roll usage up by project (git-root), with per-project Used %% attribution", None, None),
     _Reg('diff', _build_diff_parser, "Compare Claude usage between two windows.", None, None),
     _Reg('session', _build_session_parser, "Show Claude usage grouped by sessionId (merges resumed-across-files sessions)", "Alias of `cctally claude session` (the canonical form).", None),
+    _Reg('transcript', _build_transcript_parser, "Export or search conversation transcripts (anonymized export by default)", None, None),
     _Reg('claude', _build_claude_parser, "Claude-source reports (drop-in for `ccusage claude …`)", None, None),
     _Reg('codex', _build_codex_parser, "Codex-source reports (drop-in for `ccusage codex …`)", None, None),
     _Reg('config', _build_config_parser, "Get / set / unset persisted user preferences", None, None),