feat: add deterministic evidence-health assessment core

[harshitethic]

Summary

Adds a dependency-free, versioned evidence-health core for captured agent sessions, plus focused tests and user-facing semantics documentation.

This is a scoped foundation for #240 rather than claiming the entire issue is complete. The PR intentionally implements the deterministic calculation layer first; wiring the result into every CLI/API/dashboard surface can build on this without duplicating health rules.

What the core detects

• missing / duplicate session start and end markers
• events recorded outside the session boundary
• mixed session IDs
• missing / duplicate event IDs
• non-finite timestamps and timestamp regressions
• unpaired tool calls/results
• unpaired LLM requests/responses
• observable export failures
• explicitly declared provider blind spots
• active sessions vs finalized sessions with a missing end marker

The result is versioned and machine-readable with healthy, partial, unknown, and invalid states plus stable reason codes.

Trust boundary

A key constraint from #240 is that a clean timeline must not be presented as proof of complete capture. This implementation therefore never guesses provider limitations from absent events. Provider blind spots must be supplied explicitly by the capture adapter / future capture matrix work (#239), and they are kept distinct from observed structural defects.

The empty-evidence path also preserves any observable export failures and declared provider blind spots instead of returning early and discarding those signals; the overall state remains unknown because there is still no event stream to assess.

That keeps the core local and dependency-free, matching the repository's architecture constraints.

Tests

tests/test_evidence_health.py covers:

• a complete paired session
• empty evidence, including preservation of export/limitation signals
• active vs finalized missing-end sessions
• orphan/missing tool relationships
• timestamp regression
• declared provider blind spots
• mixed session IDs
• duplicate boundaries / event IDs
• export failure evidence
• versioned serialization

Documentation

docs/evidence-health.md documents statuses, reason semantics, the distinction between observed defects and provider limitations, and what a healthy result does not claim.

Scope / follow-ups

This PR does not claim to close #240 yet. Remaining integration work includes exposing the same result through the CLI/replay/API/dashboard and sourcing provider limitations from the capture matrix rather than ad-hoc callers. Keeping those integrations separate avoids inventing provider metadata before #239 defines it and avoids coupling the calculation engine to the dashboard work in #242.

Validation

The fork workflow is currently waiting for upstream approval, so CI has not executed yet. The implementation follows the repository's stdlib-only constraint and includes a dedicated unittest module. Once approved, CI is the authoritative full-repository validation.

Intended local commands:

python -m unittest discover -s tests -p 'test_evidence_health.py' -v
python -m unittest discover -s tests -v

No runtime dependencies or storage-format changes are introduced.