cctally 1.107.0 → 1.109.0

package/CHANGELOG.md

@@ -5,6 +5,155 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.109.0] - 2026-09-15
+
+### Added
+- The dashboard picks up a new pricing revision without a restart. It re-reads the deployed pricing file every 60 seconds, adopts a complete newer revision, and keeps serving; no connected client is dropped.
+- The conversation filter popover says `Projects appear once indexing finishes.` in place of `No projects.` while the transcript index is being rebuilt. Model counts stay live on the Claude tab.
+- The dashboard's Projects panel gives every billing cycle of a credited week its own percentage. Both cycles shared one calendar date, and only the later reading survived, so the second cycle could never carry one.
+- The milestone modal names an observation gap where it showed a bare em dash, and states each back-filled run once above the table, as `cctally percent-breakdown` already did. A gap in the current cycle is disclosed too.
+
+### Changed
+- The dashboard's conversation routes open the transcript store read-only. Every browse used to run two write-capable pragmas first, so a read competed with maintenance for the SQLite write lock and lost.
+- A conversation route answers with a typed degraded envelope instead of HTTP 500 while a rebuild, a reclaim pass or a schema upgrade holds the store. Sessions reappear on their own; no request returns a server error.
+- Transcript reclaim runs under a two-second budget and continues on the next pass, so it no longer holds the maintenance and both provider locks until the freelist drains. It is reported as its own timed phase.
+- `cctally project` reports the same per-cycle percentages as `cctally weekly` on the same store. A credited week now contributes one percentage per cycle to `totals.usedPercent`, so a week credited once reports both figures instead of one.
+- A cycle with no observation of its own is reported as missing rather than given the previous cycle's reading, so a week credited `n` times can report up to `n + 1` independently missing observations.
+- An observation captured at the exact instant of a weekly credit belongs to the cycle that starts there, matching where the spend recorded at that instant already goes.
+- The Trend panel, the Trend modal, the Projects modal and the period modal count in billing cycles for both providers, and share artifacts follow.
+- The Projects window pills render bare numbers under a `cycles` label, the Projects grid columns drop the `wk` prefix, and the period modal's `Subscription window` field is now `Reset cycle`.
+- Two cycles of a credited week that fall on one calendar day now render distinct labels, with a time suffix on each. An uncredited week and an ordinarily credited week are unchanged.
+- The dashboard's Projects share artifact states the period its data actually covers. It multiplied a cycle count by seven days, which overstates the span once a credited week is inside it.
+- An All-tab project drill widens to a window that reaches the ranking the row came from, instead of assuming every cycle spans seven days.
+- `cctally project`'s `Used %` cell counts billing cycles: `(3wk)` now reads `(3cy)`, and the trend share artifacts' `Δ` rows follow. A credited week contributes two cycles, so the week abbreviation named the wrong unit.
+- Screen readers announce the Weekly modal's cost chart and the Current Week navigator in billing cycles on the Claude tab. They announced "week" and "period" while every visible label beside them said cycle.
+- `--no-sync` no longer runs the two transcript derivations at startup, so a frozen dashboard starts promptly. While either is owed, conversation reads report that state rather than an empty list, until you run `cctally cache-sync`.
+- A Codex project or quota block reports itself partial when any accounting record inside the past year is unreadable, and states that project metadata is withheld for that item, so a cost is no longer missing with nothing saying so.
+- A momentary database error marks that refresh's Codex project and quota block views partial, and the next refresh recovers on its own once the store is healthy.
+- When the dashboard cannot read the account registry, the Codex source says so: it reports the refresh as partial and states that per-account detail is withheld, instead of presenting the install as if it held one account.
+- The source status chip names the withheld account detail instead of reading `Source degraded`, so a registry the dashboard could not read is distinguishable from a source that could not be built at all.
+- The first journal rebuild after upgrading re-reads every segment once, because the stored segment-summary format changed. Later rebuilds skip unchanged segments as before.
+
+### Fixed
+- `cctally record-credit` plans a credit from the confirmed account's own snapshots, floors and five-hour readings, and its preview names the account it will write to. An install with one account is unchanged.
+- `cctally record-usage`, `cctally report` and `cctally percent-breakdown` read each account's own week boundary, so one account's earliest capture no longer sets another account's week.
+- `cctally explain` decides Codex prompt evidence per conversation. A conversation whose transcript is no longer retained leaves the evaluated population and lowers reported coverage, instead of counting as a confident non-contributor.
+- A journal segment summary survives an ordinary volume remount, after proving the file's bytes are unchanged, so a rebuild no longer re-reads the whole journal once an external or network volume is remounted.
+- The dashboard rebuilds a Codex view whose project metadata was incomplete instead of serving it again for the life of the process, and retries on a bounded schedule rather than once.
+- The dashboard tells a temporary read failure apart from a record it cannot interpret, so only the second advises `cctally cache-sync --source codex --rebuild`.
+- The Projects drill issues one request at the width where two panels are mounted, so resizing the window no longer fetches the same project twice.
+- `cctally five-hour-breakdown` and the current-usage modal report the weekly percentage a reader saw at each five-hour crossing, not the raw reading a held tick recorded. Where that reading is no longer retained the column reads `—`.
+- A five-hour block shows only its own account's crossings. One window owns one block per account, and both the current-usage modal and the historical cycle view listed every account's crossings under each.
+- `cctally five-hour-blocks` and `cctally five-hour-breakdown` withhold a weekly percentage a weekly credit retired, at a block's start and end, closed and reset-crossing blocks included. A block observed only before the credit is unchanged.
+- A held status-line tick keeps its five-hour reading through an in-place weekly credit. The credit's cleanup of stale pre-credit replays removed that tick's row, the only record of the reading it carried.
+- A status-line tick whose weekly percentage is held at its high-water mark no longer discards that tick's five-hour usage, so `cctally five-hour-blocks` and the dashboard's five-hour panel stay current.
+- A status-line tick held at the weekly high-water mark does not advance the weekly percentage or its freshness stamp. `cctally forecast`, `cctally report`, the status line, the TUI and the dashboard keep the last observed reading.
+- The Codex source recovers on the next refresh once the account registry is readable again. A refresh that could not read it republished that result for the life of the process, so the per-account panels stayed missing until a restart.
+- A Codex quota block whose retained metadata is incomplete opens and states that, instead of replacing the whole panel with a message saying the dashboard had updated. Nothing had updated.
+- Above one Codex account, clicking a quota block row in the Blocks panel opens that row's own account while the account selector is on All accounts. One of two rows sharing a window opened the other account's block.
+- Opening a Codex project or quota block in the dashboard is immediate. Each click read a year of Codex accounting first, which on a large store is every row it has, and now reads only that project's or that window's own rows.
+- A Codex quota block opens while one unreadable Codex accounting record sits elsewhere in the store. The view converted a year of records it never used, so a single bad record failed the whole request.
+- A Codex quota block renders every observation of its own window. The detail read a thousand recent rows, so a busy window could lose members, or arrive empty and report the block as missing.
+- Above one Codex account, opening a quota block returns that account's block. Two accounts whose blocks share a root, a limit, a slot, a window length and a reset produced one link, and whichever sorted first was shown.
+- A Codex quota block older than the two hundred and fiftieth most recent now opens instead of reporting itself missing.
+- A Claude transcript keeps its account after its volume is remounted. A remount renumbers the device each transcript records, and the next time one grew, its whole history took the account signed in then. Existing damage is not repaired.
+- The conversation list names the transcript-import state and the command that clears it, instead of reporting a load failure beside a Retry that could never succeed. The server reported that state; the page discarded it.
+- The current-usage modal describes a reconciling Codex quota projection the way the hero does, rather than calling it unavailable directly above the figures it publishes. The Codex-only view carries that qualification too.
+- A Codex hero that is showing its last coherent figure says so in text and to assistive technology. The explanation was in a tooltip, which a touch user cannot reach.
+- Opening a Codex row in Recent Sessions is immediate. The detail rebuilt every Codex session of the past year on each click, and now uses the row the dashboard already published, so it reads no accounting data at all.
+- The dashboard's Codex hero keeps its last known spend, with a quiet updating marker, while the quota projection reconciles. It blanked the figure for that moment, and the account card beneath it went on showing a number.
+- A Codex hero says it is pending, rather than rendering an empty value that reads as no spend, both before its first coherent reading and whenever its weekly cycle stops resolving afterwards.
+- The dashboard publishes a recorded metering-rate change on the next refresh. Nothing the dashboard compared between refreshes changed when one was written, so an idle dashboard kept serving the alert list from before it.
+- The dashboard evicts its least recently used Codex caches at their retained-memory budget instead of discarding all of them. A store permanently above the budget rebuilt every cached view on every refresh. Published figures are unchanged.
+- The visible-population memo is still evicted whole, not in part, because it is one indivisible population. Two other cases take every Codex cache cold: a total eviction cannot reduce, and a refresh whose generation moved mid-build.
+- The dashboard no longer discards its most expensive Codex caches first. Two reported no age and no size to the eviction order, so the visible-population memo and the quota memo always went first, however recently they had been used.
+- `cctally dashboard-perf` reports what the Codex source caches retain. The figure came from a background measurement that never finished on a large store, so it read as zero.
+- Codex spend and transcripts reach the dashboard within one tick of a rollout being appended to. An append made mid-turn left no evidence any freshness check examined, so only the two-minute safety walk ever found it.
+- A Codex rollout cctally has read since this release is re-read from the start when it is replaced in place, even at an unchanged size and modification time. An older read position carries no file identity to compare.
+- Adding or removing a `$CODEX_HOME` entry is noticed immediately. A configured root could be added or removed with nothing on disk changing, and the dashboard would keep reporting itself up to date.
+- The conversation viewer keeps every session title and the browse list's cost, project and date columns while `cctally cache-sync --rebuild` replays. The rebuild cleared those tables first, so the list showed no titles throughout.
+- A transcript sync keeps reading a file that the running session appended to mid-read. Any size or modification-time change read as a replacement, so an ordinary append discarded that pass's records and left the whole rebuild to run again.
+- A transcript rebuild drops session titles whose sessions no longer exist. Every rebuild kept the previous titles in full, so titles for deleted sessions stayed forever and title search returned them.
+- A transcript rebuild keeps each message's recorded account instead of re-attributing it to whichever account is active. The attribution was held in memory, so a rebuild resumed in a fresh process lost it.
+- A transcript file replaced in place is recognised as a new file even when its size and modification time are unchanged, so records that no longer exist cannot lend their identity to whatever replaced them.
+- `cctally cache-sync --rebuild` refuses, before deleting anything, when the volume holding `conversations.db` is nearly full, instead of failing partway through and leaving the store half-rebuilt.
+- `cctally doctor` warns when it cannot read a store's rollup pricing fingerprint, instead of reporting no refused write. A locked store read as one that recorded nothing, and every writer of conversation cost authorized itself over it.
+- `cctally cache-sync --prune-orphans` exits 3 and names the affected files when the conversation rollup re-derive is refused. It reported success, and the dashboard's automatic prune said nothing at all.
+- The conversation browse rail falls back to live aggregation when the rollup's state cannot be read, instead of reporting it authoritative over a failed read. Sessions stay visible; cost sorting and project filtering degrade.
+- `cctally doctor` reports a transcript reclaim backlog that is not draining, and fails above 16 GiB. A rebuild is refused at that point, because it adds churn to a store already failing to return the space it freed.
+- `cctally cache-sync --rebuild` measures the free space it needs against the store instead of a fixed 64 MiB. A rebuild replays the whole corpus before the pages it frees come back, so the fixed figure admitted rebuilds that ran out of room.
+- A transcript rebuild that finds no files on disk no longer deletes every message's recorded account. An unmounted volume produced that walk, and the account is the one thing in the store that cannot be derived again.
+- A `cctally dashboard --no-sync` run advances the transcript schema once at startup. Nothing else does in that mode, so a store one migration behind stayed behind and every conversation route stayed degraded.
+- `cctally five-hour-blocks`, `five-hour-breakdown` and the dashboard's Blocks panel record a five-hour credit only when one reporting source both observes the drop and confirms it. A stale status-line sample below an API reading minted one.
+- `cctally statusline` records a weekly reset within 180 seconds even while another session still reports the pre-reset percentage. Agreement from every session was required, so one session that never agreed held the reset back forever.
+- `cctally record-credit` keeps its journalled cleanup when the operation is retried. The list of rows to remove followed database row order, so a retry could describe the same removal differently and have the second description withheld.
+- The stats-database writer guard `cctally doctor` reports now checks every write, not only the first of its kind on a connection. A repeated write that reused an earlier statement went unchecked, so it was neither refused nor recorded.
+- `cctally five-hour-blocks` totals, their breakdowns and the dashboard's Blocks panel count an entry once when a reset shift makes two windows overlap. The later window also priced the earlier one's overlapping entries.
+- The dashboard's Blocks panel and its block modal report a closed five-hour block's recorded totals and model split. They recomputed from the cache, so a session ingested after the block closed changed numbers that are meant to be final.
+- The Blocks share artifact counts a project's cost in one five-hour block only. It read the recorded rollup with a key that never matched, then swept each block's raw interval, so two overlapping windows both claimed the shared entries.
+- The dashboard's block modal says when a closed five-hour block's headline comes from the record kept at its close while the chart below is drawn from the local cache. The two can differ, and nothing said so.
+- After `cctally cache-sync --rebuild`, `cctally doctor` warns that `conversations.db` has space to reclaim until the passes drain it. The dashboard drains it; without one, run `cctally db vacuum --db conversations`.
+- `cctally cache-sync --rebuild` still runs when the free space on its volume cannot be measured. A failed measurement is now unknown and the check is skipped; it used to read as too little space and defer every rebuild.
+- The conversation viewer's live-tail stream answers immediately while a rebuild holds the transcript store, instead of holding the connection open for the whole rebuild. Two other conversation-route paths answer the same way.
+- A dashboard request, panel rebuild or transcript sync that is under way when a new pricing revision is adopted finishes on the revision it started with, so one response is never priced from two revisions.
+- `cctally cache-report`'s per-call tier threshold follows an adopted pricing revision. It was a fixed figure that a reload could not replace.
+- A transcript schema upgrade is started once when several conversation requests find the store behind head at the same moment, instead of once per request.
+- The dashboard's Codex cache report keeps each row on the day it belongs to when a row moves to another day. Its former day kept a copy, so the report either refused to build or published the row under a date it had left.
+
+### Maintenance
+- The test-evidence scrub no longer redacts a diagnostic line for containing the ordinary word "token". A token credential now needs a real separator, so a line such as `unexpected token ')' at line 4` is published rather than replaced.
+- A failing envelope-oracle verification keeps the envelope that disagreed with the baseline, and the sanitized failure extract names it, so a mismatch can be diagnosed from the retained evidence instead of by reproducing it.
+- The sanitized failure extract is withheld whole, and says which check withheld it, when the scrub's transformer fails a health probe before publication. A per-line refusal could otherwise publish beside a secret the backstop cannot see.
+- The envelope-oracle harness emits its results in the one form the failure-extract reader parses, bringing it under the harness scrub contract so its output survives sanitization.
+
+## [1.108.0] - 2026-09-05
+
+### Added
+- Codex reporting prices `gpt-6-astra` from OpenAI's published standard, cached-input, long-context and Fast-mode rates instead of the legacy `gpt-5` fallback.
+- `cctally alerts test` gains `--axis quota` and `--axis meter-rate-change`, so you can rehearse those two notifications instead of waiting for a real crossing or rate change. `--threshold` does not apply to `meter-rate-change`.
+- `cctally percent-breakdown` and `cctally report --detail` name a run of percent thresholds that one observation recorded, and print `observation_gap` where the marginal cost showed a bare `n/a`. `--json` adds `marginalCostWithheldCause`.
+- On an install with more than one account for a provider, every alert toast names the account it belongs to, as the dashboard's Recent Alerts list already did.
+- `cctally doctor` gains `hooks.codex_liveness_7d`, which FAILs when an enabled Codex hook has not succeeded in seven days. It reads the per-root success markers, so log rotation cannot hide a hook that stopped firing.
+
+### Changed
+- `cctally weekly`, `cctally report` and `cctally project` render a week credited twice as three rows, one per billing cycle. A dictionary keyed on the week alone now keeps only the last cycle; key on the week and its start instant together.
+- `cctally weekly`, `cctally report` and `cctally project` start the first cycle of a week whose boundary moved and was then credited at the moved boundary. The previous week keeps its own spend, which was counted into the credited week.
+- Upgrading from 1.107.0 or earlier rebuilds the disposable stats index once, because a weekly reset now records the observation it came from and a rate change records its evidence. Commands report the rebuild until it finishes.
+- A metering-rate change recorded before this upgrade reports no evidence rather than inventing any.
+- A weekly credit is recorded at the exact second Anthropic issued it rather than the top of that hour, so a reading captured earlier in the same hour stays in the cycle it belongs to.
+- A pre-credit reading captured before a second weekly credit now survives and is shown inside the earlier cycle, because each credit's cleanup is scoped to its own instant instead of reaching back past the previous credit.
+- `cctally doctor` now reads Codex's own hook trust record and FAILs when the cctally handler is disabled or was never trusted in Codex `/hooks`, instead of reporting it as installed.
+- `cctally doctor` warns when the Codex handler changed after Codex last recorded a trust decision about it, and when that record cannot be read at all.
+- `cctally setup` refuses at exit 1 when reconciling the Codex handler would land it on a trust decision Codex recorded about a different handler. The message names the file, the slots and the fix.
+- When Codex's trust record changes mid-run, the `cctally setup` refusal names each Codex hooks file it had already rewritten and the dated backup of its previous contents. `--json` adds `changed_hooks_backups`.
+- `cctally doctor` states how many Codex roots are installed beside how many are enabled, so two installed-but-untrusted handlers no longer read as `0/2 root(s) enabled` alone.
+- `cctally setup` recognizes a Codex handler written by a different install channel and collapses it into one canonical handler, instead of adding a second one beside it.
+- `cctally setup --json` moves to `schema_version: 2`: the `installed_review_required` state is retired, and per-root `changes` becomes a per-event object with separate added, removed and unchanged counts.
+- `cctally setup --dry-run` and the applied run now report the same added, removed and unchanged Codex handler counts for the same input.
+- The dashboard and the TUI stop treating a Codex handler as trusted merely because it is present, and re-check that trust when `config.toml` changes, so a hook disabled while either was running no longer certifies stale conversation cost.
+- A freshly installed Codex handler reports as untrusted, and `cctally doctor` FAILs, until you approve it in Codex `/hooks`. Until then the dashboard and the TUI walk every Codex session on each refresh.
+- Two `cctally setup` messages read as ordinary English again: the orphaned `[hooks.state]` remedy says to remove the entry from the file by hand, and a moved trust slot says the handler would move from one key to the other.
+
+### Fixed
+- A percent milestone crossed on a week that holds two recorded resets is listed again. It was filed against one cycle while `cctally percent-breakdown` listed another, so the crossing appeared under neither.
+- Every view of a credited week picks the cycle the week is currently in, not the reset written last. `cctally diff`, the TUI's per-percent modal and the dashboard's milestone list could each name an earlier cycle.
+- A weekly threshold notification names the billing cycle that crossed. On a week credited more than once it read `Week starting Jun 05` for every cycle, naming all of them at once; an uncredited week reads exactly as before.
+- A second Anthropic usage reset inside one subscription week now registers. Every reset in a week shared one slot, so the first held it and later ones were discarded, leaving the reported percentage at the pre-reset high-water mark.
+- A weekly reset observed while cctally is interrupted is no longer lost, and one zero reading can no longer confirm itself into a credit. The pending-reset state moved into the database and commits or rolls back with the reset it fired.
+- A stale pre-credit reading that a credit removed stays removed after `cctally db rebuild --db stats`. The removal is recorded, so a rebuild no longer restores the reading and holds the reported percentage at the pre-credit high.
+- An idle session no longer holds the reported weekly percentage at a stale value. It re-renders its status line from a cached rate-limit block, and that block is now ignored in full once its five-hour window has closed.
+- A severe metering-rate drop now raises a red alert toast instead of the amber that made it look like a smaller drop, and the toast's rate chip matches the colour Recent Alerts already showed for the same event.
+- A metering-rate change detected while the quota calibration was withheld now records which calibration was withheld and how many baseline days were missing, instead of pointing you at a fitted budget that may never have been produced.
+- A metering-rate change whose notification failed and is retried later now carries that same disclosure, because it is read back from the recorded change rather than re-derived from a later run.
+- A metering-rate toast now names the calibration that was withheld and why, instead of pointing you at a fitted budget that may not exist. An ordinary rate change reads exactly as it did before.
+- Recent Alerts shows the evidence behind a metering-rate change: the withheld calibration, the detector's inputs, the composition provenance, and how many baseline days were withheld.
+- An alert toast on a multi-account install states how to dismiss it again, on its own line below the alert's own text rather than above it, so a screen reader reads the alert before it reads how to close it.
+- Alert toasts are usable from the keyboard: press Enter or Space to dismiss one, or to activate its own button and open the window it names. A focused toast states the alert before how to close it, and dismissing one restores focus.
+- The dashboard's Daily panel reads `loading` while it hydrates, instead of reporting the 30-day window as `withheld` over a loading skeleton.
+- The dashboard's Trend panel states its title in full on a phone. The week and cycle counts moved to the wrapping sub-line the other cards use, so the title is no longer cut off mid-word.
+- The dashboard's Daily panel prints its total and peak-day amounts in full on a narrow window. Below about 400px the two summary columns stack instead of cutting the dollar figures off.
+- An install upgrading from a version that predates the append-only journal no longer records a second copy of a reset it already had, so a credited week keeps its own cycles instead of gaining an extra one.
+
 ## [1.107.0] - 2026-09-04
 
 ### Changed

package/bin/_cctally_account.py

@@ -446,6 +446,10 @@ def _cmd_account_show(args: argparse.Namespace) -> int:
         ).fetchone()
         a = ({col: row[i] for i, col in enumerate(_ACCOUNT_COLUMNS)}
              if row is not None else None)
+        # HELD-INCLUSIVE, decided rather than overlooked (#769 S11,
+        # #824). This is an inventory of the rows the account actually
+        # wrote, not a reading of its weekly level, and a held row is a
+        # real write by a real tick.
         snap_count = _count_scoped(conn, "weekly_usage_snapshots", key)
         milestone_count = _count_scoped(conn, "percent_milestones", key)
         # Resolved while the connection is still open — the map is

package/bin/_cctally_alerts.py

@@ -252,9 +252,16 @@ def _alert_label_prefix(axis: str, account_key: "str | None",
     install's alert text stays byte-identical to today.
 
     Delegates the R8 gate + label precedence to the single-definition helpers
-    ``_cctally_account.real_account_count`` / ``account_label`` (P2-CQ1) so the
-    ">1 real account" trigger and the key->label map have exactly one home; this
-    wrapper only opens the RO connection and stays best-effort/never-raise.
+    ``_cctally_account.provider_is_decorated`` / ``account_label`` (P2-CQ1) so
+    the ">1 real account" trigger and the key->label map have exactly one home;
+    this wrapper only opens the RO connection and stays best-effort/never-raise.
+
+    #702: the gate is the canonical predicate itself, negated at the call site.
+    This site previously inverted the underlying counter by hand
+    (``real_account_count(conn, vendor) <= 1``), which is a second written form
+    of the R8 threshold — the arrangement that lets the two spellings disagree
+    if the threshold ever moves. ``provider_is_decorated`` is ``> 1``, so the
+    suppressed branch is ``not provider_is_decorated(...)``.
 
     #697: the VENDOR comes from the payload's own ``provider`` when it carries
     one, and from ``_AXIS_VENDOR`` otherwise. The metering-rate-change family
@@ -285,10 +292,12 @@ def _alert_label_prefix(axis: str, account_key: "str | None",
         import _cctally_store
         conn = _cctally_store.stats_open_guarded(
             db_path,
-            connect=lambda p: _sq.connect(f"file:{p}?mode=ro", uri=True),
+            # #778: forward the opener's `cached_statements=0`.
+            connect=lambda p, **kw: _sq.connect(
+                f"file:{p}?mode=ro", uri=True, **kw),
         )
         try:
-            if _cctally_account.real_account_count(conn, vendor) <= 1:
+            if not _cctally_account.provider_is_decorated(conn, vendor):
                 return ""
             # #416 §6: population-aware, so two accounts that auto-label to
             # one email do not print the same alert prefix.
@@ -400,8 +409,27 @@ def _dispatch_alert_notification(
         # rate transition has no percentage threshold for `severity_for` to
         # map. Reading it verbatim is what keeps the three tiers meaningful
         # here; falling through would floor every transition at `info`.
+        #
+        # #750 S2: the vocabulary is RESOLVED from the kernel's own tuple
+        # rather than restated as a literal. A restated literal makes this the
+        # second written form of the same rule, which is exactly the
+        # arrangement #747 closed on the envelope: a fourth member added to
+        # `RATE_CHANGE_SEVERITIES`, to the TypeScript tuple and to the CSS
+        # passes every parity test and is still clamped to `info` here, so the
+        # OS notification's urgency and the trailing `alerts.log` column are
+        # wrong while the suite is green.
+        #
+        # Guarded the same way `_cctally_dashboard_envelope` guards its copy,
+        # and an unresolvable kernel degrades to NO clamp. This function's
+        # contract is that it never raises, and clamping against an empty
+        # vocabulary would send every correct severity to `info`.
         severity = str(payload.get("severity") or "info")
-        if severity not in ("info", "warn", "alarm"):
+        try:
+            _severities = frozenset(
+                _load_lib("_lib_meter_rate_change").RATE_CHANGE_SEVERITIES)
+        except Exception:                              # noqa: BLE001
+            _severities = None
+        if _severities is not None and severity not in _severities:
             severity = "info"
     else:
         try:
@@ -484,6 +512,56 @@ def _dispatch_alert_notification(
     return status
 
 
+def _synthetic_instant_days_ago(days: int) -> str:
+    """A timezone-aware ISO instant `days` before now (#699).
+
+    Negative goes forward, which is what a quota reset needs. Both non-registry
+    synthetics require real instants rather than placeholders: the rate-change
+    body renders an effective date, and the quota body renders a reset.
+    """
+    moment = dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=days)
+    return moment.isoformat().replace("+00:00", "Z")
+
+
+def _test_alert_account_key(vendor: str) -> str:
+    """A REAL account key for `vendor`, else the vendor-wide sentinel (#699).
+
+    This is what makes the R8 `[<label>]` prefix observable from
+    `alerts test`: on a decorated install the synthetic carries a key the
+    registry can label, and on a single-account install it falls back to `*`,
+    which `_alert_label_prefix` suppresses — so that install's output stays
+    byte-identical, exactly as R8 requires.
+
+    Best-effort and never-raise, following `_alert_label_prefix`: a missing
+    database, an unreadable registry or an empty one all degrade to the
+    sentinel rather than turning a rehearsal into an error path.
+    """
+    try:
+        import sqlite3 as _sq
+        import _cctally_account
+        import _cctally_store
+        db_path = _cctally_core.DB_PATH
+        if not db_path.exists():
+            return _lib_accounts.VENDOR_WIDE
+        conn = _cctally_store.stats_open_guarded(
+            db_path,
+            # #778: forward the opener's `cached_statements=0`.
+            connect=lambda p, **kw: _sq.connect(
+                f"file:{p}?mode=ro", uri=True, **kw),
+        )
+        try:
+            for row in _cctally_account.load_accounts(conn, vendor):
+                key = str(row.get("account_key") or "")
+                if key and key not in (_lib_accounts.UNATTRIBUTED,
+                                       _lib_accounts.VENDOR_WIDE):
+                    return key
+        finally:
+            conn.close()
+    except Exception:                                  # noqa: BLE001
+        return _lib_accounts.VENDOR_WIDE
+    return _lib_accounts.VENDOR_WIDE
+
+
 def cmd_alerts_test(args: argparse.Namespace) -> int:
     """Send a synthetic test alert through the dispatch pipeline.
 
@@ -510,9 +588,28 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
         axis = "codex_budget"
     elif args.axis == "projected":
         axis = "projected"
+    elif args.axis == "quota":
+        axis = "quota"
+    elif args.axis == "meter-rate-change":
+        axis = "meter_rate_change"
     else:
         axis = "five_hour"
-    threshold = int(args.threshold)
+    # #699: `--threshold` now defaults to None so that "supplied" is
+    # distinguishable from "defaulted". Every axis that takes one still gets 90
+    # when it is omitted, which keeps the existing surface byte-identical.
+    raw_threshold = getattr(args, "threshold", None)
+    if axis == "meter_rate_change" and raw_threshold is not None:
+        # Exit 2 is native-usage per docs/cli-contract.md. The message names
+        # BOTH the axis and the flag: a refusal that does not say what failed
+        # costs the reader more than one that gives no reason at all.
+        print(
+            "cctally: --axis meter-rate-change does not accept --threshold; "
+            "a metering-rate change has no percentage threshold and carries "
+            "an explicit severity instead",
+            file=sys.stderr,
+        )
+        return 2
+    threshold = 90 if raw_threshold is None else int(raw_threshold)
     # --threshold range stays [1, 100] (F5): the cap is axis-uniform with the
     # existing weekly/5h thresholds. Over-budget tiers (>100%) are a v2
     # deferral, not an oversight — see spec §2 (F5).
@@ -603,6 +700,54 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
             denominator=denominator,
             week_start_at=dt.date.today().isoformat(),
         )
+    elif axis == "meter_rate_change":
+        # #699: the family is deliberately NOT in `AXIS_REGISTRY`, so there is
+        # no `_build_alert_payload_*` helper for it. The synthetic descriptor
+        # is built HERE and passed through the real
+        # `_lib_meter_rate_change.alert_payload`, which is what keeps that
+        # kernel clock-, database- and policy-free while still rehearsing the
+        # exact payload production dispatches.
+        import _lib_meter_rate_change as _mrc
+        previous, new = 2_442_620.0, 1_665_096.0
+        effective = _synthetic_instant_days_ago(7)
+        payload = _mrc.alert_payload(_mrc.RateChangeTransition(
+            provider="claude",
+            account_key=_test_alert_account_key("claude"),
+            effective_from=effective,
+            previous_units_per_point=previous,
+            new_units_per_point=new,
+            # Computed by the real kernel rather than hardcoded, so a change
+            # to the severity boundaries is rehearsed here too. These rates
+            # are a 31.8% drop — the maintainer's own observed transition —
+            # which lands on `alarm`.
+            severity=_mrc.transition_severity(previous, new),
+            detected_at=now_utc_iso(),
+            # The #690 disclosure, so the rehearsal exercises the withheld
+            # copy rather than only the ordinary path.
+            withholding_status="unsupported-model-mix",
+            detector_input_causes='["unsupported-composition"]',
+            composition_provenance='["forecast-aggregate"]',
+            baseline_withheld_days=3,
+        ))
+    elif axis == "quota":
+        # #699: also outside `AXIS_REGISTRY`, but this one HAS a payload
+        # builder, so the synthetic goes through it unchanged. `source` is
+        # `codex` because that is the only vendor this family observes, and
+        # `_AXIS_VENDOR` maps the axis to the same vendor for the R8 lookup.
+        payload = _build_alert_payload_quota(
+            source="codex",
+            source_root_key="default",
+            logical_limit_key="weekly",
+            observed_slot=_synthetic_instant_days_ago(2),
+            window_minutes=10080,
+            resets_at_utc=_synthetic_instant_days_ago(-5),
+            threshold=threshold,
+            kind="weekly",
+            crossed_at_utc=now_utc_iso(),
+            qualifying_percent=float(threshold),
+            projected_percent=min(100.0, float(threshold) + 5.0),
+            account_key=_test_alert_account_key("codex"),
+        )
     else:
         payload = _build_alert_payload_five_hour(
             threshold=threshold,