codex-usage-tracking 0.8.1__tar.gz → 0.10.0__tar.gz

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-06-21
+
+- Add Git/GitHub CLI diagnostic snapshots with safe operation labels, coarse categories, mutability buckets, and terminal token-count coverage.
+- Add file-modification diagnostic snapshots for structured patch events, modified-path aggregates, extension counts, and largest modification events without storing patch text or raw paths.
+- Add derived call timing fields for call start, duration, previous-call timestamp, and previous-call gap across dashboard rows, details, CSV/export actions, live API sorting, and thread aggregates.
+- Surface `Duration`, `Prev gap`, `Longest duration`, and `Longest gap` in the dashboard with localized labels and focused regression coverage.
+- Reconcile all diagnostics panels into one release so `overview`, `tool-output`, `commands`, `git-interactions`, `file-reads`, `file-modifications`, `read-productivity`, and `concentration` can refresh together from the live dashboard.
+
+## 0.9.0 - 2026-06-21
+
+- Add persisted aggregate diagnostic snapshots with explicit on-demand refresh metadata and schema-versioned CLI/API contracts.
+- Add dashboard Diagnostics panels for overview, tool output, commands, file reads, read productivity, and concentration.
+- Add tool-output and command reports with terminal token-count buckets, missing-count coverage, command roots, and expandable command children.
+- Add file-read and read-productivity reports with token allocation, largest read commands, read-to-modify correlation, and privacy-safe path labels.
+- Add concentration reports for top source/session, project/cwd, and day shares without leaking raw source-log paths.
+- Keep Diagnostics refresh isolated from normal live dashboard refresh so regular usage updates do not recompute or blink diagnostic panels.
+- Add Playwright diagnostics smoke coverage and release documentation for the snapshot pipeline, privacy boundary, and on-demand refresh behavior.
+
 ## 0.8.1 - 2026-06-20
 
 - Make Diagnostics fact tables easier to scan by widening and pinning the Fact column while horizontally scrolling.

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.8.1
+Version: 0.10.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -103,11 +103,15 @@ Threads view groups related calls so long chats, subagents, and auto-review pass
 
 ![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=readme-drilldown)
 
+Diagnostics surfaces on-demand snapshot reports for tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration without tying them to the normal live refresh loop.
+
+![Diagnostics view showing stored snapshot panels for tool output, commands, Git interactions, file modifications, and concentration.](docs/assets/dashboard-diagnostics.png?v=readme-drilldown)
+
 Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
 
 ![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=readme-drilldown)
 
-The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
+The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, real tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
 
 If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
 

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/README.md

@@ -65,11 +65,15 @@ Threads view groups related calls so long chats, subagents, and auto-review pass
 
 ![Threads view with one expanded thread and its calls in chronological order.](docs/assets/dashboard-threads.png?v=readme-drilldown)
 
+Diagnostics surfaces on-demand snapshot reports for tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration without tying them to the normal live refresh loop.
+
+![Diagnostics view showing stored snapshot panels for tool output, commands, Git interactions, file modifications, and concentration.](docs/assets/dashboard-diagnostics.png?v=readme-drilldown)
+
 Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
 
 ![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=readme-drilldown)
 
-The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
+The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, real tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
 
 If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
 

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/docs/architecture.md

@@ -13,7 +13,8 @@ Codex Usage Tracker is a local sidecar app. It reads aggregate token counters fr
 - `costing.py`, `pricing_config.py`, `pricing_openai.py`, `pricing_estimates.py`, and `allowance.py` own cost, credit, rate-card, and allowance annotation. Keep estimate confidence and source metadata attached to rows.
 - `projects.py`, `threads.py`, and `recommendations.py` annotate aggregate rows with project identity, thread relationships, and actionable signals. Project privacy redaction also belongs in `projects.py` so CLI, MCP, dashboard, CSV, and support-bundle surfaces share the same behavior.
 - `dashboard.py` builds aggregate-only static dashboard payloads and writes HTML/assets. `server.py` adds localhost refresh, the compatibility `/api/usage` endpoint, SQL-backed live API slices, and explicit lazy context loading.
-- `plugin_data/dashboard/dashboard_format.js` owns dashboard formatting primitives. `dashboard_data.js` owns row payload and thread relationship helpers. `dashboard_analysis.js` owns scoring, sorting, recommendation, and thread grouping logic. `dashboard_cells.js` owns reusable table/cell HTML helpers. `dashboard_details.js` owns sidebar detail and thread narrative rendering. `dashboard_insights.js` owns insight cards and investigation preset UI. `dashboard_tables.js` owns Calls, Threads, and expanded thread-call table rendering. `dashboard_diagnostics.js` owns the Diagnostics tab that consumes `/api/diagnostics/*` aggregate payloads. `dashboard_filters.js` owns date range parsing and row date matching. `dashboard_state.js` owns URL, CSV, and download state utilities. `dashboard_i18n.js`, `dashboard_payload_cache.js`, and `dashboard_tooltips.js` own localization, session aggregate cache, and fast tooltip helpers. `dashboard_call_investigator.js` owns the dedicated call drilldown surface. `dashboard.js` owns top-level DOM rendering, event handling, and API refresh orchestration.
+- `diagnostic_snapshots.py` owns persisted diagnostic snapshot refresh/load orchestration. `diagnostic_snapshot_analysis.py`, `diagnostic_snapshot_events.py`, `diagnostic_snapshot_rows.py`, and `diagnostic_snapshot_concentration.py` own source-log aggregation, safe event parsing, row shaping, and concentration math. `diagnostic_snapshot_report.py` owns CLI rendering. Keep these modules synthetic-testable and aggregate-only.
+- `plugin_data/dashboard/dashboard_format.js` owns dashboard formatting primitives. `dashboard_data.js` owns row payload and thread relationship helpers. `dashboard_analysis.js` owns scoring, sorting, recommendation, and thread grouping logic. `dashboard_cells.js` owns reusable table/cell HTML helpers. `dashboard_details.js` owns sidebar detail and thread narrative rendering. `dashboard_insights.js` owns insight cards and investigation preset UI. `dashboard_tables.js` owns Calls, Threads, and expanded thread-call table rendering. `dashboard_diagnostics.js` coordinates the Diagnostics tab data flow and events, `dashboard_diagnostics_snapshots.js` renders on-demand snapshot panels, and `dashboard_diagnostics_facts.js` renders the fact tables and drilldowns. `dashboard_filters.js` owns date range parsing and row date matching. `dashboard_state.js` owns URL, CSV, and download state utilities. `dashboard_i18n.js`, `dashboard_payload_cache.js`, and `dashboard_tooltips.js` own localization, session aggregate cache, and fast tooltip helpers. `dashboard_call_investigator.js` owns the dedicated call drilldown surface. `dashboard.js` owns top-level DOM rendering, event handling, and API refresh orchestration.
 - `context.py` is the only normal path that reads raw log context, and it does so only for one selected record on demand with redaction and size limits. Its default quick mode omits tool output and serialized groups; full serialized JSONL group analysis is explicit.
 - `plugin_installer.py`, `.mcp.json`, `skills/`, and `scripts/check_release.py` own install and packaging behavior.
 - `scripts/benchmark_synthetic_history.py` owns generated large-history query timing and threshold enforcement for 10k, 100k, and 500k aggregate-row fixtures. Its optional `--with-source-logs` mode writes synthetic JSONL source logs to time explicit context loading and to guard normal dashboard payload assembly against source-log reads. It must stay synthetic-only and must not read real Codex logs.
@@ -26,10 +27,11 @@ Codex Usage Tracker is a local sidecar app. It reads aggregate token counters fr
 1. Add new persisted usage-event metrics through `UsageEvent`, `schema.py`, migrations, store queries, dashboard payload tests, and CSV/export checks. Add auxiliary aggregate tables such as `thread_summaries` or `source_files` through `store.py` migrations plus focused migration/privacy tests.
 2. Add new report views through `reports.py` first, then wire CLI and MCP wrappers to that shared service.
 3. Add new machine-readable outputs through `api_payloads.py` or report payload methods with a `schema` value, a `json_contracts.py` entry, and focused tests.
-4. Add dashboard-only interactions in `plugin_data/dashboard/dashboard.js` and keep URL state in `dashboard_state.js`.
+4. Add dashboard-only interactions in the narrowest dashboard module and keep URL state in `dashboard_state.js`. Diagnostics snapshot panels should stay in `dashboard_diagnostics_snapshots.js`; fact tables should stay in `dashboard_diagnostics_facts.js`.
 5. Keep all examples, screenshots, mocks, and tests synthetic. Never derive fixtures from real logs.
 6. When editing skill instructions, update both the source `skills/...` file and the bundled `src/codex_usage_tracker/plugin_data/skills/...` copy. `scripts/check_release.py` verifies that installable plugin assets stay complete and synced.
 7. When adding fields derived from `cwd`, Git metadata, source paths, or log-event metadata, decide how they behave in `normal`, `redacted`, and `strict` privacy modes before exposing them in dashboard, JSON, CSV, MCP, or support-bundle output.
+8. Diagnostic snapshot refresh must remain explicit and on demand. Normal usage refresh paths may load stored snapshots, but they must not rescan source logs for diagnostic sections unless the user calls a diagnostics `--refresh` command or a `/api/diagnostics/<section>/refresh` endpoint.
 
 ## Validation
 

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/docs/cli-json-schemas.md

@@ -47,6 +47,14 @@ Tracked schema ids:
 | `codex-usage-tracker-query-v1` | CLI `query`, MCP `usage_query(...)` |
 | `codex-usage-tracker-recommendations-v1` | CLI `recommendations --json`, MCP `usage_recommendations(response_format="json")` |
 | `codex-usage-tracker-diagnostics-v1` | CLI `diagnostics ... --json`, dashboard server `/api/diagnostics/*` |
+| `codex-usage-tracker-diagnostic-overview-v1` | CLI `diagnostics overview --json`, dashboard server `/api/diagnostics/overview` |
+| `codex-usage-tracker-diagnostic-tool-output-v1` | CLI `diagnostics tool-output --json`, dashboard server `/api/diagnostics/tool-output` |
+| `codex-usage-tracker-diagnostic-commands-v1` | CLI `diagnostics commands --json`, dashboard server `/api/diagnostics/commands` |
+| `codex-usage-tracker-diagnostic-git-interactions-v1` | CLI `diagnostics git-interactions --json`, dashboard server `/api/diagnostics/git-interactions` |
+| `codex-usage-tracker-diagnostic-file-reads-v1` | CLI `diagnostics file-reads --json`, dashboard server `/api/diagnostics/file-reads` |
+| `codex-usage-tracker-diagnostic-file-modifications-v1` | CLI `diagnostics file-modifications --json`, dashboard server `/api/diagnostics/file-modifications` |
+| `codex-usage-tracker-diagnostic-read-productivity-v1` | CLI `diagnostics read-productivity --json`, dashboard server `/api/diagnostics/read-productivity` |
+| `codex-usage-tracker-diagnostic-concentration-v1` | CLI `diagnostics concentration --json`, dashboard server `/api/diagnostics/concentration` |
 | `codex-usage-tracker-session-v1` | CLI `session --json`, MCP `session_usage(response_format="json")` |
 | `codex-usage-tracker-context-v1` | CLI `context`, MCP `usage_call_context` when raw context is explicitly enabled |
 | `codex-usage-tracker-context-disabled-v1` | MCP `usage_call_context` when raw context is disabled |
@@ -162,6 +170,8 @@ Supported filters:
 
 Privacy mode affects returned metadata after matching rows. `redacted` hides raw cwd/source paths, hides Git remote labels, and hashes unnamed project names. `strict` also hides project-relative cwd, Git branch, and tags. Configured project aliases are treated as explicit display opt-ins.
 
+Per-call rows include derived timing fields when returned through dashboard/live call APIs: `call_started_at`, `call_duration_seconds`, `previous_call_event_timestamp`, and `previous_call_delta_seconds`. These values are derived from aggregate timestamps and thread adjacency; they do not read or store transcript content.
+
 ## Recommendations
 
 Command:
@@ -281,6 +291,352 @@ Schema: `codex-usage-tracker-diagnostics-v1`
 
 Diagnostics payloads report aggregate structured facts such as compaction, tool/function/MCP activity, command families, structured skill labels, search/read loops, and outcome events. They do not include prompts, assistant messages, tool arguments, tool output, patch text, raw commands, command arguments, file contents, or JSONL fragments. Token totals are associated with facts observed before a token-count row; they are not causal allocations.
 
+Diagnostic snapshots use separate section endpoints instead of one large read payload. `GET` returns the latest stored section snapshot or `status: "missing"`; `POST /api/diagnostics/<section>/refresh` recomputes and replaces only that section. The dashboard button calls `POST /api/diagnostics/refresh`, which returns a small wrapper with `sections` and recomputes source-log-derived sections with one shared analyzer pass. This keeps ordinary dashboard refresh fast and prevents source-log rescans unless a diagnostics refresh is explicit.
+
+## Diagnostic Overview Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics overview --json
+codex-usage-tracker diagnostics overview --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/overview`
+- `POST /api/diagnostics/overview/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-overview-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-overview-v1",
+  "section": "overview",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {
+    "computed_at": "2026-06-20T18:00:00+00:00",
+    "history_scope": "active",
+    "source_logs_scanned": 3,
+    "usage_rows_scanned": 10,
+    "raw_content_included": false
+  },
+  "overview": {
+    "usage_rows": 10,
+    "total_tokens": 12345,
+    "cached_input_tokens": 9000,
+    "uncached_input_tokens": 2000,
+    "cache_ratio": 0.75
+  },
+  "notes": []
+}
+```
+
+The overview snapshot is recomputed only when explicitly refreshed. Ordinary dashboard usage refreshes do not update diagnostic snapshots.
+
+## Diagnostic Tool Output Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics tool-output --json
+codex-usage-tracker diagnostics tool-output --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/tool-output`
+- `POST /api/diagnostics/tool-output/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-tool-output-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-tool-output-v1",
+  "section": "tool-output",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {},
+  "summary": {
+    "function_calls": 1,
+    "function_outputs": 1,
+    "outputs_with_original_token_count": 1,
+    "outputs_missing_original_token_count": 0,
+    "original_token_sum": 42
+  },
+  "functions": [],
+  "command_roots": [],
+  "missing_reasons": [],
+  "notes": []
+}
+```
+
+The tool-output snapshot stores function names, conservative command roots, numeric counts, and terminal `Original token count` totals. It does not store raw tool output or command text.
+
+## Diagnostic Commands Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics commands --json
+codex-usage-tracker diagnostics commands --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/commands`
+- `POST /api/diagnostics/commands/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-commands-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-commands-v1",
+  "section": "commands",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {},
+  "summary": {
+    "shell_function_calls": 1,
+    "command_root_count": 1,
+    "missing_command": 0
+  },
+  "commands": [
+    {
+      "root": "git",
+      "total": 1,
+      "children": [{"child": "status", "count": 1}]
+    }
+  ],
+  "notes": []
+}
+```
+
+The commands snapshot keeps only command roots and a bounded list of safe one-level child labels such as `status`, `diff`, or `-m:pytest`.
+
+## Diagnostic Git Interactions Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics git-interactions --json
+codex-usage-tracker diagnostics git-interactions --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/git-interactions`
+- `POST /api/diagnostics/git-interactions/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-git-interactions-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-git-interactions-v1",
+  "section": "git-interactions",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {},
+  "summary": {
+    "git_shell_calls": 2,
+    "git_command_calls": 1,
+    "github_cli_calls": 1,
+    "unique_interactions": 2,
+    "interactions_with_original_token_count": 2,
+    "interactions_missing_original_token_count": 0,
+    "original_token_sum": 55
+  },
+  "interactions": [
+    {
+      "root": "git",
+      "operation": "status",
+      "category": "read_only",
+      "mutability": "read_only",
+      "calls": 1,
+      "with_original_token_count": 1,
+      "missing_original_token_count": 0,
+      "original_token_sum": 42
+    }
+  ],
+  "categories": [{"category": "read_only", "count": 1}],
+  "mutability": [{"mutability": "read_only", "count": 1}],
+  "notes": []
+}
+```
+
+The Git interactions snapshot is a specialized view of shell commands. It persists only `git`/`gh` root labels, safe operation labels, coarse categories, counts, and token coverage. It does not persist raw command strings, branch names, remotes, file paths, tags, commit messages, PR titles, release notes, or raw command output.
+
+## Diagnostic File Reads Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics file-reads --json
+codex-usage-tracker diagnostics file-reads --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/file-reads`
+- `POST /api/diagnostics/file-reads/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-file-reads-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-file-reads-v1",
+  "section": "file-reads",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {},
+  "summary": {
+    "read_commands": 1,
+    "read_events": 1,
+    "unique_paths_read": 1,
+    "read_events_with_output_count": 1,
+    "read_events_missing_output_count": 0,
+    "allocated_output_token_sum": 42
+  },
+  "by_reader": [],
+  "top_paths": [],
+  "largest_read_commands": [],
+  "path_privacy": {},
+  "notes": []
+}
+```
+
+The file-reads snapshot classifies common shell readers such as `cat`, `sed`, `nl`, `rg`, and `find`. Path labels are basename-only with a short irreversible hash; raw commands, command arguments, absolute paths, file contents, and tool output are not stored.
+
+## Diagnostic File Modifications Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics file-modifications --json
+codex-usage-tracker diagnostics file-modifications --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/file-modifications`
+- `POST /api/diagnostics/file-modifications/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-file-modifications-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-file-modifications-v1",
+  "section": "file-modifications",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {},
+  "summary": {
+    "modification_events": 2,
+    "modified_path_events": 3,
+    "unique_paths_modified": 2,
+    "largest_event_path_count": 2
+  },
+  "top_paths": [],
+  "by_extension": [],
+  "largest_events": [],
+  "path_privacy": {},
+  "notes": []
+}
+```
+
+The file-modifications snapshot counts structured patch events and modified paths. Path labels are basename-only with short irreversible hashes; patch text, raw absolute paths, file contents, raw commands, tool output, and JSONL fragments are not stored.
+
+## Diagnostic Read Productivity Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics read-productivity --json
+codex-usage-tracker diagnostics read-productivity --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/read-productivity`
+- `POST /api/diagnostics/read-productivity/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-read-productivity-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-read-productivity-v1",
+  "section": "read-productivity",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {},
+  "summary": {
+    "read_events": 1,
+    "read_events_modified_later": 1,
+    "read_events_modified_later_pct": 1.0,
+    "unique_paths_read": 1,
+    "unique_paths_modified_later": 1,
+    "unique_path_modified_later_pct": 1.0,
+    "correlation_note": "Read-to-modify counts are temporal correlations."
+  },
+  "by_reader": [],
+  "top_modified_paths": [],
+  "path_privacy": {},
+  "notes": []
+}
+```
+
+Read productivity is a temporal correlation, not causation. A read is counted as modified later only when the same privacy-preserving path key appears in a later structured patch event in the same source log.
+
+## Diagnostic Concentration Snapshot
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics concentration --json
+codex-usage-tracker diagnostics concentration --refresh --json
+```
+
+Dashboard server API:
+
+- `GET /api/diagnostics/concentration`
+- `POST /api/diagnostics/concentration/refresh`
+
+Schema: `codex-usage-tracker-diagnostic-concentration-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostic-concentration-v1",
+  "section": "concentration",
+  "status": "ready",
+  "refreshed": false,
+  "raw_context_included": false,
+  "snapshot": {},
+  "summary": {
+    "usage_rows": 4,
+    "total_tokens": 100,
+    "dimension_count": 3,
+    "history_scope": "active"
+  },
+  "metrics": [
+    {"metric": "top_1_source_log_share", "dimension": "source_log", "top_n": 1, "share": 0.5}
+  ],
+  "dimensions": [],
+  "largest_impact_rows": [],
+  "privacy": {},
+  "notes": []
+}
+```
+
+The concentration snapshot computes top-1/top-3/top-5 share and effective group count by source log/session, cwd/project label, and day. Metric ids such as `top_1_source_log_share` are stable JSON contract fields; dashboard views should render them as reader-facing labels. Source log labels use session-id prefixes or source hashes, cwd labels use basename-only labels, and raw source paths/cwd paths are not included.
+
 ## Pricing Coverage
 
 Command:

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/docs/cli-reference.md

@@ -85,7 +85,7 @@ Dashboards default to active sessions only. Use `--include-archived` for an all-
 
 Use global `--lang <code>` before the dashboard command, or set `CODEX_USAGE_TRACKER_LANG`, to choose the dashboard's initial UI language. The dashboard language selector can then override that default in the browser. Localization applies to dashboard UI text, not JSON fields, CSV columns, model names, thread names, paths, or full CLI output.
 
-The localhost `/api/usage` endpoint accepts `limit` and `offset` query parameters, so automation can page aggregate rows without asking the server to load an entire large history at once.
+The localhost `/api/usage` endpoint accepts `limit` and `offset` query parameters, so automation can page aggregate rows without asking the server to load an entire large history at once. Call rows include derived `call_duration_seconds` and `previous_call_delta_seconds`, and live API sorting accepts `duration` and `gap` sort keys.
 
 ## Summaries
 
@@ -120,12 +120,24 @@ codex-usage-tracker diagnostics summary
 codex-usage-tracker diagnostics facts --sort uncached
 codex-usage-tracker diagnostics compactions
 codex-usage-tracker diagnostics tools
+codex-usage-tracker diagnostics overview --refresh
+codex-usage-tracker diagnostics tool-output --refresh
+codex-usage-tracker diagnostics commands --refresh
+codex-usage-tracker diagnostics git-interactions --refresh
+codex-usage-tracker diagnostics file-reads --refresh
+codex-usage-tracker diagnostics file-modifications --refresh
+codex-usage-tracker diagnostics read-productivity --refresh
+codex-usage-tracker diagnostics concentration --refresh
 codex-usage-tracker diagnostics fact-calls --fact-type compaction --fact-name post_compaction
 ```
 
 Diagnostics expose structured event patterns and their associated token totals. They can show compactions, tool/function/MCP activity, safe command families, structured skill labels, patch outcomes, task completion, search/read loops, and aborted or rolled-back turns. Associated totals are not causal allocations and are not additive when one model call has multiple diagnostic facts.
 
-Diagnostic payloads are aggregate-only. They do not include prompts, assistant text, tool arguments, tool output, patch text, raw commands, command arguments, file contents, or JSONL fragments.
+Snapshot diagnostics are persisted aggregate reports. Without `--refresh`, snapshot commands return the latest stored payload or a `missing` status. With `--refresh`, they recompute from indexed source logs and replace the stored section snapshot. Ordinary `refresh`, `open-dashboard`, and dashboard `Refresh` update usage rows only; they do not recompute diagnostic snapshots.
+
+The snapshot sections answer different questions: `overview` summarizes usage rows and aggregate token totals, `tool-output` counts functions and terminal `Original token count` coverage, `commands` keeps command roots plus bounded safe child labels, `git-interactions` counts safe Git/GitHub CLI operations and token-count coverage, `file-reads` counts reader/path activity and allocated read-output tokens, `file-modifications` counts patch modification events and safe modified-path aggregates, `read-productivity` reports later-edit correlations for matching path keys, and `concentration` shows top-N token share by source/session, cwd/project, and day.
+
+Diagnostic payloads are aggregate-only. They do not include prompts, assistant text, tool arguments, tool output, patch text, raw commands, command arguments, file contents, raw absolute paths, or JSONL fragments. Git interaction diagnostics persist only root and operation labels such as `git/status` or `gh/pr`, category counts, and token coverage; they do not persist branch names, remotes, file paths, tags, commit messages, PR titles, or release notes. File-read and file-modification diagnostics use basename-only path labels plus short irreversible hashes, read-productivity percentages are temporal correlations rather than proof that a read caused a later edit, and concentration reports use safe source/session, cwd, and day labels only.
 
 ## JSON Queries
 

{codex_usage_tracking-0.8.1 → codex_usage_tracking-0.10.0}/docs/dashboard-guide.md

@@ -2,7 +2,7 @@
 
 > **Unofficial project:** Codex Usage Tracker is independent and is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI.
 
-This guide uses synthetic aggregate data. The screenshots do not contain prompts, assistant text, tool output, or real Codex session content.
+This guide uses synthetic aggregate data. The screenshots do not contain real prompts, real assistant text, real tool output, or real Codex session content.
 
 ## Open The Dashboard
 
@@ -92,6 +92,7 @@ Use `Calls` view when you want to inspect individual model calls.
 - In redacted or strict privacy mode, search only sees the redacted metadata fields included in the dashboard payload.
 - The cards summarize only the currently visible filtered rows.
 - 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.
 - 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.
@@ -108,6 +109,7 @@ Useful interpretation notes:
 
 - `Last call total` is the token usage for the selected model call.
 - `Session cumulative` is the running total Codex logged for that session at the time of that call.
+- `Duration` is a best-effort elapsed time for the selected call segment. `Prev gap` can include waiting time between separate user turns because it measures from the previous resolved-thread call.
 - `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.
@@ -128,11 +130,21 @@ Use `Threads` view when you want to understand a work session as a group instead
 
 ## Diagnostics View
 
+![Diagnostics view showing stored snapshot panels for tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration.](assets/dashboard-diagnostics.png)
+
 Use `Diagnostics` view when you want to see what structured event patterns are happening and what token totals are associated with those patterns.
 
 - The tab consumes the localhost `/api/diagnostics/*` endpoints; static file dashboards show a live-API unavailable state.
 - The first table shows top diagnostic facts by associated uncached input tokens. Tool/function/MCP/command-family and compaction sections expose narrower slices of the same fact data.
 - Command diagnostics store only a command family such as `pytest`, `git`, or `unknown_command`. Skill and MCP labels are detected only when they are present as structured event metadata.
+- Newer on-demand diagnostic snapshot endpoints are section-specific (`overview`, `tool-output`, `commands`, `git-interactions`, `file-reads`, `file-modifications`, `read-productivity`, and `concentration`). Heavy recomputation happens only through explicit diagnostic refresh endpoints. The dashboard's `Refresh diagnostics` button uses one batched refresh so source-log sections share one scan.
+- Git interaction panels persist only safe roots and operations such as `git/status` or `gh/pr`, plus coarse categories and counts. They do not expose branch names, remotes, file paths, tags, commit messages, PR titles, release notes, or raw command output.
+- File-modification panels count structured patch events and modified paths using basename-only labels plus short irreversible path hashes. They do not expose patch text, raw paths, file contents, or JSONL fragments.
+- Click `Refresh diagnostics` when you want to recompute stored diagnostic snapshots. The normal dashboard `Refresh` action updates usage rows only.
+- Snapshot panels show their stored status, last computed time, history scope, and logs scanned count. Missing or stale panels still render without forcing a source-log scan.
+- `Tool Output` totals come from terminal wrapper metadata such as `Original token count`; missing-count rows show coverage gaps where that header was absent.
+- File-read snapshots use basename-only path labels and short hashes. Read-productivity rates are temporal correlations between earlier reads and later structured patch events, not causation.
+- Concentration snapshots show top-N share and effective group count by source log/session, cwd/project label, and day without exposing raw source-log or cwd paths.
 - Click `Calls` on a fact row to load associated model calls. Call links and largest-call links open the Call Investigator, where raw context remains explicit and on demand.
 - Associated token totals are not causal allocations and are not additive when one call has multiple diagnostic facts.