feat(security): US4 collapse scan-notification storm into one settled event (Spec 077, MCP-2207) (#794)

* feat(security): debounce scan notifications into one settled event per server

Related #786

Spec 077 US4 (MCP-2207): the security-scan notification storm came from
per-scanner scan_started/progress/completed/failed SSE events multiplied by
reconnect storms (prior partial fixes: #659, MCP-2223). Replace those per-scanner
lifecycle emissions with a single debounced security.scan_settled event per
server per scan.

## Changes
- Add scanNotifyDebouncer (internal/runtime/scan_notify.go): terminal-triggered
  per-server debounce with a generation counter guarding the AfterFunc race;
  only completed/failed arm the timer, started/progress are dropped.
- Add EventTypeSecurityScanSettled; route runtime EmitSecurityScan* through the
  debouncer (started/progress become no-ops, completed/failed record terminal
  state) and publish one settled event carrying the terminal findings summary.
- Wire scanNotify (750ms) into newRuntime alongside the existing coalescer.
- Collapse the activity log to one handleSecurityScanSettled record per scan,
  removing the former started/completed/failed handlers.

## Testing
- scan_notify_test.go: a reconnect storm across N servers yields <= N settled
  events (exactly one per server) and zero per-scanner lifecycle events;
  settled event carries the terminal summary.

Related: Spec 077 (specs/077-scanner-simplification)

* feat(web-ui): consume debounced scan.settled event; drop per-scanner lifecycle

Related #786

Spec 077 US4 (MCP-2207): forward the new security.scan_settled SSE event from the
system store as a mcpproxy:scan-settled window event, and have
useSecurityScannerStatus refresh its cached scan totals off that single settled
signal instead of tracking per-scanner lifecycle events.

## Changes
- stores/system.ts: add a security.scan_settled SSE listener that dispatches
  mcpproxy:scan-settled.
- composables/useSecurityScannerStatus.ts: register a module-scope
  mcpproxy:scan-settled listener that triggers a status refresh.

## Testing
- frontend vue-tsc --noEmit clean; vite build succeeds.

Related: Spec 077 (specs/077-scanner-simplification)

Author: Dumbris

frontend/src/composables/useSecurityScannerStatus.ts

@@ -17,6 +17,18 @@ const totalFindings = ref<number>(0)
 const totalScans = ref<number>(0)
 let inflight: Promise<void> | null = null
 
+// Spec 077 US4 (MCP-2207): the backend now collapses the per-scanner
+// scan_started/progress/completed/failed storm into a single debounced
+// `security.scan_settled` event per server per scan (forwarded by the system
+// store as `mcpproxy:scan-settled`). We consume that one settled signal to
+// refresh the cached scan totals, instead of tracking per-scanner lifecycle
+// events. Registered once at module scope so all consumers share it.
+if (typeof window !== 'undefined') {
+  window.addEventListener('mcpproxy:scan-settled', () => {
+    void refreshSecurityScannerStatus()
+  })
+}
+
 export async function refreshSecurityScannerStatus(): Promise<void> {
   if (inflight) {
     return inflight

frontend/src/stores/system.ts

@@ -185,6 +185,19 @@ export const useSystemStore = defineStore('system', () => {
       }
     })
 
+    // Spec 077 US4 (MCP-2207): a single debounced settled event per server per
+    // scan replaces the per-scanner scan_started/progress/completed/failed
+    // storm. Forward it so scan-status consumers can refresh once per scan.
+    es.addEventListener('security.scan_settled', (event) => {
+      try {
+        const data = JSON.parse(event.data)
+        const payload = data.payload || data
+        window.dispatchEvent(new CustomEvent('mcpproxy:scan-settled', { detail: payload }))
+      } catch (error) {
+        console.error('Failed to parse SSE security.scan_settled event:', error)
+      }
+    })
+
     // Listen for activity events (tool calls, policy decisions, etc.)
     es.addEventListener('activity.tool_call.started', (event) => {
       try {

internal/runtime/activity_service.go

@@ -246,13 +246,10 @@ func (s *ActivityService) handleEvent(evt Event) {
 	// Spec 032: Tool-level quarantine events
 	case EventTypeActivityToolQuarantineChange:
 		s.handleToolQuarantineChange(evt)
-	// Spec 039: Security scan events
-	case EventTypeSecurityScanStarted:
-		s.handleSecurityScanStarted(evt)
-	case EventTypeSecurityScanCompleted:
-		s.handleSecurityScanCompleted(evt)
-	case EventTypeSecurityScanFailed:
-		s.handleSecurityScanFailed(evt)
+	// Spec 077 US4: one settled activity record per server per scan replaces the
+	// former per-scanner started/completed/failed storm (Spec 039).
+	case EventTypeSecurityScanSettled:
+		s.handleSecurityScanSettled(evt)
 	default:
 		// Ignore other event types
 	}
@@ -855,82 +852,39 @@ func (s *ActivityService) handleToolQuarantineChange(evt Event) {
 }
 
 // handleSecurityScanStarted records a security scan start event (Spec 039).
-func (s *ActivityService) handleSecurityScanStarted(evt Event) {
-	serverName := getStringPayload(evt.Payload, "server_name")
-	jobID := getStringPayload(evt.Payload, "job_id")
-
-	metadata := map[string]interface{}{
-		"job_id": jobID,
-	}
-	if scanners := evt.Payload["scanners"]; scanners != nil {
-		metadata["scanners"] = scanners
-	}
-
-	record := &storage.ActivityRecord{
-		Type:       storage.ActivityTypeSecurityScan,
-		Source:     storage.ActivitySourceInternal,
-		ServerName: serverName,
-		ToolName:   "security_scan",
-		Status:     "started",
-		Timestamp:  evt.Timestamp,
-		Metadata:   metadata,
-	}
-
-	if err := s.storage.SaveActivity(record); err != nil {
-		s.logger.Error("Failed to save security scan started activity",
-			zap.String("server", serverName),
-			zap.Error(err))
-	}
-}
-
-// handleSecurityScanCompleted records a security scan completion event (Spec 039).
-func (s *ActivityService) handleSecurityScanCompleted(evt Event) {
+// handleSecurityScanSettled records the single settled scan result per server
+// per scan (Spec 077 US4, MCP-2207). It replaces the former started/completed/
+// failed handlers so the activity log carries one entry per scan instead of a
+// per-scanner storm.
+func (s *ActivityService) handleSecurityScanSettled(evt Event) {
 	serverName := getStringPayload(evt.Payload, "server_name")
+	scanStatus := getStringPayload(evt.Payload, "status")
+	errMsg := getStringPayload(evt.Payload, "error")
 
 	metadata := map[string]interface{}{}
 	if findingsSummary := getMapPayload(evt.Payload, "findings_summary"); findingsSummary != nil {
 		metadata["findings_summary"] = findingsSummary
 	}
-	if jobID := getStringPayload(evt.Payload, "job_id"); jobID != "" {
-		metadata["job_id"] = jobID
-	}
-
-	record := &storage.ActivityRecord{
-		Type:       storage.ActivityTypeSecurityScan,
-		Source:     storage.ActivitySourceInternal,
-		ServerName: serverName,
-		ToolName:   "security_scan",
-		Status:     "success",
-		Timestamp:  evt.Timestamp,
-		Metadata:   metadata,
-	}
 
-	if err := s.storage.SaveActivity(record); err != nil {
-		s.logger.Error("Failed to save security scan completed activity",
-			zap.String("server", serverName),
-			zap.Error(err))
+	// Map the scan's terminal state onto the activity record status.
+	status := "success"
+	if scanStatus == "failed" {
+		status = "error"
 	}
-}
-
-// handleSecurityScanFailed records a security scan failure event (Spec 039).
-func (s *ActivityService) handleSecurityScanFailed(evt Event) {
-	serverName := getStringPayload(evt.Payload, "server_name")
-	scannerID := getStringPayload(evt.Payload, "scanner_id")
-	errMsg := getStringPayload(evt.Payload, "error")
 
 	record := &storage.ActivityRecord{
 		Type:         storage.ActivityTypeSecurityScan,
 		Source:       storage.ActivitySourceInternal,
 		ServerName:   serverName,
 		ToolName:     "security_scan",
-		Status:       "error",
+		Status:       status,
 		ErrorMessage: errMsg,
 		Timestamp:    evt.Timestamp,
-		Metadata:     map[string]interface{}{"scanner_id": scannerID},
+		Metadata:     metadata,
 	}
 
 	if err := s.storage.SaveActivity(record); err != nil {
-		s.logger.Error("Failed to save security scan failed activity",
+		s.logger.Error("Failed to save settled security scan activity",
 			zap.String("server", serverName),
 			zap.Error(err))
 	}

internal/runtime/event_bus.go

@@ -585,44 +585,54 @@ func (r *Runtime) EmitSensitiveDataDetected(activityID string, detectionCount in
 	r.publishEvent(newEvent(EventTypeSensitiveDataDetected, payload))
 }
 
-// EmitSecurityScanStarted emits an event when a security scan begins (Spec 039).
-func (r *Runtime) EmitSecurityScanStarted(serverName string, scanners []string, jobID string) {
-	payload := map[string]any{
-		"server_name": serverName,
-		"scanners":    scanners,
-		"job_id":      jobID,
+// EmitSecurityScanStarted feeds the scan-notification debouncer (Spec 077 US4,
+// MCP-2207). The started signal is intentionally dropped: it is part of the
+// per-scanner storm the debouncer collapses. The service still invalidates its
+// summary cache independently so the UI shows "scanning" while the scan runs.
+func (r *Runtime) EmitSecurityScanStarted(serverName string, _ []string, _ string) {
+	// No-op for notifications: a single settled event replaces the whole
+	// per-scanner lifecycle. Kept to satisfy the scanner EventEmitter contract.
+	_ = serverName
+}
+
+// EmitSecurityScanProgress is dropped: intermediate per-scanner progress is the
+// noise the settled-event model eliminates (Spec 077 US4).
+func (r *Runtime) EmitSecurityScanProgress(_, _, _ string, _ int) {}
+
+// EmitSecurityScanCompleted records a terminal scan result for the debouncer,
+// which publishes exactly one settled event per server per scan (Spec 077 US4).
+func (r *Runtime) EmitSecurityScanCompleted(serverName string, findingsSummary map[string]int) {
+	if r.scanNotify != nil {
+		r.scanNotify.noteTerminal(serverName, "completed", findingsSummary, "")
+		return
 	}
-	r.publishEvent(newEvent(EventTypeSecurityScanStarted, payload))
+	// Fallback (no debouncer wired, e.g. some tests): publish directly so the
+	// terminal result is not silently lost.
+	r.publishScanSettled(serverName, "completed", findingsSummary, "")
 }
 
-// EmitSecurityScanProgress emits an event for scanner progress updates (Spec 039).
-func (r *Runtime) EmitSecurityScanProgress(serverName, scannerID, status string, progress int) {
-	payload := map[string]any{
-		"server_name": serverName,
-		"scanner_id":  scannerID,
-		"status":      status,
-		"progress":    progress,
+// EmitSecurityScanFailed records a terminal failure for the debouncer. Under
+// Spec 077 the baseline verdict is derived elsewhere; here we only ensure the
+// storm still collapses to a single settled event (Spec 077 US4).
+func (r *Runtime) EmitSecurityScanFailed(serverName, _, errMsg string) {
+	if r.scanNotify != nil {
+		r.scanNotify.noteTerminal(serverName, "failed", nil, errMsg)
+		return
 	}
-	r.publishEvent(newEvent(EventTypeSecurityScanProgress, payload))
+	r.publishScanSettled(serverName, "failed", nil, errMsg)
 }
 
-// EmitSecurityScanCompleted emits an event when a security scan completes (Spec 039).
-func (r *Runtime) EmitSecurityScanCompleted(serverName string, findingsSummary map[string]int) {
+// publishScanSettled emits the single debounced terminal scan event.
+func (r *Runtime) publishScanSettled(serverName, status string, findingsSummary map[string]int, errMsg string) {
 	payload := map[string]any{
 		"server_name":      serverName,
+		"status":           status,
 		"findings_summary": findingsSummary,
 	}
-	r.publishEvent(newEvent(EventTypeSecurityScanCompleted, payload))
-}
-
-// EmitSecurityScanFailed emits an event when a scanner fails (Spec 039).
-func (r *Runtime) EmitSecurityScanFailed(serverName, scannerID, errMsg string) {
-	payload := map[string]any{
-		"server_name": serverName,
-		"scanner_id":  scannerID,
-		"error":       errMsg,
+	if errMsg != "" {
+		payload["error"] = errMsg
 	}
-	r.publishEvent(newEvent(EventTypeSecurityScanFailed, payload))
+	r.publishEvent(newEvent(EventTypeSecurityScanSettled, payload))
 }
 
 // EmitSecurityIntegrityAlert emits an event for integrity violations (Spec 039).

internal/runtime/events.go

@@ -60,6 +60,11 @@ const (
 	EventTypeSecurityScanCompleted EventType = "security.scan_completed"
 	// EventTypeSecurityScanFailed is emitted when a scanner fails.
 	EventTypeSecurityScanFailed EventType = "security.scan_failed"
+	// EventTypeSecurityScanSettled is the single, debounced terminal event that
+	// Spec 077 US4 (MCP-2207) emits per server per scan. It collapses the
+	// per-scanner scan_started/progress/completed/failed storm — including
+	// repeats from reconnect storms — into one settled result.
+	EventTypeSecurityScanSettled EventType = "security.scan_settled"
 	// EventTypeSecurityIntegrityAlert is emitted for integrity violations.
 	EventTypeSecurityIntegrityAlert EventType = "security.integrity_alert"
 	// EventTypeSecurityScannerChanged is emitted when a scanner plugin's state

internal/runtime/runtime.go

@@ -89,6 +89,10 @@ type Runtime struct {
 	// GET /api/v1/servers.
 	coalescer *serversChangedCoalescer
 
+	// Spec 077 US4 (MCP-2207): debounces the per-scanner security-scan
+	// lifecycle storm into one settled event per server per scan.
+	scanNotify *scanNotifyDebouncer
+
 	// Phase 6: Supervisor for state reconciliation (lock-free reads via StateView)
 	supervisor *supervisor.Supervisor
 
@@ -282,6 +286,11 @@ func New(cfg *config.Config, cfgPath string, logger *zap.Logger) (*Runtime, erro
 	rt.coalescer = newServersChangedCoalescer(rt, 50*time.Millisecond)
 	rt.coalescer.start(appCtx)
 
+	// Spec 077 US4 (MCP-2207): collapse the per-scanner scan-notification storm
+	// into one settled event per server. 750ms bridges the rapid lifecycle
+	// signals of a reconnect storm without noticeably delaying the result.
+	rt.scanNotify = newScanNotifyDebouncer(rt, 750*time.Millisecond)
+
 	return rt, nil
 }
 

internal/runtime/scan_notify.go

@@ -0,0 +1,101 @@
+package runtime
+
+import (
+	"sync"
+	"time"
+)
+
+// scanNotifyDebouncer collapses the per-scanner security-scan lifecycle storm
+// into a single debounced "settled" event per server per scan (Spec 077 US4,
+// MCP-2207). Prior partial fixes (#659, MCP-2223) trimmed individual event
+// classes but the reconnect-storm × per-scanner multiplication remained: every
+// reconnect re-ran the full scan_started/progress/completed lifecycle for every
+// enabled scanner, flooding SSE subscribers.
+//
+// The model here is deliberately terminal-triggered: only terminal signals
+// (scan completed / scan failed) arm the per-server debounce timer; the noisy
+// started/progress signals are dropped entirely. Each terminal signal for a
+// server (re)arms a short timer; when the timer finally fires quietly, exactly
+// one EventTypeSecurityScanSettled is published carrying the last-known terminal
+// state. A reconnect storm across N servers therefore yields at most N settled
+// events (one per server), satisfying FR-015/SC-006.
+//
+// Concurrency: a per-server generation counter guards against the classic
+// AfterFunc race where a timer that has already fired blocks on the mutex while
+// a fresh signal re-arms — only the flush whose generation still matches the
+// latest signal is allowed to publish, so a superseded timer is a no-op.
+type scanNotifyDebouncer struct {
+	rt       *Runtime
+	interval time.Duration
+
+	mu      sync.Mutex
+	pending map[string]*pendingScan
+}
+
+// pendingScan holds the debounced terminal state for one server between the
+// last terminal signal and the settled publish.
+type pendingScan struct {
+	gen     uint64
+	timer   *time.Timer
+	status  string         // "completed" | "failed"
+	summary map[string]int // findings-by-severity from the last completed scan
+	errMsg  string         // last error, when status == "failed"
+}
+
+func newScanNotifyDebouncer(rt *Runtime, interval time.Duration) *scanNotifyDebouncer {
+	return &scanNotifyDebouncer{
+		rt:       rt,
+		interval: interval,
+		pending:  make(map[string]*pendingScan),
+	}
+}
+
+// noteTerminal records a terminal scan signal for a server and (re)arms the
+// debounce timer. Non-nil summaries and non-empty statuses/errors overwrite the
+// prior state last-write-wins, so the eventual settled event reflects the most
+// recent scan in a storm.
+func (d *scanNotifyDebouncer) noteTerminal(server, status string, summary map[string]int, errMsg string) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	p := d.pending[server]
+	if p == nil {
+		p = &pendingScan{}
+		d.pending[server] = p
+	}
+	if status != "" {
+		p.status = status
+	}
+	if summary != nil {
+		p.summary = summary
+	}
+	if errMsg != "" {
+		p.errMsg = errMsg
+	}
+
+	p.gen++
+	gen := p.gen
+	if p.timer != nil {
+		p.timer.Stop()
+	}
+	p.timer = time.AfterFunc(d.interval, func() { d.flush(server, gen) })
+}
+
+// flush publishes the single settled event for a server, but only if no newer
+// terminal signal has superseded the timer that scheduled this flush.
+func (d *scanNotifyDebouncer) flush(server string, gen uint64) {
+	d.mu.Lock()
+	p := d.pending[server]
+	if p == nil || p.gen != gen {
+		// Superseded by a newer signal (or already flushed) — do nothing.
+		d.mu.Unlock()
+		return
+	}
+	delete(d.pending, server)
+	status := p.status
+	summary := p.summary
+	errMsg := p.errMsg
+	d.mu.Unlock()
+
+	d.rt.publishScanSettled(server, status, summary, errMsg)
+}