cctally 1.99.1 → 1.101.0

package/bin/_cctally_project.py

@@ -24,6 +24,7 @@ import bisect
 import datetime as dt
 import json
 import os
+import sqlite3
 import sys
 
 from _cctally_core import (
@@ -35,6 +36,9 @@ from _cctally_core import (
 )
 from _lib_fmt import stable_sum
 
+# #620 S1 D11: the one affordance shape every warning state renders.
+import _lib_alert_scope
+
 
 def _cctally():
     """Resolve the current `cctally` module at call-time (spec §3.1)."""
@@ -42,7 +46,8 @@ def _cctally():
 
 
 def _load_week_snapshots(
-    since: dt.datetime, until: dt.datetime
+    since: dt.datetime, until: dt.datetime, *,
+    account_key: "str | None" = None,
 ) -> dict[dt.datetime, float]:
     """Return {week_start_utc -> max(weekly_percent)} for weeks intersecting
     the [since, until] range.
@@ -68,20 +73,43 @@ def _load_week_snapshots(
     helper apply (spec §4a, test S15). The floor compare uses `unixepoch()` on
     both sides (mixed `Z` / `+00:00` offset spellings).
 
+    ``account_key`` (#620 S1): scopes the read to one account's snapshots.
+    ``None`` — the default and every unfiltered invocation — is the merged
+    all-accounts read, byte-identical to before. A real key is required under
+    ``--account``: two accounts hold independent weekly quotas, so summing
+    another account's percentage into an account-filtered total reports a
+    figure that describes neither account. Percentages across accounts are
+    never summed for the same reason the dashboard never sums them.
+
     Returns an empty dict if the stats DB has no relevant rows.
     """
+    acct_pred = "" if account_key is None else " AND account_key = ?"
+    acct_params: tuple = () if account_key is None else (account_key,)
     conn = open_db()
     try:
-        cur = 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 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()),
-        )
+        try:
+            cur = 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 IS NOT NULL "
+                "AND week_end_at IS NOT NULL "
+                "AND datetime(week_start_at) < datetime(?) "
+                "AND datetime(week_end_at) > datetime(?)"
+                f"{acct_pred}",
+                (until.isoformat(), since.isoformat(), *acct_params),
+            )
+        except sqlite3.OperationalError:
+            # A stats.db predating the `account_key` column — an install
+            # whose migrations have not run, or a dev binary that refused
+            # the prod forward-migration (#142). `_projects_week_grid`
+            # carries the same guard for the same predicate.
+            #
+            # Withholding is the degradation, not dropping the predicate:
+            # retrying unscoped would sum another account's weekly
+            # percentage into an account-filtered total, which is the
+            # figure describing neither account that #620 S1 removed.
+            return {}
         rows_in = []
         for wsd, ws_iso, we_iso, cap_iso, pct in cur.fetchall():
             if ws_iso is None or pct is None:
@@ -402,46 +430,115 @@ def cmd_project(args: argparse.Namespace) -> int:
     now = _command_as_of()
     conn = open_db()
 
-    # Resolve [since_dt, until_dt] in UTC.  All-provider project dispatch
-    # resolves its calendar range once, then injects it here so Claude and
-    # Codex describe precisely the same interval.  The normal Claude parser
-    # remains unchanged for every user-facing legacy invocation.
+    # #341 --account: resolve the render filter (provider=claude; fail closed
+    # with exit 3 when the entry cache is unavailable). None = merged.
+    #
+    # #620 S1 D1: resolved BEFORE the subscription-week walk below, not after
+    # it. `_compute_subscription_weeks` takes an account context precisely so
+    # one account's resets cannot re-anchor another's week walk, and passing
+    # `None` while `--account` was in force bucketed one account's dollars
+    # against the merged boundary set — which, when two accounts reset on
+    # different weekdays, is neither account's. An invocation WITHOUT
+    # `--account` still passes `None` and keeps today's merged boundaries.
+    # Argument VALIDATION runs first. Task 4 moved `resolve_account_filter`
+    # ahead of the range resolution because `_compute_subscription_weeks`
+    # needs the account context to build the default window, and that
+    # reordering also moved which error a user sees when both are wrong: a
+    # malformed `--since` with an unavailable entry cache started exiting 3
+    # instead of 2. Exit codes are contract (`docs/cli-contract.md`), and a
+    # native-usage error outranks a staged environment failure because it is
+    # the one the user can act on. Only the parse moves back in front; the
+    # resolved account still precedes interval construction below.
     source_range = getattr(args, "_source_analytics_range", None)
-    if source_range is not None:
-        since_dt, until_dt = source_range
-    elif args.since or args.until:
+    parsed_explicit_range = None
+    if source_range is None and (args.since or args.until):
         parsed = c._parse_cli_date_range(args, now_utc=now)
         if isinstance(parsed, int):
             # Translate the ccusage-parity helper's exit 1 into project's own
             # native usage code 2 — project is cctally-native, not a ccusage
             # drop-in (docs/cli-contract.md; #279 S6 W2).
             return 2
-        since_dt, until_dt = parsed
+        parsed_explicit_range = parsed
+
+    acct_key, acct_exit = c.resolve_account_filter(
+        args, "claude", needs_cache=True)
+    if acct_exit is not None:
+        return acct_exit
+
+    # Resolve [since_dt, until_dt] in UTC.  All-provider project dispatch
+    # resolves its calendar range once, then injects it here so Claude and
+    # Codex describe precisely the same interval.  The normal Claude parser
+    # remains unchanged for every user-facing legacy invocation.
+    if source_range is not None:
+        since_dt, until_dt = source_range
+    elif parsed_explicit_range is not None:
+        since_dt, until_dt = parsed_explicit_range
         since_dt = since_dt.astimezone(dt.timezone.utc)
         until_dt = until_dt.astimezone(dt.timezone.utc)
     else:
-        # Default to the current subscription week; --weeks N extends backwards.
+        # Default to the current subscription week; --weeks N extends
+        # backwards over the REAL intervals.
+        #
+        # #620 S1. `since_dt = cw_start - 7 * (weeks - 1)` was short of the
+        # truth by the accumulated shortfall of every drifted week in the
+        # window — one day per six-day week, several days over `--weeks 12`.
+        # `_compute_subscription_weeks` emits a leading extrapolated slice
+        # covering whatever `since_dt` it is given, so that deficit was not
+        # empty: every entry inside it was read and bucketed into a week the
+        # panel does not have, `_load_week_snapshots` admitted the prior real
+        # week (it selects every week OVERLAPPING the range) and summed its
+        # whole percentage into `totals.usedPercent`, and the extra week with
+        # no snapshot drove the rendered line "Used % unavailable for 1 week".
+        #
+        # The window is resolved the way the dashboard Projects panel
+        # resolves it: one walk over one shared probe range, locate the
+        # interval containing `now`, then take the `weeks` intervals ending
+        # there. `rangeStart` and `weeksInRange` move as a result, which is
+        # the point — a figure computed over the wrong population is what
+        # this correction removes.
+        weeks_back = args.weeks if args.weeks is not None else 1
+        probe_start, _probe_end = c.subscription_window_probe_range(
+            now, weeks_back,
+        )
         # Widen by 1us so the emit loop fires when `now` is exactly at a reset
         # boundary (zero-width [now, now] makes Case A's `current < range_end`
         # false, which would otherwise wrongly fall through to the Monday
         # fallback for non-Monday-reset accounts).
-        current_weeks = c._compute_subscription_weeks(
-            conn, now, now + dt.timedelta(microseconds=1), config=config,
-            account_key=None,  # #341: merged (all-accounts) analytics read
+        probe_weeks = c._compute_subscription_weeks(
+            conn, probe_start, now + dt.timedelta(microseconds=1),
+            config=config,
+            # #341/#620 S1: the resolved `--account` scope, or None for the
+            # merged (all-accounts) analytics read.
+            account_key=acct_key,
         )
-        if current_weeks:
-            cw_start = parse_iso_datetime(
-                current_weeks[0].start_ts, "week.start_ts"
-            ).astimezone(dt.timezone.utc)
-        else:
-            # No snapshots available: fall back to a Monday-anchored week.
-            cw_start = (now - dt.timedelta(days=now.weekday())).replace(
-                hour=0, minute=0, second=0, microsecond=0
-            )
-        if args.weeks is not None:
-            since_dt = cw_start - dt.timedelta(days=7 * (args.weeks - 1))
+        probe_bounds: list[tuple[dt.datetime, dt.datetime]] = []
+        for sw in probe_weeks:
+            probe_bounds.append((
+                parse_iso_datetime(sw.start_ts, "week.start_ts").astimezone(
+                    dt.timezone.utc),
+                parse_iso_datetime(sw.end_ts, "week.end_ts").astimezone(
+                    dt.timezone.utc),
+            ))
+        cw_start = None
+        for s_dt, e_dt in reversed(probe_bounds):
+            if s_dt <= now < e_dt:
+                cw_start = s_dt
+        window = (
+            c.subscription_window_ending_at(probe_bounds, cw_start, weeks_back)
+            if cw_start is not None else []
+        )
+        if window:
+            since_dt = window[0][0]
         else:
-            since_dt = cw_start
+            # No interval covers `now` — the genuine no-anchor path. A
+            # Monday-anchored week stepped back in seven-day multiples is
+            # what that history actually looks like, and it is what the
+            # panel falls back to as well.
+            if cw_start is None:
+                cw_start = (now - dt.timedelta(days=now.weekday())).replace(
+                    hour=0, minute=0, second=0, microsecond=0
+                )
+            since_dt = cw_start - dt.timedelta(days=7 * (weeks_back - 1))
         until_dt = now
 
     # Pre-compute subscription-week bounds for the query window so each entry
@@ -449,7 +546,9 @@ def cmd_project(args: argparse.Namespace) -> int:
     # `_aggregate_weekly`'s bisect pattern (first-match-wins on overlap).
     subweeks = c._compute_subscription_weeks(
         conn, since_dt, until_dt, config=config,
-        account_key=None,  # #341: merged (all-accounts) analytics read
+        # #341/#620 S1: the resolved `--account` scope, or None for the merged
+        # (all-accounts) analytics read.
+        account_key=acct_key,
     )
     parsed_bounds: list[tuple[dt.datetime, dt.datetime]] = []
     for sw in subweeks:
@@ -495,13 +594,6 @@ def cmd_project(args: argparse.Namespace) -> int:
     else:
         scan_start, scan_end = since_dt, until_dt
 
-    # #341 --account: resolve the render filter (provider=claude; fail closed
-    # with exit 3 when the entry cache is unavailable). None = merged.
-    acct_key, acct_exit = c.resolve_account_filter(
-        args, "claude", needs_cache=True)
-    if acct_exit is not None:
-        return acct_exit
-
     resolver_cache: dict[str, ProjectKey] = {}
     buckets: dict[tuple[ProjectKey, dt.datetime], dict] = {}
     total_cost_by_week: dict[dt.datetime, float] = {}
@@ -622,16 +714,32 @@ def cmd_project(args: argparse.Namespace) -> int:
             buckets[bkey] = b
         _accumulate_entry_into_bucket(b, entry, pre_computed_cost=entry_cost)
 
+    # The remediation moved OUT of these two sentences and into the shared
+    # affordance line below (#620 S1 D11), so the terminal states the problem
+    # once and the fix once. The `warnings` list the JSON payload carries is a
+    # separate wire surface and keeps its own wording unchanged.
     if unknown_entry_count > 0:
         eprint(
-            f"Warning: {unknown_entry_count} entries lacked project_path — "
-            f"run `cache-sync` to backfill."
+            f"Warning: {unknown_entry_count} entries lacked project_path."
         )
     if missing_sid_count > 0:
         eprint(
             f"Warning: {missing_sid_count} entries lacked session_files "
-            f"session_id — run `cache-sync` to backfill."
+            f"session_id."
         )
+    # #620 S1 D11: state the remediation in the one shape every warning uses,
+    # scoped to the provider whose cache is short and the range that was read.
+    # The `warnings` list the JSON payload carries is deliberately untouched;
+    # it is a wire surface, and this is the terminal affordance.
+    resolved_source = getattr(args, "source", None) or "claude"
+    if unknown_entry_count > 0 or missing_sid_count > 0:
+        eprint(_lib_alert_scope.next_step_line(
+            f"cctally cache-sync --source {resolved_source}",
+            provider=resolved_source,
+            window_start=since_dt,
+            window_end=until_dt,
+            tz=getattr(args, "_resolved_tz", None),
+        ))
 
     # --- Attribution math (Task 5) -----------------------------------------
     # Load per-week `weekly_percent` (max within window) for every week that
@@ -639,7 +747,7 @@ def cmd_project(args: argparse.Namespace) -> int:
     # can surface `weeksMissingSnapshot` in the output — those weeks can't
     # contribute to attributed %.
     week_snapshots: dict[dt.datetime, float] = _load_week_snapshots(
-        since_dt, until_dt
+        since_dt, until_dt, account_key=acct_key,
     )
 
     # Set of every week the user asked about (from the computed SubWeek

package/bin/_cctally_quota.py

@@ -253,14 +253,26 @@ PROJECTION_READ_SITE_ACTIONS: "dict[str, str]" = {
 #: an unnamed caller reduces `gate_at_caller` to an assertion nothing tests, and
 #: that is how the first version of this map came to claim a gating caller that
 #: neither called the kernel nor called the gate.
+#:
+#: `_cctally_dashboard_sources.py::_codex_quota_reuse_identity` joined the list
+#: with #583 S5. It derives `codex_stats_digest` when its caller cannot supply
+#: one, which is the share path and the per-request cycle-detail route — neither
+#: of which computes a build signature, so neither had already gated. It gates
+#: and, uniquely among the named callers, returns `None` on
+#: `QuotaProjectionIncomplete` rather than propagating: it produces a cache KEY,
+#: and the fail-safe for an identity that cannot be established is a cold read.
+#: The retry signal is not lost, because its callers reach a `gate`-classified
+#: projection read within a few statements.
 PROJECTION_GATE_CALLERS: "dict[str, tuple[str, ...]]" = {
     "_lib_dashboard_sources.py::<module>::quota_projection_state": (
         "_cctally_tui.py::_tui_build_source_bundle",
         "_cctally_tui.py::_tui_compute_dispatch_signature",
+        "_cctally_dashboard_sources.py::_codex_quota_reuse_identity",
     ),
     "_lib_dashboard_sources.py::<module>::quota_window_blocks": (
         "_cctally_tui.py::_tui_build_source_bundle",
         "_cctally_tui.py::_tui_compute_dispatch_signature",
+        "_cctally_dashboard_sources.py::_codex_quota_reuse_identity",
     ),
 }
 
@@ -1908,13 +1920,14 @@ def load_codex_quota_observations(
     because SQL compares seconds while ``physical_order_key`` compares full
     datetimes and then breaks ties on the reset anchor and physical position.
 
-    The residual difference is a malformed row. Rows whose required text is
-    blank, or whose capture or reset instant SQLite cannot read as a time, are
-    excluded in SQL exactly as the loop below excludes them; a row that survives
-    those predicates but still fails a Python parse can, on this path, hide an
-    older valid capture of the same window that the full load would have
-    reported. That trade is confined to a store already carrying corrupt quota
-    rows, and it is the only behavioural difference between the two paths.
+    The residual differences are malformed or non-canonical instants. A row
+    that survives SQLite's predicates but still fails Python parsing can hide
+    an older valid capture of the same window. In the reverse direction,
+    ``datetime.fromisoformat`` accepts basic-format ISO instants such as
+    ``20260814T120000Z`` that SQLite's ``unixepoch`` rejects, so the SQL path
+    drops that row and may let an older capture win. Neither shape is emitted
+    by ``_utc_iso``; both are confined to a store carrying hand-written or
+    corrupt quota rows.
     """
     for name, value in (
         ("captured_at_or_after", captured_at_or_after), ("active_at", active_at),
@@ -2079,23 +2092,29 @@ def load_codex_quota_observations(
             else:
                 sql += " AND unixepoch(captured_at_utc) >= unixepoch(?)"
                 params.append(_utc_iso(captured_at_or_after))
-        if sql_bounded and max_rows is not None:
-            if active_at is not None:
-                sql += (
-                    " ORDER BY (unixepoch(resets_at_utc) > unixepoch(?)) DESC, "
-                    "unixepoch(captured_at_utc) DESC, unixepoch(resets_at_utc) DESC, "
-                    "source_path DESC, line_offset DESC"
-                )
-                params.append(_utc_iso(active_at))
+        # ``latest_per_identity`` replaces the base query wholesale below, so
+        # assembling its ORDER BY here would be dead work.
+        if not latest_per_identity:
+            if sql_bounded and max_rows is not None:
+                if active_at is not None:
+                    sql += (
+                        " ORDER BY (unixepoch(resets_at_utc) > unixepoch(?)) DESC, "
+                        "unixepoch(captured_at_utc) DESC, unixepoch(resets_at_utc) DESC, "
+                        "source_path DESC, line_offset DESC"
+                    )
+                    params.append(_utc_iso(active_at))
+                else:
+                    sql += (
+                        " ORDER BY unixepoch(captured_at_utc) DESC, "
+                        "unixepoch(resets_at_utc) DESC, source_path DESC, line_offset DESC"
+                    )
+                sql += " LIMIT ?"
+                params.append(max_rows)
             else:
                 sql += (
-                    " ORDER BY unixepoch(captured_at_utc) DESC, "
-                    "unixepoch(resets_at_utc) DESC, source_path DESC, line_offset DESC"
+                    " ORDER BY source_root_key, captured_at_utc, resets_at_utc, "
+                    "source_path, line_offset"
                 )
-            sql += " LIMIT ?"
-            params.append(max_rows)
-        else:
-            sql += " ORDER BY source_root_key, captured_at_utc, resets_at_utc, source_path, line_offset"
         # ONE SHARD PER GROUP (public #5), not one disjunction over all of them.
         # Measured on a 211K-row / 608-group store: an OR over the five-member
         # equality gives up and SCANs the table (2 groups 45.7ms, 3 groups

package/bin/_cctally_record.py

@@ -902,8 +902,13 @@ def maybe_record_milestone(
                     # Filter by reset_event_id so a credited week's
                     # alert payload reads the post-credit row, not a
                     # stale pre-credit row at the same (week, threshold).
+                    # `week_start_at` comes from the row rather than the
+                    # local variable for the same reason `cumulative_cost_usd`
+                    # does: it is the value persisted on insert, so the alert
+                    # states the week the milestone actually recorded.
                     row = conn.execute(
-                        "SELECT cumulative_cost_usd FROM percent_milestones "
+                        "SELECT cumulative_cost_usd, week_start_at "
+                        "FROM percent_milestones "
                         "WHERE week_start_date = ? AND percent_threshold = ? "
                         "  AND reset_event_id = ? AND account_key = ?",
                         (week_start_date, pct, reset_event_id, account_key),
@@ -916,6 +921,7 @@ def maybe_record_milestone(
                             threshold=pct,
                             crossed_at_utc=crossed_at,
                             week_start_date=week_start_date,
+                            week_start_at=row["week_start_at"],
                             cumulative_cost_usd=cum,
                             dollars_per_percent=dpp,
                             account_key=account_key,
@@ -4172,6 +4178,8 @@ def cmd_record_usage(
     args: argparse.Namespace, *,
     ingest_mode: str = "authoritative",
     writer: str = "record-usage",
+    nudge_dashboard: bool = True,
+    nudge_sink=None,
 ) -> int:
     """Record usage from the Claude Code status line rate_limits — DB journal
     redesign reroute (Appendix A).
@@ -4187,7 +4195,23 @@ def cmd_record_usage(
     observes its own write synchronously; "opportunistic" (hook-tick OAuth /
     dedup ticks) skips a busy ingest lock and lets the winner consume the line.
     ``writer`` is the obs line ``src``. Returns 0 on a recorded/deduped tick, 2
-    on an implausible weekly resets_at."""
+    on an implausible weekly resets_at.
+
+    ``nudge_dashboard`` (#583 S2 §5.3) enqueues a rebuild on a locally running
+    dashboard when — and only when — the ingest emitted events. Pass False
+    from `_refresh_usage_inproc`, which runs inside the dashboard's own
+    ``sync_lock`` while servicing a ``refresh=1`` and whose caller
+    ``cmd_refresh_usage`` already nudges once itself.
+
+    ``nudge_sink`` is for callers that hold a cross-process lock across this
+    call. When supplied it is invoked INSTEAD of the nudge, and that caller
+    fires the real nudge once its critical section has ended. The nudge is a
+    loopback POST with a multi-second timeout, so a stalled nudge inside such a
+    section stalls every other process contending on the same lock. There are
+    two such locks and both supply a sink: ``_selected_state_lock`` (the OAuth
+    refresh and the authoritative statusline publication) and the statusline
+    persist flock (``_statusline_reduce_and_publish``, reached from the forked
+    persist child and from the ``sync_for_test`` foreground path)."""
 
     # ULP-noise sanitization is applied at the cmd_record_usage ingress
     # boundary so every downstream consumer (HWM files, DB rows,
@@ -4310,7 +4334,24 @@ def cmd_record_usage(
         account=obs_account))
     # authoritative observes its own write synchronously; opportunistic skips a
     # busy ingest lock and lets the current holder consume the appended line.
-    _jr.run_stats_ingest(mode=ingest_mode)
+    result = _jr.run_stats_ingest(mode=ingest_mode)
+    # #583 S2 §5.3. Nudge only on a MATERIAL change. This runs at Claude
+    # Code's status-line cadence, so an unconditional nudge would queue a
+    # rebuild for work that changed nothing displayed. `consumed` is the wrong
+    # signal — unchanged observations advance ingestion without changing
+    # anything the dashboard shows — and `alerts` is the wrong signal, because
+    # it covers only a subset of material events: a new 5-hour window changes
+    # the dashboard without necessarily firing an alert. The nudge happens
+    # after `run_stats_ingest` returns, which is already after post-commit
+    # alert dispatch, so the alerts ordering is untouched.
+    if (nudge_dashboard
+            and getattr(result, "ran", False)
+            and getattr(result, "error", None) is None
+            and int(getattr(result, "events_emitted", 0)) > 0):
+        # A caller holding the selected-state lock supplies a sink and fires
+        # the real nudge after releasing it — a network call has no business
+        # inside that critical section.
+        (nudge_sink or _cctally()._nudge_dashboard_repaint)()
     return 0
 
 

package/bin/_cctally_refresh.py

@@ -716,6 +716,11 @@ def _refresh_usage_inproc_locked(
             *({"fiveHour"} if five_pct is not None else set()),
         },
         lock_held=True,
+        # #583 S2 §5.3: the dashboard calls this INSIDE its own `sync_lock`
+        # while servicing a `refresh=1`, so an inner nudge would enqueue a
+        # second rebuild for work already underway. `cmd_refresh_usage`
+        # already nudges once on its own after this returns.
+        nudge_dashboard=False,
     )
     if authoritative.status != "ok":
         return _RefreshUsageResult(
@@ -761,6 +766,25 @@ def _refresh_usage_inproc_locked(
     return _RefreshUsageResult(status="ok", payload=payload, warnings=warnings)
 
 
+def _resolve_dashboard_api_token() -> "str | None":
+    """Return the bearer token a running dashboard would require, if known.
+
+    #583 S2 §4. `_require_api_auth` admits an unauthenticated `/api/*` request
+    only when `cctally_api_token` is None, and the dashboard mints that token
+    with `secrets.token_urlsafe(32)` at startup for a non-loopback bind. It is
+    printed once ("dashboard: LAN access token: …") and placed in the startup
+    URL's fragment; it is never written to `config.json` and never persisted.
+    So there is NO configured token for a separate `refresh-usage` process to
+    read, and this environment variable is the only mechanism available today:
+    export the printed token and the nudge authenticates. Without it a
+    LAN-bound, token-configured dashboard answers 401 and the helper's
+    swallow-everything contract discards the nudge, which is a pre-existing
+    defect rather than a regression.
+    """
+    token = (os.environ.get("CCTALLY_DASHBOARD_API_TOKEN") or "").strip()
+    return token or None
+
+
 def _nudge_dashboard_repaint(port: int = 8789, timeout_seconds: float = 3.0) -> None:
     """Best-effort: tell a locally-running dashboard to rebuild+broadcast NOW.
 
@@ -776,20 +800,28 @@ def _nudge_dashboard_repaint(port: int = 8789, timeout_seconds: float = 3.0) ->
 
     CSRF: the dashboard's _check_origin_csrf requires Origin/Host authority
     parity. urllib auto-sets Host from the URL; we set Origin to the
-    byte-identical authority so the POST is accepted (not 403). The timeout
-    is 3.0s — comfortably above the server's _DASHBOARD_SYNC_LOCK_TIMEOUT_
-    SECONDS (2.0s) bounded lock-wait — so the client stays connected until
-    the 204 lands and never leaves a broken-pipe log line in the dashboard's
-    terminal. In the common case (lock free) it returns in single-digit ms.
+    byte-identical authority so the POST is accepted (not 403).
+
+    #583 S2 §4. The URL carries `queue=1`, which marks this as a MACHINE
+    NUDGE: the handler enqueues it even when `sync_lock` is free, because this
+    fires at Claude Code's status-line cadence and a synchronous rebuild at
+    that frequency would reopen the #313 peg. The response is therefore a
+    202 that arrives as soon as the request is queued, not a 204 that waits
+    for a rebuild — the 3.0s timeout is now generous rather than tuned to a
+    server-side lock-wait. A bearer header is sent when a token is
+    resolvable; see `_resolve_dashboard_api_token`.
     """
     # Whole body (incl. Request construction) inside the try so the
     # "swallows EVERY error" contract holds structurally, not just because
     # Request() happens to be total for the hardcoded loopback URL.
     try:
-        url = f"http://127.0.0.1:{port}/api/sync?refresh=0"
+        url = f"http://127.0.0.1:{port}/api/sync?refresh=0&queue=1"
+        headers = {"Origin": f"http://127.0.0.1:{port}"}
+        token = _cctally()._resolve_dashboard_api_token()
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
         req = urllib.request.Request(
-            url, data=b"", method="POST",
-            headers={"Origin": f"http://127.0.0.1:{port}"},
+            url, data=b"", method="POST", headers=headers,
         )
         with urllib.request.urlopen(req, timeout=timeout_seconds) as resp:
             resp.read()
@@ -922,16 +954,28 @@ def _hook_tick_oauth_refresh(
     # its suppression conditions.  A concurrent publisher can otherwise make
     # this tick issue an unnecessary OAuth request between the initial gate
     # and the request itself.
+    # #583 S2: the nudge is deferred out of the critical section. This frame
+    # owns the lock across the OAuth fetch AND the authoritative record, so
+    # `_authoritative_record_usage` cannot release it — the deferral has to
+    # reach the frame that acquired it. The nudge is a loopback POST with a
+    # multi-second timeout and this lock is an `fcntl.flock` every cctally
+    # process contends on, so one unresponsive listener would otherwise stall
+    # every other process's selected-state writes at status-line cadence.
+    deferred = []
     try:
         with c._selected_state_lock():
-            return _hook_tick_oauth_refresh_locked(
+            out = _hook_tick_oauth_refresh_locked(
                 c,
                 token=token,
                 timeout_seconds=timeout_seconds,
                 throttle_seconds=throttle_seconds,
+                nudge_sink=lambda: deferred.append(1),
             )
     except OSError:
         return "err(record-usage=exc)", None
+    if deferred:
+        c._nudge_dashboard_repaint()
+    return out
 
 
 def _hook_tick_oauth_refresh_locked(
@@ -940,8 +984,13 @@ def _hook_tick_oauth_refresh_locked(
     token: str,
     timeout_seconds: float,
     throttle_seconds: float,
+    nudge_sink=None,
 ) -> tuple[str, dict | None]:
-    """Automatic OAuth path with the selected-state lock already held."""
+    """Automatic OAuth path with the selected-state lock already held.
+
+    ``nudge_sink`` records that a dashboard nudge is warranted; the caller
+    fires it after releasing the lock (#583 S2).
+    """
     # Backfill gate: an inflight/invalid tombstone bypasses only selected-age
     # suppression so a later authoritative result can repair it.  The normal
     # throttle and 429 deadline continue to bound OAuth traffic.
@@ -997,6 +1046,7 @@ def _hook_tick_oauth_refresh_locked(
         record_args,
         {"sevenDay", *({"fiveHour"} if five_pct is not None else set())},
         lock_held=True,
+        nudge_sink=nudge_sink,
     )
     if authoritative.status != "ok":
         reason = authoritative.reason or ""

package/bin/_cctally_share.py

@@ -949,7 +949,7 @@ def _build_forecast_snapshot(
     projected_low_pct: float,
     projected_high_pct: float,
     days_remaining: float,
-    dollars_per_percent: float,
+    dollars_per_percent: "float | None",
     dollars_per_percent_source: str,
     low_conf: bool,
     notes: tuple[str, ...] = (),
@@ -1038,6 +1038,13 @@ def _build_forecast_snapshot(
             f"{projected_low_pct:.1f}% — {projected_high_pct:.1f}%"
         )
     dpp_source_label = dollars_per_percent_source.replace("_", " ")
+    # #620 S1 D5: a withheld rate renders as the same `n/a` the report trend
+    # table already uses for an absent $/1%. Forcing it through MoneyCell
+    # would print $0.00, which is the fabrication this contract removes.
+    dpp_cell = (
+        _lib_share.TextCell("n/a") if dollars_per_percent is None
+        else _lib_share.MoneyCell(float(dollars_per_percent))
+    )
     snap_rows = (
         _lib_share.Row(cells={
             "metric": _lib_share.TextCell("Current %"),
@@ -1053,7 +1060,7 @@ def _build_forecast_snapshot(
         }),
         _lib_share.Row(cells={
             "metric": _lib_share.TextCell(f"$ / 1% ({dpp_source_label})"),
-            "value": _lib_share.MoneyCell(float(dollars_per_percent)),
+            "value": dpp_cell,
         }),
     )
     # Caller-provided `notes` (e.g., empty-data path's clearer message)