@upx-us/shield 0.6.4 → 0.6.5

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.6.5] — 2026-03-09
+
+### Added
+- **Smart degradation detection in `shield status`** — `getMonitorHealth()` now implements a three-gate algorithm to eliminate false positives from transient connectivity blips:
+  1. **Count gate**: `consecutiveFailures ≥ 5` (unchanged from v0.6.4)
+  2. **Time gate**: first failure in the current streak must be `> 3 minutes` old — a 1-minute connectivity blip (3 failures at 1m intervals) can never trigger DEGRADED
+  3. **Sticky recovery**: requires `≥ 2 consecutive successes` to clear DEGRADED — prevents flapping where one success clears it and then it degrades again next cycle
+- **`MonitorHealth` interface** exported from `src/case-monitor.ts` — new fields: `status: 'ok' | 'degraded' | 'unknown'`, `consecutiveSuccesses`, `degradedSinceMs`, `lastCheckMs`, `lastErrorMessage`
+  - `status: 'unknown'` before the monitor has completed its first check cycle
+- **`shield.status` RPC** — `caseMonitor` section now includes smart health fields: `status`, `degradedSince` (ISO string), `consecutiveFailures`, `lastError`, `lastCheck` (ISO string), and a pre-formatted `display` string (e.g. `⚠️ Case Monitor: DEGRADED — 7 consecutive failures since 2026-03-09T12:00:00.000Z. Last error: ...` or `✅ Case Monitor: ok`)
+- **7 new tests** covering all degradation scenarios: unknown initial state, transient blip (count gate), time gate, true DEGRADED positive, sticky recovery (1 success not enough), recovery (2 successes clear), and RPC handler shape
+
+---
+
 ## [0.6.4] — 2026-03-09
 
 ### Fixed

package/dist/index.js

@@ -879,6 +879,10 @@ exports.default = {
             const creds = (0, config_1.loadCredentials)();
             const activated = state.activated || hasValidCredentials(creds);
             const caseStatus = (0, case_monitor_1.getCaseMonitorStatus)();
+            const monitorHealth = (0, case_monitor_1.getMonitorHealth)();
+            const caseMonitorDisplay = monitorHealth.status === 'degraded'
+                ? `⚠️ Case Monitor: DEGRADED — ${monitorHealth.consecutiveFailures} consecutive failures since ${monitorHealth.degradedSinceMs ? new Date(monitorHealth.degradedSinceMs).toISOString() : 'unknown'}. Last error: ${monitorHealth.lastErrorMessage}`
+                : `✅ Case Monitor: ok`;
             respond(true, {
                 activated,
                 running: state.running,
@@ -893,6 +897,16 @@ exports.default = {
                     intervalMs: caseStatus.intervalMs,
                     nextCheckInMs: caseStatus.nextCheckIn,
                     lastCheckAt: caseStatus.lastCheckAt,
+                    status: monitorHealth.status,
+                    degradedSince: monitorHealth.degradedSinceMs
+                        ? new Date(monitorHealth.degradedSinceMs).toISOString()
+                        : null,
+                    consecutiveFailures: monitorHealth.consecutiveFailures,
+                    lastError: monitorHealth.lastErrorMessage,
+                    lastCheck: monitorHealth.lastCheckMs
+                        ? new Date(monitorHealth.lastCheckMs).toISOString()
+                        : null,
+                    display: caseMonitorDisplay,
                 },
             });
         });

package/dist/src/case-monitor.d.ts

@@ -56,10 +56,15 @@ export interface CaseDetail extends CaseSummary {
 }
 export declare function initCaseMonitor(dataDir: string): void;
 export declare function notifyCaseMonitorActivity(): void;
-export declare function getMonitorHealth(): {
-    status: 'ok' | 'degraded';
+export interface MonitorHealth {
+    status: 'ok' | 'degraded' | 'unknown';
     consecutiveFailures: number;
-};
+    consecutiveSuccesses: number;
+    degradedSinceMs: number | null;
+    lastCheckMs: number | null;
+    lastErrorMessage: string | null;
+}
+export declare function getMonitorHealth(): MonitorHealth;
 export declare function getCaseMonitorStatus(): {
     intervalMs: number;
     nextCheckIn: number;
@@ -70,4 +75,6 @@ export declare function getPendingCases(): CaseSummary[];
 export declare function acknowledgeCases(caseIds: string[]): void;
 export declare function formatCaseNotification(c: CaseSummary | CaseDetail): string;
 export declare function _resetForTesting(): void;
+export declare function _simulateFailuresForTesting(count: number, firstFailureAgeMs: number): void;
+export declare function _simulateSuccessForTesting(): void;
 export {};

package/dist/src/case-monitor.js

@@ -44,6 +44,8 @@ exports.getPendingCases = getPendingCases;
 exports.acknowledgeCases = acknowledgeCases;
 exports.formatCaseNotification = formatCaseNotification;
 exports._resetForTesting = _resetForTesting;
+exports._simulateFailuresForTesting = _simulateFailuresForTesting;
+exports._simulateSuccessForTesting = _simulateSuccessForTesting;
 const safe_io_1 = require("./safe-io");
 const client_1 = require("./rpc/client");
 const exclusions_1 = require("./exclusions");
@@ -164,7 +166,14 @@ let _lastEventAt = 0;
 let _currentIntervalMs = MAX_CHECK_INTERVAL_MS;
 let _exclusionsWarnedOnce = false;
 let _consecutiveCheckFailures = 0;
+let _consecutiveSuccesses = 0;
+let _degradedSinceMs = null;
+let _firstFailureInStreakMs = null;
+let _lastCheckMs = null;
+let _lastErrorMessage = null;
 const DEGRADED_THRESHOLD = 5;
+const DEGRADED_TIME_GATE_MS = 3 * 60 * 1000;
+const RECOVERY_THRESHOLD = 2;
 function computeInterval() {
     if (_lastCheckAt === 0)
         return MIN_CHECK_INTERVAL_MS;
@@ -186,11 +195,58 @@ function notifyCaseMonitorActivity() {
     _lastEventAt = Date.now();
 }
 function getMonitorHealth() {
+    const now = Date.now();
+    const isDegraded = _consecutiveCheckFailures >= DEGRADED_THRESHOLD &&
+        _firstFailureInStreakMs !== null &&
+        (now - _firstFailureInStreakMs) >= DEGRADED_TIME_GATE_MS;
+    if (isDegraded && _degradedSinceMs === null) {
+        _degradedSinceMs = now;
+    }
+    let status;
+    if (_lastCheckMs === null) {
+        status = 'unknown';
+    }
+    else if (isDegraded) {
+        status = 'degraded';
+    }
+    else {
+        status = 'ok';
+    }
     return {
-        status: _consecutiveCheckFailures >= DEGRADED_THRESHOLD ? 'degraded' : 'ok',
+        status,
         consecutiveFailures: _consecutiveCheckFailures,
+        consecutiveSuccesses: _consecutiveSuccesses,
+        degradedSinceMs: _degradedSinceMs,
+        lastCheckMs: _lastCheckMs,
+        lastErrorMessage: _lastErrorMessage,
     };
 }
+function recordCheckFailure(message) {
+    const now = Date.now();
+    if (_consecutiveCheckFailures === 0) {
+        _firstFailureInStreakMs = now;
+    }
+    _consecutiveCheckFailures++;
+    _consecutiveSuccesses = 0;
+    _lastCheckMs = now;
+    _lastErrorMessage = message;
+    if (_degradedSinceMs === null &&
+        _consecutiveCheckFailures >= DEGRADED_THRESHOLD &&
+        _firstFailureInStreakMs !== null &&
+        (now - _firstFailureInStreakMs) >= DEGRADED_TIME_GATE_MS) {
+        _degradedSinceMs = now;
+    }
+}
+function recordCheckSuccess() {
+    _consecutiveSuccesses++;
+    _lastCheckMs = Date.now();
+    _lastErrorMessage = null;
+    if (_consecutiveSuccesses >= RECOVERY_THRESHOLD) {
+        _consecutiveCheckFailures = 0;
+        _firstFailureInStreakMs = null;
+        _degradedSinceMs = null;
+    }
+}
 function getCaseMonitorStatus() {
     const interval = computeInterval();
     const nextCheckIn = Math.max(0, (_lastCheckAt + interval) - Date.now());
@@ -220,7 +276,7 @@ async function checkForNewCases(config) {
         const result = await (0, client_1.callPlatformApi)(config, '/v1/agent/cases', params, 'GET');
         if (!result.ok) {
             if (!result.error?.includes('not configured')) {
-                _consecutiveCheckFailures++;
+                recordCheckFailure(result.error ?? 'unknown error');
                 log.warn('case-monitor', `Failed to check cases: ${result.error}`);
                 if (_consecutiveCheckFailures >= DEGRADED_THRESHOLD) {
                     log.warn('case-monitor', `[case-monitor] DEGRADED: ${_consecutiveCheckFailures} consecutive check failures — notifications may be silently dropped`);
@@ -260,11 +316,12 @@ async function checkForNewCases(config) {
         }
         state.lastCheckAt = new Date().toISOString();
         (0, safe_io_1.writeJsonSafe)(stateFile, state);
-        _consecutiveCheckFailures = 0;
+        recordCheckSuccess();
     }
     catch (err) {
-        _consecutiveCheckFailures++;
-        log.warn('case-monitor', `Check failed: ${err instanceof Error ? err.message : String(err)}`);
+        const msg = err instanceof Error ? err.message : String(err);
+        recordCheckFailure(msg);
+        log.warn('case-monitor', `Check failed: ${msg}`);
         if (_consecutiveCheckFailures >= DEGRADED_THRESHOLD) {
             log.warn('case-monitor', `[case-monitor] DEGRADED: ${_consecutiveCheckFailures} consecutive check failures — notifications may be silently dropped`);
         }
@@ -369,6 +426,11 @@ function _resetForTesting() {
     _currentIntervalMs = MAX_CHECK_INTERVAL_MS;
     _exclusionsWarnedOnce = false;
     _consecutiveCheckFailures = 0;
+    _consecutiveSuccesses = 0;
+    _degradedSinceMs = null;
+    _firstFailureInStreakMs = null;
+    _lastCheckMs = null;
+    _lastErrorMessage = null;
     _enqueueSystemEvent = null;
     _requestHeartbeatNow = null;
     _agentId = 'main';
@@ -376,3 +438,21 @@ function _resetForTesting() {
     _directSendTo = null;
     _directSendChannel = null;
 }
+function _simulateFailuresForTesting(count, firstFailureAgeMs) {
+    const now = Date.now();
+    _firstFailureInStreakMs = now - firstFailureAgeMs;
+    _consecutiveCheckFailures = count;
+    _consecutiveSuccesses = 0;
+    _lastCheckMs = now - firstFailureAgeMs;
+    _lastErrorMessage = 'simulated failure';
+}
+function _simulateSuccessForTesting() {
+    _consecutiveSuccesses++;
+    _lastCheckMs = Date.now();
+    _lastErrorMessage = null;
+    if (_consecutiveSuccesses >= RECOVERY_THRESHOLD) {
+        _consecutiveCheckFailures = 0;
+        _firstFailureInStreakMs = null;
+        _degradedSinceMs = null;
+    }
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "shield",
   "name": "OpenClaw Shield",
   "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "skills": [
     "./skills"
   ],
@@ -78,7 +78,7 @@
   },
   "clawhub": {
     "slug": "openclaw-shield-upx",
-    "skillVersion": "1.2.5",
+    "skillVersion": "0.6.5",
     "note": "ClawHub auto-increments on publish. Update this after each clawhub submission."
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Security monitoring plugin for OpenClaw agents — streams enriched security events to the Shield detection platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",