cctally 1.50.0 → 1.51.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.51.0] - 2026-06-19
+
+### Added
+- **`record-credit` — manually record an in-place weekly credit the auto-detector misses.** When Anthropic lowers your 7-day usage counter mid-window by a sub-25pp, non-zero amount (e.g. 46%→31%) instead of a clean reset, neither auto-detector fires and the monotonic clamp pins every display at the stale peak. `cctally record-credit --to 31` records the credit explicitly and repairs the data while keeping the **same week** (no re-anchor): it records a clamp floor for the current week, lowers `hwm-7d`, clears stale replays, and inserts a post-credit snapshot so reports and the statusline read the credited value while the week boundaries and the forecast rate stay correct. As usage resumes, a later reading below the pre-credit peak (e.g. 37%) is stored normally rather than suppressed. Preview-and-confirm by default (`--dry-run` / `--yes`), with `--from` / `--at` / `--week` overrides, a `--force` clean re-record that never touches real history, and a `--json` (schemaVersion 1) envelope. See `docs/commands/record-credit.md`.
+
+### Fixed
+- **Dashboard conversation viewer — the mobile fix that stops the sticky topbar from hiding `← Back` now holds on notched phones, and in-page panel jumps land correctly.** The mobile topbar height budget (`--topbar-h`) was a flat 104px, but the real two-row mobile header renders ~148px; the #205 reader-height fix compensated only for the no-safe-area (headless) case, so on a notched device (`env(safe-area-inset-top)`) roughly 30px of document overflow returned and the sticky topbar could again scroll over the reader's `← Back` button. `--topbar-h` is now measured safe-area-aware (`calc(142px + max(6px, env(safe-area-inset-top)))`) so it tracks the real header height at any inset — the conversation reader fills the viewport with no document overflow on every phone, and because that same variable is every panel's scroll-anchor floor, in-page jumps and `scrollIntoView()` now land panel titles flush just below the header instead of ~44px under it. Desktop is byte-identical (#206).
+
 ## [1.50.0] - 2026-06-18
 
 ### Fixed

package/bin/_cctally_core.py

@@ -1365,6 +1365,34 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # In-place weekly partial-credit floor (issue #209, record-credit M2).
+    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / NO user_version
+    # bump — the same framework-untracked posture as `project_budget_milestones`
+    # above. A `record-credit` invocation records a weekly credit (e.g.
+    # 46% -> 31%) WITHOUT writing a `week_reset_events` row: a credit lowers the
+    # current-7d clamp floor only and must NOT re-anchor the week window (the
+    # `week_reset_events`-driven window-resolution code would otherwise show a
+    # spurious "new week" and corrupt the forecast rate). `_reset_aware_floor`
+    # (below) unions this table with `week_reset_events` so the four MAX-clamp
+    # sites floor the current % to the post-credit value while the window stays
+    # put. `effective_at_utc` is `floor_to_hour(at)` in UTC; `applied_at_utc` is
+    # audit-only (kept out of goldens). Lives BEFORE the migration dispatcher: a
+    # plain CREATE on a framework-untracked table never touches
+    # `schema_migrations`, so the dispatcher's fresh-install snapshot is
+    # unaffected. See docs/superpowers/specs/2026-06-19-record-credit-weekly-design.md §2/§4a.
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS weekly_credit_floors (
+            id                      INTEGER PRIMARY KEY AUTOINCREMENT,
+            week_start_date         TEXT    NOT NULL,
+            effective_at_utc        TEXT    NOT NULL,
+            observed_pre_credit_pct REAL    NOT NULL,
+            applied_at_utc          TEXT    NOT NULL,
+            UNIQUE(week_start_date, effective_at_utc)
+        )
+        """
+    )
+
     # Migration framework dispatcher. Replaces the prior inline gate stack
     # (has_blocks + _migration_done) with the framework's _run_pending_-
     # migrations entry point. See spec §2.3, §5.2 + the migration handlers
@@ -1523,6 +1551,54 @@ def _get_latest_row_for_week(
     ).fetchone()
 
 
+def _reset_aware_floor(
+    conn: sqlite3.Connection,
+    week_start_date: str,
+    week_start_at: str,
+    week_end_at: str,
+) -> str | None:
+    """Return the latest in-week clamp floor (an ISO timestamp) across BOTH
+    `week_reset_events` and `weekly_credit_floors`, or None when neither has a
+    row for this week.
+
+    This is the single chokepoint the four MAX-clamp sites consult to floor the
+    current 7d % to the most-recent in-place credit / reset effective moment
+    (record-credit M2, issue #209, spec §4a):
+      - statusline `_hwm_clamp` 7d (bin/_cctally_statusline.py)
+      - the record-usage write-site monotonic clamp (bin/_cctally_record.py)
+      - `_resolve_reset_aware_hwm` (the --from default helper)
+      - `project`'s `_load_week_snapshots` per-week MAX (bin/_cctally_project.py)
+
+    A `week_reset_events` row counts iff its `effective_reset_at_utc` falls in
+    `[week_start_at, week_end_at)`; a `weekly_credit_floors` row counts iff its
+    `week_start_date` matches (record-credit always stamps `effective_at_utc`
+    inside the week, validated at plan-build time).
+
+    The latest floor wins via `ORDER BY unixepoch(floor_at) DESC LIMIT 1` —
+    `unixepoch()`, NOT a textual `MAX(...)`: the two legs carry mixed offset
+    spellings (`Z` / `+00:00`), and a lexical MAX would silently mis-order them
+    on a non-UTC host (the same gotcha as the statusline clamp / 5h-block
+    cross-reset flag; see the comment at bin/_cctally_statusline.py)."""
+    row = conn.execute(
+        """
+        SELECT floor_at FROM (
+            SELECT effective_reset_at_utc AS floor_at
+              FROM week_reset_events
+             WHERE unixepoch(effective_reset_at_utc) >= unixepoch(?)
+               AND unixepoch(effective_reset_at_utc) <  unixepoch(?)
+            UNION ALL
+            SELECT effective_at_utc AS floor_at
+              FROM weekly_credit_floors
+             WHERE week_start_date = ?
+        )
+        ORDER BY unixepoch(floor_at) DESC
+        LIMIT 1
+        """,
+        (week_start_at, week_end_at, week_start_date),
+    ).fetchone()
+    return row[0] if row and row[0] else None
+
+
 def get_latest_usage_for_week(
     conn: sqlite3.Connection,
     week_ref: WeekRef,

package/bin/_cctally_dashboard.py

@@ -4988,6 +4988,18 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "_error":       f"{type(exc).__name__}: {exc}",
         }
 
+    # B1 (#207): the "vs last week" header delta reuses the is_current trend
+    # row's delta_dpp ($/1% vs the previous trend row — normally the prior
+    # subscription week). Select by the is_current FLAG, not snap.trend[-1]:
+    # snap.trend is oldest-first by week_start_date and reset/credit handling
+    # can synthesize an intervening row, so position -1 is not guaranteed to
+    # be the current week (Codex P1). reversed() picks the latest if ever
+    # multiple are flagged. Null-safe: None when no row is current, or when
+    # the current row's delta_dpp is itself None — both hide the stat.
+    _current_trend = next(
+        (r for r in reversed(snap.trend) if r.is_current), None
+    ) if snap.trend else None
+
     return {
         "envelope_version": 2,
         "generated_at":     _iso_z(snap.generated_at),
@@ -5011,7 +5023,9 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "dollar_per_pct":     dollar_pp,
             "forecast_pct":       header_fcast_pct,
             "forecast_verdict":   verdict,
-            "vs_last_week_delta": None,   # populated if/when trend comparison lands
+            "vs_last_week_delta": (
+                _current_trend.delta_dpp if _current_trend is not None else None
+            ),
         },
 
         "current_week":
@@ -5387,6 +5401,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         if path == "/":
             self._serve_static_file(self.static_dir / "dashboard.html",
                                     "text/html; charset=utf-8")
+        elif path == "/favicon.ico":
+            # #207 D11 — serve the SVG favicon for the browser's default
+            # /favicon.ico request so it stops 404-ing even absent the
+            # <link rel="icon"> in dashboard.html. Vite copies public/ verbatim
+            # into the build output, so favicon.svg lands under static_dir.
+            self._serve_static_file(self.static_dir / "favicon.svg",
+                                    "image/svg+xml")
         elif path.startswith("/static/"):
             # Defense in depth: a lexical ".." pre-check is bypassable via
             # percent-encoding (e.g., %2e%2e), so the authoritative guard is the

package/bin/_cctally_parser.py

@@ -1610,6 +1610,51 @@ def build_parser() -> argparse.ArgumentParser:
     )
     ru.set_defaults(func=c.cmd_record_usage)
 
+    rc = sub.add_parser(
+        "record-credit",
+        help="Record an in-place weekly credit the auto-detector misses",
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Record an in-place weekly (7d) credit that the auto-detector
+            misses (a sub-25pp, non-zero drop — e.g. Anthropic lowered your
+            7d % from 46 to 31 without a clean reset). Writes a
+            weekly_credit_floors clamp row (no week re-anchor — the same week
+            continues), lowers hwm-7d, and inserts a post-credit snapshot so
+            reports and the statusline read the credited value.
+            Preview + confirm by default.
+            """
+        ),
+        epilog=textwrap.dedent(
+            """\
+            Examples:
+              cctally record-credit --to 31              # baseline auto-read from HWM
+              cctally record-credit --to 31 --dry-run    # preview, write nothing
+              cctally record-credit --to 31 --yes        # apply without prompting
+
+            Exit codes: 0 success (incl. --dry-run and an interactive decline),
+            2 validation/refuse, 3 on a database error.
+            """
+        ),
+    )
+    rc.add_argument("--to", required=True, type=float,
+                    help="New post-credit weekly %% (0-100).")
+    rc.add_argument("--from", dest="from_pct", metavar="FROM", type=float, default=None,
+                    help="Pre-credit baseline %% (default: current HWM for the week).")
+    rc.add_argument("--at", default=None,
+                    help="Effective credit moment (ISO; naive=UTC; default now).")
+    rc.add_argument("--week", default=None,
+                    help="week_start_date YYYY-MM-DD (default: current week).")
+    rc.add_argument("--dry-run", action="store_true",
+                    help="Preview only; write nothing.")
+    rc.add_argument("--yes", action="store_true",
+                    help="Apply without the confirm prompt.")
+    rc.add_argument("--force", action="store_true",
+                    help="Re-record when a credit is already fully recorded for the week.")
+    rc.add_argument("--json", action="store_true",
+                    help="Machine output (schemaVersion 1).")
+    rc.set_defaults(func=c.cmd_record_credit)
+
     rfu = sub.add_parser(
         "refresh-usage",
         help="Force-fetch 7d/5h percent from OAuth API and record it",

package/bin/_cctally_project.py

@@ -26,7 +26,13 @@ import json
 import os
 import sys
 
-from _cctally_core import _command_as_of, eprint, open_db, parse_iso_datetime
+from _cctally_core import (
+    _command_as_of,
+    _reset_aware_floor,
+    eprint,
+    open_db,
+    parse_iso_datetime,
+)
 from _lib_fmt import stable_sum
 
 
@@ -53,22 +59,59 @@ def _load_week_snapshots(
     `+03:00` from pre-UTC-cast canonicalizer history) coalesce into one
     bucket instead of splitting and silently dropping the higher value.
 
+    Reset-aware (record-credit M2, #209): each week's MAX is restricted to
+    snapshots captured at-or-after that week's latest in-place clamp floor
+    (`_reset_aware_floor`, the union of `week_reset_events` +
+    `weekly_credit_floors`). Without this, a credited week's per-project Used %
+    would read the stale pre-credit peak (e.g. 46) instead of the post-credit
+    value (e.g. 31) — the same floor the statusline / write-clamp / `--from`
+    helper apply (spec §4a, test S15). The floor compare uses `unixepoch()` on
+    both sides (mixed `Z` / `+00:00` offset spellings).
+
     Returns an empty dict if the stats DB has no relevant rows.
     """
     conn = open_db()
     try:
         cur = conn.execute(
-            "SELECT week_start_at, weekly_percent FROM weekly_usage_snapshots "
+            "SELECT week_start_date, week_start_at, week_end_at, "
+            "       captured_at_utc, weekly_percent "
+            "FROM weekly_usage_snapshots "
             "WHERE week_start_at IS NOT NULL "
             "AND week_end_at IS NOT NULL "
             "AND datetime(week_start_at) < datetime(?) "
             "AND datetime(week_end_at) > datetime(?)",
             (until.isoformat(), since.isoformat()),
         )
+        rows = cur.fetchall()
+        # Resolve each week's clamp floor once (keyed on week_start_date) so a
+        # mid-week credit doesn't re-inflate the per-project Used %. None means
+        # "no floor" — every captured row counts.
+        floor_epoch: dict[str, int | None] = {}
+
+        def _floor_for(wsd, ws_iso, we_iso):
+            if wsd not in floor_epoch:
+                f_iso = _reset_aware_floor(conn, wsd, ws_iso, we_iso)
+                floor_epoch[wsd] = (
+                    int(parse_iso_datetime(f_iso, "project.floor").timestamp())
+                    if f_iso else None
+                )
+            return floor_epoch[wsd]
+
         result: dict[dt.datetime, float] = {}
-        for ws_iso, pct in cur.fetchall():
+        for wsd, ws_iso, we_iso, cap_iso, pct in rows:
             if ws_iso is None or pct is None:
                 continue
+            floor = _floor_for(wsd, ws_iso, we_iso)
+            if floor is not None and cap_iso is not None:
+                try:
+                    cap_epoch = int(
+                        parse_iso_datetime(str(cap_iso), "project.cap").timestamp()
+                    )
+                except ValueError:
+                    cap_epoch = None
+                # Drop pre-floor (stale pre-credit) snapshots from the MAX.
+                if cap_epoch is not None and cap_epoch < floor:
+                    continue
             ws = dt.datetime.fromisoformat(
                 str(ws_iso).replace("Z", "+00:00")
             )