From 5639d57128ebecf87449cdd95511e207541bc417 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 3 May 2026 12:42:43 +0000
Subject: [PATCH] Patch dashboard runs from SSE payloads instead of full
 refetch (BEN-49)

The dashboard refetched `/api/runs` and `/api/events/recent` on every
SSE event except usage/tick/settings, so a live run with frequent turn
events caused per-event table rebuilds, flicker, and wasted bandwidth.

Add a small pure reducer in `src/web/dashboardEvents.ts`
(`applyTurnEvent` / `applyRunFinishedEvent` / `replaceRun` / `hasRun`)
and rewire `Dashboard.tsx` so:

- `turn` increments `turnCount` on the matching row in-memory; only
  falls back to a full `/api/runs` if the runId is unknown (stale tab).
- `runFinished` stamps `status` + `finishedAt` immediately for instant
  feedback, then a single `/api/runs/:id` fills in the authoritative
  token + cost totals via `replaceRun`. Also refreshes the recent-events
  feed once.
- `runStarted` falls back to `/api/runs` (rare, payload is `Issue`-shaped
  not `ApiRun`-shaped).

Adds 11 unit tests in `dashboardEvents.test.ts` and documents the
SSE-to-state convention in `docs/FRONTEND.md`. `pnpm all` green
(131 unit + 5 eval); `pnpm build:web` 184ms.
---
 docs/FRONTEND.md                |  17 +++++
 src/web/Dashboard.tsx           |  46 ++++++++++++-
 src/web/dashboardEvents.test.ts | 113 ++++++++++++++++++++++++++++++++
 src/web/dashboardEvents.ts      |  45 +++++++++++++
 4 files changed, 218 insertions(+), 3 deletions(-)
 create mode 100644 src/web/dashboardEvents.test.ts
 create mode 100644 src/web/dashboardEvents.ts

diff --git a/docs/FRONTEND.md b/docs/FRONTEND.md
index 7acbc13..bb60235 100644
--- a/docs/FRONTEND.md
+++ b/docs/FRONTEND.md
@@ -36,6 +36,23 @@ file. Don't install a router.
 All fetches live in [`src/web/api.ts`](../src/web/api.ts). Never call `fetch`
 from a component.
 
+### SSE → state updates
+
+The dashboard does **not** refetch `/api/runs` on every `turn` event. The
+in-memory runs list is patched from the SSE payload via the pure helpers in
+[`dashboardEvents.ts`](../src/web/dashboardEvents.ts):
+
+- `turn` → `applyTurnEvent` increments `turnCount` on the matching row.
+- `runFinished` → `applyRunFinishedEvent` stamps `status` + `finishedAt`
+  immediately, then a single `GET /api/runs/:id` (`replaceRun`) fills in
+  authoritative token totals + cost.
+- `runStarted` → falls back to `GET /api/runs` (rare event, payload is
+  `Issue`-shaped not `ApiRun`-shaped).
+- A `turn` event for an unknown `runId` (stale tab, missed `runStarted`)
+  falls back to a full `GET /api/runs`.
+
+This keeps a live run from triggering a full table refetch per turn.
+
 ## Conventions
 
 - **Accessibility first.** Every interactive element is a real `<button>` or
diff --git a/src/web/Dashboard.tsx b/src/web/Dashboard.tsx
index 45a37a4..5a86fbf 100644
--- a/src/web/Dashboard.tsx
+++ b/src/web/Dashboard.tsx
@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import {
   fetchHealth,
   fetchRecentEvents,
+  fetchRun,
   fetchRuns,
   fetchSettings,
   type ApiEvent,
@@ -11,6 +12,7 @@ import {
   type ApiUsage,
   type ApiWorkflowSummary,
 } from "./api.js";
+import { applyRunFinishedEvent, applyTurnEvent, hasRun, replaceRun } from "./dashboardEvents.js";
 import { useEventStream } from "./useEventStream.js";
 import { HealthStrip } from "./HealthStrip.js";
 import { MetricsPanel } from "./MetricsPanel.js";
@@ -46,9 +48,47 @@ export function Dashboard() {
         setSettings(data as ApiOrchestratorSettings);
         return;
       }
-      const [freshRuns, freshEvents] = await Promise.all([fetchRuns(), fetchRecentEvents()]);
-      setRuns(freshRuns);
-      setEvents(freshEvents.events);
+      const payload = data as { runId?: string; status?: string } | null;
+      const runId = payload?.runId;
+      if (name === "turn" && runId) {
+        let needsFullRefetch = false;
+        setRuns((prev) => {
+          if (!hasRun(prev, runId)) {
+            needsFullRefetch = true;
+            return prev;
+          }
+          return applyTurnEvent(prev, runId).next;
+        });
+        if (needsFullRefetch) {
+          const fresh = await fetchRuns();
+          setRuns(fresh);
+        }
+        return;
+      }
+      if (name === "runFinished" && runId) {
+        const finishedAt = new Date().toISOString();
+        const status = typeof payload?.status === "string" ? payload.status : "completed";
+        setRuns((prev) =>
+          hasRun(prev, runId) ? applyRunFinishedEvent(prev, runId, status, finishedAt).next : prev,
+        );
+        try {
+          const detail = await fetchRun(runId);
+          setRuns((prev) =>
+            hasRun(prev, runId) ? replaceRun(prev, detail.run) : [detail.run, ...prev],
+          );
+        } catch {
+          const fresh = await fetchRuns();
+          setRuns(fresh);
+        }
+        const recent = await fetchRecentEvents();
+        setEvents(recent.events);
+        return;
+      }
+      if (name === "runStarted" && runId) {
+        const fresh = await fetchRuns();
+        setRuns(fresh);
+        return;
+      }
     },
   );
 
diff --git a/src/web/dashboardEvents.test.ts b/src/web/dashboardEvents.test.ts
new file mode 100644
index 0000000..c9b328c
--- /dev/null
+++ b/src/web/dashboardEvents.test.ts
@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import type { ApiRun } from "./api.js";
+import { applyRunFinishedEvent, applyTurnEvent, hasRun, replaceRun } from "./dashboardEvents.js";
+
+function makeRun(overrides: Partial<ApiRun> = {}): ApiRun {
+  return {
+    id: "run-1",
+    issueId: "issue-1",
+    issueIdentifier: "BEN-1",
+    issueTitle: "demo",
+    status: "running",
+    startedAt: "2026-05-03T00:00:00.000Z",
+    finishedAt: null,
+    scenario: null,
+    turnCount: 0,
+    tokensInput: null,
+    tokensOutput: null,
+    tokensCacheRead: null,
+    tokensCacheCreation: null,
+    totalCostUsd: null,
+    authStatus: null,
+    startFiveHourUtil: null,
+    startSevenDayUtil: null,
+    ...overrides,
+  };
+}
+
+describe("applyTurnEvent", () => {
+  it("increments turnCount on the matching run", () => {
+    const runs = [makeRun({ id: "a", turnCount: 2 }), makeRun({ id: "b", turnCount: 5 })];
+    const { next, matched } = applyTurnEvent(runs, "b");
+    expect(matched).toBe(true);
+    expect(next.map((r) => [r.id, r.turnCount])).toEqual([
+      ["a", 2],
+      ["b", 6],
+    ]);
+  });
+
+  it("returns the same array reference when the run is not present", () => {
+    const runs = [makeRun({ id: "a" })];
+    const result = applyTurnEvent(runs, "missing");
+    expect(result.matched).toBe(false);
+    expect(result.next).toBe(runs);
+  });
+
+  it("does not mutate the input array or row", () => {
+    const row = makeRun({ id: "a", turnCount: 1 });
+    const runs = [row];
+    applyTurnEvent(runs, "a");
+    expect(row.turnCount).toBe(1);
+    expect(runs[0]).toBe(row);
+  });
+});
+
+describe("applyRunFinishedEvent", () => {
+  it("updates status and stamps finishedAt when missing", () => {
+    const runs = [makeRun({ id: "a", status: "running", finishedAt: null })];
+    const finishedAt = "2026-05-03T01:23:45.000Z";
+    const { next, matched } = applyRunFinishedEvent(runs, "a", "completed", finishedAt);
+    expect(matched).toBe(true);
+    expect(next[0].status).toBe("completed");
+    expect(next[0].finishedAt).toBe(finishedAt);
+  });
+
+  it("preserves an existing finishedAt rather than overwriting it", () => {
+    const earlier = "2026-05-02T00:00:00.000Z";
+    const runs = [makeRun({ id: "a", status: "running", finishedAt: earlier })];
+    const { next } = applyRunFinishedEvent(runs, "a", "failed", "2026-05-03T01:23:45.000Z");
+    expect(next[0].finishedAt).toBe(earlier);
+    expect(next[0].status).toBe("failed");
+  });
+
+  it("returns the original array when no run matches", () => {
+    const runs = [makeRun({ id: "a" })];
+    const result = applyRunFinishedEvent(runs, "missing", "completed", "2026-05-03T00:00:00.000Z");
+    expect(result.matched).toBe(false);
+    expect(result.next).toBe(runs);
+  });
+});
+
+describe("replaceRun", () => {
+  it("replaces the matching row by id", () => {
+    const runs = [makeRun({ id: "a", turnCount: 1 }), makeRun({ id: "b", turnCount: 2 })];
+    const updated = makeRun({
+      id: "b",
+      turnCount: 9,
+      status: "completed",
+      finishedAt: "2026-05-03T02:00:00.000Z",
+      tokensInput: 100,
+    });
+    const next = replaceRun(runs, updated);
+    expect(next[0]).toBe(runs[0]);
+    expect(next[1]).toBe(updated);
+  });
+
+  it("returns the input array when the id is unknown", () => {
+    const runs = [makeRun({ id: "a" })];
+    const updated = makeRun({ id: "missing" });
+    expect(replaceRun(runs, updated)).toBe(runs);
+  });
+});
+
+describe("hasRun", () => {
+  it("is true when the id is present", () => {
+    expect(hasRun([makeRun({ id: "a" })], "a")).toBe(true);
+  });
+  it("is false when the id is absent", () => {
+    expect(hasRun([makeRun({ id: "a" })], "b")).toBe(false);
+  });
+  it("is false on an empty list", () => {
+    expect(hasRun([], "a")).toBe(false);
+  });
+});
diff --git a/src/web/dashboardEvents.ts b/src/web/dashboardEvents.ts
new file mode 100644
index 0000000..7d8326a
--- /dev/null
+++ b/src/web/dashboardEvents.ts
@@ -0,0 +1,45 @@
+import type { ApiRun } from "./api.js";
+
+export interface ApplyResult {
+  next: ApiRun[];
+  matched: boolean;
+}
+
+export function applyTurnEvent(runs: ApiRun[], runId: string): ApplyResult {
+  let matched = false;
+  const next = runs.map((r) => {
+    if (r.id !== runId) return r;
+    matched = true;
+    return { ...r, turnCount: r.turnCount + 1 };
+  });
+  return matched ? { next, matched } : { next: runs, matched };
+}
+
+export function applyRunFinishedEvent(
+  runs: ApiRun[],
+  runId: string,
+  status: string,
+  finishedAtIso: string,
+): ApplyResult {
+  let matched = false;
+  const next = runs.map((r) => {
+    if (r.id !== runId) return r;
+    matched = true;
+    return { ...r, status, finishedAt: r.finishedAt ?? finishedAtIso };
+  });
+  return matched ? { next, matched } : { next: runs, matched };
+}
+
+export function replaceRun(runs: ApiRun[], updated: ApiRun): ApiRun[] {
+  let matched = false;
+  const next = runs.map((r) => {
+    if (r.id !== updated.id) return r;
+    matched = true;
+    return updated;
+  });
+  return matched ? next : runs;
+}
+
+export function hasRun(runs: ApiRun[], runId: string): boolean {
+  return runs.some((r) => r.id === runId);
+}