feat(agent-workspace): add notification delivery observability

Author: Jacobinwwey

docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md

@@ -557,6 +557,36 @@ Deliverables:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+### M7.18 (Now): Notification Delivery Hardening and Suppression Observability (Lane Ops Bridge)
+
+Deliverables:
+
+- persist a bounded delivery trail for reminder and digest notification channels.
+- expose a bounded notification-log route with delivery/suppression summary counters.
+- keep suppression state inspectable without replaying route side effects.
+
+#### M7.18 Progress Note (2026-04-16)
+
+- [Done] expanded `src/server.ts` with notification delivery observability surface:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications?limit=...`.
+- [Done] added bounded notification delivery persistence:
+  - `agent_workspace_diagnostics/triage_remediation_escalation_notifications.v1.json` now stores emitted reminder deliveries, suppressed reminder deliveries, and digest throttling/emission events.
+- [Done] hardened notification governance output:
+  - `/triage/remediation/escalation/notification-policy` now includes `notificationSummary`,
+  - `/triage/remediation/escalation/reminders` and `/digest` now append delivery trail entries after dispatch/suppression decisions.
+- [Done] added deterministic helper stack:
+  - `readAgentWorkspaceDiagnosticsRemediationEscalationNotificationTrail(...)`,
+  - `appendAgentWorkspaceDiagnosticsRemediationEscalationNotificationEntries(...)`,
+  - `buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationSummary(...)`.
+- [Done] expanded evidence coverage:
+  - `src/server.migration.test.ts` now validates notification trail route semantics, summary counters, suppression-reason visibility, and persisted notification file contents.
+  - `src/knowledge.api.contract.test.ts` now fail-fast checks notification-log route contract.
+  - `src/agent_workspace.verification.contract.test.ts` + `scripts/verify-agent-workspace-runtime.js` now fail fast on notification-log route and helper drift.
+- [Done] verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern "escalation notification-policy, digest cadence, and reminder suppression stay deterministic|escalation notification delivery trail and suppression observability stay deterministic"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## Success Criteria
 
 - CI failure mode that previously blocked the three agent-workspace suites is eliminated on mainline.
@@ -566,4 +596,4 @@ Deliverables:
 
 ## Next Step
 
-Proceed to `/prompts:ce-plan` using this document as the source for `M7.18` decomposition (escalation notification delivery hardening and suppression-observability expansion), while preserving M7 lane boundary constraints.
+Proceed to `/prompts:ce-plan` using this document as the source for `M7.19` decomposition (notification delivery health auditing and stale-notification cleanup), while preserving M7 lane boundary constraints.

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -544,6 +544,24 @@ Execution anchor:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## Latest Mainline Increment (2026-04-16 M7.18 Notification Delivery Hardening and Suppression Observability Lane)
+
+- Expanded `src/server.ts` with bounded delivery observability route:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications?limit=...`.
+- Added deterministic delivery-trail persistence:
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notifications.v1.json` now stores emitted reminder deliveries, suppressed reminder events, and digest throttle/emission events.
+- Hardened notification governance output:
+  - `/triage/remediation/escalation/notification-policy` now includes `notificationSummary`,
+  - reminder and digest routes now append delivery-trail entries after policy decisions.
+- Expanded executable evidence:
+  - `src/server.migration.test.ts` now validates notification log route semantics, by-channel/by-status summary counters, suppression-reason visibility, and persisted delivery-log contents.
+- Hardened runtime verification gate:
+  - `src/knowledge.api.contract.test.ts`, `src/agent_workspace.verification.contract.test.ts`, and `scripts/verify-agent-workspace-runtime.js` now fail fast on notification-log route and helper drift.
+- Verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification-policy, digest cadence, and reminder suppression stay deterministic|escalation notification delivery trail and suppression observability stay deterministic\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## Mainline vs Working-Branch Snapshot (2026-04-14)
 
 | Capability Slice | Working Branch (`feat/learning-multi-tutor-adapter`) | Mainline (`origin/main`) | Integration Status |
@@ -592,7 +610,7 @@ This dashboard aligns against the following requirement chain:
 | L2 Retrieval | explainable hybrid/vector retrieval + governance | Expanded in branch-oriented plans | Mainline file-backed baseline only (`src/learning/store.ts`) | Re-enter lane after concrete module evidence lands on mainline |
 | L3 Learning | mastery diagnostics + path/session loop | Expanded in branch | Partially integrated | Contract and integration parity |
 | L4 Interaction | agent conversation + focus/path pane runtime | Implemented in branch | M1-M4 baseline integrated on mainline | Expand capability surface via typed contract only |
-| L5 Governance | runbook, diagnostics, replay/autonomy controls | Expanded in branch | Operator diagnostics persistence/triage/history/threshold governance + runbook automation/audit + adaptive simulation/remediation + remediation backtest/approval-gate + approval-policy hardening/regression-alarms + approval-policy drift/escalation + escalation acknowledgement lifecycle/audit + escalation SLA/reminder baseline + notification digest/suppression baseline integrated | M7.18: delivery-channel hardening and suppression observability |
+| L5 Governance | runbook, diagnostics, replay/autonomy controls | Expanded in branch | Operator diagnostics persistence/triage/history/threshold governance + runbook automation/audit + adaptive simulation/remediation + remediation backtest/approval-gate + approval-policy hardening/regression-alarms + approval-policy drift/escalation + escalation acknowledgement lifecycle/audit + escalation SLA/reminder baseline + notification digest/suppression baseline + delivery-log observability integrated | M7.19: delivery-health auditing and stale-notification cleanup |
 
 ## Verification Baseline
 

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -546,6 +546,24 @@
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## 主线最新增量（2026-04-16 M7.18 通知交付链路硬化与抑制可观测性链路）
+
+- 已在 `src/server.ts` 增加有界通知交付可观测路由：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications?limit=...`。
+- 已新增确定性交付轨迹持久化工件：
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notifications.v1.json` 持久化 reminder 已发送、reminder 已抑制、digest 已发送与 digest 节流事件。
+- 已硬化通知治理输出：
+  - `/triage/remediation/escalation/notification-policy` 新增 `notificationSummary`，
+  - reminder 与 digest 路由在完成策略判定后会追加交付轨迹记录。
+- 已补可执行证据：
+  - `src/server.migration.test.ts` 新增通知日志路由语义、按 channel/status 聚合计数、抑制原因可见性与交付日志落盘断言。
+- 已加固 runtime 门禁：
+  - `src/knowledge.api.contract.test.ts`、`src/agent_workspace.verification.contract.test.ts` 与 `scripts/verify-agent-workspace-runtime.js` 新增 notification-log 路由与 helper 的 fail-fast 断言。
+- 验证证据：
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification-policy, digest cadence, and reminder suppression stay deterministic|escalation notification delivery trail and suppression observability stay deterministic\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
@@ -594,7 +612,7 @@
 | L2 检索层 | 可解释混合/向量检索 + 治理 | 分支规划增强中 | 主线当前为 file-backed 基线（`src/learning/store.ts`） | 待主线出现对应模块证据后再收敛 |
 | L3 学习层 | 掌握诊断 + 路径/会话闭环 | 分支增强中 | 主线部分集成 | 契约与集成一致性 |
 | L4 交互层 | agent 对话 + focus/path pane 运行时 | 分支已实现 | 主线 M1-M4 已落入基线 | 继续通过 typed contract 扩展动作面 |
-| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警 + 批准策略漂移/升级 + 升级确认生命周期/审计 + 升级 SLA/提醒基线 + 通知摘要/抑制基线 | M7.18：通知交付链路硬化与抑制可观测性扩展 |
+| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警 + 批准策略漂移/升级 + 升级确认生命周期/审计 + 升级 SLA/提醒基线 + 通知摘要/抑制基线 + 交付日志可观测性 | M7.19：通知交付健康审计与陈旧通知清理 |
 
 ## 验证基线
 

scripts/verify-agent-workspace-runtime.js

@@ -160,6 +160,10 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-policy'),
     'Missing diagnostics remediation escalation notification policy route in src/server.ts'
   );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications'),
+    'Missing diagnostics remediation escalation notifications route in src/server.ts'
+  );
   assert(
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/digest'),
     'Missing diagnostics remediation escalation digest route in src/server.ts'
@@ -272,6 +276,18 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('recordAgentWorkspaceDiagnosticsRemediationEscalationDigestDispatch'),
     'Missing remediation escalation digest dispatch recorder in src/server.ts'
   );
+  assert(
+    serverSource.includes('readAgentWorkspaceDiagnosticsRemediationEscalationNotificationTrail'),
+    'Missing remediation escalation notification trail reader in src/server.ts'
+  );
+  assert(
+    serverSource.includes('appendAgentWorkspaceDiagnosticsRemediationEscalationNotificationEntries'),
+    'Missing remediation escalation notification trail writer in src/server.ts'
+  );
+  assert(
+    serverSource.includes('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationSummary'),
+    'Missing remediation escalation notification summary helper in src/server.ts'
+  );
   assert(
     serverSource.includes('applyAgentWorkspaceDiagnosticsRemediationEscalationReminderSuppressionPolicy'),
     'Missing remediation escalation reminder suppression policy helper in src/server.ts'
@@ -339,14 +355,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
       'diagnostics remediation policy drift route exists',
       'diagnostics remediation escalation route exists',
       'diagnostics remediation escalation SLA/reminder routes exist',
-      'diagnostics remediation escalation notification policy and digest routes exist',
+      'diagnostics remediation escalation notification policy, log, and digest routes exist',
       'diagnostics remediation escalation acknowledgement routes exist',
       'diagnostics remediation approval routes exist',
       'diagnostics triage remediation route exists',
       'diagnostics retention governance exists',
       'diagnostics alert-threshold governance helpers exist',
       'diagnostics threshold simulation, drift, remediation, escalation, and SLA helpers exist',
-      'diagnostics escalation notification, digest cadence, and reminder suppression helpers exist',
+      'diagnostics escalation notification, digest cadence, reminder suppression, and delivery-log helpers exist',
       'diagnostics remediation policy and alarm helpers exist',
       'diagnostics threshold audit helpers exist',
       'diagnostics remediation approval trail helpers exist',

src/agent_workspace.verification.contract.test.ts

@@ -63,6 +63,7 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/sla');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/reminders');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-policy');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/digest');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/acknowledge');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approvals');
@@ -89,6 +90,9 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationSlaReport');
     expect(runtimeSource).toContain('getAgentWorkspaceDiagnosticsRemediationEscalationNotificationPolicy');
     expect(runtimeSource).toContain('recordAgentWorkspaceDiagnosticsRemediationEscalationDigestDispatch');
+    expect(runtimeSource).toContain('readAgentWorkspaceDiagnosticsRemediationEscalationNotificationTrail');
+    expect(runtimeSource).toContain('appendAgentWorkspaceDiagnosticsRemediationEscalationNotificationEntries');
+    expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationSummary');
     expect(runtimeSource).toContain('applyAgentWorkspaceDiagnosticsRemediationEscalationReminderSuppressionPolicy');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationGovernanceContext');
     expect(runtimeSource).toContain('acknowledgeAgentWorkspaceDiagnosticsRemediationEscalation');

src/knowledge.api.contract.test.ts

@@ -27,6 +27,7 @@ describe('Knowledge mastery API contract wiring', () => {
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/sla',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/reminders',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-policy',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/digest',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/acknowledge',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approvals',