feat(health): Phase 689 health-mixin, spans, and handoff clear (v0.8.664)

Add health-mixin gossip dedupe and partition heal hooks; extend
getAutomationHealthDashboard automation.health spans; clearDigestRelayHandoffs
and digestRelayHandoffDuplicateAt view flag; openHealth deep link field.

Co-authored-by: Cursor <[email protected]>

README.md

@@ -2,6 +2,8 @@
 
 Application facade: one `PearcordPlatform` class that wires identity, database, guild mesh, DMs, invites, voice, discovery, bots, and dozens of feature modules for the Pearcord desktop sidecar and companion.
 
+**Phase 689 (v0.8.664):** Integration health dashboard — `health-mixin.js`, `automation.health` spans (`guildHealthRowCount`), digest relay handoff gossip dedupe, `_healScheduleDashboardOnPartition` + `_healArchivePeerCursorOnPartition`, `clearDigestRelayHandoffs`, deep link `openHealth`. Bundle: `npm run test:ci-phase689`.
+
 **Phase 688 (v0.8.663):** Hook delivery receipts & failure digest — `delivery-mixin.js`, receipt gossip dedupe, `_healReceiptRegistryOnPartition` + `_healFailureDigestCursorOnPartition`, `guildReceiptCount`/`bridgeKind` span metadata, `clearAutomationDeliveryReceipts`, deep link `openReceipts`. Bundle: `npm run test:ci-phase688`.
 
 **Phase 687 (v0.8.662):** Integration workers & headless bridge — `workers-mixin.js`, worker trial/release gossip dedupe, `_healWorkerRegistryOnPartition` + `_healWorkerTrialCursorOnPartition`, `guildWorkerCount`/`bridgeKind` span metadata, deep link `openWorkers`. Bundle: `npm run test:ci-phase687`.

health-mixin.js

@@ -0,0 +1,103 @@
+'use strict'
+
+const healthMixin = {
+  _digestRelayHandoffGossipKeys: null,
+  _scheduleDashboardHealWatermark: null,
+  _archivePeerHealWatermark: null,
+
+  _initHealthMixinState () {
+    if (!this._digestRelayHandoffGossipKeys) {
+      this._digestRelayHandoffGossipKeys = new Set()
+    }
+  },
+
+  _shouldGossipDigestRelayHandoff (slice) {
+    this._initHealthMixinState()
+    if (!slice?.guildId || !slice?.exportedAt) return true
+    const hash = `${slice.guildId}:${slice.exportedAt}:${slice.snapshotId || ''}:${slice.transport || ''}:${slice.signature || ''}`
+    if (this._digestRelayHandoffGossipKeys.has(hash)) return false
+    this._digestRelayHandoffGossipKeys.add(hash)
+    if (this._digestRelayHandoffGossipKeys.size > 8192) {
+      const first = this._digestRelayHandoffGossipKeys.values().next().value
+      if (first) this._digestRelayHandoffGossipKeys.delete(first)
+    }
+    return true
+  },
+
+  async _healScheduleDashboardOnPartition (guildId) {
+    const gid = guildId || this.guild?.guild?.id || null
+    const span = this.log.time('automation.health', {
+      spanKind: 'automation.health',
+      guildId: gid,
+      context: 'heal.schedule'
+    })
+    try {
+      if (!gid || !this.getAutomationHealthDashboard) {
+        span.end({ relisted: 0, skipped: true, guildHealthRowCount: 0 })
+        return { relisted: 0, skipped: true }
+      }
+      const dash = await this.getAutomationHealthDashboard()
+      const watermark = Date.now()
+      this._scheduleDashboardHealWatermark = watermark
+      const rowCount = (dash.overdueActions || []).length + (dash.auditExport ? 1 : 0) + (dash.digestSync ? 1 : 0)
+      span.end({
+        relisted: 1,
+        watermark,
+        guildHealthRowCount: rowCount,
+        anyOverdue: !!dash.anyOverdue,
+        bridgeKind: 'automation.health'
+      })
+      return { relisted: 1, watermark, guildHealthRowCount: rowCount }
+    } catch (err) {
+      this.log.error('automation.health error', {
+        guildId: gid,
+        context: 'heal.schedule',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      return { relisted: 0, error: err?.message || String(err) }
+    }
+  },
+
+  async _healArchivePeerCursorOnPartition (guildId) {
+    const gid = guildId || this.guild?.guild?.id || null
+    const span = this.log.time('automation.health', {
+      spanKind: 'automation.health',
+      guildId: gid,
+      context: 'heal.archive'
+    })
+    try {
+      if (!gid) {
+        span.end({ relisted: 0, skipped: true, guildHealthRowCount: 0 })
+        return { relisted: 0, skipped: true }
+      }
+      const watermark = Date.now()
+      this._archivePeerHealWatermark = watermark
+      const dash = await this.getAutomationHealthDashboard().catch(() => ({}))
+      span.end({
+        relisted: 0,
+        watermark,
+        guildHealthRowCount: (dash.health?.archivePeers || []).length,
+        avgArchivePeerScore: dash.health?.avgArchivePeerScore || 0,
+        guildCount: (this.guilds || []).length,
+        activeChannelId: this.activeChannelId || null,
+        bridgeKind: 'automation.health'
+      })
+      return {
+        relisted: 0,
+        watermark,
+        guildHealthRowCount: (dash.health?.archivePeers || []).length
+      }
+    } catch (err) {
+      this.log.error('automation.health error', {
+        guildId: gid,
+        context: 'heal.archive',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      return { relisted: 0, error: err?.message || String(err) }
+    }
+  }
+}
+
+module.exports = { healthMixin }

index.js

@@ -1620,6 +1620,12 @@ class PearcordPlatform extends EventEmitter {
     const failureDigestHeal = await this._healFailureDigestCursorOnPartition(gid).catch(() => ({
       relisted: 0
     }))
+    const scheduleDashboardHeal = await this._healScheduleDashboardOnPartition(gid).catch(() => ({
+      relisted: 0
+    }))
+    const archivePeerHeal = await this._healArchivePeerCursorOnPartition(gid).catch(() => ({
+      relisted: 0
+    }))
     return {
       voiceApplied,
       emojiSlots,
@@ -1662,7 +1668,9 @@ class PearcordPlatform extends EventEmitter {
       workerRegistryHeal,
       workerTrialHeal,
       receiptRegistryHeal,
-      failureDigestHeal
+      failureDigestHeal,
+      scheduleDashboardHeal,
+      archivePeerHeal
     }
   }
 
@@ -9821,10 +9829,15 @@ class PearcordPlatform extends EventEmitter {
       }
       if (payload.digestRelayHandoff) {
         await this._initDeliveryReceipts(payload.guildId)
-        await this.deliveryReceipts.ingestDigestRelayHandoffSlice(
+        const slice = payload.digestRelayHandoff
+        this._shouldGossipDigestRelayHandoff(slice)
+        const ingested = await this.deliveryReceipts.ingestDigestRelayHandoffSlice(
           payload.guildId,
-          payload.digestRelayHandoff
+          slice
         )
+        if (ingested?.duplicate) {
+          this._digestRelayHandoffDuplicateAt = ingested.exportedAt || slice.exportedAt || null
+        }
       }
       if (payload.hookFailureDigestCsvExport) {
         await this._initDeliveryReceipts(payload.guildId)
@@ -12284,7 +12297,15 @@ class PearcordPlatform extends EventEmitter {
   }
 
   async getAutomationHealthDashboard () {
+    const gid = this.guild?.guild?.id || null
+    const span = this.log.time('automation.health', {
+      spanKind: 'automation.health',
+      guildId: gid,
+      context: 'dashboard'
+    })
+    try {
       if (!this.guild?.guild) {
+        span.end({ guildHealthRowCount: 0, skipped: true })
         return buildAutomationHealthDashboard({})
       }
     const auditExportSchedule = await this.getAuditExportSchedule()
@@ -12302,7 +12323,7 @@ class PearcordPlatform extends EventEmitter {
     const automationDigestNotifyPrefs = await this.getAutomationDigestNotifyPrefs()
     const digestRelayHandoff = await this.getLastDigestRelayHandoff()
     const auditExportCsvMeta = await this.getAuditExportCsvExport().catch(() => null)
-    return buildAutomationHealthDashboard({
+    const result = buildAutomationHealthDashboard({
       auditExportSchedule,
       digestExportSchedule,
       automationDigestExportSchedule,
@@ -12314,6 +12335,40 @@ class PearcordPlatform extends EventEmitter {
       digestRelayHandoff,
       auditExportCsvMeta
     })
+    const guildHealthRowCount =
+      (result.auditExport ? 1 : 0) +
+      (result.auditCsvMesh ? 1 : 0) +
+      (result.digestSync ? 1 : 0) +
+      (result.automationDigestExport ? 1 : 0) +
+      (result.health?.archivePeers?.length || 0)
+    span.end({
+      guildHealthRowCount,
+      anyOverdue: !!result.anyOverdue,
+      overdueCount: (result.overdueActions || []).length,
+      bridgeKind: 'automation.health'
+    })
+    return result
+    } catch (err) {
+      this.log.error('automation.health error', {
+        guildId: gid,
+        context: 'dashboard',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      throw err
+    }
+  }
+
+  async clearDigestRelayHandoffs () {
+    if (!this.guild?.guild) throw new Error('no guild')
+    const roles = await this._memberRoles()
+    if (!roleHasPermission(roles, PERMISSION.MANAGE_GUILD)) {
+      throw new Error('no permission to manage automations')
+    }
+    await this._initDeliveryReceipts(this.guild.guild.id)
+    const removed = await this.deliveryReceipts.clearDigestRelayHandoffs()
+    this.emit('digest-relay-handoff-cleared', { removed })
+    return { removed }
   }
 
   async _resolveAuditExportFilter (explicit) {
@@ -17168,7 +17223,8 @@ class PearcordPlatform extends EventEmitter {
         openWebhooks: !!parsed.openWebhooks,
         openAutomation: !!parsed.openAutomation,
         openWorkers: !!parsed.openWorkers,
-        openReceipts: !!parsed.openReceipts
+        openReceipts: !!parsed.openReceipts,
+        openHealth: !!parsed.openHealth
       }
     }
 
@@ -25750,6 +25806,8 @@ class PearcordPlatform extends EventEmitter {
     const pollDbReadBudget = this._pollDbReadBudget?.stats?.() || null
     const deliveryReceiptDuplicateId = this._deliveryReceiptDuplicateId || null
     this._deliveryReceiptDuplicateId = null
+    const digestRelayHandoffDuplicateAt = this._digestRelayHandoffDuplicateAt || null
+    this._digestRelayHandoffDuplicateAt = null
     return {
       onboarded: this.onboarded,
       sessionReady: this._sessionReady,
@@ -25878,6 +25936,7 @@ class PearcordPlatform extends EventEmitter {
       automationDelivery,
       deliveryReceiptRows,
       deliveryReceiptDuplicateId,
+      digestRelayHandoffDuplicateAt,
       automationDeliveryMetrics,
       automationReceiptRetention,
       hookFailurePrefs,
@@ -26488,6 +26547,7 @@ const { webhooksMixin } = require('./webhooks-mixin')
 const { automationMixin } = require('./automation-mixin')
 const { workersMixin } = require('./workers-mixin')
 const { deliveryMixin } = require('./delivery-mixin')
+const { healthMixin } = require('./health-mixin')
 Object.assign(PearcordPlatform.prototype, pollSchedulingMixin)
 Object.assign(PearcordPlatform.prototype, notificationsActivityMixin)
 Object.assign(PearcordPlatform.prototype, userSettingsMixin)
@@ -26503,3 +26563,4 @@ Object.assign(PearcordPlatform.prototype, webhooksMixin)
 Object.assign(PearcordPlatform.prototype, automationMixin)
 Object.assign(PearcordPlatform.prototype, workersMixin)
 Object.assign(PearcordPlatform.prototype, deliveryMixin)
+Object.assign(PearcordPlatform.prototype, healthMixin)