[4865ff8b] Add WebSocket support to the usage dashboard (#115)

* [e7349d84] feat(dashboard): WS usage store, hook extension, status badge, and smooth animations (#111) (#113)

- Add src/store/usage-store.ts with typed UsageData interface, useUsageStore
  Zustand store, setUsageData, clearUsageData, and setWsState actions
- Export useUsageStore and UsageData from store/index.ts
- Extend use-rate-limit-websocket.ts: rename msg type to SystemWsMessage,
  add key_metrics field; add useEffect syncing wsState into useUsageStore;
  add USAGE_UPDATE/USAGE_SNAPSHOT handler dispatching to useUsageStore
  (RATE_LIMIT_HIT/LIFTED handling and onReconnect unchanged)
- Update CommandCenter to read key_metrics from useUsageStore when
  wsState === 'connected' and usageData non-null; falls back to
  useCeoOverview() (refetchInterval: 60000) when WS disconnected
- Update KeyMetricsPanel: add wsState prop, render connection status Badge
  matching AgentStreamViewer pattern (bg-green-500+Wifi / bg-yellow-500+
  Loader2 spin / bg-gray-500+WifiOff); add transition-all duration-300
  ease-in-out to metric value spans for smooth animated updates

Co-authored-by: Frontend Developer 1 <fe-dev-1@agents.roboco.dev>

* [c9745ee8] feat(events): add USAGE_UPDATE/SNAPSHOT event types, throttled publisher, /ws/system usage bridge (#112) (#114)

- Add EventType.USAGE_UPDATE='usage.update' and EventType.USAGE_SNAPSHOT='usage.snapshot'
  to the EventType StrEnum in roboco/models/events.py

- Create roboco/services/usage_events.py with _UsageThrottle class (5-second per-agent
  window using time.monotonic()) and publish_usage_update() / publish_usage_snapshot()
  helpers; lazy imports prevent circular dependency with roboco.events

- Extend orchestrator._sweep_token_snapshots() to publish USAGE_UPDATE per active agent
  (throttled) and a USAGE_SNAPSHOT aggregate after each sweep cycle; wrapped in
  contextlib.suppress so event errors never abort DB snapshot operations

- Add _handle_usage_event() to websocket_bridge.py following _handle_rate_limit_event
  pattern; register USAGE_UPDATE and USAGE_SNAPSHOT subscriptions in
  register_websocket_bridge_handlers() forwarding both to /ws/system via broadcast_system()

- Add unit tests: test_usage_events.py (throttle suppression, publish helpers) and
  test_websocket_bridge.py extended with _handle_usage_event coverage and updated
  registration assertion to include USAGE_UPDATE/USAGE_SNAPSHOT

Co-authored-by: Backend Developer 1 <be-dev-1@agents.roboco.dev>

* fix(usage-ws): reconcile the realtime token/cost contract end-to-end

The backend and frontend halves shipped mismatched contracts, so the usage
dashboard never received live data:

- The bridge forwarded the dotted event value ("usage.update") while the panel
  switched on "USAGE_UPDATE"; map both to the UPPER_SNAKE type string the same
  way the rate-limit handler does.
- The backend emitted token/cost telemetry but the frontend read a key_metrics
  field and fed the org-metrics panel. Rewire the frontend to consume the
  USAGE_SNAPSHOT token/cost payload into the "Token Usage & Cost" panel —
  WS-first with polling fallback and a connection-status badge — and revert the
  unrelated KeyMetricsPanel / CommandCenter wiring.

Backend cleanups in the same path:

- Replace the multi-argument publish helpers with typed UsageUpdate /
  UsageSnapshot payloads, removing the too-many-arguments lint suppressions.
- Extract _fetch_agent_tokens and _persist_token_snapshot from the token sweep,
  removing the too-many-statements suppression; label the live snapshot "live".

Hardening uncovered while fixing the above:

- _finalize_spawn_session pulled the full RAG stack into the
  session-finalization path through a transcript-parse import; move the pure
  parser into a dependency-light roboco.agent_sdk.transcript_usage module so
  finalization never imports the agent SDK server.
- Reduce _finalize_spawn_session complexity by extracting
  _resolve_final_token_usage, and widen the transcript-fallback guard so a read
  error can never abort finalization.

Also align KeyMetricsPanel with the metrics /dashboard/ceo actually returns: it
read velocity_24h / avg_time_to_done / active_agents, none of which
get_key_metrics() emits, so four of five rows rendered "—". Render
velocity_weekly, completion_rate, documentation_coverage and active_blockers.

* docs: note live usage push over /ws/system on the usage dashboard

* fix(usage): finalize on self-exit and de-duplicate transcript token counts

Two bugs left token capture broken even after the transcript-read fallback
landed — surfaced by a live agent run:

- Agents that self-exit (the normal i_am_idle -> container shutdown, exit 0)
  were never finalized. _finalize_spawn_session is only called from
  stop_agent(), but a graceful self-exit goes through _handle_stopped_container,
  which set the instance OFFLINE and returned without finalizing — leaving the
  spawn-session row open with zero tokens. Finalize there for both graceful
  (exit_reason="completed") and crash (exit_reason="crashed") exits.

- sum_transcript_usage double-counted. Claude Code logs one assistant message
  as several JSONL lines (one per content block — thinking / text / tool_use),
  each repeating the same message.usage, so summing every line roughly doubled
  the totals. De-duplicate by message.id.

Verified against a live agent transcript: the raw sum (12, 1068, 62502, 115828)
vs the de-duped (6, 516, 62502, 63336), which matches the session's
authoritative result.usage exactly.

* feat(usage): fall back to the transcript in the live token sweep

The 60s token sweep read only the agent SDK's /usage/status, which races
container teardown and reports zero mid-run — so live usage (and the
USAGE_SNAPSHOT pushed to /ws/system) stayed at zero for active agents.
Extract _resolve_active_tokens: try the SDK, then fall back to the durable
transcript (the same source finalize uses) so running agents report live.

* feat(usage): add GET /usage/sessions for the dashboard's Recent Sessions

The panel's Recent Sessions table was mock-only — the backend had no sessions
endpoint, so production always showed 'No sessions recorded yet'. Add
UsageService.get_recent_sessions + a /usage/sessions route returning the most
recent spawn-session rows (token totals + cost), and point the panel client
at it.

---------

Co-authored-by: Frontend Developer 1 <fe-dev-1@agents.roboco.dev>
Co-authored-by: Backend Developer 1 <be-dev-1@agents.roboco.dev>
Co-authored-by: Renn F <rennf93@users.noreply.github.com>

tests/unit/runtime/test_orchestrator_write_hooks.py

@@ -265,6 +265,7 @@ async def test_finalize_spawn_session_http_error_uses_zero_tokens() -> None:
 
     with (
         patch("roboco.runtime.orchestrator.httpx.AsyncClient", _client_cls),
+        patch.object(orch, "_usage_from_transcript", return_value=(0, 0, 0, 0)),
         patch("roboco.db.base.get_session_factory", return_value=db_factory),
         patch("roboco.billing.pricing.calculate_cost", return_value=0.0) as mock_cost,
     ):
@@ -298,6 +299,7 @@ async def test_finalize_spawn_session_non_200_uses_zero_tokens() -> None:
 
     with (
         patch("roboco.runtime.orchestrator.httpx.AsyncClient", _client_cls),
+        patch.object(orch, "_usage_from_transcript", return_value=(0, 0, 0, 0)),
         patch("roboco.db.base.get_session_factory", return_value=db_factory),
         patch("roboco.billing.pricing.calculate_cost", return_value=0.0) as mock_cost,
     ):
@@ -383,6 +385,7 @@ async def test_sweep_token_snapshots_skips_zero_token_agents() -> None:
 
     with (
         patch("roboco.runtime.orchestrator.httpx.AsyncClient", _client_cls),
+        patch.object(orch, "_usage_from_transcript", return_value=(0, 0, 0, 0)),
         patch("roboco.db.base.get_session_factory", return_value=db_factory),
     ):
         await orch._sweep_token_snapshots()
@@ -525,7 +528,7 @@ async def test_stop_agent_finalizes_before_lock() -> None:
 
     finalized: list[str] = []
 
-    async def _fake_finalize(agent_id: str, exit_reason: str = "stopped") -> None:  # noqa: ARG001
+    async def _fake_finalize(agent_id: str, **_kwargs: object) -> None:
         finalized.append(agent_id)
 
     # Stub out the Docker subprocess so stop_agent doesn't actually run Docker
@@ -541,3 +544,107 @@ async def test_stop_agent_finalizes_before_lock() -> None:
 
     # _finalize_spawn_session must have been called exactly once with our agent id
     assert finalized == [_AGENT_ID]
+
+
+# ---------------------------------------------------------------------------
+# _handle_stopped_container — self-exits finalize (stop_agent was not called)
+# ---------------------------------------------------------------------------
+
+
+async def test_handle_stopped_container_graceful_finalizes() -> None:
+    """A graceful self-exit (exit 0) finalizes the spawn session.
+
+    The agent calls i_am_idle and its container exits 0 without stop_agent
+    being invoked, so _handle_stopped_container must finalize to capture the
+    token usage; otherwise the session row is left open with zero tokens.
+    """
+    orch = _make_orchestrator()
+    instance = _make_instance(_AGENT_ID)
+    instance.container_id = "abc123def456"
+    orch._instances[_AGENT_ID] = instance
+
+    calls: list[tuple[str, str]] = []
+
+    async def _fake_finalize(agent_id: str, exit_reason: str = "stopped") -> None:
+        calls.append((agent_id, exit_reason))
+
+    with patch.object(orch, "_finalize_spawn_session", side_effect=_fake_finalize):
+        await orch._handle_stopped_container(_AGENT_ID, instance, 0)
+
+    assert calls == [(_AGENT_ID, "completed")]
+    assert instance.state is OrchestratorAgentState.OFFLINE
+
+
+async def test_handle_stopped_container_crash_finalizes_then_restarts() -> None:
+    """A non-zero exit finalizes (exit_reason='crashed') before auto-restart."""
+    orch = _make_orchestrator()
+    instance = _make_instance(_AGENT_ID)
+    instance.container_id = "abc123def456"
+    instance.error_count = 0
+    orch._instances[_AGENT_ID] = instance
+
+    calls: list[tuple[str, str]] = []
+
+    async def _fake_finalize(agent_id: str, exit_reason: str = "stopped") -> None:
+        calls.append((agent_id, exit_reason))
+
+    with (
+        patch.object(orch, "_finalize_spawn_session", side_effect=_fake_finalize),
+        patch.object(orch, "spawn_agent", AsyncMock()) as mock_spawn,
+    ):
+        await orch._handle_stopped_container(_AGENT_ID, instance, 1)
+
+    assert calls == [(_AGENT_ID, "crashed")]
+    mock_spawn.assert_awaited_once()
+
+
+# ---------------------------------------------------------------------------
+# _resolve_active_tokens — SDK first, transcript fallback for live agents
+# ---------------------------------------------------------------------------
+
+
+async def test_resolve_active_tokens_falls_back_to_transcript() -> None:
+    """When the SDK reports all-zero, live resolution uses the transcript."""
+    orch = _make_orchestrator()
+
+    def _handler(_url: str) -> Any:
+        return _mock_response(
+            200,
+            {
+                "tokens_input": 0,
+                "tokens_output": 0,
+                "tokens_cache_read": 0,
+                "tokens_cache_write": 0,
+            },
+        )
+
+    client = _FakeHTTPClient(_handler)
+    with patch.object(orch, "_usage_from_transcript", return_value=(6, 514, 100, 50)):
+        tokens = await orch._resolve_active_tokens(client, _AGENT_ID)
+
+    assert tokens == (6, 514, 100, 50)
+
+
+async def test_resolve_active_tokens_prefers_sdk() -> None:
+    """A non-zero SDK response is used directly — no transcript fallback."""
+    orch = _make_orchestrator()
+
+    def _handler(_url: str) -> Any:
+        return _mock_response(
+            200,
+            {
+                "tokens_input": 10,
+                "tokens_output": 20,
+                "tokens_cache_read": 0,
+                "tokens_cache_write": 0,
+            },
+        )
+
+    client = _FakeHTTPClient(_handler)
+    with patch.object(
+        orch, "_usage_from_transcript", return_value=(999, 999, 999, 999)
+    ) as mock_tx:
+        tokens = await orch._resolve_active_tokens(client, _AGENT_ID)
+
+    assert tokens == (10, 20, 0, 0)
+    mock_tx.assert_not_called()