…i/snapshot

Per the unified-operator-interface lens + cheap-substrate thesis
(feedback-opus-escalation-must-be-earned): DashboardPage now
tries the $0 daemon snapshot first on page load, projects the
fields the snapshot covers cleanly, and only fans out to live
endpoints for the fields where projection would mislead the
operator. Force-refresh button gives the explicit "I want live"
path. Cost-economy thesis made visible via the freshness badge.

Shifted to snapshot (2 of 4 spec-listed fields)
================================================

  * operational — snapshot.operational_state.{primary, paused,
    pause_reason} maps cleanly to OperationalStateResponse's
    {primary_state, is_degraded, claim_permission} fields the
    OperationalCardBody consumes. claim_permission defaults via
    paused → "none" / not paused → "normal" (valid enum values
    per api.ts:1004 ClaimPermission).

  * alerts — snapshot.alerts.{active_count, by_severity,
    by_category} populates AlertsResponse's {total_active,
    by_severity}; per-alert array projected empty (snapshot
    doesn't carry it). AlertsBanner uses total_active for
    visibility check + falls through to aggregate-hash for
    dismissal — change documented inline in the banner.

KEPT on fan-out (2 of 4 spec-listed fields)
============================================

Per spec §2(b) "If field types don't line up cleanly, prefer to
leave the existing fan-out call for that field rather than
coerce." Coercion would actively mislead operator:

  * cost — snapshot.cost_ladder has {current_tier,
    monthly_budget_pct_used, model_default} but LACKS
    spent_to_date_usd + credit_pool_usd which CostCardBody
    renders PROMINENTLY ($ figures). Defaulting to $0 / $0
    would scream "no budget used" — actively misleading.

  * health — snapshot.service_health is SaaS-dependency health
    (vercel/sentry/doppler/supabase/fly), NOT Kora's own
    control_plane / worker daemon health. HealthHero renders
    overall/control_plane/worker; the semantic mismatch means
    a derived "any service unhealthy → overall unhealthy"
    projection would conflate dep-health with daemon-health.

Anti-projection tests pin both (test_dashboard_does_not_project_
cost_from_snapshot + test_dashboard_does_not_project_health_from_
snapshot) so a future refactor that tries the coercion gets
caught at the test gate.

Wired (per spec §3 acceptance)
================================

  * api.getSnapshot() wrapper with typed
    SnapshotResponse | SnapshotUnavailable union (caller
    branches on `"error" in resp`)
  * loadInitial() tries snapshot first; falls back to full
    fan-out on `{error: "no_snapshot"}` OR exception (network /
    5xx). Snapshot success: project ops + alerts, then fan out
    the remaining 17 fields (cost, health, sea, control, boot,
    dr, capabilities, charter, recentEvents, runbooks,
    heartbeat, mcpClients, webhookEvents, agentActivity,
    slackDM, email, reasoning).
  * forceFullLiveRefresh() bypasses snapshot, runs full fan-out.
  * Per-card retry buttons unchanged; loadOne tracks live
    overrides — when a snapshot-projected field gets refreshed
    via per-card button, badge counts it for the "mixed"
    sub-mode.

FreshnessBadge component (new)
================================

web/src/components/FreshnessBadge.tsx — 4 visual states:

  * snapshot — "Snapshot from N min ago · $0 cost view"
    (success-toned border)
  * live     — "Live (just refreshed) · live fetch"
    (neutral border)
  * unavailable — "Live fetch · backend snapshot unavailable"
    (muted; no shame about the fallback)
  * mixed    — "Snapshot from N min ago · K field(s) force-
    refreshed · mixed cost view" (warning-toned)

Force-refresh button always present. Hover tooltip shows the
underlying ISO timestamp (computed_at for snapshot mode; last
live-fetch time for live mode) — operator can grep forensically.

NOTE: timestampAbsoluteUtc inlined locally (KR-FE-OPS-QUALITY-
PASS #155 — which exports it from panelHelpers — hasn't merged
into this branch's base). Follow-on PR can swap to the shared
helper once #155 lands.

AlertsBanner snapshot-compatibility patch
==========================================

Banner now hides on `data.total_active === 0` instead of
`data.alerts.length === 0` so the snapshot path (empty per-alert
array, but total_active > 0) still surfaces the banner.

Dismissal hash falls through from id-set hash to aggregate-shape
hash (`agg:{total_active}:{critical}:{warning}:{info}`) when the
per-alert array is empty — re-dismissal triggers on aggregate
shape change so operator doesn't get silenced across new alert
additions just because we're on the $0 path.

Tests (tests/kora_cli/test_dashboard_snapshot_wire.py — 17 tests)
=================================================================

Source-pin tests (no FE component-runner per the established
CC#2 pattern):
  * api.getSnapshot wrapper signature + URL
  * SnapshotResponse + SnapshotUnavailable types declared with
    required field set
  * FreshnessBadge: component exists, 3-mode union, Force-
    refresh button, $0-cost-view literal, mixed mode marker
  * DashboardPage projects operational + alerts (positive pin)
  * DashboardPage does NOT project cost + health (anti-
    projection pin to lock the spec-§2(b) discipline)
  * loadInitial calls api.getSnapshot FIRST
  * Snapshot unavailable → fanOutAll fallback path
  * forceFullLiveRefresh sets mode="live" + bypasses snapshot
  * AlertsBanner total_active check + aggregate-hash fall-through

Verification:
  * 17/17 source-pin tests pass
  * tsc -b clean
  * vite build clean
  * Screenshot rendered: web/docs/freshness-badge/states.png
    (4 visual states + preview HTML for reproducibility)

Refs:
  * rafe-walker/kora-docs 17_cc_bucket_prompts/KR-FE-DASHBOARD-SNAPSHOT-WIRE_zero_cost_dashboard.md
  * PR #157 — snapshot infrastructure (GET /api/snapshot)
  * PR #134 — AlertsPanel + AlertsBanner (the dismissal logic
    being patched)
  * Council R3 unified-operator-interface lens
  * feedback-opus-escalation-must-be-earned (cost-economy
    visibility thesis)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>