Harden production workflows and agent admission

agent/internal/spool/spool.go

@@ -24,10 +24,19 @@ type Spool struct {
 	maxEvents int
 	maxBytes  int64
 
-	mu      sync.Mutex
-	nextSeq uint64
-	files   []entry // sorted ascending by seq
-	bytes   int64
+	mu         sync.Mutex
+	nextSeq    uint64
+	files      []entry // sorted ascending by seq
+	bytes      int64
+	dropEvents int
+	dropBytes  int
+}
+
+// DropStats reports events dropped due to bounded-spool overflow since the
+// previous call to Drops. Counters are reset on read.
+type DropStats struct {
+	OverflowEvents int
+	OverflowBytes  int
 }
 
 type entry struct {
@@ -135,13 +144,31 @@ func (s *Spool) dropOldestLocked() {
 		if len(s.files) == 0 {
 			return
 		}
+		byCount := len(s.files) > s.maxEvents
 		old := s.files[0]
 		_ = os.Remove(filepath.Join(s.dir, old.name))
 		s.bytes -= old.size
 		s.files = s.files[1:]
+		if byCount {
+			s.dropEvents++
+		} else {
+			s.dropBytes++
+		}
 	}
 }
 
+// Drops returns and resets the count of events dropped due to overflow since
+// the previous call. Callers use this to feed bounded-cardinality metrics and
+// throttled logs without spamming on every Enqueue.
+func (s *Spool) Drops() DropStats {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	d := DropStats{OverflowEvents: s.dropEvents, OverflowBytes: s.dropBytes}
+	s.dropEvents = 0
+	s.dropBytes = 0
+	return d
+}
+
 // Peek returns up to limit oldest items. Does not remove them.
 func (s *Spool) Peek(limit int) ([]Item, error) {
 	s.mu.Lock()