codex-usage-tracking 0.15.1__tar.gz → 0.17.0__tar.gz

{codex_usage_tracking-0.15.1 → codex_usage_tracking-0.17.0}/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.15.1",
-  "description": "Unofficial local tracker for aggregate Codex token usage from local session logs.",
+  "version": "0.17.0",
+  "description": "Unofficial local Codex usage dashboard and MCP diagnostics from local session logs.",
   "author": {
     "name": "Douglas Monsky"
   },
@@ -19,8 +19,8 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Codex Usage Tracker",
-    "shortDescription": "Unofficial local aggregate token usage analytics for Codex",
-    "longDescription": "Unofficial independent project, not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. Reads local Codex session logs, aggregates exact token usage counters, and generates summaries, CSV exports, and a hoverable dashboard with optional localhost-only raw context loading.",
+    "shortDescription": "Local Codex usage dashboard, MCP diagnostics, and token-waste investigations",
+    "longDescription": "Unofficial independent project, not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. Reads local Codex session logs to power a local dashboard, MCP tools, allowance diagnostics, token-waste investigations, and shareable aggregate reports without uploading logs.",
     "developerName": "Douglas Monsky",
     "category": "Productivity",
     "capabilities": [
@@ -33,8 +33,9 @@
     "termsOfServiceURL": "https://github.com/douglasmonsky/codex-usage-tracker",
     "defaultPrompt": [
       "Open dashboard",
-      "Heaviest thread?",
-      "Thread leaderboard"
+      "Look through my usage for token waste",
+      "Suggest usage investigations",
+      "Check whether my weekly allowance changed"
     ],
     "brandColor": "#2563EB",
     "composerIcon": "./assets/icon.svg",

{codex_usage_tracking-0.15.1 → codex_usage_tracking-0.17.0}/AGENTS.md

@@ -242,9 +242,9 @@ git push origin v0.4.0
 ## Privacy Rules
 
 - Never commit real Codex session logs.
-- Never store raw prompts, assistant text, tool outputs, pasted secrets, or message snippets.
-- Raw context may be read only on demand from original local JSONL files; never persist it to SQLite, CSV, generated HTML, fixtures based on real logs, or commits.
-- Store only selected aggregate session metadata for subagents, including parent thread labels; do not persist raw session instructions or source JSON.
+- Never commit real prompts, assistant text, tool outputs, pasted secrets, message snippets, or raw Codex logs.
+- The local content index may store bounded snippets in the user-owned SQLite database by approved design. Do not expose indexed/raw content through default CSV, generated HTML, support bundles, screenshots, aggregate JSON, fixtures based on real logs, or commits.
+- Raw context may be read during refresh/content indexing or explicit selected-call context loading. Keep shareable outputs aggregate-first unless a command is explicitly documented as a local raw/content export.
 - Keep fixture data synthetic.
 - Keep local SQLite databases, CSV exports, HTML dashboards, caches, and virtualenvs out of git.
 - Do not hard-code real current USD model pricing in source; refresh the local config from OpenAI's published pricing docs or use manual local overrides. Internal Codex model estimates must be explicitly marked as estimates with source and rationale metadata.
@@ -252,10 +252,10 @@ git push origin v0.4.0
 
 ## Definition Of Done
 
-- Parser handles synthetic session logs without reading raw message content.
+- Parser and content-index handling are covered by synthetic session logs.
 - SQLite refresh is idempotent.
-- MCP tool functions return concise aggregate data.
-- Dashboard is generated from aggregate-only JSON.
+- MCP tool functions return concise aggregate data by default; content-aware tools must be explicit local investigation surfaces.
+- Dashboard generated HTML is aggregate-first and does not embed indexed/raw content.
 - Doctor, summary presets, dashboard, and expensive-call views work from CLI and MCP wrappers.
 - `codex-usage-tracker install-plugin` can register the installed package without relying on a source-checkout symlink.
 - `python -m codex_usage_tracker` and `codex-usage-tracker --version` both work.
@@ -263,8 +263,8 @@ git push origin v0.4.0
 - `scripts/check_release.py --dist` passes before any public release.
 - Pricing coverage clearly separates configured, estimated, and unpriced model usage.
 - Codex credit coverage clearly separates exact rate-card matches, inferred aliases, and missing credit rates.
-- Dashboard Calls and Threads views share filters, totals, and aggregate-only hover details.
+- Dashboard Calls and Threads views share filters, totals, and aggregate-first hover details.
 - Dashboard usage docs are updated when the visible dashboard workflow changes, and screenshots must be generated from synthetic data only.
-- Dashboard aggregate refresh is localhost-only and keeps generated HTML aggregate-only; context loading is lazy, localhost-only, explicit, redacted, and not embedded in the static HTML payload.
+- Dashboard refresh is localhost-only, generated HTML stays aggregate-first, and context loading is lazy, localhost-only, explicit, redacted, and not embedded in the static HTML payload.
 - Subagent calls preserve logged parent-session metadata, latch to parent thread labels when available, and auto-review attachment is clearly marked when inferred.
 - Tests and compile checks pass.

{codex_usage_tracking-0.15.1 → codex_usage_tracking-0.17.0}/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 0.17.0 - 2026-07-08
+
+- Add agentic MCP investigation tools for hypothesis-driven usage diagnostics, compact evidence briefs, and actionable recommendation reports.
+- Add repeated file rediscovery, shell churn, and large low-output usage diagnostics to identify avoidable local workflow waste.
+- Improve bundled skill guidance so Codex can route vague usage questions into concrete tracker endpoints, Headroom suggestions, and custom remediation ideas.
+- Add async dogfood progress polling and warm result caching so longer usage investigations can report progress and rerun faster.
+- Speed up content indexing with incremental append metadata, parallel source parsing, and batched FTS rebuilds.
+- Add dashboard refresh progress bars, no-cap paged loading, loaded-call metrics, token breakdowns, persisted loading preferences, and restored usage-drain chart data.
+
+## 0.16.2 - 2026-07-08
+
+- Restore Usage Drain, Investigator Workbench, Reports, and related dashboard charts by deriving shared usage-drain series from loaded aggregate rows again.
+- Keep sparse line charts expanded to their panel width so low-point datasets do not collapse into the left edge.
+
+## 0.16.1 - 2026-07-08
+
+- Add async refresh progress polling and dashboard progress bars for long all-row loads.
+- Speed up local content index refreshes with batched writes and parallel source extraction.
+- Load uncapped dashboard rows in finite pages so no-cap mode stays responsive on large histories.
+- Show loaded-call counts and call-level token breakdowns on Overview metric cards.
+- Restore session row/history loading preferences after browser refresh without storing large row payloads.
+
+## 0.16.0 - 2026-07-07
+
+- Add allowance intelligence foundation with normalized allowance history, evidence-graded change diagnostics, local evidence exports, and API/MCP report surfaces for weekly-vs-5-hour usage analysis.
+- Add local content-indexed MCP/API exploration surfaces, including content search, thread trace, pattern scans, investigation walks, and strict local evidence exports.
+- Add roadmap for default local content indexing, SQLite FTS5 search, parser drift handling, and future diagnostics for repeated file rediscovery, shell churn, and large low-output calls.
+- Fix schema initialization so already-applied migrations are not rerun during read/report calls on migrated local databases.
+
 ## 0.15.1 - 2026-07-05
 
 - Fix the PyPI wheel package resources by tracking the React dashboard `index.html` entrypoint used by `serve-dashboard` and installed-package smoke tests.

{codex_usage_tracking-0.15.1 → codex_usage_tracking-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.15.1
+Version: 0.17.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -44,7 +44,7 @@ Requires-Dist: zizmor>=1.26.1; python_version >= "3.11" and extra == "dev"
 Dynamic: license-file
 
 <p align="center">
- <img src="docs/assets/readme-hero.png?v=readme-hero-20260704" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
+ <img src="docs/assets/readme-hero-2.png?v=readme-hero-20260708" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
 </p>
 
 # Codex Usage Tracker
@@ -59,11 +59,11 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 > **Unofficial project:** Codex Usage Tracker is an independent open-source project. It is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI; this project only reads local log files from your machine.
 
-Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
+Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters plus local content/tool/command/file-event evidence into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. The content index stays on your machine; CSV exports, generated dashboard HTML, support bundles, and shareable reports omit indexed content by default. Use `refresh --aggregate-only` or `rebuild-index --aggregate-only` when you want the older aggregate-only SQLite posture.
 
 Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/), and it installs the `codex-usage-tracker` command.
 
-After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
+After install, you get a localhost dashboard, a local SQLite usage index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
 
 ## Quick Install
 
@@ -90,13 +90,13 @@ Source install for development or branch testing:
 pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 ```
 
-`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
+`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the local usage index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
 
 Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard.`
 
 ## Talk To Your Usage Data
 
-The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local aggregate index, call MCP tools, and explain what is driving usage without exposing prompts or tool output.
+The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local usage index, call MCP tools, and explain what is driving usage. Shareable reports stay aggregate-first and omit indexed content unless an explicit local content tool/export is added for that purpose.
 
 Good starter prompts:
 
@@ -108,7 +108,7 @@ Compare model and effort usage, then suggest safer defaults.
 Open the dashboard and filter Calls to the rows behind your recommendation.
 ```
 
-The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
+The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Allowance Intelligence, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
 
 Example conversation docs:
 
@@ -307,6 +307,7 @@ Full model: [Privacy Guide](docs/privacy.md).
 - [Dashboard Guide](docs/dashboard-guide.md)
 - [CLI Reference](docs/cli-reference.md)
 - [Pricing, Credits, And Allowance](docs/pricing-and-credits.md)
+- [Allowance Intelligence](docs/allowance-intelligence.md)
 - [MCP And Codex Skills](docs/mcp.md)
 - [Privacy Guide](docs/privacy.md)
 - [Architecture](docs/architecture.md)

{codex_usage_tracking-0.15.1 → codex_usage_tracking-0.17.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
- <img src="docs/assets/readme-hero.png?v=readme-hero-20260704" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
+ <img src="docs/assets/readme-hero-2.png?v=readme-hero-20260708" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
 </p>
 
 # Codex Usage Tracker
@@ -14,11 +14,11 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 > **Unofficial project:** Codex Usage Tracker is an independent open-source project. It is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI; this project only reads local log files from your machine.
 
-Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
+Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters plus local content/tool/command/file-event evidence into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. The content index stays on your machine; CSV exports, generated dashboard HTML, support bundles, and shareable reports omit indexed content by default. Use `refresh --aggregate-only` or `rebuild-index --aggregate-only` when you want the older aggregate-only SQLite posture.
 
 Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/), and it installs the `codex-usage-tracker` command.
 
-After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
+After install, you get a localhost dashboard, a local SQLite usage index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
 
 ## Quick Install
 
@@ -45,13 +45,13 @@ Source install for development or branch testing:
 pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 ```
 
-`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
+`setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the local usage index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
 
 Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard.`
 
 ## Talk To Your Usage Data
 
-The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local aggregate index, call MCP tools, and explain what is driving usage without exposing prompts or tool output.
+The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local usage index, call MCP tools, and explain what is driving usage. Shareable reports stay aggregate-first and omit indexed content unless an explicit local content tool/export is added for that purpose.
 
 Good starter prompts:
 
@@ -63,7 +63,7 @@ Compare model and effort usage, then suggest safer defaults.
 Open the dashboard and filter Calls to the rows behind your recommendation.
 ```
 
-The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
+The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Allowance Intelligence, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
 
 Example conversation docs:
 
@@ -262,6 +262,7 @@ Full model: [Privacy Guide](docs/privacy.md).
 - [Dashboard Guide](docs/dashboard-guide.md)
 - [CLI Reference](docs/cli-reference.md)
 - [Pricing, Credits, And Allowance](docs/pricing-and-credits.md)
+- [Allowance Intelligence](docs/allowance-intelligence.md)
 - [MCP And Codex Skills](docs/mcp.md)
 - [Privacy Guide](docs/privacy.md)
 - [Architecture](docs/architecture.md)

codex_usage_tracking-0.17.0/docs/agentic-briefing-and-dogfood-roadmap.md

@@ -0,0 +1,187 @@
+# Agentic Briefing And Dogfood Roadmap
+
+This roadmap follows the agentic MCP and hypothesis-testing hardening work merged through
+PR #114. The current backend can already suggest investigations, test hypotheses, inspect
+large low-output calls, identify shell churn, rank repeated file rediscovery, and evaluate
+allowance-change evidence. This phase is about making that flow repeatable, easier for
+agents to use correctly, and more action-oriented for users.
+
+Product stance stays unchanged:
+
+- Local-first and unofficial.
+- Aggregate/shareable evidence by default.
+- No raw prompts, raw tool output, full paths, raw commands, or transcript snippets unless
+  the user explicitly asks for deeper local content inspection.
+- Dashboard UI is not the source of truth for this phase; backend/MCP payloads are.
+- Recommendation language must separate exact facts, estimates, missing access, and next
+  verification steps.
+
+## Why This Phase Exists
+
+Dogfooding the improved MCP flow surfaced two needs:
+
+- The project needs a repeatable local experiment harness so future changes can be checked
+  against the same old and new hypotheses instead of relying on ad hoc terminal snippets.
+- The bundled skill/plugin guidance should teach agents the new investigation sequence and
+  explain newer report concepts such as `unclassified_shell_script`.
+- The MCP should be able to produce a concise action brief that translates diagnostics into
+  practical workflow recommendations, including existing tools and custom helper ideas.
+
+## PR Chunk 1: Dogfood Hypothesis Harness
+
+Add a repeatable local experiment harness that runs the old and new hypothesis battery and
+emits compact local artifacts.
+
+Proposed command:
+
+```bash
+codex-usage-tracker dogfood-agentic
+```
+
+Initial behavior:
+
+- Refresh active usage by default, with `--include-archived` opt-in.
+- Run `usage_test_hypotheses` over the old hypothesis set:
+  - token waste in large low-output calls
+  - cache/cold-resume pressure
+  - repeated file rediscovery
+  - shell churn
+  - model/effort choice
+  - weekly allowance change
+- Run the new follow-up hypothesis set:
+  - large low-output calls as cleanup target
+  - repeated file rediscovery concentrated in safe file identities
+  - shell churn as repeated probing
+  - context pressure driving expensive calls
+  - local content-index/thread-trace follow-up needed for intent
+  - allowance-change claims not ready without weekly spans
+- Run direct evidence tools:
+  - `usage_large_low_output_calls`
+  - `usage_shell_churn`
+  - `usage_repeated_file_rediscovery`
+  - `usage_allowance_diagnostics`
+  - `usage_suggest_investigations`
+  - `usage_investigate` for `token_waste` and `workflow_churn`
+- Write a compact JSON summary and optional Markdown brief.
+
+Acceptance criteria:
+
+- Harness output declares scope: refresh status, archived setting, privacy mode, evidence
+  limit, and artifact paths.
+- Harness asserts privacy invariants: no indexed content, no raw fragments, no raw command
+  output, and no full paths in compact outputs.
+- Harness records expected family routing for the old and new hypotheses.
+- Harness can be run locally without publishing or contacting external services.
+- Add focused tests for summary shape and privacy flags using synthetic data.
+
+## PR Chunk 2: Skill And Plugin Guidance Refresh
+
+Update bundled skills and docs so Codex agents use the improved investigation flow.
+
+Guidance changes:
+
+- Lead broad usage questions with `usage_suggest_investigations`.
+- Use `usage_test_hypotheses` when the user frames the request as:
+  - "I'd like to be able to..."
+  - "I will accomplish this using..."
+  - "I'm missing access to..."
+  - "my hypothesis was true/false..."
+- Use direct tools after the hypothesis result:
+  - `usage_large_low_output_calls` for large low-output/context pressure.
+  - `usage_repeated_file_rediscovery` for repeated safe file identities.
+  - `usage_shell_churn` for command churn.
+  - `usage_allowance_diagnostics` and `usage_allowance_export` for limit-change claims.
+- Explain `unclassified_shell_script` plainly:
+  - It is a mixed or legacy bucket where the tracker cannot safely recover one specific
+    command root from aggregate indexed data.
+  - It is still evidence of churn, but needs thread trace or future indexed command detail
+    before prescribing a specific command-level fix.
+- Recommend existing tools and possible custom solutions when diagnosing waste:
+  - Headroom or similar context-pressure tools when available.
+  - Project notes, handoff templates, helper scripts, test selectors, file summaries, or
+    targeted commands when repeated rediscovery or shell churn appears.
+
+Acceptance criteria:
+
+- Bundled plugin skill files and source skill files stay in sync.
+- MCP docs describe the recommended investigation sequence.
+- Tests or docs snapshots prove the guidance mentions hypothesis testing, direct evidence
+  follow-up, `unclassified_shell_script`, and existing/custom remediation options.
+
+## PR Chunk 3: Actionable Recommendation Brief
+
+Add a user-facing aggregate report/MCP tool that converts diagnostics into a compact
+remediation brief.
+
+Proposed tool:
+
+```text
+usage_action_brief(...)
+```
+
+Initial inputs:
+
+- `goal`: optional, default `token_waste`
+- `since`, `until`, `thread`
+- `include_archived`
+- `evidence_limit`
+- `privacy_mode`
+
+Output shape:
+
+- `schema`
+- `content_mode`
+- `includes_indexed_content`
+- `includes_raw_fragments`
+- `privacy_mode`
+- `filters`
+- `summary`
+- `actions[]`
+  - `finding`
+  - `confidence`
+  - `evidence`
+  - `likely_waste_pattern`
+  - `recommended_workflow_change`
+  - `recommended_existing_tool`
+  - `recommended_custom_solution`
+  - `how_to_verify`
+  - `recommended_next_tools`
+- `caveats`
+
+Initial action families:
+
+- Large low-output/context pressure:
+  - recommend shorter handoffs, fresh thread with summary, context-pressure tooling, and
+    direct verification with `usage_large_low_output_calls` and `usage_call_detail`.
+- Repeated file rediscovery:
+  - recommend durable file summaries, project notes, helper commands, and narrower reads.
+- Shell churn:
+  - recommend stopping repeated retry loops, summarizing failures, using test selectors or
+    helper scripts, and inspecting thread traces.
+- Allowance-change readiness:
+  - recommend weekly diagnostics/export only when evidence is ready; otherwise explain why
+    public claims are premature.
+
+Acceptance criteria:
+
+- New schema is documented in CLI JSON schema docs and MCP docs.
+- MCP tool and CLI JSON path return the same payload builder.
+- Payload remains aggregate/shareable by default.
+- Tests cover at least one action from each initial action family using synthetic fixtures.
+- Dogfood harness can optionally include the action brief.
+
+## Phase Exit Criteria
+
+This phase is complete when:
+
+- The dogfood harness can be run before future MCP changes.
+- The bundled skill/plugin teaches agents the intended investigation flow.
+- The action brief can turn evidence into concrete user-facing remediation steps.
+- Full local validation passes.
+- No dashboard UI work has been started as part of this phase.
+
+## Release Guidance
+
+- If the phase only lands the harness and docs, ship as a patch.
+- If `usage_action_brief` becomes a new public MCP/API surface, ship as the next minor
+  release, likely `0.17.0`.

codex_usage_tracking-0.17.0/docs/agentic-investigation-hardening-roadmap.md

@@ -0,0 +1,159 @@
+# Agentic Investigation Hardening Roadmap
+
+This roadmap follows the exploratory MCP experiments run on 2026-07-08. The goal is to make Codex Usage Tracker useful as an agent-facing investigation partner, not just a dashboard data source.
+
+Product stance stays unchanged:
+
+- Local-first and unofficial.
+- Aggregate/shareable evidence first.
+- Explicit local content-index tools only when the user asks for deeper local diagnosis.
+- No raw context by default.
+- Recommendations must name evidence, missing evidence, confidence, and next verification step.
+
+## Experiment Findings
+
+The agentic layer already identifies meaningful waste patterns:
+
+- Large low-output calls are real and actionable.
+- High context pressure dominates recent usage.
+- Repeated file rediscovery is measurable and severe.
+- Shell churn exists, but command labels are too cloudy.
+- Allowance-change evidence is currently insufficient, which is the correct conservative result.
+
+The rough edges are agent-facing rather than purely analytical:
+
+- `usage_suggest_investigations(goal=...)` returns too few ideas for broad discovery.
+- `usage_investigate(...)` returns large nested payloads that are hard for agents to consume.
+- There is no first-class hypothesis-testing endpoint matching the preferred user framing.
+- Shell churn command labels collapse too often into `unknown_command`.
+- Local evidence export can report confusing aggregate fields for some branches.
+- Some filters and archived-row behavior need targeted regression tests.
+
+## Target Interaction Shape
+
+When a user asks for exploratory analysis, the agent should answer in this shape:
+
+```text
+I'd like to be able to ...
+I will accomplish this using ...
+I'm missing access to ...
+My hypothesis was true/false/partially true because ...
+Next action ...
+```
+
+The MCP should make that easy by returning this structure directly, with compact evidence and explicit caveats.
+
+## PR Chunk 1: Suggestions And Compact Investigation Payloads
+
+Improve existing entry points before adding new tools.
+
+Changes:
+
+- Expand `usage_suggest_investigations(...)` so broad goals can return multiple useful suggestions instead of one sparse row.
+- Add a compact mode or bounded evidence shape for `usage_investigate(...)` that avoids dumping full dashboard rows unless explicitly requested.
+- Preserve current schema compatibility by adding fields rather than removing stable fields.
+- Add tests proving broad suggestions include token waste, cache failure, workflow churn, allowance change, and overview.
+- Add tests proving compact investigation payloads include enough fields for actionability: finding, evidence summary, confidence, missing access, next tools.
+
+Acceptance criteria:
+
+- A user asking "what should I investigate?" receives a menu, not a single option.
+- A user asking "look through usage for token waste" receives concise findings that an agent can summarize without parsing massive nested rows.
+- Existing MCP contract tests remain green.
+
+## PR Chunk 2: Hypothesis Runner MCP/API Surface
+
+Add a first-class hypothesis-testing tool.
+
+Proposed tool:
+
+- `usage_test_hypotheses(...)`
+
+Initial inputs:
+
+- `question`
+- optional `hypotheses`
+- `since`, `until`, `thread`, `include_archived`
+- `evidence_limit`
+- `privacy_mode`
+
+Output shape:
+
+- `schema`
+- `content_mode`
+- `includes_indexed_content`
+- `includes_raw_fragments`
+- `question`
+- `hypotheses[]`
+  - `id`
+  - `hypothesis`
+  - `status`: `true`, `false`, `partially_true`, `insufficient_evidence`
+  - `confidence`
+  - `i_would_like_to_be_able_to`
+  - `i_will_accomplish_this_using`
+  - `i_am_missing_access_to`
+  - `evidence_summary`
+  - `counter_evidence`
+  - `next_action`
+  - `recommended_next_tools`
+
+Initial built-in hypothesis families:
+
+- token waste
+- cache/cold-resume failure
+- repeated file rediscovery
+- shell churn
+- effort/model choice
+- allowance change
+
+Acceptance criteria:
+
+- The tool can evaluate supplied hypotheses and default hypotheses.
+- It returns explicit true/false/partial/insufficient decisions.
+- It does not require raw context.
+- It recommends lower-level MCP tools when evidence is insufficient.
+
+## PR Chunk 3: Evidence Quality Hardening
+
+Fix the diagnostic surfaces that made recommendations cloudy.
+
+Changes:
+
+- Improve shell command normalization so common command families do not collapse into `unknown_command`.
+- Add tests for repeated `sed`, `rg`, `git`, `nl`, `npm`, `python`, `pytest`, and package-manager commands.
+- Tighten `usage_local_evidence_export(...)` aggregate summaries so `occurrences`, `call_count`, and `total_tokens` are meaningful for every branch.
+- Add regression tests for `include_archived=false` across the new agentic, low-output, shell, file, export, and hypothesis surfaces.
+- Make repeated file rediscovery recommendations more specific when safe fields are available: basename, extension, operation mix, adjacent retouch count, and trace handles.
+
+Acceptance criteria:
+
+- Shell churn reports are readable without raw command output.
+- Shareable local evidence export does not show confusing zero counts for supported branches.
+- Active-only filters do not surface archived rows in evidence samples.
+
+## Later Dashboard Work
+
+Do not start with UI. Once the APIs are stable:
+
+- Add a Diagnostics Notebook module for hypothesis testing.
+- Show "hypothesis true/false/partial" cards.
+- Link each card to Calls, Threads, Call Investigator, and local evidence export.
+
+## Validation Plan
+
+Each implementation PR should run:
+
+```bash
+.venv/bin/python -m ruff check .
+PYTHONPATH=src .venv/bin/python -m mypy
+PYTHONPATH=src .venv/bin/python -m pytest tests/cli/test_mcp_integration.py tests/cli/test_cli_release.py
+.venv/bin/python scripts/check_release.py
+git diff --check
+```
+
+Broader tests should be run when touching parser/indexing logic:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m pytest
+PYTHONPATH=src .venv/bin/python -m compileall src
+```