@upx-us/shield 0.7.13 → 0.8.1

package/CHANGELOG.md

@@ -4,269 +4,117 @@ All notable changes to this project will be documented in this file.
 
 ---
 
-## [0.7.13] — 2026-03-16
+## [0.8.1] — 2026-03-17
 
 ### Fixed
 
-- **`openclaw shield` commands missing after auto-update** — the auto-updater was deleting the `integrity` field from `openclaw.json` without recomputing it. OpenClaw 2026.3.13+ requires this field to wire plugin CLI commands; without it the plugin loads but `openclaw shield status` and all shield commands fail with "unknown command". The updater now computes the correct SRI `sha512` integrity hash from the downloaded tarball and writes it to the install record.
-
----
-
-## [0.7.12] — 2026-03-16
-
-### Fixed
-
-- **Plugin showing permanently "Disconnected" after gateway hot-reload** — when the OpenClaw gateway reloaded the plugin module, a race condition between teardown and startup caused new startup attempts to silently abort. The previous instance's timers kept running but were invisible to the status command, resulting in permanent "Disconnected" status and missed telemetry cycles. The teardown is now properly awaited before startup proceeds.
-
----
-
-## [0.7.11] — 2026-03-16
-
-### Added
-
-- **Debug logging mode** (`debugLog: true`) — writes timestamped logs to `~/.openclaw/shield/logs/shield-debug.log`. Captures the full startup sequence with numbered checkpoints (1–11 + SIGTERM) so disconnection issues can be pinpointed exactly. Off by default — safe on all existing installs.
-
----
-
-## [0.7.10] — 2026-03-16
-
-### Added
-
-- **`openclaw shield restart` command** — restarts Shield monitoring without a full gateway restart. Checks credentials, clears any stale update state, resets the session, and cycles the runtime. Use `--verbose` for step-by-step diagnostic output.
-
-### Fixed
-
-- **Plugin no longer silently stalls when telemetry consistently fails** — after 10 consecutive failed `reportInstance` calls, the plugin deactivates with a clear log message instead of running indefinitely with no output.
-- **Update cycle cleanup after successful auto-update** — the periodic update check now properly stops all activity after calling a successful gateway restart, preventing a window where both the old and new instance could be active simultaneously.
+- **Disconnected status after failed startup no longer wipes prior healthy activity** — when a new plugin runtime starts but fails before completing its first sync, Shield now preserves the last known-good state (poll time, sync time, session activity) instead of replacing it with a blank slate. Instances that appeared disconnected after a gateway reload now show accurate prior activity.
+- **Plugin no longer advances into startup with partially-formed credentials** — a change in v0.7.5 caused the canonical ingest URL to be treated as a valid credential even when instance ID and HMAC secret were missing, allowing startup to proceed further than it should before failing and writing zero-state. Credential validation now requires all three fields.
+- **Rapid version bumps no longer trigger multiple zero-state writes** — consecutive `openclaw.plugin.json` version changes (as seen in the v0.7.3→v0.7.6 series) could trigger multiple gateway hot-reload cycles, each writing a blank initial state before credential checks failed. The startup guard now prevents redundant state resets during re-registration.
 
 ### Changed
 
-- **Standalone `shield-bridge` binary removed** — the plugin now runs exclusively as an OpenClaw gateway plugin. Running `npx @upx-us/shield` directly shows a clear message with installation instructions. This eliminates a source of divergent behavior that caused the v0.7.7 incident.
-- `bridge` terminology removed from all customer-visible log output and internal comments.
+- **Status output shows last known-good activity when current runtime is disconnected** — if Shield is not running, the status command now surfaces when the last healthy poll and sync occurred, giving a clearer picture of what happened before the disconnect.
 
 ---
 
-## [0.7.9] — 2026-03-16
+## [0.8.0] — 2026-03-17
 
 ### Fixed
 
-- **Bug causing the plugin to repeatedly reinstall itself to the same version** — After a self-update, the plugin could enter a loop installing the already-installed version (e.g. 0.7.8 → 0.7.8) because the cached update state was not cleared correctly. The updater now verifies that the candidate version is strictly newer than the running version before proceeding with any install.
-
----
-
-## [0.7.8] — 2026-03-16
-
-### Fixed
-
-- **Bug causing the plugin to be repeatedly terminated by the gateway after updating** — The same boot-loop fix from v0.7.7 was missing from the gateway plugin entrypoint. When running as an OpenClaw plugin (the normal mode), the gateway would spawn the plugin, the plugin would trigger a new update check, send itself a restart signal, and get killed — silently repeating on every boot.
-
----
-
-## [0.7.7] — 2026-03-16
-
-### Fixed
-
-- **Bug preventing the plugin from starting after an auto-update** (#177): In certain conditions following an auto-update, the plugin would crash on every boot before processing any events. A gateway restart is sufficient to recover affected instances.
-- **Bug causing incorrect plugin version to be reported in the dashboard** (#175): Some instances were reporting a stale version number in the platform dashboard instead of the currently installed version.
-
----
-
-## [0.7.6] — 2026-03-13
-
-### Security
-- **URL enforcement switched to allowlist** — plugin traffic is restricted to the Shield ingest endpoint. Any other URL is rejected and replaced with the default. No infrastructure details are disclosed in source.
-
----
-
-## [0.7.5] — 2026-03-13
-
-### Security
-- **Block direct platform backend calls** — `loadCredentials()` now detects and overrides any `SHIELD_API_URL` pointing to a platform backend (legacy Replit URLs, `uss.upx.com`). Plugin traffic is enforced to only reach the Shield ingest proxy. A second-layer check in the RPC client rejects blocked URLs even if config loading is bypassed.
-- **Fix RPC `apiUrl` resolution** — RPC handlers now use the validated `apiUrl` from credentials instead of a non-existent config field (which silently fell through to `null`).
-
----
-## [0.7.4] — 2026-03-13
-
-### Changed
-- Cases are now instance-scoped by default — the platform API filters cases so each instance only sees its own cases. This eliminates cross-instance notification flooding when multiple instances share an org.
-- Removed `--mine` flag from `shield cases` and `shield cases list` — no longer needed since all returned cases belong to this instance.
-- Removed `[mine]` / `[sibling]` per-case tags from list output.
-- Removed sibling instance notice from `shield cases show`.
-- Removed mixed-ownership attribution summary from case list output.
-
----
-
-## [0.7.3] — 2026-03-13
-
-### Fixed
-- Trigger attribution (`trigger_type`, `author_name`, `trigger_type` fields) now works correctly in OpenClaw plugin mode — the plugin entry point was calling `transformEntries` without forwarding `sessionDirs`, so attribution was silently skipped on every event for all plugin-mode installations
-- Session directory discovery is now robust when the plugin process is spawned with a different `HOME` environment variable than the main OpenClaw process (common on VPS and Docker deployments) — discovery now walks up from the plugin install path to find the `agents/` directory rather than relying solely on `homedir()`
-- `trigger.type` is now always written to `tool_metadata` (as `"unknown"`) even when session directory lookup fails entirely, ensuring the field is never silently absent from SIEM events
-
----
-
-## [0.7.2] — 2026-03-13
-
-### Fixed
-- Events now always include a meaningful `trigger.type` field — previously, unresolved sessions silently omitted the field; they now report `unknown` for full visibility
-- Attribution correctly handles sessions where the first user message contains non-text content blocks (images, structured context)
-- Auto-updater no longer prunes the previous version backup during the install window — the safety net is preserved until the new version is confirmed running
-- Gateway restart is now blocked if critical plugin files are missing or empty after install, preventing boot loops from incomplete updates
-
-### Improved
-- `shield logs` entries now include a `details` line (file path, command, or URL) and a `[trigger_type]` tag per event — significantly more useful for case investigation
-- Each event type generates a meaningful one-line summary (`read: path/to/file`, `exec: npm test`, `fetch: example.com/api`) instead of just the tool name
-- New `src/utils.ts` shared module — `trunc()` and `urlHost()` helpers consolidated with full unit test coverage
-
----
-
-## [0.7.1] — 2026-03-13
-
-### Added
-- Case ownership awareness: `shield cases` now shows which cases belong to this instance vs other instances in the org
-- `--mine` flag for `shield cases` and `shield cases list` to filter to locally-owned cases
-- Sibling case detail view: `shield cases show <ID>` notes when a case belongs to another org instance and clarifies that remote investigation requires direct platform access
-- Attribution summary line when listing mixed-ownership cases
-
----
-
-## [0.7.0] — 2026-03-13
-
-### Added
-- **Event authorship & source attribution** — Shield now captures the source of every monitored agent action: who or what triggered it. Each event is tagged with an authorship category — a user via a messaging channel (Telegram, Discord, WhatsApp, etc.), a scheduled job, a periodic health check, a spawned sub-agent, or an autonomous agent action. This context appears alongside every event in your security dashboard, enabling "who caused this?" forensics on any alert or case.
-- **Sender identity captured when available** — when an action is triggered by a user via a messaging channel, the user's display name and channel are captured in plain text for human-readable alerting. The raw user identifier is stored as a reversible token (recoverable locally via `openclaw shield vault show`).
+- **Plugin could stay partially active after losing platform authorization** — when the platform revoked an instance's registration, Shield now fully shuts down all background activity immediately instead of only stopping event delivery. Prevents a state where the plugin appeared stopped but was still running internally.
+- **Diagnostic state could be lost on unexpected crashes** — Shield now saves error details to disk immediately when a poll cycle fails, so the information is preserved even if the process exits right after.
+- **Silent crash after first successful sync on certain Linux environments** — fixed an issue where Shield would start correctly, deliver the first batch of events, then crash silently without any log output. Affected VPS and containerized deployments.
 
 ### Changed
-- **README updated** — new "Authorship & Event Source" section documents the authorship categories available in the dashboard.
 
-### Notes
-- Fully backward compatible. Existing deployments continue to work without any configuration changes. Authorship context is captured automatically on upgrade.
+- **`shield restart` is more reliable** — the restart sequence now uses a consistent reset path, reducing the chance of leftover state from a previous session affecting the new one.
+- **Failed batch retries no longer skip already-delivered events** — when a sync cycle partially succeeds, Shield retries only what failed. Events already accepted by the platform are not re-sent.
 
 ---
 
-## [0.6.10] — 2026-03-12
+## [0.7 series] — 2026-03-13 to 2026-03-16
 
-### Fixed
-- **Local event buffer not populated in plugin mode** — `appendEvents` and `initEventStore` were implemented in the standalone bridge (`src/index.ts`) but never wired into the plugin-mode poll loop (`index.ts`). As a result, `openclaw shield logs` always returned "No events found" even when events were being sent successfully to the platform. Fixed by wiring the event store into the plugin-mode startup and poll cycle (#148).
+> Versions 0.7.0–0.7.13. Individual patch notes consolidated below.
 
-### Changed
-- **Local event buffer default increased to 250** — was 123. Provides better forensic coverage (~24h of normal activity) without significant storage impact. `SHIELD_LOCAL_EVENT_LIMIT` env var still overrides this. README and config updated (#148).
-- **Version corrected from 1.3.0 → 0.6.10** — the 1.3.0 version in `package.json` was premature; this release re-anchors versioning at the correct next increment after 0.6.8.
+### Added across 0.7 series
+- **Event authorship & source attribution** (0.7.0) — every monitored event is now tagged with its source: a user via a messaging channel, a scheduled job, a health check, a sub-agent, or an autonomous agent action. Enables "who caused this?" forensics on any alert or case.
+- **Sender identity captured when available** (0.7.0) — when triggered by a user via a messaging channel, the user's display name and channel are captured for human-readable alerting.
+- **`openclaw shield restart` command** (0.7.10) — restarts Shield monitoring without a full gateway restart. Use `--verbose` for step-by-step output.
+- **Debug logging mode** (0.7.11) — opt-in detailed startup and runtime logs written to `~/.openclaw/shield/logs/shield-debug.log`. Off by default.
+- **Instance-scoped cases** (0.7.4) — each instance only sees its own security cases; no cross-instance notification flooding in multi-instance orgs.
+- **`shield logs` now includes event details and trigger context** (0.7.2) — each log entry shows the file path, command, or URL involved and what triggered the session.
 
-### Added
-- **`openclaw.message_length_bytes` enrichment field** — message events now include the byte length of the message body as `openclaw.message_length_bytes`. Enables detection rules based on message size thresholds (#152).
-- **Event buffer diagnostics in `shield.status`** — `shield.status` RPC now includes an `eventBuffer` section showing: `enabled`, `path`, `total` events buffered, `oldest`/`newest` timestamps, and `redactedCount`. Makes it immediately diagnosable if the local log is empty or disabled (#148).
+### Fixed across 0.7 series
+- **Plugin commands disappearing after auto-update** (0.7.13) — `openclaw shield status` and all shield commands returned "unknown command" after an update. Fixed.
+- **Permanent "Disconnected" status after gateway reload** (0.7.12) — a race condition between shutdown and startup left the plugin in a broken state. Fixed.
+- **Plugin silently stalling on repeated telemetry failures** (0.7.10) — after 10 consecutive failures, the plugin now deactivates cleanly with a clear log message.
+- **Update loop installing the same version repeatedly** (0.7.9) — the updater now verifies the candidate version is strictly newer before proceeding.
+- **Boot loop after auto-update in plugin mode** (0.7.7, 0.7.8) — fixed a crash-on-boot cycle affecting gateway-loaded plugin mode.
+- **Trigger attribution silently skipped in plugin mode** (0.7.3) — attribution fields were missing from all events on plugin-mode installations. Fixed.
+- **Session directory discovery failing on VPS and Docker** (0.7.3) — discovery now works regardless of how `HOME` is set when the plugin process starts.
 
-### Docs
-- **Case investigation workflow in SKILL.md** — documents the standard 4-step forensic procedure: cases + logs + vault correlation for complete incident context. Covers correlating case timestamps, log event windows, and redaction vault lookups (#148, #151).
-- **Expanded uninstall documentation in README** — step-by-step uninstall guide covering plugin removal, local data cleanup (with file-by-file breakdown), and platform instance deactivation. Includes redaction vault retention warning (#151).
+### Changed across 0.7 series
+- **Standalone `shield-bridge` binary removed** (0.7.10) — the plugin now runs exclusively as an OpenClaw gateway plugin. Running it directly shows installation instructions.
+- **`--mine` flag removed from `shield cases`** (0.7.4) — no longer needed; all returned cases already belong to this instance.
 
 ---
 
-## [0.6 series summary] — 2026-03-06 to 2026-03-10
-
-> Versions 0.6.0–0.6.8 are superseded by 0.6.10. Individual release notes consolidated below.
+## [0.6 series] — 2026-03-06 to 2026-03-12
 
 ### Added across 0.6 series
-- **Transformer gap fields** (0.6.0) — 7 new enrichment fields unblocking ~20 SIEM detection rules: `openclaw.secret_in_command`, `openclaw.channel`, `openclaw.chat_type`, `openclaw.message_content`, `openclaw.browser_action`, `openclaw.config_change`, `openclaw.file_size_bytes`
-- **Plugin lifecycle events** (0.6.6) — startup, update failure, integrity drift, and check-failing signals forwarded to the platform via `PUT /v1/instance`
-- **Smart degradation detection in `shield status`** (0.6.5) — three-gate algorithm (count + time + sticky recovery) eliminating false-positive DEGRADED alerts
-- **`_skill_hint` in RPC responses** (0.6.0) — machine-readable hint in all Shield RPC replies
-- **Postinstall guidance** (0.6.7) — clear warning when plugin is installed outside OpenClaw
-- **First event confirmation log** (0.6.7) — `✅ First event delivered` emitted once per process lifetime
-- **Vault summary in `shield.status`** (0.6.7) — redaction vault breakdown by category
+- **`openclaw shield logs`** — view recent events captured by Shield directly from the command line, with filtering by type, time window, and JSON output
+- **Event context in logs** — each log entry now shows the file, command, or URL involved alongside what triggered the session
+- **`openclaw shield vault show`** — inspect the local agent and workspace inventory with redaction token summary
+- **Status diagnostics** — `shield status` now shows event buffer health, redaction counts by category, and clearer degradation signals
+- **Plugin lifecycle signals** — Shield reports startup, update failures, and integrity changes to the platform for visibility in the dashboard
+- **Message size tracking** — message events include the byte size of the message body, enabling size-based detection rules
+- **Redaction coverage expanded** — credentials in `curl` commands (`-u`, `--user`, `Authorization: Basic`) are now redacted; npm package references no longer trigger false positives
 
 ### Fixed across 0.6 series
-- **Auto-update restart resilience** (0.6.1) — `pendingRestart` tracked in state, retried for 5 cycles then rolls back to backup
-- **ANSI field prefix** (0.6.2) — `ansi_content_detected`/`ansi_sequences` now correctly namespaced as `openclaw.*`
-- **Version normalization** (0.6.3) — messy `openclaw --version` strings normalized to clean semver
-- **Missing public IP in telemetry** (0.6.3) — `PUT /v1/instance` always includes `public_ip` (sends `""` instead of omitting)
-- **Case monitor exclusions crash** (0.6.4) — soft dependency: if exclusions not initialized, cases forwarded unfiltered instead of throwing
-- **npm redaction false positive** (0.6.7) — `@scope/package@version` no longer matched by SSH `user@host` regex
-- **curl credential redaction** (0.6.8) — `curl -u`, `--user`, and `Authorization: Basic` all redacted as `secret:HASH`
-- **`SHIELD_AUTO_UPDATE=false` ignored** (0.6.6) — env var now correctly parsed as boolean
+- **`openclaw shield logs` always showing empty** — event capture was never connected to the local log store in plugin mode. Fixed.
+- **Auto-update sometimes failing to recover after a bad restart** — the update state is now tracked persistently and retried before falling back to the previous version
+- **Plugin reporting wrong version in the dashboard** — version detection is now reliable across macOS, Linux, and containerized environments
+- **`SHIELD_AUTO_UPDATE=false` being ignored** — the environment variable is now parsed correctly
+- **False-positive DEGRADED status in `shield status`** — a three-condition check now prevents transient failures from incorrectly marking the plugin as degraded
 
 ---
 
-## [0.5.38] — 2026-03-06
+## [0.5 series] — 2026-03-06
 
-### Added
-- `_skill_hint` field in all RPC responses (agent-facing, invisible to users)
+### Added across 0.5 series
+- **Plain language case notifications** — alerts now lead with a human-readable summary; technical rule details are available as a footnote
+- **False positive exclusions** — mark a case as a false positive and Shield suppresses identical future alerts automatically. Manage via `openclaw shield exclusions`
 
 ---
 
-## [0.5.18] — 2026-03-06
+## [0.4 series] — 2026-03-05
 
-### Added
-- **User-friendly case notifications** — notifications now use plain language summaries when available, with technical details (rule title, MITRE technique) as a `📎` footnote.
-- **False positive exclusions** — mark a case as false positive and Shield auto-suppresses identical future alerts for your instance.
-  - `openclaw shield exclusions` — list active exclusions.
-  - `openclaw shield exclusions remove <ID>` — re-enable alerts by removing an exclusion.
-  - RPCs: `shield.exclusions_list`, `shield.exclusion_add`, `shield.exclusion_remove`.
-  - Pattern normalization: IPs, UUIDs, timestamps, and hashes are generalized so the same type of event matches regardless of specific values.
+### Added across 0.4 series
+- **Case management** — `openclaw shield cases` to list open security cases; `cases show <ID>` for full detail including events and remediation playbook; `cases resolve <ID>` to close a case with resolution notes
+- **Case notifications** — Shield polls for new cases and notifies you automatically
+- **`openclaw shield logs`** — local rolling store of recent events for offline inspection and debugging, with filtering options
+- **Agent and workspace inventory** — Shield discovers all agents running on the machine and surfaces cross-workspace activity in the dashboard
+- **Auto-update** — Shield keeps itself up to date automatically. Patch and minor versions install with a rollback safety net; major versions notify only
+- **Resilient local storage** — local state files recover automatically from corruption instead of causing crashes
 
-### Fixed
-- Campaign URLs updated to English (`/en/` instead of `/pt/`).
+### Fixed across 0.4 series
+- **Auto-update continuing to run after a failed gateway restart** — Shield now holds at the previous version until the restart succeeds
+- **Stale process warnings in `shield status`** — the status command now detects when a previously recorded process is no longer running and reports it clearly
 
 ---
 
-## [0.4.36] — 2026-03-05
-
-Consolidated from 0.4.0–0.4.12.
-
-### Added
-- **Case management** — `openclaw shield cases` CLI command to list open security cases, `cases show <ID>` for full detail with events, rule info, and playbook, `cases resolve <ID>` with `--resolution`, `--root-cause`, and `--comment` flags.
-- **Case notification system** — agent polls platform for new cases and notifies users. Case monitor with pending notification queue and acknowledgment.
-- 4 case RPCs: `shield.cases_list`, `shield.case_detail`, `shield.case_resolve`, `shield.cases_ack`.
-- **Local event buffer** — rolling store of recently sent events for offline inspection and debugging. `openclaw shield logs` command with `--last`, `--type`, `--since`, and `--format` options. `shield.events_recent` and `shield.events_summary` RPCs now return local data. Configurable via `SHIELD_LOCAL_EVENT_BUFFER` and `SHIELD_LOCAL_EVENT_LIMIT`.
-- **Host agent/workspace inventory** — scans agents on startup, persists to local vault. Cross-workspace access detection enriches events. New token categories: `agent:HASH`, `workspace:HASH`. `openclaw shield vault show` displays inventory with hashed IDs and redaction token summary.
-- **Auto-update** — plugin checks for updates on gateway restart and every 6 hours. Patch and minor versions install automatically with backup and rollback safety. Major versions notify only.
-- **Chained command detection** — exec events parse shell chains (`&&`, `||`, `;`) to detect destructive commands regardless of position.
-- **Atomic file writes** (`writeJsonSafe`) for status, stats, vault, updater state, and IP cache — prevents corruption on crash or disk-full.
-- **Corrupt JSON recovery** (`readJsonSafe`) — auto-recovers from corrupted state files instead of crash-looping.
-- Skill validation tests (26 tests) to prevent infrastructure leaks in ClawHub-published content.
-- ClawHub frontmatter metadata, gating via `requires.config`, cross-references between npm/ClawHub/dashboard.
-- `callPlatformApi` now supports GET and POST methods.
-- Platform attribution in case detail responses.
-- Tarball shasum preserved in `openclaw.json` after self-update.
-- Plugin metadata sync prevents OpenClaw core updates from removing the plugin.
+## [0.3 series] — 2026-02-26 to 2026-03-03
 
-### Fixed
-- Auto-update no longer kills bridge when gateway restart fails — continues running with old version in memory.
-- Stale PID detection in `shield status` — warns when daemon PID is no longer running.
-- OpenClaw version detection: replaced hardcoded macOS paths with platform-independent `require.resolve` + `execSync` fallback.
-- HMAC signing in RPC client aligned with sender format (`fingerprint:nonce`).
+### Added across 0.3 series
+- **Auto-update** — Shield checks for newer versions on startup and installs them automatically with backup and rollback safety
+- **Chained command detection** — Shell chains (`&&`, `||`, `;`) are parsed so detection rules can match commands regardless of their position in a sequence
+- **Quick Install** — terminal-based setup flow that doesn't require agent involvement
+- Location and identity data included in telemetry for geo-correlation in the dashboard
 
-### Changed
-- Installation instructions rewritten: three options (Quick Install, Agent Configure, Agent Full) with command reference table and agent refusal guidance.
-- CHANGELOG.md now bundled with npm package.
-
----
-
-## [0.3.29] — 2026-03-03
-
-Consolidated from 0.3.0–0.3.28.
-
-### Added
-- **Auto-update** — Shield checks for newer versions and installs them automatically. Patch and minor versions install with backup and rollback safety. Major versions notify only. Configure via `autoUpdate` in plugin config.
-- **Chained command detection** — exec events parse chained commands (`&&`, `||`, `;`) to extract all commands in a chain.
-- Public IP and instance name included in telemetry for geo-enrichment and display.
-- Update check on gateway startup — no longer need to wait for the 6-hour cycle.
-- Commands reference table in README.
-- Quick Install section for terminal-based setup (no agent needed).
-
-### Fixed
-- Plugin no longer deactivates on transient registration failures at startup. Retries up to 10 times before exiting.
-- Auto-update now wired into the plugin entry point (the file OpenClaw actually loads).
-- Auto-update now syncs `plugins.installs.shield` metadata in `openclaw.json` after self-updating — prevents OpenClaw core updates from removing the plugin.
-- Auto-update now computes and preserves tarball shasum in `openclaw.json` metadata after self-update.
-- Detection rules can now match destructive commands embedded after chain operators.
-
-### Changed
-- README installation section fully rewritten: three clear options (Quick Install, Agent Configure, Agent Full), command reference table, concern table, manual steps.
-- Agent refusal guidance added with explicit trust confirmation prompt and concern-by-concern explanation table.
-- Quick Start prompt rewritten to address agent security concerns (redaction model, npm scope trust, installation key purpose).
-- CHANGELOG.md now bundled with the npm package.
+### Fixed across 0.3 series
+- Plugin no longer stops monitoring on transient registration failures at startup — retries before giving up
+- Auto-update now correctly preserves plugin registration in OpenClaw after installing a new version
 
 ---
 

package/README.md

@@ -1,14 +1,31 @@
 # OpenClaw Shield
 
 > **OpenClaw Shield is a paid security service by UPX.**
-> Start your **free 30-day trial** at [upx.com/en/lp/openclaw-shield-upx](https://www.upx.com/en/lp/openclaw-shield-upx).
+> Start your **free 60-day trial (no credit card required)** at [upx.com/en/lp/openclaw-shield-upx](https://www.upx.com/en/lp/openclaw-shield-upx).
 
-Real-time security monitoring for your OpenClaw agents — powered by the UPX Shield detection platform.
+**OpenClaw Shield** is the first SIEM-powered security solution built for AI agents — not to control what they *can* do, but to detect what they *did*.
+
+While agent sandboxes block at the gate, Shield watches from inside: every tool call, file read, command execution, and outbound request is ingested, enriched, and matched against behavioral detection rules in real time. Anomalies become cases. Cases get playbooks.
+
+**What you get:**
+- 🔍 **90+ detection rules** tuned for OpenClaw agents — continuously curated and expanded by UPX security experts
+- 📋 Automated case generation with remediation playbooks
+- 🔒 Cryptographic event integrity (HMAC-SHA256, AES-256-GCM)
+- 🏷️ Full trigger attribution — who prompted what, when, and why
+- 🧹 Built-in data redaction before events leave the host
+- ☁️ **Powered by Google SecOps (Chronicle)** — the same enterprise SIEM trusted by security teams worldwide
+
+> Shield is designed to complement the security controls built into OpenClaw and any Claw-based solution — not replace them. Zero-trust policies, sandboxed execution, and private routing control what your agent *can* do. Shield adds what they can't: a continuous forensic record of what it *did*, with behavioral detection and automated case management on top.
+>
+> Works alongside any hardening strategy, out of the box.
+> *For example, solutions like NemoClaw control the perimeter. Shield owns the forensics.*
+
+---
 
 **Shield is a local collector.** It captures agent activity, redacts sensitive data, and forwards clean telemetry to the UPX platform at [uss.upx.com](https://uss.upx.com) — where security rules, correlation, alerting, playbooks, and case management give your team full visibility. The plugin itself stays lean and transparent; all the heavy lifting happens on the platform side.
 
 ```
-Your Agent → Shield (local: capture + redact) → UPX Platform (analysis, alerts, detections)
+Your Agent → Shield (local: capture + redact) → UPX Platform → Google SecOps (detection, cases, forensics)
 ```
 
 ---
@@ -176,6 +193,8 @@ openclaw gateway restart
 
 ## What to expect after activation
 
+Shield's agent skill communicates with you in your language. Alerts, case summaries, and recommendations are presented in whichever language you use — raw command output and technical identifiers (rule names, case IDs, field names) are always kept as-is.
+
 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:
@@ -183,41 +202,39 @@ Run `openclaw shield status` to confirm:
 **Just activated (first minute):**
 
 ```
-OpenClaw Shield — v0.3.x  (5s ago)
+OpenClaw Shield — v0.8.x  (5s ago)
 
-── Plugin Health ─────────────────────────────
-  Connection:   ✅ Connected
-  Version:      0.3.x
+── Status ────────────────────────────────────
+  ✅ Running · Connected
+  Version:      0.8.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
+
+── Monitoring ────────────────────────────────
+  Events:       3 sent · 0 quarantined
+  Failures:     0 poll · 0 telemetry
+  Session:      0m active
+  Last data:    poll 5s ago · capture 5s ago
 ```
 
-A low event count and a recent `Last capture` time means Shield is working correctly. Events accumulate as your agent uses tools.
+A low event count and a recent `Last data` 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.x  (5s ago)
+OpenClaw Shield — v0.8.x  (5s ago)
 
-── Plugin Health ─────────────────────────────
-  Connection:   ✅ Connected
-  Version:      0.3.x
+── Status ────────────────────────────────────
+  ✅ Running · Connected
+  Version:      0.8.x
   Instance:     a1b2c3d4…
-  Last poll:    5s ago
-  Last capture: 14s ago
-  Events sent:  1,842  (all-time)
-  Quarantine:   0  (all-time)
-  Failures:     0  (consecutive)
-  Daemon PID:   12345
-  Session:      4h 12m
+
+── Monitoring ────────────────────────────────
+  Events:       1,842 sent · 0 quarantined
+  Failures:     0 poll · 0 telemetry
+  Session:      4h 12m active
+  Last data:    poll 5s ago · capture 14s ago
 
 ── Activity ──────────────────────────────────
 
@@ -238,7 +255,7 @@ OpenClaw Shield — v0.3.x  (5s ago)
 **When not activated:**
 
 ```
-OpenClaw Shield — v0.3.x
+OpenClaw Shield — v0.8.x
 
   Status: Loaded (not activated)
 
@@ -473,7 +490,7 @@ When `autoUpdate` is `true`, Shield backs up the current version before installi
 → Increase poll interval: `"pollIntervalMs": 60000` in plugin config (default: 30000ms)
 
 **Cursor file issues**
-→ To reset: `rm ~/.openclaw/shield/data/cursors.json` — Shield reinitializes on next poll
+→ To reset: `rm ~/.openclaw/shield/data/cursor.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
@@ -507,10 +524,10 @@ See CHANGELOG.md included with the plugin.
 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**
+2. Pause delivery and retain cursor position so events can be retried after service is restored
 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.
+Renew your subscription at [uss.upx.com](https://uss.upx.com) and restart the gateway to resume delivery.
 
 ---
 

package/dist/index.d.ts

@@ -21,7 +21,7 @@ interface StatusWarningInput {
 }
 export declare function getStatusWarnings(input: StatusWarningInput): string[];
 interface OpenClawPluginAPI {
-    config?: Record<string, unknown>;
+    config?: OpenClawConfig;
     pluginConfig?: Record<string, unknown>;
     logger: {
         info(msg: string): void;
@@ -42,7 +42,70 @@ interface OpenClawPluginAPI {
     }) => void, opts?: {
         commands: string[];
     }): void;
+    runtime?: OpenClawRuntime;
+    registerCommand?: (definition: {
+        name: string;
+        description: string;
+        requireAuth?: boolean;
+        handler: () => {
+            text: string;
+        } | Promise<{
+            text: string;
+        }>;
+    }) => void;
 }
+interface OpenClawSystemRuntime {
+    enqueueSystemEvent?: (text: string, options: {
+        sessionKey: string;
+        contextKey?: string | null;
+    }) => boolean;
+    requestHeartbeatNow?: (opts?: {
+        reason?: string;
+        agentId?: string;
+        sessionKey?: string;
+    }) => void;
+}
+interface OpenClawChannelRuntime {
+    telegram?: {
+        sendMessageTelegram?: (to: string, text: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    };
+    discord?: {
+        sendMessageDiscord?: (to: string, text: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    };
+    whatsapp?: {
+        sendMessageWhatsApp?: (to: string, text: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    };
+    slack?: {
+        sendMessageSlack?: (to: string, text: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    };
+    signal?: {
+        sendMessageSignal?: (to: string, text: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    };
+}
+interface OpenClawRuntime {
+    system?: OpenClawSystemRuntime;
+    channel?: OpenClawChannelRuntime;
+}
+interface OpenClawAgentConfig {
+    default?: string;
+}
+interface OpenClawChannelAccountConfig {
+    enabled?: boolean;
+    allowFrom?: string[];
+    defaultTo?: string;
+}
+interface OpenClawChannelsConfig {
+    telegram?: OpenClawChannelAccountConfig;
+    discord?: OpenClawChannelAccountConfig;
+    whatsapp?: OpenClawChannelAccountConfig;
+    slack?: OpenClawChannelAccountConfig;
+    signal?: OpenClawChannelAccountConfig;
+}
+interface OpenClawConfig {
+    agents?: OpenClawAgentConfig;
+    channels?: OpenClawChannelsConfig;
+}
+export declare function _resetForTesting(): void;
 declare const _default: {
     id: string;
     name: string;