@upx-us/shield 0.7.9 → 0.7.11

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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
+
+- **`openclaw shield restart` command** — restarts Shield monitoring without a full gateway restart. Checks credentials, clears any stale update state, resets the session, and cycles the runtime. Use `--verbose` for step-by-step diagnostic output.
+
+### Fixed
+
+- **Plugin no longer silently stalls when telemetry consistently fails** — after 10 consecutive failed `reportInstance` calls, the plugin deactivates with a clear log message instead of running indefinitely with no output.
+- **Update cycle cleanup after successful auto-update** — the periodic update check now properly stops all activity after calling a successful gateway restart, preventing a window where both the old and new instance could be active simultaneously.
+
+### Changed
+
+- **Standalone `shield-bridge` binary removed** — the plugin now runs exclusively as an OpenClaw gateway plugin. Running `npx @upx-us/shield` directly shows a clear message with installation instructions. This eliminates a source of divergent behavior that caused the v0.7.7 incident.
+- `bridge` terminology removed from all customer-visible log output and internal comments.
+
+---
+
 ## [0.7.9] — 2026-03-16
 
 ### Fixed

package/dist/index.js

@@ -319,8 +319,10 @@ const state = {
 };
 let firstEventDelivered = false;
 let teardownPreviousRuntime = null;
+let serviceStartFn = null;
 const MAX_BACKOFF_MS = 5 * 60 * 1000;
 const TELEMETRY_INTERVAL_MS = 5 * 60 * 1000;
+const MAX_REGISTRATION_FAILURES = 10;
 function getBackoffInterval(baseMs) {
     if (state.consecutiveFailures === 0)
         return baseMs;
@@ -486,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;
@@ -545,7 +579,7 @@ exports.default = {
                 .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 });
-        api.registerService({
+        const serviceDefinition = {
             id: 'shield-monitor',
             async start() {
                 if (!startGuard.begin()) {
@@ -555,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);
@@ -565,7 +601,7 @@ exports.default = {
                             startGuard.endFailure();
                             return;
                         }
-                        log.info('shield', '✅ Shield activated! Starting monitoring bridge...');
+                        log.info('shield', '✅ Shield activated! Starting Shield monitoring...');
                         log.info('shield', `   Credentials saved to ${config_1.SHIELD_CONFIG_PATH}`);
                         log.info('shield', '   Tip: you can remove installationKey from config after first activation.');
                         credentials = autoCreds;
@@ -592,9 +628,12 @@ exports.default = {
                     const persistedStats = readAllTimeStats();
                     if (persistedStats.lastSync)
                         state.lastSync = persistedStats.lastSync;
-                    log.info('shield', `Starting monitoring bridge v${version_1.VERSION} (poll: ${config.pollIntervalMs}ms, dryRun: ${config.dryRun})`);
+                    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 });
                     }
@@ -668,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)();
@@ -701,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;
@@ -732,8 +775,21 @@ exports.default = {
                         if (activeGeneration !== runtimeGeneration)
                             return;
                         log.info('shield', `Instance report → Platform: success=${result.ok}`);
+                        if (result.ok) {
+                            state.consecutiveFailures = 0;
+                        }
+                        else {
+                            state.consecutiveFailures++;
+                            if (state.consecutiveFailures >= MAX_REGISTRATION_FAILURES) {
+                                log.error('shield', `Instance report failed ${state.consecutiveFailures} consecutive times — Shield deactivated. Re-run: openclaw shield activate <KEY>`);
+                                state.running = false;
+                                markStateDirty();
+                                persistState();
+                            }
+                        }
                     };
                     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)
@@ -744,9 +800,12 @@ exports.default = {
                             if (updateResult.action !== 'none') {
                                 log.info('updater', updateResult.message);
                                 if (updateResult.action === 'updated') {
-                                    if (!(0, updater_1.requestGatewayRestart)()) {
-                                        log.warn('updater', 'Restart not available — new version loads on next manual restart');
+                                    const restarted = (0, updater_1.requestGatewayRestart)();
+                                    if (restarted) {
+                                        cleanupRuntime({ markStopped: true, flushRedactor: true });
+                                        return;
                                     }
+                                    log.warn('updater', 'Restart not available — new version loads on next manual restart');
                                 }
                             }
                         }
@@ -887,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) {
@@ -909,7 +971,9 @@ exports.default = {
                 if (wasRunning)
                     log.info('shield', 'Service stopped');
             },
-        });
+        };
+        serviceStartFn = serviceDefinition.start.bind(serviceDefinition);
+        api.registerService(serviceDefinition);
         api.registerGatewayMethod('shield.status', ({ respond }) => {
             const creds = (0, config_1.loadCredentials)();
             const activated = state.activated || hasValidCredentials(creds);
@@ -1114,13 +1178,108 @@ exports.default = {
                 .description('Trigger an immediate poll cycle')
                 .action(async () => {
                 if (!pollFn) {
-                    console.error('Bridge not started');
+                    console.error('Shield is not running');
                     return;
                 }
                 console.log('Flushing...');
                 await pollFn();
                 console.log('Done');
             });
+            shield.command('restart')
+                .description('Restart Shield monitoring (use when status shows Disconnected)')
+                .option('--verbose', 'Show detailed diagnostic output during restart')
+                .action(async (opts) => {
+                const verbose = opts.verbose ?? false;
+                const step = (msg) => { if (verbose)
+                    console.log(`  [restart] ${msg}`); };
+                console.log('🛡️  Restarting Shield monitoring...');
+                console.log('');
+                step('Reading current state...');
+                const wasRunning = state.running;
+                const wasActivated = state.activated;
+                const failures = state.consecutiveFailures ?? 0;
+                const lastPollAgo = state.lastPollAt
+                    ? `${Math.round((Date.now() - state.lastPollAt) / 1000)}s ago`
+                    : 'never';
+                console.log(`  Was running:   ${wasRunning ? 'yes' : 'no'}`);
+                console.log(`  Activated:     ${wasActivated ? 'yes' : 'no'}`);
+                console.log(`  Last poll:     ${lastPollAgo}`);
+                console.log(`  Failures:      ${failures}`);
+                console.log('');
+                step('Checking credentials...');
+                const creds = (0, config_1.loadCredentials)();
+                if (!hasValidCredentials(creds)) {
+                    console.error('❌ Cannot restart — Shield is not activated.');
+                    console.error('   Run: openclaw shield activate <YOUR_KEY>');
+                    return;
+                }
+                step(`Credentials OK (instance: ${(creds.instanceId || '').slice(0, 8)}…)`);
+                step('Checking update state...');
+                const updateState = (0, updater_1.loadUpdateState)();
+                if (updateState.pendingRestart) {
+                    console.warn('  ⚠️  update-state.json has pendingRestart:true — clearing before restart');
+                    updateState.pendingRestart = false;
+                    updateState.restartAttempts = 0;
+                    const { saveUpdateState } = require('./src/updater');
+                    saveUpdateState(updateState);
+                    step('pendingRestart cleared');
+                }
+                if (updateState.updateAvailable && updateState.latestVersion === updateState.currentVersion) {
+                    console.warn('  ⚠️  Stale updateAvailable flag detected — clearing');
+                    updateState.updateAvailable = false;
+                    const { saveUpdateState } = require('./src/updater');
+                    saveUpdateState(updateState);
+                    step('Stale updateAvailable cleared');
+                }
+                step('Resetting session state...');
+                state.running = false;
+                state.consecutiveFailures = 0;
+                state.lastPollAt = 0;
+                state.captureSeenSinceLastSync = false;
+                markStateDirty();
+                persistState();
+                step('State reset');
+                step('Stopping current runtime...');
+                if (typeof teardownPreviousRuntime === 'function') {
+                    await teardownPreviousRuntime();
+                    step('Runtime torn down');
+                }
+                else {
+                    step('No active runtime to tear down');
+                }
+                console.log('  Restarting...');
+                step('Calling service start...');
+                try {
+                    if (!serviceStartFn) {
+                        console.error('❌ Service not initialized — try: openclaw gateway restart');
+                        return;
+                    }
+                    await serviceStartFn();
+                    await new Promise(r => setTimeout(r, 2000));
+                    const nowRunning = state.running;
+                    const nowLastPoll = state.lastPollAt
+                        ? `${Math.round((Date.now() - state.lastPollAt) / 1000)}s ago`
+                        : 'not yet';
+                    console.log('');
+                    if (nowRunning) {
+                        console.log(`✅ Shield restarted successfully.`);
+                        console.log(`   Running: yes | Last poll: ${nowLastPoll} | Failures: ${state.consecutiveFailures}`);
+                    }
+                    else {
+                        console.log('⚠️  Shield started but running flag is not set yet.');
+                        console.log(`   Last poll: ${nowLastPoll} | Failures: ${state.consecutiveFailures}`);
+                        console.log('   Run `openclaw shield status` in a few seconds to confirm.');
+                    }
+                }
+                catch (err) {
+                    console.error('');
+                    console.error(`❌ Restart failed: ${err instanceof Error ? err.message : String(err)}`);
+                    if (verbose) {
+                        console.error(err instanceof Error ? err.stack : '');
+                    }
+                    console.error('   If this persists, run: openclaw gateway restart');
+                }
+            });
             shield.command('activate')
                 .description('Activate Shield with an Installation Key')
                 .argument('<key>', 'Installation Key from the Shield portal')

package/dist/src/index.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/index.js

@@ -1,348 +1,13 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-const os = __importStar(require("os"));
-const path = __importStar(require("path"));
-const updater_1 = require("./updater");
-const config_1 = require("./config");
-const log = __importStar(require("./log"));
-const fetcher_1 = require("./fetcher");
-const transformer_1 = require("./transformer");
-const sender_1 = require("./sender");
-const redactor_1 = require("./redactor");
-const validator_1 = require("./validator");
-const fs_1 = require("fs");
-const version_1 = require("./version");
-const event_store_1 = require("./event-store");
-const case_monitor_1 = require("./case-monitor");
-const exclusions_1 = require("./exclusions");
-const SHIELD_DATA_DIR = path.join(os.homedir(), '.openclaw', 'shield', 'data');
-function extractEventDetails(event) {
-    const path = event.target?.file_path || event.target?.file?.path || event.target?.process?.command_line;
-    const url = event.network?.http?.url || event.target?.url || event.url;
-    if (path)
-        return path.length > 100 ? path.slice(0, 97) + '…' : path;
-    if (url)
-        return url.length > 100 ? url.slice(0, 97) + '…' : url;
-    return undefined;
-}
-let running = true;
-let lastTelemetryAt = 0;
-let consecutiveFailures = 0;
-let registrationOk = false;
-const TELEMETRY_INTERVAL_MS = 5 * 60 * 1000;
-const MAX_BACKOFF_MS = 5 * 60 * 1000;
-const MAX_REGISTRATION_FAILURES = 10;
-function getBackoffInterval(baseMs) {
-    if (consecutiveFailures === 0)
-        return baseMs;
-    const backoff = baseMs * Math.pow(2, Math.min(consecutiveFailures, 10));
-    return Math.min(backoff, MAX_BACKOFF_MS);
-}
-async function poll() {
-    const config = (0, config_1.loadConfig)();
-    if (config.redactionEnabled) {
-        (0, redactor_1.init)();
-    }
-    (0, exclusions_1.initExclusions)(SHIELD_DATA_DIR);
-    (0, case_monitor_1.initCaseMonitor)(SHIELD_DATA_DIR);
-    if (config.localEventBuffer) {
-        (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 _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 _bootState = (0, updater_1.loadUpdateState)();
-    const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, _bootState.pendingRestart ? undefined : 0);
-    if (startupUpdate.action === "none") {
-        log.info("updater", `Up to date (${version_1.VERSION})`);
-    }
-    else if (startupUpdate.action === "updated") {
-        log.info("updater", startupUpdate.message);
-        const restarted = (0, updater_1.requestGatewayRestart)();
-        if (restarted)
-            return;
-        log.warn("updater", "Gateway restart failed — continuing with current version. Restart manually to load the update.");
-    }
-    else if (startupUpdate.action === "notify") {
-        log.info("updater", startupUpdate.message);
-    }
-    else if (startupUpdate.action === "rollback" || startupUpdate.action === "error") {
-        log.warn("updater", startupUpdate.message);
-    }
-    while (running) {
-        try {
-            let entries = await (0, fetcher_1.fetchNewEntries)(config);
-            const now = Date.now();
-            if (now - lastTelemetryAt >= TELEMETRY_INTERVAL_MS) {
-                const hostSnapshot = config.collectHostMetrics ? (0, transformer_1.generateHostTelemetry)() : null;
-                const hostMeta = hostSnapshot?.event?.tool_metadata;
-                const agentId = process.env.OPENCLAW_AGENT_ID || 'main';
-                const instancePayload = {
-                    machine: {
-                        hostname: config.hostname,
-                        os: process.platform,
-                        arch: process.arch,
-                        node_version: process.version,
-                        public_ip: (0, transformer_1.getCachedPublicIp)() ?? '',
-                    },
-                    software: {
-                        plugin_version: (0, version_1.getVersion)(),
-                        openclaw_version: (0, transformer_1.resolveOpenClawVersion)(),
-                        agent_label: (0, transformer_1.resolveAgentLabel)(agentId),
-                        instance_name: (0, transformer_1.resolveAgentLabel)(agentId) || config.hostname,
-                        ...(hostMeta && {
-                            gateway_bind: hostMeta['openclaw.gateway_bind'],
-                            webhook_configured: hostMeta['openclaw.webhook_configured'],
-                            browser_auth_required: hostMeta['openclaw.browser_auth_required'],
-                        }),
-                    },
-                };
-                if (!(0, transformer_1.getCachedPublicIp)()) {
-                    log.warn('bridge', 'Public IP not yet resolved — sending empty public_ip so platform can enrich server-side');
-                }
-                const result = await (0, sender_1.reportInstance)(instancePayload, config.credentials);
-                log.info('bridge', `Instance report → Platform: success=${result.ok}`);
-                if (result.ok) {
-                    registrationOk = true;
-                    lastTelemetryAt = now;
-                    if (result.score) {
-                        log.info('bridge', `Protection score: ${result.score.badge} ${result.score.total}/100 (${result.score.grade})`);
-                        if (result.score.recommendations?.length) {
-                            for (const rec of result.score.recommendations) {
-                                log.warn('bridge', `⚠ ${rec}`);
-                            }
-                        }
-                    }
-                }
-                else if (!registrationOk) {
-                    consecutiveFailures++;
-                    if (consecutiveFailures >= MAX_REGISTRATION_FAILURES) {
-                        log.error('bridge', `reportInstance failed ${consecutiveFailures} consecutive times — instance not recognized. Re-run setup wizard. Exiting.`);
-                        process.exit(1);
-                    }
-                    log.warn('bridge', `reportInstance failed (attempt ${consecutiveFailures}/${MAX_REGISTRATION_FAILURES}) — skipping events this cycle (platform may still be syncing)`);
-                    continue;
-                }
-            }
-            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") {
-                    log.info("updater", updateResult.message);
-                }
-                else if (updateResult.action === "updated") {
-                    log.info("updater", updateResult.message);
-                    const restarted = (0, updater_1.requestGatewayRestart)();
-                    if (restarted) {
-                        running = false;
-                        break;
-                    }
-                    log.warn("updater", "Gateway restart failed — continuing with current version. Restart manually to load the update.");
-                }
-                else if (updateResult.action === "rollback") {
-                    log.warn("updater", updateResult.message);
-                }
-                else if (updateResult.action === "error") {
-                    log.error("updater", updateResult.message);
-                }
-            }
-            if (entries.length > 0) {
-                let envelopes = (0, transformer_1.transformEntries)(entries, config.sessionDirs);
-                const { valid: validEnvelopes, quarantined } = (0, validator_1.validate)(envelopes.map(e => e.event));
-                if (quarantined > 0) {
-                    log.warn('bridge', `${quarantined} events quarantined (see ~/.openclaw/shield/data/quarantine.jsonl)`);
-                }
-                envelopes = envelopes.filter(e => validEnvelopes.includes(e.event));
-                if (config.maxEvents > 0 && envelopes.length > config.maxEvents) {
-                    log.info('bridge', `Limiting to ${config.maxEvents} of ${envelopes.length} events (maxEvents cap)`);
-                    envelopes = envelopes.slice(0, config.maxEvents);
-                }
-                if (config.redactionEnabled) {
-                    envelopes = envelopes.map(env => {
-                        const redacted = (0, redactor_1.redactEvent)(env);
-                        log.debug('redactor', `tool=${env.event.tool_name} session=${env.event.session_id}`, { event: redacted.event });
-                        return redacted;
-                    });
-                }
-                log.info('bridge', `${entries.length} entries → ${envelopes.length} envelopes`);
-                const results = await (0, sender_1.sendEvents)(envelopes, config);
-                for (const r of results) {
-                    if (r.success) {
-                        log.info('bridge', `Result: success=${r.success} status=${r.statusCode} events=${r.eventCount}`);
-                    }
-                    else {
-                        log.error('bridge', `Result: FAILED status=${r.statusCode} events=${r.eventCount} body=${r.body?.slice(0, 200)}`);
-                    }
-                }
-                if (config.localEventBuffer && results.some(r => r.success)) {
-                    const summaries = envelopes.map(env => ({
-                        ts: env.event.timestamp,
-                        type: env.event.event_type || 'UNKNOWN',
-                        tool: env.event.tool_name || 'unknown',
-                        summary: env.event.tool_metadata?.["openclaw.display_summary"] || env.event.target?.command_line || env.event.tool_name || 'event',
-                        session: env.event.session_id || '?',
-                        model: env.event.model || '?',
-                        redacted: !!env.source?.plugin?.redaction_applied,
-                        details: extractEventDetails(env.event),
-                        trigger_type: env.event.tool_metadata?.['trigger.type'] ?? undefined,
-                    }));
-                    (0, event_store_1.appendEvents)(summaries);
-                }
-                if (results.some(r => r.needsRegistration)) {
-                    consecutiveFailures++;
-                    registrationOk = false;
-                    lastTelemetryAt = 0;
-                    if (consecutiveFailures >= MAX_REGISTRATION_FAILURES) {
-                        log.error('bridge', `Instance not recognized by platform after ${consecutiveFailures} attempts. Re-run the setup wizard. Exiting.`);
-                        process.exit(1);
-                    }
-                    log.warn('bridge', `Instance not registered on platform (attempt ${consecutiveFailures}/${MAX_REGISTRATION_FAILURES}) — will re-register on next cycle`);
-                    continue;
-                }
-                const pendingResult = results.find(r => r.pendingNamespace);
-                if (pendingResult) {
-                    const retryAfterMs = Math.min(pendingResult.retryAfterMs ?? 300_000, MAX_BACKOFF_MS);
-                    log.warn('bridge', `Namespace pending — holding cursors, retrying in ${Math.round(retryAfterMs / 1000)}s`);
-                    await new Promise(r => setTimeout(r, retryAfterMs));
-                    continue;
-                }
-                const allSuccess = results.every(r => r.success);
-                if (allSuccess) {
-                    (0, fetcher_1.commitCursors)(config, entries);
-                    if (config.redactionEnabled)
-                        (0, redactor_1.flush)();
-                    log.info('bridge', 'Cursors committed');
-                    consecutiveFailures = 0;
-                }
-                else {
-                    consecutiveFailures++;
-                    log.warn('bridge', 'Some batches failed — cursors NOT updated (will retry next poll)');
-                }
-                if (config.maxEvents > 0) {
-                    log.info('bridge', 'Test mode complete, exiting');
-                    running = false;
-                    break;
-                }
-            }
-            else {
-                (0, fetcher_1.commitCursors)(config, []);
-                consecutiveFailures = 0;
-            }
-        }
-        catch (err) {
-            consecutiveFailures++;
-            log.error('bridge', 'Poll error', err);
-        }
-        try {
-            const creds = (0, config_1.loadCredentials)();
-            const platformConfig = {
-                apiUrl: config.platformApiUrl ?? null,
-                instanceId: creds?.instanceId || '',
-                hmacSecret: creds?.hmacSecret || '',
-            };
-            await (0, case_monitor_1.checkForNewCases)(platformConfig);
-        }
-        catch (err) {
-            log.debug('case-monitor', `Check error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        if (!running)
-            break;
-        const interval = getBackoffInterval(config.pollIntervalMs);
-        if (interval !== config.pollIntervalMs) {
-            log.warn('bridge', `Backing off: next poll in ${Math.round(interval / 1000)}s (${consecutiveFailures} consecutive failures)`);
-        }
-        await new Promise(r => setTimeout(r, interval));
-    }
-    if (config.redactionEnabled)
-        (0, redactor_1.flush)();
-    console.log('[Shield Bridge] Stopped');
-}
-function checkConfiguration() {
-    if (!(0, fs_1.existsSync)(config_1.SHIELD_CONFIG_PATH)) {
-        const { SHIELD_API_URL, SHIELD_INSTANCE_ID, SHIELD_HMAC_SECRET, SHIELD_FINGERPRINT, SHIELD_SECRET } = process.env;
-        if (SHIELD_API_URL && (SHIELD_INSTANCE_ID || SHIELD_FINGERPRINT) && (SHIELD_HMAC_SECRET || SHIELD_SECRET))
-            return true;
-        console.log('🛡️  OpenClaw Shield — First Time Setup Required');
-        console.log('=================================================\n');
-        console.log(`No config found at ${config_1.SHIELD_CONFIG_PATH}`);
-        console.log('Run the setup wizard to connect to your Shield API:\n');
-        console.log('  npx shield-setup\n');
-        return false;
-    }
-    (0, config_1.injectConfigEnv)();
-    const creds = (0, config_1.loadCredentials)();
-    if (!creds.apiUrl || !creds.instanceId || !creds.hmacSecret) {
-        console.error('❌ Shield config is incomplete. Missing apiUrl, instanceId, or hmacSecret.');
-        console.error(`   Config file: ${config_1.SHIELD_CONFIG_PATH}`);
-        console.error('   Run: npx shield-setup');
-        return false;
-    }
-    return true;
-}
-if (!checkConfiguration()) {
-    process.exit(1);
-}
-const config = (0, config_1.loadConfig)();
-process.on('SIGINT', () => {
-    console.log('\n[Shield Bridge] Shutting down...');
-    if (config.redactionEnabled)
-        (0, redactor_1.flush)();
-    running = false;
-});
-process.on('SIGTERM', () => {
-    console.log('\n[Shield Bridge] Received SIGTERM, shutting down gracefully...');
-    if (config.redactionEnabled)
-        (0, redactor_1.flush)();
-    running = false;
-});
-poll().catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error('[Shield Bridge] Fatal error:', msg);
-    if (msg.includes('ENOTFOUND') || msg.includes('ECONNREFUSED')) {
-        console.error('\n💡 This looks like a network connectivity issue.');
-        console.error('   - Check your Shield API URL in the configuration');
-        console.error('   - Verify your internet connection');
-        console.error('   - Run: npm run setup -- --verify');
-    }
-    else if (msg.includes('401') || msg.includes('403')) {
-        console.error('\n💡 This looks like an authentication issue.');
-        console.error('   - Verify your Shield API credentials');
-        console.error('   - Run: npm run setup');
-    }
-    process.exit(1);
-});
+console.error('');
+console.error('OpenClaw Shield is an OpenClaw plugin — it runs inside the OpenClaw gateway,');
+console.error('not as a standalone process.');
+console.error('');
+console.error('To get started:');
+console.error('  1. Install OpenClaw       https://openclaw.ai');
+console.error('  2. Install the plugin     openclaw plugins install @upx-us/shield');
+console.error('  3. Activate               openclaw shield activate <YOUR_KEY>');
+console.error('');
+console.error('Get your key at: https://www.upx.com/en/lp/openclaw-shield-upx');
+console.error('');
+process.exit(1);

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.9",
+  "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,11 +1,10 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.7.9",
+  "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",
   "bin": {
-    "shield-bridge": "dist/src/index.js",
     "shield-setup": "dist/src/setup.js"
   },
   "files": [