codex-agent-hour-tracker 0.1.0__tar.gz

codex_agent_hour_tracker-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+/reports/
+/dist/
+/build/
+/docs/superpowers/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.DS_Store
+.venv/
+.pytest_cache/
+.coverage
+.env
+.env.*
+!.env.example
+.dev.vars
+.wrangler/

codex_agent_hour_tracker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Osterhus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_agent_hour_tracker-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: codex-agent-hour-tracker
+Version: 0.1.0
+Summary: Measure cumulative Codex agent runtime without decoding conversation content.
+Project-URL: Homepage, https://agenthours.dev
+Project-URL: Repository, https://github.com/tim-osterhus/codex-agent-hour-tracker
+Project-URL: Issues, https://github.com/tim-osterhus/codex-agent-hour-tracker/issues
+Author-email: Tim Osterhus <tim@millrace.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,analytics,codex,privacy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.11
+Requires-Dist: tzdata>=2025.2; platform_system == 'Windows'
+Requires-Dist: tzlocal<6,>=5.3
+Description-Content-Type: text/markdown
+
+# Agent Hour Tracker
+
+Agent Hour Tracker is a local CLI that measures cumulative Codex agent-hours from completed session turns.
+
+If you inspect your own local Codex activity, start with the sanitized Archive Score card:
+
+```bash
+uvx codex-agent-hour-tracker --share
+```
+
+The command reads local session JSONL files and reports completed root and delegated turns. It does not decode conversation content for timing. Use explicit date bounds when you need a reproducible custom report.
+
+## Synthetic Archive Score example
+
+The following card uses fabricated dates and values. It is an example, not a report from a person or machine:
+
+```text
+CODEX AGENT-HOUR SCORE
+
+30 complete calendar days | 2025-01-01 to 2025-01-30
+-----------------------------------------------------
+Agent-hours/day: 2.00
+Total agent-hours: 60.00
+Peak day: 4.00
+Completed turns: 12
+Active days: 10/30
+
+Archive Score | methodology v1 | tracker v0.1.0
+Calculated locally. No conversation content uploaded.
+```
+
+Agent-hours are cumulative completed-turn durations. If turns overlap, the tracker sums each turn independently. The total measures cumulative runtime, not elapsed wall-clock time.
+
+## Install
+
+Install the published package with either tool:
+
+```bash
+uv tool install codex-agent-hour-tracker
+codex-agent-hour-tracker --share
+```
+
+```bash
+pipx install codex-agent-hour-tracker
+codex-agent-hour-tracker --share
+```
+
+The `agent-hours` command is also installed as a short alias. The CLI reads the local Codex session directory by default. Use `--sessions-dir PATH` to select another directory.
+
+## Custom reports
+
+The default report is text. Explicit `--start` and `--end` values define an inclusive local-calendar date range:
+
+```bash
+mkdir -p reports
+agent-hours --start 2025-01-01 --end 2025-01-30 \
+  > reports/january-summary.txt
+```
+
+CSV output has one row per calendar day. Save generated reports only under the ignored `reports/` directory:
+
+```bash
+agent-hours --start 2025-01-01 --end 2025-01-30 --format csv \
+  > reports/january-summary.csv
+```
+
+Git ignores the `reports/` directory. Do not redirect generated output to tracked files.
+
+## Default window and methodology
+
+The canonical Archive Score and a report without date bounds cover the 30 most recent completed local calendar days ending yesterday. Calendar days include days with zero use. If today is March 1, the window is January 30 through February 28.
+
+The scanner bounds each event gap at 30 minutes and uses bounded duration fallbacks. It attributes turns to their payload `started_at` date, excludes batch files, and deduplicates turns globally. See the [methodology](docs/methodology.md) for exact rules and limitations.
+
+## Privacy boundary
+
+`--share` emits intentionally sanitized aggregate output and is the safe default for sharing. The card contains counts, durations, and dates, so sharing it remains a deliberate aggregate disclosure.
+
+CSV and full text reports contain semi-sensitive activity patterns. Do not commit or share those files accidentally. Keep generated files under the ignored `reports/` directory and review any output before distribution.
+
+The scanner retains compact timing metadata only. It does not decode conversation content or send session data over the network. Diagnostics are separate from report output and may include counts and, outside `--share`, bounded local file paths.
+
+## Optional Codex skill
+
+The optional Codex skill is available with this repository under [`skills/codex-agent-hour-tracker/`](https://github.com/tim-osterhus/codex-agent-hour-tracker/tree/main/skills/codex-agent-hour-tracker/). Use the repository path when you want the tracker workflow in Codex.
+
+## Development and tests
+
+The package requires Python 3.11 or newer. From a source checkout, run the synthetic test suite with:
+
+```bash
+uv run python -m unittest discover -s tests -v
+```
+
+The command exposes `agent-hours` and `codex-agent-hour-tracker` entry points. Packaging metadata and the test suite are the source of truth for supported commands.
+
+Read the [security policy](SECURITY.md), [methodology](docs/methodology.md), and [MIT license](LICENSE) before deploying or sharing reports.

codex_agent_hour_tracker-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Agent Hour Tracker
+
+Agent Hour Tracker is a local CLI that measures cumulative Codex agent-hours from completed session turns.
+
+If you inspect your own local Codex activity, start with the sanitized Archive Score card:
+
+```bash
+uvx codex-agent-hour-tracker --share
+```
+
+The command reads local session JSONL files and reports completed root and delegated turns. It does not decode conversation content for timing. Use explicit date bounds when you need a reproducible custom report.
+
+## Synthetic Archive Score example
+
+The following card uses fabricated dates and values. It is an example, not a report from a person or machine:
+
+```text
+CODEX AGENT-HOUR SCORE
+
+30 complete calendar days | 2025-01-01 to 2025-01-30
+-----------------------------------------------------
+Agent-hours/day: 2.00
+Total agent-hours: 60.00
+Peak day: 4.00
+Completed turns: 12
+Active days: 10/30
+
+Archive Score | methodology v1 | tracker v0.1.0
+Calculated locally. No conversation content uploaded.
+```
+
+Agent-hours are cumulative completed-turn durations. If turns overlap, the tracker sums each turn independently. The total measures cumulative runtime, not elapsed wall-clock time.
+
+## Install
+
+Install the published package with either tool:
+
+```bash
+uv tool install codex-agent-hour-tracker
+codex-agent-hour-tracker --share
+```
+
+```bash
+pipx install codex-agent-hour-tracker
+codex-agent-hour-tracker --share
+```
+
+The `agent-hours` command is also installed as a short alias. The CLI reads the local Codex session directory by default. Use `--sessions-dir PATH` to select another directory.
+
+## Custom reports
+
+The default report is text. Explicit `--start` and `--end` values define an inclusive local-calendar date range:
+
+```bash
+mkdir -p reports
+agent-hours --start 2025-01-01 --end 2025-01-30 \
+  > reports/january-summary.txt
+```
+
+CSV output has one row per calendar day. Save generated reports only under the ignored `reports/` directory:
+
+```bash
+agent-hours --start 2025-01-01 --end 2025-01-30 --format csv \
+  > reports/january-summary.csv
+```
+
+Git ignores the `reports/` directory. Do not redirect generated output to tracked files.
+
+## Default window and methodology
+
+The canonical Archive Score and a report without date bounds cover the 30 most recent completed local calendar days ending yesterday. Calendar days include days with zero use. If today is March 1, the window is January 30 through February 28.
+
+The scanner bounds each event gap at 30 minutes and uses bounded duration fallbacks. It attributes turns to their payload `started_at` date, excludes batch files, and deduplicates turns globally. See the [methodology](docs/methodology.md) for exact rules and limitations.
+
+## Privacy boundary
+
+`--share` emits intentionally sanitized aggregate output and is the safe default for sharing. The card contains counts, durations, and dates, so sharing it remains a deliberate aggregate disclosure.
+
+CSV and full text reports contain semi-sensitive activity patterns. Do not commit or share those files accidentally. Keep generated files under the ignored `reports/` directory and review any output before distribution.
+
+The scanner retains compact timing metadata only. It does not decode conversation content or send session data over the network. Diagnostics are separate from report output and may include counts and, outside `--share`, bounded local file paths.
+
+## Optional Codex skill
+
+The optional Codex skill is available with this repository under [`skills/codex-agent-hour-tracker/`](https://github.com/tim-osterhus/codex-agent-hour-tracker/tree/main/skills/codex-agent-hour-tracker/). Use the repository path when you want the tracker workflow in Codex.
+
+## Development and tests
+
+The package requires Python 3.11 or newer. From a source checkout, run the synthetic test suite with:
+
+```bash
+uv run python -m unittest discover -s tests -v
+```
+
+The command exposes `agent-hours` and `codex-agent-hour-tracker` entry points. Packaging metadata and the test suite are the source of truth for supported commands.
+
+Read the [security policy](SECURITY.md), [methodology](docs/methodology.md), and [MIT license](LICENSE) before deploying or sharing reports.

codex_agent_hour_tracker-0.1.0/SECURITY.md

@@ -0,0 +1,17 @@
+# Security
+
+## Supported versions
+
+The latest version is the supported version. Update to the latest published version before investigating or reporting a security issue. Older versions may not contain current fixes.
+
+## Private reports
+
+Report vulnerabilities privately through [GitHub Security Advisories](https://github.com/tim-osterhus/codex-agent-hour-tracker/security/advisories) and GitHub's private vulnerability reporting workflow. Do not use a public issue for undisclosed vulnerabilities.
+
+Never attach Codex session files, transcripts, or full generated reports to a public issue. Those files can contain sensitive activity data even when the report looks operational.
+
+The `--share` command emits a bounded aggregate designed for sharing. Sharing its dates, counts, or durations is still an intentional disclosure. Review the card before publishing it.
+
+## What to include
+
+Describe the affected version, the command or input shape involved, and the observed impact. Provide a minimal reproduction that contains synthetic data. Do not include private session content.

codex_agent_hour_tracker-0.1.0/docs/methodology.md

@@ -0,0 +1,53 @@
+# Methodology
+
+Agent Hour Tracker scans local Codex session JSONL files and retains completed-turn timing metadata. The implementation and tests in `src/agent_hour_tracker/` and `tests/` define the behavior described here.
+
+## Timing
+
+For an open turn, each valid top-level event timestamp advances active time from the previous timestamp. Each event gap contributes nonnegative elapsed time capped at 30 minutes. The cap prevents an idle gap from inflating active runtime.
+
+When the event timeline has no positive duration, the scanner uses the completion's `duration_ms`, bounded to 30 minutes. If that field is unavailable, it uses `completed_at - started_at`, also bounded to 30 minutes. These are fallback durations. Diagnostics count event-timing fallbacks, and timestamp subtraction also increments duration fallbacks.
+
+## Calendar-day attribution
+
+The payload `started_at` value supplies the turn start timestamp. The selected IANA timezone converts that timestamp to a local calendar date. The full turn duration belongs to that start date. The tracker does not split one turn across midnight.
+
+An explicit `--start` or `--end` date defines an inclusive range. Turns whose local start date falls outside the range do not contribute. The metrics builder creates one row for every date in the range, including zero-use days. Calendar-day means, medians, percentiles, and the daily histogram use those zero-use rows.
+
+## Archive Score window
+
+The canonical Archive Score and an unbounded report use the 30 most recent completed local calendar days ending yesterday. The range is inclusive. If today is March 1, the range is January 30 through February 28. `--share` always uses this window and rejects explicit date bounds and report formats.
+
+## Session selection and batch exclusion
+
+The scanner includes interactive root and delegated subagent turns. The scanner classifies a session file as batch when its session metadata identifies `exec`, `batch`, or `codex_exec`, or a direct source mapping contains an `exec` or `batch` key. A batch classification excludes every completed turn found in that file.
+
+Unknown source types remain eligible for aggregation. The normal report emits a bounded fingerprint label for an unknown source. Share diagnostics omit that label.
+
+## Global deduplication and ranking
+
+The scanner excludes batch files before deduplicating observations globally by `turn_id` across all session files. One observation remains for each ID. The ranking uses event-timing usability first:
+
+1. Prefer an observation with usable event timing.
+2. Prefer the greater duration.
+3. Prefer the earlier start timestamp when the first two values tie.
+
+The scanner then sorts retained turns by start timestamp, turn-ID type and representation, and duration. Duplicate observations increment the duplicate diagnostic count.
+
+## Diagnostics
+
+The CLI reports malformed candidate lines and affected file counts. It reports incomplete turns, unmatched completions, duration fallbacks, event-timing fallbacks, duplicate observations, and excluded batch turns when those counts are nonzero. A normal report also lists unknown source fingerprints. `--share` keeps diagnostics aggregate-only and omits source labels and file paths.
+
+## Limitations
+
+- The scanner uses recognized top-level envelopes and bounded direct metadata scalars. It does not decode transcript, reasoning, base instructions, or tool payloads.
+
+- The tracker assigns a turn's full duration to its local start date. Long turns can therefore make one day appear busier than the elapsed timeline suggests.
+
+- The tracker sums overlapping turns independently. Agent-hours measure cumulative runtime, not wall-clock occupancy.
+
+- The 30-minute event-gap cap and fallback durations are estimates when session timestamps are sparse or incomplete.
+
+- Batch detection is file-level. One batch classification excludes all completed turns in that file.
+
+- Malformed records, incomplete turns, unmatched completions, and invalid metadata do not contribute to totals. Diagnostics expose counts, not the discarded content.

codex_agent_hour_tracker-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-agent-hour-tracker"
+version = "0.1.0"
+description = "Measure cumulative Codex agent runtime without decoding conversation content."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Tim Osterhus", email = "tim@millrace.ai" },
+]
+keywords = ["codex", "agents", "analytics", "privacy"]
+dependencies = [
+    "tzlocal>=5.3,<6",
+    "tzdata>=2025.2; platform_system == 'Windows'",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+]
+
+[project.urls]
+Homepage = "https://agenthours.dev"
+Repository = "https://github.com/tim-osterhus/codex-agent-hour-tracker"
+Issues = "https://github.com/tim-osterhus/codex-agent-hour-tracker/issues"
+
+[project.scripts]
+agent-hours = "agent_hour_tracker.cli:main"
+codex-agent-hour-tracker = "agent_hour_tracker.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_hour_tracker"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/SECURITY.md",
+    "/docs",
+    "/pyproject.toml",
+]

codex_agent_hour_tracker-0.1.0/src/agent_hour_tracker/__init__.py

@@ -0,0 +1,6 @@
+"""Privacy-preserving duration tracking for Codex session logs."""
+
+__all__ = ["METHODOLOGY_VERSION", "__version__"]
+
+__version__ = "0.1.0"
+METHODOLOGY_VERSION = "1"

codex_agent_hour_tracker-0.1.0/src/agent_hour_tracker/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

codex_agent_hour_tracker-0.1.0/src/agent_hour_tracker/cli.py

@@ -0,0 +1,281 @@
+"""Command-line interface for the local agent-hour report."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import TextIO
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import tzlocal
+
+from . import METHODOLOGY_VERSION, __version__
+from .metrics import build_report_metrics
+from .report import render_csv, render_share, render_text
+from .scanner import ScanDiagnostics, scan_sessions
+
+__all__ = ["main"]
+
+_MAX_MALFORMED_FILE_PATHS = 20
+_MAX_DISPLAYED_PATH_LENGTH = 120
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the agent-hour tracker CLI and return a process exit code."""
+
+    parser = _build_parser()
+    try:
+        arguments = parser.parse_args(argv)
+    except SystemExit as error:
+        return int(error.code)
+
+    if arguments.share and (
+        arguments.start is not None
+        or arguments.end is not None
+        or arguments.format is not None
+    ):
+        print(
+            "error: --share cannot be combined with --start, --end, or --format",
+            file=sys.stderr,
+        )
+        return 2
+
+    timezone = _resolve_timezone(arguments.timezone, sys.stderr)
+    if timezone is None:
+        return 2
+    report_range = _resolve_report_range(
+        None if arguments.share else arguments.start,
+        None if arguments.share else arguments.end,
+        _today_in_timezone(timezone),
+        sys.stderr,
+    )
+    if report_range is None:
+        return 2
+    start, end = report_range
+
+    sessions_dir = arguments.sessions_dir
+    if not sessions_dir.is_dir():
+        if arguments.share:
+            print(
+                "error: sessions directory is missing or not a directory",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"error: sessions directory is missing or not a directory: {sessions_dir}",
+                file=sys.stderr,
+            )
+        return 2
+
+    scan_result = scan_sessions(sessions_dir)
+    report = build_report_metrics(scan_result.turns, start, end, timezone)
+    if arguments.share:
+        sys.stdout.write(render_share(report, __version__, METHODOLOGY_VERSION))
+    elif arguments.format == "csv":
+        sys.stdout.write(render_csv(report))
+    else:
+        sys.stdout.write(render_text(report))
+    _write_diagnostics(scan_result.diagnostics, sys.stderr, share_safe=arguments.share)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-hours",
+        description="Report cumulative Codex agent-hours from local session metadata.",
+    )
+    parser.add_argument(
+        "--sessions-dir",
+        type=Path,
+        default=Path.home() / ".codex" / "sessions",
+        help="Codex sessions directory (default: ~/.codex/sessions)",
+    )
+    parser.add_argument(
+        "--start",
+        default=None,
+        metavar="YYYY-MM-DD",
+        help="first report date, inclusive (default: 30 completed days)",
+    )
+    parser.add_argument(
+        "--end",
+        default=None,
+        metavar="YYYY-MM-DD",
+        help="last report date, inclusive (default: yesterday)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "csv"),
+        default=None,
+        help="report format (default: text; unavailable with --share)",
+    )
+    parser.add_argument(
+        "--share",
+        action="store_true",
+        help="render a sanitized Archive Score card for sharing (canonical 30-day range)",
+    )
+    parser.add_argument(
+        "--timezone",
+        default=None,
+        metavar="IANA_ZONE",
+        help="IANA timezone (default: discovered local timezone)",
+    )
+    return parser
+
+
+def _parse_date(value: str, label: str, stderr: TextIO) -> date | None:
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        print(f"error: invalid {label} date: {value!r}", file=stderr)
+        return None
+
+
+def _resolve_report_range(
+    start_value: str | None,
+    end_value: str | None,
+    today: date,
+    stderr: TextIO,
+) -> tuple[date, date] | None:
+    start = (
+        _parse_date(start_value, "start", stderr)
+        if start_value is not None
+        else None
+    )
+    if start_value is not None and start is None:
+        return None
+
+    end = (
+        _parse_date(end_value, "end", stderr)
+        if end_value is not None
+        else None
+    )
+    if end_value is not None and end is None:
+        return None
+
+    if end is None:
+        end = today - timedelta(days=1)
+    if start is None:
+        start = end - timedelta(days=29)
+
+    if end < start:
+        print("error: end date must not precede start date", file=stderr)
+        return None
+    return start, end
+
+
+def _resolve_timezone(value: str | None, stderr: TextIO) -> ZoneInfo | None:
+    if value is not None:
+        try:
+            return ZoneInfo(value)
+        except (ZoneInfoNotFoundError, ValueError):
+            print(f"error: invalid timezone: {value!r}", file=stderr)
+            return None
+
+    timezone_name, warning = _discover_timezone_name()
+    if warning:
+        print(
+            f"warning: using {timezone_name} for the local timezone",
+            file=stderr,
+        )
+    try:
+        return ZoneInfo(timezone_name)
+    except (ZoneInfoNotFoundError, TypeError, ValueError):
+        print("warning: local timezone is unavailable; using UTC", file=stderr)
+        return ZoneInfo("UTC")
+
+
+def _discover_timezone_name() -> tuple[str, bool]:
+    try:
+        timezone_name = tzlocal.get_localzone_name()
+    except Exception:
+        return "UTC", True
+    if not isinstance(timezone_name, str) or not timezone_name:
+        return "UTC", True
+    return timezone_name, False
+
+
+def _today_in_timezone(timezone: ZoneInfo) -> date:
+    return datetime.now(timezone).date()
+
+
+def _write_diagnostics(
+    diagnostics: ScanDiagnostics,
+    stderr: TextIO,
+    share_safe: bool = False,
+) -> None:
+    if share_safe:
+        if diagnostics.malformed_lines:
+            print(f"Malformed lines: {diagnostics.malformed_lines}", file=stderr)
+        if diagnostics.malformed_files:
+            print(f"Malformed files: {len(diagnostics.malformed_files)}", file=stderr)
+        if diagnostics.incomplete_turns:
+            print(f"Incomplete turns: {diagnostics.incomplete_turns}", file=stderr)
+        if diagnostics.unmatched_completions:
+            print(
+                f"Unmatched completions: {diagnostics.unmatched_completions}",
+                file=stderr,
+            )
+        if diagnostics.duration_fallbacks:
+            print(f"Duration fallbacks: {diagnostics.duration_fallbacks}", file=stderr)
+        if diagnostics.event_timing_fallbacks:
+            print(
+                f"Event timing fallbacks: {diagnostics.event_timing_fallbacks}",
+                file=stderr,
+            )
+        if diagnostics.duplicate_turns:
+            print(f"Duplicate turns: {diagnostics.duplicate_turns}", file=stderr)
+        if diagnostics.excluded_batch_turns:
+            print(
+                f"Excluded batch turns: {diagnostics.excluded_batch_turns}",
+                file=stderr,
+            )
+        return
+
+    if diagnostics.malformed_lines:
+        print(f"Malformed lines: {diagnostics.malformed_lines}", file=stderr)
+    if diagnostics.malformed_files:
+        malformed_files = sorted(diagnostics.malformed_files)
+        print(f"Malformed files: {len(malformed_files)}", file=stderr)
+        for path in malformed_files[:_MAX_MALFORMED_FILE_PATHS]:
+            print(f"  {_display_path(path)}", file=stderr)
+        omitted = len(malformed_files) - _MAX_MALFORMED_FILE_PATHS
+        if omitted > 0:
+            print(
+                f"  ... {omitted} malformed file paths omitted",
+                file=stderr,
+            )
+    if diagnostics.incomplete_turns:
+        print(f"Incomplete turns: {diagnostics.incomplete_turns}", file=stderr)
+    if diagnostics.unmatched_completions:
+        print(
+            f"Unmatched completions: {diagnostics.unmatched_completions}",
+            file=stderr,
+        )
+    if diagnostics.duration_fallbacks:
+        print(f"Duration fallbacks: {diagnostics.duration_fallbacks}", file=stderr)
+    if diagnostics.event_timing_fallbacks:
+        print(
+            f"Event timing fallbacks: {diagnostics.event_timing_fallbacks}",
+            file=stderr,
+        )
+    if diagnostics.duplicate_turns:
+        print(f"Duplicate turns: {diagnostics.duplicate_turns}", file=stderr)
+    if diagnostics.excluded_batch_turns:
+        print(
+            f"Excluded batch turns: {diagnostics.excluded_batch_turns}",
+            file=stderr,
+        )
+    if diagnostics.unknown_sources:
+        print("Unknown sources:", file=stderr)
+        for source, count in sorted(diagnostics.unknown_sources.items()):
+            print(f"  {source}: {count}", file=stderr)
+
+
+def _display_path(path: Path) -> str:
+    escaped = json.dumps(str(path), ensure_ascii=True)
+    if len(escaped) <= _MAX_DISPLAYED_PATH_LENGTH:
+        return escaped
+    return escaped[: _MAX_DISPLAYED_PATH_LENGTH - 4] + '..."'