perf: v2.5.10 — ready for 10+ concurrent users, leaner locally

Measured on a copy of a real 1.2 GB / 253K-event database, 10 simulated
browsers + 10 hooks/s for 90 s: event-loop delay p99 1239 ms → 32 ms (max
2.0 s → 94 ms), 266 failed requests → 0, 74 → 111 requests/s served, server
RSS 633 → 346 MB. Entry bundle 975 KB raw → 394 KB (106 KB brotli).

Server
- /api/analytics: the events-table scans run in the read worker
  (scoped-stats eventAggregates, read-pool job analyticsEvents); runRead takes
  maxAgeMs — analytics 10 s, /api/workflows 30 s — keyed by the args
- /api/workflows/skill-usage: +event_type and a tool_name range instead of
  LIKE, so it uses idx_events_tool (784 ms → a few ms)
- idx_events_session_type_tool (session_id, event_type, tool_name,
  created_at) replaces idx_events_session_type: covering reads for session
  stats, the hook dedupes and the import resume point (1.2 s → 20 ms); 64 MB
  cache_size and 256 MB mmap_size on both connections
- WAL: the server sets wal_autocheckpoint = 0 and checkpoints PASSIVE every
  DASHBOARD_WAL_CHECKPOINT_MS (5 s) from the read worker's own writable
  connection; a failed checkpoint restores the automatic one (hook COMMIT p95
  109 ms → 15 ms at 100 hooks/s)
- tmux: one list-sessions answers a whole GET /api/lanes and the heal beat
  (liveSessions), shared for 1 s and cleared by this process's new/kill —
  GET /api/run's sync spawns had blocked 60 s of a 90 s run; the heal beat
  skips tmux when nothing runs; attach options chained into 2 spawns
- hooks: TurnDuration/APIError deduped against one read per hook instead of a
  query per transcript entry (23 ms/hook on a 763-turn session); one lane
  scan per hook; hourly upserts skip rows that did not grow; frames are sent
  after the transaction commits (and after the pane binding); new_event
  carries its row id; a split pane's (slot 1–9) hooks no longer rebind the
  lane's session_id
- watchdog liveness probe runs ps asynchronously; transcript newline scan via
  indexOf; startup subagent backfill fingerprints the files it already checked
- pty attach: backpressure (pause past 1 MB unsent, resume under 256 KB)
- static: hashed assets served from their pre-compressed .br/.gz sibling

Client
- hidden tabs neither refetch on WS events nor poll (useLiveRefresh, panes,
  lane cards, git header, changes panel, settings); no per-tab hourly
  /updates/check (the server already checks)
- refetch storms throttled (workspace tree/session list 3 s, /api/run only on
  a run-key change, notification pane lookup only when shown); WS reconnect
  jitter; terminal retry backoff 1.5 → 30 s, stops on 1008
- heavier throttles for aggregates (15 s) and detail views; Monitor keepIfSame;
  GET in-flight dedupe in request()
- lazy Dashboard/History, xterm (with the first terminal), lane modals, Sagi
  (only while enabled); only the active locale loads; Workspace chunk
  prefetched on a /workspace deep link
- Sagi: no work while disabled, pupil via CSS variables, memo avatar
- build: .br/.gz siblings, sourcemap hidden; service worker no longer caches
  /assets/ (cache v3 drops the old one)

Tests: scripts/test-server.js drops the GIT_DIR-family variables a hook
exports, so a suite run from a linked worktree's pre-commit can no longer
commit into the real repository or set core.bare.

Docs: ARCHITECTURE, DATABASE, API, DEPLOYMENT, client README,
docs/plans/perf/README.md (audit, checklist, results).

client/src/pages/ActivityFeed.tsx

@@ -111,7 +111,7 @@ const PAGE_SIZE = 50;
 // Throttle live-event refreshes so a burst of hook events (e.g. a stream of
 // PostToolUse results) triggers one refetch instead of dozens — and a steady
 // stream still refreshes, which a trailing debounce never did.
-const REFRESH_THROTTLE_MS = 1000;
+const REFRESH_THROTTLE_MS = 3000;
 
 /** The agents on screen not asked about yet, and the sessions to ask for them. */
 export function agentsToFetch(

client/src/pages/Dashboard.tsx

@@ -97,6 +97,7 @@ import { eventBus } from "../lib/eventBus";
 import { useLiveRefresh } from "../hooks/useLiveRefresh";
 import { isRemoteDataRefreshMessage } from "../lib/remoteDataEvents";
 import { useDataScope } from "../lib/dataScope";
+import { keepIfSame } from "../lib/keepIfSame";
 import { StatCard } from "../components/StatCard";
 import { AgentCard } from "../components/AgentCard";
 import { useContextMenu } from "../components/ContextMenu";
@@ -783,8 +784,10 @@ function AnalyticsTab() {
     load();
   }, [load]);
 
+  // Heavy aggregates: event-driven reloads at most every 15 s.
   useLiveRefresh(load, {
     intervalMs: 15000,
+    throttleMs: 15000,
     match: (msg) =>
       msg.type === "session_created" ||
       msg.type === "session_updated" ||
@@ -2920,7 +2923,9 @@ export function Dashboard() {
     if (sessionsRes) setSessionsById(new Map(sessionsRes.sessions.map((s) => [s.id, s])));
     if (workingRes && waitingRes) {
       const active = [...workingRes.agents, ...waitingRes.agents];
-      setActiveAgents(active);
+      // keepIfSame: an identical poll keeps the arrays, so the memoized cards
+      // do not re-render.
+      setActiveAgents(keepIfSame(active));
       // Every subagent of the active main agents' sessions, in ONE call.
       const activeSessionIds = [
         ...new Set(active.filter((a) => a.type === "main").map((a) => a.session_id)),
@@ -2929,7 +2934,7 @@ export function Dashboard() {
         ? await soft(api.agents.list({ session_ids: activeSessionIds, limit: 2000 }))
         : { agents: [] };
       if (seq !== monitorSeq.current) return;
-      if (subsRes) setAllSubagents(subsRes.agents.filter((a) => a.type === "subagent"));
+      if (subsRes) setAllSubagents(keepIfSame(subsRes.agents.filter((a) => a.type === "subagent")));
     }
     setError(failed[0] ?? null);
   }, [scope]);

client/src/pages/SessionDetail.tsx

@@ -83,6 +83,7 @@ import {
 } from "lucide-react";
 import { api, type RunHandle } from "../lib/api";
 import { useLiveRefresh } from "../hooks/useLiveRefresh";
+import { laneChangeMatcher, runKeyOf } from "../lib/laneChange";
 import { workspaceHref } from "../components/SessionRowMenu";
 import { downloadText, exportName, toCsv } from "../lib/exportData";
 import { toast } from "../lib/toast";
@@ -140,7 +141,7 @@ const EVENTS_INITIAL_BATCH = 50;
 const EVENTS_MORE_BATCH = 500;
 // Live-refresh bounds - see ActivityFeed for rationale.
 const EVENTS_MAX_REFRESH = 500;
-const EVENTS_REFRESH_THROTTLE_MS = 1000;
+const EVENTS_REFRESH_THROTTLE_MS = 3000;
 const DETAIL_TABS: DetailTab[] = ["agents", "conversation", "timeline"];
 
 export function SessionDetail() {
@@ -249,8 +250,10 @@ export function SessionDetail() {
   useEffect(() => {
     probeRuns();
   }, [probeRuns]);
-  // A pane starting/stopping re-broadcasts its lane (`lane_update`).
-  useLiveRefresh(probeRuns, { intervalMs: 10000, match: (msg) => msg.type === "lane_update" });
+  // A pane starting/stopping re-broadcasts its lane (`lane_update`); a hook's
+  // re-broadcast that moved no run column is ignored.
+  const [runChanged] = useState(() => laneChangeMatcher(runKeyOf));
+  useLiveRefresh(probeRuns, { intervalMs: 10000, match: runChanged });
 
   const load = useCallback(async () => {
     if (!id) return;

client/src/pages/Sessions.tsx

@@ -70,6 +70,7 @@ import {
 import { api } from "../lib/api";
 import type { RemoteSource, RunHandle } from "../lib/api";
 import { useLiveRefresh } from "../hooks/useLiveRefresh";
+import { laneChangeMatcher, runKeyOf } from "../lib/laneChange";
 import { useAiTools } from "../hooks/useAiTools";
 import { useLanes } from "../hooks/useLanes";
 import { toast } from "../lib/toast";
@@ -253,11 +254,13 @@ export function Sessions({ embedded = false }: { embedded?: boolean } = {}) {
   useEffect(() => {
     loadDashboardRuns();
   }, [loadDashboardRuns]);
+  const [runChanged] = useState(() => laneChangeMatcher(runKeyOf));
   useLiveRefresh(loadDashboardRuns, {
     intervalMs: 15000,
-    // A pane starting/stopping re-broadcasts its lane (`lane_update`); the
-    // server sends no run_status any more. The 15 s poll covers extra slots.
-    match: (msg) => msg.type === "lane_update",
+    // A pane starting/stopping re-broadcasts its lane (`lane_update`) — only
+    // then, not on every hook's re-broadcast; the server sends no run_status
+    // any more. The 15 s poll covers extra slots.
+    match: runChanged,
   });
 
   useLiveRefresh(load, {

client/src/pages/Settings.tsx

@@ -263,7 +263,8 @@ export function Settings({
     lastInfoAt.current = Date.now();
     let timer: number | undefined;
     const soon = () => {
-      if (timer !== undefined) return;
+      // Hidden tab: no reads; onVis catches up once when it is shown.
+      if (timer !== undefined || document.visibilityState !== "visible") return;
       const wait = Math.max(0, INFO_MIN_MS - (Date.now() - lastInfoAt.current));
       timer = window.setTimeout(() => {
         timer = undefined;
@@ -275,6 +276,8 @@ export function Settings({
       }, wait);
     };
     const beat = window.setInterval(soon, 30_000);
+    const onVis = () => soon();
+    document.addEventListener("visibilitychange", onVis);
     const off = eventBus.subscribe((msg: WSMessage) => {
       if (
         msg.type === "session_created" ||
@@ -288,6 +291,7 @@ export function Settings({
     });
     return () => {
       off();
+      document.removeEventListener("visibilitychange", onVis);
       window.clearInterval(beat);
       window.clearTimeout(timer);
     };

client/src/pages/Workflows.tsx

@@ -139,9 +139,9 @@ export function Workflows({
   }, [fetchData]);
 
   // Auto-refresh on the WebSocket messages that change workflow data, throttled
-  // so a steady stream refreshes every few seconds instead of never.
+  // so a steady stream refreshes every 15 s (heavy aggregates) instead of never.
   useLiveRefresh(fetchData, {
-    throttleMs: 5000,
+    throttleMs: 15000,
     match: (msg: WSMessage) =>
       msg.type === "session_created" ||
       msg.type === "session_updated" ||

client/src/pages/Workspace.tsx

@@ -775,7 +775,8 @@ export function Workspace() {
   useEffect(() => {
     refreshList();
     const tick = setInterval(() => {
-      refreshList();
+      // Hidden tab: skip; the visibility handler below re-reads on show.
+      if (document.visibilityState === "visible") refreshList();
     }, 5000);
     return () => clearInterval(tick);
   }, [refreshList]);

client/src/pages/__tests__/__snapshots__/screens.snapshot.test.tsx.snap

@@ -7233,7 +7233,7 @@ exports[`screen snapshots > Settings — about 1`] = `
             <p
               class="text-[10px] text-status-warning/90 mt-1"
             >
-              UI build v2.5.9 (rebuild client to match)
+              UI build v2.5.10 (rebuild client to match)
             </p>
           </div>
           <div