wolverine-ai 4.7.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "4.7.0",
+  "version": "4.9.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/agent/agent-engine.js

@@ -121,7 +121,7 @@ const TOOL_DEFINITIONS = [
         type: "object",
         properties: {
           command: { type: "string", description: "Shell command to execute" },
-          timeout: { type: "number", description: "Timeout in ms (default: 10000)" },
+          timeout: { type: "number", description: "Timeout in ms (default: 30000, max: 60000)" },
         },
         required: ["command"],
       },
@@ -442,6 +442,22 @@ const TOOL_DEFINITIONS = [
       },
     },
   },
+  // ── ENVIRONMENT ──
+  {
+    type: "function",
+    function: {
+      name: "add_env_var",
+      description: "Append a key=value pair to .env.local. Only adds if the key does not already exist. Use for missing environment variable errors.",
+      parameters: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "Environment variable name (e.g. DATABASE_URL)" },
+          value: { type: "string", description: "Value to set" },
+        },
+        required: ["key", "value"],
+      },
+    },
+  },
   // ── TASK MANAGEMENT ──
   {
     type: "function",
@@ -814,6 +830,7 @@ class AgentEngine {
       case "check_file_descriptors": return this._checkFileDescriptors(args);
       case "check_event_loop": return this._checkEventLoop(args);
       case "check_websocket": return this._checkWebsocket(args);
+      case "add_env_var":   return this._addEnvVar(args);
       case "done":          return this._done(args);
       // Legacy aliases
       case "list_files":    return this._globFiles({ pattern: (args.dir || ".") + "/*" + (args.pattern || "") });
@@ -1204,7 +1221,8 @@ class AgentEngine {
     try {
       let Database;
       try { Database = require("better-sqlite3"); } catch {
-        return { content: "better-sqlite3 not installed. Run: npm install better-sqlite3" };
+        // Fallback: try PostgreSQL via pg if available
+        return this._inspectDbPg(args);
       }
       const db = new Database(dbPath, { readonly: true });
       let result;
@@ -1236,6 +1254,55 @@ class AgentEngine {
     } catch (e) { return { content: `DB error: ${e.message}` }; }
   }
 
+  async _inspectDbPg(args) {
+    let pg;
+    try { pg = require("pg"); } catch {
+      return { content: "Neither better-sqlite3 nor pg is installed. Run: npm install better-sqlite3 (for SQLite) or npm install pg (for PostgreSQL)" };
+    }
+    // db_path is treated as a connection string or uses DATABASE_URL
+    const connectionString = args.db_path.startsWith("postgres")
+      ? args.db_path
+      : process.env.DATABASE_URL;
+    if (!connectionString) {
+      return { content: "PostgreSQL: no connection string. Set DATABASE_URL or pass a postgres:// URI as db_path." };
+    }
+    const client = new pg.Client({ connectionString, statement_timeout: 10000 });
+    try {
+      await client.connect();
+      let result;
+      if (args.action === "tables") {
+        const res = await client.query("SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename");
+        result = res.rows.map(r => r.tablename).join("\n") || "(no tables)";
+      } else if (args.action === "schema") {
+        const res = await client.query(`SELECT table_name, column_name, data_type, is_nullable FROM information_schema.columns WHERE table_schema = 'public' ORDER BY table_name, ordinal_position`);
+        const tables = {};
+        for (const row of res.rows) {
+          if (!tables[row.table_name]) tables[row.table_name] = [];
+          tables[row.table_name].push(`  ${row.column_name} ${row.data_type}${row.is_nullable === "NO" ? " NOT NULL" : ""}`);
+        }
+        result = Object.entries(tables).map(([t, cols]) => `TABLE ${t}:\n${cols.join("\n")}`).join("\n\n") || "(no tables)";
+      } else if (args.action === "query") {
+        if (!args.sql) return { content: "Error: sql required for query action" };
+        const upper = args.sql.trim().toUpperCase();
+        if (!upper.startsWith("SELECT") && !upper.startsWith("SHOW")) {
+          return { content: "BLOCKED: inspect_db only allows SELECT/SHOW for PostgreSQL. Use run_db_fix for writes." };
+        }
+        const res = await client.query(args.sql);
+        result = JSON.stringify(res.rows.slice(0, 50), null, 2);
+        if (res.rows.length > 50) result += `\n... (${res.rows.length} total rows, showing first 50)`;
+      } else {
+        result = "Unknown action. Use: tables, schema, or query";
+      }
+      const { redact } = require("../security/secret-redactor");
+      console.log(chalk.gray(`    🗃️ DB (pg) ${args.action}: ${args.db_path}`));
+      return { content: redact(result) };
+    } catch (e) {
+      return { content: `PostgreSQL error: ${e.message}` };
+    } finally {
+      try { await client.end(); } catch {}
+    }
+  }
+
   _runDbFix(args) {
     const dbPath = path.resolve(this.cwd, args.db_path);
     try {
@@ -1752,6 +1819,35 @@ class AgentEngine {
     };
   }
 
+  // ── Environment variable tool ──
+  // Controlled exception to _isProtectedPath: allows APPENDING to .env.local only.
+  _addEnvVar(args) {
+    const key = (args.key || "").trim();
+    const value = args.value || "";
+    if (!key || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      return { content: "Error: invalid env var name. Must match [A-Za-z_][A-Za-z0-9_]*" };
+    }
+    const envPath = path.resolve(this.cwd, ".env.local");
+    try {
+      // Check if key already exists
+      if (fs.existsSync(envPath)) {
+        const existing = fs.readFileSync(envPath, "utf-8");
+        const keyRegex = new RegExp(`^${key}=`, "m");
+        if (keyRegex.test(existing)) {
+          return { content: `${key} already exists in .env.local — not overwriting.` };
+        }
+      }
+      // Append the key=value pair
+      const line = `${key}=${value}\n`;
+      fs.appendFileSync(envPath, line, "utf-8");
+      console.log(chalk.green(`    🔑 Added ${key} to .env.local`));
+      if (this.logger) this.logger.info("agent.env_var_add", `Added ${key} to .env.local`);
+      return { content: `Successfully added ${key} to .env.local` };
+    } catch (err) {
+      return { content: `Error adding env var: ${err.message}` };
+    }
+  }
+
   // ── Protected path guard ──
   // Wolverine's own source code is off-limits to the agent.
   // The agent should build/fix the USER's project, not modify itself.

package/src/brain/brain.js

@@ -145,6 +145,10 @@ const SEED_DOCS = [
     text: "Server context scanner (wolverine --init): scans server/ directory on every startup to build .wolverine/server-context.json. Extracts routes (HTTP methods + paths from fastify/express), middleware stack, database type + tables, config structure, dependencies, env vars used (process.env.X patterns), and full file tree. Context summary auto-injected into agent's heal prompt so it knows the server's route map, DB schema, and dependencies without re-scanning. Manual scan: wolverine --init. Auto-scan: runs silently on every boot. The context is read-only — never modified by the agent.",
     metadata: { topic: "server-context" },
   },
+  {
+    text: "Tool router (src/brain/tool-router.js): maps error types to recommended tool chains. Injected into agent prompt automatically — agent sees 'TOOL ROUTE: diagnose with [X, Y], fix with [Z]. Strategy: ...' for every error it heals. 25+ error categories mapped: TypeError→read_file+edit_file, ENOENT→list_dir+write_file, ECONNREFUSED→check_network+check_port+inspect_cache, EMFILE→check_file_descriptors+disk_cleanup, ENOSPC→disk_cleanup, certificate→inspect_certificate, OOM→check_memory+check_event_loop, websocket���check_websocket, database→inspect_db+run_db_fix (with prereq: inspect_db FIRST), missing_module→audit_deps+verify_node_modules, env_missing→inspect_env+add_env_var. Lookup is O(1) by error type + regex fallback. No AI tokens used for routing.",
+    metadata: { topic: "tool-router" },
+  },
   {
     text: "Telemetry architecture: 4 files, ~250 lines total. heartbeat.js sends one HTTP POST every 60s (5s timeout, non-blocking). register.js auto-registers and caches key in memory + disk. queue.js appends to JSONL file only on failure, trims lazily. telemetry.js collects from subsystems using optional chaining (no crashes if subsystem missing). All secrets redacted before sending. Response bodies drained immediately (res.resume). No blocking, no delays, no busy waits.",
     metadata: { topic: "telemetry-architecture" },
@@ -154,7 +158,7 @@ const SEED_DOCS = [
     metadata: { topic: "fastify" },
   },
   {
-    text: "npm package: wolverine-ai on npmjs.com (v3.7.7). Install: npm i wolverine-ai. CLI: npx wolverine server/index.js. 85 files, 190KB compressed. Includes src/, bin/, examples/. Server directory created from src/templates/server/ on first run (never overwritten). GitHub: https://github.com/bobbyswhip/Wolverine. Unified billing: all AI calls route through inference proxy with credit-based billing. WOLVERINE_API_KEY authenticates through billing proxy, WOLVERINE_GPU_KEY for direct GPU access. 3 providers: openai, anthropic, wolverine (self-hosted GPU via Vast.ai).",
+    text: "npm package: wolverine-ai on npmjs.com (latest). Install: npm i wolverine-ai. CLI: npx wolverine server/index.js. 85 files, 190KB compressed. Includes src/, bin/, examples/. Server directory created from src/templates/server/ on first run (never overwritten). GitHub: https://github.com/bobbyswhip/Wolverine. Unified billing: all AI calls route through inference proxy with credit-based billing. WOLVERINE_API_KEY authenticates through billing proxy, WOLVERINE_GPU_KEY for direct GPU access. 3 providers: openai, anthropic, wolverine (self-hosted GPU via Vast.ai).",
     metadata: { topic: "npm-package" },
   },
   {

package/src/brain/tool-router.js

@@ -0,0 +1,211 @@
+/**
+ * Tool Router — maps error types to recommended tool chains.
+ *
+ * Lightweight adjacency graph that tells the agent which tools to use
+ * for each error category. Injected into the agent prompt so it doesn't
+ * waste turns guessing.
+ *
+ * Structure per error type:
+ *   diagnose: tools to understand the problem (read-only)
+ *   fix: tools to apply the solution (write)
+ *   hint: one-line strategy for the AI
+ *   prereq: tools that must run BEFORE fix tools
+ *
+ * Lookup: O(1) by error classifier output or regex match on error message.
+ */
+
+const TOOL_ROUTES = {
+  // ── Code Errors ──
+  "TypeError": {
+    diagnose: ["read_file", "grep_code"],
+    fix: ["edit_file"],
+    hint: "Read the file at the error line. Find the undefined/null variable. Add a guard or fix the assignment.",
+  },
+  "ReferenceError": {
+    diagnose: ["read_file", "grep_code"],
+    fix: ["edit_file"],
+    hint: "Variable is not defined. Check for typos, missing imports, or scope issues.",
+  },
+  "SyntaxError": {
+    diagnose: ["read_file"],
+    fix: ["edit_file"],
+    hint: "Parse error in source. Read the file and fix the syntax at the reported line.",
+  },
+  "RangeError": {
+    diagnose: ["read_file", "check_memory"],
+    fix: ["edit_file"],
+    hint: "Stack overflow or invalid array length. Check for infinite recursion or unbounded growth.",
+  },
+
+  // ── Module/Dependency Errors ──
+  "missing_module": {
+    diagnose: ["audit_deps", "verify_node_modules"],
+    fix: ["bash_exec"],
+    hint: "Run npm install <module>. If in package.json but missing from disk, run npm ci.",
+  },
+  "missing_file": {
+    diagnose: ["read_file", "list_dir", "inspect_env"],
+    fix: ["write_file", "bash_exec"],
+    hint: "Check if the path is wrong (edit require) or if the file should exist (create it with expected content).",
+  },
+  "version_conflict": {
+    diagnose: ["audit_deps", "check_migration", "verify_node_modules"],
+    fix: ["bash_exec"],
+    hint: "Check peer deps and version compatibility. May need npm install package@version or full reinstall.",
+  },
+
+  // ── File System Errors ──
+  "ENOENT": {
+    diagnose: ["list_dir", "inspect_env", "read_file"],
+    fix: ["write_file", "bash_exec"],
+    prereq: ["read_file"],
+    hint: "File or directory doesn't exist. Check if path is correct, create if missing.",
+  },
+  "EACCES": {
+    diagnose: ["bash_exec", "list_dir"],
+    fix: ["bash_exec"],
+    hint: "Permission denied. Run chmod to fix permissions on the target file/directory.",
+  },
+  "ENOSPC": {
+    diagnose: ["disk_cleanup", "check_memory"],
+    fix: ["disk_cleanup"],
+    hint: "Disk full. Run disk_cleanup with dry_run=false to clear old backups and caches.",
+  },
+  "EMFILE": {
+    diagnose: ["check_file_descriptors", "list_processes", "check_event_loop"],
+    fix: ["disk_cleanup", "restart_service"],
+    hint: "Too many open files. Check for FD leaks, clear caches, consider raising ulimit in system profile.",
+  },
+
+  // ── Network Errors ──
+  "ECONNREFUSED": {
+    diagnose: ["check_network", "check_port", "inspect_cache", "inspect_env"],
+    fix: ["edit_file", "restart_service"],
+    hint: "Target service is down or wrong host/port. Check config, verify service is running.",
+  },
+  "ECONNRESET": {
+    diagnose: ["check_network", "check_logs"],
+    fix: ["edit_file"],
+    hint: "Connection reset by remote. Check for timeout settings, proxy config, or unstable network.",
+  },
+  "ETIMEDOUT": {
+    diagnose: ["check_network", "check_logs", "inspect_certificate"],
+    fix: ["edit_file"],
+    hint: "Connection timed out. Increase timeout, check DNS, verify endpoint is reachable.",
+  },
+  "EADDRINUSE": {
+    diagnose: ["check_port", "list_processes"],
+    fix: ["bash_exec"],
+    hint: "Port already in use. Find and kill the stale process holding the port.",
+  },
+
+  // ── Database Errors ──
+  "database": {
+    diagnose: ["inspect_db", "inspect_cache", "read_file"],
+    fix: ["run_db_fix", "edit_file"],
+    prereq: ["inspect_db"],
+    hint: "ALWAYS inspect_db before run_db_fix. Check table schema, query the affected data, then fix.",
+  },
+  "pool_exhaustion": {
+    diagnose: ["inspect_cache", "check_network", "check_logs"],
+    fix: ["edit_file", "restart_service"],
+    hint: "DB connection pool exhausted. Check for connection leaks, increase pool size, or restart.",
+  },
+
+  // ── SSL/TLS Errors ──
+  "certificate": {
+    diagnose: ["inspect_certificate", "check_network", "inspect_env"],
+    fix: ["bash_exec", "edit_file", "add_env_var"],
+    hint: "Check cert expiry, SAN list, and chain. May need renewal, hostname fix, or CA bundle.",
+  },
+
+  // ── Memory/Performance Errors ──
+  "OOM": {
+    diagnose: ["check_memory", "check_event_loop", "list_processes"],
+    fix: ["edit_file", "restart_service"],
+    hint: "Out of memory. Check for memory leaks (growing arrays, unclosed streams), reduce batch sizes.",
+  },
+  "event_loop_blocked": {
+    diagnose: ["check_event_loop", "check_logs", "check_memory"],
+    fix: ["edit_file"],
+    hint: "Synchronous operation blocking event loop. Replace readFileSync→readFile, execSync→exec, etc.",
+  },
+
+  // ── WebSocket Errors ──
+  "websocket": {
+    diagnose: ["check_websocket", "check_network", "check_port"],
+    fix: ["edit_file"],
+    hint: "Test WS handshake. Check upgrade headers, proxy config, and connection timeout settings.",
+  },
+
+  // ── Config/Environment Errors ──
+  "config": {
+    diagnose: ["read_file", "inspect_env", "list_dir"],
+    fix: ["write_file", "edit_file", "add_env_var"],
+    hint: "Check if config file exists and has expected structure. Check if required env vars are set.",
+  },
+  "env_missing": {
+    diagnose: ["inspect_env", "read_file"],
+    fix: ["add_env_var"],
+    hint: "Required environment variable not set. Add it to .env.local with the correct value.",
+  },
+};
+
+/**
+ * Find tool recommendations for an error.
+ * @param {string} errorMessage — the raw error message
+ * @param {string} errorType — from error-parser classifyError() (optional)
+ * @returns {{ diagnose: string[], fix: string[], prereq?: string[], hint: string } | null}
+ */
+function route(errorMessage, errorType) {
+  const msg = (errorMessage || "").toLowerCase();
+
+  // 1. Try exact error type match
+  if (errorType && TOOL_ROUTES[errorType]) return TOOL_ROUTES[errorType];
+
+  // 2. Try error class match
+  if (/typeerror/i.test(msg)) return TOOL_ROUTES.TypeError;
+  if (/referenceerror/i.test(msg)) return TOOL_ROUTES.ReferenceError;
+  if (/syntaxerror|unexpected token/i.test(msg)) return TOOL_ROUTES.SyntaxError;
+  if (/rangeerror/i.test(msg)) return TOOL_ROUTES.RangeError;
+
+  // 3. Try errno/code match
+  if (/enoent|no such file/i.test(msg)) return TOOL_ROUTES.ENOENT;
+  if (/eacces|eperm/i.test(msg)) return TOOL_ROUTES.EACCES;
+  if (/enospc/i.test(msg)) return TOOL_ROUTES.ENOSPC;
+  if (/emfile|enfile/i.test(msg)) return TOOL_ROUTES.EMFILE;
+  if (/econnrefused/i.test(msg)) return TOOL_ROUTES.ECONNREFUSED;
+  if (/econnreset/i.test(msg)) return TOOL_ROUTES.ECONNRESET;
+  if (/etimedout/i.test(msg)) return TOOL_ROUTES.ETIMEDOUT;
+  if (/eaddrinuse/i.test(msg)) return TOOL_ROUTES.EADDRINUSE;
+
+  // 4. Try pattern match
+  if (/cannot find module/i.test(msg)) return /['"][./\\]/.test(msg) ? TOOL_ROUTES.missing_file : TOOL_ROUTES.missing_module;
+  if (/cert|ssl|tls|self.signed/i.test(msg)) return TOOL_ROUTES.certificate;
+  if (/pool.*exhaust|pool.*timeout|acquire.*timeout/i.test(msg)) return TOOL_ROUTES.pool_exhaustion;
+  if (/websocket|ws.*close|transport.*close/i.test(msg)) return TOOL_ROUTES.websocket;
+  if (/out of memory|heap.*limit|allocation.*failed/i.test(msg)) return TOOL_ROUTES.OOM;
+  if (/not.set|undefined.*env|missing.*env/i.test(msg)) return TOOL_ROUTES.env_missing;
+  if (/missing.*config|invalid.*json|invalid.*config/i.test(msg)) return TOOL_ROUTES.config;
+  if (/sqlite|postgres|mysql|mongo|sequelize|prisma|knex/i.test(msg)) return TOOL_ROUTES.database;
+  if (/peer dep|eresolve|version.*mismatch/i.test(msg)) return TOOL_ROUTES.version_conflict;
+
+  return null; // unknown — let the AI figure it out
+}
+
+/**
+ * Get a compact prompt injection for the agent.
+ * Returns a string like "TOOL ROUTE: diagnose with [check_port, list_processes], fix with [bash_exec]. Hint: ..."
+ */
+function getRoutePrompt(errorMessage, errorType) {
+  const r = route(errorMessage, errorType);
+  if (!r) return "";
+  const parts = [`TOOL ROUTE for this error:`];
+  parts.push(`  Diagnose: ${r.diagnose.join(", ")}`);
+  if (r.prereq) parts.push(`  Prerequisites: ${r.prereq.join(", ")} (run these FIRST)`);
+  parts.push(`  Fix: ${r.fix.join(", ")}`);
+  parts.push(`  Strategy: ${r.hint}`);
+  return parts.join("\n");
+}
+
+module.exports = { route, getRoutePrompt, TOOL_ROUTES };

package/src/core/ai-client.js

@@ -659,6 +659,11 @@ Include both if needed, or just one.`;
   const result = await aiCall({ model, systemPrompt, userPrompt, maxTokens: 2048, category: "reasoning" });
   const content = (result.content || "").trim();
 
+  // Guard: cap length before regex extraction to prevent catastrophic backtracking
+  if (content.length > 50000) {
+    throw new Error("AI response too large for regex extraction (>50K chars)");
+  }
+
   // Strip thinking tags (Gemma), markdown fences, and any prefix text
   let cleaned = content
     .replace(/<\|channel>.*?<channel\|>/gs, "")

package/src/core/config.js

@@ -15,11 +15,14 @@ const path = require("path");
  */
 
 let _config = null;
+let _configRoot = null;
+
+function setConfigRoot(root) { _configRoot = root; }
 
 function loadConfig() {
   if (_config) return _config;
 
-  const configPath = path.join(process.cwd(), "server", "config", "settings.json");
+  const configPath = path.join(_configRoot || process.cwd(), "server", "config", "settings.json");
   let fileConfig = {};
   if (fs.existsSync(configPath)) {
     try {
@@ -109,6 +112,7 @@ function getConfig(dotPath) {
 }
 
 function resetConfig() { _config = null; }
+function resetConfigRoot() { _configRoot = null; }
 
 /**
  * Migrate old provider-based config to new flat models format.
@@ -153,4 +157,4 @@ function _migrateAndEnsureDefaults(fileConfig, configPath) {
   }
 }
 
-module.exports = { loadConfig, getConfig, resetConfig };
+module.exports = { loadConfig, getConfig, resetConfig, setConfigRoot, resetConfigRoot };

package/src/core/runner.js

@@ -45,14 +45,30 @@ class WolverineRunner {
     this.child = null;
     this.running = false;
 
+    // Stability tracking
+    this._lastStartTime = null;
+    this._lastBackupId = null;
+    this._stabilityTimer = null;
+    this._stderrBuffer = "";
+    this._healInProgress = false;
+    this._healStatus = null; // { active, file, error, phase, startedAt, iteration }
+
+    this._initSubsystems(options);
+  }
+
+  /**
+   * Initialize all subsystems — extracted from constructor for readability.
+   */
+  _initSubsystems(options) {
     // Core subsystems
     this.sandbox = new Sandbox(this.cwd);
     this.redactor = initRedactor(this.cwd);
+    const cfg = loadConfig();
     this.rateLimiter = new RateLimiter({
-      maxCallsPerWindow: parseInt(process.env.WOLVERINE_RATE_MAX_CALLS, 10) || 10,
-      windowMs: parseInt(process.env.WOLVERINE_RATE_WINDOW_MS, 10) || 600000,
-      minGapMs: parseInt(process.env.WOLVERINE_RATE_MIN_GAP_MS, 10) || 5000,
-      maxTokensPerHour: parseInt(process.env.WOLVERINE_RATE_MAX_TOKENS_HOUR, 10) || 100000,
+      maxCallsPerWindow: cfg.rateLimiting.maxCallsPerWindow,
+      windowMs: cfg.rateLimiting.windowMs,
+      minGapMs: cfg.rateLimiting.minGapMs,
+      maxTokensPerHour: cfg.rateLimiting.maxTokensPerHour,
       maxGlobalHealsPerWindow: parseInt(process.env.WOLVERINE_RATE_MAX_GLOBAL_HEALS, 10) || 5,
       globalWindowMs: parseInt(process.env.WOLVERINE_RATE_GLOBAL_WINDOW_MS, 10) || 300000,
     });
@@ -68,14 +84,14 @@ class WolverineRunner {
     });
 
     // Health monitoring
-    const port = parseInt(process.env.PORT, 10) || 3000;
+    const port = cfg.server.port;
     this.healthMonitor = new HealthMonitor({
       port,
       path: options.healthPath || "/health",
-      intervalMs: parseInt(process.env.WOLVERINE_HEALTH_INTERVAL_MS, 10) || 15000,
-      timeoutMs: parseInt(process.env.WOLVERINE_HEALTH_TIMEOUT_MS, 10) || 5000,
-      failThreshold: parseInt(process.env.WOLVERINE_HEALTH_FAIL_THRESHOLD, 10) || 3,
-      startDelayMs: parseInt(process.env.WOLVERINE_HEALTH_START_DELAY_MS, 10) || 10000,
+      intervalMs: cfg.healthCheck.intervalMs,
+      timeoutMs: cfg.healthCheck.timeoutMs,
+      failThreshold: cfg.healthCheck.failThreshold,
+      startDelayMs: cfg.healthCheck.startDelayMs,
     });
 
     // Performance monitoring
@@ -89,6 +105,9 @@ class WolverineRunner {
     // Process monitor — heartbeat, memory, CPU, leak detection
     this.processMonitor = new ProcessMonitor({ logger: this.logger });
 
+    // Brain — semantic memory + project context
+    this.brain = new Brain(this.cwd);
+
     // Route prober — tests all routes periodically
     this.routeProber = new RouteProber({
       port,
@@ -98,9 +117,9 @@ class WolverineRunner {
 
     // Error monitor — detects caught 500 errors without process crash
     this.errorMonitor = new ErrorMonitor({
-      threshold: parseInt(process.env.WOLVERINE_ERROR_THRESHOLD, 10) || 1,
-      windowMs: parseInt(process.env.WOLVERINE_ERROR_WINDOW_MS, 10) || 30000,
-      cooldownMs: parseInt(process.env.WOLVERINE_ERROR_COOLDOWN_MS, 10) || 60000,
+      threshold: cfg.errorMonitor.threshold,
+      windowMs: cfg.errorMonitor.windowMs,
+      cooldownMs: cfg.errorMonitor.cooldownMs,
       logger: this.logger,
       onError: (routePath, errorDetails) => this._healFromError(routePath, errorDetails),
     });
@@ -111,9 +130,6 @@ class WolverineRunner {
       windowMs: parseInt(process.env.WOLVERINE_LOOP_WINDOW_MS, 10) || 600000,
     });
 
-    // Brain — semantic memory + project context
-    this.brain = new Brain(this.cwd);
-
     // Skills — discoverable capabilities
     this.skills = new SkillRegistry();
     this.skills.load();
@@ -143,14 +159,6 @@ class WolverineRunner {
       routeProber: this.routeProber,
       errorMonitor: this.errorMonitor,
     });
-
-    // Stability tracking
-    this._lastStartTime = null;
-    this._lastBackupId = null;
-    this._stabilityTimer = null;
-    this._stderrBuffer = "";
-    this._healInProgress = false;
-    this._healStatus = null; // { active, file, error, phase, startedAt, iteration }
   }
 
   async start() {
@@ -465,9 +473,10 @@ class WolverineRunner {
           this._healInProgress = false;
           return;
         }
-        // Release lock so _healAndRestart can acquire it
+        // Pass through directly — _healAndRestart checks _healInProgress internally,
+        // so release it just before the call to avoid a race window
         this._healInProgress = false;
-        await this._healAndRestart();
+        await this._healAndRestart({ skipHealLockCheck: true });
       } catch (err) {
         // #5: Prevent unhandled errors in health callback from crashing the parent
         console.log(chalk.red(`  ⚠️  Health callback error: ${err.message}`));
@@ -570,8 +579,8 @@ class WolverineRunner {
     this.errorMonitor.reset();
   }
 
-  async _healAndRestart() {
-    if (this._healInProgress) return;
+  async _healAndRestart(options) {
+    if (this._healInProgress && !options?.skipHealLockCheck) return;
     // #9: Bail if stop() was called during the window between crash and heal
     if (this._shuttingDown) return;
     this._healInProgress = true;

package/src/core/wolverine.js

@@ -1,19 +1,26 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
 const chalk = require("chalk");
 const { parseError } = require("./error-parser");
-const { requestRepair, getClient, aiCall, _trackOp } = require("./ai-client");
+const { requestRepair, getClient, aiCall, _trackOp, getTrackerSnapshot } = require("./ai-client");
 const { getModel } = require("./models");
 const { applyPatch } = require("./patcher");
 const { verifyFix } = require("./verifier");
 const { Sandbox, SandboxViolationError } = require("../security/sandbox");
 const { RateLimiter } = require("../security/rate-limiter");
 const { detectInjection } = require("../security/injection-detector");
+const { redact, hasSecrets } = require("../security/secret-redactor");
 const { BackupManager } = require("../backup/backup-manager");
+const { getRoutePrompt } = require("../brain/tool-router");
 const { AgentEngine } = require("../agent/agent-engine");
 const { ResearchAgent } = require("../agent/research-agent");
 const { GoalLoop } = require("../agent/goal-loop");
 const { exploreAndFix, spawnParallel } = require("../agent/sub-agents");
 const { EVENT_TYPES } = require("../logger/event-logger");
 const { diagnose: diagnoseDeps } = require("../skills/deps");
+const { getSummary: getServerContextSummary } = require("./server-context");
 
 /**
  * The Wolverine healing engine — v3.
@@ -55,9 +62,7 @@ async function heal(opts) {
 async function _healImpl({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager, logger, brain, mcp, skills, repairHistory, routeContext }) {
   const healStartTime = Date.now();
   // Snapshot token tracker at heal start — diff at end = FULL pipeline cost
-  const { getTrackerSnapshot } = require("./ai-client");
   const _snapshot = getTrackerSnapshot();
-  const { redact, hasSecrets } = require("../security/secret-redactor");
 
   // Guard: don't burn tokens on empty stderr (signal kills, clean shutdowns, etc.)
   if (!stderr || stderr.trim().length < 10) {
@@ -191,8 +196,6 @@ async function _healImpl({ stderr, cwd, sandbox, notifier, rateLimiter, backupMa
   let backupSourceCode = "";
   if (hasFile && backupManager) {
     try {
-      const fs = require("fs");
-      const path = require("path");
       const stableBackups = backupManager.getAll().filter(b => b.status === "stable" || b.status === "verified");
       if (stableBackups.length > 0) {
         const latest = stableBackups[stableBackups.length - 1];
@@ -210,10 +213,15 @@ async function _healImpl({ stderr, cwd, sandbox, notifier, rateLimiter, backupMa
   let brainContext = "";
   // Inject server context (routes, DB, config, deps) if available
   try {
-    const { getSummary } = require("./server-context");
-    const serverCtx = getSummary(cwd);
+    const serverCtx = getServerContextSummary(cwd);
     if (serverCtx) brainContext += serverCtx + "\n\n";
   } catch {}
+  // Inject tool routing — tells agent exactly which tools to use for this error type
+  const toolRoute = getRoutePrompt(parsed.errorMessage, parsed.errorType);
+  if (toolRoute) {
+    brainContext += toolRoute + "\n\n";
+    console.log(chalk.gray(`  🗺️  Tool route: ${toolRoute.split("\n")[1]?.trim() || "matched"}`));
+  }
   // Inject relevant skill context (claw-code: pre-enrich prompt with matched tools)
   if (skills) {
     const skillCtx = skills.buildContext(parsed.errorMessage);
@@ -348,7 +356,6 @@ async function _healImpl({ stderr, cwd, sandbox, notifier, rateLimiter, backupMa
 
           // Execute shell commands first (npm install, mkdir, etc.)
           if (repair.commands && Array.isArray(repair.commands)) {
-            const { execSync } = require("child_process");
             for (const cmd of repair.commands) {
               // Block dangerous commands
               if (/rm\s+-rf\s+[/\\]|format\s+c:|mkfs/i.test(cmd)) {
@@ -554,7 +561,6 @@ async function _healImpl({ stderr, cwd, sandbox, notifier, rateLimiter, backupMa
  * Returns { fixed: boolean, action: string }
  */
 async function tryOperationalFix(parsed, cwd, logger, sandbox) {
-  const { execSync } = require("child_process");
   const msg = parsed.errorMessage || "";
 
   // Pattern 1: Dependency issues — use deps skill for structured diagnosis
@@ -581,8 +587,6 @@ async function tryOperationalFix(parsed, cwd, logger, sandbox) {
     || msg.match(/cannot find.*?'([^']+\.\w+)'/i);
   if (enoent) {
     const missingFile = enoent[1];
-    const fs = require("fs");
-    const path = require("path");
 
     // Only auto-create if it's inside the project and looks like a config/data file
     const rel = path.relative(cwd, missingFile).replace(/\\/g, "/");
@@ -639,7 +643,6 @@ async function tryOperationalFix(parsed, cwd, logger, sandbox) {
     const permFile = msg.match(/(?:EACCES|EPERM).*?'([^']+)'/);
     if (permFile) {
       try {
-        const fs = require("fs");
         fs.chmodSync(permFile[1], 0o755);
         console.log(chalk.blue(`  🔑 Fixed permissions on: ${permFile[1]}`));
         return { fixed: true, action: `Fixed permissions (chmod 755) on: ${permFile[1]}` };
@@ -671,7 +674,6 @@ async function tryOperationalFix(parsed, cwd, logger, sandbox) {
   // Pattern 5: ENOSPC — disk full, try automated cleanup
   if (/ENOSPC/.test(msg)) {
     try {
-      const os = require("os");
       const backupDir = path.join(os.homedir(), ".wolverine-safe-backups", "snapshots");
       let cleaned = 0;
       if (fs.existsSync(backupDir)) {
@@ -717,9 +719,6 @@ async function tryOperationalFix(parsed, cwd, logger, sandbox) {
  * Returns a JSON string with empty/default values, or null if can't infer.
  */
 function _inferJsonConfig(missingFile, cwd, parsed) {
-  const fs = require("fs");
-  const path = require("path");
-
   // Find which source file loads the missing config
   const basename = path.basename(missingFile);
   const sourceFile = parsed.filePath;
@@ -728,10 +727,18 @@ function _inferJsonConfig(missingFile, cwd, parsed) {
   // #17: Escape all regex special characters in basename to prevent regex injection
   const escapedBasename = basename.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
+  // #23: Guard against regex construction failure on unusual filenames
+  let configVarRegex;
+  try {
+    configVarRegex = new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:require|JSON\\.parse).*${escapedBasename}`);
+  } catch {
+    return null;
+  }
+
   try {
     const source = fs.readFileSync(sourceFile, "utf-8");
     // Look for property accesses on the loaded config: config.apiUrl, config.timeout, etc.
-    const configVarMatch = source.match(new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:require|JSON\\.parse).*${escapedBasename}`));
+    const configVarMatch = source.match(configVarRegex);
     if (!configVarMatch) return null;
 
     const varName = configVarMatch[1];

package/src/skills/deps.js

@@ -161,14 +161,19 @@ function findUnused(cwd) {
 
   // Scan all .js/.ts/.mjs/.cjs files for require/import statements
   const usedPackages = new Set();
+  let _fileCount = 0;
+  const FILE_SCAN_CAP = 5000;
   const scanDir = (dir) => {
+    if (_fileCount >= FILE_SCAN_CAP) return;
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const entry of entries) {
+      if (_fileCount >= FILE_SCAN_CAP) return;
       if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".wolverine") continue;
       const fullPath = path.join(dir, entry.name);
       if (entry.isDirectory()) { scanDir(fullPath); continue; }
       if (!/\.(js|ts|mjs|cjs|jsx|tsx)$/.test(entry.name)) continue;
+      _fileCount++;
       try {
         const content = fs.readFileSync(fullPath, "utf-8");
         // Match require("X") and import ... from "X"

package/src/vault/vault-manager.js

@@ -16,9 +16,9 @@ const path = require("path");
  * - Survives git pull, npm install, auto-update (lives in .wolverine/)
  */
 
-const VAULT_DIR = () => path.join(process.cwd(), ".wolverine", "vault");
-const MASTER_KEY_PATH = () => path.join(VAULT_DIR(), "master.key");
-const ETH_VAULT_PATH = () => path.join(VAULT_DIR(), "eth.vault");
+const VAULT_DIR = (projectRoot) => path.join(projectRoot || process.cwd(), ".wolverine", "vault");
+const MASTER_KEY_PATH = (projectRoot) => path.join(VAULT_DIR(projectRoot), "master.key");
+const ETH_VAULT_PATH = (projectRoot) => path.join(VAULT_DIR(projectRoot), "eth.vault");
 
 const ALGORITHM = "aes-256-gcm";
 const IV_LENGTH = 16;
@@ -28,26 +28,26 @@ const AUTH_TAG_LENGTH = 16;
  * Initialize the vault. Idempotent — creates keys only if missing.
  * Called during runner startup before any server code runs.
  */
-async function initVault() {
-  const vaultDir = VAULT_DIR();
+async function initVault(projectRoot) {
+  const vaultDir = VAULT_DIR(projectRoot);
   fs.mkdirSync(vaultDir, { recursive: true });
 
   let created = false;
 
   // Master encryption key
-  if (!fs.existsSync(MASTER_KEY_PATH())) {
+  if (!fs.existsSync(MASTER_KEY_PATH(projectRoot))) {
     const masterKey = crypto.randomBytes(32);
-    fs.writeFileSync(MASTER_KEY_PATH(), masterKey);
-    try { fs.chmodSync(MASTER_KEY_PATH(), 0o600); } catch {}
+    fs.writeFileSync(MASTER_KEY_PATH(projectRoot), masterKey);
+    try { fs.chmodSync(MASTER_KEY_PATH(projectRoot), 0o600); } catch {}
     masterKey.fill(0);
     created = true;
     console.log("  🔐 Vault: master encryption key generated");
   }
 
   // Ethereum private key (encrypted)
-  if (!fs.existsSync(ETH_VAULT_PATH())) {
+  if (!fs.existsSync(ETH_VAULT_PATH(projectRoot))) {
     const ethKey = crypto.randomBytes(32);
-    await encryptAndStore(ethKey);
+    await encryptAndStore(ethKey, { projectRoot });
     ethKey.fill(0);
     created = true;
     console.log("  🔐 Vault: ethereum wallet created");
@@ -59,18 +59,19 @@ async function initVault() {
 /**
  * Check if vault is fully initialized.
  */
-function isVaultInitialized() {
-  return fs.existsSync(MASTER_KEY_PATH()) && fs.existsSync(ETH_VAULT_PATH());
+function isVaultInitialized(projectRoot) {
+  return fs.existsSync(MASTER_KEY_PATH(projectRoot)) && fs.existsSync(ETH_VAULT_PATH(projectRoot));
 }
 
 /**
  * Encrypt a private key Buffer and write to eth.vault.
  * Wipes the master key from memory after use.
  */
-async function encryptAndStore(keyBuf) {
+async function encryptAndStore(keyBuf, options) {
+  const projectRoot = options?.projectRoot;
   let masterKey = null;
   try {
-    masterKey = fs.readFileSync(MASTER_KEY_PATH());
+    masterKey = fs.readFileSync(MASTER_KEY_PATH(projectRoot));
     const iv = crypto.randomBytes(IV_LENGTH);
     const cipher = crypto.createCipheriv(ALGORITHM, masterKey, iv);
     const encrypted = Buffer.concat([cipher.update(keyBuf), cipher.final()]);
@@ -83,13 +84,13 @@ async function encryptAndStore(keyBuf) {
       authTag: authTag.toString("hex"),
       ciphertext: encrypted.toString("hex"),
       created: new Date().toISOString(),
-      rotated: null,
+      rotated: options?.rotated || null,
     };
 
-    const tmpPath = ETH_VAULT_PATH() + ".tmp";
+    const tmpPath = ETH_VAULT_PATH(projectRoot) + ".tmp";
     fs.writeFileSync(tmpPath, JSON.stringify(vault, null, 2), "utf-8");
-    fs.renameSync(tmpPath, ETH_VAULT_PATH());
-    try { fs.chmodSync(ETH_VAULT_PATH(), 0o600); } catch {}
+    fs.renameSync(tmpPath, ETH_VAULT_PATH(projectRoot));
+    try { fs.chmodSync(ETH_VAULT_PATH(projectRoot), 0o600); } catch {}
   } finally {
     if (masterKey) masterKey.fill(0);
   }
@@ -99,15 +100,15 @@ async function encryptAndStore(keyBuf) {
  * Decrypt the Ethereum private key. Returns a Buffer.
  * CALLER MUST call .fill(0) on the returned Buffer when done.
  */
-function decryptPrivateKey() {
-  if (!isVaultInitialized()) {
+function decryptPrivateKey(projectRoot) {
+  if (!isVaultInitialized(projectRoot)) {
     throw new Error("vault not initialized");
   }
 
   let masterKey = null;
   try {
-    masterKey = fs.readFileSync(MASTER_KEY_PATH());
-    const vault = JSON.parse(fs.readFileSync(ETH_VAULT_PATH(), "utf-8"));
+    masterKey = fs.readFileSync(MASTER_KEY_PATH(projectRoot));
+    const vault = JSON.parse(fs.readFileSync(ETH_VAULT_PATH(projectRoot), "utf-8"));
 
     if (vault.version !== 1) throw new Error("unsupported vault version");
 
@@ -128,16 +129,11 @@ function decryptPrivateKey() {
  * Re-encrypt with a fresh IV. Defensive measure if key material was
  * potentially exposed in an error message.
  */
-async function rotateEncryption() {
+async function rotateEncryption(projectRoot) {
   let keyBuf = null;
   try {
-    keyBuf = decryptPrivateKey();
-    await encryptAndStore(keyBuf);
-
-    // Update rotated timestamp
-    const vault = JSON.parse(fs.readFileSync(ETH_VAULT_PATH(), "utf-8"));
-    vault.rotated = new Date().toISOString();
-    fs.writeFileSync(ETH_VAULT_PATH(), JSON.stringify(vault, null, 2), "utf-8");
+    keyBuf = decryptPrivateKey(projectRoot);
+    await encryptAndStore(keyBuf, { rotated: new Date().toISOString(), projectRoot });
   } finally {
     if (keyBuf) keyBuf.fill(0);
   }
@@ -147,11 +143,11 @@ async function rotateEncryption() {
  * Export vault contents for backup. Returns raw Buffers.
  * Caller MUST wipe masterKey after writing to backup.
  */
-function exportVaultForBackup() {
-  if (!isVaultInitialized()) return null;
+function exportVaultForBackup(projectRoot) {
+  if (!isVaultInitialized(projectRoot)) return null;
   return {
-    masterKey: fs.readFileSync(MASTER_KEY_PATH()),
-    vaultFile: fs.readFileSync(ETH_VAULT_PATH(), "utf-8"),
+    masterKey: fs.readFileSync(MASTER_KEY_PATH(projectRoot)),
+    vaultFile: fs.readFileSync(ETH_VAULT_PATH(projectRoot), "utf-8"),
   };
 }
 
@@ -159,18 +155,18 @@ function exportVaultForBackup() {
  * Import vault from backup. Only used during catastrophic recovery
  * when both vault files are missing.
  */
-function importVaultFromBackup(masterKeyBuf, vaultFileStr) {
-  const vaultDir = VAULT_DIR();
+function importVaultFromBackup(masterKeyBuf, vaultFileStr, projectRoot) {
+  const vaultDir = VAULT_DIR(projectRoot);
   fs.mkdirSync(vaultDir, { recursive: true });
 
-  fs.writeFileSync(MASTER_KEY_PATH(), masterKeyBuf);
-  try { fs.chmodSync(MASTER_KEY_PATH(), 0o600); } catch {}
+  fs.writeFileSync(MASTER_KEY_PATH(projectRoot), masterKeyBuf);
+  try { fs.chmodSync(MASTER_KEY_PATH(projectRoot), 0o600); } catch {}
 
-  fs.writeFileSync(ETH_VAULT_PATH(), vaultFileStr, "utf-8");
-  try { fs.chmodSync(ETH_VAULT_PATH(), 0o600); } catch {}
+  fs.writeFileSync(ETH_VAULT_PATH(projectRoot), vaultFileStr, "utf-8");
+  try { fs.chmodSync(ETH_VAULT_PATH(projectRoot), 0o600); } catch {}
 }
 
-function getVaultPath() { return VAULT_DIR(); }
+function getVaultPath(projectRoot) { return VAULT_DIR(projectRoot); }
 
 module.exports = {
   initVault,