@upx-us/shield 0.7.13 → 0.8.0

package/dist/index.js

@@ -39,6 +39,7 @@ exports.maskPluginConfigForLogs = maskPluginConfigForLogs;
 exports.createSingleflightRunner = createSingleflightRunner;
 exports.createStartGuard = createStartGuard;
 exports.getStatusWarnings = getStatusWarnings;
+exports._resetForTesting = _resetForTesting;
 const config_1 = require("./src/config");
 const log_1 = require("./src/log");
 const log = __importStar(require("./src/log"));
@@ -231,6 +232,61 @@ function flushAllTimeStats() {
 }
 let _stateDirty = true;
 function markStateDirty() { _stateDirty = true; }
+function createInitialState() {
+    return {
+        activated: false,
+        running: false,
+        startedAt: 0,
+        lastPollAt: 0,
+        lastSuccessfulPollAt: 0,
+        eventsProcessed: 0,
+        quarantineCount: 0,
+        consecutiveFailures: 0,
+        telemetryConsecutiveFailures: 0,
+        instanceId: '',
+        lastCaptureAt: 0,
+        captureSeenSinceLastSync: false,
+        lastSync: null,
+        lastTelemetryAt: 0,
+        lastSuccessfulTelemetryAt: 0,
+        lastTelemetryError: null,
+        lastPollError: null,
+        lastLifecyclePhase: 'idle',
+        lastStopReason: 'none',
+        lastError: null,
+        lastStartupCheckpoint: null,
+        sessionDirCount: 0,
+        eventsRetainedForRetry: 0,
+        lastDeliveryIssue: null,
+        lastDeliveryIssueAt: 0,
+    };
+}
+function setLifecyclePhase(phase, checkpoint) {
+    state.lastLifecyclePhase = phase;
+    if (checkpoint !== undefined)
+        state.lastStartupCheckpoint = checkpoint;
+    markStateDirty();
+}
+function setLastError(message) {
+    state.lastError = message;
+    markStateDirty();
+}
+function setStopReason(reason) {
+    state.lastStopReason = reason;
+    markStateDirty();
+}
+function hasMeaningfulRuntimeState(snapshot) {
+    return Boolean(snapshot.running ||
+        snapshot.startedAt ||
+        snapshot.lastPollAt ||
+        snapshot.lastSuccessfulPollAt ||
+        snapshot.eventsProcessed ||
+        snapshot.quarantineCount ||
+        snapshot.lastTelemetryAt ||
+        snapshot.lastSuccessfulTelemetryAt ||
+        snapshot.lastStartupCheckpoint ||
+        snapshot.instanceId);
+}
 function persistState(extra = {}) {
     flushAllTimeStats();
     if (!_stateDirty)
@@ -264,15 +320,27 @@ function persistState(extra = {}) {
 function readPersistedState() {
     try {
         const d = (0, safe_io_1.readJsonSafe)(STATUS_FILE, null, 'status');
-        if (!d)
-            return null;
+        if (!d) {
+            if (hasMeaningfulRuntimeState(state)) {
+                return { data: state, source: 'runtime', message: null };
+            }
+            return { data: null, source: 'missing', message: 'No persisted Shield runtime state found yet.' };
+        }
         const age = Date.now() - (Number(d.updatedAt) || 0);
-        if (age > 10 * 60 * 1000)
-            return null;
-        return d;
+        if (age > 10 * 60 * 1000) {
+            return {
+                data: d,
+                source: 'stale',
+                message: `Last persisted Shield state is stale (${Math.floor(age / 60_000)}m old).`,
+            };
+        }
+        return { data: d, source: 'persisted', message: null };
     }
     catch {
-        return null;
+        if (hasMeaningfulRuntimeState(state)) {
+            return { data: state, source: 'runtime', message: null };
+        }
+        return { data: null, source: 'missing', message: 'Shield status state could not be read.' };
     }
 }
 const STALE_POLL_WARN_MS = 2 * 60 * 1000;
@@ -304,19 +372,7 @@ function getStatusWarnings(input) {
     }
     return warnings;
 }
-const state = {
-    activated: false,
-    running: false,
-    startedAt: 0,
-    lastPollAt: 0,
-    eventsProcessed: 0,
-    quarantineCount: 0,
-    consecutiveFailures: 0,
-    instanceId: '',
-    lastCaptureAt: 0,
-    captureSeenSinceLastSync: false,
-    lastSync: null,
-};
+const state = createInitialState();
 let firstEventDelivered = false;
 let teardownPreviousRuntime = null;
 let pendingTeardown = null;
@@ -330,6 +386,26 @@ function getBackoffInterval(baseMs) {
     const backoff = baseMs * Math.pow(2, Math.min(state.consecutiveFailures, 10));
     return Math.min(backoff, MAX_BACKOFF_MS);
 }
+function describeSendFailure(kind, statusCode, body) {
+    switch (kind) {
+        case 'missing_credentials':
+            return 'Missing Shield credentials';
+        case 'pending_namespace':
+            return 'Namespace allocation pending';
+        case 'needs_registration':
+            return 'Instance registration invalidated by platform';
+        case 'quota_exceeded':
+            return 'Subscription inactive or quota exhausted';
+        case 'circuit_breaker':
+            return 'Circuit breaker opened after repeated batch failures';
+        case 'network_error':
+            return `Network error while sending events${body ? `: ${body}` : ''}`;
+        case 'http_error':
+            return `HTTP ${statusCode ?? 0} while sending events${body ? `: ${body}` : ''}`;
+        default:
+            return body || `HTTP ${statusCode ?? 0} while sending events`;
+    }
+}
 function printNotActivatedStatus() {
     console.log(`OpenClaw Shield — v${version_1.VERSION}`);
     console.log('');
@@ -344,42 +420,54 @@ function printNotActivatedStatus() {
     console.log('  Get your key at: https://uss.upx.com → APPS → OpenClaw Shield');
 }
 function printActivatedStatus() {
-    const s = readPersistedState() ?? state;
+    const snapshot = readPersistedState();
+    const s = snapshot.data;
+    const fmtTime = (ms) => ms < 60_000 ? `${Math.round(ms / 1000)}s ago`
+        : ms < 3_600_000 ? `${Math.floor(ms / 60_000)}m ago`
+            : `${(ms / 3_600_000).toFixed(1)}h ago`;
+    if (!s) {
+        console.log(`OpenClaw Shield — v${version_1.VERSION}`);
+        console.log('');
+        console.log('── Plugin Health ─────────────────────────────');
+        console.log('  Connection:   ⚠️ Status unavailable');
+        console.log(`  Version:      ${version_1.VERSION}`);
+        console.log(`  Warning:      ${snapshot.message ?? 'Shield has not persisted runtime state yet.'}`);
+        console.log('               - This usually means the gateway has not started the plugin yet, or state persistence is unavailable.');
+        console.log('               - If this persists, run: openclaw gateway restart');
+        return;
+    }
     const isRunning = Boolean(s.running);
     const ageMs = s.updatedAt ? Date.now() - s.updatedAt : null;
-    const ageLabel = ageMs != null
-        ? (ageMs < 60_000 ? `${Math.round(ageMs / 1000)}s ago`
-            : ageMs < 3_600_000 ? `${Math.floor(ageMs / 60_000)}m ago`
-                : `${(ageMs / 3_600_000).toFixed(1)}h ago`)
-        : '';
+    const ageLabel = ageMs != null ? fmtTime(ageMs) : '';
     const lastPollMs = s.lastPollAt ? Date.now() - s.lastPollAt : null;
-    const lastPollLabel = s.lastPollAt
-        ? (lastPollMs < 60_000 ? `${Math.round(lastPollMs / 1000)}s ago`
-            : lastPollMs < 3_600_000 ? `${Math.floor(lastPollMs / 60_000)}m ago`
-                : `${(lastPollMs / 3_600_000).toFixed(1)}h ago`)
-        : 'never';
+    const lastPollLabel = s.lastPollAt ? fmtTime(lastPollMs) : 'never';
     const instanceId = s.instanceId;
     const shortId = instanceId ? `${instanceId.slice(0, 8)}…` : '';
+    const lifecyclePhase = s.lastLifecyclePhase ?? 'unknown';
+    const stopReason = s.lastStopReason ?? 'unknown';
     console.log(`OpenClaw Shield — v${s.version ?? version_1.VERSION}${ageLabel ? `  (${ageLabel})` : ''}`);
     console.log('');
     console.log('── Plugin Health ─────────────────────────────');
-    console.log(`  Connection:   ${isRunning ? '✅ Connected' : '❌ Disconnected'}`);
+    console.log(`  Connection:   ${isRunning ? '✅ Connected' : snapshot.source === 'stale' ? '⚠️ Status stale' : '❌ Disconnected'}`);
     console.log(`  Version:      ${s.version ?? version_1.VERSION}`);
     if (shortId)
         console.log(`  Instance:     ${shortId}`);
     console.log(`  Last poll:    ${lastPollLabel}`);
     const lastCaptureMs = s.lastCaptureAt ? Date.now() - s.lastCaptureAt : null;
-    const lastCaptureLabel = s.lastCaptureAt
-        ? (lastCaptureMs < 60_000 ? `${Math.round(lastCaptureMs / 1000)}s ago`
-            : lastCaptureMs < 3_600_000 ? `${Math.floor(lastCaptureMs / 60_000)}m ago`
-                : `${(lastCaptureMs / 3_600_000).toFixed(1)}h ago`)
-        : null;
+    const lastCaptureLabel = s.lastCaptureAt ? fmtTime(lastCaptureMs) : null;
     if (lastCaptureLabel)
         console.log(`  Last capture: ${lastCaptureLabel}`);
+    const updateState = (0, updater_1.loadUpdateState)();
     const allTime = (s.allTime ?? readAllTimeStats());
     console.log(`  Events sent:  ${allTime.eventsProcessed.toLocaleString()}  (all-time)`);
     console.log(`  Quarantine:   ${allTime.quarantineCount.toLocaleString()}  (all-time)`);
-    console.log(`  Failures:     ${s.consecutiveFailures ?? 0}  (consecutive)`);
+    console.log(`  Failures:     ${s.consecutiveFailures ?? 0}  (poll)`);
+    if (s.telemetryConsecutiveFailures != null) {
+        console.log(`  Telemetry:    ${s.telemetryConsecutiveFailures ?? 0}  (consecutive failures)`);
+    }
+    console.log(`  Phase:        ${lifecyclePhase}`);
+    if (stopReason && stopReason !== 'none')
+        console.log(`  Stop reason:  ${stopReason}`);
     if (s.pid) {
         let pidAlive = false;
         try {
@@ -389,6 +477,28 @@ function printActivatedStatus() {
         catch { }
         console.log(`  Daemon PID:   ${s.pid}${pidAlive ? '' : '  ⚠️ stale (process not running)'}`);
     }
+    if (snapshot.message) {
+        console.log(`  Status note:  ${snapshot.message}`);
+    }
+    if (s.lastStartupCheckpoint) {
+        console.log(`  Checkpoint:   ${s.lastStartupCheckpoint}`);
+    }
+    if (s.lastError) {
+        console.log(`  Last error:   ${s.lastError}`);
+    }
+    if (updateState.pendingRestart || updateState.lastFailureStage || updateState.rollbackPending) {
+        console.log(`  Update:       ${updateState.pendingRestart ? 'pending restart' : updateState.rollbackPending ? 'rollback needed' : 'attention required'}`);
+        if (updateState.lastFailureStage)
+            console.log(`  Update stage: ${updateState.lastFailureStage}`);
+        if (updateState.lastError)
+            console.log(`  Update error: ${updateState.lastError}`);
+    }
+    if (s.lastDeliveryIssue) {
+        console.log(`  Delivery:     ${s.lastDeliveryIssue}`);
+    }
+    if (s.eventsRetainedForRetry && Number(s.eventsRetainedForRetry) > 0) {
+        console.log(`  Retry backlog:${String(s.eventsRetainedForRetry).padStart(3)}  event(s) retained for retry`);
+    }
     const statusWarnings = getStatusWarnings({
         running: isRunning,
         lastPollAt: s.lastPollAt ?? null,
@@ -397,11 +507,21 @@ function printActivatedStatus() {
         captureSeenSinceLastSync: Boolean(s.captureSeenSinceLastSync ?? false),
         consecutiveFailures: s.consecutiveFailures ?? 0,
     });
-    if (statusWarnings.length > 0) {
+    const telemetryWarnings = [];
+    if (s.telemetryConsecutiveFailures && Number(s.telemetryConsecutiveFailures) >= CONSECUTIVE_FAILURES_WARN) {
+        telemetryWarnings.push(`Instance telemetry is failing (${s.telemetryConsecutiveFailures} consecutive attempts), but capture remains active.`);
+    }
+    if (s.lastTelemetryError) {
+        telemetryWarnings.push(`Last telemetry error: ${s.lastTelemetryError}`);
+    }
+    if (statusWarnings.length > 0 || telemetryWarnings.length > 0 || snapshot.source === 'stale') {
         console.log('  Warning:      ⚠️ Capture health degraded');
-        for (const warning of statusWarnings) {
+        for (const warning of [...statusWarnings, ...telemetryWarnings]) {
             console.log(`               - ${warning}`);
         }
+        if (snapshot.source === 'stale') {
+            console.log('               - Persisted status is stale; the gateway may have restarted or status writes may be blocked.');
+        }
         console.log('               - If this persists, run: openclaw gateway restart');
     }
     const startedAt = s.startedAt;
@@ -422,9 +542,6 @@ function printActivatedStatus() {
         const filled = Math.max(1, Math.round((count / max) * BAR_MAX));
         return BAR_CHARS.slice(0, filled);
     };
-    const fmtTime = (ms) => ms < 60_000 ? `${Math.round(ms / 1000)}s ago`
-        : ms < 3_600_000 ? `${Math.floor(ms / 60_000)}m ago`
-            : `${(ms / 3_600_000).toFixed(1)}h ago`;
     const lastSync = s.lastSync;
     console.log('');
     if (lastSync && lastSync.at) {
@@ -437,7 +554,7 @@ function printActivatedStatus() {
     }
     else {
         console.log('📡 Last sync');
-        console.log('  No sync yet. Bridge will send on the next poll cycle.');
+        console.log(`  ${snapshot.source === 'stale' ? 'Last known sync is unavailable because persisted state is stale.' : 'No sync yet. Bridge will send on the next poll cycle.'}`);
     }
     const counters = (s.counters ?? {});
     const sessionEvents = counters.totalEvents ?? 0;
@@ -472,6 +589,16 @@ function printActivatedStatus() {
         console.log('  (original values never stored or transmitted)');
     }
 }
+function _resetForTesting() {
+    Object.assign(state, createInitialState());
+    _allTimeStats = null;
+    _allTimeStatsDirty = false;
+    _stateDirty = true;
+    firstEventDelivered = false;
+    teardownPreviousRuntime = null;
+    pendingTeardown = null;
+    serviceStartFn = null;
+}
 exports.default = {
     id: 'shield',
     name: 'OpenClaw Shield',
@@ -561,6 +688,8 @@ exports.default = {
             const markStopped = opts?.markStopped ?? true;
             if (markStopped) {
                 state.running = false;
+                state.lastLifecyclePhase = opts?.finalPhase ?? 'stopped';
+                state.lastStopReason = opts?.stopReason ?? 'unknown';
                 markStateDirty();
                 persistState();
             }
@@ -569,7 +698,7 @@ exports.default = {
             }
             if (opts?.flushRedactor) {
                 try {
-                    const { flush: flushRedactor } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
+                    const { flush: flushRedactor } = require('./src/redactor');
                     flushRedactor();
                 }
                 catch { }
@@ -580,6 +709,17 @@ 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 });
+        const deactivateForRegistrationInvalidation = async (checkpoint, message) => {
+            setLifecyclePhase('deactivated', checkpoint);
+            setStopReason('registration_invalidated');
+            setLastError(message);
+            await cleanupRuntime({
+                markStopped: true,
+                stopReason: 'registration_invalidated',
+                finalPhase: 'deactivated',
+                flushRedactor: true,
+            });
+        };
         const serviceDefinition = {
             id: 'shield-monitor',
             async start() {
@@ -594,6 +734,11 @@ exports.default = {
                 try {
                     await cleanupRuntime({ markStopped: false, resetGuard: false, flushRedactor: false });
                     const activeGeneration = ++runtimeGeneration;
+                    Object.assign(state, createInitialState());
+                    setLastError(null);
+                    setStopReason('none');
+                    setLifecyclePhase('starting', 'checkpoint:1');
+                    persistState();
                     log.info('shield', `[checkpoint:1] Service start() entered — generation=${activeGeneration}`);
                     let credentials = (0, config_1.loadCredentials)();
                     let validCreds = hasValidCredentials(credentials);
@@ -603,6 +748,10 @@ exports.default = {
                         const autoCreds = await performAutoRegistration(installationKey);
                         if (!autoCreds) {
                             log.error('shield', 'Activation failed. Verify your Installation Key and try again.');
+                            setLifecyclePhase('startup_failed', 'checkpoint:activation_failed');
+                            setStopReason('activation_failed');
+                            setLastError('Activation failed. Verify your Installation Key and try again.');
+                            persistState();
                             startGuard.endFailure();
                             return;
                         }
@@ -617,11 +766,17 @@ exports.default = {
                         log.warn('shield', '  Activate via CLI:  openclaw shield activate <YOUR_KEY>');
                         log.warn('shield', '  Or set plugins.entries.shield.config.installationKey in openclaw.json and restart.');
                         log.warn('shield', '  Get your key at: https://uss.upx.com → APPS → OpenClaw Shield');
+                        setLifecyclePhase('stopped', 'checkpoint:not_activated');
+                        setStopReason('not_activated');
+                        setLastError('Shield is not activated.');
+                        persistState();
                         startGuard.endFailure();
                         return;
                     }
                     state.activated = true;
                     state.startedAt = Date.now();
+                    setLastError(null);
+                    setLifecyclePhase('starting', 'checkpoint:3');
                     const config = (0, config_1.loadConfig)({
                         credentials,
                         dryRun: dryRunVal,
@@ -630,25 +785,33 @@ exports.default = {
                         collectHostMetrics: hostMetricsVal,
                     });
                     state.instanceId = config.credentials.instanceId ?? '';
+                    state.sessionDirCount = config.sessionDirs.length;
+                    if (config.sessionDirs.length === 0) {
+                        state.lastDeliveryIssue = 'No OpenClaw session directories discovered yet — Shield is loaded but has no event sources.';
+                        state.lastDeliveryIssueAt = Date.now();
+                    }
                     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})`);
+                    persistState();
                     (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');
+                    state.lastStartupCheckpoint = 'checkpoint:5';
+                    persistState();
                     if (config.localEventBuffer) {
                         (0, event_store_1.initEventStore)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'), { maxEvents: config.localEventLimit });
                     }
                     const runtime = api.runtime;
-                    if (runtime?.system?.enqueueSystemEvent && runtime?.system?.requestHeartbeatNow) {
-                        const config = api.config;
+                    const openclawConfig = api.config;
+                    if (typeof runtime?.system?.enqueueSystemEvent === 'function' && typeof runtime?.system?.requestHeartbeatNow === 'function') {
                         (0, case_monitor_1.setCaseNotificationDispatcher)({
                             enqueueSystemEvent: runtime.system.enqueueSystemEvent,
                             requestHeartbeatNow: runtime.system.requestHeartbeatNow,
-                            agentId: config?.agents?.default ?? 'main',
+                            agentId: openclawConfig?.agents?.default ?? 'main',
                         });
                     }
                     else {
@@ -656,7 +819,6 @@ exports.default = {
                     }
                     try {
                         const channels = runtime?.channel;
-                        const cfg = api.config;
                         const channelCandidates = [
                             { name: 'telegram', sendFn: channels?.telegram?.sendMessageTelegram, configPath: 'telegram' },
                             { name: 'discord', sendFn: channels?.discord?.sendMessageDiscord, configPath: 'discord' },
@@ -667,7 +829,7 @@ exports.default = {
                         for (const candidate of channelCandidates) {
                             if (typeof candidate.sendFn !== 'function')
                                 continue;
-                            const channelCfg = cfg?.channels?.[candidate.configPath];
+                            const channelCfg = openclawConfig?.channels?.[candidate.configPath];
                             if (!channelCfg?.enabled && channelCfg?.enabled !== undefined)
                                 continue;
                             let targetId = null;
@@ -694,6 +856,9 @@ exports.default = {
                                 break;
                             }
                         }
+                        if (!channels) {
+                            log.debug('case-monitor', 'Direct send runtime channels unavailable — direct message notifications disabled');
+                        }
                     }
                     catch (err) {
                         log.debug('case-monitor', `Direct send setup failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
@@ -702,7 +867,7 @@ exports.default = {
                         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')));
+                        const { reportLifecycleEvent } = require('./src/sender');
                         void reportLifecycleEvent('plugin_started', {
                             version: version_1.VERSION,
                             reason: startReason,
@@ -712,14 +877,21 @@ exports.default = {
                     catch { }
                     const autoUpdateMode = pluginConfig.autoUpdate ?? true;
                     const _bootState = (0, updater_1.loadUpdateState)();
+                    state.lastStartupCheckpoint = 'checkpoint:6';
+                    persistState();
                     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);
+                    state.lastStartupCheckpoint = 'checkpoint:7';
+                    persistState();
                     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)();
                         if (restarted) {
+                            setLifecyclePhase('stopped', 'checkpoint:update_restart');
+                            setStopReason('update_restart');
+                            persistState();
                             startGuard.endFailure();
                             return;
                         }
@@ -736,21 +908,22 @@ exports.default = {
                     }
                     try {
                         const inv = (0, inventory_1.collectInventory)();
-                        const { setCachedInventory } = await Promise.resolve().then(() => __importStar(require('./src/inventory')));
+                        const { setCachedInventory } = require('./src/inventory');
                         setCachedInventory(inv);
                     }
                     catch (err) {
                         log.warn('shield', `Inventory collection failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
                     }
-                    const { fetchNewEntries, commitCursors } = await Promise.resolve().then(() => __importStar(require('./src/fetcher')));
-                    const { transformEntries, generateHostTelemetry, resolveOpenClawVersion, resolveAgentLabel } = await Promise.resolve().then(() => __importStar(require('./src/transformer')));
-                    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')));
+                    const { fetchNewEntries, commitCursors } = require('./src/fetcher');
+                    const { transformEntries, generateHostTelemetry, resolveOpenClawVersion, resolveAgentLabel } = require('./src/transformer');
+                    const { sendEvents, reportInstance } = require('./src/sender');
+                    const { init: initRedactor, flush: flushRedactor, redactEvent } = require('./src/redactor');
+                    const { validate } = require('./src/validator');
                     log.info('shield', '[checkpoint:8] Dynamic imports loaded');
                     if (config.redactionEnabled)
                         initRedactor();
                     state.running = true;
+                    setLifecyclePhase('running', 'checkpoint:9');
                     persistState();
                     log.info('shield', '[checkpoint:9] state.running=true — entering poll loop');
                     const runTelemetry = async () => {
@@ -779,19 +952,31 @@ exports.default = {
                         const result = await reportInstance(instancePayload, config.credentials);
                         if (activeGeneration !== runtimeGeneration)
                             return;
+                        state.lastTelemetryAt = Date.now();
                         log.info('shield', `Instance report → Platform: success=${result.ok}`);
                         if (result.ok) {
-                            state.consecutiveFailures = 0;
+                            state.telemetryConsecutiveFailures = 0;
+                            state.lastSuccessfulTelemetryAt = Date.now();
+                            state.lastTelemetryError = null;
+                            if (state.lastLifecyclePhase === 'degraded' && state.running) {
+                                state.lastLifecyclePhase = 'running';
+                            }
                         }
                         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();
+                            state.telemetryConsecutiveFailures++;
+                            state.lastTelemetryError = result.error ? String(result.error).slice(0, 200) : `HTTP ${result.statusCode ?? 0}`;
+                            if (result.needsRegistration) {
+                                log.error('shield', 'Instance report says this Shield instance is no longer registered — deactivating monitoring.');
+                                await deactivateForRegistrationInvalidation('checkpoint:telemetry_registration_invalid', 'Instance registration invalidated by platform.');
+                                return;
+                            }
+                            if (state.telemetryConsecutiveFailures >= MAX_REGISTRATION_FAILURES) {
+                                log.error('shield', `Instance telemetry failed ${state.telemetryConsecutiveFailures} consecutive times — capture remains active but health is degraded.`);
+                                setLifecyclePhase('degraded');
                             }
                         }
+                        markStateDirty();
+                        persistState();
                     };
                     const runTelemetrySingleflight = createSingleflightRunner(runTelemetry);
                     log.info('shield', '[checkpoint:9a] Firing initial telemetry');
@@ -828,7 +1013,10 @@ exports.default = {
                             if (entries.length === 0) {
                                 commitCursors(config, []);
                                 state.consecutiveFailures = 0;
+                                state.lastPollError = null;
                                 state.lastPollAt = Date.now();
+                                state.lastSuccessfulPollAt = state.lastPollAt;
+                                state.eventsRetainedForRetry = 0;
                                 markStateDirty();
                                 persistState();
                                 const idlePlatformConfig = { apiUrl: config.credentials.apiUrl, instanceId: config.credentials.instanceId, hmacSecret: config.credentials.hmacSecret };
@@ -858,8 +1046,7 @@ exports.default = {
                             const needsReg = results.some(r => r.needsRegistration);
                             if (needsReg) {
                                 log.error('shield', 'Instance not registered on platform — Shield deactivated.');
-                                state.running = false;
-                                markStateDirty();
+                                await deactivateForRegistrationInvalidation('checkpoint:poll_registration_invalid', 'Instance registration invalidated by platform.');
                                 return;
                             }
                             const pending = results.find(r => r.pendingNamespace);
@@ -867,6 +1054,10 @@ exports.default = {
                                 const waitMs = Math.min(pending.retryAfterMs ?? 300_000, MAX_BACKOFF_MS);
                                 log.warn('shield', `Namespace allocation in progress — holding events, backing off ${Math.round(waitMs / 1000)}s`);
                                 state.lastPollAt = Date.now();
+                                state.lastPollError = null;
+                                state.lastDeliveryIssue = describeSendFailure(pending.failureKind, pending.statusCode, pending.body);
+                                state.lastDeliveryIssueAt = Date.now();
+                                state.eventsRetainedForRetry = pending.eventCount;
                                 markStateDirty();
                                 persistState();
                                 await new Promise(r => setTimeout(r, waitMs));
@@ -875,7 +1066,9 @@ exports.default = {
                                 return;
                             }
                             const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
-                            if (accepted > 0) {
+                            const allBatchesSucceeded = results.length > 0 && results.every(r => r.success);
+                            const firstFailure = results.find(r => !r.success);
+                            if (allBatchesSucceeded && accepted > 0) {
                                 (0, case_monitor_1.notifyCaseMonitorActivity)();
                                 if (!firstEventDelivered) {
                                     firstEventDelivered = true;
@@ -885,6 +1078,14 @@ exports.default = {
                                 flushRedactor();
                                 state.eventsProcessed += accepted;
                                 state.consecutiveFailures = 0;
+                                state.lastPollError = null;
+                                state.lastDeliveryIssue = null;
+                                state.lastDeliveryIssueAt = 0;
+                                state.eventsRetainedForRetry = 0;
+                                state.lastSuccessfulPollAt = Date.now();
+                                if (state.lastLifecyclePhase === 'degraded') {
+                                    state.lastLifecyclePhase = 'running';
+                                }
                                 markStateDirty();
                                 const syncEventTypes = {};
                                 for (const env of envelopes) {
@@ -908,8 +1109,30 @@ exports.default = {
                                     (0, event_store_1.appendEvents)(summaries);
                                 }
                             }
+                            else if (accepted > 0) {
+                                state.consecutiveFailures++;
+                                state.lastPollError = 'Partial delivery detected — retaining cursor position to retry all events safely.';
+                                state.lastDeliveryIssue = firstFailure
+                                    ? `${describeSendFailure(firstFailure.failureKind, firstFailure.statusCode, firstFailure.body)}. Retrying entire poll window without advancing cursors.`
+                                    : 'Partial delivery detected — retrying without advancing cursors.';
+                                state.lastDeliveryIssueAt = Date.now();
+                                state.eventsRetainedForRetry = envelopes.length;
+                                setLifecyclePhase('degraded');
+                                log.warn('shield', 'Partial delivery detected — not advancing cursors so events can be retried safely. Some already-accepted events may be resent.');
+                                markStateDirty();
+                            }
                             else {
                                 state.consecutiveFailures++;
+                                state.lastPollError = firstFailure
+                                    ? describeSendFailure(firstFailure.failureKind, firstFailure.statusCode, firstFailure.body)
+                                    : 'Event delivery failed';
+                                state.lastDeliveryIssue = state.lastPollError;
+                                state.lastDeliveryIssueAt = Date.now();
+                                state.eventsRetainedForRetry = envelopes.length;
+                                state.lastLifecyclePhase = 'degraded';
+                                if (firstFailure?.failureKind === 'quota_exceeded') {
+                                    setLifecyclePhase('degraded');
+                                }
                                 markStateDirty();
                             }
                             state.lastPollAt = Date.now();
@@ -924,8 +1147,13 @@ exports.default = {
                             if (activeGeneration !== runtimeGeneration)
                                 return;
                             state.consecutiveFailures++;
+                            state.lastPollError = err instanceof Error ? err.message : String(err);
+                            state.lastDeliveryIssue = state.lastPollError;
+                            state.lastDeliveryIssueAt = Date.now();
+                            state.lastLifecyclePhase = 'degraded';
                             markStateDirty();
                             log.error('shield', `Poll error: ${err instanceof Error ? err.message : String(err)}`);
+                            persistState();
                         }
                     };
                     const runPollSingleflight = createSingleflightRunner(poll);
@@ -957,7 +1185,8 @@ exports.default = {
                         if (!state.running)
                             return;
                         log.info('shield', '[checkpoint:SIGTERM] SIGTERM received — shutting down');
-                        await cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: true });
+                        setLifecyclePhase('stopping', 'checkpoint:SIGTERM');
+                        await cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: true, stopReason: 'signal' });
                         log.info('shield', 'Service stopped (signal)');
                     };
                     process.once('SIGTERM', onSignalHandler);
@@ -966,13 +1195,18 @@ exports.default = {
                     startGuard.endSuccess();
                 }
                 catch (err) {
+                    setLifecyclePhase('startup_failed');
+                    setStopReason('startup_failed');
+                    setLastError(err instanceof Error ? err.message : String(err));
+                    persistState();
                     startGuard.endFailure();
                     throw err;
                 }
             },
             async stop() {
                 const wasRunning = state.running;
-                await cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: true });
+                setLifecyclePhase('stopping');
+                await cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: true, stopReason: 'service_stop' });
                 if (wasRunning)
                     log.info('shield', 'Service stopped');
             },
@@ -984,6 +1218,7 @@ exports.default = {
             const activated = state.activated || hasValidCredentials(creds);
             const caseStatus = (0, case_monitor_1.getCaseMonitorStatus)();
             const monitorHealth = (0, case_monitor_1.getMonitorHealth)();
+            const updateState = (0, updater_1.loadUpdateState)();
             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`;
@@ -1005,18 +1240,47 @@ exports.default = {
                 }
             }
             const hasSecret = !!creds?.hmacSecret && !PLACEHOLDER_VALUES.has((creds.hmacSecret || '').trim().toLowerCase());
-            const stateField = hasSecret ? (activated ? 'connected' : 'pending') : 'unconfigured';
+            const stateField = !hasSecret
+                ? 'unconfigured'
+                : !activated
+                    ? 'pending'
+                    : state.running
+                        ? (state.lastLifecyclePhase === 'degraded' ? 'degraded' : 'connected')
+                        : state.lastLifecyclePhase;
             respond(true, {
                 activated,
                 state: stateField,
                 running: state.running,
                 lastPollAt: state.lastPollAt,
+                lastSuccessfulPollAt: state.lastSuccessfulPollAt,
                 lastCaptureAt: state.lastCaptureAt,
                 captureSeenSinceLastSync: state.captureSeenSinceLastSync,
                 eventsProcessed: state.eventsProcessed,
                 quarantineCount: state.quarantineCount,
                 consecutiveFailures: state.consecutiveFailures,
+                telemetryConsecutiveFailures: state.telemetryConsecutiveFailures,
+                lastTelemetryAt: state.lastTelemetryAt,
+                lastSuccessfulTelemetryAt: state.lastSuccessfulTelemetryAt,
+                lastTelemetryError: state.lastTelemetryError,
+                lastPollError: state.lastPollError,
+                lastLifecyclePhase: state.lastLifecyclePhase,
+                lastStopReason: state.lastStopReason,
+                lastError: state.lastError,
+                lastStartupCheckpoint: state.lastStartupCheckpoint,
+                sessionDirCount: state.sessionDirCount,
+                eventsRetainedForRetry: state.eventsRetainedForRetry,
+                lastDeliveryIssue: state.lastDeliveryIssue,
+                lastDeliveryIssueAt: state.lastDeliveryIssueAt,
                 version: version_1.VERSION,
+                update: {
+                    pendingRestart: updateState.pendingRestart,
+                    restartAttempts: updateState.restartAttempts,
+                    latestVersion: updateState.latestVersion,
+                    updateAvailable: updateState.updateAvailable,
+                    lastError: updateState.lastError,
+                    lastFailureStage: updateState.lastFailureStage,
+                    rollbackPending: updateState.rollbackPending,
+                },
                 caseMonitor: {
                     intervalMs: caseStatus.intervalMs,
                     nextCheckInMs: caseStatus.nextCheckIn,
@@ -1071,34 +1335,39 @@ exports.default = {
             hmacSecret: rpcCreds?.hmacSecret || '',
         };
         (0, rpc_1.registerAllRpcs)(api, platformApiConfig);
-        api.registerCommand({
-            name: 'shieldcases',
-            description: 'Show pending Shield security cases',
-            requireAuth: true,
-            handler: () => {
-                const { getPendingCases } = require('./src/case-monitor');
-                const cases = getPendingCases();
-                if (cases.length === 0) {
-                    return { text: '✅ No pending Shield security cases.' };
-                }
-                const severityEmoji = { CRITICAL: '🔴', HIGH: '🟠', MEDIUM: '🟡', LOW: '🔵' };
-                const lines = cases.map((c) => {
-                    const emoji = severityEmoji[c.severity] || '⚠️';
-                    const age = Math.floor((Date.now() - new Date(c.created_at).getTime()) / 60000);
-                    const ageStr = age < 60 ? `${age}m` : `${Math.floor(age / 60)}h`;
-                    return `${emoji} **${c.rule_title}** (${c.severity || 'unknown'}) — ${c.event_count} events — ${ageStr} ago`;
-                });
-                return {
-                    text: [
-                        `🛡️ **Shield — ${cases.length} Pending Case${cases.length > 1 ? 's' : ''}**`,
-                        '',
-                        ...lines,
-                        '',
-                        'Use `openclaw shield cases show <id>` for details.',
-                    ].join('\n'),
-                };
-            },
-        });
+        if (typeof api.registerCommand === 'function') {
+            api.registerCommand({
+                name: 'shieldcases',
+                description: 'Show pending Shield security cases',
+                requireAuth: true,
+                handler: () => {
+                    const { getPendingCases } = require('./src/case-monitor');
+                    const cases = getPendingCases();
+                    if (cases.length === 0) {
+                        return { text: '✅ No pending Shield security cases.' };
+                    }
+                    const severityEmoji = { CRITICAL: '🔴', HIGH: '🟠', MEDIUM: '🟡', LOW: '🔵' };
+                    const lines = cases.map((c) => {
+                        const emoji = severityEmoji[c.severity] || '⚠️';
+                        const age = Math.floor((Date.now() - new Date(c.created_at).getTime()) / 60000);
+                        const ageStr = age < 60 ? `${age}m` : `${Math.floor(age / 60)}h`;
+                        return `${emoji} **${c.rule_title}** (${c.severity || 'unknown'}) — ${c.event_count} events — ${ageStr} ago`;
+                    });
+                    return {
+                        text: [
+                            `🛡️ **Shield — ${cases.length} Pending Case${cases.length > 1 ? 's' : ''}**`,
+                            '',
+                            ...lines,
+                            '',
+                            'Use `openclaw shield cases show <id>` for details.',
+                        ].join('\n'),
+                    };
+                },
+            });
+        }
+        else {
+            log.debug('shield', 'registerCommand not available — auto-reply command /shieldcases disabled on this OpenClaw runtime');
+        }
         api.registerCli(({ program }) => {
             const shield = program.command('shield');
             (0, cli_cases_1.registerCasesCli)(shield);
@@ -1237,10 +1506,9 @@ exports.default = {
                     step('Stale updateAvailable cleared');
                 }
                 step('Resetting session state...');
-                state.running = false;
-                state.consecutiveFailures = 0;
-                state.lastPollAt = 0;
-                state.captureSeenSinceLastSync = false;
+                Object.assign(state, createInitialState());
+                state.lastLifecyclePhase = 'stopping';
+                state.lastStopReason = 'manual_restart';
                 markStateDirty();
                 persistState();
                 step('State reset');
@@ -1332,7 +1600,7 @@ exports.default = {
                     console.log(`  agent:${agentHash}  workspace:${wsHash}  identity=${identityLabel}  bootstrapped=${bootstrapLabel}`);
                 }
                 try {
-                    const { initVault, getAllMappings } = await Promise.resolve().then(() => __importStar(require('./src/redactor/vault')));
+                    const { initVault, getAllMappings } = require('./src/redactor/vault');
                     initVault();
                     const mappings = getAllMappings();
                     const tokens = Object.keys(mappings);