feat(dashboard): live report stream via SSE with memory-safe lifecycle

Adds a GET /api/projects/:id/reports/:reportId/stream SSE endpoint that
pushes minimal {kind, payload} events to a browser tab open on the report
detail page. Every write-site — triage PATCH, comment create/edit/delete,
the issue_comment / issues.* webhook branches — publishes after DB commit.
The page's existing refresh() / activity refresh / comments refresh fans
out from a single handler wired through useEventSource, replacing the
20s comment-tab polling with immediate updates.

Memory-safety invariants (asserted by server/lib/report-events-bus.test.ts):
  - per-report subscriber cap (20) surfaces as 429 on excess
  - idempotent unsubscribe; empty Sets are deleted from the Map
  - listener mid-iteration unsubscribe is snapshot-safe
  - a throwing listener does not stop peers from receiving
  - dead listeners are lazy-reaped on next publish
  - SSE endpoint cleans up heartbeat + subscription via THREE paths:
    stream.onClosed, the underlying req 'close' event, and a self-
    eviction guard after LISTENER_FAILURE_THRESHOLD consecutive push
    failures — all routed through a single idempotent cleanup()
  - reconnect bounded to 10 attempts with 2s backoff (no forever loops)

Includes @vueuse/nuxt as a dependency for useEventSource.

Author: Ripwords

apps/dashboard/app/composables/use-report-stream.ts

@@ -0,0 +1,72 @@
+// apps/dashboard/app/composables/use-report-stream.ts
+//
+// Client-side subscription to the per-report SSE endpoint. Wraps VueUse's
+// `useEventSource` and invokes the caller's handler for each message.
+//
+// Memory-safety design:
+//   - `useEventSource` already teardowns the underlying EventSource on
+//     `onScopeDispose`, which Vue fires when the component's setup scope
+//     ends (route change, unmount). We additionally call `close()` in
+//     `onBeforeUnmount` as a belt-and-suspenders hook.
+//   - The `watch` we register on `data` is automatically disposed with the
+//     component's setup scope — no manual `stop()` needed, assuming the
+//     composable is only used inside `<script setup>` (the documented
+//     contract; Vue warns at runtime if called outside a setup context).
+//   - Reconnect is bounded: 10 retries with 2-second backoff. After that
+//     the stream goes silent rather than retrying forever. Users get the
+//     same data via the next page load or a manual refresh trigger.
+//   - Parse errors from malformed server payloads are swallowed — a bad
+//     single event must not tear down the stream.
+
+import { onBeforeUnmount, watch } from "vue"
+import { useEventSource } from "@vueuse/core"
+
+export type ReportStreamEvent = {
+  kind:
+    | "triage"
+    | "comment_added"
+    | "comment_edited"
+    | "comment_deleted"
+    | "github_synced"
+    | "github_unlinked"
+  payload?: Record<string, unknown>
+}
+
+export function useReportStream(
+  projectId: () => string,
+  reportId: () => string,
+  onEvent: (event: ReportStreamEvent) => void,
+) {
+  const url = computed(() => `/api/projects/${projectId()}/reports/${reportId()}/stream`)
+
+  const { data, status, close } = useEventSource(url, [], {
+    autoReconnect: {
+      retries: 10,
+      delay: 2_000,
+      onFailed() {
+        // Silent after bounded retries — a forever-retry loop burns battery
+        // on mobile clients and adds server load during outages.
+        console.warn("[report-stream] giving up after 10 reconnect attempts")
+      },
+    },
+  })
+
+  watch(data, (raw) => {
+    if (!raw) return
+    try {
+      const parsed = JSON.parse(raw) as ReportStreamEvent
+      onEvent(parsed)
+    } catch {
+      // Malformed payload — ignore rather than break the stream.
+    }
+  })
+
+  // useEventSource registers an onScopeDispose internally, but an extra
+  // close() on unmount is harmless (the library no-ops repeat closes) and
+  // keeps the lifecycle intent explicit at the call-site level.
+  onBeforeUnmount(() => {
+    close()
+  })
+
+  return { status }
+}

apps/dashboard/app/pages/projects/[id]/reports/[reportId].vue

@@ -114,6 +114,25 @@ async function onPatched() {
   if (commentsRef.value) await commentsRef.value.refresh()
 }
 
+// Live-update subscription: the SSE endpoint pushes an event every time this
+// report is touched (locally or via a GitHub webhook). Each event triggers the
+// same refetch used by the PATCH round-trip — the activity tab, triage
+// footer, and comments tab repaint from their new data.
+useReportStream(
+  () => projectId.value,
+  () => reportId.value,
+  async (e) => {
+    if (e.kind === "comment_added" || e.kind === "comment_edited" || e.kind === "comment_deleted") {
+      if (commentsRef.value) await commentsRef.value.refresh()
+      if (activityRef.value) await activityRef.value.refresh()
+      return
+    }
+    // triage / github_synced / github_unlinked all warrant a full refetch so
+    // the drawer's every tab reflects the new row state.
+    await onPatched()
+  },
+)
+
 const triageOpen = ref(false)
 
 // Keyboard shortcuts: 1-8 jump to each tab; Esc navigates back to the inbox.

apps/dashboard/nuxt.config.ts

@@ -2,7 +2,7 @@ import tailwindcss from "@tailwindcss/vite"
 
 export default defineNuxtConfig({
   compatibilityDate: "2026-04-17",
-  modules: ["@nuxt/ui", "@nuxt/fonts", "nuxt-security"],
+  modules: ["@nuxt/ui", "@nuxt/fonts", "nuxt-security", "@vueuse/nuxt"],
   css: ["~/assets/css/tailwind.css"],
   // Scan source at build time and bundle every `<UIcon>` / `i-*` reference
   // into the client JS. Without this, icons fall through to `@nuxt/icon`'s

apps/dashboard/package.json

@@ -22,6 +22,7 @@
     "@reprojs/integrations-github": "workspace:*",
     "@reprojs/shared": "workspace:*",
     "@tailwindcss/vite": "^4.2.1",
+    "@vueuse/nuxt": "14.2.1",
     "better-auth": "^1.5.6",
     "drizzle-orm": "^0.45.2",
     "h3": "^1.15.11",

apps/dashboard/server/api/integrations/github/webhook.post.ts

@@ -12,6 +12,7 @@ import {
 } from "../../../db/schema"
 import { getWebhookSecret } from "../../../lib/github"
 import { invalidateInstallationRepos } from "../../../lib/github-repo-cache"
+import { publishReportStream } from "../../../lib/report-events-bus"
 import { githubCache } from "../../../lib/github-cache"
 import { parseGithubLabels } from "../../../lib/github-helpers"
 import {
@@ -491,6 +492,11 @@ export default defineEventHandler(async (event) => {
           .where(eq(reports.id, linked.r.id))
       }
     }
+
+    // Regardless of which issues-sub-action landed (closed/reopened/labeled/
+    // unlabeled/assigned/unassigned/milestoned/demilestoned/edited), the
+    // dashboard row was touched — nudge any open SSE subscribers to refetch.
+    publishReportStream(linked.r.id, { kind: "triage", payload: { source: "github" } })
   } else if (kind === "issue_comment") {
     const p = payload as IssueCommentPayload
     const action = p.action
@@ -543,6 +549,10 @@ export default defineEventHandler(async (event) => {
           kind: "comment_added",
           payload: { githubCommentId: comment.id, source: "github" },
         })
+        publishReportStream(linked.r.id, {
+          kind: "comment_added",
+          payload: { source: "github", githubCommentId: comment.id },
+        })
       } else {
         // edited
         await db
@@ -556,6 +566,10 @@ export default defineEventHandler(async (event) => {
           kind: "comment_edited",
           payload: { githubCommentId: comment.id, source: "github" },
         })
+        publishReportStream(linked.r.id, {
+          kind: "comment_edited",
+          payload: { source: "github", githubCommentId: comment.id },
+        })
       }
     } else if (action === "deleted") {
       const commentDeleteSig = signCommentDelete(comment.id)
@@ -580,6 +594,10 @@ export default defineEventHandler(async (event) => {
         kind: "comment_deleted",
         payload: { githubCommentId: comment.id, source: "github" },
       })
+      publishReportStream(linked.r.id, {
+        kind: "comment_deleted",
+        payload: { source: "github", githubCommentId: comment.id },
+      })
     }
   }
 

apps/dashboard/server/api/projects/[id]/reports/[reportId]/comments/[commentId].delete.ts

@@ -5,6 +5,7 @@ import { db } from "../../../../../../db"
 import { reportComments } from "../../../../../../db/schema/report-comments"
 import { reportSyncJobs } from "../../../../../../db/schema/github-integrations"
 import { requireProjectRole } from "../../../../../../lib/permissions"
+import { publishReportStream } from "../../../../../../lib/report-events-bus"
 import { enqueueCommentDelete } from "../../../../../../lib/enqueue-sync"
 
 export default defineEventHandler(async (event) => {
@@ -64,6 +65,11 @@ export default defineEventHandler(async (event) => {
     }
   }
 
+  publishReportStream(reportId, {
+    kind: "comment_deleted",
+    payload: { commentId },
+  })
+
   setResponseStatus(event, 204)
   return null
 })

apps/dashboard/server/api/projects/[id]/reports/[reportId]/comments/[commentId].patch.ts

@@ -6,6 +6,7 @@ import { db } from "../../../../../../db"
 import { reportComments } from "../../../../../../db/schema/report-comments"
 import { reports } from "../../../../../../db/schema/reports"
 import { requireProjectRole } from "../../../../../../lib/permissions"
+import { publishReportStream } from "../../../../../../lib/report-events-bus"
 import { enqueueCommentUpsert } from "../../../../../../lib/enqueue-sync"
 
 const UpdateCommentBody = z.object({
@@ -62,5 +63,10 @@ export default defineEventHandler(async (event) => {
     }
   }
 
+  publishReportStream(reportId, {
+    kind: "comment_edited",
+    payload: { commentId },
+  })
+
   return { comment: updated }
 })

apps/dashboard/server/api/projects/[id]/reports/[reportId]/comments/index.post.ts

@@ -13,6 +13,7 @@ import { reportComments } from "../../../../../../db/schema/report-comments"
 import { reports } from "../../../../../../db/schema/reports"
 import { githubIntegrations } from "../../../../../../db/schema/github-integrations"
 import { requireProjectRole } from "../../../../../../lib/permissions"
+import { publishReportStream } from "../../../../../../lib/report-events-bus"
 import { enqueueCommentUpsert } from "../../../../../../lib/enqueue-sync"
 
 const CreateCommentBody = z.object({
@@ -55,6 +56,11 @@ export default defineEventHandler(async (event) => {
     }
   }
 
+  publishReportStream(reportId, {
+    kind: "comment_added",
+    payload: { commentId: inserted.id },
+  })
+
   setResponseStatus(event, 201)
   return { comment: inserted }
 })

apps/dashboard/server/api/projects/[id]/reports/[reportId]/index.patch.ts

@@ -12,6 +12,7 @@ import {
 } from "../../../../../db/schema"
 import { buildReportEvents } from "../../../../../lib/report-events"
 import { enqueueSync } from "../../../../../lib/enqueue-sync"
+import { publishReportStream } from "../../../../../lib/report-events-bus"
 import { compareRole, requireProjectRole } from "../../../../../lib/permissions"
 import type { ProjectRoleName } from "../../../../../lib/permissions"
 
@@ -253,6 +254,11 @@ export default defineEventHandler(async (event) => {
       }
     }
 
+    // Push the change to any open report-stream subscribers (SSE).
+    if (hasEvents) {
+      publishReportStream(reportId, { kind: "triage" })
+    }
+
     return { ok: true, updated: true }
   })
 })