wolverine-ai 6.3.0 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Self-healing Node.js server framework powered by AI. Catches crashes, diagnoses errors, generates fixes, verifies, and restarts — automatically.",
   "main": "src/index.js",
   "bin": {

package/src/claw/wolverine-api.js

@@ -0,0 +1,443 @@
+/**
+ * Wolverine API — unified entry point for any OpenClaw process.
+ *
+ * Exposes every wolverine subsystem through a single, lazy-loaded API.
+ * Nothing is imported until first use, so requiring this module is free.
+ *
+ * Usage from any OpenClaw skill, plugin, or agent:
+ *   const wolverine = require("wolverine-ai/src/claw/wolverine-api");
+ *   const api = wolverine.init("/path/to/project");
+ *
+ *   // Security
+ *   api.security.detectInjection("some user input");
+ *   api.security.redact("text with sk-abc123 key");
+ *   api.security.sandbox.resolve("server/index.js");
+ *
+ *   // Brain
+ *   await api.brain.search("how to fix ECONNREFUSED");
+ *   await api.brain.learn("Redis needs REDIS_URL env var", "fix");
+ *
+ *   // AI
+ *   const result = await api.ai.call({ model: "claude-sonnet-4-6", ... });
+ *
+ *   // Errors
+ *   api.errors.parse(stderrText);
+ *   api.errors.classify(errorMessage);
+ *   api.errors.routeTools("ECONNREFUSED");
+ *
+ *   // Backup
+ *   api.backup.create("before risky change");
+ *   api.backup.rollbackLatest();
+ *
+ *   // ... etc
+ */
+
+const path = require("path");
+
+let _projectRoot = null;
+let _initialized = false;
+
+// Lazy singletons — created on first access
+const _cache = {};
+
+function _require(relativePath) {
+  return require(path.join(_projectRoot, relativePath));
+}
+
+function _lazy(key, factory) {
+  if (!_cache[key]) _cache[key] = factory();
+  return _cache[key];
+}
+
+// ── Public API ──────────────────────────────────────────────────
+
+/**
+ * Initialize the Wolverine API for a project.
+ * Call once — returns the API object. Subsequent calls return the same instance.
+ */
+function init(projectRoot) {
+  if (_initialized && _projectRoot === path.resolve(projectRoot)) return api;
+  _projectRoot = path.resolve(projectRoot);
+  _initialized = true;
+
+  // Clear cache if re-initializing with different root
+  for (const key of Object.keys(_cache)) delete _cache[key];
+
+  return api;
+}
+
+const api = {
+  // ── Security ────────────────────────────────────────────────
+
+  get security() {
+    return _lazy("security", () => {
+      const { detectInjection, localScan, INJECTION_PATTERNS } = _require("src/security/injection-detector");
+      const { initRedactor, redact, redactObj, hasSecrets } = _require("src/security/secret-redactor");
+      const { Sandbox } = _require("src/security/sandbox");
+      const { RateLimiter } = _require("src/security/rate-limiter");
+
+      // Initialize redactor for this project
+      const redactor = initRedactor(_projectRoot);
+
+      return {
+        // Prompt injection detection (~50 patterns)
+        detectInjection,
+        localScan,
+        INJECTION_PATTERNS,
+
+        // Secret redaction
+        redact,
+        redactObj,
+        hasSecrets,
+        redactor,
+
+        // File sandbox
+        sandbox: new Sandbox(_projectRoot),
+        Sandbox,
+
+        // Rate limiting
+        createRateLimiter: (opts) => new RateLimiter(opts),
+        RateLimiter,
+      };
+    });
+  },
+
+  // ── Brain (semantic memory) ─────────────────────────────────
+
+  get brain() {
+    return _lazy("brain", () => {
+      const { Brain } = _require("src/brain/brain");
+      const { VectorStore } = _require("src/brain/vector-store");
+      const { embed, embedBatch, compact, compactAndEmbed } = _require("src/brain/embedder");
+      const { scanProject, mapToChunks } = _require("src/brain/function-map");
+      const { route, getRoutePrompt, TOOL_ROUTES } = _require("src/brain/tool-router");
+
+      const brain = new Brain(_projectRoot);
+      let _initPromise = null;
+
+      return {
+        // High-level brain operations
+        async search(query, opts) {
+          if (!_initPromise) _initPromise = brain.init();
+          await _initPromise;
+          return brain.search ? brain.search(query, opts)
+            : brain.recall ? brain.recall(query, opts)
+            : [];
+        },
+        async learn(content, category) {
+          if (!_initPromise) _initPromise = brain.init();
+          await _initPromise;
+          if (brain.addDocument) {
+            return brain.addDocument({ content, namespace: category || "learnings", source: "wolverine-claw", timestamp: Date.now() });
+          }
+          if (brain.remember) return brain.remember(content, { namespace: category });
+        },
+        async getContext(query) {
+          if (!_initPromise) _initPromise = brain.init();
+          await _initPromise;
+          return brain.getContext ? brain.getContext(query) : "";
+        },
+        async init() {
+          if (!_initPromise) _initPromise = brain.init();
+          return _initPromise;
+        },
+
+        // Low-level access
+        instance: brain,
+        VectorStore,
+        embed,
+        embedBatch,
+        compact,
+        compactAndEmbed,
+        scanProject,
+        mapToChunks,
+
+        // Tool router — maps error types to tool chains
+        routeTools: route,
+        getRoutePrompt,
+        TOOL_ROUTES,
+      };
+    });
+  },
+
+  // ── AI Client ───────────────────────────────────────────────
+
+  get ai() {
+    return _lazy("ai", () => {
+      const client = _require("src/core/ai-client");
+      const { getModel, getEmbeddingModel, getModelConfig, detectProvider, MODEL_ROLES } = _require("src/core/models");
+
+      return {
+        // Make AI calls (auto-detects provider from model name)
+        call: client.aiCall,
+        callWithHistory: client.aiCallWithHistory,
+
+        // Embeddings
+        embed: async (text) => {
+          const { embed } = _require("src/brain/embedder");
+          return embed(text);
+        },
+
+        // Model utilities
+        getModel,
+        getEmbeddingModel,
+        getModelConfig,
+        detectProvider,
+        MODEL_ROLES,
+
+        // Token tracking
+        setTokenTracker: client.setTokenTracker,
+        getTrackerSnapshot: client.getTrackerSnapshot,
+      };
+    });
+  },
+
+  // ── Error Handling ──────────────────────────────────────────
+
+  get errors() {
+    return _lazy("errors", () => {
+      const { parseError, classifyError } = _require("src/core/error-parser");
+      const { route, getRoutePrompt } = _require("src/brain/tool-router");
+      const { Notifier, HUMAN_REQUIRED_PATTERNS } = _require("src/notifications/notifier");
+      const { LoopGuard } = _require("src/skills/loop-guard");
+
+      return {
+        // Parse error text → structured {file, line, message, errorType}
+        parse: parseError,
+        // Classify error → type (missing_module, syntax, runtime, etc.)
+        classify: classifyError,
+        // Map error type → recommended tool chain
+        routeTools: route,
+        getRoutePrompt,
+
+        // Detect if error needs human vs can be auto-fixed
+        HUMAN_REQUIRED_PATTERNS,
+        createNotifier: (opts) => new Notifier(opts),
+
+        // Loop detection — prevent infinite fix attempts
+        createLoopGuard: (opts) => new LoopGuard(_projectRoot, opts),
+      };
+    });
+  },
+
+  // ── Backup & Recovery ───────────────────────────────────────
+
+  get backup() {
+    return _lazy("backup", () => {
+      const { BackupManager } = _require("src/backup/backup-manager");
+      const manager = new BackupManager(_projectRoot);
+
+      return {
+        create: (reason) => manager.createBackup(reason),
+        rollback: (id) => manager.rollbackTo(id),
+        rollbackLatest: () => manager.rollbackLatest(),
+        undoRollback: () => manager.undoRollback(),
+        list: () => manager.list(),
+        getStats: () => manager.getStats(),
+        promote: (id) => manager.promote(id),
+        prune: () => manager.prune(),
+        instance: manager,
+      };
+    });
+  },
+
+  // ── Skills ──────────────────────────────────────────────────
+
+  get skills() {
+    return _lazy("skills", () => {
+      const { SkillRegistry } = _require("src/skills/skill-registry");
+      const registry = new SkillRegistry();
+      registry.load();
+
+      return {
+        // Skill registry
+        match: (query) => registry.match(query),
+        list: () => registry.getAll(),
+        registry,
+
+        // SQL injection protection
+        get sql() {
+          const { scanForInjection, deepScan, sqlGuard } = _require("src/skills/sql");
+          return { scanForInjection, deepScan, sqlGuard };
+        },
+
+        // Dependency analysis
+        get deps() {
+          const deps = _require("src/skills/deps");
+          return {
+            diagnose: deps.diagnose,
+            healthReport: deps.healthReport,
+            getMigration: deps.getMigration,
+          };
+        },
+
+        // Backup (alias)
+        get backup() {
+          const b = _require("src/skills/backup");
+          return { backup: b.backup, rollback: b.rollback, rollbackLatest: b.rollbackLatest, undoRollback: b.undoRollback, listBackups: b.listBackups };
+        },
+      };
+    });
+  },
+
+  // ── Monitoring ──────────────────────────────────────────────
+
+  get monitor() {
+    return _lazy("monitor", () => {
+      const { ErrorMonitor } = _require("src/monitor/error-monitor");
+      const { PerfMonitor } = _require("src/monitor/perf-monitor");
+      const { ProcessMonitor } = _require("src/monitor/process-monitor");
+      const { AdaptiveLimiter } = _require("src/monitor/adaptive-limiter");
+
+      return {
+        ErrorMonitor,
+        PerfMonitor,
+        ProcessMonitor,
+        AdaptiveLimiter,
+      };
+    });
+  },
+
+  // ── Logging & Metrics ───────────────────────────────────────
+
+  get logger() {
+    return _lazy("logger", () => {
+      const { EventLogger, EVENT_TYPES, SEVERITY } = _require("src/logger/event-logger");
+      const { TokenTracker } = _require("src/logger/token-tracker");
+      const { RepairHistory } = _require("src/logger/repair-history");
+
+      return {
+        createEventLogger: () => new EventLogger(_projectRoot),
+        createTokenTracker: () => new TokenTracker(_projectRoot),
+        createRepairHistory: () => new RepairHistory(_projectRoot),
+        EVENT_TYPES,
+        SEVERITY,
+      };
+    });
+  },
+
+  // ── Config ──────────────────────────────────────────────────
+
+  get config() {
+    return _lazy("config", () => {
+      const { loadConfig, getConfig } = _require("src/core/config");
+      return { load: loadConfig, get: getConfig };
+    });
+  },
+
+  // ── Agent Engine ────────────────────────────────────────────
+
+  get agent() {
+    return _lazy("agent", () => {
+      const { AgentEngine, TOOL_DEFINITIONS, BLOCKED_COMMANDS } = _require("src/agent/agent-engine");
+      const { Sandbox } = _require("src/security/sandbox");
+
+      return {
+        // Create a sandboxed agent engine
+        create: (opts = {}) => new AgentEngine({
+          cwd: opts.cwd || _projectRoot,
+          sandbox: opts.sandbox || new Sandbox(opts.cwd || _projectRoot),
+          maxTurns: opts.maxTurns || 25,
+          maxTokens: opts.maxTokens || 100000,
+          logger: opts.logger,
+          mcp: opts.mcp,
+        }),
+        TOOL_DEFINITIONS,
+        BLOCKED_COMMANDS,
+        AgentEngine,
+      };
+    });
+  },
+
+  // ── Server Context ──────────────────────────────────────────
+
+  get context() {
+    return _lazy("context", () => {
+      const { scan, load, getSummary } = _require("src/core/server-context");
+      return {
+        scan: () => scan(_projectRoot),
+        load: () => load(_projectRoot),
+        getSummary: () => getSummary(_projectRoot),
+      };
+    });
+  },
+
+  // ── Verification ────────────────────────────────────────────
+
+  get verify() {
+    return _lazy("verify", () => {
+      const { verifyFix, syntaxCheck, bootProbe } = _require("src/core/verifier");
+      return { verifyFix, syntaxCheck, bootProbe };
+    });
+  },
+
+  // ── MCP (Model Context Protocol) ───────────────────────────
+
+  get mcp() {
+    return _lazy("mcp", () => {
+      const { McpRegistry } = _require("src/mcp/mcp-registry");
+      return {
+        create: (opts = {}) => new McpRegistry({
+          projectRoot: _projectRoot,
+          ...opts,
+        }),
+        McpRegistry,
+      };
+    });
+  },
+
+  // ── Convenience: all-in-one scan ───────────────────────────
+
+  /**
+   * Run a fast security scan on text (regex injection + secrets). Sync, no AI call.
+   * For deep AI-powered injection scan, use api.security.detectInjection() (async).
+   * Returns { safe, injection, secrets, redacted }.
+   */
+  scanText(text) {
+    const sec = this.security;
+    const injectionResult = sec.localScan(text);
+    const hasSecretContent = sec.hasSecrets(text);
+    const redacted = sec.redact(text);
+
+    return {
+      safe: injectionResult.safe !== false && !hasSecretContent,
+      injection: injectionResult,
+      secrets: hasSecretContent,
+      redacted,
+    };
+  },
+
+  /**
+   * Diagnose an error: parse, classify, route tools, check if human-needed.
+   * Returns { parsed, type, tools, humanRequired }.
+   */
+  diagnoseError(errorText) {
+    const err = this.errors;
+    const parsed = err.parse(errorText);
+    const toolRoute = err.routeTools(parsed.errorType || "unknown");
+
+    // Check if human required
+    let humanRequired = false;
+    for (const pattern of err.HUMAN_REQUIRED_PATTERNS) {
+      if (pattern.test ? pattern.test(errorText) : errorText.includes(pattern)) {
+        humanRequired = true;
+        break;
+      }
+    }
+
+    return {
+      parsed,
+      type: parsed.errorType,
+      tools: toolRoute,
+      humanRequired,
+    };
+  },
+
+  /** Get the project root. */
+  get projectRoot() { return _projectRoot; },
+
+  /** Check if initialized. */
+  get initialized() { return _initialized; },
+};
+
+module.exports = { init, api };

package/wolverine-claw/plugins/wolverine-integration.js

@@ -1,14 +1,21 @@
 /**
  * Wolverine Integration Plugin for OpenClaw
  *
- * Gives the claw agent access to wolverine's self-healing capabilities:
- * - Brain: semantic memory, project context, and learning
- * - Backup: workspace snapshots and rollback
- * - Healing: error diagnosis and auto-fix pipeline
- * - Health: process monitoring and status reporting
+ * Two integration layers:
  *
- * This plugin registers as an OpenClaw skill/extension, adding wolverine-specific
- * tools to the agent's toolkit.
+ * 1. TOOLS — 7 wolverine tools injected into the agent toolkit
+ *    (backup, rollback, brain search/learn, health, self-heal)
+ *
+ * 2. HOOKS — taps into OpenClaw's 28-hook plugin system for deep
+ *    error observability and self-healing triggers:
+ *    - after_tool_call: catch skill/tool failures
+ *    - agent_end: catch agent crashes and timeouts
+ *    - before_tool_call: detect and report tool loops
+ *    - message_sent: catch channel send failures
+ *    - llm_output: catch provider errors, failovers, billing blocks
+ *    - subagent_ended: catch subagent failures
+ *    - gateway_start/gateway_stop: lifecycle tracking
+ *    - session_end: session error tracking
  */
 
 const path = require("path");
@@ -16,51 +23,348 @@ const fs = require("fs");
 
 const PLUGIN_NAME = "wolverine-integration";
 
+// ── Error tracking state ────────────────────────────────────────
+
+const _errorCounts = {
+  tool: 0,
+  agent: 0,
+  channel: 0,
+  llm: 0,
+  subagent: 0,
+  total: 0,
+};
+
+const _recentErrors = []; // last 50 errors for context
+const MAX_RECENT = 50;
+
+function _trackError(category, summary, detail) {
+  _errorCounts[category] = (_errorCounts[category] || 0) + 1;
+  _errorCounts.total++;
+
+  const entry = {
+    category,
+    summary: summary?.slice(0, 200),
+    timestamp: Date.now(),
+    detail: detail?.slice?.(0, 500),
+  };
+  _recentErrors.push(entry);
+  if (_recentErrors.length > MAX_RECENT) _recentErrors.shift();
+
+  return entry;
+}
+
+// ── Main registration ───────────────────────────────────────────
+
 /**
  * Register the wolverine integration with the OpenClaw gateway.
+ * Supports both Plugin SDK (api.registerPluginHook) and basic EventEmitter.
  */
 async function register(gateway, config) {
   const projectRoot = path.resolve(__dirname, "../..");
 
-  // Register wolverine tools as OpenClaw tools/skills
+  // Register wolverine tools
   const tools = buildWolverineTools(projectRoot, config);
+  _registerTools(gateway, tools);
 
-  if (gateway.registerTools) {
-    gateway.registerTools(PLUGIN_NAME, tools);
-  } else if (gateway.addTools) {
-    gateway.addTools(tools);
-  } else if (gateway.skills?.register) {
-    gateway.skills.register(PLUGIN_NAME, {
-      description: "Wolverine self-healing integration — backup, brain, and health tools",
-      tools,
-    });
-  }
-
-  // Hook into gateway events for self-healing
-  if (gateway.on) {
-    gateway.on("error", (err) => handleGatewayError(err, projectRoot));
-    gateway.on("agent:error", (err) => handleAgentError(err, projectRoot));
-    gateway.on("skill:error", (err) => handleSkillError(err, projectRoot));
+  // Register into OpenClaw Plugin SDK hooks (preferred)
+  const api = _getPluginApi(gateway);
+  if (api) {
+    _registerPluginHooks(api, projectRoot, config);
+    console.log("[CLAW] Wolverine plugin hooks registered (Plugin SDK)");
   }
+  // Also register EventEmitter hooks (fallback / additional coverage)
+  _registerEventHooks(gateway, projectRoot);
 
-  // Periodic health reporting
+  // Periodic health reporting with error stats
   const healthInterval = setInterval(() => {
     reportToWolverine("claw_heartbeat", {
       uptime: process.uptime(),
       memory: process.memoryUsage(),
+      errorCounts: { ..._errorCounts },
       timestamp: Date.now(),
     });
   }, 30000);
 
-  // Cleanup on shutdown
   if (gateway.on) {
     gateway.on("shutdown", () => clearInterval(healthInterval));
   }
 }
 
+// ── Plugin SDK Hooks ────────────────────────────────────────────
+
 /**
- * Build wolverine-specific tools for the OpenClaw agent.
+ * Get the Plugin SDK API from the gateway (if available).
  */
+function _getPluginApi(gateway) {
+  // OpenClaw exposes plugin registration via multiple paths
+  if (gateway.pluginApi) return gateway.pluginApi;
+  if (gateway.api) return gateway.api;
+  if (gateway.plugins?.api) return gateway.plugins.api;
+  if (typeof gateway.registerPluginHook === "function") return gateway;
+  return null;
+}
+
+/**
+ * Register all wolverine hooks into the OpenClaw Plugin SDK.
+ */
+function _registerPluginHooks(api, projectRoot, config) {
+  const registerHook = api.registerPluginHook || api.register;
+  if (typeof registerHook !== "function") return;
+
+  const reg = (name, handler, priority) => {
+    try {
+      registerHook.call(api, name, { handler, priority: priority || 100 });
+    } catch (e) {
+      // Hook not supported in this OpenClaw version — skip silently
+      try {
+        registerHook.call(api, name, handler);
+      } catch {}
+    }
+  };
+
+  // ── after_tool_call: catch skill and tool failures ──────────
+  reg("after_tool_call", (event, ctx) => {
+    if (!event) return;
+    const hasError = event.error || event.status === "error" || event.exitCode;
+
+    if (hasError) {
+      const toolName = event.toolName || event.name || "unknown";
+      const errorMsg = event.error?.message || event.error || event.stderr || "Tool failed";
+      const entry = _trackError("tool", `Tool ${toolName} failed: ${errorMsg}`);
+
+      console.error(`[CLAW] Tool error: ${toolName} — ${errorMsg.slice(0, 100)}`);
+
+      // Skill errors are wrapped as tool errors — detect them
+      const isSkill = toolName.includes("skill") || event.source === "skill";
+
+      reportToWolverine("route_error", {
+        path: `claw://tool/${toolName}`,
+        method: isSkill ? "SKILL" : "TOOL",
+        statusCode: 500,
+        message: `${isSkill ? "Skill" : "Tool"} ${toolName}: ${errorMsg}`.slice(0, 500),
+        stack: event.error?.stack || event.stderr || null,
+        file: event.file || null,
+        line: null,
+        timestamp: Date.now(),
+      });
+    }
+  });
+
+  // ── agent_end: catch agent failures and timeouts ────────────
+  reg("agent_end", (event, ctx) => {
+    if (!event) return;
+    const hasError = event.error || event.status === "error" || event.lifecycle === "error";
+
+    if (hasError) {
+      const reason = event.reason || event.error?.message || "Agent failed";
+      const isTimeout = reason.includes("timeout") || event.reason === "timeout";
+      const entry = _trackError("agent", `Agent ${isTimeout ? "timeout" : "error"}: ${reason}`);
+
+      console.error(`[CLAW] Agent ${isTimeout ? "timeout" : "error"}: ${reason.slice(0, 100)}`);
+
+      reportToWolverine("route_error", {
+        path: "claw://agent",
+        method: isTimeout ? "TIMEOUT" : "AGENT",
+        statusCode: isTimeout ? 408 : 500,
+        message: reason.slice(0, 500),
+        stack: event.error?.stack || null,
+        file: null,
+        line: null,
+        timestamp: Date.now(),
+      });
+    }
+  });
+
+  // ── before_tool_call: detect tool loops ─────────────────────
+  reg("before_tool_call", (event, ctx) => {
+    if (!event) return;
+
+    // OpenClaw's loop detection may have already flagged this
+    if (event.block || event.loopDetected) {
+      const toolName = event.toolName || event.name || "unknown";
+      const reason = event.blockReason || event.reason || "Loop detected";
+      _trackError("tool", `Tool loop blocked: ${toolName} — ${reason}`);
+
+      console.warn(`[CLAW] Tool loop blocked: ${toolName} — ${reason}`);
+
+      reportToWolverine("claw_warning", {
+        category: "tool_loop",
+        tool: toolName,
+        reason,
+        timestamp: Date.now(),
+      });
+    }
+  });
+
+  // ── message_sent: catch channel send failures ───────────────
+  reg("message_sent", (event, ctx) => {
+    if (!event) return;
+    const failed = event.success === false || event.error;
+
+    if (failed) {
+      const channel = event.channelId || event.channel || "unknown";
+      const errorMsg = event.error?.message || event.error || "Send failed";
+      _trackError("channel", `Channel ${channel}: ${errorMsg}`);
+
+      console.error(`[CLAW] Channel send failed: ${channel} — ${errorMsg.slice(0, 100)}`);
+
+      reportToWolverine("claw_warning", {
+        category: "channel_failure",
+        channel,
+        error: errorMsg.slice(0, 500),
+        timestamp: Date.now(),
+      });
+    }
+  });
+
+  // ── llm_output: catch provider errors and failovers ─────────
+  reg("llm_output", (event, ctx) => {
+    if (!event) return;
+    const hasError = event.error || event.failover;
+
+    if (hasError) {
+      const provider = event.provider || event.model || "unknown";
+      const reason = event.failoverReason || event.error?.message || event.error || "LLM error";
+      const status = event.httpCode || event.status;
+      _trackError("llm", `LLM ${provider}: ${reason} (${status || "?"})`);
+
+      // Billing errors (402) are critical — stop healing
+      const isBilling = status === 402 || reason.includes("billing");
+      // Rate limits (429) are transient
+      const isRateLimit = status === 429 || reason.includes("rate_limit");
+
+      if (isBilling) {
+        console.error(`[CLAW] BILLING ERROR: ${provider} — ${reason}`);
+        reportToWolverine("claw_critical", {
+          category: "billing",
+          provider,
+          error: reason.slice(0, 500),
+          timestamp: Date.now(),
+        });
+      } else if (!isRateLimit) {
+        // Don't spam wolverine with rate limit warnings
+        console.warn(`[CLAW] LLM error: ${provider} — ${reason.slice(0, 100)}`);
+        reportToWolverine("claw_warning", {
+          category: "llm_error",
+          provider,
+          status,
+          error: reason.slice(0, 500),
+          timestamp: Date.now(),
+        });
+      }
+    }
+  });
+
+  // ── subagent_ended: catch subagent failures ─────────────────
+  reg("subagent_ended", (event, ctx) => {
+    if (!event) return;
+    const failed = event.status === "error" || event.status === "timeout" || event.error;
+
+    if (failed) {
+      const agentId = event.subagentId || event.runId || "unknown";
+      const errorMsg = event.error?.message || event.error || `Subagent ${event.status}`;
+      _trackError("subagent", `Subagent ${agentId}: ${errorMsg}`);
+
+      console.error(`[CLAW] Subagent failed: ${agentId} — ${errorMsg.slice(0, 100)}`);
+
+      reportToWolverine("route_error", {
+        path: `claw://subagent/${agentId}`,
+        method: "SUBAGENT",
+        statusCode: 500,
+        message: errorMsg.slice(0, 500),
+        stack: event.error?.stack || null,
+        file: null,
+        line: null,
+        timestamp: Date.now(),
+      });
+    }
+  });
+
+  // ── gateway_start: lifecycle tracking ───────────────────────
+  reg("gateway_start", (event, ctx) => {
+    console.log("[CLAW] OpenClaw gateway started — wolverine watching");
+    reportToWolverine("claw_health", {
+      status: "running",
+      detail: "gateway_start",
+      timestamp: Date.now(),
+    });
+  });
+
+  // ── gateway_stop: lifecycle tracking ────────────────────────
+  reg("gateway_stop", (event, ctx) => {
+    console.log("[CLAW] OpenClaw gateway stopping");
+    reportToWolverine("claw_health", {
+      status: "stopping",
+      detail: "gateway_stop",
+      errorCounts: { ..._errorCounts },
+      timestamp: Date.now(),
+    });
+  });
+
+  // ── session_end: track session errors ───────────────────────
+  reg("session_end", (event, ctx) => {
+    if (event?.error) {
+      console.warn(`[CLAW] Session error: ${event.error?.message || event.error}`);
+    }
+  });
+}
+
+// ── EventEmitter fallback hooks ─────────────────────────────────
+
+/**
+ * Register basic EventEmitter hooks (works with all versions).
+ */
+function _registerEventHooks(gateway, projectRoot) {
+  if (!gateway.on) return;
+
+  gateway.on("error", (err) => {
+    const msg = err?.message || String(err);
+    _trackError("agent", `Gateway error: ${msg}`);
+    console.error(`[CLAW] Gateway error: ${msg}`);
+
+    reportToWolverine("route_error", {
+      path: "claw://gateway",
+      method: "INTERNAL",
+      statusCode: 500,
+      message: msg.slice(0, 500),
+      stack: err?.stack || null,
+      file: null,
+      line: null,
+      timestamp: Date.now(),
+    });
+  });
+
+  // These may or may not exist depending on OpenClaw version
+  const optionalEvents = ["agent:error", "skill:error", "channel:error", "channel:disconnect"];
+  for (const evt of optionalEvents) {
+    try {
+      gateway.on(evt, (err) => {
+        const msg = err?.message || String(err);
+        const category = evt.split(":")[0];
+        _trackError(category === "skill" ? "tool" : "agent", `${evt}: ${msg}`);
+        console.error(`[CLAW] ${evt}: ${msg.slice(0, 100)}`);
+      });
+    } catch {}
+  }
+}
+
+// ── Tool registration ───────────────────────────────────────────
+
+function _registerTools(gateway, tools) {
+  if (gateway.registerTools) {
+    gateway.registerTools(PLUGIN_NAME, tools);
+  } else if (gateway.addTools) {
+    gateway.addTools(tools);
+  } else if (gateway.skills?.register) {
+    gateway.skills.register(PLUGIN_NAME, {
+      description: "Wolverine self-healing integration — backup, brain, health, and error pipeline",
+      tools,
+    });
+  }
+}
+
+// ── Wolverine tools for the agent ───────────────────────────────
+
 function buildWolverineTools(projectRoot, config) {
   return [
     {
@@ -163,7 +467,7 @@ function buildWolverineTools(projectRoot, config) {
     },
     {
       name: "wolverine_health",
-      description: "Get wolverine system health status (process, memory, backups, heal history)",
+      description: "Get wolverine system health status including error tracking from all OpenClaw subsystems",
       parameters: { type: "object", properties: {} },
       execute: async () => {
         const status = {
@@ -171,6 +475,8 @@ function buildWolverineTools(projectRoot, config) {
           memory: `${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)}MB`,
           pid: process.pid,
           nodeVersion: process.version,
+          errors: { ..._errorCounts },
+          recentErrors: _recentErrors.slice(-5).map(e => `[${e.category}] ${e.summary}`),
         };
 
         try {
@@ -211,7 +517,6 @@ function buildWolverineTools(projectRoot, config) {
         required: ["error"],
       },
       execute: async ({ error, file }) => {
-        // Report to parent wolverine process for healing
         reportToWolverine("route_error", {
           path: "claw://agent",
           method: "INTERNAL",
@@ -225,50 +530,20 @@ function buildWolverineTools(projectRoot, config) {
         return "Error reported to wolverine healing pipeline.";
       },
     },
+    {
+      name: "wolverine_error_stats",
+      description: "Get error statistics from all OpenClaw subsystems (tools, agent, channels, LLM, subagents)",
+      parameters: { type: "object", properties: {} },
+      execute: async () => {
+        return JSON.stringify({
+          counts: { ..._errorCounts },
+          recent: _recentErrors.slice(-10),
+        }, null, 2);
+      },
+    },
   ];
 }
 
-/**
- * Handle gateway errors — report to wolverine for healing.
- */
-function handleGatewayError(err, projectRoot) {
-  console.error(`[CLAW] Gateway error: ${err.message}`);
-  reportToWolverine("route_error", {
-    path: "claw://gateway",
-    method: "INTERNAL",
-    statusCode: 500,
-    message: err.message,
-    stack: err.stack,
-    file: null,
-    line: null,
-    timestamp: Date.now(),
-  });
-}
-
-/**
- * Handle agent errors.
- */
-function handleAgentError(err, projectRoot) {
-  console.error(`[CLAW] Agent error: ${err.message}`);
-  reportToWolverine("route_error", {
-    path: "claw://agent",
-    method: "INTERNAL",
-    statusCode: 500,
-    message: err.message,
-    stack: err.stack,
-    file: null,
-    line: null,
-    timestamp: Date.now(),
-  });
-}
-
-/**
- * Handle skill errors.
- */
-function handleSkillError(err, projectRoot) {
-  console.warn(`[CLAW] Skill error (non-fatal): ${err.message}`);
-}
-
 /**
  * Report to wolverine parent process via IPC.
  */