codex-usage-tracking 0.20.0__tar.gz → 0.21.0__tar.gz

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+## 0.21.0 - 2026-07-17
+
+- Keep the macOS dashboard available at a stable, localhost-only URL with a
+  login LaunchAgent, explicit port-collision handling, health checks, and
+  install, status, and uninstall commands.
+- Preserve responsive inline thread expansion while bounding initial work and
+  polishing progressive call loading, retry behavior, and row presentation.
+- Preserve full-width Windows filesystem identifiers so distinct sources do
+  not collapse during aggregate usage ingestion.
+- Ingest aggregate `response.completed` telemetry from local
+  `codex-completions*.jsonl` exporter files and conservatively reconcile exact
+  Fast/Standard service-tier evidence to canonical calls without retaining raw
+  response bodies or arbitrary OTLP attributes.
+- Show exact service tier separately from the existing Fast proxy in Calls,
+  details, and CSV exports; older or unmatched history remains Unknown.
+- Apply documented model-family Fast multipliers to confirmed Codex credit
+  estimates with source URL/date/confidence and local overrides while leaving
+  standard-credit allowance calibration unchanged.
+- Cache Standard, Batch, Flex, and Priority API pricing together, select the
+  observed tier per call, and expose Standard/Priority cost scenarios plus an
+  explicit local billing basis without applying ChatGPT Fast multipliers to API
+  USD estimates.
+- Preserve exact response tiers in dashboard labels and CSV contracts, clear
+  OTel staging on confirmed database reset, and make incremental source cursors
+  descriptor-safe across concurrent file rotation. Verify a bounded content
+  anchor before resuming so same-inode rewrites cannot silently skip telemetry.
+
 ## 0.20.0 - 2026-07-16
 
 - Reinvent the Threads tab around inline row expansion, progressively loading and virtualizing every call in the selected thread while preserving explicit investigator actions, deep links, responsive layouts, retry recovery, and aggregate-first privacy boundaries.

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.20.0
+Version: 0.21.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.20.0 → codex_usage_tracking-0.21.0}/docs/architecture.md

@@ -17,6 +17,15 @@ Shareable outputs remain aggregate-first and must omit indexed/raw content unles
 ## Boundaries
 
 - `parser.py` converts local JSONL events into aggregate `UsageEvent` records. It also attaches metadata-only call-origin categories, diagnostic facts from `diagnostic_facts.py`, archived-session flags, conservative thread keys, source cursors, and parser diagnostics.
+- `parser/otel.py`, `store/otel_ingest.py`, and `store/otel_reconciliation.py`
+  provide aggregate-only completion enrichment from local
+  `~/.codex-usage-tracker/otel/codex-completions*.jsonl` files. The importer
+  retains only approved completion identifiers, token counters, model/effort,
+  application version, and service-tier metadata; response bodies and arbitrary
+  OTLP attributes are never persisted. Reconciliation requires one canonical
+  call group with the same conversation id and all four token counters. Model
+  and effort narrow a match when both sides provide them, but timestamps are not
+  identity evidence.
 - `store/content_index.py` owns normalized local content-index population and cleanup. It may persist bounded local snippets, tool-call metadata, command roots/labels, file path hashes/basenames, parser adapter metadata, source provenance, parse warnings, and FTS5 search rows. Investigation/report builders may persist bounded run summaries in `investigation_runs`. These surfaces must not feed raw/indexed content into default CSV, dashboard HTML, support bundle, or aggregate report payloads.
 - `call_origin.py` owns the pure call-origin classifier and migrated-row fallback. It must not open source JSONL files; source-log reads belong in refresh/indexing or explicit context loading.
 - `schema.py` owns persisted SQLite columns and migrations. Add columns or tables there before changing refresh, export, or MCP behavior.
@@ -62,6 +71,10 @@ Shareable outputs remain aggregate-first and must omit indexed/raw content unles
     totals through `canonical_usage_events`. New physical-row investigation
     surfaces must be bounded, explicitly labeled, and tested against an
     original/copy/new-call fixture.
+15. Treat service tier as exact only when a completion explicitly reports it, or
+    when Codex `0.143.0` or newer omits it under the documented Standard
+    protocol. Older or unmatched calls remain Unknown. Latency and reasoning
+    effort are useful throughput signals, not proof of Fast usage.
 
 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.20.0 → codex_usage_tracking-0.21.0}/docs/cli-json-schemas.md

@@ -1466,4 +1466,38 @@ Most setup and file-writing commands accept `--json` and return a schema-specifi
 - `init-thresholds --json`, `init-projects --json`
 - `support-bundle --json`
 
+Refresh and rebuild payloads add bounded OTel counters under
+`parser_diagnostics`: `otel_files_scanned`, `otel_imported`,
+`otel_duplicates`, `otel_matched`, `otel_pending`, `otel_ambiguous`, and
+`otel_conflicts` (zero-valued counters may be omitted from the immediate JSON
+payload). Stored refresh metadata keeps the same keys with zero defaults so
+localhost status is stable. These surfaces never expose OTel source paths,
+semantic fingerprints, response bodies, arbitrary attributes, or staging ids.
+
+Aggregate call rows may add nullable `service_tier`, `fast`,
+`service_tier_source`, and `service_tier_confidence` fields. `service_tier`
+preserves the exact normalized response value such as `priority`, `default`,
+`standard`, `flex`, or `batch`; `fast` is the derived speed classification.
+
+Cost-annotated rows may add `standard_cost_usd`, `priority_cost_usd`,
+`pricing_service_tier`, `billing_basis`, and
+`cost_semantics="api_token_estimate"`. `estimated_cost_usd` remains the
+API-token-equivalent estimate selected from the observed tier when pricing-v2
+contains that table. `billing_basis` is `unknown`, `chatgpt_credits`, or
+`api_tokens` and describes applicability rather than changing the observed tier.
+
+Credit-annotated rows may also add `standard_usage_credits`,
+`fast_usage_credits`, `usage_credit_multiplier`,
+`usage_credit_multiplier_source`, `usage_credit_multiplier_source_url`,
+`usage_credit_multiplier_fetched_at`, and
+`usage_credit_multiplier_confidence`. These are ChatGPT-equivalent credit
+scenarios and are never used as generic multipliers for API USD. `fast: null`
+means Unknown; clients must not replace it with the separate throughput proxy.
+CSV export includes the exact tier, both scenario families, multiplier
+provenance, and the separately named proxy candidate.
+
+`rebuild-index` retains aggregate OTel staging for reconciliation. Confirmed
+`reset-db --yes` clears both `otel_completion_events` and
+`otel_completion_sources` along with the other tracker-owned rows.
+
 `context` already returns JSON because it is an explicit on-demand context request. Treat `codex-usage-tracker-context-v1` output as sensitive local context even though it is redacted and size-limited by default. `max_entries=0` requests all matching entries and `max_chars=0` removes the character cap for that explicit request. Tool output and compacted replacement history are omitted unless explicitly requested. Compaction entries may include metadata such as `replacement_history_available`, `replacement_entry_count`, and `replacement_history_included`; replacement text appears only when `include_compaction_history` is true for that local request. Evidence responses include `action_timing`, derived from timestamps in the same selected-turn source scan, plus per-entry `action_timing` fields such as `since_turn_start_ms`, `since_previous_entry_ms`, and `reported_duration_ms` when available. MCP returns `codex-usage-tracker-context-disabled-v1` when raw context loading has not been explicitly enabled with `CODEX_USAGE_TRACKER_ALLOW_RAW_CONTEXT=1`.

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/cli-reference.md

@@ -81,6 +81,26 @@ codex-usage-tracker serve-dashboard --no-refresh --open
 codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
+Keep the live dashboard available across terminal and Codex task lifetimes on
+macOS with the user LaunchAgent commands:
+
+```bash
+codex-usage-tracker dashboard-service install
+codex-usage-tracker dashboard-service status
+codex-usage-tracker dashboard-service uninstall
+```
+
+The persistent service defaults to `http://127.0.0.1:47821`, starts at login,
+restarts after failure, and never opens a browser automatically. Installation
+refuses an occupied port rather than silently changing the URL; use
+`dashboard-service install --port PORT` for an explicit alternative. These
+management actions are macOS-only. The foreground `serve-dashboard` command is
+cross-platform and keeps its existing default port `8765`.
+
+The persistent process starts with the cached aggregate index so the fixed URL
+binds promptly. Its Refresh and Live controls remain the explicit way to rescan
+Codex logs.
+
 `serve-dashboard --context-api explicit` is the default and keeps context loading as an explicit per-row action. `serve-dashboard --no-context-api` or `--context-api disabled` starts with context loading off; a token-protected button in the local details panel can enable it without restarting the server.
 
 `open-dashboard` and `serve-dashboard` refresh active-session logs before opening by default. `serve-dashboard --open` opens the React dashboard; the legacy dashboard remains available at `/dashboard.html` on the same localhost server. Use `--no-refresh` only for an intentionally cached snapshot. The lower-level `dashboard` command writes from the current SQLite index and does not rescan logs.

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/dashboard-guide.md

@@ -6,15 +6,37 @@ This guide uses synthetic aggregate data. The screenshots do not contain real pr
 
 ## Open The Dashboard
 
-For the best experience, run the localhost dashboard server:
+On macOS, install the persistent localhost dashboard once:
 
 ```bash
 codex-usage-tracker setup
 codex-usage-tracker update-pricing
 codex-usage-tracker update-rate-card
+codex-usage-tracker dashboard-service install
+codex-usage-tracker dashboard-service status
+open http://127.0.0.1:47821
+```
+
+The LaunchAgent starts at login, restarts after a failure, stays bound to
+`127.0.0.1`, and does not open browser tabs automatically. If port `47821` is
+already owned by another process, installation refuses the collision; use
+`dashboard-service install --port PORT` to choose and persist a different
+address. Remove the managed service with
+`codex-usage-tracker dashboard-service uninstall`.
+
+Persistent startup serves the cached aggregate index immediately. Use Refresh
+or Live in the dashboard to rescan Codex logs after the page is reachable.
+
+For Linux, Windows, or an on-demand macOS session, run the foreground server:
+
+```bash
+codex-usage-tracker setup
 codex-usage-tracker serve-dashboard --open
 ```
 
+The foreground command retains its existing default port `8765` and stops when
+its process exits.
+
 For optional allowance context, initialize a local template and copy values from Codex Usage or `/status`:
 
 ```bash
@@ -117,6 +139,11 @@ Use `Calls` view when you want to inspect individual model calls.
 - Time values are shown in your browser's local date/time format while sorting and time filtering still use the logged timestamp.
 - Calls include `Duration`, derived from turn start for a new turn or the previous same-turn call end for continuations, and `Prev gap`, the elapsed time since the previous call in the resolved thread.
 - Calls view token columns separate total tokens, cached input, uncached input, and output so the accounting can be scanned without expanding a row.
+- The `Service Tier` column preserves the exact response value with distinct
+  labels for Priority/Fast, Fast, Default/Standard, Standard, Flex, Batch, and
+  other bounded explicit tiers. It shows `Unknown` when completion telemetry is
+  absent. The detail view keeps the older throughput heuristic labeled as a
+  separate Fast proxy candidate rather than historical proof.
 - Source pucks are call-level estimates derived from local event metadata. `User` means the token-count segment included a user message, `Codex` means it followed tool output, compaction, or agent-continuation metadata, and `Unknown` means the source event metadata was unavailable or ambiguous.
 - Click a column header like `Time`, `Thread`, `Tokens`, `Cost`, or `Cache` to sort. Use the sort menu for `Highest Codex credits`. Click the same header again to reverse the direction.
 - Hover a row to scan a compact aggregate preview in `Call Details`; click a Calls row to open the dedicated call investigator.
@@ -136,6 +163,16 @@ Useful interpretation notes:
 - `Cached input` and `Uncached input` are split so cache behavior is visible without storing transcript text.
 - A cost with `*` means the pricing row is marked as a best-guess estimate.
 - Codex credits are estimated from aggregate input, cached-input, and output token counters. Direct model matches use the bundled OpenAI Codex rate-card snapshot; inferred labels are marked estimated, and local credit-rate overrides are marked user-provided.
+- Confirmed Fast rows apply the source-stamped model-family multiplier to
+  ChatGPT-equivalent Codex credits. API-equivalent USD estimates instead select
+  the exact API tier table; the cost detail identifies whether the configured
+  billing basis is API tokens, ChatGPT credits, or Unknown without claiming
+  actual spend when the basis is unknown.
+- CSV exports include exact tier/provenance, the separate Fast proxy,
+  Standard/Priority API cost scenarios, Standard/Fast credit scenarios,
+  `billing_basis`, and credit multiplier source URL/date/confidence. Missing
+  exact tier evidence remains blank/Unknown instead of being reconstructed from
+  duration or reasoning effort.
 - `Usage observed` is not a live account query. It uses the latest local Codex `token_count.rate_limits` snapshot when present; otherwise configure `~/.codex-usage-tracker/allowance.json` with values copied from Codex Settings > Usage, the Codex Usage dashboard, or `/status` when you want current remaining allowance context.
 
 ## Threads View
@@ -147,9 +184,13 @@ Use `Threads` view when you want to understand a work session as a group instead
 - Threads pages through `/api/threads` on localhost and hydrates the selected
   thread's supporting calls through `/api/thread-calls`; loaded snapshot rows
   remain the fallback.
-- Click a thread row to expand all of its aggregate calls directly beneath it.
+- Click a thread row to load the first 100 aggregate calls directly beneath it.
 - Only one thread stays expanded at a time.
-- Remaining call pages load progressively with visible progress and retry.
+- The compact default keeps the most useful comparison columns visible; use
+  `Columns` to reveal duration, model/effort mix, token breakdowns, and other
+  advanced fields without making the default leaderboard excessively wide.
+- Use `Load 100 more` to request each additional page; visible progress and retry
+  keep large threads bounded and recoverable.
 - Parent rows never open a representative call.
 - Explicit child `Open` and `Copy` actions reach Call Investigator.
 - Cache Frontier and Lifecycle remain secondary analysis modes.

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/database-schema.md

@@ -32,6 +32,39 @@ identity, parser coverage, replacement, and refresh revision. Changing or removi
 a source causes its owned physical rows/materializations to be replaced in a
 transaction rather than accumulated blindly.
 
+## OTel Service-Tier Enrichment (Schemas 30–31)
+
+Schema 30 adds nullable `service_tier`, `fast`, `service_tier_source`, and
+`service_tier_confidence` columns to `usage_events`. Null means the tracker does
+not have exact tier evidence; it is not interpreted as Standard.
+
+`otel_completion_sources` records device/inode identity, size, the last complete
+byte and line cursor, a bounded SHA-256 resume anchor, and an update timestamp
+for each local `codex-completions*.jsonl` file. The default directory is the
+`otel` sibling of the selected database (`~/.codex-usage-tracker/otel` for the
+default database), so alternate databases do not ingest another tracker
+instance's telemetry.
+`otel_completion_events` stores one semantic
+fingerprint plus aggregate matching fields, the exact normalized response tier,
+derived Fast classification, tier provenance, a
+bounded match status (`pending`, `matched`, `ambiguous`, `conflict`, or
+`invalid`), and the matched aggregate record id when available.
+
+Append refresh resumes after the last complete JSONL line, retries a partial
+trailing line, and restarts a cursor after rotation, truncation, or a mismatched
+resume anchor. Schema 31 adds the anchor; a legacy cursor without one is safely
+reread once and then anchored. Cursor identity, size, offsets, and anchor bytes
+come from the open descriptor so a path rotation or same-inode replacement
+cannot persist an offset against different content. Rebuild keeps
+the aggregate OTel staging rows, resets their match pointers, and reconciles
+them against the rebuilt canonical calls. A match requires conversation id plus
+input, cached-input, output, and reasoning-output counters to resolve to exactly
+one canonical group. Existing contradictory tier values are preserved and the
+completion is marked as a conflict.
+
+`reset-db --yes` is intentionally different from rebuild: it deletes both OTel
+staging tables and their source cursors along with the other tracker-owned rows.
+
 ## Allowance Intelligence Materializations
 
 `allowance_observations` stores normalized structured weekly and 5-hour snapshots,
@@ -68,7 +101,7 @@ Identical keys reuse a completed snapshot or the same in-flight job.
 
 ## Privacy And Rebuilds
 
-Allowance materializations and logical identity contain aggregate metadata only.
+Allowance materializations, OTel completion staging, and logical identity contain aggregate metadata only.
 They do not contain prompts, assistant text, tool output, or raw JSONL content.
 Rebuilds can recreate them from physical aggregate rows and source provenance.
 The local content index is a separate opt-in investigation layer and is not used

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/development.md

@@ -174,8 +174,8 @@ python scripts/smoke_installed_package.py --docker
 To verify the public PyPI package instead of the local checkout:
 
 ```bash
-python scripts/smoke_installed_package.py --from-pypi --version 0.20.0
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.20.0
+python scripts/smoke_installed_package.py --from-pypi --version 0.21.0
+python scripts/smoke_installed_package.py --docker --from-pypi --version 0.21.0
 ```
 
 `scripts/check_release.py` treats these public-package smoke commands as release-state claims. Keep their `--version` and `codex-usage-tracking==...` values aligned with `pyproject.toml`; the release gate fails when the docs claim a different public version. It also checks that install docs point at the real PyPI distribution, `codex-usage-tracking`, and keep the warning that `codex-usage-tracker` is a different PyPI package.

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/install.md

@@ -11,9 +11,15 @@ python -m pip install --user pipx
 python -m pipx ensurepath
 pipx install codex-usage-tracking
 codex-usage-tracker setup
-codex-usage-tracker serve-dashboard --open
+codex-usage-tracker dashboard-service install  # macOS
 ```
 
+On macOS, the persistent service starts at login, restarts after a failure, and
+keeps the live dashboard available at `http://127.0.0.1:47821` without opening
+browser tabs automatically. Check it with
+`codex-usage-tracker dashboard-service status`. On Linux and Windows, or for a
+one-time macOS session, use `codex-usage-tracker serve-dashboard --open`.
+
 Use the Python launcher that is normal for your platform:
 
 - macOS/Linux: `python3` may be the right command instead of `python`.
@@ -112,6 +118,25 @@ codex-usage-tracker install-plugin --python .venv/bin/python --force
 
 ## Local Dashboard
 
+On macOS, install the localhost-only login service once:
+
+```bash
+codex-usage-tracker dashboard-service install
+codex-usage-tracker dashboard-service status
+open http://127.0.0.1:47821
+```
+
+The service uses fixed port `47821` by default and never exposes a non-loopback
+host. If another local process owns that port, installation stops with a clear
+error instead of changing the URL; choose an explicit alternative with
+`codex-usage-tracker dashboard-service install --port PORT`. To remove only the
+tracker-managed LaunchAgent, run
+`codex-usage-tracker dashboard-service uninstall`.
+
+The login service binds promptly from the cached aggregate index. Use the
+dashboard's Refresh or Live controls when you want to rescan Codex logs; the
+initial background process does not hold the port closed during a full rescan.
+
 Generate a static dashboard:
 
 ```bash
@@ -126,6 +151,9 @@ codex-usage-tracker serve-dashboard --open
 codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
+Foreground `serve-dashboard` remains the cross-platform, on-demand option and
+retains its existing default port `8765`.
+
 The server binds to localhost, requires a per-server token for refresh/context endpoints, and rejects non-loopback `Host` or cross-origin `Origin` headers.
 `--no-context-api` starts context loading off; the details panel can enable it later without restarting the server.
 

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/one-dot-oh-readiness.md

@@ -24,12 +24,12 @@ Not guaranteed:
 
 ## 1. Public Install And Package Metadata
 
-- [x] Verify the current public PyPI version is visible as `0.20.0`: `python -c "import json, urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/codex-usage-tracking/json'))['info']['version'])"`.
-- [x] Verify public venv install for `0.20.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.20.0 && codex-usage-tracker --version`.
-- [x] Verify public pipx install path for `0.20.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.20.0 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
+- [x] Verify the current public PyPI version is visible as `0.21.0`: `python -c "import json, urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/codex-usage-tracking/json'))['info']['version'])"`.
+- [x] Verify public venv install for `0.21.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.21.0 && codex-usage-tracker --version`.
+- [x] Verify public pipx install path for `0.21.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.21.0 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
 - [x] Verify installed package resources from a built wheel: `python scripts/smoke_installed_package.py`.
 - [x] Verify installed package resources in Linux Docker: `python scripts/smoke_installed_package.py --docker`.
-- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.20.0`.
+- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.21.0`.
 - [x] Verify PyPI metadata names remain unchanged: `python scripts/check_release.py`.
 - [x] Add Python 3.14 as an official support target after CI, package classifiers, docs, and installed-package smoke coverage were added. Docker smoke coverage uses `python:3.14-slim` by default. Track this in issue #12.
 
@@ -134,14 +134,14 @@ Not guaranteed:
 
 ## Evidence References
 
-These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.20.0`; all repo tests use synthetic or aggregate-only data.
+These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.21.0`; all repo tests use synthetic or aggregate-only data.
 
 ### Public Install And Package Metadata
 
 - Public PyPI version, public venv install, and public pipx install are proven by the exact public-install commands in section 1.
 - Built-wheel and installed-resource coverage is proven by `scripts/smoke_installed_package.py` and `tests/test_cli_release.py::test_installed_package_smoke_checks_help_for_stable_commands`.
 - Linux package-resource coverage is proven by `scripts/smoke_installed_package.py --docker`.
-- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.20.0`.
+- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.21.0`.
 - PyPI metadata, package/distribution names, package resources, source/wheel member names, Python 3.10-3.14 support metadata, CI workflow requirements, publish workflow safety text, and tracked secret patterns are proven by `scripts/check_release.py`, `scripts/check_release.py --dist`, and `tests/test_cli_release.py::test_release_check_script_passes`.
 
 ### Upgrade And Migration
@@ -219,8 +219,8 @@ These references are the concrete proof behind completed checklist items. Public
 - Publish workflow package name, Trusted Publishing, TestPyPI/PyPI job presence, event guards, no push/PR publishing, no token/password publishing, and manual PyPI main/tag preflight are proven by `scripts/check_release.py::_check_publish_workflow`.
 - The GitHub `pypi` environment gate is proven by `gh api repos/douglasmonsky/codex-usage-tracker/environments/pypi`, which reports a `required_reviewers` protection rule and `can_admins_bypass=false`.
 - Dist filename and wheel/sdist member checks are proven by `python -m build`, `python -m twine check dist/*`, and `python scripts/check_release.py --dist`.
-- TestPyPI publish process is proven by a workflow-dispatch run on `main`, followed by TestPyPI metadata and clean virtualenv install checks for `codex-usage-tracking==0.20.0`.
-- PyPI publish process is proven by a workflow-dispatch run on `main`, protected `pypi` environment approval, PyPI metadata visibility, clean virtualenv install, temporary pipx install, and Docker public-package smoke for `codex-usage-tracking==0.20.0`.
+- TestPyPI publish process is proven by a workflow-dispatch run on `main`, followed by TestPyPI metadata and clean virtualenv install checks for `codex-usage-tracking==0.21.0`.
+- PyPI publish process is proven by a workflow-dispatch run on `main`, protected `pypi` environment approval, PyPI metadata visibility, clean virtualenv install, temporary pipx install, and Docker public-package smoke for `codex-usage-tracking==0.21.0`.
 - Release recovery documentation is proven by `scripts/check_release.py` required-file and docs checks.
 
 ### Known Limitations

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/pricing-and-credits.md

@@ -14,7 +14,7 @@ Enable optional cost estimates:
 codex-usage-tracker update-pricing
 ```
 
-This fetches OpenAI text-token pricing from `https://developers.openai.com/api/docs/pricing.md`, parses the selected tier, and writes a source-stamped local cache to `~/.codex-usage-tracker/pricing.json`. The default tier is `standard`; other supported tiers are `batch`, `flex`, and `priority`.
+This fetches OpenAI text-token pricing from `https://developers.openai.com/api/docs/pricing.md` once, parses the `standard`, `batch`, `flex`, and `priority` tables, and writes a source-stamped pricing-v2 cache to `~/.codex-usage-tracker/pricing.json`. The top-level `models` object remains the selected-tier compatibility projection, while `api_service_tiers` retains every published table so mixed historical calls can be priced by their observed response tier.
 
 The updater supports both the older four-value pricing rows and the newer five-value rows used by GPT-5.6 for input, cached input, cache writes, and output. GPT-5.6 Sol, Terra, and Luna are loaded from the published table, and the documented `gpt-5.6` alias resolves to `gpt-5.6-sol`. Current Codex logs do not expose a separate cache-write token counter, so cost estimates use the logged uncached input, cached input, and output counters without adding an explicit cache-write charge.
 
@@ -39,6 +39,20 @@ codex-usage-tracker init-pricing
 
 Edit `~/.codex-usage-tracker/pricing.json` with USD-per-million-token rates for local overrides or models that are not present in the OpenAI pricing table. Normal reports never contact the network; only `update-pricing` refreshes the local pricing cache.
 
+### Billing Basis And Tier Scenarios
+
+OTel `service_tier=priority` proves the response tier, but it does not prove whether the call used ChatGPT/Codex credits or an API key. Set the top-level local `billing_basis` only when you know the billing path:
+
+```json
+{
+  "billing_basis": "unknown"
+}
+```
+
+Supported values are `unknown`, `chatgpt_credits`, and `api_tokens`. `update-pricing` preserves this local value. Invalid values make the pricing config invalid instead of silently guessing.
+
+`estimated_cost_usd` is always an API-token-equivalent estimate. With pricing-v2, it selects the exact observed API table for `priority`, `default`/`standard`, `flex`, or `batch`; it never applies a generic ChatGPT Fast multiplier. Each annotated row also exposes `standard_cost_usd`, `priority_cost_usd`, `pricing_service_tier`, `billing_basis`, and `cost_semantics` so an unknown billing path can be reported as bounded scenarios rather than false actual spend. Pricing-v1 files remain readable and keep their existing single-table behavior.
+
 ## Codex Credits
 
 `Codex Credits` is a calculated usage number, not a dashboard-only unit. The tracker uses Codex's logged aggregate token counters and the bundled OpenAI Codex rate-card snapshot to estimate credits consumed by local Codex calls.
@@ -62,6 +76,34 @@ codex-usage-tracker update-rate-card
 
 The local snapshot is written to `~/.codex-usage-tracker/rate-card.json`. Each bundled rate and alias includes source URL, fetched date, tier, confidence, and alias rationale where applicable. Use `--source-file` only when you have a reviewed replacement JSON snapshot you want the tracker to validate and use.
 
+### Confirmed Fast Usage
+
+When a call has exact OTel evidence that `fast=1`, the tracker first computes
+`standard_usage_credits`, then applies the documented model-family Fast
+multiplier to produce `usage_credits`:
+
+- GPT-5.6 family: `2.5x`
+- GPT-5.5 family: `2.5x`
+- GPT-5.4 family: `2.0x`
+
+The row also exposes `fast_usage_credits`, `usage_credit_multiplier`, and
+source URL/date/confidence fields so the adjustment is auditable independently
+from OTel tier evidence. A confirmed
+Fast call whose model has no documented multiplier stays at `1.0x` and is
+marked `no_documented_fast_multiplier`; the tracker does not guess. Standard
+and Unknown-tier calls also stay at `1.0x`.
+
+The bundled `fast_multipliers` rate-card entries are source-stamped. A local
+`allowance.json` may override a model-family entry with `multiplier`,
+`source_name`, `source_url`, and `fetched_at`; valid local entries are marked
+`user_override`, while malformed entries do not replace the bundled value.
+
+This adjustment applies only to Codex/ChatGPT usage-credit estimates. It never
+changes API USD estimates, which use the observed API service-tier table and
+aggregate token counters. Allowance-drain calibration uses the
+standard-credit baseline so a newly observed Fast label does not redefine the
+historical credit-to-percentage relationship.
+
 ## Usage Observed
 
 `Usage observed` is different from `Codex Credits`. The tracker cannot currently read your logged-in ChatGPT plan, live remaining credits, reset windows, or usage from other agentic surfaces automatically.
@@ -90,6 +132,13 @@ Configure the usage component:
 - Codex upstream log formats can change, and parser compatibility may require tracker updates before new event shapes are fully understood.
 - Pricing and rate-card sources can change outside this project. Refresh or pin local files when reports need a known source snapshot.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
+- Service tier is exact only when a local completion explicitly reports it or
+  Codex `0.143.0` or newer establishes Standard through omission. Older or
+  unmatched history remains Unknown; latency and reasoning effort cannot prove
+  Fast usage.
+- `priority` can describe ChatGPT Fast mode or API Priority processing. The
+  retained telemetry does not identify authentication or billing, so leave
+  `billing_basis` as `unknown` unless you have independent evidence.
 - Live account allowance cannot be read automatically by this local tracker, and the dashboard does not infer live remaining allowance from the logged-in account plan.
 - Observed local-log snapshots may be stale until Codex records another model call, and may omit other agentic surfaces that share the same allowance.
 - Pricing can change after a report is generated. Use `pin-pricing` when you need reproducible historical cost estimates.

{codex_usage_tracking-0.20.0 → codex_usage_tracking-0.21.0}/docs/privacy.md

@@ -22,11 +22,29 @@ The local SQLite database is stored at `~/.codex-usage-tracker/usage.sqlite3` by
   quality/coverage metrics, source revisions, and persisted statistical results
 - diagnostic fact labels tied to aggregate call records, safe event categories, payload type labels, counts, timestamps, and line ranges
 - pricing, credit, allowance, recommendation, and project metadata derived from aggregate fields
+- aggregate OTel completion identifiers, token counters, normalized service
+  tier/provenance, application version, semantic fingerprints, source cursors,
+  and bounded reconciliation status from local
+  `~/.codex-usage-tracker/otel/codex-completions*.jsonl` files
 - normalized local content-index rows for local investigation, including conversation turns, bounded content fragments, tool calls, command runs, file events, source provenance, parser adapter metadata, parser warnings, and FTS5 search rows when SQLite supports FTS5
 - bounded local investigation run summaries, including run kind, schema id, content-mode flags, strict summary JSON, branch counts, evidence counts, and timestamps
 
 The content index is intended for local MCP/API exploration. It is not a hosted collection system and it does not change where the original Codex logs live. Normalized command and file-event rows store command roots/labels plus path hashes/basenames rather than full shell commands or full paths; bounded raw snippets remain confined to `content_fragments`.
 
+The OTel completion reader accepts only `codex.sse_event` /
+`response.completed` aggregate fields needed for conservative call matching and
+tier classification. It never persists OTLP response bodies or arbitrary
+attributes. Default exports do not expose staging fingerprints, source paths,
+or matched record pointers. Support bundles report only whether the configured
+completion directory exists and bounded aggregate refresh/reconciliation counts.
+The exact response tier does not reveal whether ChatGPT credits or an API key
+paid for the call; the tracker keeps that billing basis as separate local
+configuration and defaults it to Unknown.
+
+`rebuild-index` retains aggregate OTel staging so it can reconcile tiers after
+canonical rows are recreated. Confirmed `reset-db --yes` deletes that staging
+and its cursors. Neither operation changes or deletes the source exporter files.
+
 Cloned Codex tasks can copy historical calls into another local JSONL file. The tracker keeps every physical row and its source metadata in SQLite, but default dashboard, CLI, MCP, report, recommendation, allowance, compression, and export totals use one canonical representative for strict fingerprint matches. Similar calls are never excluded on fuzzy evidence. Deduplication diagnostics expose aggregate totals plus bounded provenance metadata for excluded rows; they never include prompt, response, tool-output, or raw-log content.
 
 ## Shareable Outputs
@@ -42,6 +60,11 @@ Default shareable outputs omit indexed or raw content. That includes:
 - allowance exports
 - source coverage reports
 
+Tier-aware shareable rows may include exact service-tier labels, API-equivalent
+Standard/Priority cost scenarios, ChatGPT-equivalent credit scenarios, billing
+basis, and source-stamped multiplier metadata. These are aggregate pricing
+annotations and do not include authentication tokens or raw OTel payloads.
+
 Those outputs should not include prompts, assistant messages, tool output, pasted secrets, raw snippets, reconstructed transcript evidence, indexed fragments, or full JSONL records unless a future command is explicitly documented as a local raw/content export.
 
 Default totals and allowance intelligence use canonical usage rows. High-confidence
@@ -112,7 +135,7 @@ The report pack contains aggregate report definitions, linked aggregate call
 rows, a schema marker, and a server generation timestamp. It does not include
 prompts, assistant text, tool output, command output, or indexed content.
 
-Source JSONL reads happen during refresh/indexing, explicit on-demand context loading for one selected call, and explicit synthetic benchmark/diagnostic runs. Live refresh records source metadata and parser cursors so unchanged logs can be skipped and append-only growth can parse from the last indexed byte. Live aggregate APIs do not return indexed content unless an endpoint is explicitly documented as a local content investigation endpoint.
+Source JSONL reads happen during refresh/indexing, explicit on-demand context loading for one selected call, and explicit synthetic benchmark/diagnostic runs. Refresh also reads only local `codex-completions*.jsonl` OTLP exporter files for aggregate service-tier enrichment. Live refresh records source metadata and parser cursors so unchanged logs can be skipped and append-only growth can parse from the last indexed byte. Live aggregate APIs do not return indexed content unless an endpoint is explicitly documented as a local content investigation endpoint.
 
 ## Privacy Modes
 
@@ -142,7 +165,7 @@ Strict mode redacts local diagnostic path strings in bundle doctor details while
 
 Cost estimates are calculated only from aggregate token fields and your local pricing config. They are omitted when no matching model price is configured. Pricing refreshes pull only OpenAI's public pricing markdown and do not send local usage data anywhere.
 
-Codex credit estimates are calculated only from aggregate token fields and bundled or locally configured rate-card values. The optional allowance config stores only remaining percentages, reset times, and credit totals you manually enter. Observed rate-limit snapshots, when present in Codex token-count logs, store only structured percentages, window lengths, reset times, plan type, and limit id.
+Codex credit estimates are calculated only from aggregate token fields and bundled or locally configured rate-card values. Confirmed Fast calls may apply the documented model-family credit multiplier; this does not change USD token-cost estimates. The optional allowance config stores only remaining percentages, reset times, and credit totals you manually enter. Observed rate-limit snapshots, when present in Codex token-count logs, store only structured percentages, window lengths, reset times, plan type, and limit id.
 
 Allowance calibration and forecasts use canonical aggregate credits and observed
 percentages. A displayed credits-per-percent value is a personal historical