cli-consumption 0.2.1__tar.gz → 0.3.0__tar.gz

cli_consumption-0.3.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+Notable user-visible changes to CLI Consumption are documented in this file. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases
+use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-29
+
+### Added
+
+- Added privacy-safe database readiness checks and bounded request correlation for the
+  collector service ([#35]).
+
+### Changed
+
+- Provider input processing now enforces cumulative discovery, byte, SQLite row, and
+  structured-field limits across a complete collection ([#31]).
+- Dashboard generation now preflights bounded selections, streams its output, and
+  atomically replaces an existing report only after a successful write ([#32]).
+- Concurrent schema initialization, upgrade, and downgrade are now serialized on
+  SQLite and PostgreSQL, with SQLite lock waits capped at 15 seconds ([#34]).
+- Published source distributions exclude repository-only tests and automation while
+  retaining release metadata, the changelog and README, license notices, the runtime
+  package, and Hatchling's rebuild `.gitignore` ([#33]).
+- Identical adapter primitives are shared while provider-specific parsing semantics
+  remain isolated ([#36]).
+
+### Fixed
+
+- Older, identical, graph-only, and partially stale snapshots can no longer erase a
+  newer subagent relationship graph ([#30]).
+
+## [0.2.1] - 2026-08-29
+
+### Changed
+
+- Hardened ingestion privacy and normalized persisted timestamps to canonical,
+  fixed-width UTC values ([#29]).
+
+## [0.2.0] - 2026-08-29
+
+### Added
+
+- Added versioned SQLite and PostgreSQL schema migrations, retention previews, and a
+  metadata-only central collector and synchronization client ([#28]).
+- Added streamed CSV exports, time-window selection, and a share-safe dashboard
+  profile ([#28]).
+
+### Changed
+
+- Strengthened snapshot validation, transport defaults, storage deduplication, and
+  privacy regression coverage ([#28]).
+
+## [0.1.1] - 2026-08-27
+
+### Added
+
+- Added the Mistral Vibe CLI adapter ([#27]).
+
+## [0.1.0] - 2026-08-27
+
+### Changed
+
+- Refreshed the provider guide for the first minor release ([#26]).
+
+[Unreleased]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.0.18...v0.1.0
+[#26]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/26
+[#27]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/27
+[#28]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/28
+[#29]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/29
+[#30]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/30
+[#31]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/31
+[#32]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/32
+[#33]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/33
+[#34]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/34
+[#35]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/35
+[#36]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/36

{cli_consumption-0.2.1 → cli_consumption-0.3.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: cli-consumption
-Version: 0.2.1
+Version: 0.3.0
 Summary: Analyze and consolidate AI coding CLI consumption across machines.
 Project-URL: Homepage, https://github.com/Guillaume-Lombardo/cli-consumption
 Project-URL: Documentation, https://github.com/Guillaume-Lombardo/cli-consumption#readme
+Project-URL: Changelog, https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/Guillaume-Lombardo/cli-consumption/issues
 Project-URL: Repository, https://github.com/Guillaume-Lombardo/cli-consumption.git
 Author-email: Guillaume Lombardo <lombardo.guillaume@gmail.com>
@@ -95,29 +96,29 @@ uv tool run --from git+https://github.com/Guillaume-Lombardo/cli-consumption \
 `--provider all` detects the supported data stores found in their default locations.
 Use the provider name below with `--provider` to select one CLI explicitly.
 
-| CLI | Provider name | Default local source | Particularities and limits |
-| --- | --- | --- | --- |
-| Aider | `aider` | `~/.aider/analytics.jsonl` | Requires opt-in analytics logging; no projects, tools, cache/reasoning split, or provider-reported durations. |
-| Amazon Q Developer CLI | `amazon-q` | `~/.local/share/amazon-q/data.sqlite3` | Persistent conversations only; request timing is available, but token counters are not. |
-| Amp | `amp` | `~/.local/share/amp/threads/` | Per-inference tokens and context windows; no subthreads, compactions, reasoning split, or latency. |
-| Claude Code | `claude` | `~/.claude/projects/` | Main sessions, tokens, tools, and compactions; no subagents, context windows, or provider-reported durations. `claude-code` is accepted as an alias. |
-| Cline CLI | `cline` | `~/.cline/data/sessions/sessions.db` | Uses the session index and message artifacts; no costs or arbitrary task metadata. |
-| Codex | `codex` | `~/.codex/sessions/` | Richest support: timing, context pressure, settings, compactions, work items, and subagent relationships. |
-| Continue CLI | `continue` | `~/.continue/sessions/` | Token usage when present; session files lack reliable per-message timing and duration. |
-| Crush | `crush` | `~/.local/share/crush/` | Reads registered per-project SQLite stores; token counters are a latest-context snapshot, not additive usage. |
-| Cursor CLI | `cursor` | `~/.cursor/` | Composer 2 transcripts and chat metadata; no per-message time or tokens, and model attribution is incomplete. |
-| Gemini CLI | `gemini` | `~/.gemini/tmp/` | Replays active history and rewinds; hashed projects are not reversed and nested agents are excluded. |
-| GitHub Copilot CLI | `copilot` | `~/.copilot/session-state/` | Tokens are latest shutdown aggregates and cannot be assigned to individual turns. |
-| Goose | `goose` | `~/.local/share/goose/sessions/sessions.db` | Supports SQLite schema v16; no legacy JSONL, subagents, reasoning tokens, or latency. |
-| Grok Build | `grok` | `~/.grok/sessions/` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
-| Kilo Code | `kilo` | `~/.local/share/kilo/kilo.db` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
-| Kimi Code CLI | `kimi` | `~/.kimi/sessions/` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
-| Mistral Vibe CLI | `mistral-vibe` | `~/.vibe/logs/session/` | Session-level token aggregates, user turns, tools, and compactions; no per-message timestamps or historical model attribution. |
-| OpenCode | `opencode` | `~/.local/share/opencode/opencode.db` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
-| OpenHands CLI | `openhands` | `~/.openhands/conversations/` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
-| Pi | `pi` | `~/.pi/agent/sessions/` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
-| Plandex | `plandex` | `/plandex-server` | Requires an offline copy of a self-hosted `PLANDEX_BASE_DIR`; hosted accounts are not accessed, and models/tools are unavailable. |
-| Qwen Code | `qwen` | `~/.qwen/projects/` | Follows the active branch and records context windows and compactions; excludes archived and sidechain sessions. |
+| CLI | Provider name | Aliases | Default local source | Token semantics | Particularities and limits |
+| --- | --- | --- | --- | --- | --- |
+| Aider | `aider` | — | `~/.aider/analytics.jsonl` | `additive` | Requires opt-in analytics logging; no projects, tools, cache/reasoning split, or provider-reported durations. |
+| Amazon Q Developer CLI | `amazon-q` | — | `~/.local/share/amazon-q/data.sqlite3` | `unavailable` | Persistent conversations only; request timing is available, but token counters are not. |
+| Amp | `amp` | — | `~/.local/share/amp/threads/` | `additive` | Per-inference tokens and context windows; no subthreads, compactions, reasoning split, or latency. |
+| Claude Code | `claude` | `claude-code` | `~/.claude/projects/` | `additive` | Main sessions, tokens, tools, and compactions; no subagents, context windows, or provider-reported durations. |
+| Cline CLI | `cline` | — | `~/.cline/data/sessions/sessions.db` | `additive` | Uses the session index and message artifacts; no costs or arbitrary task metadata. |
+| Codex | `codex` | — | `~/.codex/sessions/` | `additive` | Richest support: timing, context pressure, settings, compactions, work items, and subagent relationships. |
+| Continue CLI | `continue` | — | `~/.continue/sessions/` | `additive` | Token usage when present; session files lack reliable per-message timing and duration. |
+| Crush | `crush` | — | `~/.local/share/crush/` | `context-snapshot` | Reads registered per-project SQLite stores; token counters are a latest-context snapshot, not additive usage. |
+| Cursor CLI | `cursor` | — | `~/.cursor/` | `unavailable` | Composer 2 transcripts and chat metadata; no per-message time or tokens, and model attribution is incomplete. |
+| Gemini CLI | `gemini` | — | `~/.gemini/tmp/` | `additive` | Replays active history and rewinds; hashed projects are not reversed and nested agents are excluded. |
+| GitHub Copilot CLI | `copilot` | — | `~/.copilot/session-state/` | `conversation-aggregate` | Tokens are latest shutdown aggregates and cannot be assigned to individual turns. |
+| Goose | `goose` | — | `~/.local/share/goose/sessions/sessions.db` | `additive` | Supports SQLite schema v16; no legacy JSONL, subagents, reasoning tokens, or latency. |
+| Grok Build | `grok` | — | `~/.grok/sessions/` | `additive` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
+| Kilo Code | `kilo` | — | `~/.local/share/kilo/kilo.db` | `additive` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
+| Kimi Code CLI | `kimi` | — | `~/.kimi/sessions/` | `additive` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
+| Mistral Vibe CLI | `mistral-vibe` | — | `~/.vibe/logs/session/` | `conversation-aggregate` | Session-level token aggregates, user turns, tools, and compactions; no per-message timestamps or historical model attribution. |
+| OpenCode | `opencode` | — | `~/.local/share/opencode/opencode.db` | `additive` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
+| OpenHands CLI | `openhands` | — | `~/.openhands/conversations/` | `additive` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
+| Pi | `pi` | — | `~/.pi/agent/sessions/` | `additive` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
+| Plandex | `plandex` | — | `/plandex-server` | `additive` | Requires an offline copy of a self-hosted `PLANDEX_BASE_DIR`; hosted accounts are not accessed, and models/tools are unavailable. |
+| Qwen Code | `qwen` | — | `~/.qwen/projects/` | `additive` | Follows the active branch and records context windows and compactions; excludes archived and sidechain sessions. |
 
 Provider formats are internal and can change without notice. The detailed extraction
 rules and qualification versions are documented in
@@ -141,12 +142,19 @@ uv run cli-consumption collect --provider codex \
 
 Copy only the required provider data. For Codex, copy the `sessions/` directory but
 never `auth.json` or other credentials. Globally identical conversation IDs are
-deduplicated, and the most complete copy wins.
+deduplicated, and the most complete copy wins. After a subagent scope is first seen,
+its relationship graph is replaced only when at least one conversation from that
+provider and source machine is strictly more complete and none is less complete.
+Identical, graph-only, or older copies cannot erase a newer graph.
 
 Provider files are untrusted. Monolithic JSON files are limited to 64 MiB, JSONL files
-to 256 MiB with an 8 MiB per-line limit, and a snapshot to 250,000 normalized records
-while it is being built. Direct provider-file symlinks are refused. `collect --strict`
-refuses to write a snapshot when malformed records were skipped.
+to 256 MiB with an 8 MiB per-line limit, 512 MiB of provider-file bytes actually read,
+and discovery to 10,000 candidate entries per provider collection. Provider SQLite
+inputs share a cumulative 512 MiB limit across databases and active WAL, SHM, or
+journal sidecars, plus 250,000 selected rows, 8 MiB per structured field, and 256 MiB
+across structured fields. A snapshot is limited to 250,000 normalized records while it
+is being built. Direct provider-file symlinks are refused. `collect --strict` refuses
+to write a snapshot when malformed records were skipped.
 
 Map original working-directory prefixes to stable project labels with repeated
 `--project NAME=PATH_PREFIX` options. The longest matching prefix wins:
@@ -197,6 +205,19 @@ to the window. CSV rows are streamed in stable primary-key order. Spreadsheet fo
 prefixes in text cells are neutralized with a leading apostrophe; CSV remains a
 detailed operational-data export, not a share-safe format.
 
+Dashboard generation preflights the selected report before streaming its tables. The
+selection is limited to 250,000 rows and 128 MiB of selected scalar values, and the
+final self-contained HTML is limited to 128 MiB of bytes actually encoded. If an
+accumulated database exceeds these limits, narrow it with `--since` and/or `--until`.
+A dashboard is streamed through a temporary file in its destination directory,
+synchronized, and atomically replaces an older dashboard only after generation
+succeeds.
+
+When `--csv` and the dashboard are requested together, each CSV is still streamed
+before dashboard generation. The dashboard file is atomic, but the output directory
+as a whole is not: a dashboard limit or write failure can leave newly written CSV
+files alongside the preserved older dashboard.
+
 ## SQLite and PostgreSQL
 
 A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:
@@ -224,6 +245,10 @@ conversation end-time path; see the
 [timestamp decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0002-canonical-utc-timestamps.md)
 for the exact representation and downgrade boundary.
 
+Revision `0004` adds internal per-scope state that serializes subagent graph freshness
+decisions. It does not add snapshot or export fields; see the
+[subagent freshness decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0003-subagent-scope-freshness.md).
+
 Preview retention before deleting normalized metadata:
 
 ```bash
@@ -233,6 +258,9 @@ uv run cli-consumption retention --keep-days 90 --database usage.sqlite --apply
 
 The first command is a dry run. `--apply` deletes old conversations and their child
 rows, old subagent relationships, and old ingestion-run records.
+Internal subagent-scope coordination rows remain as replay guards, so an older
+graph-only copy cannot recreate relationships after retention. They contain only the
+provider, source-machine label, and a lock counter and are never exported.
 
 ## Central collector API
 
@@ -259,6 +287,23 @@ deployments also need TLS and standard operational controls. The sync client ref
 plain HTTP beyond loopback unless `--allow-insecure` is passed explicitly. See
 [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md) for the trade-offs.
 
+Use `GET /health` as the process liveness probe; it never opens the database. Use
+`GET /ready` as the traffic readiness probe; it returns `200` only when the database
+is reachable and its schema is the expected revision, otherwise a generic `503`.
+The readiness path uses one fixed schema query and returns within a two-second
+application deadline. PostgreSQL uses a separate unpooled engine with connection and
+server-side timeouts configured at startup; SQLite lock waiting is capped at 1.5
+seconds. If a network stack ignores its connection timeout, the single daemon probe
+may continue after the response, but no second probe or connection starts until it
+finishes. Configure the orchestrator probe timeout slightly above two seconds as an
+independent safeguard.
+Both endpoints are intentionally unauthenticated so infrastructure probes can call
+them, and every HTTP response carries a bounded `X-Request-ID`. Put the collector
+behind a TLS-terminating reverse proxy or platform ingress. Configure request rate
+limits, connection limits, trusted proxy headers, and access-log redaction there; the
+application does not implement a second rate limiter and disables Uvicorn access logs
+to avoid recording untrusted URLs or query strings.
+
 Snapshots use strict schema version 1. The collector rejects request bodies larger
 than 32 MiB and snapshots containing more than 250,000 normalized records. A sync
 client checks `/api/v1/capabilities` before sending when the endpoint exposes it.

{cli_consumption-0.2.1 → cli_consumption-0.3.0}/README.md

@@ -60,29 +60,29 @@ uv tool run --from git+https://github.com/Guillaume-Lombardo/cli-consumption \
 `--provider all` detects the supported data stores found in their default locations.
 Use the provider name below with `--provider` to select one CLI explicitly.
 
-| CLI | Provider name | Default local source | Particularities and limits |
-| --- | --- | --- | --- |
-| Aider | `aider` | `~/.aider/analytics.jsonl` | Requires opt-in analytics logging; no projects, tools, cache/reasoning split, or provider-reported durations. |
-| Amazon Q Developer CLI | `amazon-q` | `~/.local/share/amazon-q/data.sqlite3` | Persistent conversations only; request timing is available, but token counters are not. |
-| Amp | `amp` | `~/.local/share/amp/threads/` | Per-inference tokens and context windows; no subthreads, compactions, reasoning split, or latency. |
-| Claude Code | `claude` | `~/.claude/projects/` | Main sessions, tokens, tools, and compactions; no subagents, context windows, or provider-reported durations. `claude-code` is accepted as an alias. |
-| Cline CLI | `cline` | `~/.cline/data/sessions/sessions.db` | Uses the session index and message artifacts; no costs or arbitrary task metadata. |
-| Codex | `codex` | `~/.codex/sessions/` | Richest support: timing, context pressure, settings, compactions, work items, and subagent relationships. |
-| Continue CLI | `continue` | `~/.continue/sessions/` | Token usage when present; session files lack reliable per-message timing and duration. |
-| Crush | `crush` | `~/.local/share/crush/` | Reads registered per-project SQLite stores; token counters are a latest-context snapshot, not additive usage. |
-| Cursor CLI | `cursor` | `~/.cursor/` | Composer 2 transcripts and chat metadata; no per-message time or tokens, and model attribution is incomplete. |
-| Gemini CLI | `gemini` | `~/.gemini/tmp/` | Replays active history and rewinds; hashed projects are not reversed and nested agents are excluded. |
-| GitHub Copilot CLI | `copilot` | `~/.copilot/session-state/` | Tokens are latest shutdown aggregates and cannot be assigned to individual turns. |
-| Goose | `goose` | `~/.local/share/goose/sessions/sessions.db` | Supports SQLite schema v16; no legacy JSONL, subagents, reasoning tokens, or latency. |
-| Grok Build | `grok` | `~/.grok/sessions/` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
-| Kilo Code | `kilo` | `~/.local/share/kilo/kilo.db` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
-| Kimi Code CLI | `kimi` | `~/.kimi/sessions/` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
-| Mistral Vibe CLI | `mistral-vibe` | `~/.vibe/logs/session/` | Session-level token aggregates, user turns, tools, and compactions; no per-message timestamps or historical model attribution. |
-| OpenCode | `opencode` | `~/.local/share/opencode/opencode.db` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
-| OpenHands CLI | `openhands` | `~/.openhands/conversations/` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
-| Pi | `pi` | `~/.pi/agent/sessions/` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
-| Plandex | `plandex` | `/plandex-server` | Requires an offline copy of a self-hosted `PLANDEX_BASE_DIR`; hosted accounts are not accessed, and models/tools are unavailable. |
-| Qwen Code | `qwen` | `~/.qwen/projects/` | Follows the active branch and records context windows and compactions; excludes archived and sidechain sessions. |
+| CLI | Provider name | Aliases | Default local source | Token semantics | Particularities and limits |
+| --- | --- | --- | --- | --- | --- |
+| Aider | `aider` | — | `~/.aider/analytics.jsonl` | `additive` | Requires opt-in analytics logging; no projects, tools, cache/reasoning split, or provider-reported durations. |
+| Amazon Q Developer CLI | `amazon-q` | — | `~/.local/share/amazon-q/data.sqlite3` | `unavailable` | Persistent conversations only; request timing is available, but token counters are not. |
+| Amp | `amp` | — | `~/.local/share/amp/threads/` | `additive` | Per-inference tokens and context windows; no subthreads, compactions, reasoning split, or latency. |
+| Claude Code | `claude` | `claude-code` | `~/.claude/projects/` | `additive` | Main sessions, tokens, tools, and compactions; no subagents, context windows, or provider-reported durations. |
+| Cline CLI | `cline` | — | `~/.cline/data/sessions/sessions.db` | `additive` | Uses the session index and message artifacts; no costs or arbitrary task metadata. |
+| Codex | `codex` | — | `~/.codex/sessions/` | `additive` | Richest support: timing, context pressure, settings, compactions, work items, and subagent relationships. |
+| Continue CLI | `continue` | — | `~/.continue/sessions/` | `additive` | Token usage when present; session files lack reliable per-message timing and duration. |
+| Crush | `crush` | — | `~/.local/share/crush/` | `context-snapshot` | Reads registered per-project SQLite stores; token counters are a latest-context snapshot, not additive usage. |
+| Cursor CLI | `cursor` | — | `~/.cursor/` | `unavailable` | Composer 2 transcripts and chat metadata; no per-message time or tokens, and model attribution is incomplete. |
+| Gemini CLI | `gemini` | — | `~/.gemini/tmp/` | `additive` | Replays active history and rewinds; hashed projects are not reversed and nested agents are excluded. |
+| GitHub Copilot CLI | `copilot` | — | `~/.copilot/session-state/` | `conversation-aggregate` | Tokens are latest shutdown aggregates and cannot be assigned to individual turns. |
+| Goose | `goose` | — | `~/.local/share/goose/sessions/sessions.db` | `additive` | Supports SQLite schema v16; no legacy JSONL, subagents, reasoning tokens, or latency. |
+| Grok Build | `grok` | — | `~/.grok/sessions/` | `additive` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
+| Kilo Code | `kilo` | — | `~/.local/share/kilo/kilo.db` | `additive` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
+| Kimi Code CLI | `kimi` | — | `~/.kimi/sessions/` | `additive` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
+| Mistral Vibe CLI | `mistral-vibe` | — | `~/.vibe/logs/session/` | `conversation-aggregate` | Session-level token aggregates, user turns, tools, and compactions; no per-message timestamps or historical model attribution. |
+| OpenCode | `opencode` | — | `~/.local/share/opencode/opencode.db` | `additive` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
+| OpenHands CLI | `openhands` | — | `~/.openhands/conversations/` | `additive` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
+| Pi | `pi` | — | `~/.pi/agent/sessions/` | `additive` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
+| Plandex | `plandex` | — | `/plandex-server` | `additive` | Requires an offline copy of a self-hosted `PLANDEX_BASE_DIR`; hosted accounts are not accessed, and models/tools are unavailable. |
+| Qwen Code | `qwen` | — | `~/.qwen/projects/` | `additive` | Follows the active branch and records context windows and compactions; excludes archived and sidechain sessions. |
 
 Provider formats are internal and can change without notice. The detailed extraction
 rules and qualification versions are documented in
@@ -106,12 +106,19 @@ uv run cli-consumption collect --provider codex \
 
 Copy only the required provider data. For Codex, copy the `sessions/` directory but
 never `auth.json` or other credentials. Globally identical conversation IDs are
-deduplicated, and the most complete copy wins.
+deduplicated, and the most complete copy wins. After a subagent scope is first seen,
+its relationship graph is replaced only when at least one conversation from that
+provider and source machine is strictly more complete and none is less complete.
+Identical, graph-only, or older copies cannot erase a newer graph.
 
 Provider files are untrusted. Monolithic JSON files are limited to 64 MiB, JSONL files
-to 256 MiB with an 8 MiB per-line limit, and a snapshot to 250,000 normalized records
-while it is being built. Direct provider-file symlinks are refused. `collect --strict`
-refuses to write a snapshot when malformed records were skipped.
+to 256 MiB with an 8 MiB per-line limit, 512 MiB of provider-file bytes actually read,
+and discovery to 10,000 candidate entries per provider collection. Provider SQLite
+inputs share a cumulative 512 MiB limit across databases and active WAL, SHM, or
+journal sidecars, plus 250,000 selected rows, 8 MiB per structured field, and 256 MiB
+across structured fields. A snapshot is limited to 250,000 normalized records while it
+is being built. Direct provider-file symlinks are refused. `collect --strict` refuses
+to write a snapshot when malformed records were skipped.
 
 Map original working-directory prefixes to stable project labels with repeated
 `--project NAME=PATH_PREFIX` options. The longest matching prefix wins:
@@ -162,6 +169,19 @@ to the window. CSV rows are streamed in stable primary-key order. Spreadsheet fo
 prefixes in text cells are neutralized with a leading apostrophe; CSV remains a
 detailed operational-data export, not a share-safe format.
 
+Dashboard generation preflights the selected report before streaming its tables. The
+selection is limited to 250,000 rows and 128 MiB of selected scalar values, and the
+final self-contained HTML is limited to 128 MiB of bytes actually encoded. If an
+accumulated database exceeds these limits, narrow it with `--since` and/or `--until`.
+A dashboard is streamed through a temporary file in its destination directory,
+synchronized, and atomically replaces an older dashboard only after generation
+succeeds.
+
+When `--csv` and the dashboard are requested together, each CSV is still streamed
+before dashboard generation. The dashboard file is atomic, but the output directory
+as a whole is not: a dashboard limit or write failure can leave newly written CSV
+files alongside the preserved older dashboard.
+
 ## SQLite and PostgreSQL
 
 A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:
@@ -189,6 +209,10 @@ conversation end-time path; see the
 [timestamp decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0002-canonical-utc-timestamps.md)
 for the exact representation and downgrade boundary.
 
+Revision `0004` adds internal per-scope state that serializes subagent graph freshness
+decisions. It does not add snapshot or export fields; see the
+[subagent freshness decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0003-subagent-scope-freshness.md).
+
 Preview retention before deleting normalized metadata:
 
 ```bash
@@ -198,6 +222,9 @@ uv run cli-consumption retention --keep-days 90 --database usage.sqlite --apply
 
 The first command is a dry run. `--apply` deletes old conversations and their child
 rows, old subagent relationships, and old ingestion-run records.
+Internal subagent-scope coordination rows remain as replay guards, so an older
+graph-only copy cannot recreate relationships after retention. They contain only the
+provider, source-machine label, and a lock counter and are never exported.
 
 ## Central collector API
 
@@ -224,6 +251,23 @@ deployments also need TLS and standard operational controls. The sync client ref
 plain HTTP beyond loopback unless `--allow-insecure` is passed explicitly. See
 [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md) for the trade-offs.
 
+Use `GET /health` as the process liveness probe; it never opens the database. Use
+`GET /ready` as the traffic readiness probe; it returns `200` only when the database
+is reachable and its schema is the expected revision, otherwise a generic `503`.
+The readiness path uses one fixed schema query and returns within a two-second
+application deadline. PostgreSQL uses a separate unpooled engine with connection and
+server-side timeouts configured at startup; SQLite lock waiting is capped at 1.5
+seconds. If a network stack ignores its connection timeout, the single daemon probe
+may continue after the response, but no second probe or connection starts until it
+finishes. Configure the orchestrator probe timeout slightly above two seconds as an
+independent safeguard.
+Both endpoints are intentionally unauthenticated so infrastructure probes can call
+them, and every HTTP response carries a bounded `X-Request-ID`. Put the collector
+behind a TLS-terminating reverse proxy or platform ingress. Configure request rate
+limits, connection limits, trusted proxy headers, and access-log redaction there; the
+application does not implement a second rate limiter and disables Uvicorn access logs
+to avoid recording untrusted URLs or query strings.
+
 Snapshots use strict schema version 1. The collector rejects request bodies larger
 than 32 MiB and snapshots containing more than 250,000 normalized records. A sync
 client checks `/api/v1/capabilities` before sending when the endpoint exposes it.

{cli_consumption-0.2.1 → cli_consumption-0.3.0}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cli-consumption"
-version = "0.2.1"
+version = "0.3.0"
 description = "Analyze and consolidate AI coding CLI consumption across machines."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
 authors = [{ name = "Guillaume Lombardo", email = "lombardo.guillaume@gmail.com" }]
 keywords = ["ai", "cli", "codex", "observability", "tokens", "usage"]
 classifiers = [
@@ -36,6 +37,7 @@ sync = ["httpx>=0.27"]
 [project.urls]
 Homepage = "https://github.com/Guillaume-Lombardo/cli-consumption"
 Documentation = "https://github.com/Guillaume-Lombardo/cli-consumption#readme"
+Changelog = "https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CHANGELOG.md"
 Issues = "https://github.com/Guillaume-Lombardo/cli-consumption/issues"
 Repository = "https://github.com/Guillaume-Lombardo/cli-consumption.git"
 
@@ -46,6 +48,7 @@ cli-consumption = "cli_consumption.cli:app"
 dev = [
   "fastapi>=0.115",
   "httpx>=0.27",
+  "hypothesis>=6.165.10",
   "pre-commit>=4.6.2",
   "psycopg[binary]>=3.2",
   "pytest>=8.3",
@@ -58,6 +61,17 @@ dev = [
 [tool.hatch.build.targets.wheel]
 packages = ["src/cli_consumption"]
 
+[tool.hatch.build.targets.sdist]
+include = [
+  "/LICENSE",
+  "/NOTICE",
+  "/CHANGELOG.md",
+  "/README.md",
+  "/pyproject.toml",
+  "/src/cli_consumption",
+]
+exclude = ["**/__pycache__", "**/*.pyc"]
+
 [tool.pytest.ini_options]
 addopts = "--strict-config --strict-markers"
 testpaths = ["tests"]