perf(dashboard): opt-in /control?debug=perf overlay (P0 #1-2) (Th0rgal#437)

Adds a live diagnostics panel for the /control page so we can measure
the freezes we've been hunting (DOM growth, SSE noise, reducer cost)
without instrumenting a browser session by hand. Behind a query flag
so production users never see or pay for it.

- `lib/perf-bus.ts`: shared counter bus. Reads `?debug=perf` once at
  module load, installs a `PerformanceObserver({type:'longtask'})`
  with a 10s sliding window. Exposes `recordSseBytes`, `recordSseEvent`
  (received/filtered), `recordReducer`, and a `time(name, fn)` wrapper
  that pairs `console.time` with cumulative timing. Everything no-ops
  when the flag is off — one boolean check per call site.
- `components/perf-overlay.tsx`: fixed-position panel polling the bus
  every 500ms. Shows 10s longtask total/max, DOM node count, JS heap
  used/limit, SSE bytes/s + total, SSE events/s rx vs dropped, and the
  top 6 reducers by cumulative ms. Color-codes longtask > 2s, DOM
  > 5k, heap > 50% of limit.
- `control-client.tsx`: mounts the overlay near the root, hooks
  SSE byte counts via the diagnostics callback, marks received/
  filtered events at the cross-mission filter site, and wraps the
  historical replay (`eventsToItems` → `replay:apply`) plus the
  per-render view derivation (`deriveItemViews` → `replay:group`)
  in `perfBus.time`. The same timings show up as named entries in
  Chrome's Performance panel via console.time/timeEnd.

Usage: append `?debug=perf` to any /control URL.

Author: Th0rgal

dashboard/src/app/control/control-client.tsx

@@ -13,6 +13,8 @@ import {
   type FilePasteContext,
 } from "@/components/enhanced-input";
 import { MissionAutomationsDialog } from "@/components/mission-automations-dialog";
+import { PerfOverlay } from "@/components/perf-overlay";
+import { perfBus } from "@/lib/perf-bus";
 import { MissionDebugStats } from "./MissionDebugStats";
 import { LazyCodeBlock } from "@/components/lazy-code-block";
 import { LazyJsonHighlighter } from "@/components/lazy-json-highlighter";
@@ -4044,7 +4046,10 @@ export default function ControlClient() {
     // block the main thread for several seconds, so feed it through
     // `useDeferredValue`: the toggle button + panel mount react instantly
     // while the chat-list regrouping is treated as a non-urgent transition.
-    () => deriveItemViews(items, deferredShowThinkingPanel),
+    () =>
+      perfBus.time("replay:group", () =>
+        deriveItemViews(items, deferredShowThinkingPanel)
+      ),
     [items, deferredShowThinkingPanel]
   );
 
@@ -4812,6 +4817,12 @@ export default function ControlClient() {
   // Convert stored events (from SQLite) to ChatItems for display
   // This enables full history replay including tool calls on page refresh
   const eventsToItems = useCallback((events: StoredEvent[], mission?: Mission | null): ChatItem[] => {
+    return perfBus.time("replay:apply", () => eventsToItemsImpl(events, mission));
+  }, []);
+
+  // Implementation extracted so the perf wrapper above stays one-liner; the
+  // function body is unchanged from the original eventsToItems.
+  function eventsToItemsImpl(events: StoredEvent[], mission?: Mission | null): ChatItem[] {
     const items: ChatItem[] = [];
     const toolCallMap = new Map<string, number>(); // tool_call_id -> index in items
     // Track seen event IDs to prevent duplicate items (backend may store duplicates)
@@ -5061,7 +5072,7 @@ export default function ControlClient() {
     }
 
     return items;
-  }, []);
+  }
 
   renderDeferredTraceRef.current = (id, traceEvents, maxSequence) => {
     if (traceEvents.length === 0) return;
@@ -5661,6 +5672,9 @@ export default function ControlClient() {
   }, []);
 
   const handleStreamDiagnostics = useCallback((update: StreamDiagnosticUpdate) => {
+    if (typeof update.bytes === "number") {
+      perfBus.recordSseBytes(update.bytes);
+    }
     switch (update.phase) {
       case "connecting":
         streamLog("info", "connecting", { url: update.url });
@@ -6670,6 +6684,7 @@ export default function ControlClient() {
           ? String(data["mission_id"])
           : null;
       const currentMissionId = currentMissionRef.current?.id;
+      perfBus.recordSseEvent("received");
       streamLog("debug", "received", {
         type: event.type,
         eventMissionId,
@@ -6700,6 +6715,7 @@ export default function ControlClient() {
           }
         }
         if (filterReason) {
+          perfBus.recordSseEvent("filtered");
           streamLog("debug", "filtered", {
             type: event.type,
             eventMissionId,
@@ -8530,6 +8546,10 @@ export default function ControlClient() {
           publishes a CustomEvent the parent listens to for shedding. */}
       <MissionDebugStats items={items} visibleItems={visibleItemsLimit} />
 
+      {/* Opt-in perf overlay — `?debug=perf` only. Mounts no work in normal
+          sessions; the bus and observer self-disable when the flag is off. */}
+      <PerfOverlay />
+
       {/* Hidden file input */}
       <input
         ref={fileInputRef}

dashboard/src/components/perf-overlay.tsx

@@ -0,0 +1,171 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { perfBus, type ReducerSample } from "@/lib/perf-bus";
+
+type Snapshot = {
+  longtaskTotalMs: number;
+  longtaskMaxMs: number;
+  longtaskCount: number;
+  domNodes: number;
+  heapUsedMB: number | null;
+  heapLimitMB: number | null;
+  sseBytesPerSec: number;
+  sseTotalKb: number;
+  sseEventsPerSec: number;
+  sseFilteredPerSec: number;
+  reducers: { name: string; sample: ReducerSample }[];
+};
+
+type MemoryInfo = { usedJSHeapSize: number; jsHeapSizeLimit: number };
+
+function readHeap(): MemoryInfo | null {
+  const mem = (performance as unknown as { memory?: MemoryInfo }).memory;
+  return mem && typeof mem.usedJSHeapSize === "number" ? mem : null;
+}
+
+/**
+ * Fixed-position diagnostics panel. Only mounts when `?debug=perf` is set on
+ * the URL (the bus reads the flag once at module load). Polls the bus every
+ * 500 ms; everything is best-effort and silently degrades on Safari/Firefox
+ * (no `PerformanceObserver` for longtask, no `performance.memory`).
+ */
+export function PerfOverlay() {
+  const [snap, setSnap] = useState<Snapshot | null>(null);
+
+  useEffect(() => {
+    if (!perfBus.enabled) return;
+
+    let prevBytes = perfBus.sseBytes;
+    let prevReceived = perfBus.sseEventsReceived;
+    let prevFiltered = perfBus.sseEventsFiltered;
+    let prevAt = performance.now();
+
+    const tick = () => {
+      const now = performance.now();
+      perfBus.pruneLongtasks(now);
+      const dt = (now - prevAt) / 1000;
+      const heap = readHeap();
+      const reducers = [...perfBus.reducerTimings.entries()]
+        .map(([name, sample]) => ({ name, sample }))
+        .sort((a, b) => b.sample.totalMs - a.sample.totalMs)
+        .slice(0, 6);
+
+      setSnap({
+        longtaskTotalMs: perfBus.longtasks.reduce((a, b) => a + b.d, 0),
+        longtaskMaxMs: perfBus.longtasks.reduce(
+          (a, b) => (b.d > a ? b.d : a),
+          0
+        ),
+        longtaskCount: perfBus.longtasks.length,
+        domNodes: document.getElementsByTagName("*").length,
+        heapUsedMB: heap ? heap.usedJSHeapSize / 1024 / 1024 : null,
+        heapLimitMB: heap ? heap.jsHeapSizeLimit / 1024 / 1024 : null,
+        sseBytesPerSec: dt > 0 ? (perfBus.sseBytes - prevBytes) / dt : 0,
+        sseTotalKb: perfBus.sseBytes / 1024,
+        sseEventsPerSec:
+          dt > 0 ? (perfBus.sseEventsReceived - prevReceived) / dt : 0,
+        sseFilteredPerSec:
+          dt > 0 ? (perfBus.sseEventsFiltered - prevFiltered) / dt : 0,
+        reducers,
+      });
+
+      prevBytes = perfBus.sseBytes;
+      prevReceived = perfBus.sseEventsReceived;
+      prevFiltered = perfBus.sseEventsFiltered;
+      prevAt = now;
+    };
+
+    tick();
+    const id = window.setInterval(tick, 500);
+    return () => window.clearInterval(id);
+  }, []);
+
+  if (!perfBus.enabled) return null;
+  if (!snap) {
+    return (
+      <div className="fixed right-2 top-2 z-[9999] rounded bg-black/80 px-2 py-1 font-mono text-[10px] text-white">
+        perf overlay loading…
+      </div>
+    );
+  }
+
+  const fmtMs = (ms: number) =>
+    ms < 1 ? "<1ms" : ms < 1000 ? `${ms.toFixed(0)}ms` : `${(ms / 1000).toFixed(1)}s`;
+  const fmtRate = (n: number) => (n < 10 ? n.toFixed(1) : n.toFixed(0));
+  const fmtKB = (n: number) =>
+    n < 1024 ? `${n.toFixed(0)} KB` : `${(n / 1024).toFixed(1)} MB`;
+
+  const heapWarn =
+    snap.heapUsedMB != null && snap.heapLimitMB != null
+      ? snap.heapUsedMB / snap.heapLimitMB > 0.5
+      : false;
+  const ltWarn = snap.longtaskTotalMs > 2000;
+
+  return (
+    <div
+      className="pointer-events-auto fixed right-2 top-2 z-[9999] w-[260px] rounded-md border border-white/10 bg-black/85 px-3 py-2 font-mono text-[11px] leading-tight text-white shadow-lg backdrop-blur"
+      data-testid="perf-overlay"
+    >
+      <div className="mb-1 flex items-center justify-between text-[10px] uppercase tracking-wider text-white/60">
+        <span>perf · ?debug=perf</span>
+        <span className={ltWarn ? "text-red-400" : "text-white/40"}>
+          {snap.longtaskCount} LT/10s
+        </span>
+      </div>
+      <Row
+        label="Longtask 10s"
+        value={`${fmtMs(snap.longtaskTotalMs)} (max ${fmtMs(snap.longtaskMaxMs)})`}
+        warn={ltWarn}
+      />
+      <Row label="DOM nodes" value={snap.domNodes.toLocaleString()} warn={snap.domNodes > 5000} />
+      {snap.heapUsedMB != null && (
+        <Row
+          label="JS heap"
+          value={`${snap.heapUsedMB.toFixed(0)} / ${snap.heapLimitMB?.toFixed(0) ?? "?"} MB`}
+          warn={heapWarn}
+        />
+      )}
+      <Row
+        label="SSE in"
+        value={`${fmtKB(snap.sseBytesPerSec / 1)}/s · total ${fmtKB(snap.sseTotalKb)}`}
+      />
+      <Row
+        label="SSE evt/s"
+        value={`${fmtRate(snap.sseEventsPerSec)} rx · ${fmtRate(snap.sseFilteredPerSec)} drop`}
+      />
+      {snap.reducers.length > 0 && (
+        <div className="mt-2 border-t border-white/10 pt-1">
+          <div className="mb-0.5 text-[10px] uppercase tracking-wider text-white/40">
+            Reducers (cum)
+          </div>
+          {snap.reducers.map(({ name, sample }) => (
+            <div key={name} className="flex justify-between text-[10px]">
+              <span className="truncate text-white/70">{name}</span>
+              <span className="ml-2 shrink-0 text-white/80">
+                {sample.count}× · {fmtMs(sample.totalMs)} · max {fmtMs(sample.maxMs)}
+              </span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function Row({
+  label,
+  value,
+  warn,
+}: {
+  label: string;
+  value: string;
+  warn?: boolean;
+}) {
+  return (
+    <div className="flex items-baseline justify-between gap-2">
+      <span className="text-white/60">{label}</span>
+      <span className={warn ? "text-red-400" : "text-white/90"}>{value}</span>
+    </div>
+  );
+}

dashboard/src/lib/perf-bus.ts

@@ -0,0 +1,107 @@
+/**
+ * Process-wide diagnostic bus for the `?debug=perf` overlay.
+ *
+ * The overlay polls this module every 500 ms to render counters; the rest of
+ * the dashboard (SSE handler, reducers) call `recordX` to push data in.
+ * Everything no-ops when the URL flag isn't set, so production cost is one
+ * boolean check per call site.
+ */
+
+type SseEventCategory = "received" | "filtered";
+
+export type ReducerSample = {
+  count: number;
+  totalMs: number;
+  maxMs: number;
+};
+
+class PerfBus {
+  enabled = false;
+
+  /** Cumulative bytes read from the SSE stream since this tab loaded. */
+  sseBytes = 0;
+  sseEventsReceived = 0;
+  sseEventsFiltered = 0;
+
+  /** Reducer name → aggregated timing since tab load. */
+  reducerTimings = new Map<string, ReducerSample>();
+
+  /** Sliding window of longtask entries in the last 10s (start-time, duration). */
+  longtasks: { t: number; d: number }[] = [];
+
+  recordSseBytes(totalBytes: number) {
+    if (!this.enabled) return;
+    this.sseBytes = totalBytes;
+  }
+
+  recordSseEvent(category: SseEventCategory) {
+    if (!this.enabled) return;
+    if (category === "received") this.sseEventsReceived++;
+    else this.sseEventsFiltered++;
+  }
+
+  recordReducer(name: string, durationMs: number) {
+    if (!this.enabled) return;
+    const entry = this.reducerTimings.get(name) ?? {
+      count: 0,
+      totalMs: 0,
+      maxMs: 0,
+    };
+    entry.count++;
+    entry.totalMs += durationMs;
+    if (durationMs > entry.maxMs) entry.maxMs = durationMs;
+    this.reducerTimings.set(name, entry);
+  }
+
+  pruneLongtasks(now = performance.now()) {
+    const cutoff = now - 10_000;
+    while (this.longtasks.length && this.longtasks[0].t < cutoff) {
+      this.longtasks.shift();
+    }
+  }
+
+  /** Wraps `fn` with a console.time + reducer timing record. Mirrors Chrome's perf panel. */
+  time<T>(name: string, fn: () => T): T {
+    if (!this.enabled) return fn();
+    const t0 = performance.now();
+    // eslint-disable-next-line no-console
+    console.time(name);
+    try {
+      return fn();
+    } finally {
+      // eslint-disable-next-line no-console
+      console.timeEnd(name);
+      this.recordReducer(name, performance.now() - t0);
+    }
+  }
+}
+
+export const perfBus = new PerfBus();
+
+/**
+ * One-shot install at module load. Behind `typeof window` so the bus stays
+ * inert during SSR.
+ */
+if (typeof window !== "undefined") {
+  try {
+    const params = new URLSearchParams(window.location.search);
+    perfBus.enabled = params.get("debug") === "perf";
+  } catch {
+    perfBus.enabled = false;
+  }
+
+  if (perfBus.enabled && typeof PerformanceObserver !== "undefined") {
+    try {
+      const observer = new PerformanceObserver((list) => {
+        const now = performance.now();
+        for (const entry of list.getEntries()) {
+          perfBus.longtasks.push({ t: entry.startTime, d: entry.duration });
+        }
+        perfBus.pruneLongtasks(now);
+      });
+      observer.observe({ type: "longtask", buffered: true });
+    } catch {
+      // longtask is not implemented in Safari/Firefox — silently degrade.
+    }
+  }
+}