@upx-us/shield 0.7.10 → 0.7.11

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [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

@@ -488,6 +488,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;
@@ -557,8 +589,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 +628,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 +707,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 +742,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 +789,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 +946,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.11",
   "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.11",
   "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",