@upx-us/shield 0.7.10 → 0.7.12

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.12] — 2026-03-16
+
+### Fixed
+
+- **Plugin showing permanently "Disconnected" after gateway hot-reload** — when the OpenClaw gateway reloaded the plugin module, a race condition between teardown and startup caused new startup attempts to silently abort. The previous instance's timers kept running but were invisible to the status command, resulting in permanent "Disconnected" status and missed telemetry cycles. The teardown is now properly awaited before startup proceeds.
+
+---
+
+## [0.7.11] — 2026-03-16
+
+### Added
+
+- **Debug logging mode** (`debugLog: true`) — writes timestamped logs to `~/.openclaw/shield/logs/shield-debug.log`. Captures the full startup sequence with numbered checkpoints (1–11 + SIGTERM) so disconnection issues can be pinpointed exactly. Off by default — safe on all existing installs.
+
+---
+
 ## [0.7.10] — 2026-03-16
 
 ### Added

package/dist/index.js

@@ -319,6 +319,7 @@ const state = {
 };
 let firstEventDelivered = false;
 let teardownPreviousRuntime = null;
+let pendingTeardown = null;
 let serviceStartFn = null;
 const MAX_BACKOFF_MS = 5 * 60 * 1000;
 const TELEMETRY_INTERVAL_MS = 5 * 60 * 1000;
@@ -488,6 +489,38 @@ exports.default = {
         (0, log_1.setAdapter)(gatewayAdapter);
         const pluginConfig = (api.pluginConfig ?? {});
         log.debug('shield', 'Plugin config received', maskPluginConfigForLogs(pluginConfig));
+        const debugLogEnabled = pluginConfig.debugLog === true;
+        if (debugLogEnabled) {
+            try {
+                const { appendFileSync, mkdirSync } = require('fs');
+                const { join: pathJoin } = require('path');
+                const debugLogDir = pathJoin((0, os_1.homedir)(), '.openclaw', 'shield', 'logs');
+                const debugLogPath = pathJoin(debugLogDir, 'shield-debug.log');
+                mkdirSync(debugLogDir, { recursive: true });
+                const ts = () => new Date().toISOString();
+                const writeLine = (level, tag, msg, extra) => {
+                    try {
+                        const line = `${ts()} [${level.padEnd(5)}] [${tag}] ${msg}${extra !== undefined ? ' ' + JSON.stringify(extra) : ''}\n`;
+                        appendFileSync(debugLogPath, line);
+                    }
+                    catch { }
+                };
+                const teeAdapter = {
+                    debug(tag, msg, data) { gatewayAdapter.debug(tag, msg, data); writeLine('DEBUG', tag, msg, data); },
+                    info(tag, msg) { gatewayAdapter.info(tag, msg); writeLine('INFO', tag, msg); },
+                    warn(tag, msg) { gatewayAdapter.warn(tag, msg); writeLine('WARN', tag, msg); },
+                    error(tag, msg, err) { gatewayAdapter.error(tag, msg, err); writeLine('ERROR', tag, msg, err ? String(err) : undefined); },
+                };
+                (0, log_1.setAdapter)(teeAdapter);
+                appendFileSync(debugLogPath, `\n${'─'.repeat(80)}\n` +
+                    `${ts()} [SHIELD DEBUG SESSION START] v${version_1.VERSION}\n` +
+                    `${'─'.repeat(80)}\n`);
+                log.info('shield', `Debug logging active → ${debugLogPath}`);
+            }
+            catch (err) {
+                log.warn('shield', `Failed to init debug log file: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         if (pluginConfig.enabled === false) {
             log.info('shield', 'Monitoring disabled via config (enabled: false)');
             return;
@@ -543,13 +576,17 @@ exports.default = {
             }
         };
         if (teardownPreviousRuntime) {
-            void teardownPreviousRuntime()
+            pendingTeardown = teardownPreviousRuntime()
                 .catch((err) => log.warn('shield', `Runtime cleanup before re-register failed: ${err instanceof Error ? err.message : String(err)}`));
         }
         teardownPreviousRuntime = () => cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: false });
         const serviceDefinition = {
             id: 'shield-monitor',
             async start() {
+                if (pendingTeardown) {
+                    await pendingTeardown.catch(() => { });
+                    pendingTeardown = null;
+                }
                 if (!startGuard.begin()) {
                     log.debug('shield', 'Start requested while service is already started or in progress');
                     return;
@@ -557,8 +594,10 @@ exports.default = {
                 try {
                     await cleanupRuntime({ markStopped: false, resetGuard: false, flushRedactor: false });
                     const activeGeneration = ++runtimeGeneration;
+                    log.info('shield', `[checkpoint:1] Service start() entered — generation=${activeGeneration}`);
                     let credentials = (0, config_1.loadCredentials)();
                     let validCreds = hasValidCredentials(credentials);
+                    log.info('shield', `[checkpoint:2] Credentials loaded — valid=${validCreds} instanceId=${credentials?.instanceId ? credentials.instanceId.slice(0, 8) + '…' : 'missing'}`);
                     if (!validCreds && installationKey) {
                         log.info('shield', 'Installation key found — activating Shield (first-time setup)...');
                         const autoCreds = await performAutoRegistration(installationKey);
@@ -594,9 +633,12 @@ exports.default = {
                     const persistedStats = readAllTimeStats();
                     if (persistedStats.lastSync)
                         state.lastSync = persistedStats.lastSync;
+                    log.info('shield', `[checkpoint:3] Config loaded — sessionDirs=${config.sessionDirs.length} poll=${config.pollIntervalMs}ms dryRun=${config.dryRun}`);
                     log.info('shield', `Starting Shield v${version_1.VERSION} (poll: ${config.pollIntervalMs}ms, dryRun: ${config.dryRun})`);
                     (0, exclusions_1.initExclusions)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'));
+                    log.info('shield', '[checkpoint:4] Exclusions initialized');
                     (0, case_monitor_1.initCaseMonitor)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'));
+                    log.info('shield', '[checkpoint:5] Case monitor initialized');
                     if (config.localEventBuffer) {
                         (0, event_store_1.initEventStore)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'), { maxEvents: config.localEventLimit });
                     }
@@ -670,8 +712,10 @@ exports.default = {
                     catch { }
                     const autoUpdateMode = pluginConfig.autoUpdate ?? true;
                     const _bootState = (0, updater_1.loadUpdateState)();
+                    log.info('shield', `[checkpoint:6] Pre-update-check — autoUpdate=${autoUpdateMode} pendingRestart=${_bootState.pendingRestart} updateAvailable=${_bootState.updateAvailable} latestVersion=${_bootState.latestVersion}`);
                     log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION}, pendingRestart=${_bootState.pendingRestart})`);
                     const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, _bootState.pendingRestart ? undefined : 0);
+                    log.info('shield', `[checkpoint:7] Update check done — action=${startupUpdate.action}`);
                     if (startupUpdate.action === 'updated') {
                         log.info('updater', startupUpdate.message);
                         const restarted = (0, updater_1.requestGatewayRestart)();
@@ -703,10 +747,12 @@ exports.default = {
                     const { sendEvents, reportInstance } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
                     const { init: initRedactor, flush: flushRedactor, redactEvent } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
                     const { validate } = await Promise.resolve().then(() => __importStar(require('./src/validator')));
+                    log.info('shield', '[checkpoint:8] Dynamic imports loaded');
                     if (config.redactionEnabled)
                         initRedactor();
                     state.running = true;
                     persistState();
+                    log.info('shield', '[checkpoint:9] state.running=true — entering poll loop');
                     const runTelemetry = async () => {
                         if (!state.running || activeGeneration !== runtimeGeneration)
                             return;
@@ -748,6 +794,7 @@ exports.default = {
                         }
                     };
                     const runTelemetrySingleflight = createSingleflightRunner(runTelemetry);
+                    log.info('shield', '[checkpoint:9a] Firing initial telemetry');
                     runTelemetrySingleflight().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
                     telemetryHandle = setInterval(() => {
                         if (activeGeneration !== runtimeGeneration || !state.running)
@@ -904,15 +951,18 @@ exports.default = {
                             });
                         }, interval);
                     };
+                    log.info('shield', '[checkpoint:10] First poll scheduled');
                     schedulePoll();
                     onSignalHandler = async () => {
                         if (!state.running)
                             return;
+                        log.info('shield', '[checkpoint:SIGTERM] SIGTERM received — shutting down');
                         await cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: true });
                         log.info('shield', 'Service stopped (signal)');
                     };
                     process.once('SIGTERM', onSignalHandler);
                     process.once('SIGINT', onSignalHandler);
+                    log.info('shield', '[checkpoint:11] Startup complete — service running');
                     startGuard.endSuccess();
                 }
                 catch (err) {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "shield",
   "name": "OpenClaw Shield",
   "description": "Real-time security monitoring — streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "skills": [
     "./skills"
   ],
@@ -48,6 +48,11 @@
         ],
         "default": true,
         "description": "Auto-update mode: true (auto-update patch versions), false (disabled), or 'notify-only' (log available updates without installing)."
+      },
+      "debugLog": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable verbose debug logging to ~/.openclaw/shield/logs/shield-debug.log. Use only when diagnosing connectivity issues."
       }
     }
   },
@@ -74,6 +79,10 @@
     "autoUpdate": {
       "label": "Auto-update mode",
       "description": "true = auto-install patch updates, 'notify-only' = log only, false = disabled"
+    },
+    "debugLog": {
+      "label": "Debug logging",
+      "description": "Writes detailed startup and lifecycle logs to a file for support diagnosis"
     }
   },
   "clawhub": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "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",