codex-usage-tracking 0.4.0__tar.gz → 0.4.1__tar.gz

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Unofficial local tracker for aggregate Codex token usage from local session logs.",
   "author": {
     "name": "Douglas Monsky"

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.4.1 - 2026-06-09
+
+- Harden the production PyPI workflow so manual publishing must run from `main` or a tag ref before artifacts are downloaded and uploaded.
+- Strengthen `scripts/check_release.py` so it validates the publish-ref preflight inside both the TestPyPI and PyPI jobs.
+- Check off completed 1.0 readiness items with evidence for migration coverage, localhost dashboard smoke testing, and the protected GitHub `pypi` environment.
+- Pin the marketplace MCP runtime launcher to the exact `codex-usage-tracking==0.4.1` package.
+
 ## 0.4.0 - 2026-06-09
 
 - Add official Python 3.14 support across CI, package classifiers, README/install docs, and installed-package Docker smoke coverage.

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.4.0
+Version: 0.4.1
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -253,10 +253,13 @@ This is optional. The normal shell install above is the fastest trusted path for
 ## Current Limitations
 
 - This is a sidecar dashboard and plugin, not a native Codex chat overlay.
+- Codex upstream log formats can change, and parser compatibility may require tracker updates.
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
-- Pricing and Codex credit estimates depend on local rate data and confidence labels.
-- Remaining 5-hour and weekly allowance is not read automatically from the logged-in account.
+- Pricing and rate-card sources can change outside this project.
+- Pricing and Codex credit estimates depend on local rate data and confidence labels and are not guaranteed to match exact billing.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is only available when you configure copied values.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
+- Plugin discovery limitations are separate from core Python CLI/dashboard support.
 - Parent-child thread relationships are only as good as the metadata Codex logs; inferred auto-review attachments are labeled as inferred.
 
 ## Roadmap

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/README.md

@@ -216,10 +216,13 @@ This is optional. The normal shell install above is the fastest trusted path for
 ## Current Limitations
 
 - This is a sidecar dashboard and plugin, not a native Codex chat overlay.
+- Codex upstream log formats can change, and parser compatibility may require tracker updates.
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
-- Pricing and Codex credit estimates depend on local rate data and confidence labels.
-- Remaining 5-hour and weekly allowance is not read automatically from the logged-in account.
+- Pricing and rate-card sources can change outside this project.
+- Pricing and Codex credit estimates depend on local rate data and confidence labels and are not guaranteed to match exact billing.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is only available when you configure copied values.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
+- Plugin discovery limitations are separate from core Python CLI/dashboard support.
 - Parent-child thread relationships are only as good as the metadata Codex logs; inferred auto-review attachments are labeled as inferred.
 
 ## Roadmap

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/docs/cli-reference.md

@@ -4,6 +4,14 @@ This page lists the common command-line workflows. For tested JSON contract ids,
 
 ## Index And Setup
 
+Run first-time setup:
+
+```bash
+codex-usage-tracker setup
+```
+
+`setup` installs or refreshes the local plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `doctor`, and prints whether Codex needs a restart for plugin discovery.
+
 Refresh the local aggregate index:
 
 ```bash
@@ -27,6 +35,36 @@ codex-usage-tracker inspect-log ~/.codex/sessions/YYYY/MM/DD/rollout-...jsonl --
 
 `inspect-log` reports parser adapter, aggregate token-count events, session ids, models, and parser diagnostics. It does not store raw prompts, assistant messages, tool output, or transcript snippets.
 
+Check setup without writing files:
+
+```bash
+codex-usage-tracker doctor
+codex-usage-tracker doctor --suggest-repair
+```
+
+`doctor` validates local paths, database state, parser diagnostics, pricing and allowance config, dashboard output, plugin files, and MCP importability. `--suggest-repair` adds likely next commands without making changes.
+
+Reset only the local aggregate database:
+
+```bash
+codex-usage-tracker reset-db --yes
+```
+
+`reset-db` deletes tracker-owned aggregate SQLite rows. It does not delete raw Codex logs and requires `--yes`.
+
+## Plugin Lifecycle
+
+```bash
+codex-usage-tracker install-plugin
+codex-usage-tracker install-plugin --python .venv/bin/python
+codex-usage-tracker upgrade-plugin
+codex-usage-tracker uninstall-plugin
+```
+
+`install-plugin` writes the package-owned local Codex plugin wrapper, companion skills, and MCP config. Use the `--python` form for source checkouts that should use a repo-local virtual environment.
+
+`upgrade-plugin` refreshes an existing wrapper in place. `uninstall-plugin` removes only the tracker-owned plugin wrapper and marketplace entry.
+
 ## Dashboard
 
 ```bash
@@ -110,6 +148,14 @@ codex-usage-tracker export --output usage.csv --limit 0
 
 Use `--privacy-mode redacted` or `--privacy-mode strict` before sharing CSV output.
 
+## Support Bundle
+
+```bash
+codex-usage-tracker --privacy-mode strict support-bundle --output ~/.codex-usage-tracker/support-bundle.json
+```
+
+Support bundles are diagnostic summaries for issues. They include package, platform, doctor, schema, parser, pricing, allowance, threshold, project-config, and privacy metadata. They exclude raw logs, aggregate rows, prompts, assistant messages, tool output, and context text.
+
 ## Local Config
 
 ```bash
@@ -125,6 +171,16 @@ codex-usage-tracker init-projects
 
 Local config files live under `~/.codex-usage-tracker/` and are never committed by this project.
 
+Stable local config files:
+
+- `pricing.json`: schema `_schema: codex-usage-tracker-pricing-v1`, optional `_source`, `models`, `aliases`, and `_estimated_models`. `models` maps model labels to USD-per-million-token rates such as `input`, `cached_input`, and `output`.
+- `rate-card.json`: schema `codex-usage-tracker-codex-rate-card-v1`, optional `_source`, `credit_rates`, and `aliases`. `credit_rates` maps Codex model labels to credit rates for aggregate token counters.
+- `allowance.json`: schema `codex-usage-tracker-allowance-v1`, `windows`, optional `credit_rates`, and `aliases`. `windows` stores copied 5-hour, weekly, or other allowance snapshots such as `remaining_percent`, `reset_at`, `remaining_credits`, and `total_credits`.
+- `thresholds.json`: JSON object keyed by recommendation threshold names such as `low_cache_ratio`, `high_context_percent`, and `high_cost_usd`. Unknown keys are ignored.
+- `projects.json`: JSON object with `aliases`, `ignored_paths`, and `tags` for local project attribution.
+
+These config schemas are part of the 1.0 compatibility surface. New optional fields may be added, but existing meanings should not change without documentation and a compatibility plan.
+
 ## Privacy Mode
 
 `--privacy-mode` is a global option, so place it before the subcommand:

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/docs/dashboard-guide.md

@@ -22,9 +22,9 @@ codex-usage-tracker init-allowance
 codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7"
 ```
 
-To tune review thresholds locally, run `codex-usage-tracker init-thresholds` and edit `~/.codex-usage-tracker/thresholds.json`. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.
+To tune review thresholds locally, run `codex-usage-tracker init-thresholds` and edit `~/.codex-usage-tracker/thresholds.json`. This file is a JSON object keyed by recommendation threshold names such as `low_cache_ratio`, `high_context_percent`, and `high_cost_usd`; unknown keys are ignored. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.
 
-To tune project attribution locally, run `codex-usage-tracker init-projects` and edit `~/.codex-usage-tracker/projects.json`. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate `cwd` and local Git metadata when available.
+To tune project attribution locally, run `codex-usage-tracker init-projects` and edit `~/.codex-usage-tracker/projects.json`. This file supports `aliases`, `ignored_paths`, and `tags`. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate `cwd` and local Git metadata when available.
 
 Before sharing screenshots or generated artifacts, use `--privacy-mode redacted` or `--privacy-mode strict` before the subcommand:
 

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/docs/development.md

@@ -38,7 +38,7 @@ fix/<issue-number>-short-description
 docs/<issue-number>-short-description
 chore/<issue-number>-short-description
 test/<issue-number>-short-description
-release/0.4.0
+release/0.4.1
 hotfix/0.3.3
 ```
 
@@ -91,7 +91,7 @@ blocked
 Recommended milestones:
 
 ```text
-0.4.0
+0.4.1
 1.0-readiness
 1.0.0
 ```
@@ -147,8 +147,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.4.0
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.4.0
+python scripts/smoke_installed_package.py --from-pypi --version 0.4.1
+python scripts/smoke_installed_package.py --docker --from-pypi --version 0.4.1
 ```
 
 Docker avoids local toolchain side effects during install testing. Keep one local `pipx` smoke for platform-specific PATH and plugin-discovery behavior, but use Docker for repeatable Linux package verification.
@@ -264,8 +264,8 @@ After the release branch merges, tag from updated `main`, not from an unreviewed
 ```bash
 git switch main
 git pull --ff-only
-git tag -a v0.4.0 -m "codex-usage-tracker 0.4.0"
-git push origin v0.4.0
+git tag -a v0.4.1 -m "codex-usage-tracker 0.4.1"
+git push origin v0.4.1
 ```
 
 Do not create or push release tags without maintainer approval.
@@ -274,12 +274,13 @@ Do not create or push release tags without maintainer approval.
 
 Publishing uses GitHub Actions Trusted Publishing through `.github/workflows/publish.yml`; do not upload from a local machine and do not add PyPI or TestPyPI API tokens.
 
-The first public package release, `0.3.0`, was published on June 8, 2026. Patch release `0.3.1` followed the same day to ship the live-dashboard skill launch fix. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading. Minor release `0.4.0` added Python 3.14 support, release recovery docs, stricter privacy/support-bundle regression coverage, and large-history benchmark thresholds:
+The first public package release, `0.3.0`, was published on June 8, 2026. Patch release `0.3.1` followed the same day to ship the live-dashboard skill launch fix. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading. Minor release `0.4.0` added Python 3.14 support, release recovery docs, stricter privacy/support-bundle regression coverage, and large-history benchmark thresholds. Patch release `0.4.1` hardened the PyPI publish workflow and checked off completed 1.0 readiness gates:
 
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.0`
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.1`
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.2`
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.4.0`
+- GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.4.1`
 - PyPI: `https://pypi.org/project/codex-usage-tracking/`
 - TestPyPI: `https://test.pypi.org/project/codex-usage-tracking/`
 

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/docs/install.md

@@ -38,6 +38,8 @@ By default the tracker looks for Codex JSONL logs under `~/.codex`, stores its o
 
 Windows support should work for the core dashboard/CLI when Codex writes readable JSONL logs, but plugin discovery is tied to Codex's local plugin directory behavior. Run `codex-usage-tracker doctor --suggest-repair` after setup if Codex does not show the plugin.
 
+Plugin discovery limitations are separate from core Python CLI/dashboard support. If Codex cannot discover the local plugin wrapper, the installed command, SQLite index, generated dashboard, localhost server, and CLI JSON reports can still work.
+
 ## Upgrade
 
 ```bash

codex_usage_tracking-0.4.1/docs/one-dot-oh-readiness.md

@@ -0,0 +1,226 @@
+# 1.0 Readiness
+
+This checklist tracks the work needed to move from the first public PyPI releases toward a stable 1.0 contract. Keep all verification data synthetic or aggregate-only.
+
+Each completed checkbox names the primary verification command inline. The evidence reference section at the end maps those commands to the concrete tests, scripts, workflow checks, or public-install smokes that prove the completed items.
+
+## Compatibility Promise
+
+- CLI command names documented in `docs/cli-reference.md` are stable after 1.0.
+- JSON schema IDs documented in `docs/cli-json-schemas.md` are stable after 1.0.
+- New JSON fields may be added in minor releases, but existing required fields should not be removed or change type without a new schema version.
+- MCP tool names and response schemas are stable after 1.0.
+- CSV export columns are stable after 1.0 unless a new export schema or version flag is introduced.
+- Config file schemas for pricing, allowance, thresholds, projects, and rate cards are stable after 1.0.
+- Privacy-mode semantics are stable after 1.0.
+- SQLite migrations must support upgrade from the last pre-1.0 release to 1.0.
+
+Not guaranteed:
+
+- Codex upstream log format stability.
+- OpenAI pricing or rate-card source stability.
+- Automatic access to live account allowance.
+- Exact billing equivalence.
+
+## 1. Public Install And Package Metadata
+
+- [x] Verify the current public PyPI version is visible as `0.4.1`: `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.4.1`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.4.1 && codex-usage-tracker --version`.
+- [x] Verify public pipx install path for `0.4.1`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.4.1 && /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.4.1`.
+- [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.
+
+## 2. Upgrade And Migration
+
+- [x] Add synthetic legacy SQLite fixture test proving `init_db` upgrades without data loss: `python -m pytest tests/test_store_migrations.py`.
+- [x] Reassess whether a synthetic v0.3-style SQLite fixture is required; the current legacy migration fixture covers active schema drift, so no separate v0.3 fixture is currently needed: `python -m pytest tests/test_store_migrations.py`.
+- [x] Verify `schema_state` reports expected version and checksum after migration: `python -m pytest tests/test_store_migrations.py`.
+- [x] Verify `rebuild-index` clears only tracker-owned aggregate tables: `python -m pytest tests/test_store_dashboard_mcp.py`.
+- [x] Verify `reset-db` does not touch raw Codex logs: `python -m pytest tests/test_cli_lifecycle.py`.
+- [x] Verify refresh metadata and parser diagnostics survive migration: `python -m pytest tests/test_store_migrations.py tests/test_parser.py`.
+- [x] Verify CSV export columns after migration: `python -m pytest tests/test_store_migrations.py`.
+
+## 3. CLI Compatibility
+
+- [x] Confirm every documented command in `docs/cli-reference.md` exists: `python -m pytest tests/test_cli_release.py`.
+- [x] Confirm no documented command is removed without a deprecation plan: manual diff review plus `python -m pytest tests/test_cli_release.py`.
+- [x] Verify command help works from an installed wheel: `python scripts/smoke_installed_package.py`.
+- [x] Verify lifecycle commands still return actionable errors without real logs: `python -m pytest tests/test_cli_lifecycle.py`.
+
+## 4. MCP Compatibility
+
+- [x] Verify MCP tool names remain documented in `docs/mcp.md`: `python -m pytest tests/test_cli_release.py`.
+- [x] Verify MCP JSON responses use tracked schema IDs where applicable: `python -m pytest tests/test_store_dashboard_mcp.py`.
+- [x] Verify companion skill packaged copy matches source skill: `python scripts/check_release.py`.
+- [x] Verify plugin installer writes MCP config from an installed wheel: `python scripts/smoke_installed_package.py`.
+
+## 5. JSON Contract Stability
+
+- [x] Verify every documented `--json` command has a tracked schema: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify every schema in `docs/cli-json-schemas.md` exists in `src/codex_usage_tracker/json_contracts.py`: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify every schema in `json_contracts.py` is documented: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify known payload examples pass `validate_json_payload_contract`: `python -m pytest tests/test_json_contracts.py`.
+- [x] Verify invalid or missing required fields fail contract validation: `python -m pytest tests/test_json_contracts.py`.
+- [x] Cover query, recommendations, summary, session, doctor, pricing-coverage, dashboard, export, support-bundle, and plugin lifecycle JSON payload contracts: `python -m pytest tests/test_json_contracts.py`.
+
+## 6. CSV Export Stability
+
+- [x] Verify expected CSV columns for aggregate exports: `python -m pytest tests/test_cli_lifecycle.py`.
+- [x] Verify redacted and strict privacy CSV exports omit private metadata: `python -m pytest tests/test_privacy.py`.
+- [x] Verify migration fixtures still export the expected CSV shape: `python -m pytest tests/test_store_migrations.py`.
+
+## 7. Config File Stability
+
+- [x] Verify pricing config initialization and parsing: `python -m pytest tests/test_pricing.py`.
+- [x] Verify allowance and rate-card config initialization and parsing: `python -m pytest tests/test_allowance.py`.
+- [x] Verify threshold config initialization and parsing: `python -m pytest tests/test_recommendations.py`.
+- [x] Verify project alias/tag config initialization and parsing: `python -m pytest tests/test_projects.py`.
+- [x] Document config schema changes before release: manual review of `docs/pricing-and-credits.md`, `docs/dashboard-guide.md`, and `docs/cli-reference.md`; enforced by `python -m pytest tests/test_cli_release.py`.
+
+## 8. Dashboard Behavior
+
+- [x] Verify dashboard aggregate payload remains raw-context-free: `python -m pytest tests/test_store_dashboard_mcp.py`.
+- [x] Verify dashboard URL state round trips: `python -m pytest tests/test_dashboard_state.py`.
+- [x] Verify dashboard formatting helpers: `node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_format.js`.
+- [x] Verify dashboard data helpers: `node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_data.js`.
+- [x] Verify active-history and all-history state labels: `python -m pytest tests/test_cli_release.py tests/test_store_dashboard_mcp.py`.
+- [x] Run a manual localhost dashboard smoke before release with temporary aggregate-only paths: `codex-usage-tracker serve-dashboard --open` plus `curl -fsS http://127.0.0.1:8897/dashboard.html`.
+
+## 9. Privacy And Sharing Safety
+
+- [x] Verify dashboard payloads in normal, redacted, and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify query JSON in normal, redacted, and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify session JSON in normal, redacted, and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify CSV export in redacted and strict modes: `python -m pytest tests/test_privacy.py`.
+- [x] Verify strict mode does not leak raw cwd, source paths, branch, remote labels, project tags, or synthetic private project names: `python -m pytest tests/test_privacy.py`.
+- [x] Verify raw context fields never appear in SQLite, CSV, dashboard payloads, support bundles, generated static HTML, docs, or screenshots: `python -m pytest tests/test_privacy.py scripts/check_release.py`.
+
+## 10. Support-Bundle Safety
+
+- [x] Verify support bundles include package version, Python version, OS/platform, doctor status, schema state, parser diagnostics, pricing status, allowance status, threshold status, project config status, and privacy metadata: `python -m pytest tests/test_support.py`.
+- [x] Verify support bundles exclude raw logs, prompt text, assistant text, tool output, context text, and raw source paths in strict mode: `python -m pytest tests/test_support.py`.
+- [x] Update issue templates to request only strict-mode support bundles: `python scripts/check_release.py`.
+
+## 11. Large-History Performance
+
+- [x] Run synthetic 10k benchmark: `python scripts/benchmark_synthetic_history.py --rows 10000 --json --enforce-thresholds`.
+- [x] Run synthetic 100k benchmark: `python scripts/benchmark_synthetic_history.py --rows 100000 --json --enforce-thresholds`.
+- [x] Run synthetic 500k benchmark as a release gate when practical: `python scripts/benchmark_synthetic_history.py --rows 500000 --json --enforce-thresholds`.
+- [x] Define thresholds for active-only dashboard query, all-history dashboard query, since/until, model/effort, min_tokens, recommendations, pricing coverage, and project summary.
+- [x] Add a smaller CI-safe benchmark if it can stay fast and deterministic.
+
+## 12. Release Process
+
+- [x] Verify publish workflow publishes `codex-usage-tracking`, not `codex-usage-tracker`: `python scripts/check_release.py`.
+- [x] Verify publish workflow uses Trusted Publishing, not API tokens: `python scripts/check_release.py`.
+- [x] Verify TestPyPI and PyPI jobs exist and publish only on workflow dispatch or release events: `python scripts/check_release.py`.
+- [x] Verify manual PyPI workflow dispatch is restricted to `main` or tag refs: `python scripts/check_release.py`.
+- [x] Verify PyPI job is gated by environment `pypi`: `gh api repos/douglasmonsky/codex-usage-tracker/environments/pypi`.
+- [x] Verify dist filenames match `codex_usage_tracking`: `python -m build && python scripts/check_release.py --dist`.
+- [ ] Verify TestPyPI process: run `Publish Python package` with `target=testpypi` only when intentionally testing release publication.
+- [ ] Verify PyPI process: publish a GitHub Release or run workflow dispatch with `target=pypi` only when intentionally publishing a reviewed release.
+- [x] Document release recovery by cutting a new patch version when an uploaded artifact is wrong: see `docs/development.md`.
+
+## 13. Known Limitations
+
+- [x] Document that Codex upstream log formats can change and parser compatibility may require updates.
+- [x] Document that pricing and rate-card sources can change outside this project.
+- [x] Document that live account allowance cannot be read automatically by this local tracker.
+- [x] Document that cost and credit estimates are not guaranteed to match exact billing.
+- [x] Document platform/plugin discovery limitations separately from the core Python CLI/dashboard support.
+
+## Evidence References
+
+These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.4.1`; 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.4.1`.
+- 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
+
+- Legacy SQLite migration, schema state, migration idempotence, malformed legacy schema handling, and migration CSV shape are proven by `tests/test_store_migrations.py`.
+- The v0.3 fixture decision is covered by `tests/test_store_migrations.py`; no additional v0.3-specific fixture is currently required because the active pre-1.0 migration path is already represented by the legacy fixture.
+- `rebuild-index` clearing only tracker-owned aggregate rows is proven by `tests/test_store_dashboard_mcp.py::test_rebuild_index_clears_aggregate_rows_before_rescan`.
+- `reset-db` preserving raw Codex logs is proven by `tests/test_cli_lifecycle.py::test_setup_support_bundle_and_reset_db_cli`.
+- Refresh metadata and parser diagnostics are proven by `tests/test_store_migrations.py`, `tests/test_parser.py`, and `tests/test_store_dashboard_mcp.py::test_refresh_reports_skipped_corrupt_token_events`.
+
+### CLI Compatibility
+
+- Documented CLI command existence and stable command coverage are proven by `tests/test_cli_release.py::test_cli_reference_documents_only_existing_stable_commands` and `tests/test_cli_release.py::test_stable_cli_commands_are_not_removed_without_a_deprecation_plan`.
+- Installed-wheel subcommand help coverage is proven by `scripts/smoke_installed_package.py` and guarded by `tests/test_cli_release.py::test_installed_package_smoke_checks_help_for_stable_commands`.
+- Lifecycle actionable errors without real logs are proven by `tests/test_cli_lifecycle.py::test_lifecycle_commands_return_actionable_errors_without_real_logs`.
+
+### MCP Compatibility
+
+- MCP tool documentation parity is proven by `tests/test_cli_release.py::test_mcp_tool_names_remain_documented`.
+- MCP JSON response schema IDs and wrapper payload contracts are proven by `tests/test_store_dashboard_mcp.py::test_mcp_wrappers_smoke`.
+- Companion skill source/package parity is proven by `scripts/check_release.py`.
+- Installed-wheel plugin MCP config is proven by `scripts/smoke_installed_package.py`.
+
+### JSON Contract Stability
+
+- Documented schema table parity, runtime schema ID tracking, example validation, invalid-payload rejection, and minimal payload validation are proven by `tests/test_json_contracts.py`.
+- README and CLI schema doc references are additionally guarded by `tests/test_cli_release.py::test_cli_json_schema_doc_lists_tracked_contracts`.
+
+### CSV Export Stability
+
+- Aggregate CSV columns are proven by `tests/test_cli_lifecycle.py::test_report_json_and_query_cli`.
+- Redacted and strict privacy CSV behavior is proven by `tests/test_privacy.py::test_privacy_modes_cover_dashboard_query_session_and_csv` and `tests/test_privacy.py::test_aggregate_outputs_exclude_raw_transcript_content`.
+- Migration CSV shape is proven by `tests/test_store_migrations.py::test_csv_export_keeps_current_columns_after_legacy_migration`.
+
+### Config File Stability
+
+- Pricing config initialization and parsing are proven by `tests/test_pricing.py` and `tests/test_cli_lifecycle.py::test_rate_card_allowance_and_pricing_snapshot_cli`.
+- Allowance and Codex rate-card config initialization/parsing are proven by `tests/test_allowance.py` and `tests/test_cli_lifecycle.py::test_rate_card_allowance_and_pricing_snapshot_cli`.
+- Threshold config initialization/parsing is proven by `tests/test_recommendations.py::test_threshold_template_and_overrides`.
+- Project alias, ignored-path, tag, and privacy behavior is proven by `tests/test_projects.py`.
+- Config schema documentation coverage is proven by `tests/test_cli_release.py::test_local_config_schema_docs_reference_stable_fields`.
+
+### Dashboard Behavior
+
+- Aggregate-only dashboard payloads and CSV are proven by `tests/test_store_dashboard_mcp.py::test_dashboard_and_csv_are_aggregate_only` and `tests/test_privacy.py::test_aggregate_outputs_exclude_raw_transcript_content`.
+- URL-state round trips are proven by `tests/test_dashboard_state.py::test_dashboard_url_state_round_trips`.
+- Dashboard helper syntax is proven by the `node --check` commands in section 8 and the CI dashboard JavaScript syntax job.
+- Active/all-history payload behavior is proven by `tests/test_store_dashboard_mcp.py::test_dashboard_history_scope_excludes_archived_rows_by_default` and `tests/test_store_dashboard_mcp.py::test_dashboard_server_usage_api_switches_history_scope`.
+- Active/all-history user-facing labels are proven by `tests/test_cli_release.py::test_dashboard_history_scope_labels_remain_user_facing`.
+- No-context startup and runtime context enablement are proven by `tests/test_store_dashboard_mcp.py::test_dashboard_server_can_enable_context_api_at_runtime` and `tests/test_privacy.py::test_context_server_requires_loopback_origin_token_and_enablement`.
+- Manual localhost smoke is proven by running `codex-usage-tracker serve-dashboard --open` against temporary database, config, output, and Codex-home paths on `127.0.0.1:8897`, then probing `/dashboard.html` with `curl -fsS`.
+
+### Privacy And Sharing Safety
+
+- Dashboard, query, session, CSV, support-bundle, and generated-static-HTML privacy behavior is proven by `tests/test_privacy.py`.
+- Strict project metadata redaction is proven by `tests/test_privacy.py::test_privacy_modes_cover_dashboard_query_session_and_csv` and `tests/test_projects.py::test_project_privacy_modes_redact_sensitive_metadata`.
+- Raw context exclusion and explicit context loading are proven by `tests/test_privacy.py::test_context_loading_is_explicit_redacted_and_not_static_html`, `tests/test_privacy.py::test_context_server_requires_loopback_origin_token_and_enablement`, and `tests/test_store_dashboard_mcp.py::test_context_loads_raw_log_only_on_demand`.
+- Tracked-file secret scanning is proven by `scripts/check_release.py`.
+
+### Support-Bundle Safety
+
+- Support-bundle payload shape and secret safety are proven by `tests/test_support.py::test_support_bundle_default_mode_contract_and_secret_safety`.
+- Strict support-bundle path and doctor-text redaction is proven by `tests/test_support.py::test_support_bundle_strict_mode_redacts_local_paths_and_doctor_text`.
+- Safe issue-template requests are proven by `scripts/check_release.py`.
+
+### Large-History Performance
+
+- Benchmark command behavior and threshold contract are smoke-tested by `tests/test_cli_release.py::test_synthetic_history_benchmark_script_smoke`.
+- Release-size 10k, 100k, and 500k benchmark claims are proven by running `python scripts/benchmark_synthetic_history.py --rows 10000 100000 500000 --json --enforce-thresholds` before release work when practical.
+- CI-safe benchmark coverage is proven by the CI `Release readiness` job through `tests/test_cli_release.py::test_synthetic_history_benchmark_script_smoke`.
+
+### Release Process
+
+- Normal CI package build plus `twine check` and dist verification are proven by `.github/workflows/ci.yml` and enforced by `scripts/check_release.py::_check_ci_workflow`.
+- 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`.
+- Release recovery documentation is proven by `scripts/check_release.py` required-file and docs checks.
+
+### Known Limitations
+
+- Parser-format drift, pricing/rate-card drift, live allowance, non-billing-equivalence, and plugin-discovery boundary documentation are proven by `tests/test_cli_release.py::test_known_limitations_are_documented`.

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/docs/pricing-and-credits.md

@@ -83,8 +83,11 @@ Configure the usage component:
 
 ## Accuracy Notes
 
+- 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.
-- The dashboard does not infer live remaining allowance from the logged-in account plan.
+- 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.
 - Pricing can change after a report is generated. Use `pin-pricing` when you need reproducible historical cost estimates.
 - Rows with direct model/rate-card matches are more trustworthy than inferred aliases or local overrides.
 - Cost and credit calculations use aggregate counters; the tracker does not re-tokenize prompts or reconstruct usage from raw text.
+- Cost and credit estimates are not guaranteed to match exact billing.

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.4.0"
+version = "0.4.1"
 description = "Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns."
 readme = "README.md"
 requires-python = ">=3.10"

{codex_usage_tracking-0.4.0 → codex_usage_tracking-0.4.1}/scripts/check_release.py

@@ -110,6 +110,7 @@ def main() -> int:
     failures.extend(_check_required_files())
     failures.extend(_check_versions())
     failures.extend(_check_docs())
+    failures.extend(_check_issue_templates())
     failures.extend(_check_packaging_metadata())
     failures.extend(_check_tracked_files_for_secrets())
     if args.dist:
@@ -173,6 +174,37 @@ def _check_docs() -> list[str]:
     return failures
 
 
+def _check_issue_templates() -> list[str]:
+    failures: list[str] = []
+    templates = {
+        "bug_report.yml": [
+            "Do not paste real Codex logs",
+            "strict support bundle",
+            "--privacy-mode strict support-bundle",
+        ],
+        "parser_log_compatibility.yml": [
+            "Do not attach or paste raw Codex JSONL logs",
+            "Synthetic log shape",
+        ],
+        "pricing_or_allowance.yml": [
+            "Do not paste account screenshots with private details",
+            "--privacy-mode strict pricing-coverage --json",
+        ],
+    }
+    for filename, required_texts in templates.items():
+        path = REPO_ROOT / ".github" / "ISSUE_TEMPLATE" / filename
+        if not path.exists():
+            failures.append(f"missing issue template: {path.relative_to(REPO_ROOT)}")
+            continue
+        text = path.read_text(encoding="utf-8")
+        for required in required_texts:
+            if required not in text:
+                failures.append(
+                    f"{path.relative_to(REPO_ROOT)} is missing safe-reporting text: {required}"
+                )
+    return failures
+
+
 def _check_packaging_metadata() -> list[str]:
     sys.path.insert(0, str(REPO_ROOT / "src"))
     from codex_usage_tracker.plugin_installer import plugin_manifest
@@ -231,6 +263,7 @@ def _check_packaging_metadata() -> list[str]:
     if "PACKAGE_SPEC_MARKER" not in launcher:
         failures.append("MCP runtime launcher should invalidate cached runtimes when package spec changes")
     failures.extend(_check_python_support_metadata(project))
+    failures.extend(_check_ci_workflow())
     failures.extend(_check_publish_workflow())
     return failures
 
@@ -279,6 +312,14 @@ def _check_publish_workflow() -> list[str]:
         "id-token: write",
         "repository-url: https://test.pypi.org/legacy/",
         "python -m twine check dist/*",
+        "if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'",
+        "if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')",
+        "echo \"ref=$GITHUB_REF\"",
+        "echo \"sha=$GITHUB_SHA\"",
+        "refs/heads/main|refs/tags/*",
+        "Manual PyPI publishing must run from main or a tag ref.",
+        "name: testpypi",
+        "name: pypi",
         "https://test.pypi.org/project/codex-usage-tracking/",
         "https://pypi.org/project/codex-usage-tracking/",
     ]:
@@ -290,6 +331,65 @@ def _check_publish_workflow() -> list[str]:
         failures.append("publish workflow must not publish on pull requests")
     if "secrets." in workflow or "api-token" in workflow or "password:" in workflow:
         failures.append("publish workflow must not use token secrets or password-based publishing")
+    for job_name in ["publish-testpypi", "publish-pypi"]:
+        job_block = _workflow_job_block(workflow, job_name)
+        if job_block is None:
+            failures.append(f"publish workflow is missing job: {job_name}")
+            continue
+        for required in [
+            "Verify PyPI publish ref",
+            "echo \"event=$GITHUB_EVENT_NAME\"",
+            "echo \"ref=$GITHUB_REF\"",
+            "echo \"sha=$GITHUB_SHA\"",
+            "refs/heads/main|refs/tags/*",
+            "Manual PyPI publishing must run from main or a tag ref.",
+        ]:
+            if required not in job_block:
+                failures.append(f"publish workflow {job_name} job is missing preflight: {required}")
+    return failures
+
+
+def _workflow_job_block(workflow: str, job_name: str) -> str | None:
+    match = re.search(
+        rf"(?ms)^  {re.escape(job_name)}:\n(?P<body>.*?)(?=^  [A-Za-z0-9_-]+:\n|\Z)",
+        workflow,
+    )
+    if not match:
+        return None
+    return match.group("body")
+
+
+def _check_ci_workflow() -> list[str]:
+    workflow_path = REPO_ROOT / ".github" / "workflows" / "ci.yml"
+    if not workflow_path.exists():
+        return ["missing CI workflow: .github/workflows/ci.yml"]
+    workflow = workflow_path.read_text(encoding="utf-8")
+    failures: list[str] = []
+    for required in [
+        "name: Build package",
+        "python -m build",
+        "python -m twine check dist/*",
+        "python scripts/check_release.py --dist",
+    ]:
+        if required not in workflow:
+            failures.append(f"CI package job is missing required build check: {required}")
+    return failures
+
+
+def _check_ci_workflow() -> list[str]:
+    workflow_path = REPO_ROOT / ".github" / "workflows" / "ci.yml"
+    if not workflow_path.exists():
+        return ["missing CI workflow: .github/workflows/ci.yml"]
+    workflow = workflow_path.read_text(encoding="utf-8")
+    failures: list[str] = []
+    for required in [
+        "name: Build package",
+        "python -m build",
+        "python -m twine check dist/*",
+        "python scripts/check_release.py --dist",
+    ]:
+        if required not in workflow:
+            failures.append(f"CI package job is missing required build check: {required}")
     return failures