@upx-us/shield 0.3.5 → 0.3.16

package/README.md

@@ -20,29 +20,32 @@ Your Agent → Shield (local: capture + redact) → UPX Platform (analysis, aler
 
 ---
 
-## Quick Start — Suggested bot prompt
+## Installation
 
-Copy this prompt and paste it to your AI agent. Replace `<YOUR_KEY>` with your Installation Key:
+**If you have an OpenClaw agent running**, use Quick Start — paste a single prompt and you're done.
+**If you prefer to configure manually**, follow Manual Installation below.
 
-> Run `openclaw plugins install @upx-us/shield` to install the Shield plugin. Then update `~/.openclaw/openclaw.json`: add `"shield"` to `plugins.allow`, and under `plugins.entries.shield.config` set `"installationKey": "<YOUR_KEY>"`. Then run `openclaw gateway restart`. Confirm Shield is active with `openclaw shield status`.
+### Quick Start — Let your agent do it
 
-That's it. The bot installs the plugin, configures the key, restarts the gateway, and Shield activates automatically.
+Copy this prompt and paste it to your AI agent. Replace `<YOUR_KEY>` with your Installation Key:
 
----
+> Install the OpenClaw Shield plugin (@upx-us/shield) with installation key `<YOUR_KEY>`. Add "shield" to plugins.allow and set installationKey in plugins.entries.shield.config. Restart the gateway and confirm Shield is active with openclaw shield status.
 
-## Manual Installation
+The agent installs the plugin, edits the config, restarts the gateway, and Shield activates automatically.
 
-### Step 1 — Install the plugin
+### Manual Installation
+
+#### Step 1 — Install the plugin
 
 ```bash
 openclaw plugins install @upx-us/shield
 ```
 
-> OpenClaw will show a security warning about environment variable access and network calls — this is **expected** for a security monitoring plugin. Add `"shield"` to `plugins.allow` in `openclaw.json` to suppress it.
+> **Security prompt:** OpenClaw will warn about environment variable access combined with network calls. This is **expected** — Shield reads signing credentials and sends telemetry to the Shield API. To acknowledge, add `"shield"` to `plugins.allow` in `~/.openclaw/openclaw.json` (shown in Step 2). If automating via a script or agent, pre-populate `plugins.allow` before running the install command to avoid interactive prompts.
 
-### Step 2 — Add your Installation Key
+#### Step 2 — Add your Installation Key
 
-Open `~/.openclaw/openclaw.json` and add the following:
+Open `~/.openclaw/openclaw.json` and add:
 
 ```json
 {
@@ -59,9 +62,9 @@ Open `~/.openclaw/openclaw.json` and add the following:
 }
 ```
 
-> **Note:** Each Installation Key is single-use. The plugin exchanges it for credentials on first startup and saves them locally — you can remove `installationKey` from the config after activation.
+> **Installation Keys are single-use** — the plugin exchanges your key for permanent credentials on first startup and saves them locally. The key is consumed on the first *successful* activation; if the first attempt fails (network issue, config typo), the key is not burned and you can retry. Once activation succeeds, you can safely remove `installationKey` from the config.
 
-### Step 3 — Restart the Gateway
+#### Step 3 — Restart the Gateway
 
 ```bash
 openclaw gateway restart
@@ -69,9 +72,7 @@ openclaw gateway restart
 
 Shield auto-registers, saves credentials to `~/.openclaw/shield/config.env`, and starts monitoring.
 
----
-
-## Alternative: CLI Activation
+### Alternative: CLI Activation
 
 If the config-based flow didn't work (e.g. the key was added to the wrong path), you can activate directly:
 
@@ -82,22 +83,45 @@ openclaw gateway restart
 
 ---
 
-## Verify it's running
+## What to expect after activation
+
+After restart, Shield exchanges your key for permanent credentials — this takes a few seconds. You should see your first events within the first poll cycle (~30 seconds). Within 1–2 minutes, those events will appear on the platform at [uss.upx.com](https://uss.upx.com).
+
+Run `openclaw shield status` to confirm:
+
+**Just activated (first minute):**
 
-```bash
-openclaw shield status
 ```
+OpenClaw Shield — v0.3.x  (5s ago)
 
-**When activated:**
+── Plugin Health ─────────────────────────────
+  Connection:   ✅ Connected
+  Version:      0.3.x
+  Instance:     a1b2c3d4…
+  Last poll:    5s ago
+  Last capture: 5s ago
+  Events sent:  3  (all-time)
+  Quarantine:   0  (all-time)
+  Failures:     0  (consecutive)
+  Daemon PID:   12345
+  Session:      0m
+```
+
+A low event count and a recent `Last capture` time means Shield is working correctly. Events accumulate as your agent uses tools.
+
+> **Note:** The Activity and Redactions sections appear after your first sync cycle (~30s). If your status looks shorter than the "extended use" example below, that's normal — they'll populate automatically.
+
+**After extended use:**
 
 ```
-OpenClaw Shield — v0.3.0  (5s ago)
+OpenClaw Shield — v0.3.x  (5s ago)
 
 ── Plugin Health ─────────────────────────────
   Connection:   ✅ Connected
-  Version:      0.3.0
+  Version:      0.3.x
   Instance:     a1b2c3d4…
   Last poll:    5s ago
+  Last capture: 14s ago
   Events sent:  1,842  (all-time)
   Quarantine:   0  (all-time)
   Failures:     0  (consecutive)
@@ -107,8 +131,8 @@ OpenClaw Shield — v0.3.0  (5s ago)
 ── Activity ──────────────────────────────────
 
 📡 Last sync  (29s ago — 5 events)
-  TOOL_RESULT          ████████  3
-  TOOL_CALL            █████     2
+  exec                 ████████  3
+  file                 █████     2
 
 📊 This session  (since restart 4h 12m ago — 142 events)
   TOOL_CALL            ████████  78
@@ -123,7 +147,7 @@ OpenClaw Shield — v0.3.0  (5s ago)
 **When not activated:**
 
 ```
-OpenClaw Shield — v0.3.0
+OpenClaw Shield — v0.3.x
 
   Status: Loaded (not activated)
 
@@ -142,11 +166,18 @@ OpenClaw Shield — v0.3.0
 
 ### Event types
 
-Shield captures what your agent *does* — not what it says. Each line in the Activity section represents a category of tool calls:
+Shield captures what your agent *does* — tool invocations and their results — not what it says.
+
+The Activity section shows two levels:
+
+- **Session-level** (`TOOL_CALL`, `TOOL_RESULT`) — every tool invocation and result, shown in the "This session" summary
+- **Sync-level** (`exec`, `file`, `web`, etc.) — the specific event type after parsing, shown in "Last sync"
+
+`exec: 2` in Last sync means 2 of those synced events were shell commands. Those same 2 are also counted within the `TOOL_CALL` total in the session view. They are not separate.
 
 | Event type | What it means |
 |---|---|
-| `TOOL_CALL` | A tool was invoked by the agent (exec, read, write, web search, etc.) |
+| `TOOL_CALL` | A tool was invoked by the agent |
 | `TOOL_RESULT` | The result returned from a tool call |
 | `exec` | Shell command executed |
 | `file` | File read, written, or edited |
@@ -156,23 +187,27 @@ Shield captures what your agent *does* — not what it says. Each line in the Ac
 | `browser` | Browser automation action |
 | `cron` | A scheduled task fired |
 
-Shield captures what your agent *does* — tool invocations and their results. Each event carries metadata about the operation (tool name, paths, URLs) along with a redacted summary of the result.
-
 ### Quarantine
 
-Quarantine counts events that failed local schema validation and were **held back** rather than forwarded to the platform. They are not lost — they're written to `~/.openclaw/shield/data/quarantine.jsonl` for inspection. A non-zero quarantine count usually means a plugin version mismatch between the collector and the platform schema; upgrading Shield typically resolves it.
+Quarantine counts events that failed local schema validation and were **held back** rather than forwarded to the platform. They are not lost — written to `~/.openclaw/shield/data/quarantine.jsonl` for inspection. A non-zero quarantine count usually means a plugin version mismatch; upgrading Shield typically resolves it.
 
 ### Redactions
 
-Redaction runs locally before anything leaves your machine. The counts shown are **occurrences** — how many times that category of sensitive data was detected and replaced with a reversible token (e.g. `host:a3f9b1c2`, `user:7b2c4a1f`). The original values are stored in an encrypted local vault (`~/.openclaw/shield/data/redaction-vault.json`) so they can be recovered for investigation — they are never transmitted to the platform.
+Redaction runs locally before anything leaves your machine. The counts shown are **occurrences** — how many times sensitive data was detected and replaced with a reversible token (e.g. `host:a3f9b1c2`, `user:7b2c4a1f`). Original values are stored in an encrypted local vault and never transmitted.
 
 ### All-time vs. session
 
-- **Events sent / Quarantine** in the health section = all-time totals, persisted across gateway restarts
-- **This session** in the activity section = since the last gateway restart
+- **Events sent / Quarantine** = all-time totals, persisted across gateway restarts
+- **This session** = since the last gateway restart
 - **Last sync** = the most recent poll cycle only
 
-To see the full picture — detections, alerts, rules, and cases — visit [uss.upx.com](https://uss.upx.com).
+### Warnings
+
+When status shows `⚠️ Capture health degraded`, the plugin is connected but capture activity is not syncing successfully. This is not triggered by idle sessions.
+
+Use `Last capture` as the first diagnostic:
+- Recent `Last capture` + warning present → investigate sync pipeline health
+- Old `Last capture` + no warning → normal idle behavior
 
 ---
 
@@ -195,11 +230,47 @@ Shield captures agent activity locally, applies on-device redaction, and forward
 
 ---
 
+## What is sent to the platform
+
+Shield uses two separate channels with different privacy properties:
+
+### Telemetry (operational identity)
+
+Sent every ~5 minutes over HTTPS. This tells the platform *where* the instance is running, not *what* it does. It does **not** pass through the redaction pipeline.
+
+```json
+{
+  "machine": {
+    "hostname": "openclaw-agent",
+    "os": "linux",
+    "arch": "x64",
+    "node_version": "v22.x.x",
+    "public_ip": "1.2.3.4"
+  },
+  "software": {
+    "plugin_version": "0.3.x",
+    "openclaw_version": "2026.x.x",
+    "agent_label": "main",
+    "instance_name": "openclaw-agent"
+  }
+}
+```
+
+Telemetry fields like `hostname`, `public_ip`, and `instance_name` are operational identity signals used for geo-correlation in detection rules and instance health monitoring. They travel over HTTPS and are never exposed publicly.
+
+### Events (behavioural data)
+
+Sent every poll cycle over HTTPS. This is the data stream subject to the full redaction pipeline. Per-event fields include: tool name, redacted command/path/output, timestamp, session ID, and action type. Sensitive values are replaced with `category:hash` tokens before transmission.
+
+> **The distinction:** telemetry = *who/where the instance is* (slim, operational). Events = *what the agent did* (redacted, privacy-protected).
+
+---
+
 ## How your data is protected
 
-**Redaction** runs locally before any data leaves your machine. The redactor detects hostnames, usernames, file paths, API keys, and secrets — replacing them with deterministic `category:hash` tokens. The token→original mapping is stored in an AES-256-GCM encrypted vault (`~/.openclaw/shield/data/redaction-vault.json`, mode 0600). Original values are never transmitted.
+**Redaction** runs locally before any data leaves your machine. The redactor detects hostnames, usernames, file paths, API keys, and secrets — replacing them with deterministic `category:hash` tokens. The token→original mapping is stored in an AES-256-GCM encrypted vault (`~/.openclaw/shield/data/redaction-vault.json`, mode 0600).
 
-**Authentication** uses HMAC-SHA256 with a per-instance signing key. Every request is signed — requests with invalid signatures are rejected by the platform.
+**Authentication** uses HMAC-SHA256 with a per-instance key. Every request is signed — requests with invalid signatures are rejected.
 
 **Credentials** are stored locally at `~/.openclaw/shield/config.env` (mode 0600) and are never transmitted.
 
@@ -207,10 +278,14 @@ Shield captures agent activity locally, applies on-device redaction, and forward
 
 ## Upgrading
 
-- Standard upgrade command: `openclaw plugins update shield`
-- Cursors and credentials are preserved across upgrades
-- After upgrade verify with: `openclaw shield status`
-- See CHANGELOG.md for version history
+```bash
+openclaw plugins update shield
+openclaw shield status
+```
+
+Cursors and credentials are preserved across upgrades. See the CHANGELOG (available on the Shield portal at uss.upx.com) for version history.
+
+> **"Integrity drift detected"** during upgrade is expected — OpenClaw warns when plugin files change, which always happens on a legitimate upgrade. This only indicates a real problem if you see it without having explicitly upgraded.
 
 ---
 
@@ -218,43 +293,79 @@ Shield captures agent activity locally, applies on-device redaction, and forward
 
 **Shield shows "not activated"**
 → Get your Installation Key at [uss.upx.com](https://uss.upx.com) → APPS → OpenClaw Shield → Install
-→ Add to `openclaw.json`:
-```json
-"plugins": { "entries": { "shield": { "config": { "installationKey": "YOUR_KEY" } } } }
-```
-→ Restart OpenClaw
+→ Add to `openclaw.json` and restart the gateway (see Manual Installation above)
 
-**Activated but no events reaching platform**
-→ Run `openclaw shield status` — check Failures count and Last sync time
-→ Verify network access to the Shield API endpoint (check your config for the URL)
-→ Enable debug logging: set `LOG_LEVEL=debug` in your environment
+**Activated but no events after 5 minutes**
+→ Run `openclaw shield status` — check `Failures` count and `Last sync` time
+→ Check `Last capture`: if it's recent, Shield is capturing but may have a sync issue — restart the gateway
+→ If `Last capture` is old, your agent may not have used any tools yet — try running a command and check again
+→ Enable debug logging: `LOG_LEVEL=debug openclaw start`
 
 **High CPU or memory usage**
-→ Increase poll interval in config: `"pollIntervalMs": 60000` (default is 30000ms)
-→ Shield processes at most 5000 events per poll cycle regardless of backlog size
+→ Increase poll interval: `"pollIntervalMs": 60000` in plugin config (default: 30000ms)
 
 **Cursor file issues**
-→ Cursor file location: `~/.openclaw/shield/data/cursors.json`
-→ To reset: delete the file — Shield will reinitialize on next poll (some events may re-process)
-
-**Enable debug logging**
-→ `LOG_LEVEL=debug openclaw start` — verbose output including poll cycles and send results
+→ To reset: `rm ~/.openclaw/shield/data/cursors.json` — Shield reinitializes on next poll
 
 **Dry-run mode (no events sent)**
 → Add `"dryRun": true` to plugin config — events are processed and logged but never transmitted
 
 ---
 
+## FAQ
+
+**How long until I see my first event on the platform?**
+Within 1–2 minutes of activation. Shield polls every ~30 seconds; the platform processes events within seconds of receipt.
+
+**How do I verify it's working end-to-end?**
+Run `openclaw shield status` and check that `Events sent` is increasing and `Last capture` is recent. Then visit [uss.upx.com](https://uss.upx.com) and check your instance — you should see events flowing within 2 minutes.
+
+**What if I don't see any events after 5 minutes?**
+Check `openclaw shield status` for elevated `Failures` or a stale `Last sync`. If failures are high, restart the gateway. If `Last capture` is old, your agent hasn't used any tools — run a command to generate activity.
+
+**Can I run Shield alongside other plugins?**
+Yes. Shield runs as a passive observer — it hooks into the event stream and does not interfere with other plugins or agent behavior.
+
+**Is my Installation Key burned if activation fails?**
+No. The key is consumed only on the first *successful* activation. If the attempt fails (network issue, config error), you can fix the issue and retry with the same key.
+
+**Where is the changelog?**
+the CHANGELOG, available on the Shield portal at uss.upx.com
+
+---
+
+## Subscription expiry
+
+When a subscription lapses or the monthly event quota is exhausted, Shield detects this on the next ingest call and will:
+
+1. Log a clear warning
+2. Stop transmitting events — **events are dropped, not queued**
+3. Show elevated consecutive failures in `openclaw shield status`
+
+Events generated during an expiry or quota period are permanently lost. Renew your subscription at [uss.upx.com](https://uss.upx.com) and restart the gateway to resume.
+
+---
+
 ## Uninstalling
 
 ```bash
 openclaw plugins uninstall shield
 ```
 
-Stops the monitoring bridge and removes the plugin.
+This removes the plugin code. To fully remove all local Shield data:
+
+```bash
+rm -rf ~/.openclaw/shield/
+```
+
+This deletes credentials, cursors, IP cache, and the redaction vault. 
+
+> **Note:** The redaction vault (`data/redaction-vault.json`) contains the mapping from redaction tokens back to original values. Deleting it means you can no longer reverse-lookup redacted values from past events. Retain this file for as long as your data retention policy requires.
+
+Platform-side instance data can be managed via [uss.upx.com](https://uss.upx.com).
 
 ---
 
 ## Need help?
 
-Visit the Shield portal at [uss.upx.com](https://uss.upx.com) or contact your Shield administrator. For UPX support, reach out at [upx.com](https://upx.com).
+Visit [uss.upx.com](https://uss.upx.com) or contact your Shield administrator.

package/dist/index.d.ts

@@ -10,6 +10,16 @@ interface StartGuard {
     reset: () => void;
 }
 export declare function createStartGuard(): StartGuard;
+interface StatusWarningInput {
+    running: boolean;
+    lastPollAt?: number | null;
+    lastSyncAt?: number | null;
+    lastCaptureAt?: number | null;
+    captureSeenSinceLastSync?: boolean;
+    consecutiveFailures?: number | null;
+    now?: number;
+}
+export declare function getStatusWarnings(input: StatusWarningInput): string[];
 interface OpenClawPluginAPI {
     config?: Record<string, unknown>;
     pluginConfig?: Record<string, unknown>;

package/dist/index.js

@@ -38,6 +38,7 @@ exports.resolveInstallationKey = resolveInstallationKey;
 exports.maskPluginConfigForLogs = maskPluginConfigForLogs;
 exports.createSingleflightRunner = createSingleflightRunner;
 exports.createStartGuard = createStartGuard;
+exports.getStatusWarnings = getStatusWarnings;
 const config_1 = require("./src/config");
 const log_1 = require("./src/log");
 const log = __importStar(require("./src/log"));
@@ -94,6 +95,13 @@ async function performAutoRegistration(installationKey) {
         const configDir = (0, path_1.join)(config_1.SHIELD_CONFIG_PATH, '..');
         if (!(0, fs_1.existsSync)(configDir))
             (0, fs_1.mkdirSync)(configDir, { recursive: true });
+        if ((0, fs_1.existsSync)(config_1.SHIELD_CONFIG_PATH)) {
+            const existing = (0, config_1.loadCredentials)();
+            if (hasValidCredentials(existing)) {
+                log.info('shield', 'Existing credentials found and valid — skipping config.env overwrite.');
+                return existing;
+            }
+        }
         const envContent = [
             `# Shield API Configuration — auto-generated by OpenClaw plugin on ${new Date().toISOString()}`,
             `SHIELD_API_URL=${SHIELD_API_URL}`,
@@ -262,6 +270,35 @@ function readPersistedState() {
         return null;
     }
 }
+const STALE_POLL_WARN_MS = 2 * 60 * 1000;
+const STALE_SYNC_WARN_MS = 15 * 60 * 1000;
+const CONSECUTIVE_FAILURES_WARN = 5;
+function getStatusWarnings(input) {
+    const warnings = [];
+    if (!input.running)
+        return warnings;
+    const now = input.now ?? Date.now();
+    const lastPollAt = input.lastPollAt ?? 0;
+    const lastSyncAt = input.lastSyncAt ?? 0;
+    const lastCaptureAt = input.lastCaptureAt ?? 0;
+    const captureSeenSinceLastSync = input.captureSeenSinceLastSync ?? false;
+    const consecutiveFailures = input.consecutiveFailures ?? 0;
+    if (!lastPollAt) {
+        warnings.push('Hooks may not be initialized: service is running but no poll has executed yet.');
+    }
+    else if (now - lastPollAt > STALE_POLL_WARN_MS) {
+        warnings.push('Polling looks stale while connected; event capture may be paused after reload.');
+    }
+    const staleSinceSync = Boolean(lastSyncAt) && (now - lastSyncAt > STALE_SYNC_WARN_MS);
+    const staleSinceCaptureWithoutSync = !lastSyncAt && Boolean(lastCaptureAt) && (now - lastCaptureAt > STALE_SYNC_WARN_MS);
+    if (captureSeenSinceLastSync && (staleSinceSync || staleSinceCaptureWithoutSync)) {
+        warnings.push('Capture activity observed, but no successful event sync in a prolonged interval.');
+    }
+    if (consecutiveFailures >= CONSECUTIVE_FAILURES_WARN) {
+        warnings.push(`Consecutive poll failures are elevated (${consecutiveFailures}).`);
+    }
+    return warnings;
+}
 const state = {
     activated: false,
     running: false,
@@ -271,8 +308,11 @@ const state = {
     quarantineCount: 0,
     consecutiveFailures: 0,
     instanceId: '',
+    lastCaptureAt: 0,
+    captureSeenSinceLastSync: false,
     lastSync: null,
 };
+let teardownPreviousRuntime = null;
 const MAX_BACKOFF_MS = 5 * 60 * 1000;
 const TELEMETRY_INTERVAL_MS = 5 * 60 * 1000;
 function getBackoffInterval(baseMs) {
@@ -319,12 +359,35 @@ function printActivatedStatus() {
     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;
+    if (lastCaptureLabel)
+        console.log(`  Last capture: ${lastCaptureLabel}`);
     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)`);
     if (s.pid)
         console.log(`  Daemon PID:   ${s.pid}`);
+    const statusWarnings = getStatusWarnings({
+        running: isRunning,
+        lastPollAt: s.lastPollAt ?? null,
+        lastSyncAt: s.lastSync?.at ?? null,
+        lastCaptureAt: s.lastCaptureAt ?? null,
+        captureSeenSinceLastSync: Boolean(s.captureSeenSinceLastSync ?? false),
+        consecutiveFailures: s.consecutiveFailures ?? 0,
+    });
+    if (statusWarnings.length > 0) {
+        console.log('  Warning:      ⚠️ Capture health degraded');
+        for (const warning of statusWarnings) {
+            console.log(`               - ${warning}`);
+        }
+        console.log('               - If this persists, run: openclaw gateway restart');
+    }
     const startedAt = s.startedAt;
     if (startedAt) {
         const uptimeMs = Date.now() - startedAt;
@@ -424,6 +487,51 @@ exports.default = {
         let telemetryHandle = null;
         const startGuard = createStartGuard();
         let onSignalHandler = null;
+        let runtimeGeneration = 0;
+        const clearRuntimeHandles = () => {
+            if (pollHandle) {
+                clearTimeout(pollHandle);
+                pollHandle = null;
+            }
+            if (telemetryHandle) {
+                clearInterval(telemetryHandle);
+                telemetryHandle = null;
+            }
+        };
+        const detachSignalHandlers = () => {
+            if (!onSignalHandler)
+                return;
+            process.off('SIGTERM', onSignalHandler);
+            process.off('SIGINT', onSignalHandler);
+            onSignalHandler = null;
+        };
+        const cleanupRuntime = async (opts) => {
+            runtimeGeneration++;
+            pollFn = null;
+            clearRuntimeHandles();
+            detachSignalHandlers();
+            const markStopped = opts?.markStopped ?? true;
+            if (markStopped) {
+                state.running = false;
+                markStateDirty();
+                persistState();
+            }
+            if (opts?.resetGuard) {
+                startGuard.reset();
+            }
+            if (opts?.flushRedactor) {
+                try {
+                    const { flush: flushRedactor } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
+                    flushRedactor();
+                }
+                catch { }
+            }
+        };
+        if (teardownPreviousRuntime) {
+            void teardownPreviousRuntime()
+                .catch((err) => log.warn('shield', `Runtime cleanup before re-register failed: ${err instanceof Error ? err.message : String(err)}`));
+        }
+        teardownPreviousRuntime = () => cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: false });
         api.registerService({
             id: 'shield-monitor',
             async start() {
@@ -432,6 +540,8 @@ exports.default = {
                     return;
                 }
                 try {
+                    await cleanupRuntime({ markStopped: false, resetGuard: false, flushRedactor: false });
+                    const activeGeneration = ++runtimeGeneration;
                     let credentials = (0, config_1.loadCredentials)();
                     let validCreds = hasValidCredentials(credentials);
                     if (!validCreds && installationKey) {
@@ -480,7 +590,7 @@ exports.default = {
                     state.running = true;
                     persistState();
                     const runTelemetry = async () => {
-                        if (!state.running)
+                        if (!state.running || activeGeneration !== runtimeGeneration)
                             return;
                         const hostSnapshot = config.collectHostMetrics ? generateHostTelemetry() : null;
                         const hostMeta = hostSnapshot?.event?.tool_metadata;
@@ -503,18 +613,24 @@ exports.default = {
                             },
                         };
                         const result = await reportInstance(instancePayload, config.credentials);
+                        if (activeGeneration !== runtimeGeneration)
+                            return;
                         log.info('shield', `Instance report → Platform: success=${result.ok}`);
                     };
                     const runTelemetrySingleflight = createSingleflightRunner(runTelemetry);
                     runTelemetrySingleflight().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
                     telemetryHandle = setInterval(() => {
+                        if (activeGeneration !== runtimeGeneration || !state.running)
+                            return;
                         runTelemetrySingleflight().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
                     }, TELEMETRY_INTERVAL_MS);
                     const poll = async () => {
-                        if (!state.running)
+                        if (!state.running || activeGeneration !== runtimeGeneration)
                             return;
                         try {
                             const entries = await fetchNewEntries(config);
+                            if (activeGeneration !== runtimeGeneration)
+                                return;
                             if (entries.length === 0) {
                                 commitCursors(config, []);
                                 state.consecutiveFailures = 0;
@@ -523,6 +639,9 @@ exports.default = {
                                 persistState();
                                 return;
                             }
+                            state.lastCaptureAt = Date.now();
+                            state.captureSeenSinceLastSync = true;
+                            markStateDirty();
                             let envelopes = transformEntries(entries);
                             const { valid: validEvents, quarantined } = validate(envelopes.map(e => e.event));
                             if (quarantined > 0) {
@@ -536,6 +655,8 @@ exports.default = {
                                 envelopes = envelopes.map(e => redactEvent(e));
                             }
                             const results = await sendEvents(envelopes, config);
+                            if (activeGeneration !== runtimeGeneration)
+                                return;
                             const needsReg = results.some(r => r.needsRegistration);
                             if (needsReg) {
                                 log.error('shield', 'Instance not registered on platform — Shield deactivated.');
@@ -551,6 +672,8 @@ exports.default = {
                                 markStateDirty();
                                 persistState();
                                 await new Promise(r => setTimeout(r, waitMs));
+                                if (activeGeneration !== runtimeGeneration)
+                                    return;
                                 return;
                             }
                             const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
@@ -567,6 +690,7 @@ exports.default = {
                                 }
                                 const lastSync = { at: Date.now(), eventCount: accepted, eventTypes: syncEventTypes };
                                 state.lastSync = lastSync;
+                                state.captureSeenSinceLastSync = false;
                                 writeAllTimeStats({ eventsProcessed: accepted, lastSync });
                             }
                             else {
@@ -578,6 +702,8 @@ exports.default = {
                             persistState();
                         }
                         catch (err) {
+                            if (activeGeneration !== runtimeGeneration)
+                                return;
                             state.consecutiveFailures++;
                             markStateDirty();
                             log.error('shield', `Poll error: ${err instanceof Error ? err.message : String(err)}`);
@@ -587,14 +713,18 @@ exports.default = {
                     pollFn = runPollSingleflight;
                     await runPollSingleflight();
                     const schedulePoll = () => {
-                        if (!state.running)
+                        if (!state.running || activeGeneration !== runtimeGeneration)
                             return;
                         const interval = getBackoffInterval(config.pollIntervalMs);
                         if (interval !== config.pollIntervalMs) {
                             log.warn('shield', `Backing off: next poll in ${Math.round(interval / 1000)}s (${state.consecutiveFailures} consecutive failures)`);
                         }
                         pollHandle = setTimeout(() => {
+                            if (activeGeneration !== runtimeGeneration || !state.running)
+                                return;
                             runPollSingleflight().catch((err) => {
+                                if (activeGeneration !== runtimeGeneration)
+                                    return;
                                 state.consecutiveFailures++;
                                 log.error('shield', `Poll error (unhandled): ${err instanceof Error ? err.message : String(err)}`);
                             }).finally(() => {
@@ -606,23 +736,7 @@ exports.default = {
                     onSignalHandler = async () => {
                         if (!state.running)
                             return;
-                        state.running = false;
-                        startGuard.reset();
-                        markStateDirty();
-                        persistState();
-                        if (pollHandle) {
-                            clearTimeout(pollHandle);
-                            pollHandle = null;
-                        }
-                        if (telemetryHandle) {
-                            clearInterval(telemetryHandle);
-                            telemetryHandle = null;
-                        }
-                        try {
-                            const { flush: fr } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
-                            fr();
-                        }
-                        catch { }
+                        await cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: true });
                         log.info('shield', 'Service stopped (signal)');
                     };
                     process.once('SIGTERM', onSignalHandler);
@@ -635,31 +749,10 @@ exports.default = {
                 }
             },
             async stop() {
-                if (!state.running)
-                    return;
-                state.running = false;
-                startGuard.reset();
-                markStateDirty();
-                persistState();
-                if (pollHandle) {
-                    clearTimeout(pollHandle);
-                    pollHandle = null;
-                }
-                if (telemetryHandle) {
-                    clearInterval(telemetryHandle);
-                    telemetryHandle = null;
-                }
-                if (onSignalHandler) {
-                    process.off('SIGTERM', onSignalHandler);
-                    process.off('SIGINT', onSignalHandler);
-                    onSignalHandler = null;
-                }
-                try {
-                    const { flush: flushRedactor } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
-                    flushRedactor();
-                }
-                catch { }
-                log.info('shield', 'Service stopped');
+                const wasRunning = state.running;
+                await cleanupRuntime({ markStopped: true, resetGuard: true, flushRedactor: true });
+                if (wasRunning)
+                    log.info('shield', 'Service stopped');
             },
         });
         api.registerGatewayMethod('shield.status', ({ respond }) => {
@@ -669,6 +762,8 @@ exports.default = {
                 activated,
                 running: state.running,
                 lastPollAt: state.lastPollAt,
+                lastCaptureAt: state.lastCaptureAt,
+                captureSeenSinceLastSync: state.captureSeenSinceLastSync,
                 eventsProcessed: state.eventsProcessed,
                 quarantineCount: state.quarantineCount,
                 consecutiveFailures: state.consecutiveFailures,

package/dist/src/index.js

@@ -68,17 +68,20 @@ async function poll() {
             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)() ?? undefined,
                     },
                     software: {
                         plugin_version: version_1.VERSION,
                         openclaw_version: (0, transformer_1.resolveOpenClawVersion)(),
-                        agent_label: (0, transformer_1.resolveAgentLabel)('main'),
+                        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'],

package/dist/src/sender.js

@@ -163,6 +163,16 @@ async function sendEvents(events, config) {
                     log.warn('sender', `Batch ${batchNum} attempt ${attempt + 1} — HTTP ${res.status}, retrying...`);
                     continue;
                 }
+                let parsedData = null;
+                try {
+                    parsedData = JSON.parse(data);
+                }
+                catch { }
+                if (res.status === 402 || (res.status === 429 && parsedData?.error === 'quota_exceeded')) {
+                    log.warn('sender', `⚠ Event quota exhausted or subscription inactive — events are being dropped. Renew your subscription to resume delivery.`);
+                    results.push({ success: false, statusCode: res.status, body: data, eventCount: batch.length });
+                    break;
+                }
                 const safeBody = sanitizeResponseBodyForLog(data);
                 log.error('sender', `Batch ${batchNum} — HTTP ${res.status}: ${safeBody}`);
                 consecutiveBatchFailures++;

package/dist/src/transformer.d.ts

@@ -10,6 +10,7 @@ export interface IngestPayload {
 }
 export declare function resolveOpenClawVersion(): string;
 export declare function resolveAgentLabel(agentId: string): string;
+export declare function getCachedPublicIp(): string | null;
 export declare function resolveOutboundIp(): Promise<string | null>;
 export declare function transformEntries(entries: RawEntry[]): EnvelopeEvent[];
 export declare function generateHostTelemetry(): EnvelopeEvent | null;

package/dist/src/transformer.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveOpenClawVersion = resolveOpenClawVersion;
 exports.resolveAgentLabel = resolveAgentLabel;
+exports.getCachedPublicIp = getCachedPublicIp;
 exports.resolveOutboundIp = resolveOutboundIp;
 exports.transformEntries = transformEntries;
 exports.generateHostTelemetry = generateHostTelemetry;
@@ -116,6 +117,9 @@ function writeIpCache(ip) {
     }
     catch { }
 }
+function getCachedPublicIp() {
+    return readIpCache()?.ip ?? (_source?.ip_addresses[0] ?? null);
+}
 function resolveOutboundIp() {
     return new Promise((resolve) => {
         try {

package/openclaw.plugin.json

@@ -1,60 +1,60 @@
 {
-  "id": "shield",
-  "name": "OpenClaw Shield",
-  "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.3.5",
-  "skills": [
-    "./skills"
-  ],
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-      "installationKey": {
-        "type": "string",
-        "description": "One-time installation key from the Shield portal. The plugin uses this to register the instance and obtain credentials automatically. Can be removed from config after first activation."
-      },
-      "enabled": {
-        "type": "boolean",
-        "default": true
-      },
-      "dryRun": {
-        "type": "boolean",
-        "default": false
-      },
-      "redactionEnabled": {
-        "type": "boolean",
-        "default": true
-      },
-      "pollIntervalMs": {
-        "type": "number",
-        "default": 30000
-      },
-      "collectHostMetrics": {
-        "type": "boolean",
-        "default": false
-      }
-    }
-  },
-  "uiHints": {
-    "installationKey": {
-      "label": "Installation Key",
-      "description": "One-time key from the Shield portal (https://uss.upx.com). Required for first-time activation only."
-    },
-    "enabled": {
-      "label": "Enable security monitoring"
-    },
-    "dryRun": {
-      "label": "Dry run (log events locally, do not transmit)"
-    },
-    "redactionEnabled": {
-      "label": "Redact sensitive values before transmitting"
-    },
-    "pollIntervalMs": {
-      "label": "Polling interval (milliseconds)"
+    "id": "shield",
+    "name": "OpenClaw Shield",
+    "description": "Real-time security monitoring — streams enriched, redacted security events to the Shield detection platform.",
+    "version": "0.3.16",
+    "skills": [
+        "./skills"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "installationKey": {
+                "type": "string",
+                "description": "One-time installation key from the Shield portal. The plugin uses this to register the instance and obtain credentials automatically. Can be removed from config after first activation."
+            },
+            "enabled": {
+                "type": "boolean",
+                "default": true
+            },
+            "dryRun": {
+                "type": "boolean",
+                "default": false
+            },
+            "redactionEnabled": {
+                "type": "boolean",
+                "default": true
+            },
+            "pollIntervalMs": {
+                "type": "number",
+                "default": 30000
+            },
+            "collectHostMetrics": {
+                "type": "boolean",
+                "default": false
+            }
+        }
     },
-    "collectHostMetrics": {
-      "label": "Collect host telemetry metrics"
+    "uiHints": {
+        "installationKey": {
+            "label": "Installation Key",
+            "description": "One-time key from the Shield portal (https://uss.upx.com). Required for first-time activation only."
+        },
+        "enabled": {
+            "label": "Enable security monitoring"
+        },
+        "dryRun": {
+            "label": "Dry run (log events locally, do not transmit)"
+        },
+        "redactionEnabled": {
+            "label": "Redact sensitive values before transmitting"
+        },
+        "pollIntervalMs": {
+            "label": "Polling interval (milliseconds)"
+        },
+        "collectHostMetrics": {
+            "label": "Collect host telemetry metrics"
+        }
     }
-  }
 }

package/package.json

@@ -1,69 +1,72 @@
 {
-  "name": "@upx-us/shield",
-  "version": "0.3.5",
-  "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": [
-    "dist/index.js",
-    "dist/index.d.ts",
-    "dist/src/**/*.js",
-    "dist/src/**/*.d.ts",
-    "openclaw.plugin.json",
-    "skills/",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "prebuild": "npm run clean",
-    "build": "tsc",
-    "start": "node dist/src/index.js",
-    "setup": "node dist/src/setup.js",
-    "lint": "tsc --noEmit",
-    "test": "node --require tsx/cjs --test --test-reporter spec tests/**/*.test.ts tests/*.test.ts",
-    "test:watch": "node --require tsx/cjs --test --watch tests/**/*.test.ts tests/*.test.ts",
-    "test:parser": "node tests/run-parser.js",
-    "test:parser:short": "node tests/run-parser.js --short",
-    "test:parser:verbose": "node tests/run-parser.js --verbose",
-    "test:parser:help": "node tests/run-parser.js help",
-    "dev": "tsx scripts/dev-harness.ts",
-    "dev:dry": "tsx scripts/dev-harness.ts --dry-run",
-    "generate:schemas": "tsx scripts/generate-schemas.ts",
-    "prepublishOnly": "npm run build && npm run generate:schemas && npm run prepublish:check",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "prepublish:check": "node scripts/prepublish-check.js"
-  },
-  "keywords": [
-    "openclaw",
-    "openclaw-plugin",
-    "security",
-    "monitoring",
-    "detection",
-    "siem",
-    "compliance"
-  ],
-  "author": "UPX Security Services",
-  "license": "SEE LICENSE IN LICENSE",
-  "publishConfig": {
-    "tag": "latest",
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ]
-  },
-  "devDependencies": {
-    "@types/node": "^25.2.3",
-    "ts-json-schema-generator": "^2.5.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
-  }
+    "name": "@upx-us/shield",
+    "version": "0.3.16",
+    "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": [
+        "dist/index.js",
+        "dist/index.d.ts",
+        "dist/src/**/*.js",
+        "dist/src/**/*.d.ts",
+        "openclaw.plugin.json",
+        "skills/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "prebuild": "npm run clean",
+        "build": "tsc",
+        "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+        "lint": "tsc --noEmit",
+        "test": "node --require tsx/cjs --test --test-reporter spec tests/**/*.test.ts tests/*.test.ts",
+        "test:watch": "node --require tsx/cjs --test --watch tests/**/*.test.ts tests/*.test.ts",
+        "test:parser": "node tests/run-parser.js",
+        "test:parser:short": "node tests/run-parser.js --short",
+        "test:parser:verbose": "node tests/run-parser.js --verbose",
+        "test:parser:help": "node tests/run-parser.js help",
+        "dev": "tsx scripts/dev-harness.ts",
+        "dev:dry": "tsx scripts/dev-harness.ts --dry-run",
+        "generate:schemas": "tsx scripts/generate-schemas.ts",
+        "package:check": "node scripts/prepublish-check.js",
+        "package:build": "npm run build",
+        "package:validate": "npm run build && npm run test && npm run package:check",
+        "package:pack": "npm pack",
+        "package:publish": "npm run package:validate && npm publish --access public",
+        "start": "node dist/src/index.js",
+        "setup": "node dist/src/setup.js"
+    },
+    "keywords": [
+        "openclaw",
+        "openclaw-plugin",
+        "security",
+        "monitoring",
+        "detection",
+        "siem",
+        "compliance"
+    ],
+    "author": "UPX Security Services",
+    "license": "SEE LICENSE IN LICENSE",
+    "publishConfig": {
+        "tag": "latest",
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "openclaw": {
+        "extensions": [
+            "./dist/index.js"
+        ]
+    },
+    "devDependencies": {
+        "@types/node": "^25.2.3",
+        "ts-json-schema-generator": "^2.5.0",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3"
+    }
 }