feat(hub): agent_run_events 保留策略与尾部快照

[DeliciousBuding]

背景

宏观设计基线 PR #2065 §5 目标 5 要求「事件日志必须有 snapshot + retention」。当前 agent_run_events 表只有写入侧每任务上限（config.MaxRunEventsPerTask = 4096），没有任何保留策略清理——终态任务的事件行永久增长。

变更

任务 1: repository 清理查询

• 新增 hub-server/internal/repository/agent_run_event_retention.go
• PurgeTerminalRunEvents(db, cutoff, keepTail) — 单条 DELETE + 相关子查询，原子完成
• SQLite 单测 4 个：终态超窗 800→500 尾部保留、非终态不动、窗口内不动、keepTail=0 全删、负值报错

任务 2: service 编排 + 常量 + 指标

• 新增 hub-server/internal/service/agentevent/retention.go
  • DefaultRetentionWindow = 30d, DefaultKeepTail = 500, CleanupInterval = 24h
  • RunEventsRetentionPass(ctx, db, cfg) — 可被任何循环调用的入口函数
  • StartRunEventRetentionLoop(ctx, db, cfg) — 独立后台循环（参照 delivery outbox 模式）
• 新增 hub-server/internal/service/agentevent/metrics.go（promauto 自注册，不碰 Wave6 独占的 metrics.go）
  • agenthub_agent_run_events_retention_runs_total
  • agenthub_agent_run_events_retention_deleted_rows_total
  • agenthub_agent_run_events_retention_failures_total

任务 3: L1 集成测试（真 PG）

• 新增 hub-server/tests/integration/agent_run_event_retention_test.go
• TestAgentRunEventRetention_PurgesTerminalTail: 终态任务 800→500，非终态/窗口内不受影响
• TestAgentRunEventRetention_NonTerminalNegative: 显式负向用例，running 任务 100 条事件不受影响

任务 4: gates

• go vet ./... ✅
• 受影响包测试 ✅
• make test-hub-integration ✅
• python3 scripts/verify/verify-doc-ssot.py ✅
• git diff --check ✅

BLOCKED: background.go 接线

hub-server/internal/app/background.go 和 wiring.go 当前被孤儿恢复 lane 独占，本 lane 不碰。已提供可直接调用的入口函数 agentevent.StartRunEventRetentionLoop(ctx, db, cfg)，接线建议见 lane BLOCKED.md。

文件清单

仅新增文件，全部在白名单路径内：

• hub-server/internal/repository/agent_run_event_retention.go
• hub-server/internal/repository/agent_run_event_retention_test.go
• hub-server/internal/service/agentevent/retention.go
• hub-server/internal/service/agentevent/retention_test.go
• hub-server/internal/service/agentevent/metrics.go
• hub-server/tests/integration/agent_run_event_retention_test.go

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d1863d5d-ae41-4c9a-89e4-946d247eab22

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[DeliciousBuding]

captain 暗卷验收（独立复跑，2026-08-30）：

• 单测复跑：internal/repository + internal/service/agentevent 全绿（含负向：NonTerminalNegative / NoopWhenNoneQualify / KeepTailZeroDeletesAll / NegativeKeepTailErrors）
• L1 真 PG 集成复跑：TestAgentRunEventRetention_PurgesTerminalTail PASS (4.37s) + TestAgentRunEventRetention_NonTerminalNegative PASS（PG16 127.0.0.1:5432，-tags integration）
• diff 范围：6 个新增文件全在白名单，零既有文件改动
• background 接线延迟裁决正确：入口 agentevent.StartRunEventRetentionLoop 就绪，wiring.go 接线等 background.go 独占 lane（[P0 事件一致性] 切片 A：dispatch 业务写与 outbox 记录非同事务——崩溃/回退窗口任务静默丢失（审计 + 收口） #2066 A1）合流后由主线补

验收通过，等 CI + 管理员合并队列。

[DeliciousBuding]

主线裁决收口：BLOCKED 的 background 接线已补（本提交）——在 wiring.go Background goroutines 段 StartDeliveryCleanupLoop 之后接 StartRunEventRetentionLoop(a.bg.Ctx(), a.DB, DefaultRetentionConfig())，与 outbox cleanup 同模式。指标为 promauto 自注册无需额外 Register。go build/vet + app/agentevent 包测试绿。