pi-mega-compact 0.8.17 → 0.8.18

package/src/store/sqlite/global-index.test.ts

@@ -0,0 +1,222 @@
+/**
+ * global-index.test.ts — S39 session heartbeats + token_samples round-trip.
+ *
+ * Verifies recordSessionHeartbeat + appendTokenSample + readActiveSessions +
+ * readSessionTimeseries + pruneStaleSessions + pruneTokenSamples +
+ * clearSessionHeartbeat, with particular focus on the Step 5 events.log
+ * session_sample JSONL line shape (the SSE real-time push wire format).
+ *
+ * Pi-agnostic. Uses an isolated mock index dir (never the real user
+ * `~/.mega-compact-index/` — guardrail G7). PREVENT-PI-004 (zero network):
+ * every operation is local SQLite + local FS append.
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+
+import {
+	recordSessionHeartbeat,
+	appendTokenSample,
+	readActiveSessions,
+	readSessionTimeseries,
+	pruneStaleSessions,
+	pruneTokenSamples,
+	clearSessionHeartbeat,
+	closeIndexStore,
+} from "./global-index.js";
+
+describe("global-index session time-series (S39)", () => {
+	let indexDir: string;
+	let eventsLogPath: string;
+
+	before(() => {
+		indexDir = mkdtempSync(join(tmpdir(), "mc-global-idx-"));
+		eventsLogPath = join(indexDir, "events.log");
+	});
+
+	after(() => {
+		closeIndexStore();
+		rmSync(indexDir, { recursive: true, force: true });
+	});
+
+	it("recordSessionHeartbeat + readActiveSessions: heartbeat row appears", () => {
+		recordSessionHeartbeat(
+			12_345,
+			"sess-abc-1",
+			"/home/u/repos/proj-a",
+			"/home/u/.pi/state-a",
+			200_000,
+			indexDir,
+		);
+		const sessions = readActiveSessions(indexDir);
+		assert.equal(sessions.length, 1);
+		const s = sessions[0];
+		assert.equal(s.pid, 12_345);
+		assert.equal(s.sessionId, "sess-abc-1");
+		assert.equal(s.repoRoot, "/home/u/repos/proj-a");
+		assert.equal(s.stateDir, "/home/u/.pi/state-a");
+		assert.equal(s.ctxWindow, 200_000);
+		assert.ok(s.lastSeen > 0);
+		// No token sample yet → tokens/percent are null.
+		assert.equal(s.tokens, null);
+		assert.equal(s.percent, null);
+	});
+
+	it("appendTokenSample writes a token_samples row + a session_sample JSONL line", () => {
+		appendTokenSample(
+			"sess-abc-1",
+			"/home/u/repos/proj-a",
+			42_000,
+			21.5,
+			200_000,
+			eventsLogPath,
+			indexDir,
+		);
+		// The token_samples row should now be the latest sample for this session.
+		const sessions = readActiveSessions(indexDir);
+		const s = sessions.find((x) => x.sessionId === "sess-abc-1");
+		assert.ok(s, "session must still appear in readActiveSessions");
+		assert.equal(s!.tokens, 42_000);
+		assert.equal(s!.percent, 21.5);
+
+		// The events.log JSONL line should exist and match the wire format
+		// described by the SseSessionSample contract: an object with `ts`
+		// (ISO 8601 string), `type: 'session_sample'`, and the payload fields.
+		assert.ok(existsSync(eventsLogPath), "events.log should exist");
+		const lines = readFileSync(eventsLogPath, "utf-8")
+			.trim()
+			.split("\n")
+			.filter(Boolean);
+		assert.equal(lines.length, 1, "exactly one JSONL line expected");
+		const parsed = JSON.parse(lines[0]) as Record<string, unknown>;
+		assert.equal(parsed["type"], "session_sample");
+		assert.equal(parsed["sessionId"], "sess-abc-1");
+		assert.equal(parsed["tokens"], 42_000);
+		assert.equal(parsed["percent"], 21.5);
+		// Step 5 contract mirroring: `ts` is an ISO 8601 string (matches every
+		// other SseEvent variant's `ts: string` and the DashboardEmitter
+		// events.log pattern), NOT a numeric ms value.
+		assert.equal(
+			typeof parsed["ts"],
+			"string",
+			"ts must be an ISO 8601 string (matches other SseEvent variants)",
+		);
+		// Must be ISO-parseable (NaN if invalid → typeof won't be number).
+		const tsMs = Date.parse(parsed["ts"] as string);
+		assert.ok(
+			Number.isFinite(tsMs),
+			"ts must be a valid ISO 8601 timestamp",
+		);
+		// And recent (within the last 5s).
+		assert.ok(
+			Math.abs(Date.now() - tsMs) < 5_000,
+			"ts must be within ~5s of now",
+		);
+	});
+
+	it("readSessionTimeseries returns per-session series + totals in chronological order", () => {
+		// Two sessions, two samples each — fully within the rolling window.
+		// sess-xyz-9 needs its own heartbeat row so readActiveSessions can later
+		// surface it (heartbeats are the primary key, not the samples).
+		recordSessionHeartbeat(
+			67_890,
+			"sess-xyz-9",
+			"/home/u/repos/proj-b",
+			"/home/u/.pi/state-b",
+			200_000,
+			indexDir,
+		);
+		appendTokenSample(
+			"sess-abc-1",
+			"/home/u/repos/proj-a",
+			50_000,
+			25,
+			200_000,
+			null, // no events.log line for this assertion
+			indexDir,
+		);
+		appendTokenSample(
+			"sess-xyz-9",
+			"/home/u/repos/proj-b",
+			10_000,
+			5,
+			200_000,
+			null,
+			indexDir,
+		);
+		appendTokenSample(
+			"sess-xyz-9",
+			"/home/u/repos/proj-b",
+			30_000,
+			15,
+			200_000,
+			null,
+			indexDir,
+		);
+		const since = Date.now() - 60_000;
+		const result = readSessionTimeseries(since, indexDir);
+
+		const seriesIds = result.series.map((s) => s.sessionId).sort();
+		assert.deepEqual(seriesIds, ["sess-abc-1", "sess-xyz-9"]);
+
+		const xyz = result.series.find((s) => s.sessionId === "sess-xyz-9");
+		assert.ok(xyz, "sess-xyz-9 series must exist");
+		assert.equal(xyz!.data.length, 2);
+		assert.equal(xyz!.data[0].tokens, 10_000);
+		assert.equal(xyz!.data[1].tokens, 30_000);
+		// Stable hash-based color from the SESSION_COLORS palette.
+		assert.match(xyz!.color, /^#[0-9a-f]{6}$/i);
+
+		// Totals: each timestamp summed across sessions.
+		assert.ok(result.totals.length >= 2);
+		for (const t of result.totals) {
+			assert.ok(typeof t.ts === "number" && t.ts > 0);
+			assert.ok(typeof t.tokens === "number" && t.tokens >= 0);
+		}
+		// Totals are sorted ascending by ts.
+		for (let i = 1; i < result.totals.length; i++) {
+			assert.ok(
+				result.totals[i].ts >= result.totals[i - 1].ts,
+				"totals must be chronologically ascending",
+			);
+		}
+	});
+
+	it("pruneStaleSessions clears heartbeats older than the cutoff (and only those)", () => {
+		// At this point we have 2 sessions; both are fresh (lastSeen ≈ now).
+		const beforeCount = readActiveSessions(indexDir).length;
+		assert.equal(beforeCount, 2);
+
+		// With a 0 ms cutoff, both are stale → pruned.
+		const pruned = pruneStaleSessions(0, indexDir);
+		assert.equal(pruned, 2, "both heartbeats should be pruned");
+		assert.equal(readActiveSessions(indexDir).length, 0);
+	});
+
+	it("pruneTokenSamples clears token_samples older than the cutoff", () => {
+		// Re-seed two samples; the previously-written ones were for two
+		// sessions (sess-abc-1 + sess-xyz-9). The prunedStaleSessions call
+		// above left token_samples untouched (separate table).
+		const sinceBefore = Date.now() - 60_000;
+		const before = readSessionTimeseries(sinceBefore, indexDir);
+		const beforeCount = before.series.reduce((n, s) => n + s.data.length, 0);
+		assert.ok(beforeCount >= 3, "expected to find the seeded samples");
+
+		const npurged = pruneTokenSamples(0, indexDir);
+		assert.ok(npurged >= 3, "should have pruned the seeded samples");
+
+		const after = readSessionTimeseries(sinceBefore, indexDir);
+		const afterCount = after.series.reduce((n, s) => n + s.data.length, 0);
+		assert.equal(afterCount, 0, "no samples should remain after pruning");
+	});
+
+	it("clearSessionHeartbeat is a no-op on missing rows (never throws)", () => {
+		const before = readActiveSessions(indexDir).length;
+		assert.doesNotThrow(() =>
+			clearSessionHeartbeat(99_999, "nonexistent-session", indexDir),
+		);
+		assert.equal(readActiveSessions(indexDir).length, before);
+	});
+});

package/src/store/sqlite/global-index.ts

@@ -12,7 +12,7 @@
  * infrequent idempotent upserts (ON CONFLICT). Fully local (PREVENT-PI-004).
  */
 import { DatabaseSync } from "node:sqlite";
-import { existsSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -70,6 +70,31 @@ export function openIndexStore(indexDir: string = getIndexDir()): DatabaseSync {
       PRIMARY KEY (checkpoint_id, session_id)
     );
     CREATE INDEX IF NOT EXISTS idx_injected_global_cid ON injected_global(checkpoint_id);
+    -- S39: machine-wide session heartbeats + token time-series for the live
+    -- multi-pi stacked-memory graph. One row per (pid, session_id), updated
+    -- on every material snapshot() change (NOT on idle/context-repeat events).
+    -- Written by every pi process; read by the dashboard server. WAL-safe.
+    -- PRAMETERIZED queries (PREVENT-002); local node:sqlite (PREVENT-PI-004).
+    CREATE TABLE IF NOT EXISTS session_heartbeats (
+      pid          INTEGER NOT NULL,
+      session_id   TEXT NOT NULL,
+      repo_root    TEXT,
+      state_dir    TEXT,
+      ctx_window   INTEGER DEFAULT 0,
+      last_seen    INTEGER NOT NULL,
+      PRIMARY KEY (pid, session_id)
+    );
+    CREATE TABLE IF NOT EXISTS token_samples (
+      id           INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id   TEXT NOT NULL,
+      repo_root    TEXT,
+      tokens       INTEGER NOT NULL,
+      percent      REAL NOT NULL,
+      ctx_window   INTEGER DEFAULT 0,
+      ts           INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_token_samples_ts ON token_samples(ts);
+    CREATE INDEX IF NOT EXISTS idx_token_samples_sid_ts ON token_samples(session_id, ts);
   `);
   indexCache = iddb;
   indexCacheDir = indexDir;
@@ -303,3 +328,293 @@ export function countInjectedGlobal(indexDir: string = getIndexDir()): number {
   const row = db.prepare("SELECT COUNT(*) AS n FROM injected_global").get() as { n: number } | undefined;
   return row?.n ?? 0;
 }
+
+// ---------------------------------------------------------------------------
+// S39: session heartbeats + token time-series (multi-pi stacked memory graph)
+//
+// `session_heartbeats`: one row per (pid, session_id), upserted on every
+// material snapshot() change. This is the reliable liveness signal the
+// dashboard /api/sessions endpoint reads (repo_registry.last_seen only updates
+// on repo-switch / bindRepo, so a long-running single-repo process looks
+// inactive; these heartbeats update on every material change).
+//
+// `token_samples`: append-only rows with (session_id, tokens, percent, ts) for
+// the stacked-memory graph. Garbage-collected by pruneTokenSamples.
+//
+// All queries use @named/$named bind parameters (PREVENT-002); local node:sqlite
+// + WAL (PREVENT-PI-004), multi-process safe.
+// ---------------------------------------------------------------------------
+
+/** A live active session row (joined heartbeat + latest token sample). */
+export interface ActiveSessionRow {
+  pid: number;
+  sessionId: string;
+  repoRoot: string | null;
+  stateDir: string | null;
+  ctxWindow: number;
+  lastSeen: number;
+  tokens: number | null;
+  percent: number | null;
+}
+
+/** A single time-series data point for a session. */
+export interface TokenSamplePoint {
+  ts: number;
+  tokens: number;
+  percent: number;
+}
+
+/** A recharts-ready per-session series with a stable color. */
+export interface SessionSeries {
+  sessionId: string;
+  label: string;
+  color: string;
+  data: TokenSamplePoint[];
+}
+
+/** Timeseries response shape (recharts-ready). */
+export interface SessionTimeseriesResult {
+  series: SessionSeries[];
+  totals: { ts: number; tokens: number }[];
+}
+
+/** Stable color palette for per-session series (hash-based, no randomness). */
+const SESSION_COLORS = [
+  "#60a5fa", // blue-400
+  "#34d399", // emerald-400
+  "#fbbf24", // amber-400
+  "#f87171", // red-400
+  "#a78bfa", // violet-400
+  "#f472b6", // pink-400
+  "#22d3ee", // cyan-400
+  "#a3e635", // lime-400
+];
+
+/** Hash a sessionId to a stable color index. */
+function sessionColor(sessionId: string): string {
+  let h = 0;
+  for (let i = 0; i < sessionId.length; i++) {
+    h = (h * 31 + sessionId.charCodeAt(i)) | 0;
+  }
+  return SESSION_COLORS[Math.abs(h) % SESSION_COLORS.length];
+}
+
+/**
+ * Record (upsert) a session heartbeat. Called from snapshot() on every material
+ * change. PRIMARY KEY (pid, session_id) means concurrent pi processes each get
+ * their own row. Non-fatal on conflict (INSERT ... ON CONFLICT DO UPDATE).
+ */
+export function recordSessionHeartbeat(
+  pid: number,
+  sessionId: string,
+  repoRoot: string,
+  stateDir: string,
+  ctxWindow: number,
+  indexDir: string = getIndexDir(),
+): void {
+  const db = openIndexStore(indexDir);
+  const now = Date.now();
+  db.prepare(
+    `INSERT INTO session_heartbeats (pid, session_id, repo_root, state_dir, ctx_window, last_seen)
+     VALUES (@pid, @session_id, @repo_root, @state_dir, @ctx_window, @last_seen)
+     ON CONFLICT(pid, session_id) DO UPDATE SET
+       repo_root = excluded.repo_root,
+       state_dir = excluded.state_dir,
+       ctx_window = excluded.ctx_window,
+       last_seen = excluded.last_seen`,
+  ).run({
+    pid,
+    session_id: sessionId,
+    repo_root: repoRoot,
+    state_dir: stateDir,
+    ctx_window: ctxWindow,
+    last_seen: now,
+  });
+}
+
+/**
+ * Append a token sample row + optionally a session_sample line to events.log
+ * (for SSE real-time push via /api/events). The eventsLogPath is optional —
+ * callers without an events.log (e.g. tests) can omit it.
+ */
+export function appendTokenSample(
+  sessionId: string,
+  repoRoot: string,
+  tokens: number,
+  percent: number,
+  ctxWindow: number,
+  eventsLogPath: string | null,
+  indexDir: string = getIndexDir(),
+): void {
+  const db = openIndexStore(indexDir);
+  const now = Date.now();
+  db.prepare(
+    `INSERT INTO token_samples (session_id, repo_root, tokens, percent, ctx_window, ts)
+     VALUES (@session_id, @repo_root, @tokens, @percent, @ctx_window, @ts)`,
+  ).run({
+    session_id: sessionId,
+    repo_root: repoRoot,
+    tokens,
+    percent,
+    ctx_window: ctxWindow,
+    ts: now,
+  });
+  // Step 5: also append a session_sample JSON line to events.log so the
+  // existing /api/events SSE tail streams it for free (real-time chart push).
+  // Mirrors the DashboardEmitter events.log append pattern in
+  // extensions/mega-dashboard.ts:{ event(type, data) }: a JSON object with
+  // `ts` (ISO 8601 string), `type`, and the event-specific payload. The ISO
+  // timestamp matches the shape of every other SSE variant (SseSessionSample
+  // contract; every SSE variant's `ts` is a string); a numeric ms `ts` would
+  // violate the contract union's "every SSE variant has a ts field of type
+  // string" invariant and break DashboardEmitter consumers.
+  if (eventsLogPath) {
+    try {
+      const dir = eventsLogPath.includes("/") ? eventsLogPath.slice(0, eventsLogPath.lastIndexOf("/")) : ".";
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      appendFileSync(
+        eventsLogPath,
+        JSON.stringify({
+          ts: new Date(now).toISOString(),
+          type: "session_sample",
+          sessionId,
+          tokens,
+          percent,
+        }) + "\n",
+      );
+    } catch {
+      /* non-fatal: SSE push is best-effort */
+    }
+  }
+}
+
+/**
+ * Prune stale session heartbeats (sessions not seen within maxAgeMs).
+ * Default 30-min retention. Called by /api/sessions.
+ */
+export function pruneStaleSessions(
+  maxAgeMs: number = 1_800_000,
+  indexDir: string = getIndexDir(),
+): number {
+  const db = openIndexStore(indexDir);
+  const cutoff = Date.now() - maxAgeMs;
+  const result = db.prepare(
+    "DELETE FROM session_heartbeats WHERE last_seen < @cutoff",
+  ).run({ cutoff });
+  return Number(result.changes);
+}
+
+/**
+ * Prune old token samples older than maxAgeMs. Default 30-min retention.
+ * Called by /api/sessions/timeseries.
+ */
+export function pruneTokenSamples(
+  maxAgeMs: number = 1_800_000,
+  indexDir: string = getIndexDir(),
+): number {
+  const db = openIndexStore(indexDir);
+  const cutoff = Date.now() - maxAgeMs;
+  const result = db.prepare(
+    "DELETE FROM token_samples WHERE ts < @cutoff",
+  ).run({ cutoff });
+  return Number(result.changes);
+}
+
+/**
+ * Read all active sessions with their latest token sample (if any).
+ * JOINs session_heartbeats with the latest token_samples per session_id
+ * via a correlated subquery. Returns rows sorted by last_seen descending.
+ */
+export function readActiveSessions(
+  indexDir: string = getIndexDir(),
+): ActiveSessionRow[] {
+  const db = openIndexStore(indexDir);
+  const rows = db.prepare(
+    `SELECT h.pid, h.session_id, h.repo_root, h.state_dir, h.ctx_window, h.last_seen,
+            s.tokens, s.percent
+     FROM session_heartbeats h
+     LEFT JOIN token_samples s ON s.id = (
+       SELECT id FROM token_samples t
+       WHERE t.session_id = h.session_id
+       ORDER BY t.ts DESC LIMIT 1
+     )
+     ORDER BY h.last_seen DESC`,
+  ).all() as Array<{
+    pid: number;
+    session_id: string;
+    repo_root: string | null;
+    state_dir: string | null;
+    ctx_window: number;
+    last_seen: number;
+    tokens: number | null;
+    percent: number | null;
+  }>;
+  return rows.map((r) => ({
+    pid: r.pid,
+    sessionId: r.session_id,
+    repoRoot: r.repo_root,
+    stateDir: r.state_dir,
+    ctxWindow: r.ctx_window ?? 0,
+    lastSeen: r.last_seen,
+    tokens: r.tokens,
+    percent: r.percent,
+  }));
+}
+
+/**
+ * Read token samples since sinceMs, returning a recharts-ready stacked shape:
+ * per-session `SessionSeries` (with stable color) + a `totals` array
+ * [{ts, tokens}] (sum of all sessions at each timestamp).
+ */
+export function readSessionTimeseries(
+  sinceMs: number,
+  indexDir: string = getIndexDir(),
+): SessionTimeseriesResult {
+  const db = openIndexStore(indexDir);
+  const rows = db.prepare(
+    `SELECT session_id, tokens, percent, ts FROM token_samples WHERE ts >= @since ORDER BY ts ASC`,
+  ).all({ since: sinceMs }) as Array<{
+    session_id: string;
+    tokens: number;
+    percent: number;
+    ts: number;
+  }>;
+  // Group by session_id → series; + accumulate totals per timestamp.
+  const seriesMap = new Map<string, TokenSamplePoint[]>();
+  const totalsMap = new Map<number, number>();
+  for (const r of rows) {
+    let pts = seriesMap.get(r.session_id);
+    if (!pts) {
+      pts = [];
+      seriesMap.set(r.session_id, pts);
+    }
+    pts.push({ ts: r.ts, tokens: r.tokens, percent: r.percent });
+    totalsMap.set(r.ts, (totalsMap.get(r.ts) ?? 0) + r.tokens);
+  }
+  const series: SessionSeries[] = [];
+  for (const [sessionId, data] of seriesMap) {
+    const label = sessionId.length > 12 ? sessionId.slice(0, 12) : sessionId;
+    series.push({ sessionId, label, color: sessionColor(sessionId), data });
+  }
+  // Sort series by first-timestamp for stable legend order.
+  series.sort((a, b) => (a.data[0]?.ts ?? 0) - (b.data[0]?.ts ?? 0));
+  const totals = Array.from(totalsMap.entries())
+    .sort((a, b) => a[0] - b[0])
+    .map(([ts, tokens]) => ({ ts, tokens }));
+  return { series, totals };
+}
+
+/**
+ * Clear a session's heartbeat row (e.g. on clean shutdown / session reset).
+ * Non-fatal: no-op if the row doesn't exist.
+ */
+export function clearSessionHeartbeat(
+  pid: number,
+  sessionId: string,
+  indexDir: string = getIndexDir(),
+): void {
+  const db = openIndexStore(indexDir);
+  db.prepare(
+    "DELETE FROM session_heartbeats WHERE pid = @pid AND session_id = @session_id",
+  ).run({ pid, session_id: sessionId });
+}

package/dist/extensions/dashboard-client/src/hooks/useApi.js

@@ -1,51 +0,0 @@
-/**
- * dashboard-client/src/hooks/useApi.ts — Generic data fetching hook.
- *
- * Provides typed fetch with retry, stale detection, and error handling.
- * SPRINT-B1: basic fetch. SPRINT-D1: retry + stale.
- */
-import { useState, useEffect, useCallback, useRef } from 'react';
-// SPRINT-D1-REMAINING: integrate retryWithBackoff from utils/retry.ts.
-// SPRINT-D1-REMAINING: integrate staleness detection from utils/staleness.ts.
-// SPRINT-T1-REMAINING: add Authorization header when auth token present.
-export function useApi(fetchFn, options = {}) {
-    const { pollInterval = 0, maxRetries = 0 } = options;
-    const [data, setData] = useState(null);
-    const [error, setError] = useState(null);
-    const [loading, setLoading] = useState(true);
-    const [lastFetchedAt, setLastFetchedAt] = useState(null);
-    const mountedRef = useRef(true);
-    const doFetch = useCallback(async () => {
-        setLoading(true);
-        setError(null);
-        try {
-            const result = await fetchFn();
-            if (mountedRef.current) {
-                setData(result);
-                setLastFetchedAt(Date.now());
-            }
-        }
-        catch (err) {
-            if (mountedRef.current) {
-                setError(err instanceof Error ? err : new Error(String(err)));
-            }
-        }
-        finally {
-            if (mountedRef.current) {
-                setLoading(false);
-            }
-        }
-    }, [fetchFn]);
-    useEffect(() => {
-        mountedRef.current = true;
-        doFetch();
-        return () => { mountedRef.current = false; };
-    }, [doFetch]);
-    useEffect(() => {
-        if (pollInterval <= 0)
-            return;
-        const timer = setInterval(doFetch, pollInterval);
-        return () => clearInterval(timer);
-    }, [doFetch, pollInterval]);
-    return { data, error, loading, refetch: doFetch, lastFetchedAt };
-}

package/dist/extensions/dashboard-client/src/hooks/useSSE.js

@@ -1,63 +0,0 @@
-/**
- * dashboard-client/src/hooks/useSSE.ts — Server-Sent Events hook.
- *
- * Connects to /api/events, provides real-time event stream.
- * SPRINT-B1: basic connection. SPRINT-D1: reconnect with backoff.
- */
-import { useState, useEffect, useRef, useCallback } from 'react';
-// SPRINT-D1-REMAINING: exponential backoff (1s → 2s → 4s → max 30s).
-// SPRINT-D1-REMAINING: after 5 failures, set status='disconnected'.
-export function useSSE(options = {}) {
-    const { maxEvents = 500, maxReconnects = 5 } = options;
-    const [events, setEvents] = useState([]);
-    const [status, setStatus] = useState('connecting');
-    const [eventCount, setEventCount] = useState(0);
-    const [lastEventAt, setLastEventAt] = useState(null);
-    const reconnectCount = useRef(0);
-    const sourceRef = useRef(null);
-    const connect = useCallback(() => {
-        if (sourceRef.current) {
-            sourceRef.current.close();
-        }
-        setStatus('connecting');
-        const source = new EventSource('/api/events');
-        sourceRef.current = source;
-        source.onopen = () => {
-            setStatus('connected');
-            reconnectCount.current = 0;
-        };
-        source.onmessage = (event) => {
-            try {
-                const parsed = JSON.parse(event.data);
-                setEvents(prev => {
-                    const next = [...prev, parsed];
-                    return next.length > maxEvents ? next.slice(-maxEvents) : next;
-                });
-                setEventCount(c => c + 1);
-                setLastEventAt(Date.now());
-            }
-            catch {
-                // non-fatal: skip malformed events
-            }
-        };
-        source.onerror = () => {
-            source.close();
-            if (reconnectCount.current < maxReconnects) {
-                reconnectCount.current += 1;
-                setStatus('connecting');
-                // SPRINT-D1: use exponential backoff instead of fixed delay
-                setTimeout(connect, 1000);
-            }
-            else {
-                setStatus('disconnected');
-            }
-        };
-    }, [maxEvents, maxReconnects]);
-    useEffect(() => {
-        connect();
-        return () => {
-            sourceRef.current?.close();
-        };
-    }, [connect]);
-    return { events, status, eventCount, lastEventAt };
-}