Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Honour recurring and descendant maintenance in Patrol findings

rcourtman49b7abc860f5
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index db19ba3cd2..ab2624528c 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -15,6 +15,14 @@
## Purpose
+### Patrol maintenance coverage adds no agent authority
+
+The Patrol operator-state projection in `internal/api/router.go` now reads the
+active maintenance occurrence (one-shot or recurring) and inherits ancestor
+windows scoped `resource_and_descendants`, as alert intent does. It only
+auto-dismisses new findings; it adds no agent route, command or execution
+authority, and remediation locks stay exact-resource state.
+
### Pro Patrol default adds no agent authority
The Patrol autonomy handler change only reports whether the Pro Ask first
diff --git a/docs/release-control/v6/internal/subsystems/ai-runtime.md b/docs/release-control/v6/internal/subsystems/ai-runtime.md
index a4ecc131ed..896278ee5a 100644
--- a/docs/release-control/v6/internal/subsystems/ai-runtime.md
+++ b/docs/release-control/v6/internal/subsystems/ai-runtime.md
@@ -5851,9 +5851,19 @@ attributes the suppression on the lifecycle timeline
(`operator_state_cause: maintenance_window`, with
`maintenance_end_at` metadata), and persists the finding for audit
history. The active boundary may come from a one-shot or recurring schedule;
-both are evaluated by the canonical operator-state model. Descendant-scope
-inheritance is alert-intent behavior and does not weaken exact-resource
-action-remediation locks or invent inherited action authority.
+both are evaluated by the canonical operator-state model, and the projection
+carries the active occurrence's own start and end
+(`ActiveMaintenanceOccurrenceAt`), never the one-shot fields, which a recurring
+schedule leaves nil. Patrol inherits maintenance exactly as alert intent does:
+`unifiedresources.ActiveMaintenanceCoverageAt` resolves the resource's own
+window and every ancestor window scoped `resource_and_descendants` on the live
+canonical parent chain, and the latest-ending active window wins. A window
+stored on an ancestor reaches the projection with `Inherited` and its
+`SourceID`; the dismissal note says the window is on a parent resource and the
+lifecycle event carries `maintenance_inherited` and `maintenance_source_id`.
+Only maintenance is inherited. Monitoring mode, lifecycle, criticality and
+action-remediation locks stay exact-resource state, so descendant scope never
+weakens a lock or invents inherited action authority.
Operator state outranks per-action approval on the Pulse Actions path:
`validateExecutionPolicy` in `internal/actionlifecycle/service.go` reads the
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md
index 865672f046..f8b7b0cbe8 100644
--- a/docs/release-control/v6/internal/subsystems/api-contracts.md
+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md
@@ -6452,9 +6452,19 @@ at startup: `internal/api/router.go` calls
`patrol.GetFindings().SetResourceOperatorStateProvider(...)` with a
`ResourceOperatorStateProviderFunc` closure that reads the unified
store and returns a `ResourceOperatorStateProjection` carrying every
-operator-set signal in one call (maintenance window via
-`state.IsInMaintenanceAt`, the `IntentionallyOffline` flag, and the
-`Criticality` hint). The same router setup also calls
+operator-set signal in one call (the maintenance window, the
+`IntentionallyOffline` flag, and the `Criticality` hint). The maintenance
+window is the active occurrence `unifiedresources.ActiveMaintenanceCoverageAt`
+resolves: the resource's own one-shot or recurring window, or an ancestor
+window scoped `resource_and_descendants` on the read state's
+`ResolveCanonicalResourceAncestors` chain, latest end winning, with
+`Inherited`/`SourceID` naming an ancestor's window. Its bounds come from the
+occurrence, never the one-shot fields a recurring schedule leaves nil
+(`TestPatrolOperatorStateProjectsActiveRecurringMaintenance` and
+`TestPatrolOperatorStateInheritsDescendantScopedMaintenance` in
+`internal/api/ai_handlers_more_test.go`). A resource with no row of its own
+still projects `ok=true` while an inherited window covers it; every other
+projected field is the resource's own state. The same router setup also calls
`SetResourceStoreProvider(r.resourceHandlers.getStore)` on the AI settings
handler so `/api/ai/patrol/findings` can refresh `resource_criticality` at
read time after an operator changes priority, without waiting for the next
diff --git a/docs/release-control/v6/internal/subsystems/monitoring.md b/docs/release-control/v6/internal/subsystems/monitoring.md
index 3fc4a0219c..33a6c791e1 100644
--- a/docs/release-control/v6/internal/subsystems/monitoring.md
+++ b/docs/release-control/v6/internal/subsystems/monitoring.md
@@ -6293,7 +6293,10 @@ canonical parent chain for maintenance only. An ancestor contributes an active
occurrence only when its scope is `resource_and_descendants`; monitoring mode,
lifecycle state, and every other operator field remain exact-resource policy.
When active windows overlap, the adapter projects the occurrence with the
-latest end together with its source id and inherited marker.
+latest end together with its source id and inherited marker. That resolution
+is `unifiedresources.ActiveMaintenanceCoverageAt`, the rule Patrol's
+operator-state projection shares, so a host window scoped to descendants
+silences its guests' alerts and Patrol findings alike.
Backup-aware offline intent consumes a PVE task only when VMID, instance, and
node match and the task is active. `pollBackupTasks` stamps server observation
diff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.md
index df247b26bd..8ff01c7161 100644
--- a/docs/release-control/v6/internal/subsystems/security-privacy.md
+++ b/docs/release-control/v6/internal/subsystems/security-privacy.md
@@ -18,6 +18,13 @@
## Purpose
+### Patrol maintenance coverage widens no authority
+
+Patrol inherits only maintenance from an ancestor window scoped
+`resource_and_descendants`. Monitoring mode, lifecycle and the
+`NeverAutoRemediate` lock are never inherited, so descendant scope can quiet
+findings but cannot unlock or grant automated action on any resource.
+
### Startup provisioning cannot replace retained access
`pkg/server/server.go` admits environment-selected startup import only into an
diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.md
index 60d372f95c..6c95fd225d 100644
--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md
+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md
@@ -21,6 +21,13 @@
## Purpose
+### Patrol maintenance coverage adds no recovery execution
+
+Patrol's operator-state projection now projects the active recurring
+occurrence instead of the nil one-shot fields and inherits descendant-scoped
+ancestor maintenance. It reads existing operator-state rows only; it adds no
+recovery endpoint, execution route or recovery-point access.
+
A legacy client echoing the projected `controlled` mode into an unrelated AI
settings PUT must retain a stored `autonomous` preference and its existing
legacy command-approval selection. `TestAssistantProjectedModeEchoPreservesLegacyPolicy`
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index 1a4e6e9664..7e2bfbdd76 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -3469,7 +3469,11 @@ silently move operator intent. Weekdays normalize to unique Monday-through-
Sunday order. `maintenanceScope` defaults to `resource`; the only inherited
value is `resource_and_descendants`, resolved against the canonical registry
parent chain with cycle protection. Concrete occurrence start/end boundaries
-are derived by the same model for Alerts and post-window verification. SQLite
+are derived by the same model for Alerts, Patrol and post-window verification;
+consumers read the active occurrence, never the one-shot fields, which a
+recurring schedule leaves nil. `ActiveMaintenanceCoverageAt` is the one
+inheritance rule: own window plus ancestor windows scoped
+`resource_and_descendants`, latest active end wins, maintenance only. SQLite
persists recurrence JSON and scope in additive columns while legacy one-shot
rows retain their existing meaning. Scheduling, updating, changing scope, or
clearing either form remains an atomic operator-state plus resource-timeline
@@ -3539,8 +3543,9 @@ plain words, never in implementation terms (no "persisted resource policy",
maintenance-window help says it silences alerts and dismisses new Patrol
findings, because an active window suppresses alert activation and
auto-dismisses new findings while keeping them in history. The descendant-scope
-help claims only alerts for descendants, because Patrol reads the exact
-resource's own state. The `Never auto-remediate` label stays as named, because
+help says descendants' alerts are silenced and their new Patrol findings
+dismissed, because Alerts and Patrol resolve maintenance through the one
+`ActiveMaintenanceCoverageAt` rule over the live canonical parent chain. The `Never auto-remediate` label stays as named, because
help pages and the Assistant's refusal message refer to it; its help and lock
confirmation say it blocks every automated fix, including approved ones, and
that blocked runs are logged as failed actions (an Assistant planning refusal
diff --git a/frontend-modern/browser-verification/71f230975f168afd.json b/frontend-modern/browser-verification/71f230975f168afd.json
new file mode 100644
index 0000000000..72f29d68a2
--- /dev/null
+++ b/frontend-modern/browser-verification/71f230975f168afd.json
@@ -0,0 +1,36 @@
+{
+ "version": 1,
+ "base_sha": "5996dc1a25c5b982ee2d10dd858df2e303ba97c5",
+ "verified_at": "2026-10-13T11:54:00Z",
+ "result": "passed",
+ "changed_paths": [
+ "frontend-modern/src/components/Infrastructure/ResourceOperatorStateSection.tsx"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/components/Infrastructure/ResourceOperatorStateSection.tsx": "f2161a1fcf17f2efd8502c8cf4b991b26a7569fa5b4851a80605754efcd53cdd"
+ },
+ "routes": [
+ "/proxmox"
+ ],
+ "viewports": [
+ {
+ "width": 1440,
+ "height": 1000
+ },
+ {
+ "width": 390,
+ "height": 844
+ }
+ ],
+ "states": [
+ "production vite build of these exact bytes (sha256 matches) served by vite preview on pulse-dev, proxied to the :7699 perf rig's mock estate (50 PVE nodes)",
+ "PVE node Analytics A inline drawer, Manage tab, maintenance scheduler open with Applies to set to This resource and descendants: help reads 'With descendants, everything under this resource is covered too, including resources added later: alerts are silenced and new Patrol findings dismissed.'",
+ "old alerts-only descendant help absent (0 matches) at both widths",
+ "phone 390px: help wraps to four lines under the select inside the drawer, no horizontal page overflow (scrollWidth - clientWidth = 0); desktop 1440px: single line, no overflow"
+ ],
+ "interactions": [
+ "signed in with the rig's dev login",
+ "expanded the Analytics A node row via its chevron, opened the Manage tab",
+ "clicked Schedule window, selected This resource and descendants in Applies to, read the help text and measured overflow at both viewports"
+ ]
+}
diff --git a/frontend-modern/src/components/Infrastructure/ResourceOperatorStateSection.tsx b/frontend-modern/src/components/Infrastructure/ResourceOperatorStateSection.tsx
index 2f24c6612a..1c350e9597 100644
--- a/frontend-modern/src/components/Infrastructure/ResourceOperatorStateSection.tsx
+++ b/frontend-modern/src/components/Infrastructure/ResourceOperatorStateSection.tsx
@@ -844,7 +844,7 @@ export const ResourceOperatorStateSection: Component<ResourceOperatorStateSectio
onChange={(event) =>
setScheduleScope(event.currentTarget.value as 'resource' | 'resource_and_descendants')
}
- help="With descendants, alerts on everything under this resource are silenced too, including resources added later."
+ help="With descendants, everything under this resource is covered too, including resources added later: alerts are silenced and new Patrol findings dismissed."
helpClass="text-[11px] leading-tight"
>
<option value="resource">This resource only</option>
diff --git a/frontend-modern/src/components/Infrastructure/__tests__/ResourceOperatorStateSection.test.ts b/frontend-modern/src/components/Infrastructure/__tests__/ResourceOperatorStateSection.test.ts
index 8fd9088c2f..b02b6ad6f2 100644
--- a/frontend-modern/src/components/Infrastructure/__tests__/ResourceOperatorStateSection.test.ts
+++ b/frontend-modern/src/components/Infrastructure/__tests__/ResourceOperatorStateSection.test.ts
@@ -67,8 +67,12 @@ describe('ResourceOperatorStateSection', () => {
// The lock's consequence stays beside it, including approved fixes.
expect(visibleSource).toContain('Block every automated fix on this resource, including');
expect(visibleSource).toContain('Expected offline hides availability noise only.');
- // Descendant scope reaches alerts only; Patrol reads the exact resource.
- expect(visibleSource).toContain('With descendants, alerts on everything under this resource');
+ // Descendant scope covers alerts and new Patrol findings under the
+ // resource, the same maintenance coverage both runtimes resolve.
+ expect(visibleSource).toContain('alerts are silenced and new Patrol findings dismissed.');
+ expect(visibleSource).not.toContain(
+ 'With descendants, alerts on everything under this resource',
+ );
});
it('presents resource action policy as an optional limit on global Patrol autonomy', () => {
diff --git a/internal/ai/findings.go b/internal/ai/findings.go
index 6e351bdb21..0f9b076cc3 100644
--- a/internal/ai/findings.go
+++ b/internal/ai/findings.go
@@ -847,10 +847,15 @@ type FindingsStore struct {
// this through ResourceOperatorStateProvider; the package layout puts
// the canonical type in `internal/unifiedresources` to avoid an import
// cycle, so this is the projected shape the findings runtime needs.
+// StartAt/EndAt bound the active occurrence (one-shot or recurring).
+// Inherited marks a window stored on an ancestor whose scope covers its
+// descendants; SourceID names the resource the window is stored on.
type ResourceOperatorStateMaintenanceWindow struct {
- StartAt time.Time
- EndAt time.Time
- Reason string
+ StartAt time.Time
+ EndAt time.Time
+ Reason string
+ SourceID string
+ Inherited bool
}
// ResourceOperatorStateProjection is the per-resource view the
@@ -2149,16 +2154,25 @@ func (s *FindingsStore) Add(f *Finding) bool {
window := projection.MaintenanceWindow
f.DismissedReason = "expected_behavior"
f.AcknowledgedAt = &now
- noteParts := []string{fmt.Sprintf("Resource is in operator-set maintenance window until %s.", window.EndAt.Format(time.RFC3339))}
+ note := fmt.Sprintf("Resource is in operator-set maintenance window until %s.", window.EndAt.Format(time.RFC3339))
+ if window.Inherited {
+ note = fmt.Sprintf("Resource is covered by an operator-set maintenance window on a parent resource until %s.", window.EndAt.Format(time.RFC3339))
+ }
+ noteParts := []string{note}
if reason := strings.TrimSpace(window.Reason); reason != "" {
noteParts = append(noteParts, "Reason: "+reason)
}
f.UserNote = strings.Join(noteParts, " ")
- s.appendLifecycleLocked(f, "dismissed", "Auto-acknowledged: resource in maintenance window", f.LoopState, string(FindingLoopStateDismissed), map[string]string{
+ metadata := map[string]string{
"reason": "expected_behavior",
"operator_state_cause": "maintenance_window",
"maintenance_end_at": window.EndAt.Format(time.RFC3339),
- })
+ }
+ if window.Inherited {
+ metadata["maintenance_inherited"] = "true"
+ metadata["maintenance_source_id"] = window.SourceID
+ }
+ s.appendLifecycleLocked(f, "dismissed", "Auto-acknowledged: resource in maintenance window", f.LoopState, string(FindingLoopStateDismissed), metadata)
s.syncLoopStateLocked(f)
case projection.monitoringSuppressionCauseFor(f) != "":
cause := projection.monitoringSuppressionCauseFor(f)
diff --git a/internal/ai/findings_test.go b/internal/ai/findings_test.go
index 877b7aeea2..5edd24d25e 100644
--- a/internal/ai/findings_test.go
+++ b/internal/ai/findings_test.go
@@ -1757,6 +1757,9 @@ func TestFindingsStore_Add_AutoAcknowledgesDuringMaintenanceWindow(t *testing.T)
if !strings.Contains(got.UserNote, "Q3 storage upgrade") {
t.Errorf("UserNote should include the operator's reason; got %q", got.UserNote)
}
+ if strings.Contains(got.UserNote, "parent resource") {
+ t.Errorf("UserNote on the resource's own window must not credit a parent; got %q", got.UserNote)
+ }
// Lifecycle must record the auto-dismiss with the canonical
// operator_state_cause metadata so the timeline can attribute the
// suppression to its source.
@@ -1772,6 +1775,44 @@ func TestFindingsStore_Add_AutoAcknowledgesDuringMaintenanceWindow(t *testing.T)
}
}
+// A window inherited from an ancestor's descendant-scoped maintenance
+// dismisses the finding too, and the note and timeline say the window is the
+// parent's, so the operator does not look for one on the guest.
+func TestFindingsStore_Add_AutoAcknowledgesDuringInheritedMaintenanceWindow(t *testing.T) {
+ store := NewFindingsStore()
+ now := time.Now()
+ store.SetResourceOperatorStateProvider(ResourceOperatorStateProviderFunc(func(canonicalID string, queriedAt time.Time) (ResourceOperatorStateProjection, bool) {
+ return ResourceOperatorStateProjection{
+ MaintenanceWindow: &ResourceOperatorStateMaintenanceWindow{
+ StartAt: now.Add(-time.Hour),
+ EndAt: now.Add(time.Hour),
+ Reason: "hypervisor patching",
+ SourceID: "agent:node-a",
+ Inherited: true,
+ },
+ }, true
+ }))
+
+ store.Add(&Finding{ID: "f-inherited", ResourceID: "vm:101", Severity: FindingSeverityWarning, Title: "CPU saturated"})
+
+ got := store.Get("f-inherited")
+ if got == nil || got.DismissedReason != "expected_behavior" {
+ t.Fatalf("finding under an inherited window = %+v, want it dismissed as expected_behavior", got)
+ }
+ if !strings.Contains(got.UserNote, "on a parent resource") || !strings.Contains(got.UserNote, "hypervisor patching") {
+ t.Fatalf("UserNote %q should name the parent's window and its reason", got.UserNote)
+ }
+ attributed := false
+ for _, ev := range got.Lifecycle {
+ if ev.Type == "dismissed" && ev.Metadata["maintenance_inherited"] == "true" && ev.Metadata["maintenance_source_id"] == "agent:node-a" {
+ attributed = true
+ }
+ }
+ if !attributed {
+ t.Fatal("expected the dismissed lifecycle event to name the ancestor the window is stored on")
+ }
+}
+
func TestFindingsStore_Add_DoesNotAutoAcknowledgeOutsideMaintenanceWindow(t *testing.T) {
// A provider that reports no active window must not affect the
// new-finding default path — the finding lands as active. Pin this
diff --git a/internal/api/ai_handlers_more_test.go b/internal/api/ai_handlers_more_test.go
index d6e5e92571..e4b692894b 100644
--- a/internal/api/ai_handlers_more_test.go
+++ b/internal/api/ai_handlers_more_test.go
@@ -1234,3 +1234,148 @@ func TestPatrolFindingOperatorStateResolvesContinuityBackedHost(t *testing.T) {
t.Fatalf("finding projection cloned the unified listing %d times; it must resolve through the monitor's read state", seed.clones)
}
}
+
+// patrolMaintenanceTree publishes a node with one guest under it and returns
+// the router, the operator-state store, and the two canonical IDs.
+func patrolMaintenanceTree(t *testing.T) (*Router, unifiedresources.ResourceStore, string, string) {
+ t.Helper()
+ handlers := NewResourceHandlers(&config.Config{DataPath: t.TempDir()})
+ t.Cleanup(func() { _ = handlers.CloseStores() })
+ store, err := handlers.getStore("default")
+ if err != nil {
+ t.Fatalf("resource store: %v", err)
+ }
+ adapter := unifiedresources.NewMonitorAdapter(unifiedresources.NewRegistry(store))
+ const nodeRef, guestRef = "node:pve-a", "vm:pve-a:101"
+ adapter.PopulateSupplementalRecords(unifiedresources.SourceProxmox, []unifiedresources.IngestRecord{
+ {SourceID: nodeRef, Resource: unifiedresources.Resource{ID: nodeRef, Type: unifiedresources.ResourceTypeAgent, Name: "pve-a"}},
+ {SourceID: guestRef, ParentSourceID: nodeRef, Resource: unifiedresources.Resource{ID: guestRef, Type: unifiedresources.ResourceTypeVM, Name: "database"}},
+ })
+ nodeID, nodeOK := adapter.ResolveCanonicalResourceID(nodeRef)
+ guestID, guestOK := adapter.ResolveCanonicalResourceID(guestRef)
+ if !nodeOK || !guestOK {
+ t.Fatalf("published tree does not resolve node (%v) or guest (%v)", nodeOK, guestOK)
+ }
+ if ancestors := adapter.ResolveCanonicalResourceAncestors(guestID); len(ancestors) == 0 || ancestors[0] != nodeID {
+ t.Fatalf("guest ancestors = %v, want the node %s first", ancestors, nodeID)
+ }
+ monitor := &monitoring.Monitor{}
+ monitor.SetResourceStore(adapter)
+ return &Router{monitor: monitor, resourceHandlers: handlers}, store, nodeID, guestID
+}
+
+// 2026-10-13 is a Tuesday.
+var patrolMaintenanceNow = time.Date(2026, 10, 13, 12, 0, 0, 0, time.UTC)
+
+func tuesdayLunchRecurrence() *unifiedresources.RecurringMaintenanceWindow {
+ return &unifiedresources.RecurringMaintenanceWindow{
+ Timezone: "UTC",
+ Weekdays: []string{"tuesday"},
+ StartMinute: 11 * 60,
+ EndMinute: 13 * 60,
+ }
+}
+
+func setOperatorState(t *testing.T, store unifiedresources.ResourceStore, state unifiedresources.ResourceOperatorState) {
+ t.Helper()
+ if err := store.SetResourceOperatorState(state); err != nil {
+ t.Fatalf("set operator state on %s: %v", state.CanonicalID, err)
+ }
+}
+
+// A recurring window carries no one-shot start or end. Patrol must project
+// the occurrence that is active, not dereference the absent one-shot dates.
+func TestPatrolOperatorStateProjectsActiveRecurringMaintenance(t *testing.T) {
+ router, store, nodeID, _ := patrolMaintenanceTree(t)
+ setOperatorState(t, store, unifiedresources.ResourceOperatorState{
+ CanonicalID: nodeID,
+ MaintenanceRecurrence: tuesdayLunchRecurrence(),
+ MaintenanceReason: "weekly patching",
+ })
+ provider := router.patrolResourceOperatorStateProvider("default")
+
+ projection, ok := provider.OperatorStateProjection(nodeID, patrolMaintenanceNow)
+ window := projection.MaintenanceWindow
+ if !ok || window == nil {
+ t.Fatalf("recurring occurrence active at %s projected %+v (ok=%v), want a maintenance window", patrolMaintenanceNow, projection, ok)
+ }
+ wantStart := time.Date(2026, 10, 13, 11, 0, 0, 0, time.UTC)
+ wantEnd := time.Date(2026, 10, 13, 13, 0, 0, 0, time.UTC)
+ if !window.StartAt.Equal(wantStart) || !window.EndAt.Equal(wantEnd) || window.Reason != "weekly patching" || window.Inherited {
+ t.Fatalf("projected window %+v, want the %s-%s occurrence on the resource itself", window, wantStart, wantEnd)
+ }
+
+ // Control: outside the occurrence the same row projects no window.
+ projection, ok = provider.OperatorStateProjection(nodeID, wantEnd.Add(time.Minute))
+ if !ok || projection.MaintenanceWindow != nil {
+ t.Fatalf("after the occurrence projected %+v (ok=%v), want the row without a window", projection, ok)
+ }
+
+ // Control: a one-shot window still projects its own dates.
+ start, end := patrolMaintenanceNow.Add(-time.Minute), patrolMaintenanceNow.Add(time.Hour)
+ setOperatorState(t, store, unifiedresources.ResourceOperatorState{
+ CanonicalID: nodeID,
+ MaintenanceStartAt: &start,
+ MaintenanceEndAt: &end,
+ })
+ projection, _ = provider.OperatorStateProjection(nodeID, patrolMaintenanceNow)
+ if window := projection.MaintenanceWindow; window == nil || !window.StartAt.Equal(start) || !window.EndAt.Equal(end) {
+ t.Fatalf("one-shot window projected %+v, want %s-%s", projection.MaintenanceWindow, start, end)
+ }
+}
+
+// A window scoped to resource_and_descendants silences Patrol findings on the
+// guests under it, as it silences their alerts. Only maintenance crosses: the
+// node's remediation lock and monitoring mode stay the node's own.
+func TestPatrolOperatorStateInheritsDescendantScopedMaintenance(t *testing.T) {
+ router, store, nodeID, guestID := patrolMaintenanceTree(t)
+ setOperatorState(t, store, unifiedresources.ResourceOperatorState{
+ CanonicalID: nodeID,
+ MaintenanceRecurrence: tuesdayLunchRecurrence(),
+ MaintenanceScope: unifiedresources.MaintenanceScopeResourceAndDescendants,
+ MaintenanceReason: "hypervisor patching",
+ MonitoringMode: unifiedresources.MonitoringModeMuted,
+ NeverAutoRemediate: true,
+ })
+ provider := router.patrolResourceOperatorStateProvider("default")
+
+ projection, ok := provider.OperatorStateProjection(guestID, patrolMaintenanceNow)
+ window := projection.MaintenanceWindow
+ if !ok || window == nil || !window.Inherited || window.SourceID != nodeID || window.Reason != "hypervisor patching" {
+ t.Fatalf("guest under a descendant-scoped node window projected %+v (ok=%v), want the node's window inherited", projection, ok)
+ }
+ if projection.NeverAutoRemediate || projection.MonitoringMode != "" {
+ t.Fatalf("guest inherited non-maintenance state %+v; only maintenance may cross", projection)
+ }
+
+ // A guest window ending later than the node's keeps the guest covered
+ // until the later end; an earlier one yields to the node's.
+ guestStart, guestEnd := patrolMaintenanceNow.Add(-time.Minute), patrolMaintenanceNow.Add(3*time.Hour)
+ setOperatorState(t, store, unifiedresources.ResourceOperatorState{CanonicalID: guestID, MaintenanceStartAt: &guestStart, MaintenanceEndAt: &guestEnd, MaintenanceReason: "guest upgrade"})
+ projection, _ = provider.OperatorStateProjection(guestID, patrolMaintenanceNow)
+ if window := projection.MaintenanceWindow; window == nil || window.Inherited || !window.EndAt.Equal(guestEnd) {
+ t.Fatalf("guest's own later window projected %+v, want its own window to %s", projection.MaintenanceWindow, guestEnd)
+ }
+ shortEnd := patrolMaintenanceNow.Add(10 * time.Minute)
+ setOperatorState(t, store, unifiedresources.ResourceOperatorState{CanonicalID: guestID, MaintenanceStartAt: &guestStart, MaintenanceEndAt: &shortEnd})
+ projection, _ = provider.OperatorStateProjection(guestID, patrolMaintenanceNow)
+ if window := projection.MaintenanceWindow; window == nil || !window.Inherited || window.SourceID != nodeID {
+ t.Fatalf("guest's own earlier window projected %+v, want the node's later window", projection.MaintenanceWindow)
+ }
+
+ // Control: a resource-only node window does not reach the guest.
+ if err := store.ClearResourceOperatorState(guestID); err != nil {
+ t.Fatalf("clear guest operator state: %v", err)
+ }
+ setOperatorState(t, store, unifiedresources.ResourceOperatorState{
+ CanonicalID: nodeID,
+ MaintenanceRecurrence: tuesdayLunchRecurrence(),
+ MaintenanceScope: unifiedresources.MaintenanceScopeResource,
+ })
+ if projection, ok := provider.OperatorStateProjection(guestID, patrolMaintenanceNow); ok || projection.MaintenanceWindow != nil {
+ t.Fatalf("resource-only node window reached the guest: %+v (ok=%v)", projection, ok)
+ }
+ if projection, _ := provider.OperatorStateProjection(nodeID, patrolMaintenanceNow); projection.MaintenanceWindow == nil {
+ t.Fatal("resource-only node window no longer covers the node itself, so the guest control proves nothing")
+ }
+}
diff --git a/internal/api/contract_test.go b/internal/api/contract_test.go
index 83c78de340..2baa8cef47 100644
--- a/internal/api/contract_test.go
+++ b/internal/api/contract_test.go
@@ -23495,8 +23495,11 @@ func TestContract_FindingsResourceOperatorStateProviderIsWired(t *testing.T) {
if !strings.Contains(src, "ResourceOperatorStateProviderFunc(") {
t.Error("router.go must use the ai.ResourceOperatorStateProviderFunc adapter so the closure satisfies the provider interface")
}
- if !strings.Contains(src, "IsInMaintenanceAt(now)") {
- t.Error("router.go must gate the projection on state.IsInMaintenanceAt so a stale window does not return as active")
+ if !strings.Contains(src, "unifiedresources.ActiveMaintenanceCoverageAt(now, canonicalID, own, ancestorIDs,") {
+ t.Error("router.go must project maintenance through unifiedresources.ActiveMaintenanceCoverageAt, the active-occurrence and descendant-scope rule alert intent shares, so a stale window does not return as active")
+ }
+ if strings.Contains(src, "*state.MaintenanceStartAt") || strings.Contains(src, "*state.MaintenanceEndAt") {
+ t.Error("router.go must not dereference the one-shot maintenance fields; a recurring window leaves them nil")
}
if !strings.Contains(src, "GetResourceOperatorState(canonicalID)") {
t.Error("router.go must read state from the unified store's canonical accessor")
diff --git a/internal/api/router.go b/internal/api/router.go
index 4e2dc47152..de9edced66 100644
--- a/internal/api/router.go
+++ b/internal/api/router.go
@@ -2178,6 +2178,12 @@ type canonicalResourceIDResolver interface {
ResolveCanonicalResourceID(ref string) (string, bool)
}
+// canonicalResourceAncestorResolver is the live canonical parent chain the
+// same read state exposes, nearest parent first.
+type canonicalResourceAncestorResolver interface {
+ ResolveCanonicalResourceAncestors(ref string) []string
+}
+
// patrolResourceOperatorStateProvider projects durable operator state onto the
// resource a Patrol finding names. Findings carry whatever resource ID their
// producer used: unified-derived findings hold the canonical hash, Patrol
@@ -2193,6 +2199,11 @@ type canonicalResourceIDResolver interface {
// and reused for up to two seconds while nothing it depends on changes), so
// findings do not each clone the unified listing. Only a reference it cannot
// resolve is read as given.
+//
+// Maintenance is the active occurrence (one-shot or recurring) covering the
+// resource, resolved by the rule alert intent uses: the resource's own window
+// or an ancestor's window scoped to its descendants, latest end winning. Every
+// other field is the resource's own state; nothing else is inherited.
func (r *Router) patrolResourceOperatorStateProvider(orgID string) ai.ResourceOperatorStateProvider {
return ai.ResourceOperatorStateProviderFunc(
func(resourceRef string, now time.Time) (ai.ResourceOperatorStateProjection, bool) {
@@ -2201,33 +2212,49 @@ func (r *Router) patrolResourceOperatorStateProvider(orgID string) ai.ResourceOp
return ai.ResourceOperatorStateProjection{}, false
}
canonicalID := resourceRef
- if resolver, ok := r.resolveMonitorForOrg(orgID).GetUnifiedStructureReadState().(canonicalResourceIDResolver); ok {
+ readState := r.resolveMonitorForOrg(orgID).GetUnifiedStructureReadState()
+ if resolver, ok := readState.(canonicalResourceIDResolver); ok {
if resolvedID, resolved := resolver.ResolveCanonicalResourceID(resourceRef); resolved {
canonicalID = resolvedID
}
}
state, found, fetchErr := orgStore.GetResourceOperatorState(canonicalID)
- if fetchErr != nil || !found {
+ if fetchErr != nil {
return ai.ResourceOperatorStateProjection{}, false
}
- projection := ai.ResourceOperatorStateProjection{
- IntentionallyOffline: state.IntentionallyOffline,
- MonitoringMode: string(state.MonitoringMode),
- LifecycleState: string(state.LifecycleState),
- NeverAutoRemediate: state.NeverAutoRemediate,
- Criticality: string(state.Criticality),
+ var own *unifiedresources.ResourceOperatorState
+ var projection ai.ResourceOperatorStateProjection
+ if found {
+ own = &state
+ projection = ai.ResourceOperatorStateProjection{
+ IntentionallyOffline: state.IntentionallyOffline,
+ MonitoringMode: string(state.MonitoringMode),
+ LifecycleState: string(state.LifecycleState),
+ NeverAutoRemediate: state.NeverAutoRemediate,
+ Criticality: string(state.Criticality),
+ }
+ if state.LifecycleState == unifiedresources.LifecycleStateRetired {
+ projection.NeverAutoRemediate = true
+ }
}
- if state.LifecycleState == unifiedresources.LifecycleStateRetired {
- projection.NeverAutoRemediate = true
+ var ancestorIDs []string
+ if ancestors, ok := readState.(canonicalResourceAncestorResolver); ok {
+ ancestorIDs = ancestors.ResolveCanonicalResourceAncestors(canonicalID)
}
- if state.IsInMaintenanceAt(now) {
+ coverage, covered := unifiedresources.ActiveMaintenanceCoverageAt(now, canonicalID, own, ancestorIDs, func(ancestorID string) (unifiedresources.ResourceOperatorState, bool) {
+ ancestorState, ancestorFound, ancestorErr := orgStore.GetResourceOperatorState(ancestorID)
+ return ancestorState, ancestorErr == nil && ancestorFound
+ })
+ if covered {
projection.MaintenanceWindow = &ai.ResourceOperatorStateMaintenanceWindow{
- StartAt: *state.MaintenanceStartAt,
- EndAt: *state.MaintenanceEndAt,
- Reason: state.MaintenanceReason,
+ StartAt: coverage.Occurrence.StartAt,
+ EndAt: coverage.Occurrence.EndAt,
+ Reason: coverage.Reason,
+ SourceID: coverage.SourceID,
+ Inherited: coverage.Inherited,
}
}
- return projection, true
+ return projection, found || covered
},
)
}
diff --git a/internal/monitoring/monitor_alert_intent.go b/internal/monitoring/monitor_alert_intent.go
index 1b5648b4ad..f7e60f4a74 100644
--- a/internal/monitoring/monitor_alert_intent.go
+++ b/internal/monitoring/monitor_alert_intent.go
@@ -73,41 +73,32 @@ func (m *Monitor) installOperatorIntentResolver(store ResourceStoreInterface) {
}
}
- applyActiveMaintenance := func(candidate unifiedresources.ResourceOperatorState, sourceID string, inherited bool) {
- occurrence, active := candidate.ActiveMaintenanceOccurrenceAt(now)
- if !active {
- return
- }
- // Overlapping exact/inherited schedules remain suppressed until the
- // latest active end. This avoids promising an early delivery resume.
- if context.MaintenanceEndAt != nil && !occurrence.EndAt.After(*context.MaintenanceEndAt) {
- return
- }
- startAt, endAt := occurrence.StartAt, occurrence.EndAt
- context.MaintenanceStartAt = &startAt
- context.MaintenanceEndAt = &endAt
- context.MaintenanceReason = candidate.MaintenanceReason
- context.MaintenanceSourceID = sourceID
- context.MaintenanceInherited = inherited
- context.MaintenanceScope = string(candidate.MaintenanceScope)
- }
+ var own *unifiedresources.ResourceOperatorState
if found {
- applyActiveMaintenance(state, resourceID, false)
+ own = &state
}
+ var ancestorIDs []string
if hasAncestorReader {
- for _, ancestorID := range identity.(resourceIntentAncestorReader).ResolveCanonicalResourceAncestors(resourceID) {
- ancestorState, ancestorFound, ancestorErr := reader.GetResourceOperatorState(ancestorID)
- if ancestorErr != nil {
- log.Warn().Err(ancestorErr).Str("resourceID", resourceID).Str("ancestorID", ancestorID).Msg("Failed to read inherited operator maintenance state")
- continue
- }
- if !ancestorFound || ancestorState.MaintenanceScope != unifiedresources.MaintenanceScopeResourceAndDescendants {
- continue
- }
- applyActiveMaintenance(ancestorState, ancestorID, true)
+ ancestorIDs = identity.(resourceIntentAncestorReader).ResolveCanonicalResourceAncestors(resourceID)
+ }
+ coverage, covered := unifiedresources.ActiveMaintenanceCoverageAt(now, resourceID, own, ancestorIDs, func(ancestorID string) (unifiedresources.ResourceOperatorState, bool) {
+ ancestorState, ancestorFound, ancestorErr := reader.GetResourceOperatorState(ancestorID)
+ if ancestorErr != nil {
+ log.Warn().Err(ancestorErr).Str("resourceID", resourceID).Str("ancestorID", ancestorID).Msg("Failed to read inherited operator maintenance state")
+ return unifiedresources.ResourceOperatorState{}, false
}
+ return ancestorState, ancestorFound
+ })
+ if covered {
+ startAt, endAt := coverage.Occurrence.StartAt, coverage.Occurrence.EndAt
+ context.MaintenanceStartAt = &startAt
+ context.MaintenanceEndAt = &endAt
+ context.MaintenanceReason = coverage.Reason
+ context.MaintenanceSourceID = coverage.SourceID
+ context.MaintenanceInherited = coverage.Inherited
+ context.MaintenanceScope = string(coverage.Scope)
}
- return context, found || context.MaintenanceEndAt != nil
+ return context, found || covered
})
// Alerts restore before the resource store is attached during startup.
// Reconcile that restored set as soon as persisted policy is available.
diff --git a/internal/monitoring/monitor_alert_intent_test.go b/internal/monitoring/monitor_alert_intent_test.go
index 49ca8f7e65..84d831d823 100644
--- a/internal/monitoring/monitor_alert_intent_test.go
+++ b/internal/monitoring/monitor_alert_intent_test.go
@@ -153,6 +153,67 @@ func TestInstallOperatorIntentResolverInheritsScopedMaintenanceFromParent(t *tes
}
}
+// A recurring parent window carries no one-shot dates. Scoped to descendants,
+// its active occurrence silences the child's alerts until the occurrence ends,
+// resolved by the coverage rule Patrol's projection shares.
+func TestInstallOperatorIntentResolverInheritsRecurringScopedMaintenance(t *testing.T) {
+ store := unifiedresources.NewMemoryStore()
+ registry := unifiedresources.NewRegistry(store)
+ parentID := "node:pve-a"
+ registry.IngestResources([]unifiedresources.Resource{
+ {ID: parentID, Type: unifiedresources.ResourceTypeAgent, Name: "pve-a"},
+ {ID: "vm:101", Type: unifiedresources.ResourceTypeVM, Name: "database", ParentID: &parentID},
+ })
+ // A two-hour occurrence every day, centred on the current minute.
+ now := time.Now().UTC().Truncate(time.Minute)
+ minute := now.Hour()*60 + now.Minute()
+ recurrence := &unifiedresources.RecurringMaintenanceWindow{
+ Timezone: "UTC",
+ Weekdays: []string{"monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"},
+ StartMinute: (minute + 1440 - 60) % 1440,
+ EndMinute: (minute + 60) % 1440,
+ }
+ setParent := func(scope unifiedresources.MaintenanceScope) {
+ t.Helper()
+ if err := store.SetResourceOperatorState(unifiedresources.ResourceOperatorState{
+ CanonicalID: parentID,
+ MaintenanceRecurrence: recurrence,
+ MaintenanceScope: scope,
+ }); err != nil {
+ t.Fatal(err)
+ }
+ }
+ setParent(unifiedresources.MaintenanceScopeResourceAndDescendants)
+
+ manager := alerts.NewManagerWithDataDir(t.TempDir())
+ t.Cleanup(manager.Stop)
+ monitor := &Monitor{alertManager: manager}
+ monitor.installOperatorIntentResolver(unifiedresources.NewMonitorAdapter(registry))
+ preview := func() alerts.AlertIntentPolicyPreview {
+ t.Helper()
+ got, err := manager.PreviewIntentPolicy(alerts.AlertIntentPolicyPreviewRequest{
+ ResourceID: "vm:101", ResourceType: "vm", Signal: string(alerts.AlertIntentSignalOffline), ConditionActive: true,
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ return got
+ }
+ got := preview()
+ if got.Reason != "operator_maintenance" || got.Status != "expected_transient" {
+ t.Fatalf("inherited recurring maintenance preview = %+v", got)
+ }
+ if wantEnd := now.Add(time.Hour); got.EligibleAt == nil || !got.EligibleAt.Equal(wantEnd) {
+ t.Fatalf("eligibleAt = %v, want the occurrence end %v", got.EligibleAt, wantEnd)
+ }
+
+ // Control: the same recurrence scoped to the parent alone leaves the child.
+ setParent(unifiedresources.MaintenanceScopeResource)
+ if got := preview(); got.Status != "would_activate" {
+ t.Fatalf("resource-only recurring parent window leaked to child: %+v", got)
+ }
+}
+
func TestPlatformMonitorResourceIdentityConstructors(t *testing.T) {
if got := PBSMonitorResourceID("backup-main"); got != "pbs-backup-main" {
t.Fatalf("PBS monitor resource ID = %q", got)
diff --git a/internal/unifiedresources/resource_operator_state.go b/internal/unifiedresources/resource_operator_state.go
index 754896cc3b..2dc4bdc556 100644
--- a/internal/unifiedresources/resource_operator_state.go
+++ b/internal/unifiedresources/resource_operator_state.go
@@ -337,6 +337,61 @@ func (s ResourceOperatorState) ActiveMaintenanceOccurrenceAt(now time.Time) (Mai
return MaintenanceWindowOccurrence{}, false
}
+// MaintenanceCoverage is the active maintenance occurrence covering a
+// resource: its own window, or one inherited from an ancestor whose window is
+// scoped to resource_and_descendants. SourceID names the resource the window
+// is stored on.
+type MaintenanceCoverage struct {
+ Occurrence MaintenanceWindowOccurrence
+ Reason string
+ Scope MaintenanceScope
+ SourceID string
+ Inherited bool
+}
+
+// ActiveMaintenanceCoverageAt resolves the maintenance covering resourceID at
+// now, the one rule Alerts and Patrol share. own is the resource's own state
+// (nil when it has none); ancestorIDs is the live canonical parent chain,
+// nearest first, and read returns an ancestor's state (found=false when it
+// has none or cannot be read). Only an ancestor window scoped to
+// resource_and_descendants covers descendants. When several active windows
+// overlap, the one ending latest wins, so attention never resumes before the
+// last covering window closes.
+//
+// Coverage is maintenance only. Monitoring mode, lifecycle and remediation
+// locks stay exact-resource state and are never inherited.
+func ActiveMaintenanceCoverageAt(now time.Time, resourceID string, own *ResourceOperatorState, ancestorIDs []string, read func(canonicalID string) (ResourceOperatorState, bool)) (MaintenanceCoverage, bool) {
+ var coverage MaintenanceCoverage
+ covered := false
+ consider := func(candidate ResourceOperatorState, sourceID string, inherited bool) {
+ occurrence, active := candidate.ActiveMaintenanceOccurrenceAt(now)
+ if !active || (covered && !occurrence.EndAt.After(coverage.Occurrence.EndAt)) {
+ return
+ }
+ coverage = MaintenanceCoverage{
+ Occurrence: occurrence,
+ Reason: candidate.MaintenanceReason,
+ Scope: candidate.MaintenanceScope,
+ SourceID: sourceID,
+ Inherited: inherited,
+ }
+ covered = true
+ }
+ if own != nil {
+ consider(*own, resourceID, false)
+ }
+ if read != nil {
+ for _, ancestorID := range ancestorIDs {
+ ancestor, found := read(ancestorID)
+ if !found || ancestor.MaintenanceScope != MaintenanceScopeResourceAndDescendants {
+ continue
+ }
+ consider(ancestor, ancestorID, true)
+ }
+ }
+ return coverage, covered
+}
+
// MaintenanceOccurrencesEndingBetween returns concrete occurrences whose end
// is in (since, until]. It gives the maintenance sentinel a bounded,
// restart-safe way to verify every recurring window without inventing a
diff --git a/internal/unifiedresources/resource_operator_state_policy_test.go b/internal/unifiedresources/resource_operator_state_policy_test.go
index 39bf772656..a9e49fa899 100644
--- a/internal/unifiedresources/resource_operator_state_policy_test.go
+++ b/internal/unifiedresources/resource_operator_state_policy_test.go
@@ -145,3 +145,50 @@ func TestSQLiteOperatorStateNullPolicyColumnNormalizesOnRead(t *testing.T) {
t.Fatalf("wire payload must contain an empty capabilityNames list, got: %s", encoded)
}
}
+
+func TestActiveMaintenanceCoverageAtInheritsOnlyDescendantScopedAncestors(t *testing.T) {
+ now := time.Date(2026, 10, 13, 12, 0, 0, 0, time.UTC)
+ window := func(endIn time.Duration, scope MaintenanceScope, reason string) ResourceOperatorState {
+ start, end := now.Add(-time.Hour), now.Add(endIn)
+ return ResourceOperatorState{MaintenanceStartAt: &start, MaintenanceEndAt: &end, MaintenanceScope: scope, MaintenanceReason: reason}
+ }
+ states := map[string]ResourceOperatorState{
+ "node": window(2*time.Hour, MaintenanceScopeResourceAndDescendants, "node patching"),
+ "cluster": window(4*time.Hour, MaintenanceScopeResource, "cluster only"),
+ }
+ read := func(id string) (ResourceOperatorState, bool) {
+ state, ok := states[id]
+ return state, ok
+ }
+
+ // No own state: the descendant-scoped node window covers the guest; the
+ // resource-only cluster window, though it ends later, does not.
+ coverage, ok := ActiveMaintenanceCoverageAt(now, "guest", nil, []string{"node", "cluster"}, read)
+ if !ok || !coverage.Inherited || coverage.SourceID != "node" || coverage.Reason != "node patching" || !coverage.Occurrence.EndAt.Equal(now.Add(2*time.Hour)) {
+ t.Fatalf("coverage = %+v (ok=%v), want the node's inherited window", coverage, ok)
+ }
+
+ // An own window ending earlier yields to the later inherited one; ending
+ // later, it wins.
+ short := window(time.Hour, MaintenanceScopeResource, "guest short")
+ if coverage, _ := ActiveMaintenanceCoverageAt(now, "guest", &short, []string{"node"}, read); coverage.SourceID != "node" {
+ t.Fatalf("earlier own window won over a later inherited one: %+v", coverage)
+ }
+ long := window(3*time.Hour, MaintenanceScopeResource, "guest long")
+ if coverage, _ := ActiveMaintenanceCoverageAt(now, "guest", &long, []string{"node"}, read); coverage.Inherited || coverage.SourceID != "guest" || coverage.Reason != "guest long" {
+ t.Fatalf("later own window lost to the inherited one: %+v", coverage)
+ }
+
+ // Controls: no ancestors or no reader means own state only.
+ if _, ok := ActiveMaintenanceCoverageAt(now, "guest", nil, nil, read); ok {
+ t.Fatal("covered with no own window and no ancestors")
+ }
+ if _, ok := ActiveMaintenanceCoverageAt(now, "guest", nil, []string{"node"}, nil); ok {
+ t.Fatal("covered with no ancestor reader")
+ }
+ expired := window(-time.Minute, MaintenanceScopeResourceAndDescendants, "")
+ states["node"] = expired
+ if _, ok := ActiveMaintenanceCoverageAt(now, "guest", nil, []string{"node"}, read); ok {
+ t.Fatal("an ancestor window that already ended still covers the guest")
+ }
+}