fix: add Final annotation to __version__ and document shutdown_cycles (#1059)

src/copilot_usage/__init__.py

@@ -3,4 +3,4 @@
 
 __all__: Final[list[str]] = ["__version__"]
 
-__version__: str = version("cli-tools")
+__version__: Final[str] = version("cli-tools")

src/copilot_usage/docs/implementation.md

@@ -77,6 +77,7 @@ Typed dispatch uses the `as_*()` accessors on `SessionEvent` (e.g. `as_session_s
 | `has_shutdown_metrics`   | `bool`                      | `True` when at least one shutdown event produced non-empty `modelMetrics`; set to `bool(merged_metrics)` after merging all shutdowns |
 | `last_resume_time`       | `datetime \| None`           | Timestamp of `session.resume` event (if any, after last shutdown)                   |
 | `events_path`            | `Path \| None`               | Set by `get_all_sessions()` after building — not from events                        |
+| `shutdown_cycles`        | `list[tuple[datetime \| None, SessionShutdownData]]` | Pre-computed list of `(timestamp, shutdown_payload)` pairs for every `session.shutdown` event. Populated by `build_session_summary()` so renderers never need to re-scan the event list. |
 | `active_model_calls`     | `int`                       | `assistant.turn_start` count after last shutdown (resumed sessions only)            |
 | `active_user_messages`   | `int`                       | `user.message` count after last shutdown (resumed sessions only)                    |
 | `active_output_tokens`   | `int`                       | Sum of `outputTokens` from `assistant.message` events after last shutdown           |

tests/test_packaging.py

@@ -5,6 +5,7 @@
 import subprocess
 import zipfile
 from pathlib import Path
+from typing import Final, get_args, get_origin
 
 import pytest
 
@@ -39,6 +40,20 @@ def test_all_names_importable(module_name: str) -> None:
         )
 
 
+def test_version_is_final_str() -> None:
+    """``__version__`` must be annotated as ``Final[str]`` per coding guidelines."""
+    import copilot_usage
+
+    ann = copilot_usage.__annotations__["__version__"]
+    assert get_origin(ann) is Final, (
+        f"__version__ annotation should be Final[str], got {ann!r}"
+    )
+    args = get_args(ann)
+    assert args == (str,), (
+        f"__version__ annotation should be Final[str], got Final[{args!r}]"
+    )
+
+
 def test_wheel_excludes_docs(tmp_path: Path) -> None:
     """copilot_usage/docs/ must not be shipped in the wheel."""
     uv_executable = shutil.which("uv")