@better_openclaw/betterclaw 1.4.0

package/README.md

@@ -0,0 +1,125 @@
+<p align="center">
+  <img src="docs/banner.png" alt="BetterClaw" width="100%" />
+</p>
+
+<p align="center">
+  <em>OpenClaw plugin for the BetterClaw iOS app</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@betterclaw-app/betterclaw"><img src="https://img.shields.io/npm/v/@betterclaw-app/betterclaw?style=flat-square&color=blue" alt="npm version" /></a>
+  <a href="https://github.com/BetterClaw-app/betterclaw/blob/main/LICENSE"><img src="https://img.shields.io/github/license/BetterClaw-app/betterclaw?style=flat-square" alt="license" /></a>
+  <a href="https://www.npmjs.com/package/@betterclaw-app/betterclaw"><img src="https://img.shields.io/npm/dm/@betterclaw-app/betterclaw?style=flat-square&color=green" alt="downloads" /></a>
+  <a href="https://openclaw.dev"><img src="https://img.shields.io/badge/platform-OpenClaw-orange?style=flat-square" alt="OpenClaw" /></a>
+</p>
+
+---
+
+## What is this?
+
+This is the server-side plugin for [BetterClaw](https://github.com/BetterClaw-app/BetterClaw-ios), an iOS app that connects your iPhone's sensors to your [OpenClaw](https://openclaw.dev) AI agent. The app streams device events (location, battery, health, geofences) to your gateway — this plugin decides what to do with them.
+
+Without this plugin, raw events go straight to your agent. With it, they're filtered, triaged, and enriched before anything reaches your agent's conversation.
+
+```
+  BetterClaw iOS App          This Plugin (on gateway)              Agent
+ ──────────────────          ────────────────────────             ────────
+                                       │
+  battery ──────▶  ┌───────────────────┼───────────────────┐
+  location ─────▶  │  Rules Engine     │  Context Store     │
+  health ───────▶  │  LLM Triage       │  Pattern Engine    │ ──▶  filtered events
+  geofence ─────▶  │  Budget Limiter   │  Proactive Triggers│      + full context
+                   └───────────────────┼───────────────────┘
+                                       │
+                                 proactive insights
+                              (low battery + away from
+                               home, sleep deficit, etc.)
+```
+
+## Features
+
+- **Smart Filtering** — Per-source dedup, cooldown windows, and a daily push budget prevent event spam
+- **LLM Triage** — Ambiguous events get a cheap LLM call to decide push vs. suppress, keeping the expensive agent focused
+- **Device Context** — Rolling state snapshot: battery, GPS, zone occupancy, health metrics, activity classification
+- **Pattern Recognition** — Computes location routines, health trends (7d/30d baselines), and event stats every 6 hours
+- **Proactive Insights** — Combined-signal triggers: low battery away from home, unusual inactivity, sleep deficit, routine deviations, weekly digest
+- **Agent Tool** — `get_context` tool lets your agent read the full device snapshot on demand
+
+## Requirements
+
+- [BetterClaw iOS app](https://github.com/BetterClaw-app/BetterClaw-ios) installed and connected to your gateway
+- [OpenClaw](https://openclaw.dev) gateway (2025.12+)
+
+## Install
+
+```bash
+openclaw plugins install @betterclaw-app/betterclaw
+```
+
+## Configure
+
+Add to your `openclaw.json`:
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "betterclaw": {
+        "enabled": true,
+        "config": {
+          "llmModel": "openai/gpt-4o-mini",
+          "pushBudgetPerDay": 10,
+          "patternWindowDays": 14,
+          "proactiveEnabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+All config keys are optional — defaults are shown above.
+
+### Config Reference
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `llmModel` | `openai/gpt-4o-mini` | Model used for ambiguous event triage |
+| `pushBudgetPerDay` | `10` | Max events forwarded to the agent per day |
+| `patternWindowDays` | `14` | Days of event history used for pattern computation |
+| `proactiveEnabled` | `true` | Enable proactive combined-signal insights |
+
+## How It Works
+
+### Event Pipeline
+
+Every device event from the BetterClaw app goes through a multi-stage pipeline before reaching your agent:
+
+1. **Rules Engine** — Checks dedup, cooldown timers, and daily budget. Obvious spam is dropped immediately.
+2. **LLM Triage** — Events that aren't clearly push or suppress get a fast LLM call with device context for a judgment call.
+3. **Context Update** — The device context store is updated with the latest sensor data regardless of whether the event is forwarded.
+4. **Event Logging** — Every event and its decision (push/suppress/defer) is logged for pattern computation.
+5. **Agent Injection** — Events that pass are injected into the agent's main session with formatted context.
+
+### Background Services
+
+Two engines run on a schedule in the background:
+
+- **Pattern Engine** (every 6h) — Analyzes event history to compute location routines, health trends, and event frequency stats
+- **Proactive Engine** (every 30min) — Evaluates combined-signal conditions and fires insights when thresholds are met
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/bc` | Show current device context snapshot in chat |
+
+## Compatibility
+
+| Plugin | BetterClaw iOS | OpenClaw |
+|--------|----------------|----------|
+| 1.x    | 1.x+           | 2025.12+ |
+
+## License
+
+[AGPL-3.0](LICENSE) — Free to use, modify, and self-host. Derivative works must remain open source.

package/openclaw-plugin-sdk.md

@@ -0,0 +1,38 @@
+# OpenClaw Plugin SDK — What Plugins Can and Cannot Do
+
+## No LLM/Agent Access from Plugins
+
+Plugins **cannot** invoke LLMs or spawn agent sessions. This was discovered through deep investigation of the OpenClaw source code and plugin SDK.
+
+### What we tried
+- `runEmbeddedPiAgent` — an internal OpenClaw function used by the core agent. Both betteremail and betterclaw plugins tried to import it via `openclaw/agents/pi-embedded`. This **does not work** because it's not exported in the plugin SDK.
+
+### Why it doesn't work
+- The plugin SDK (`openclaw/plugin-sdk`) only exports a limited surface:
+  - `OpenClawPluginApi` — the `api` object passed to `register()`
+  - `openclaw/plugin-sdk/llm-task` — exists as an export path but provides no agent invocation
+- `openclaw/agents/*` is **not an exported path** — the import fails at runtime via Jiti (TypeScript loader)
+- `runEmbeddedPiAgent` is internal to OpenClaw's agent system and intentionally not exposed to plugins
+- The betterclaw plugin has the **exact same bug** — it also imports `runEmbeddedPiAgent` and has never successfully run its judgment layer
+
+### What plugins CAN do
+- `api.registerTool()` — expose tools to the agent (with optional `{ optional: true }` flag)
+- `api.registerService()` — run background services (polling loops, etc.)
+- `api.registerCommand()` — add `/commands` to the chat UI
+- `api.runtime.system.runCommandWithTimeout()` — run shell commands (including `gog`, `openclaw` CLI)
+- `api.runtime.state.resolveStateDir()` — get persistent state directory
+- `api.pluginConfig` — read plugin config from openclaw.yaml
+- `api.logger` — structured logging
+
+### What plugins CANNOT do
+- Invoke LLMs or create agent sessions
+- Import internal OpenClaw modules outside the plugin SDK exports
+- Access `runEmbeddedPiAgent` or any agent runtime internals
+- Run embedded "sub-agents" for classification or judgment
+
+### The solution we adopted
+Instead of classifying emails in the plugin, we removed the classifier entirely and made the plugin a **pure stateful memory layer**. All emails enter the digest, and the agent triages them during cron-triggered sessions with full context (memory, skills, user preferences). This is actually better because:
+1. The agent has full context for triage decisions
+2. No separate LLM invocation cost
+3. Simpler architecture — the plugin just tracks state
+4. Cron job runs in isolated session, only notifies main session when something matters

package/openclaw.plugin.json

@@ -0,0 +1,34 @@
+{
+  "id": "betterclaw",
+  "name": "BetterClaw Context",
+  "description": "Intelligent context layer for BetterClaw iOS companion app",
+  "version": "1.0.3",
+  "skills": ["./skills/betterclaw"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "llmModel": {
+        "type": "string",
+        "default": "openai/gpt-4o-mini"
+      },
+      "pushBudgetPerDay": {
+        "type": "number",
+        "default": 10
+      },
+      "patternWindowDays": {
+        "type": "number",
+        "default": 14
+      },
+      "proactiveEnabled": {
+        "type": "boolean",
+        "default": true
+      }
+    }
+  },
+  "uiHints": {
+    "llmModel": { "label": "Triage LLM Model", "placeholder": "openai/gpt-4o-mini" },
+    "pushBudgetPerDay": { "label": "Max pushes per day" },
+    "proactiveEnabled": { "label": "Enable proactive insights" }
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@better_openclaw/betterclaw",
+  "version": "1.4.0",
+  "description": "Intelligent event filtering, context tracking, and proactive triggers for BetterClaw",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BetterClaw-app/betterclaw.git"
+  },
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./src/index.ts"]
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  }
+}

package/skills/betterclaw/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: BetterClaw Device Context
+description: Instructions for handling physical device events and context from BetterClaw iOS
+---
+
+# BetterClaw Device Context
+
+You have access to the user's physical device state via BetterClaw (iOS companion app).
+
+## Capabilities
+
+- **Real-time sensors**: battery level/state, GPS location, health metrics (steps, heart rate, HRV, sleep, distance, energy)
+- **Geofence events**: enter/exit named zones (Home, Office, etc.)
+- **Patterns**: location routines, health trends (7d/30d), battery drain rate
+- **Tool**: `get_context` — call anytime to read the full current device snapshot and derived patterns
+
+## Event Messages
+
+You'll receive two types of automated messages:
+
+- **Device events** — prefixed with `[BetterClaw device event]`. These are real sensor events that passed the plugin's filtering pipeline. They include relevant context.
+- **Proactive insights** — prefixed with `[BetterClaw proactive insight]`. These are combined-signal analyses (e.g., low battery + away from home, unusual inactivity, sleep deficit).
+
+## Guidelines
+
+- Events are pre-filtered for relevance. If you receive one, it's likely worth acknowledging.
+- Use `get_context` proactively when physical context would improve your response (weather questions, schedule planning, health discussions).
+- Don't parrot raw data. Synthesize naturally: "You're running low and away from home" not "Battery: 0.15, location label: null".
+- Proactive insights are observations, not commands. Use your judgment about whether to relay them to the user.
+- When the user asks about their health, location, battery, or activity — call `get_context` first rather than relying on stale event data.
+- Respond with `no_reply` for routine events that don't need user attention (e.g., geofence enter at expected time).

package/src/context.ts

@@ -0,0 +1,219 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { DeviceContext, DeviceEvent, Patterns } from "./types.js";
+
+const CONTEXT_FILE = "context.json";
+const PATTERNS_FILE = "patterns.json";
+
+export class ContextManager {
+  private contextPath: string;
+  private patternsPath: string;
+  private context: DeviceContext;
+
+  constructor(stateDir: string) {
+    this.contextPath = path.join(stateDir, CONTEXT_FILE);
+    this.patternsPath = path.join(stateDir, PATTERNS_FILE);
+    this.context = ContextManager.empty();
+  }
+
+  static empty(): DeviceContext {
+    return {
+      device: { battery: null, location: null, health: null },
+      activity: {
+        currentZone: null,
+        zoneEnteredAt: null,
+        lastTransition: null,
+        isStationary: true,
+        stationarySince: null,
+      },
+      meta: {
+        lastEventAt: 0,
+        eventsToday: 0,
+        lastAgentPushAt: 0,
+        pushesToday: 0,
+      },
+    };
+  }
+
+  async load(): Promise<void> {
+    try {
+      const raw = await fs.readFile(this.contextPath, "utf8");
+      this.context = JSON.parse(raw) as DeviceContext;
+    } catch {
+      this.context = ContextManager.empty();
+    }
+  }
+
+  get(): DeviceContext {
+    return this.context;
+  }
+
+  async save(): Promise<void> {
+    await fs.mkdir(path.dirname(this.contextPath), { recursive: true });
+    await fs.writeFile(this.contextPath, JSON.stringify(this.context, null, 2) + "\n", "utf8");
+  }
+
+  updateFromEvent(event: DeviceEvent): void {
+    const now = event.firedAt;
+    const data = event.data;
+
+    // Reset daily counters at midnight UTC
+    const lastDay = Math.floor(this.context.meta.lastEventAt / 86400);
+    const currentDay = Math.floor(now / 86400);
+    if (lastDay !== currentDay && this.context.meta.lastEventAt > 0) {
+      this.context.meta.eventsToday = 0;
+      this.context.meta.pushesToday = 0;
+    }
+
+    this.context.meta.lastEventAt = now;
+    this.context.meta.eventsToday++;
+
+    switch (event.source) {
+      case "device.battery":
+        this.context.device.battery = {
+          level: data.level ?? this.context.device.battery?.level ?? 0,
+          state: this.context.device.battery?.state ?? "unknown",
+          isLowPowerMode: (data.isLowPowerMode ?? 0) === 1,
+          updatedAt: data.updatedAt ?? now,
+        };
+        break;
+
+      case "geofence.triggered": {
+        const type = data.type === 1 ? "enter" : "exit";
+        const zoneName = event.metadata?.zoneName ?? null;
+        const prevZone = this.context.activity.currentZone;
+
+        if (type === "enter") {
+          this.context.activity.lastTransition = {
+            from: prevZone,
+            to: zoneName,
+            at: now,
+          };
+          this.context.activity.currentZone = zoneName;
+          this.context.activity.zoneEnteredAt = now;
+          this.context.activity.isStationary = true;
+          this.context.activity.stationarySince = now;
+        } else if (type === "exit") {
+          this.context.activity.lastTransition = {
+            from: prevZone,
+            to: null,
+            at: now,
+          };
+          this.context.activity.currentZone = null;
+          this.context.activity.zoneEnteredAt = null;
+          this.context.activity.isStationary = false;
+          this.context.activity.stationarySince = null;
+        }
+
+        this.context.device.location = {
+          latitude: data.latitude ?? this.context.device.location?.latitude ?? 0,
+          longitude: data.longitude ?? this.context.device.location?.longitude ?? 0,
+          horizontalAccuracy: this.context.device.location?.horizontalAccuracy ?? 0,
+          label: this.context.activity.currentZone,
+          updatedAt: data.timestamp ?? now,
+        };
+        break;
+      }
+
+      default:
+        if (event.source.startsWith("health")) {
+          this.context.device.health = {
+            stepsToday: data.stepsToday ?? this.context.device.health?.stepsToday ?? null,
+            distanceMeters: data.distanceMeters ?? this.context.device.health?.distanceMeters ?? null,
+            heartRateAvg: data.heartRateAvg ?? this.context.device.health?.heartRateAvg ?? null,
+            restingHeartRate: data.restingHeartRate ?? this.context.device.health?.restingHeartRate ?? null,
+            hrv: data.hrv ?? this.context.device.health?.hrv ?? null,
+            activeEnergyKcal: data.activeEnergyKcal ?? this.context.device.health?.activeEnergyKcal ?? null,
+            sleepDurationSeconds: data.sleepDurationSeconds ?? this.context.device.health?.sleepDurationSeconds ?? null,
+            updatedAt: data.updatedAt ?? now,
+          };
+        }
+        break;
+    }
+  }
+
+  applySnapshot(snapshot: {
+    battery?: { level: number; state: string; isLowPowerMode: boolean };
+    location?: { latitude: number; longitude: number };
+    health?: {
+      stepsToday?: number; distanceMeters?: number; heartRateAvg?: number;
+      restingHeartRate?: number; hrv?: number; activeEnergyKcal?: number;
+      sleepDurationSeconds?: number;
+    };
+    geofence?: { type: string; zoneName: string; latitude: number; longitude: number };
+  }): void {
+    const now = Date.now() / 1000;
+
+    if (snapshot.battery) {
+      this.context.device.battery = {
+        level: snapshot.battery.level,
+        state: snapshot.battery.state,
+        isLowPowerMode: snapshot.battery.isLowPowerMode,
+        updatedAt: now,
+      };
+    }
+
+    if (snapshot.location) {
+      this.context.device.location = {
+        latitude: snapshot.location.latitude,
+        longitude: snapshot.location.longitude,
+        horizontalAccuracy: 0,
+        label: this.context.activity.currentZone,
+        updatedAt: now,
+      };
+    }
+
+    if (snapshot.health) {
+      this.context.device.health = {
+        stepsToday: snapshot.health.stepsToday ?? null,
+        distanceMeters: snapshot.health.distanceMeters ?? null,
+        heartRateAvg: snapshot.health.heartRateAvg ?? null,
+        restingHeartRate: snapshot.health.restingHeartRate ?? null,
+        hrv: snapshot.health.hrv ?? null,
+        activeEnergyKcal: snapshot.health.activeEnergyKcal ?? null,
+        sleepDurationSeconds: snapshot.health.sleepDurationSeconds ?? null,
+        updatedAt: now,
+      };
+    }
+
+    if (snapshot.geofence) {
+      const prevZone = this.context.activity.currentZone;
+      if (snapshot.geofence.type === "enter") {
+        this.context.activity.currentZone = snapshot.geofence.zoneName;
+        this.context.activity.zoneEnteredAt = now;
+        this.context.activity.isStationary = true;
+        this.context.activity.stationarySince = now;
+        this.context.activity.lastTransition = { from: prevZone, to: snapshot.geofence.zoneName, at: now };
+      } else {
+        this.context.activity.currentZone = null;
+        this.context.activity.zoneEnteredAt = null;
+        this.context.activity.isStationary = false;
+        this.context.activity.stationarySince = null;
+        this.context.activity.lastTransition = { from: prevZone, to: null, at: now };
+      }
+
+      if (this.context.device.location) {
+        this.context.device.location.label = this.context.activity.currentZone;
+      }
+    }
+  }
+
+  recordPush(): void {
+    this.context.meta.lastAgentPushAt = Date.now() / 1000;
+    this.context.meta.pushesToday++;
+  }
+
+  async readPatterns(): Promise<Patterns | null> {
+    try {
+      const raw = await fs.readFile(this.patternsPath, "utf8");
+      return JSON.parse(raw) as Patterns;
+    } catch {
+      return null;
+    }
+  }
+
+  async writePatterns(patterns: Patterns): Promise<void> {
+    await fs.mkdir(path.dirname(this.patternsPath), { recursive: true });
+    await fs.writeFile(this.patternsPath, JSON.stringify(patterns, null, 2) + "\n", "utf8");
+  }
+}

package/src/events.ts

@@ -0,0 +1,67 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { EventLogEntry } from "./types.js";
+
+const EVENTS_FILE = "events.jsonl";
+const MAX_LINES = 10_000;
+const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+export class EventLog {
+  private filePath: string;
+
+  constructor(stateDir: string) {
+    this.filePath = path.join(stateDir, EVENTS_FILE);
+  }
+
+  async append(entry: EventLogEntry): Promise<void> {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    const line = JSON.stringify(entry) + "\n";
+    await fs.appendFile(this.filePath, line, "utf8");
+  }
+
+  async readAll(): Promise<EventLogEntry[]> {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf8");
+      return raw
+        .trim()
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line) as EventLogEntry);
+    } catch {
+      return [];
+    }
+  }
+
+  async readRecent(limit: number = 20): Promise<EventLogEntry[]> {
+    const all = await this.readAll();
+    return all.slice(-limit);
+  }
+
+  async readSince(sinceEpoch: number): Promise<EventLogEntry[]> {
+    const all = await this.readAll();
+    return all.filter((e) => e.timestamp >= sinceEpoch);
+  }
+
+  async rotate(): Promise<number> {
+    const entries = await this.readAll();
+    if (entries.length <= MAX_LINES) return 0;
+
+    const cutoff = Date.now() / 1000 - MAX_AGE_MS / 1000;
+    const kept = entries.filter((e) => e.timestamp >= cutoff).slice(-MAX_LINES);
+    const removed = entries.length - kept.length;
+
+    const content = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    await fs.writeFile(this.filePath, content, "utf8");
+
+    return removed;
+  }
+
+  async count(): Promise<number> {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf8");
+      return raw.trim().split("\n").filter((l) => l.length > 0).length;
+    } catch {
+      return 0;
+    }
+  }
+}

package/src/filter.ts

@@ -0,0 +1,93 @@
+import type { DeviceContext, DeviceEvent, FilterDecision } from "./types.js";
+
+// Cooldowns in seconds
+const DEDUP_COOLDOWN: Record<string, number> = {
+  "default.battery-low": 3600,
+  "default.battery-critical": 1800,
+  "default.daily-health": 82800, // 23 hours
+  "default.geofence": 300,
+};
+
+const DEFAULT_COOLDOWN = 1800; // 30 minutes
+
+export class RulesEngine {
+  private lastFired: Map<string, number> = new Map();
+  private pushBudget: number;
+
+  constructor(pushBudget: number = 10) {
+    this.pushBudget = pushBudget;
+  }
+
+  evaluate(event: DeviceEvent, context: DeviceContext): FilterDecision {
+    // Debug events always pass
+    if (event.data._debugFired === 1.0) {
+      return { action: "push", reason: "debug event — always push" };
+    }
+
+    // Dedup check
+    const lastFiredAt = this.lastFired.get(event.subscriptionId);
+    const cooldown = DEDUP_COOLDOWN[event.subscriptionId] ?? DEFAULT_COOLDOWN;
+    if (lastFiredAt && event.firedAt - lastFiredAt < cooldown) {
+      return {
+        action: "drop",
+        reason: `dedup: ${event.subscriptionId} fired ${Math.round(event.firedAt - lastFiredAt)}s ago (cooldown: ${cooldown}s)`,
+      };
+    }
+
+    // Critical battery — always push
+    if (event.subscriptionId === "default.battery-critical") {
+      return { action: "push", reason: "critical battery — always push" };
+    }
+
+    // Geofence — always push
+    if (event.source === "geofence.triggered") {
+      return { action: "push", reason: "geofence event — always push" };
+    }
+
+    // Battery low — check if level changed since last push
+    if (event.subscriptionId === "default.battery-low") {
+      const currentLevel = event.data.level;
+      const lastLevel = context.device.battery?.level;
+      if (
+        lastLevel !== undefined &&
+        currentLevel !== undefined &&
+        Math.abs(currentLevel - lastLevel) < 0.02
+      ) {
+        return { action: "drop", reason: "battery-low: level unchanged since last push" };
+      }
+      return { action: "push", reason: "battery low — level changed" };
+    }
+
+    // Daily health — check time window
+    if (event.subscriptionId === "default.daily-health") {
+      const hour = new Date(event.firedAt * 1000).getHours();
+      // Preferred window: 6am-10am
+      if (hour >= 6 && hour <= 10) {
+        return { action: "push", reason: "daily health summary — within morning window" };
+      }
+      return { action: "defer", reason: "daily health summary — outside morning window" };
+    }
+
+    // Push budget check
+    if (context.meta.pushesToday >= this.pushBudget) {
+      return { action: "drop", reason: `push budget exhausted (${context.meta.pushesToday}/${this.pushBudget} today)` };
+    }
+
+    // Anything else is ambiguous — forward to LLM judgment
+    return { action: "ambiguous", reason: "no rule matched — forward to LLM judgment" };
+  }
+
+  recordFired(subscriptionId: string, firedAt: number): void {
+    this.lastFired.set(subscriptionId, firedAt);
+  }
+
+  /** Restore cooldown state (call on load) */
+  restoreCooldowns(entries: Array<{ subscriptionId: string; firedAt: number }>): void {
+    for (const { subscriptionId, firedAt } of entries) {
+      const existing = this.lastFired.get(subscriptionId);
+      if (!existing || firedAt > existing) {
+        this.lastFired.set(subscriptionId, firedAt);
+      }
+    }
+  }
+}