test: add aggregate schema migration coverage

Author: douglasmonsky

docs/one-dot-oh-readiness.md

@@ -29,16 +29,17 @@ Not guaranteed:
 - [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 <version>`.
 - [ ] Verify PyPI metadata names remain unchanged: `python scripts/check_release.py`.
+- [ ] Add Python 3.14 as an official support target only after CI, package classifiers, docs, and installed-package smoke coverage pass. Track this in issue #12.
 
 ## 2. Upgrade And Migration
 
-- [ ] Add synthetic v0.2-style SQLite fixture test proving `init_db` upgrades without data loss: `python -m pytest tests/test_store_migrations.py`.
+- [x] Add synthetic legacy SQLite fixture test proving `init_db` upgrades without data loss: `python -m pytest tests/test_store_migrations.py`.
 - [ ] Add synthetic v0.3-style SQLite fixture if schema drift requires it: `python -m pytest tests/test_store_migrations.py`.
-- [ ] Verify `schema_state` reports expected version and checksum after migration: `python -m pytest tests/test_store_migrations.py`.
-- [ ] Verify `rebuild-index` clears only tracker-owned aggregate tables: `python -m pytest tests/test_cli_lifecycle.py`.
-- [ ] Verify `reset-db` does not touch raw Codex logs: `python -m pytest tests/test_cli_lifecycle.py`.
-- [ ] Verify refresh metadata and parser diagnostics survive migration: `python -m pytest tests/test_store_migrations.py tests/test_parser.py`.
-- [ ] Verify CSV export columns after migration: `python -m pytest tests/test_cli_lifecycle.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
 
@@ -127,3 +128,4 @@ Not guaranteed:
 - [ ] Document that live account allowance cannot be read automatically by this local tracker.
 - [ ] Document that cost and credit estimates are not guaranteed to match exact billing.
 - [ ] Document platform/plugin discovery limitations separately from the core Python CLI/dashboard support.
+- [ ] Document that Python 3.14 may install because package metadata allows `>=3.10`, but it is not officially supported until issue #12 is complete.

src/codex_usage_tracker/diagnostics.py

@@ -20,7 +20,7 @@
     DEFAULT_PRICING_PATH,
 )
 from codex_usage_tracker.pricing import load_pricing_config
-from codex_usage_tracker.store import refresh_metadata, schema_state
+from codex_usage_tracker.store import SchemaMigrationError, refresh_metadata, schema_state
 
 PLUGIN_NAME = "codex-usage-tracker"
 
@@ -165,7 +165,15 @@ def _check_database(db_path: Path) -> DoctorCheck:
 
 
 def _check_database_schema(db_path: Path) -> DoctorCheck:
-    state = schema_state(db_path)
+    try:
+        state = schema_state(db_path)
+    except SchemaMigrationError as exc:
+        return DoctorCheck(
+            "Database schema",
+            "fail",
+            str(exc),
+            "Run: codex-usage-tracker rebuild-index after confirming your local aggregate index can be regenerated.",
+        )
     if not state["exists"]:
         return DoctorCheck(
             "Database schema",
@@ -197,7 +205,15 @@ def _check_database_schema(db_path: Path) -> DoctorCheck:
 
 
 def _check_parser_diagnostics(db_path: Path) -> DoctorCheck:
-    metadata = refresh_metadata(db_path)
+    try:
+        metadata = refresh_metadata(db_path)
+    except SchemaMigrationError as exc:
+        return DoctorCheck(
+            "Parser diagnostics",
+            "fail",
+            f"Parser diagnostics are unavailable because database migration failed: {exc}",
+            "Run: codex-usage-tracker rebuild-index after resolving the database schema warning.",
+        )
     if not metadata:
         return DoctorCheck(
             "Parser diagnostics",

src/codex_usage_tracker/store.py

@@ -42,6 +42,10 @@
 )
 
 
+class SchemaMigrationError(RuntimeError):
+    """Raised when a persisted aggregate schema cannot be repaired safely."""
+
+
 def refresh_usage_index(
     codex_home: Path = DEFAULT_CODEX_HOME,
     db_path: Path = DEFAULT_DB_PATH,
@@ -137,6 +141,7 @@ def init_db(conn: sqlite3.Connection) -> None:
     else:
         _migrate_v2(conn)
         _record_migration_if_missing(conn, 2)
+    _validate_usage_events_schema(conn)
     conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
 
 
@@ -307,6 +312,22 @@ def _ensure_columns(conn: sqlite3.Connection, columns: dict[str, str]) -> None:
                     raise
 
 
+def _validate_usage_events_schema(conn: sqlite3.Connection) -> None:
+    existing = {
+        str(row["name"])
+        for row in conn.execute("PRAGMA table_info(usage_events)").fetchall()
+    }
+    missing = [column for column in EVENT_COLUMNS if column not in existing]
+    if missing:
+        missing_text = ", ".join(missing)
+        raise SchemaMigrationError(
+            "usage_events schema is missing required columns: "
+            f"{missing_text}. Run codex-usage-tracker rebuild-index after confirming your "
+            "local aggregate index can be regenerated; raw Codex logs are not touched by "
+            "rebuild-index."
+        )
+
+
 def upsert_usage_events(
     events: Iterable[UsageEvent], db_path: Path = DEFAULT_DB_PATH
 ) -> int:

tests/test_cli_lifecycle.py

@@ -84,11 +84,13 @@ def test_setup_support_bundle_and_reset_db_cli(tmp_path: Path) -> None:
         "reset-db",
         "--yes",
     )
+    raw_log_path = next((codex_home / "sessions").glob("**/*.jsonl"))
 
     assert reset_without_confirm.returncode == 1
     assert "Re-run with --yes" in reset_without_confirm.stderr
     assert reset.returncode == 0
     assert "Raw Codex logs were not touched" in reset.stdout
+    assert "SECRET RAW PROMPT" in raw_log_path.read_text(encoding="utf-8")
 
 
 def test_rate_card_allowance_and_pricing_snapshot_cli(tmp_path: Path) -> None: