wolverine-ai 1.5.2 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "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/server/config/settings.json

@@ -24,7 +24,7 @@
   },
 
   "cluster": {
-    "mode": "auto",
+    "enabled": false,
     "workers": 0
   },
 
@@ -48,7 +48,7 @@
   },
 
   "errorMonitor": {
-    "defaultThreshold": 3,
+    "defaultThreshold": 1,
     "windowMs": 30000,
     "cooldownMs": 60000
   },

package/server/index.js

@@ -1,61 +1,85 @@
-const fastify = require("fastify")({ logger: false });
+const cluster = require("cluster");
+const os = require("os");
 const PORT = process.env.PORT || 3000;
 
-// Routes
-fastify.register(require("./routes/health"), { prefix: "/health" });
-fastify.register(require("./routes/api"), { prefix: "/api" });
-fastify.register(require("./routes/time"), { prefix: "/time" });
-
-// Root
-fastify.get("/", async () => ({
-  name: "Wolverine Server",
-  version: "1.0.0",
-  status: "running",
-  uptime: process.uptime(),
-}));
-
-// 404
-fastify.setNotFoundHandler((req, reply) => {
-  reply.code(404).send({ error: "Not found", path: req.url });
-});
-
-// Error handler — reports to Wolverine parent via IPC for auto-healing
-fastify.setErrorHandler((err, req, reply) => {
-  console.error(`[ERROR] ${err.message}`);
-  reply.code(500).send({ error: err.message });
-
-  // Report to Wolverine via IPC (if running under wolverine)
-  if (typeof process.send === "function") {
-    try {
-      // Extract file/line from stack trace
-      let file = null, line = null;
-      if (err.stack) {
-        const frames = err.stack.split("\n");
-        for (const frame of frames) {
-          const m = frame.match(/\(([^)]+):(\d+):(\d+)\)/) || frame.match(/at\s+([^\s(]+):(\d+):(\d+)/);
-          if (m && !m[1].includes("node_modules") && !m[1].includes("node:")) {
-            file = m[1]; line = parseInt(m[2], 10); break;
+// Cluster mode: master forks workers, workers run the server.
+// Wolverine sets WOLVERINE_RECOMMENDED_WORKERS based on system detection.
+// Set cluster.enabled=true in settings.json or WOLVERINE_CLUSTER=true to enable.
+const clusterEnabled = process.env.WOLVERINE_CLUSTER === "true";
+const workerCount = parseInt(process.env.WOLVERINE_RECOMMENDED_WORKERS, 10) || os.cpus().length;
+
+if (clusterEnabled && cluster.isPrimary && workerCount > 1) {
+  console.log(`[CLUSTER] Primary ${process.pid} forking ${workerCount} workers`);
+  for (let i = 0; i < workerCount; i++) cluster.fork();
+
+  cluster.on("exit", (worker, code) => {
+    if (code !== 0) {
+      console.log(`[CLUSTER] Worker ${worker.process.pid} died (code ${code}), respawning...`);
+      cluster.fork();
+    }
+  });
+} else {
+  // Single worker or cluster worker — run the server
+  const fastify = require("fastify")({ logger: false });
+
+  // Routes
+  fastify.register(require("./routes/health"), { prefix: "/health" });
+  fastify.register(require("./routes/api"), { prefix: "/api" });
+  fastify.register(require("./routes/time"), { prefix: "/time" });
+
+  // Root
+  fastify.get("/", async () => ({
+    name: "Wolverine Server",
+    version: "1.0.0",
+    status: "running",
+    uptime: process.uptime(),
+    pid: process.pid,
+    worker: cluster.isWorker ? cluster.worker.id : "primary",
+  }));
+
+  // 404
+  fastify.setNotFoundHandler((req, reply) => {
+    reply.code(404).send({ error: "Not found", path: req.url });
+  });
+
+  // Error handler — reports to Wolverine parent via IPC for auto-healing
+  fastify.setErrorHandler((err, req, reply) => {
+    console.error(`[ERROR] ${err.message}`);
+    reply.code(500).send({ error: err.message });
+
+    // Report to Wolverine via IPC (if running under wolverine)
+    if (typeof process.send === "function") {
+      try {
+        let file = null, line = null;
+        if (err.stack) {
+          const frames = err.stack.split("\n");
+          for (const frame of frames) {
+            const m = frame.match(/\(([^)]+):(\d+):(\d+)\)/) || frame.match(/at\s+([^\s(]+):(\d+):(\d+)/);
+            if (m && !m[1].includes("node_modules") && !m[1].includes("node:")) {
+              file = m[1]; line = parseInt(m[2], 10); break;
+            }
           }
         }
-      }
-      process.send({
-        type: "route_error",
-        path: req.url,
-        method: req.method,
-        statusCode: 500,
-        message: err.message,
-        stack: err.stack,
-        file,
-        line,
-        timestamp: Date.now(),
-      });
-    } catch (_) { /* IPC send failed — non-fatal */ }
-  }
-});
-
-fastify.listen({ port: PORT, host: "0.0.0.0" }, (err) => {
-  if (err) { console.error(err); process.exit(1); }
-  console.log(`Server running on http://localhost:${PORT}`);
-  console.log(`Health: http://localhost:${PORT}/health`);
-  console.log(`API:    http://localhost:${PORT}/api`);
-});
+        process.send({
+          type: "route_error",
+          path: req.url,
+          method: req.method,
+          statusCode: 500,
+          message: err.message,
+          stack: err.stack,
+          file,
+          line,
+          timestamp: Date.now(),
+        });
+      } catch (_) { /* IPC send failed — non-fatal */ }
+    }
+  });
+
+  fastify.listen({ port: PORT, host: "0.0.0.0", reusePort: clusterEnabled }, (err) => {
+    if (err) { console.error(err); process.exit(1); }
+    const label = cluster.isWorker ? ` (worker ${cluster.worker.id})` : "";
+    console.log(`Server running on http://localhost:${PORT}${label}`);
+    console.log(`Health: http://localhost:${PORT}/health`);
+    console.log(`API:    http://localhost:${PORT}/api`);
+  });
+}

package/src/agent/agent-engine.js

@@ -720,7 +720,7 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
       }
     }
 
-    const timeout = Math.min(args.timeout || 10000, 30000);
+    const timeout = Math.min(args.timeout || 30000, 60000);
     try {
       const output = execSync(args.command, {
         cwd: this.cwd,

package/src/core/ai-client.js

@@ -335,7 +335,7 @@ async function _chatCallWithHistory(openai, { model, messages, tools, maxTokens
  * Send an error context to OpenAI and get a repair patch back.
  * Uses CODING_MODEL — routes to correct API automatically.
  */
-async function requestRepair({ filePath, sourceCode, backupSourceCode, errorMessage, stackTrace }) {
+async function requestRepair({ filePath, sourceCode, backupSourceCode, errorMessage, stackTrace, extraContext }) {
   const model = getModel("coding");
 
   const systemPrompt = "You are a Node.js debugging expert. Respond with ONLY valid JSON, no markdown fences.";
@@ -357,7 +357,7 @@ ${errorMessage}
 ${stackTrace}
 \`\`\`
 
-${backupSourceCode ? `## Last Known Working Version\n\`\`\`javascript\n${backupSourceCode}\n\`\`\`\n\nCompare the current broken code with this working version. If the broken code added something that doesn't work, REVERT that addition rather than patching around it.\n` : ""}## Instructions
+${backupSourceCode ? `## Last Known Working Version\n\`\`\`javascript\n${backupSourceCode}\n\`\`\`\n\nCompare the current broken code with this working version. If the broken code added something that doesn't work, REVERT that addition rather than patching around it.\n` : ""}${extraContext || ""}## Instructions
 1. Identify the root cause of the error.
 2. Not all errors are code bugs. Choose the correct fix type:
    - "Cannot find module 'X'" (not starting with ./ or ../) = missing npm package → use "commands" to npm install

package/src/core/runner.js

@@ -50,6 +50,8 @@ class WolverineRunner {
       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,
+      maxGlobalHealsPerWindow: parseInt(process.env.WOLVERINE_RATE_MAX_GLOBAL_HEALS, 10) || 5,
+      globalWindowMs: parseInt(process.env.WOLVERINE_RATE_GLOBAL_WINDOW_MS, 10) || 300000,
     });
     this.backupManager = new BackupManager(this.cwd);
     this.logger = new EventLogger(this.cwd);
@@ -93,7 +95,7 @@ class WolverineRunner {
 
     // Error monitor — detects caught 500 errors without process crash
     this.errorMonitor = new ErrorMonitor({
-      threshold: parseInt(process.env.WOLVERINE_ERROR_THRESHOLD, 10) || 3,
+      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,
       logger: this.logger,
@@ -234,11 +236,11 @@ class WolverineRunner {
 
       oldChild.removeAllListeners("exit");
       oldChild.once("exit", onExit);
-      oldChild.kill("SIGTERM");
+      this._killProcessTree(oldChild.pid, "SIGTERM");
 
       // Force kill if it doesn't exit in 3s
       setTimeout(() => {
-        try { oldChild.kill("SIGKILL"); } catch {}
+        this._killProcessTree(oldChild.pid, "SIGKILL");
         onExit();
       }, 3000);
     } else {
@@ -276,13 +278,14 @@ class WolverineRunner {
 
     this.logger.info(EVENT_TYPES.PROCESS_STOP, "Wolverine stopped (graceful shutdown)");
 
-    // Kill child — remove exit listener first so it doesn't trigger heal
+    // Kill child + all its descendants — remove exit listener first so it doesn't trigger heal
     if (this.child) {
+      const pid = this.child.pid;
       this.child.removeAllListeners("exit");
-      this.child.kill("SIGTERM");
+      this._killProcessTree(pid, "SIGTERM");
       // Force kill after 3s if it doesn't respond
       setTimeout(() => {
-        try { if (this.child) this.child.kill("SIGKILL"); } catch {}
+        this._killProcessTree(pid, "SIGKILL");
       }, 3000);
       this.child = null;
     }
@@ -302,9 +305,15 @@ class WolverineRunner {
     // Spawn with --require error-hook.js for IPC error reporting
     // The error hook auto-patches Fastify/Express to report caught 500s
     const errorHookPath = path.join(__dirname, "error-hook.js");
+    const sysInfo = require("./system-info").detect();
     this.child = spawn("node", ["--require", errorHookPath, this.scriptPath], {
       cwd: this.cwd,
-      env: { ...process.env },
+      env: {
+        ...process.env,
+        // Tell the user's server how many workers to fork (if it uses clustering)
+        WOLVERINE_RECOMMENDED_WORKERS: String(sysInfo.recommended?.workers || 1),
+        WOLVERINE_MANAGED: "1", // Signal that wolverine is managing this process
+      },
       stdio: ["inherit", "inherit", "pipe", "ipc"],
     });
 
@@ -337,13 +346,33 @@ class WolverineRunner {
     // Start health monitoring
     this.healthMonitor.stop();
     this.healthMonitor.reset();
-    this.healthMonitor.start((reason) => {
-      if (this._healInProgress) return;
-      console.log(chalk.red(`\n🚨 Health check triggered restart (reason: ${reason})`));
+    this.healthMonitor.start(async (reason) => {
+      if (this._healInProgress || !this.running) return;
+      console.log(chalk.red(`\n🚨 Health check triggered heal (reason: ${reason})`));
       this.logger.error(EVENT_TYPES.HEALTH_UNRESPONSIVE, `Server unresponsive: ${reason}`, { reason });
+      this.healthMonitor.stop();
+
+      // Kill the hung process — remove exit listener to prevent double-heal
       if (this.child) {
-        this.child.kill("SIGKILL");
+        const pid = this.child.pid;
+        this.child.removeAllListeners("exit");
+        this._killProcessTree(pid, "SIGKILL");
+        this.child = null;
+      }
+
+      // Synthesize error context for the heal pipeline
+      this._stderrBuffer = `Server became unresponsive. Health check failed: ${reason}\n` +
+        `The server was running but stopped responding to HTTP requests.\n` +
+        `Possible causes: infinite loop, deadlock, memory exhaustion, blocked event loop.`;
+
+      this.retryCount++;
+      if (this.retryCount > this.maxRetries) {
+        console.log(chalk.red(`\n🛑 Max retries reached.`));
+        this._logRollbackHint();
+        this.running = false;
+        return;
       }
+      await this._healAndRestart();
     });
 
     this.child.on("exit", async (code, signal) => {
@@ -514,6 +543,7 @@ class WolverineRunner {
         mcp: this.mcp,
         skills: this.skills,
         repairHistory: this.repairHistory,
+        routeContext: { path: routePath, method: errorDetails?.method },
       });
 
       if (result.healed) {
@@ -565,6 +595,34 @@ class WolverineRunner {
     }
   }
 
+  /**
+   * Kill a process and all its children (process tree kill).
+   * Handles servers that fork workers internally — prevents orphaned processes.
+   */
+  _killProcessTree(pid, signal = "SIGTERM") {
+    if (!pid) return;
+    try {
+      if (process.platform === "win32") {
+        // taskkill /T kills the process tree
+        execSync(`taskkill /PID ${pid} /T /F`, { timeout: 3000, stdio: "ignore" });
+      } else {
+        // Kill the process group (negative PID)
+        try { process.kill(-pid, signal); } catch {}
+        // Also kill individual PID in case it's not a group leader
+        try { process.kill(pid, signal); } catch {}
+        // Find and kill children via pgrep
+        try {
+          const children = execSync(`pgrep -P ${pid} 2>/dev/null`, { encoding: "utf-8", timeout: 3000 }).trim();
+          if (children) {
+            for (const cpid of children.split("\n").map(p => parseInt(p, 10)).filter(Boolean)) {
+              try { process.kill(cpid, signal); } catch {}
+            }
+          }
+        } catch { /* no children or pgrep not available */ }
+      }
+    } catch { /* process already dead */ }
+  }
+
   _ensurePortFree() {
     const port = parseInt(process.env.PORT, 10) || 3000;
     try {

package/src/core/verifier.js

@@ -1,5 +1,6 @@
 const { spawn } = require("child_process");
 const chalk = require("chalk");
+const { parseError, classifyError } = require("./error-parser");
 
 /**
  * Fix Verifier — validates that a patch actually fixes the error
@@ -75,9 +76,18 @@ function bootProbe(scriptPath, cwd, originalErrorSignature) {
         return;
       }
 
-      // Check if it's the same error
-      const sameError = originalErrorSignature &&
-        stderr.includes(originalErrorSignature.split("::").pop().trim());
+      // Check if it's the same error — use classification, not string matching
+      let sameError = false;
+      if (originalErrorSignature) {
+        const newParsed = parseError(stderr);
+        const origParts = (originalErrorSignature || "").split("::");
+        const origMsg = origParts.slice(1).join("::").trim();
+        const origType = classifyError(origMsg, "");
+        const origClass = (origMsg.match(/^(\w*Error)/) || [])[1] || "";
+        const newClass = (newParsed.errorMessage?.match(/^(\w*Error)/) || [])[1] || "";
+        // Same error = same classification type AND same error class (TypeError vs ReferenceError)
+        sameError = newParsed.errorType === origType && origClass === newClass;
+      }
 
       resolve({
         status: "crashed",
@@ -112,11 +122,20 @@ function bootProbe(scriptPath, cwd, originalErrorSignature) {
  * - { verified: false, status: "new-error" }     — different error, fix broke something else → rollback
  * - { verified: false, status: "syntax-error" }  — introduced syntax error → rollback
  */
-async function verifyFix(scriptPath, cwd, originalErrorSignature) {
+/**
+ * Full verification pipeline.
+ *
+ * @param {string} scriptPath — entry point to verify
+ * @param {string} cwd — working directory
+ * @param {string} originalErrorSignature — error signature for same-error detection
+ * @param {object} routeContext — optional { path, method } for route-level testing
+ */
+async function verifyFix(scriptPath, cwd, originalErrorSignature, routeContext) {
+  const steps = routeContext?.path ? 3 : 2;
   console.log(chalk.yellow("\n🔬 Verifying fix...\n"));
 
   // Step 1: Syntax check
-  console.log(chalk.gray("  [1/2] Syntax check..."));
+  console.log(chalk.gray(`  [1/${steps}] Syntax check...`));
   const syntax = await syntaxCheck(scriptPath);
   if (!syntax.valid) {
     console.log(chalk.red(`  ❌ Syntax error introduced by fix:\n      ${syntax.error}`));
@@ -125,22 +144,105 @@ async function verifyFix(scriptPath, cwd, originalErrorSignature) {
   console.log(chalk.green("  ✅ Syntax OK"));
 
   // Step 2: Boot probe
-  console.log(chalk.gray("  [2/2] Boot probe (watching for crashes)..."));
+  console.log(chalk.gray(`  [2/${steps}] Boot probe (watching for crashes)...`));
   const probe = await bootProbe(scriptPath, cwd, originalErrorSignature);
 
-  if (probe.status === "alive") {
-    console.log(chalk.green("  ✅ Process booted successfully and stayed alive."));
-    return { verified: true, status: "fixed" };
+  if (probe.status !== "alive") {
+    if (probe.sameError) {
+      console.log(chalk.red("  ❌ Same error occurred — fix did not resolve the issue."));
+      return { verified: false, status: "same-error", stderr: probe.stderr };
+    }
+    console.log(chalk.red("  ❌ A different error occurred — fix may have introduced a new bug."));
+    return { verified: false, status: "new-error", stderr: probe.stderr };
   }
-
-  // It crashed
-  if (probe.sameError) {
-    console.log(chalk.red("  ❌ Same error occurred — fix did not resolve the issue."));
-    return { verified: false, status: "same-error", stderr: probe.stderr };
+  console.log(chalk.green("  ✅ Process booted successfully"));
+
+  // Step 3: Route probe (if we know which route was failing)
+  if (routeContext?.path) {
+    console.log(chalk.gray(`  [3/${steps}] Route probe: ${routeContext.method || "GET"} ${routeContext.path}...`));
+    const routeResult = await routeProbe(scriptPath, cwd, routeContext);
+    if (routeResult.status === "failed") {
+      console.log(chalk.red(`  ❌ Route ${routeContext.path} still fails (HTTP ${routeResult.statusCode}): ${routeResult.body?.slice(0, 80)}`));
+      return { verified: false, status: "route-still-broken", stderr: routeResult.body };
+    }
+    if (routeResult.status === "passed") {
+      console.log(chalk.green(`  ✅ Route ${routeContext.path} responds OK (HTTP ${routeResult.statusCode})`));
+    } else {
+      console.log(chalk.gray(`  ⚠️  Route probe skipped: ${routeResult.reason || "unknown"}`));
+    }
   }
 
-  console.log(chalk.red("  ❌ A different error occurred — fix may have introduced a new bug."));
-  return { verified: false, status: "new-error", stderr: probe.stderr };
+  return { verified: true, status: "fixed" };
+}
+
+/**
+ * Route probe — boot the server on PORT=0, detect the actual port from stdout,
+ * then HTTP-test the failing route.
+ */
+function routeProbe(scriptPath, cwd, routeContext) {
+  const http = require("http");
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const probeEnv = { ...process.env, PORT: "0", WOLVERINE_PROBE: "1" };
+    const child = spawn("node", [scriptPath], {
+      cwd, env: probeEnv,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+
+    child.on("exit", () => {
+      if (settled) return;
+      settled = true;
+      resolve({ status: "failed", statusCode: 0, body: stderr || "Process exited before route test" });
+    });
+
+    // Poll stdout for port announcement
+    const checkPort = setInterval(() => {
+      if (settled) { clearInterval(checkPort); return; }
+      const m = stdout.match(/(?:listening|running|started|on)\s+(?:on\s+)?(?:(?:https?:\/\/)?[\w.]+:)?(\d{4,5})/i)
+              || stdout.match(/:(\d{4,5})/);
+      if (m) {
+        clearInterval(checkPort);
+        const port = parseInt(m[1], 10);
+        // Test the route
+        const req = http.request({
+          hostname: "127.0.0.1", port,
+          path: routeContext.path,
+          method: routeContext.method || "GET",
+          timeout: 5000,
+        }, (res) => {
+          let body = "";
+          res.on("data", (c) => { body += c; });
+          res.on("end", () => {
+            settled = true;
+            child.kill("SIGTERM");
+            if (res.statusCode < 500) {
+              resolve({ status: "passed", statusCode: res.statusCode });
+            } else {
+              resolve({ status: "failed", statusCode: res.statusCode, body: body.slice(0, 500) });
+            }
+          });
+        });
+        req.on("error", (e) => { settled = true; child.kill("SIGTERM"); resolve({ status: "failed", statusCode: 0, body: e.message }); });
+        req.on("timeout", () => { req.destroy(); settled = true; child.kill("SIGTERM"); resolve({ status: "failed", statusCode: 0, body: "timeout" }); });
+        req.end();
+      }
+    }, 300);
+
+    // Overall timeout
+    setTimeout(() => {
+      clearInterval(checkPort);
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      resolve({ status: "skipped", reason: "Could not detect server port from stdout" });
+    }, BOOT_PROBE_TIMEOUT_MS + 5000);
+  });
 }
 
 module.exports = { verifyFix, syntaxCheck, bootProbe, BOOT_PROBE_TIMEOUT_MS };

package/src/core/wolverine.js

@@ -23,7 +23,24 @@ const { EVENT_TYPES } = require("../logger/event-logger");
  *
  * The engine tries fast path first. If that fails verification, it escalates to the agent.
  */
-async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager, logger, brain, mcp, skills, repairHistory }) {
+async function heal(opts) {
+  const HEAL_TIMEOUT_MS = parseInt(process.env.WOLVERINE_HEAL_TIMEOUT_MS, 10) || 300000; // 5 min
+  try {
+    return await Promise.race([
+      _healImpl(opts),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), HEAL_TIMEOUT_MS)),
+    ]);
+  } catch (err) {
+    if (err.message === "timeout") {
+      console.log(chalk.red(`\n🐺 Heal timed out after ${HEAL_TIMEOUT_MS / 1000}s`));
+      if (opts.logger) opts.logger.error(EVENT_TYPES.HEAL_FAILED, `Heal timed out after ${HEAL_TIMEOUT_MS / 1000}s`);
+      return { healed: false, explanation: `Heal timed out after ${HEAL_TIMEOUT_MS / 1000}s` };
+    }
+    throw err;
+  }
+}
+
+async function _healImpl({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager, logger, brain, mcp, skills, repairHistory, routeContext }) {
   const healStartTime = Date.now();
   const { redact, hasSecrets } = require("../security/secret-redactor");
 
@@ -70,6 +87,16 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
   console.log(chalk.cyan(`  Error: ${parsed.errorMessage}`));
   console.log(chalk.cyan(`  Type:  ${parsed.errorType || "unknown"}`));
 
+  // 2c. If error mentions env vars, collect env context for AI
+  let envContext = "";
+  if (/process\.env|\.env|missing.*(?:key|token|secret|api|url|host|port|password|database)|undefined.*(?:config|setting)/i.test(parsed.errorMessage + " " + (parsed.stackTrace || ""))) {
+    const envKeys = Object.keys(process.env)
+      .filter(k => !k.startsWith("npm_") && !k.startsWith("WOLVERINE_") && !k.startsWith("__"))
+      .sort();
+    envContext = `\nAvailable environment variables (names only, values redacted): ${envKeys.join(", ")}\nIf the error is about a missing env var, suggest setting it rather than working around it in code.\n`;
+    console.log(chalk.gray(`  🔑 Env context: ${envKeys.length} vars available`));
+  }
+
   // 3. Rate limit check
   const rateCheck = rateLimiter.check(errorSignature);
   if (!rateCheck.allowed) {
@@ -200,7 +227,7 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
       backupManager.setErrorSignature(bid, errorSignature);
       if (logger) logger.info(EVENT_TYPES.BACKUP_CREATED, `Backup ${bid} (iteration ${iteration})`, { backupId: bid });
 
-      const fullContext = [brainContext, researchContext, researchCtx].filter(Boolean).join("\n");
+      const fullContext = [brainContext, researchContext, researchCtx, envContext].filter(Boolean).join("\n");
 
       let result;
       if (iteration === 1 && hasFile) {
@@ -211,6 +238,7 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
           const repair = await requestRepair({
             filePath: parsed.filePath, sourceCode, backupSourceCode,
             errorMessage: parsed.errorMessage, stackTrace: parsed.stackTrace,
+            extraContext: envContext,
           });
           rateLimiter.record(errorSignature);
 
@@ -244,7 +272,7 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
             for (const r of patchResults) console.log(chalk.green(`  ✅ Patched: ${r.file}`));
           }
 
-          const verification = await verifyFix(parsed.filePath, cwd, errorSignature);
+          const verification = await verifyFix(parsed.filePath, cwd, errorSignature, routeContext);
           if (verification.verified) {
             backupManager.markVerified(bid);
             rateLimiter.clearSignature(errorSignature);
@@ -276,7 +304,7 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
         if (agentResult.success) {
           // Verify: if we have a file, do syntax + boot check. Otherwise just boot probe.
           if (hasFile) {
-            const verification = await verifyFix(parsed.filePath, cwd, errorSignature);
+            const verification = await verifyFix(parsed.filePath, cwd, errorSignature, routeContext);
             if (verification.verified) {
               backupManager.markVerified(bid);
               rateLimiter.clearSignature(errorSignature);
@@ -304,7 +332,7 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
 
         if (subResult.success) {
           if (hasFile) {
-            const verification = await verifyFix(parsed.filePath, cwd, errorSignature);
+            const verification = await verifyFix(parsed.filePath, cwd, errorSignature, routeContext);
             if (verification.verified) {
               backupManager.markVerified(bid);
               rateLimiter.clearSignature(errorSignature);
@@ -439,6 +467,27 @@ async function tryOperationalFix(parsed, cwd, logger) {
     }
   }
 
+  // Pattern 4: EADDRINUSE — port taken by stale process
+  if (/EADDRINUSE/.test(msg)) {
+    const portMatch = msg.match(/:(\d{2,5})/) || msg.match(/port\s+(\d{2,5})/i);
+    if (portMatch) {
+      const port = parseInt(portMatch[1], 10);
+      try {
+        if (process.platform === "win32") {
+          const out = execSync(`netstat -ano | findstr ":${port}" | findstr "LISTENING"`, { encoding: "utf-8", timeout: 3000 }).trim();
+          const pids = [...new Set(out.split("\n").map(l => parseInt(l.trim().split(/\s+/).pop(), 10)).filter(p => p && p !== process.pid))];
+          for (const pid of pids) { try { execSync(`taskkill /PID ${pid} /F`, { timeout: 3000 }); } catch {} }
+          if (pids.length > 0) return { fixed: true, action: `Killed stale process(es) on port ${port}: PIDs ${pids.join(", ")}` };
+        } else {
+          const out = execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: "utf-8", timeout: 3000 }).trim();
+          const pids = out.split("\n").map(p => parseInt(p, 10)).filter(p => p && p !== process.pid);
+          for (const pid of pids) { try { process.kill(pid, "SIGKILL"); } catch {} }
+          if (pids.length > 0) return { fixed: true, action: `Killed stale process(es) on port ${port}: PIDs ${pids.join(", ")}` };
+        }
+      } catch { /* no stale process found */ }
+    }
+  }
+
   return { fixed: false };
 }