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

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

@@ -1,6 +1,6 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.19.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.19.0 → codex_usage_tracking-0.21.0}/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## 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.
+- Complete the Simplified Chinese dashboard experience across React views, visualization metadata, tables, accessibility text, CLI help, and dashboard lifecycle messages while preserving user-provided data verbatim.
+- Improve the Overview token-flow chart at constrained desktop widths with a taller single-column layout, larger Sankey node gaps, and label-safe padding; keep virtualized evidence-table actions on one row.
+- Apply official long-context input, cached-input, and output price multipliers to concrete calls above 272K input tokens when the selected OpenAI service tier publishes long-context rates, while keeping aggregate summaries from being incorrectly thresholded.
+
 ## 0.19.0 - 2026-07-15
 
 - Redesign Limits Intelligence around weekly credits-per-percentage capacity

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.19.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
@@ -237,12 +237,12 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 - Local SQLite index at `~/.codex-usage-tracker/usage.sqlite3`.
 - Static dashboard generation plus localhost live refresh.
-- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including evidence-graded weekly allowance analysis and on-demand usage-drain report runs.
+- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including responsive token-flow visualization, evidence-graded weekly allowance analysis, and on-demand usage-drain report runs.
 - Active-only dashboards by default, with an explicit `All history` toggle for archived sessions.
 - CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
 - MCP tools for Codex sessions that want to query local usage data.
 - Companion Codex skills for operational setup and conversational usage analysis.
-- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.
+- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration, including per-call long-context pricing above 272K input tokens for OpenAI service tiers that publish long-context rates.
 
 ## Dashboard Language
 
@@ -262,7 +262,7 @@ CODEX_USAGE_TRACKER_LANG=vi codex-usage-tracker serve-dashboard --open
 
 The dashboard also includes a language selector. Browser selections are stored locally and can override the generated default for that browser.
 
-Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not raw Codex log content, thread names, project names, paths, full CLI output, or data exports.
+Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. Simplified Chinese also localizes CLI help and dashboard lifecycle messages. Localization never rewrites raw Codex log content, thread names, project names, paths, or data exports.
 
 ### Adding A Dashboard Language
 

{codex_usage_tracking-0.19.0 → codex_usage_tracking-0.21.0}/README.md

@@ -189,12 +189,12 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 - Local SQLite index at `~/.codex-usage-tracker/usage.sqlite3`.
 - Static dashboard generation plus localhost live refresh.
-- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including evidence-graded weekly allowance analysis and on-demand usage-drain report runs.
+- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including responsive token-flow visualization, evidence-graded weekly allowance analysis, and on-demand usage-drain report runs.
 - Active-only dashboards by default, with an explicit `All history` toggle for archived sessions.
 - CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
 - MCP tools for Codex sessions that want to query local usage data.
 - Companion Codex skills for operational setup and conversational usage analysis.
-- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.
+- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration, including per-call long-context pricing above 272K input tokens for OpenAI service tiers that publish long-context rates.
 
 ## Dashboard Language
 
@@ -214,7 +214,7 @@ CODEX_USAGE_TRACKER_LANG=vi codex-usage-tracker serve-dashboard --open
 
 The dashboard also includes a language selector. Browser selections are stored locally and can override the generated default for that browser.
 
-Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not raw Codex log content, thread names, project names, paths, full CLI output, or data exports.
+Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. Simplified Chinese also localizes CLI help and dashboard lifecycle messages. Localization never rewrites raw Codex log content, thread names, project names, paths, or data exports.
 
 ### Adding A Dashboard Language
 

{codex_usage_tracking-0.19.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.19.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.19.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.19.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
@@ -83,6 +105,7 @@ Open `Overview` when you want a quick read on current aggregate usage before sor
 - Metric cards summarize loaded aggregate rows without exposing prompts, assistant text, or raw tool output.
 - Default totals exclude only strict clone/copy fingerprint matches while preserving every physical source row in the local index. The environment status strip shows how many copied rows were excluded; hover it to compare canonical and physical row counts.
 - Time-series charts open on the most recent dates first and can scroll left for earlier history while keeping the value axis visible.
+- At constrained desktop widths, the analysis charts stack so the token-flow diagram keeps readable label spacing; fixed-height evidence rows keep their action buttons on one line.
 - `Usage constellation` maps chronology, token volume, cache reuse, model family, waste pressure, and thread continuity in a lazy 3D view. Select a point to open Call Investigator, or switch to the synchronized evidence table for keyboard review and non-WebGL environments.
 - `Recent Calls` keeps the homepage modular: it shows the latest matching calls and lets any row open Call Investigator directly.
 - Use `Investigate` or `Calls` when you need deeper ranking, filtering, or evidence review.
@@ -116,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.
@@ -135,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
@@ -146,16 +184,19 @@ 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.
-- Switch between the virtualized table, cache-efficiency frontier, and lifecycle
-  view. Chart selections update the same selected-thread evidence used by the
-  inspector.
+- Click a thread row to load the first 100 aggregate calls directly beneath it.
+- Only one thread stays expanded at a time.
+- 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.
 - Each thread row groups the filtered model calls by thread name, falling back to session id when no name is available.
 - Thread rows show latest activity, call count, model mix, effort mix, total tokens, estimated cost, Codex credits, cache ratio, and signal count.
 - Mixed model summaries prefer the primary non-review model; `codex-auto-review` appears as the thread model only for review-only threads.
-- Hover or keyboard-select a thread to scan its aggregate inspector. Activating
-  a row opens the latest supporting call in Call Investigator.
-- The inspector's call timeline supports independent sorting, incremental
-  disclosure, copy-link actions, and direct Call Investigator navigation.
 - Subagents with logged parent session ids are shown under the parent thread. Auto-review sessions without explicit parent ids may be attached by cwd and nearby activity and are marked as attached or inferred in the details.
 
 ### Tools And Files Explorers

{codex_usage_tracking-0.19.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.19.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.19.0
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.19.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.19.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.19.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.19.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.19.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.19.0 && codex-usage-tracker --version`.
-- [x] Verify public pipx install path for `0.19.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.19.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.19.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.19.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.19.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.19.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.19.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.19.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.