Add intelligent cache revalidation

[TianqiZhang]

Summary

• Add cache-first automatic revalidation for session search and lookup commands
• Use conditional GET with persisted check metadata, backoff, and jitter
• Keep stale cache usable when revalidation fails, including missing/corrupt metadata repair
• Add explicit refresh progress logging that shows local cache state, remote check type, and whether JSON was downloaded
• Fix Build 2026 structured location normalization and trim extracted display values

Validation

• cd cli && npm test -- --run
• cd cli && npm run build
• Verified refresh --event build-2026 against the live endpoint: first run downloaded and cached 156 sessions; second run returned 304 with no JSON download

[Copilot]

Pull request overview

This PR adds “cache-first” automatic cache revalidation for session search/lookup, using conditional GET (ETag/Last-Modified) with persisted check metadata, backoff, and jitter; it also updates normalization to handle Build 2026’s structured location field.

Changes:

• Implement persisted cache revalidation metadata (checkedAt, nextCheckAt, failure backoff) and conditional GET behavior.
• Update cache warmup behavior (ensureCache) to fetch missing caches and revalidate due caches while keeping stale caches usable on failure.
• Extend normalization/contracts/tests to support location as a structured displayValue object, and improve CLI status output/documentation.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cli/test/normalize.test.ts	Adds regression coverage for location provided as a displayValue object.
cli/test/cache.test.ts	Introduces tests for automatic cache revalidation, conditional GET, and failure backoff behavior.
cli/src/output/format.ts	Enhances status output to include “checked age” and failure indication.
cli/src/data/normalize.ts	Uses shared display-value extraction for location to support structured shapes.
cli/src/data/cache.ts	Adds revalidation scheduling (jitter/backoff), conditional GET handling, and failure recording.
cli/src/contracts.ts	Extends RawSession.location typing and adds cache revalidation metadata fields/types.
cli/src/commands/common.ts	Updates cache initialization to fetch missing caches and revalidate due caches.
cli/README.md	Documents the new cache-first revalidation behavior and network-friendly checks.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

[pdebruin]

Solid improvement that addresses the cache staleness, partial-failure, and error-surfacing gaps we identified in review.

What works well:

• Adaptive revalidation intervals (20min active → 6h stable → 1d dormant) — right fit for event lifecycle
• Backoff with jitter on failures prevents hammering a down endpoint
• Stale cache remains usable on failure (graceful degradation)
• Good test coverage (337 lines, covers the key scenarios)
• location field fix handles real Build 2026 data shape

LGTM — approve and merge.