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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
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.mdindex 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 authorityThe Patrol autonomy handler change only reports whether the Pro Ask firstdiff --git a/docs/release-control/v6/internal/subsystems/ai-runtime.md b/docs/release-control/v6/internal/subsystems/ai-runtime.mdindex 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 audithistory. 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 thediff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.mdindex 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 unifiedstore 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 settingshandler so `/api/ai/patrol/findings` can refresh `resource_criticality` atread time after an operator changes priority, without waiting for the nextdiff --git a/docs/release-control/v6/internal/subsystems/monitoring.md b/docs/release-control/v6/internal/subsystems/monitoring.mdindex 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 activeoccurrence 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, andnode match and the task is active. `pollBackupTasks` stamps server observationdiff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.mdindex 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 andiff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.mdindex 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 AIsettings PUT must retain a stored `autonomous` preference and its existinglegacy 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.mdindex 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 inheritedvalue is `resource_and_descendants`, resolved against the canonical registryparent 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. SQLitepersists recurrence JSON and scope in additive columns while legacy one-shotrows retain their existing meaning. Scheduling, updating, changing scope, orclearing 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 Patrolfindings, because an active window suppresses alert activation andauto-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, becausehelp pages and the Assistant's refusal message refer to it; its help and lockconfirmation say it blocks every automated fix, including approved ones, andthat blocked runs are logged as failed actions (an Assistant planning refusaldiff --git a/frontend-modern/browser-verification/71f230975f168afd.json b/frontend-modern/browser-verification/71f230975f168afd.jsonnew file mode 100644index 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.tsxindex 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<ResourceOperatorStateSectioonChange={(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.tsindex 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.goindex 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.MaintenanceWindowf.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.goindex 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 thisdiff --git a/internal/api/ai_handlers_more_test.go b/internal/api/ai_handlers_more_test.goindex 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.goindex 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.goindex 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.ResourceOpreturn 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.goindex 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.ResourceOperatorStateif found {- applyActiveMaintenance(state, resourceID, false)+ own = &state}+ var ancestorIDs []stringif 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.goindex 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.goindex 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) (Maireturn 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 adiff --git a/internal/unifiedresources/resource_operator_state_policy_test.go b/internal/unifiedresources/resource_operator_state_policy_test.goindex 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")+ }+}