codex-usage-tracking 0.18.0__tar.gz → 0.19.0__tar.gz

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.19.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Unofficial local Codex usage dashboard and MCP diagnostics from local session logs.",
   "author": {
     "name": "Douglas Monsky"

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.19.0}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.19.0 - 2026-07-15
+
+- Redesign Limits Intelligence around weekly credits-per-percentage capacity
+  history, a compact current-status row, automatic revision analysis, and zero,
+  one, or multiple family-wise-controlled capacity changes. Rejected split
+  statistics stay hidden, five-hour usage remains observed context, and the v2
+  API/MCP contracts expose capacity points, regimes, provenance, and copied-row
+  diagnostics by default.
+
 ## 0.18.0 - 2026-07-15
 
 - Exclude exact historical calls copied by cloned Codex tasks from default dashboard, CLI, MCP, report, allowance, compression, recommendation, and export totals while retaining every physical source row for local provenance.

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.18.0
+Version: 0.19.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT

codex_usage_tracking-0.19.0/docs/allowance-intelligence.md

@@ -0,0 +1,199 @@
+# Allowance Intelligence
+
+Allowance Intelligence is a local, aggregate-only workflow for understanding the
+weekly and 5-hour percentages observed in Codex logs. It is not an OpenAI ledger,
+does not know the account's hidden allowance denominator, and cannot see usage
+from other agentic surfaces.
+
+The v2 workflow is deliberately conservative: current observations are facts;
+reconstructed values, personal calibration, forecasts, and change claims remain
+separate estimates with visible quality gates.
+
+## Truth Layers
+
+The dashboard and API keep five layers distinct:
+
+1. **Observed allowance** is the percentage and reset metadata written in local
+   `token_count.rate_limits` events or copied into the optional local allowance
+   configuration.
+2. **Canonical usage** is token and locally estimated credit activity after
+   high-confidence copied-clone rows are excluded. This is the default input to
+   reports, the dashboard, and MCP.
+3. **Reconstructed usage** estimates movement between sparse observations using
+   only calibration data available before each interval ended.
+4. **Validated forecast** is shown numerically only after time-ordered holdout
+   testing beats the relevant simple baselines and interval coverage is adequate.
+5. **Physical provenance** preserves source rows and record identifiers for local
+   debugging. It is opt-in and never changes billable totals.
+
+Copied clone rows excluded from canonical totals are always disclosed through
+`quality.copied_rows_excluded` or `copied_rows_excluded`. Similar token counts by
+themselves never cause exclusion.
+
+## Reset And Cohort Semantics
+
+Allowance observations are grouped by window kind, limit identity, plan metadata,
+and normalized reset time. Reset timestamps within 60 seconds are treated as the
+same reset boundary. A reset starts a new cycle and produces a chart break; the
+model never interpolates or fits a continuous line across it.
+
+The normal Codex cohort is selected independently for weekly and 5-hour windows.
+Conflicting simultaneous observations, ambiguous cohort changes, reversals, gaps,
+and reset uncertainty remain visible as conflicts or censored intervals. They are
+not silently converted into positive usage movement.
+
+Weekly data is the primary long-range signal. The 5-hour value is useful current
+context, but its rolling-window behavior makes it unsuitable as the primary
+capacity or regime-change claim.
+
+## Freshness
+
+- Weekly and 5-hour observations are `fresh` through five minutes.
+- Weekly observations are `aging` after five minutes through six hours.
+- Five-hour observations are `aging` after five minutes through 15 minutes.
+- Older observations are `stale`.
+- Passing the reported reset time makes an older observation stale immediately,
+  even when its age would otherwise be acceptable.
+
+The status endpoint is constant size. Poll it every 30 seconds while data is fresh
+or aging and every 60 seconds while it is stale, partial, empty, or unchanged.
+Hidden browser tabs stop polling. Transient failures back off exponentially to a
+maximum of five minutes.
+
+## Personal Calibration And Forecasts
+
+`credits_per_percent` is a personal, empirical calibration derived from local
+history. A value such as `105.11` means the user's eligible completed reset windows
+imply approximately 105.11 locally estimated credits per one observed percentage
+point. It is not an official conversion, a hardcoded product rule, or the hidden
+allowance denominator.
+
+Calibration uses completed quality-approved weekly reset identities as the unit of
+evidence. Interleaved observations carrying the same canonical reset timestamp are
+coalesced into one reset window, so concurrent sessions cannot fragment one window
+into many low-movement pseudo-cycles. Weights include recency, interval quality,
+and price coverage, with each reset window's influence capped. At least two
+completed approved reset windows are required before the
+capacity can move beyond a descriptive result.
+
+Each completed reset window also retains the explicitly logged subscription
+`plan_type`. Capacity points and trailing statistics are separated by plan, so a
+Pro Lite window cannot pull the Pro line up or down. Missing plan metadata is
+reported as `unknown`, and a reset window containing multiple explicit plans is
+reported as `mixed`; neither is guessed from its capacity value.
+
+Each reconstructed interval sees only cycles completed before that interval ended.
+Forecast validation is walk-forward and reports sample size, MAE, RMSE, empirical
+50/80/95% interval coverage, and simple baselines. A numerical forecast is
+`validated` only when the time-ordered holdout beats every relevant baseline and
+all advertised interval coverages meet the minimum gate. A failed forecast is
+reported with the specific failed validation gate; it does not make descriptive
+capacity unavailable. The capacity-first Limits page does not foreground the
+percentage forecast or conditional pace.
+
+Missing price coverage is explicit. Change detection requires at least 95% priced
+credit coverage for each eligible reset window. Forecast and calibration payloads
+report their own coverage gaps and never substitute token-count similarity for
+pricing. The Limits chart keeps an open methodology panel beside the evidence: it
+states the ratio formula, explains every mark and filter, shows the observed plan
+color key, and reports the current eligible, excluded, tested, and supported
+counts rather than asking users to infer the method from the visualization.
+
+## Change Analysis
+
+Allowance change analysis is a persisted, revision-keyed background job. It tests
+weekly cycle capacities with a hierarchical maximum-statistic cycle-block
+permutation detector. The result is one of:
+
+- `insufficient_evidence`
+- `no_supported_change`
+- `supported_changes`
+
+A supported parent boundary may split the history into child segments. Each child
+receives half its parent's alpha budget, so the discovered tree controls
+family-wise false positives rather than treating recursive searches as independent
+tests. Histories are first split at every explicitly observed subscription-plan
+transition, and candidate boundaries are tested only within those continuous plan
+segments. The family-wise alpha budget is divided across analyzable plan segments,
+so a Pro Lite-to-Pro transition is visible provenance but can never itself become a
+capacity-change claim. A boundary must also have an absolute Cliff's delta of at least `0.474`.
+Exact permutations are used where bounded; otherwise the detector uses `1,999`
+deterministic Monte Carlo permutations and requires the upper 95% Monte Carlo
+uncertainty bound to clear the allocated alpha—not merely the point estimate.
+
+A raw best split is never presented as significant. Conflict-heavy cycles,
+insufficient samples, low price coverage, weak effects, or selection-corrected
+uncertainty block strong claims. Results expose zero, one, or multiple supported
+`boundaries` and the resulting `regimes`. Deprecated singular fields are populated
+only when exactly one boundary is supported. Rejected candidate p-values and
+before/after medians are omitted from default dashboard and MCP results.
+
+The dashboard starts analysis automatically when a new semantic revision lacks a
+result. MCP callers start or reuse the same job, poll every 500 milliseconds only
+while it is pending, queued, or running, then reload the persisted result.
+Identical source/model/rate-card keys reuse the same snapshot or in-flight job.
+
+The release gate simulates 1,000 deterministic no-change histories across
+Gaussian, skewed, outlier-contaminated, and heteroskedastic families. The detector
+ships only when the upper 95% Wilson bound for its family-wise false-positive rate
+is at most `0.05`.
+
+## Dashboard Workflow
+
+Open `Limits` from the live localhost dashboard to see:
+
+- one compact row for weekly observed use, 5-hour observed context, weekly reset,
+  and personal weekly capacity;
+- weekly `credits / 1%` history with completed-cycle points, an eight-cycle rolling
+  median and interquartile band, robust outlier display, and every supported change;
+- 8-week, 6-month, all available aggregate-cycle, or bounded custom ranges;
+- cycle, week, or month granularity;
+- an automatic newest-first capacity-change timeline that suppresses rejected
+  candidate statistics; and
+- latest-first evidence in 50-row pages.
+
+Physical source links are hidden by default. Enable **Show physical source links**
+only for local provenance/debugging. Static dashboards show an aggregate fallback
+because they cannot poll the v2 localhost services or analysis jobs.
+
+## HTTP And MCP Contracts
+
+The default v2 surfaces are:
+
+| Purpose | HTTP | MCP |
+| --- | --- | --- |
+| Poll current state | `GET /api/allowance/status` | `usage_allowance_status(...)` |
+| Query a finite timeline | `GET /api/allowance/series` | `usage_allowance_series(...)` |
+| Page latest-first evidence | `GET /api/allowance/evidence` | `usage_allowance_evidence(...)` |
+| Read/start analysis | `GET`/`POST /api/allowance/analysis` | `usage_allowance_analysis(...)` |
+| Poll analysis job | `GET /api/allowance/analysis/jobs/{job_id}` | `usage_allowance_analysis_status(job_id)` |
+
+Series presets are `24h`, `7d`, `8w`, `6m`, and `all`; custom ranges are limited
+to 366 days. The `all` capacity view scans indexed aggregate cycle rows, not raw
+transcripts. Evidence limits are 1–500 and the dashboard defaults to 50;
+interactive evidence never accepts an unlimited-history setting.
+
+Normal and strict evidence return aggregate provenance. `privacy_mode="local"`
+opts into bounded physical record identifiers. Full strict evidence export remains
+the explicit offline `usage_allowance_export(...)` compatibility workflow.
+
+See [CLI, MCP, and Dashboard JSON Schemas](cli-json-schemas.md) for synthetic v2
+payloads and [MCP And Codex Skills](mcp.md) for polling examples.
+
+## V1 Compatibility
+
+`usage_allowance_history`, `usage_allowance_diagnostics`, and
+`usage_allowance_export` remain available for compatibility and explicit offline
+diagnostics. New dashboard, plugin, and MCP workflows should start with the v2
+status/series/evidence/analysis tools. Interactive v2 paths never use `limit=0`.
+
+## Privacy
+
+Normal v2 payloads are aggregate-first and never include prompts, assistant text,
+tool output, command output, or indexed transcript fragments. Strict mode also
+removes stable local identifiers. Local physical provenance is a deliberate,
+bounded opt-in for the owner of the local database.
+
+This project is unofficial, independent, and local-first. Its estimates are tools
+for personal investigation, not statements about OpenAI's internal billing or
+allowance systems.

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.19.0}/docs/architecture.md

@@ -2,9 +2,10 @@
 
 Codex Usage Tracker is a local sidecar app. It reads Codex session JSONL logs, stores tracker-owned indexes in SQLite, and exposes usage data through CLI commands, MCP tools, CSV export, generated dashboards, and the localhost React dashboard.
 
-The current storage model has two layers:
+The current storage model has three layers:
 
 - Aggregate usage index: token counters, model/effort metadata, call origins, diagnostic labels, thread summaries, pricing/credit estimates, allowance snapshots, and safe report payloads.
+- Canonical/materialized intelligence: physical usage provenance plus logical usage fingerprints and canonical pointers, reset-aware allowance observations/cycles/intervals, source revisions, and persisted analysis snapshots/jobs. Default totals read canonical rows; physical rows remain available for bounded local diagnostics.
 - Local content index: normalized conversation turns, bounded content fragments, tool calls, command runs, file events, persisted investigation run summaries, and source provenance for explicit local MCP/API investigation.
 
 The aggregate index preserves every parsed row in `usage_events` for source provenance. A versioned strict fingerprint links exact copies of the same logged model call, and the `canonical_usage_events` view selects one physical representative for default totals. Only high-confidence fingerprint matches are excluded; ambiguous or merely similar calls remain canonical. If the original source disappears, the surviving physical copy is promoted without changing the logical call identity.
@@ -21,6 +22,15 @@ Shareable outputs remain aggregate-first and must omit indexed/raw content unles
 - `schema.py` owns persisted SQLite columns and migrations. Add columns or tables there before changing refresh, export, or MCP behavior.
 - `store.py` and `store/api.py` own SQLite setup, refresh, rebuild, query access, previous/next call links, materialized thread summaries, source-file refresh cursors, SQL-backed live dashboard API slices, and cleanup ordering.
 - `source_records.py` owns source-file provenance, parser coverage, incremental cursors, and replacement on source-file changes.
+- `dedupe.py` and store migrations own conservative logical identity. Indexed
+  fingerprint lookup is O(1) per parsed event; only high-confidence identical
+  events are linked to a canonical record. No raw-content or fuzzy token-count
+  scan participates in default exclusion.
+- `allowance_intelligence/` owns cohort selection, reset-aware cycle and interval
+  materialization, prior-only calibration/forecasting, selection-corrected change
+  detection, and the constant-size status/finite series/latest-first evidence
+  services. `server/analysis_jobs.py` owns bounded asynchronous execution and
+  revision-keyed persisted results.
 - `reports.py` is the application-service layer for summaries, expensive-call reports, recommendations, pricing coverage, source coverage, allowance reports, and filtered query payloads. CLI and MCP wrappers should call this layer instead of duplicating report assembly.
 - `api_payloads.py` owns stable JSON payload helpers shared by CLI and MCP. `json_contracts.py` owns lightweight contract checks for schema-versioned CLI/MCP payloads and localhost live API payloads.
 - `costing.py`, `pricing_config.py`, `pricing_openai.py`, `pricing_estimates.py`, and `allowance.py` own cost, credit, rate-card, and allowance annotation. Keep estimate confidence and source metadata attached to rows.
@@ -47,7 +57,11 @@ Shareable outputs remain aggregate-first and must omit indexed/raw content unles
 11. Register each dashboard route in `server.route_inventory`. Interactive routes must be bounded and index-backed; unavoidable all-history detector work uses the shared asynchronous job lifecycle.
 12. Cache only immutable aggregate responses. Server keys include source generation and semantic/configuration inputs; browser persistence rejects raw or indexed content.
 13. Add or change a route budget only from repeatable synthetic evidence. Database indexes require an additive migration, query-plan or timing evidence, and focused migration coverage.
-14. Preserve physical usage rows for provenance, but route default usage totals and detector folds through `canonical_usage_events`. New physical-row investigation surfaces must be explicitly labeled and tested against an original/copy/new-call fixture.
+14. Preserve physical usage rows for provenance, but route default dashboard,
+    API, report, recommendation, diagnostic, thread-summary, detector, and MCP
+    totals through `canonical_usage_events`. New physical-row investigation
+    surfaces must be bounded, explicitly labeled, and tested against an
+    original/copy/new-call fixture.
 
 Normal aggregate responses use a 64-entry, 256-KiB-per-entry process cache.
 Allowance history and diagnostics use a separate four-entry, 8-MiB-per-entry

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.19.0}/docs/cli-json-schemas.md

@@ -50,6 +50,10 @@ Tracked schema ids:
 | `codex-usage-tracker-action-brief-v1` | CLI `action-brief --json`, MCP `usage_action_brief(...)`; compact aggregate remediation brief |
 | `codex-usage-tracker-async-job-status-v1` | MCP `usage_dogfood_start(...)`, `usage_dogfood_status(...)`; async in-process job progress/status payload |
 | `codex-usage-tracker-analysis-job-v1` | Dashboard diagnostic refresh start/status lifecycle; shared aggregate progress envelope |
+| `codex-usage-tracker-allowance-status-v2` | Dashboard `/api/allowance/status`, MCP `usage_allowance_status(...)`; constant-size canonical polling snapshot |
+| `codex-usage-tracker-allowance-series-v2` | Dashboard `/api/allowance/series`, MCP `usage_allowance_series(...)`; finite reset-aware timeline |
+| `codex-usage-tracker-allowance-evidence-v2` | Dashboard `/api/allowance/evidence`, MCP `usage_allowance_evidence(...)`; latest-first cursor pagination |
+| `codex-usage-tracker-allowance-analysis-v2` | Dashboard `/api/allowance/analysis`, MCP `usage_allowance_analysis(...)`; persisted revision-keyed result |
 | `codex-usage-tracker-allowance-history-v1` | CLI `allowance-history --json`, MCP `usage_allowance_history(...)`, dashboard server `/api/allowance/history` |
 | `codex-usage-tracker-allowance-diagnostics-v1` | CLI `allowance-diagnostics --json`, MCP `usage_allowance_diagnostics(...)`, dashboard server `/api/allowance/diagnostics` |
 | `codex-usage-tracker-allowance-evidence-export-v1` | CLI `allowance-export --json`, MCP `usage_allowance_export(...)`, dashboard server `/api/allowance/export` |
@@ -275,80 +279,226 @@ Actions translate aggregate diagnostics into concrete workflow changes. Each act
 
 ## Allowance Intelligence
 
-Commands:
+V2 is the default dashboard and MCP contract family. The examples below are
+synthetic aggregate data and apply to both the localhost route and corresponding
+MCP tool. Copied clone rows are excluded from canonical totals by default and are
+disclosed in every applicable payload.
 
-```bash
-codex-usage-tracker allowance-history --window-kind weekly --json
-codex-usage-tracker allowance-diagnostics --window-kind weekly --json
-codex-usage-tracker allowance-export --output /tmp/codex-allowance-evidence.json
+### Current status
+
+`GET /api/allowance/status` and `usage_allowance_status(...)` return
+`codex-usage-tracker-allowance-status-v2`. Pass `since_revision` to get a compact
+`changed=false` response when the source has not changed.
+
+```json
+{
+  "schema": "codex-usage-tracker-allowance-status-v2",
+  "revision": "r-synthetic-42",
+  "changed": true,
+  "model_version": "reset-aware-v4",
+  "generated_at": "2026-07-15T12:00:00+00:00",
+  "data_as_of": "2026-07-15T11:58:00+00:00",
+  "data_state": "fresh",
+  "weekly": {
+    "cohort_id": "codex-pro",
+    "plan_type": "pro",
+    "used_percent": 42.0,
+    "remaining_percent": 58.0,
+    "reset_at": 1784145600,
+    "reset_countdown_seconds": 172800,
+    "observed_at": "2026-07-15T11:58:00+00:00",
+    "age_seconds": 120,
+    "freshness": "fresh",
+    "status": "open",
+    "pricing_coverage": 0.98,
+    "quality": "high",
+    "canonical_source_revision": "r-synthetic-42"
+  },
+  "five_hour": null,
+  "estimation": {
+    "model_version": "reset-aware-v2",
+    "window_kind": "weekly",
+    "capacity": {
+      "status": "descriptive",
+      "credits_per_percent": 105.11,
+      "completed_cycle_count": 63,
+      "eligible_interval_count": 622,
+      "price_coverage": 1.0
+    },
+    "weekly_estimate": {"used_percent": 42.4, "clipped": false, "reason": null},
+    "forecast": {"used_percent": null, "quantiles": null, "reason": "holdout_not_better_than_baseline"},
+    "validation": {"status": "descriptive", "sample_size": 207, "median_absolute_error": 3.7, "mean_absolute_error": 4.22, "rmse": 5.31, "holdout": {"sample_size": 207, "passed_baseline_gate": false}},
+    "pace_scenarios": {"status": "conditional", "reason": null, "if_current_pace_continues": 47.0, "sample_count": 6, "unit": "percent_per_hour"}
+  },
+  "quality": {"canonical": true, "copied_rows_excluded": 17},
+  "next": {"action": "poll_status", "poll_after_seconds": 30}
+}
 ```
 
-MCP:
+The synthetic `105.11` is explicitly a personal local calibration: estimated
+credits per one observed percentage point over eligible history. It is not an
+official conversion.
+
+### Finite series
 
-- `usage_allowance_history(...)`
-- `usage_allowance_diagnostics(...)`
-- `usage_allowance_export(...)`
+`GET /api/allowance/series?range_preset=8w&granularity=cycle` and
+`usage_allowance_series(range_preset="8w", granularity="cycle")` return
+`codex-usage-tracker-allowance-series-v2`.
 
-Server API:
+```json
+{
+  "schema": "codex-usage-tracker-allowance-series-v2",
+  "model_version": "reset-aware-v4",
+  "generated_at": "2026-07-15T12:00:00+00:00",
+  "revision": "r-synthetic-42",
+  "requested_range": {"preset": "8w", "start_at": "2026-05-20T12:00:00+00:00", "end_at": "2026-07-15T12:00:00+00:00"},
+  "available_range": {"start_at": "2026-05-28T09:00:00+00:00", "end_at": "2026-07-15T11:58:00+00:00"},
+  "granularity": "cycle",
+  "truncated": false,
+  "downsampled": true,
+  "quality": {"canonical": true, "copied_rows_excluded": 17, "observed_only": true},
+  "points": [
+    {"kind": "observed", "cycle_id": "cycle-7", "observed_at": "2026-07-15T11:58:00+00:00", "reset_at": 1784145600, "used_percent": 42.0},
+    {"kind": "reset", "cycle_id": "cycle-6", "observed_at": "2026-07-13T12:00:00+00:00", "reset_at": 1783972800}
+  ],
+  "cycles": [
+    {"cycle_id": "cycle-7", "reset_at": 1784145600, "first_observed_at": "2026-07-13T12:01:00+00:00", "last_observed_at": "2026-07-15T11:58:00+00:00", "latest_used_percent": 42.0, "status": "open", "quality_grade": "high", "plan_type": "pro"}
+  ],
+  "capacity_history": {
+    "status": "ready",
+    "unit": "credits_per_percent",
+    "eligible_cycle_count": 63,
+    "plan_types": ["pro", "prolite"],
+    "trailing_window_cycles": 8,
+    "robust_domain": {"mode": "tukey_1_5_iqr", "min": 51.2, "max": 181.7},
+    "clipped_point_count": 2,
+    "points": [
+      {"cycle_id": "cycle-6", "completed_at": "2026-07-13T12:00:00+00:00", "credits_per_percent": 105.11, "rolling_median": 101.8, "rolling_q1": 88.4, "rolling_q3": 116.9, "quality_grade": "high", "price_coverage": 1.0, "plan_type": "pro", "regime_id": "regime-2"}
+    ],
+    "boundaries": [],
+    "regimes": []
+  }
+}
+```
+
+Supported presets are `24h`, `7d`, `8w`, `6m`, and `all`; custom ranges are
+bounded to 366 days. The `all` capacity view reads indexed aggregate cycle rows,
+not raw transcript content. Five-hour series return
+`capacity_history.status="unsupported_window_model"` because rolling expiry needs
+a different model. `capacity_history.plan_types` and each point's `plan_type` come
+from observed rate-limit metadata. Unknown or mixed plan windows remain explicit;
+clients must not infer a subscription plan from capacity values.
 
-- `/api/allowance/history`
-- `/api/allowance/diagnostics`
-- `/api/allowance/export`
+### Latest-first evidence
 
-Schemas:
+`GET /api/allowance/evidence?limit=50` and
+`usage_allowance_evidence(limit=50)` return
+`codex-usage-tracker-allowance-evidence-v2`.
 
-- `codex-usage-tracker-allowance-history-v1`
-- `codex-usage-tracker-allowance-diagnostics-v1`
-- `codex-usage-tracker-allowance-evidence-export-v1`
+```json
+{
+  "schema": "codex-usage-tracker-allowance-evidence-v2",
+  "model_version": "reset-aware-v4",
+  "generated_at": "2026-07-15T12:00:00+00:00",
+  "revision": "r-synthetic-42",
+  "privacy_mode": "normal",
+  "rows": [
+    {"window_kind": "weekly", "end_observed_at": "2026-07-15T11:58:00+00:00", "end_used_percent": 42.0, "point_kind": "positive", "censor_reason": null}
+  ],
+  "next_cursor": "2026-07-15T11:58:00+00:00|interval-synthetic-41",
+  "copied_rows_excluded": 17,
+  "provenance": "local_aggregate",
+  "offline_export_action": "build_allowance_export_report"
+}
+```
 
-Allowance intelligence normalizes observed 5-hour and weekly usage snapshots from aggregate token-count rows. Diagnostics compare visible usage movement with locally estimated Codex credits and grade the evidence. Weekly windows are the primary signal; 5-hour windows are treated as noisy rolling counters. Weekly change candidates include `nonparametric-v1` statistical evidence and a stricter `summary.research_readiness.ready_for_public_claim` flag. Strict export omits prompts, assistant text, tool output, file paths, thread names, session IDs, and record IDs.
+Rows are newest first. Pass `next_cursor` as `cursor`; limits are 1–500. Normal
+and strict modes omit physical record identifiers. `privacy_mode="local"` is an
+explicit provenance/debug opt-in that may add bounded `start_record_id` and
+`end_record_id` fields.
 
-The localhost history and diagnostics routes may append the same `query_cache`
-transport metadata documented for diagnostic fact routes. They use a dedicated
-four-entry, 8-MiB aggregate cache because full allowance payloads are larger than
-normal dashboard summaries. Cache identity includes source revision, canonical
-query, privacy mode, allowance configuration, and rate-card configuration.
+### Persisted change analysis
 
-HTTP report endpoints accept `limit=all`, `limit=0`, `limit=none`, and `limit=null` as all rows up to the endpoint safety cap.
+`GET /api/allowance/analysis` and `usage_allowance_analysis(...)` return the
+persisted `codex-usage-tracker-allowance-analysis-v2` result for the exact source,
+model, rate-card, archive, cohort, and parameter key. When missing, POST/start
+returns the shared job envelope below.
 
 ```json
 {
-  "schema": "codex-usage-tracker-allowance-diagnostics-v1",
-  "generated_at": "2026-06-01T00:00:00+00:00",
-  "privacy_mode": "strict",
-  "include_archived": false,
+  "schema": "codex-usage-tracker-allowance-analysis-v2",
+  "status": "supported_changes",
+  "snapshot_id": "analysis-synthetic-42",
+  "source_revision": "r-synthetic-42",
+  "model_version": "reset-aware-v2",
+  "rate_card_revision": "rates-synthetic-3",
+  "generated_at": "2026-07-15T12:00:02+00:00",
   "window_kind": "weekly",
-  "summary": {
-    "observation_count": 4,
-    "primary_evidence_grade": "possible_regime_change",
-    "research_readiness": {
-      "detector_version": "nonparametric-v1",
-      "ready_for_public_claim": false,
-      "weekly_positive_span_count": 3,
-      "minimum_split_spans_for_public_claim": 6
-    }
-  },
-  "windows": [],
-  "spans": [],
-  "change_candidates": [
-    {
-      "evidence_grade": "possible_regime_change",
-      "capacity_ratio": 0.72,
-      "outside_usage_possible": true,
-      "statistical_evidence": {
-        "detector_version": "nonparametric-v1",
-        "method": "exact_permutation_mean_shift",
-        "effect_size_cliffs_delta": -0.67,
-        "p_value_one_sided": 0.18,
-        "signal": "directional_effect_limited",
-        "public_claim_ready": false
-      }
-    }
+  "parameters": {"min_cycles_per_regime": 4, "permutation_count": 1999, "familywise_alpha": 0.05},
+  "quality": {"canonical": true, "copied_rows_excluded": 17},
+  "detector_version": "hierarchical-maxstat-cycle-v3",
+  "selection_correction": "hierarchical_max_statistic_cycle_block_permutation",
+  "eligible_cycle_count": 63,
+  "excluded_cycle_count": 2,
+  "candidate_count": 56,
+  "reason": null,
+  "familywise_alpha": 0.05,
+  "boundaries": [
+    {"boundary_id": "boundary-older", "effective_at": "2026-03-01T00:00:00+00:00", "alpha": 0.025, "adjusted_p_value": 0.004, "effect_size": {"median_before_credits_per_percent": 142.0, "median_after_credits_per_percent": 101.0, "median_shift_credits_per_percent": -41.0, "cliffs_delta": -0.76}},
+    {"boundary_id": "boundary-newer", "effective_at": "2026-06-15T00:00:00+00:00", "alpha": 0.025, "adjusted_p_value": 0.006, "effect_size": {"median_before_credits_per_percent": 101.0, "median_after_credits_per_percent": 78.0, "median_shift_credits_per_percent": -23.0, "cliffs_delta": -0.71}}
   ],
-  "notes": []
+  "regimes": [
+    {"regime_id": "regime-1", "plan_type": "pro", "start_at": "2025-12-01T00:00:00+00:00", "end_at": "2026-02-22T00:00:00+00:00", "start_index": 0, "end_index": 20, "eligible_cycle_count": 20, "median_credits_per_percent": 142.0, "iqr_credits_per_percent": 18.0, "price_coverage": 1.0},
+    {"regime_id": "regime-2", "plan_type": "pro", "start_at": "2026-03-01T00:00:00+00:00", "end_at": "2026-06-08T00:00:00+00:00", "start_index": 20, "end_index": 45, "eligible_cycle_count": 25, "median_credits_per_percent": 101.0, "iqr_credits_per_percent": 13.0, "price_coverage": 1.0},
+    {"regime_id": "regime-3", "plan_type": "pro", "start_at": "2026-06-15T00:00:00+00:00", "end_at": "2026-07-13T00:00:00+00:00", "start_index": 45, "end_index": 63, "eligible_cycle_count": 18, "median_credits_per_percent": 78.0, "iqr_credits_per_percent": 9.0, "price_coverage": 1.0}
+  ],
+  "caveats": ["Local observed allowance only; outside usage may be missing."]
+}
+```
+
+The detector may return zero, one, or multiple supported boundaries. It controls
+family-wise error with hierarchical alpha spending, requires a strong effect, and
+requires Monte Carlo uncertainty—not just the p-value point estimate—to clear the
+allocated alpha. Explicit subscription-plan transitions split the history into
+independently analyzed continuous segments, with the family-wise alpha divided
+across analyzable segments; a tier transition is never itself a capacity-change
+candidate. Regimes disclose their observed `plan_type`, and the caveats include
+`subscription_plan_segments_analyzed_independently` when this safeguard applies.
+A `no_supported_change` payload intentionally leaves deprecated
+singular p-value and before/after median fields null; rejected candidates are not
+default report data.
+
+### Analysis job
+
+`POST /api/allowance/analysis` or a missing-result
+`usage_allowance_analysis(...)` call returns
+`codex-usage-tracker-analysis-job-v1`. Poll the route/tool every 500 milliseconds
+only while `pending`, `queued`, or `running`, then reload the persisted analysis.
+
+```json
+{
+  "schema": "codex-usage-tracker-analysis-job-v1",
+  "job_id": "allowance-analysis-synthetic-42",
+  "job_kind": "allowance-analysis",
+  "status": "running",
+  "stage": "cycle_block_permutations",
+  "source_revision": "r-synthetic-42",
+  "progress": {"completed_units": 640, "total_units": 2000, "percent": 32.0, "current_unit": "permutation"},
+  "result": null,
+  "error": null,
+  "next": {"action": "poll_analysis_job", "job_id": "allowance-analysis-synthetic-42", "poll_after_ms": 500, "endpoint": "/api/allowance/analysis/jobs/allowance-analysis-synthetic-42"}
 }
 ```
 
+### V1 compatibility
+
+`usage_allowance_history`, `usage_allowance_diagnostics`, and
+`usage_allowance_export` plus `/api/allowance/history`,
+`/api/allowance/diagnostics`, and `/api/allowance/export` remain compatibility and
+explicit offline-diagnostic surfaces. Their v1 schemas are unchanged. New
+dashboard/plugin/MCP integrations should use v2. V2 evidence rejects `limit=0`;
+full strict export is a separate deliberate offline action.
+
 ## Compression Lab
 
 MCP lifecycle: