@upx-us/shield 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.6.6] — 2026-03-10
+
+### Added
+- **Plugin lifecycle events** — the plugin now reports key lifecycle signals to the USS platform via the existing `PUT /v1/instance` channel (no new endpoint). Signals are forwarded by Cloud Run as an optional `lifecycle_event` field in the instance telemetry PATCH to the platform. Absent on older plugin versions — fully backward compatible.
+  - `plugin_started`: emitted on every successful startup. Includes `version`, `reason` (`'update'` | `'normal'`), and `previous_version` when applicable. Enables the platform to confirm end-to-end update success.
+  - `update_restart_failed`: emitted after all gateway restart retries are exhausted. Includes `new_version`, `running_version`, `attempts`, `error`.
+  - `plugin_integrity_drift`: emitted when `openclaw.json` version diverges from the installed version after a self-update. Includes `installed_version`, `registered_version`.
+  - `update_check_failing`: emitted after 3 consecutive npm registry check failures. Includes `consecutive_failures`, `last_error`, `next_retry_at`.
+
+### Changed
+- `reportPluginEvent()` removed from `sender.ts` — replaced by `reportLifecycleEvent()` which reuses the existing `PUT /v1/instance` telemetry channel.
+
+### Fixed
+- `SHIELD_AUTO_UPDATE=false` environment variable now correctly disables auto-update (was being read as truthy string `'false'`).
+
+---
+
+## [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

@@ -648,6 +648,18 @@ exports.default = {
                     catch (err) {
                         log.debug('case-monitor', `Direct send setup failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
                     }
+                    try {
+                        const updateState = (0, updater_1.loadUpdateState)();
+                        const previousVersion = updateState.rollbackVersion ?? null;
+                        const startReason = previousVersion ? 'update' : 'normal';
+                        const { reportLifecycleEvent } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
+                        void reportLifecycleEvent('plugin_started', {
+                            version: version_1.VERSION,
+                            reason: startReason,
+                            ...(previousVersion ? { previous_version: previousVersion } : {}),
+                        }, credentials);
+                    }
+                    catch { }
                     const autoUpdateMode = pluginConfig.autoUpdate ?? true;
                     log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION})`);
                     const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, 0);
@@ -879,6 +891,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 +909,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/dist/src/index.js

@@ -73,7 +73,8 @@ async function poll() {
         (0, event_store_1.initEventStore)(SHIELD_DATA_DIR, { maxEvents: config.localEventLimit });
     }
     log.info('bridge', `Starting — dryRun=${config.dryRun} poll=${config.pollIntervalMs}ms maxEvents=${config.maxEvents || 'unlimited'} redaction=${config.redactionEnabled} logLevel=${process.env.LOG_LEVEL || 'info'}`);
-    const autoUpdateMode = process.env.SHIELD_AUTO_UPDATE ?? true;
+    const _rawEnvStartup = process.env.SHIELD_AUTO_UPDATE;
+    const autoUpdateMode = _rawEnvStartup === 'false' ? false : _rawEnvStartup ?? true;
     log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION})`);
     const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, 0);
     if (startupUpdate.action === "none") {
@@ -147,7 +148,8 @@ async function poll() {
                     continue;
                 }
             }
-            const autoUpdateMode = process.env.SHIELD_AUTO_UPDATE ?? true;
+            const _rawEnvLoop = process.env.SHIELD_AUTO_UPDATE;
+            const autoUpdateMode = _rawEnvLoop === 'false' ? false : _rawEnvLoop ?? true;
             const updateResult = (0, updater_1.performAutoUpdate)(autoUpdateMode);
             if (updateResult.action !== "none") {
                 if (updateResult.action === "notify") {

package/dist/src/sender.d.ts

@@ -24,3 +24,4 @@ export interface ReportInstanceResult {
     score?: InstanceScore;
 }
 export declare function reportInstance(payload: Record<string, unknown>, credentials: ShieldCredentials): Promise<ReportInstanceResult>;
+export declare function reportLifecycleEvent(type: 'plugin_started' | 'update_restart_failed' | 'plugin_integrity_drift' | 'update_check_failing', data: Record<string, unknown>, credentials: ShieldCredentials): Promise<void>;

package/dist/src/sender.js

@@ -37,6 +37,7 @@ exports.CIRCUIT_BREAKER_THRESHOLD = exports.REQUEST_TIMEOUT_MS = void 0;
 exports._signRequestWithSecret = _signRequestWithSecret;
 exports.sendEvents = sendEvents;
 exports.reportInstance = reportInstance;
+exports.reportLifecycleEvent = reportLifecycleEvent;
 const crypto_1 = require("crypto");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
@@ -233,3 +234,16 @@ async function reportInstance(payload, credentials) {
         return { ok: false };
     }
 }
+async function reportLifecycleEvent(type, data, credentials) {
+    try {
+        await reportInstance({
+            lifecycle_event: {
+                type,
+                timestamp: new Date().toISOString(),
+                data,
+            },
+        }, credentials);
+    }
+    catch {
+    }
+}

package/dist/src/updater.js

@@ -53,6 +53,8 @@ const os_1 = require("os");
 const crypto_1 = require("crypto");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
+const config_1 = require("./config");
+const sender_1 = require("./sender");
 const PACKAGE_NAME = '@upx-us/shield';
 const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 const MIN_CHECK_INTERVAL_MS = 60 * 1000;
@@ -163,13 +165,28 @@ function checkForUpdate(overrideInterval) {
     state.currentVersion = version_1.VERSION;
     if (!latestVersion) {
         state.lastError = 'Failed to query npm registry';
+        state.consecutiveFailures = (state.consecutiveFailures ?? 0) + 1;
         saveUpdateState(state);
+        const FAILURE_THRESHOLD = 3;
+        if (state.consecutiveFailures >= FAILURE_THRESHOLD) {
+            const nextRetryAt = new Date(now + CHECK_INTERVAL_MS).toISOString();
+            try {
+                const creds = (0, config_1.loadCredentials)();
+                void (0, sender_1.reportLifecycleEvent)('update_check_failing', {
+                    consecutive_failures: state.consecutiveFailures,
+                    last_error: state.lastError,
+                    next_retry_at: nextRetryAt,
+                }, creds);
+            }
+            catch { }
+        }
         return null;
     }
     state.latestVersion = latestVersion;
     if (isNewerVersion(version_1.VERSION, latestVersion)) {
         state.updateAvailable = true;
         state.lastError = null;
+        state.consecutiveFailures = 0;
         saveUpdateState(state);
         const classification = classifyUpdate(version_1.VERSION, latestVersion);
         log.info('updater', `Update available: ${version_1.VERSION} → ${latestVersion} (${classification.isPatch ? 'patch' : classification.isMinor ? 'minor' : 'major'})`);
@@ -182,6 +199,7 @@ function checkForUpdate(overrideInterval) {
     }
     state.updateAvailable = false;
     state.lastError = null;
+    state.consecutiveFailures = 0;
     saveUpdateState(state);
     return null;
 }
@@ -302,6 +320,24 @@ function updateOpenClawPluginMetadata(newVersion, shasum) {
         install.installedAt = new Date().toISOString();
         (0, safe_io_1.writeJsonSafe)(configPath, config);
         log.info('updater', `Updated openclaw.json plugin metadata → ${newVersion}`);
+        try {
+            const written = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf-8'));
+            const installedVersion = written?.plugins?.installs?.shield?.version;
+            if (installedVersion !== newVersion) {
+                log.warn('updater', `openclaw.json integrity check failed: expected=${newVersion} got=${installedVersion ?? '(missing)'}`);
+                try {
+                    const creds = (0, config_1.loadCredentials)();
+                    void (0, sender_1.reportLifecycleEvent)('plugin_integrity_drift', {
+                        expected_version: newVersion,
+                        installed_version: installedVersion ?? null,
+                    }, creds);
+                }
+                catch { }
+            }
+        }
+        catch (verifyErr) {
+            log.warn('updater', `openclaw.json read-back failed: ${verifyErr instanceof Error ? verifyErr.message : String(verifyErr)}`);
+        }
     }
     catch (err) {
         log.warn('updater', `Failed to update openclaw.json metadata: ${err instanceof Error ? err.message : String(err)}`);
@@ -386,6 +422,16 @@ function performAutoUpdate(mode, checkIntervalMs) {
             const MAX_RESTART_ATTEMPTS = 5;
             if ((state.restartAttempts ?? 0) >= MAX_RESTART_ATTEMPTS) {
                 log.warn('updater', `Gateway restart failed ${MAX_RESTART_ATTEMPTS}x after update to ${state.currentVersion} — rolling back`);
+                try {
+                    const creds = (0, config_1.loadCredentials)();
+                    void (0, sender_1.reportLifecycleEvent)('update_restart_failed', {
+                        new_version: state.currentVersion,
+                        running_version: version_1.VERSION,
+                        attempts: state.restartAttempts ?? MAX_RESTART_ATTEMPTS,
+                        error: state.lastError ?? 'gateway restart exhausted all retries',
+                    }, creds);
+                }
+                catch { }
                 const backups = listBackups();
                 if (backups.length > 0) {
                     restoreFromBackup(backups[0]);

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.6",
   "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.6",
   "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",