wolverine-ai 1.2.0 → 1.3.0

package/README.md

@@ -73,7 +73,7 @@ wolverine/
 │   │   ├── ai-client.js     ← OpenAI client (Chat + Responses API)
 │   │   ├── models.js        ← 10-model configuration system
 │   │   ├── verifier.js      ← Fix verification (syntax + boot probe)
-│   │   ├── error-parser.js  ← Stack trace parsing
+│   │   ├── error-parser.js  ← Stack trace parsing + error classification
 │   │   ├── patcher.js       ← File patching with sandbox
 │   │   ├── health-monitor.js← PM2-style health checks
 │   │   ├── config.js        ← Config loader (settings.json + env)
@@ -140,26 +140,38 @@ wolverine/
 
 ```
 Server crashes
-  → Error parsed (file, line, message)
+  → Error parsed (file, line, message, errorType)
+  → Error classified: missing_module | missing_file | permission | port_conflict | syntax | runtime
   → Secrets redacted from error output
   → Prompt injection scan (AUDIT_MODEL)
   → Human-required check (expired keys, service down → notify, don't waste tokens)
   → Rate limit check (error loop → exponential backoff)
 
+Operational Fix (zero AI tokens):
+  → "Cannot find module 'cors'" → npm install cors (instant, free)
+  → ENOENT on config file → create missing file with defaults
+  → EACCES/EPERM → chmod 755
+  → If operational fix works → done. No AI needed.
+
 Goal Loop (iterate until fixed or exhausted):
   Iteration 1: Fast path (CODING_MODEL, single file, ~1-2k tokens)
-    → Apply patch → Verify (syntax check + boot probe) → Pass? Done.
+    → AI returns code changes AND/OR shell commands (npm install, mkdir, etc.)
+    → Execute commands first, apply patches second
+    → Verify (syntax check + boot probe) → Pass? Done.
   Iteration 2: Single agent (REASONING_MODEL, multi-file, 10 tools)
-    → Explores codebase → Fix → Verify → Pass? Done.
+    → Agent has error pattern → fix strategy table
+    → Uses bash_exec for npm install, chmod, config creation
+    → Uses edit_file for code fixes
+    → Verify → Pass? Done.
   Iteration 3: Sub-agents (explore → plan → fix)
     → Explorer finds relevant files (read-only)
-    → Planner proposes fix strategy (read-only)
-    → Fixer executes the plan (write access)
+    → Planner considers operational vs code fixes
+    → Fixer has bash_exec + file tools (can npm install AND edit code)
     → Deep research (RESEARCH_MODEL) feeds into context
     → Each failure feeds into the next attempt
 
 After fix:
-  → Record to repair history (error, resolution, tokens, cost)
+  → Record to repair history (error, resolution, tokens, cost, mode)
   → Store in brain for future reference
   → Promote backup to stable after 30min uptime
 ```
@@ -199,7 +211,7 @@ For complex repairs, wolverine spawns specialized sub-agents that run in sequenc
 |-------|--------|-------|------|
 | `explore` | Read-only | REASONING | Investigate codebase, find relevant files |
 | `plan` | Read-only | REASONING | Analyze problem, propose fix strategy |
-| `fix` | Read+write | CODING | Execute targeted fix from plan |
+| `fix` | Read+write+shell | CODING | Execute targeted fix — code edits AND npm install/chmod |
 | `verify` | Read-only | REASONING | Check if fix actually works |
 | `research` | Read-only | RESEARCH | Search brain + web for solutions |
 | `security` | Read-only | AUDIT | Audit code for vulnerabilities |
@@ -224,8 +236,7 @@ Real-time web UI at `http://localhost:PORT+1`:
 | **Performance** | Endpoint response times, request rates, error rates |
 | **Command** | Admin chat interface — ask questions or build features |
 | **Analytics** | Memory/CPU charts, route health, per-route response times + trends |
-| **Command** | Admin chat interface — ask questions or build features |
-| **Backups** | Full server/ snapshot history with status badges |
+| **Backups** | Full backup management: rollback/hot-load buttons, undo, rollback log, admin IP allowlist |
 | **Brain** | Vector store stats (23 seed docs), namespace counts, function map |
 | **Repairs** | Error/resolution audit trail: error, fix, tokens, cost, duration |
 | **Tools** | Agent tool harness listing (10 built-in + MCP) |
@@ -241,7 +252,7 @@ Three routes (AI-classified per command):
 | **TOOLS** | TOOL_MODEL | call_endpoint, read_file, search_brain | Live data, file contents |
 | **AGENT** | CODING_MODEL | Full 10-tool harness | Build features, fix code |
 
-Secured with `WOLVERINE_ADMIN_KEY` + localhost-only IP check.
+Secured with `WOLVERINE_ADMIN_KEY` + IP allowlist (localhost + `WOLVERINE_ADMIN_IPS`).
 
 ---
 
@@ -273,7 +284,7 @@ Reasoning models (`o-series`, `gpt-5-nano`) automatically get 4x token limits to
 | **Injection Detector** | Regex layer + AI audit (AUDIT_MODEL) on every error before repair |
 | **Sandbox** | All file operations locked to project directory, symlink escape detection |
 | **Protected Paths** | Agent blocked from modifying wolverine internals (`src/`, `bin/`, etc.) |
-| **Admin Auth** | Dashboard command interface requires key + localhost IP, timing-safe comparison, lockout after 10 failures |
+| **Admin Auth** | Dashboard requires key + IP allowlist. Localhost always allowed. Remote IPs via `WOLVERINE_ADMIN_IPS` env var or `POST /api/admin/add-ip` at runtime. Timing-safe comparison, lockout after 10 failures |
 | **Rate Limiter** | Sliding window, min gap, hourly budget, exponential backoff on error loops |
 | **MCP Security** | Per-server tool allowlists, arg sanitization, result injection scanning |
 | **SQL Skill** | `sqlGuard()` middleware blocks 15 injection pattern families on all endpoints |
@@ -409,14 +420,29 @@ All demos use the `server/` directory pattern. Each demo:
 
 ## Backup System
 
-Full `server/` directory snapshots:
+Full `server/` directory snapshots with lifecycle management:
 
-- Created before every repair attempt and every smart edit
+- Created before every repair attempt and every smart edit (with reason string)
+- Created on graceful shutdown (`createShutdownBackup()`)
 - Includes all files: `.js`, `.json`, `.sql`, `.db`, `.yaml`, configs
 - **Status lifecycle**: UNSTABLE → VERIFIED (fix passed) → STABLE (30min+ uptime)
-- **Retention**: unstable pruned after 7 days, stable keeps 1/day after 7 days
+- **Retention**: unstable/verified pruned after 7 days, stable keeps 1/day after 7 days
 - Atomic writes prevent corruption on kill
 
+**Rollback & Recovery:**
+
+| Action | What it does |
+|--------|-------------|
+| **Rollback** | Restore any backup — creates a pre-rollback safety backup first, restarts server |
+| **Undo Rollback** | Restore the pre-rollback state if the rollback made things worse |
+| **Hot-load** | Load any backup as the current server state from the dashboard |
+| **Rollback Log** | Full audit trail: timestamp, action, target backup, success/failure |
+
+**Dashboard endpoints** (admin auth required):
+- `POST /api/backups/:id/rollback` — rollback to specific backup
+- `POST /api/backups/:id/hotload` — hot-load backup as current state
+- `POST /api/backups/undo` — undo the last rollback
+
 ---
 
 ## Skills

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "1.2.0",
+  "version": "1.3.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

@@ -262,11 +262,27 @@ Use these tools systematically:
 5. You can edit ANY file type: .js, .json, .sql, .yaml, .env, .dockerfile, .sh, etc.
 6. Prefer edit_file for small targeted fixes, write_file for major changes
 7. Use grep_code to find all usages before renaming something
-8. Use bash_exec to run tests or check dependencies
+8. Use bash_exec to run tests, install packages, or check dependencies
+
+CRITICAL — Not every crash is a code bug. Choose the right fix:
+
+| Error Pattern | Root Cause | Correct Fix |
+|---|---|---|
+| Cannot find module 'X' | Missing npm package | bash_exec: npm install X |
+| Cannot find module './X' | Wrong import path | edit_file: fix the require/import path |
+| ENOENT: no such file | Missing config/data file | write_file: create the missing file |
+| EACCES/EPERM | Permission denied | bash_exec: chmod or fix ownership |
+| EADDRINUSE | Port conflict | bash_exec: kill process on port, or edit config |
+| SyntaxError | Bad code | edit_file: fix the syntax |
+| TypeError/ReferenceError | Logic bug | edit_file: fix the code |
+| MODULE_NOT_FOUND + node_modules | Corrupted install | bash_exec: rm -rf node_modules && npm install |
+
+ALWAYS check package.json before editing imports. If a module isn't a local file, use bash_exec to install it.
 
 Rules:
 - Read files before modifying them
 - Make minimal, targeted changes
+- Use bash_exec for operational fixes (npm install, chmod, config creation)
 - When done, call the "done" tool with a summary
 
 Project root: ${this.cwd}

package/src/agent/sub-agents.js

@@ -25,7 +25,7 @@ const { getModel } = require("../core/models");
 const AGENT_TOOL_SETS = {
   explore: ["read_file", "glob_files", "grep_code", "git_log", "git_diff", "done"],
   plan: ["read_file", "glob_files", "grep_code", "search_brain", "done"],
-  fix: ["read_file", "write_file", "edit_file", "glob_files", "grep_code", "done"],
+  fix: ["read_file", "write_file", "edit_file", "glob_files", "grep_code", "bash_exec", "done"],
   verify: ["read_file", "glob_files", "grep_code", "bash_exec", "done"],
   research: ["read_file", "grep_code", "web_fetch", "search_brain", "done"],
   security: ["read_file", "glob_files", "grep_code", "done"],
@@ -46,8 +46,8 @@ const AGENT_CONFIGS = {
 // System prompts per agent type
 const AGENT_PROMPTS = {
   explore: "You are an Explorer agent. Your job is to investigate the codebase and find files relevant to the problem. Read files, search for patterns, check git history. Report what you found — do NOT make changes.",
-  plan: "You are a Planner agent. Your job is to analyze the problem and propose a fix strategy. Read the relevant files, understand the root cause, and describe step-by-step what needs to change. Do NOT make changes.",
-  fix: "You are a Fixer agent. You receive a specific fix plan. Execute it precisely — edit only the files mentioned, make only the changes described. Use edit_file for surgical changes.",
+  plan: "You are a Planner agent. Your job is to analyze the problem and propose a fix strategy. Read the relevant files, understand the root cause, and describe step-by-step what needs to change. Consider: is this a code bug (edit files) or an operational issue (npm install, create missing config, fix permissions)? Check package.json for dependencies. Do NOT make changes.",
+  fix: "You are a Fixer agent. You receive a specific fix plan. Execute it precisely. Use edit_file for code fixes, bash_exec for operational fixes (npm install, chmod, mkdir, config creation). Not every error is a code bug — missing modules need npm install, missing files need creation, permission errors need chmod. Check package.json before editing imports.",
   verify: "You are a Verifier agent. Check if a fix actually works. Read the modified files, look for issues, run tests if available. Report whether the fix is correct.",
   research: "You are a Research agent. Search the brain for past fixes to similar errors, and search the web for solutions. Report your findings.",
   security: "You are a Security agent. Audit the code for vulnerabilities: SQL injection, XSS, path traversal, hardcoded secrets, missing input validation. Report all findings.",

package/src/backup/backup-manager.js

@@ -1,38 +1,24 @@
 const fs = require("fs");
 const path = require("path");
 const chalk = require("chalk");
+const { redact } = require("../security/secret-redactor");
 
 /**
- * Smart Backup Manager — manages versioned backups with stability tracking.
+ * Backup Manager — full server/ directory snapshots with lifecycle management.
  *
- * Backup lifecycle:
- * 1. UNSTABLE: Created when a fix is applied, before verification
- * 2. VERIFIED: The fix ran without immediately crashing (same error)
- * 3. STABLE:   The server ran successfully for STABILITY_THRESHOLD without crashing
+ * Lifecycle: UNSTABLE → VERIFIED → STABLE
+ * Every backup is a complete copy of server/ (code, configs, databases).
+ * Admins can rollback, undo rollbacks, and hot-load any backup state.
  *
- * Retention policy:
- * - Unstable backups: deleted after 7 days
- * - Verified backups: kept for 7 days, then pruned unless promoted to stable
- * - Stable backups:   after 7 days, keep only 1 per day (most recent each day)
- *
- * Storage layout:
- *   .wolverine/
- *     backups/
- *       manifest.json         — tracks all backups with metadata
- *       <timestamp>/          — one directory per backup event
- *         <filename>.bak      — the original file content
+ * Retention: unstable/verified pruned after 7 days.
+ * Stable backups older than 7 days → keep 1 per day (most recent).
  */
 
 const WOLVERINE_DIR = ".wolverine";
 const BACKUPS_DIR = path.join(WOLVERINE_DIR, "backups");
 const MANIFEST_FILE = path.join(BACKUPS_DIR, "manifest.json");
-
-// Stability threshold: how long the server must run without the same crash
-// to consider a fix "stable" (default: 30 minutes)
 const STABILITY_THRESHOLD_MS = 30 * 60 * 1000;
-
-// Retention: unstable/verified backups older than this are pruned
-const RETENTION_UNSTABLE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 
 class BackupManager {
   constructor(projectRoot) {
@@ -44,30 +30,25 @@ class BackupManager {
   }
 
   /**
-   * Create a backup of specific files or the entire server/ directory.
-   * Returns a backupId that can be used to rollback or promote.
-   *
-   * @param {string[]|null} filePaths — specific files, or null to backup entire server/
+   * Create a full server/ backup.
+   * @param {string} reason — why this backup was created
+   * @returns {string} backupId
    */
-  createBackup(filePaths) {
+  createBackup(reason = "manual") {
     const backupId = Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 6);
     const timestamp = Date.now();
     const backupDir = path.join(this.backupsDir, backupId);
     fs.mkdirSync(backupDir, { recursive: true });
 
-    // If no specific files, backup the entire server/ directory
-    if (!filePaths || filePaths.length === 0) {
-      filePaths = this._collectServerFiles();
-    }
-
+    const filePaths = this._collectServerFiles();
     const files = [];
+
     for (const filePath of filePaths) {
       const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(this.projectRoot, filePath);
       if (!fs.existsSync(absPath)) continue;
-      // Skip large files (>10MB) and binary blobs
       try {
         const stat = fs.statSync(absPath);
-        if (stat.size > 10 * 1024 * 1024) continue;
+        if (stat.size > 10 * 1024 * 1024) continue; // skip >10MB
       } catch { continue; }
 
       const relativePath = path.relative(this.projectRoot, absPath);
@@ -85,7 +66,9 @@ class BackupManager {
       id: backupId,
       timestamp,
       status: "unstable",
+      reason: redact(reason),
       files,
+      fileCount: files.length,
       errorSignature: null,
       promotedAt: null,
       verifiedAt: null,
@@ -94,22 +77,29 @@ class BackupManager {
     this.manifest.backups.push(entry);
     this._saveManifest();
 
+    console.log(chalk.gray(`  💾 Backup ${backupId} (${files.length} files) — ${reason}`));
     return backupId;
   }
 
   /**
-   * Rollback to a specific backup.
+   * Rollback to a specific backup. Creates a pre-rollback backup first.
+   * @returns {{ success, preRollbackId }}
    */
   rollbackTo(backupId) {
     const entry = this.manifest.backups.find(b => b.id === backupId);
     if (!entry) {
       console.log(chalk.red(`Backup ${backupId} not found.`));
-      return false;
+      return { success: false };
     }
 
+    // Create a pre-rollback backup so admins can undo
+    const preRollbackId = this.createBackup(`pre-rollback (before restoring ${backupId})`);
+
     let allRestored = true;
     for (const file of entry.files) {
       if (fs.existsSync(file.backup)) {
+        // Ensure parent dir exists
+        fs.mkdirSync(path.dirname(file.original), { recursive: true });
         fs.copyFileSync(file.backup, file.original);
         console.log(chalk.yellow(`  ↩️  Restored: ${file.relative}`));
       } else {
@@ -118,22 +108,64 @@ class BackupManager {
       }
     }
 
-    return allRestored;
+    // Log the rollback
+    if (!this.manifest.rollbackLog) this.manifest.rollbackLog = [];
+    this.manifest.rollbackLog.push({
+      timestamp: Date.now(),
+      restoredBackupId: backupId,
+      preRollbackBackupId: preRollbackId,
+      success: allRestored,
+    });
+    this._saveManifest();
+
+    return { success: allRestored, preRollbackId };
   }
 
   /**
-   * Rollback to the most recent backup (any status).
+   * Rollback the most recent backup.
    */
   rollbackLatest() {
-    if (this.manifest.backups.length === 0) return false;
+    if (this.manifest.backups.length === 0) return { success: false };
     const latest = this.manifest.backups[this.manifest.backups.length - 1];
-    console.log(chalk.yellow(`\n↩️  Rolling back to backup ${latest.id} (${new Date(latest.timestamp).toISOString()})...`));
+    console.log(chalk.yellow(`\n↩️  Rolling back to ${latest.id} (${new Date(latest.timestamp).toISOString()})...`));
     return this.rollbackTo(latest.id);
   }
 
   /**
-   * Mark a backup as verified (fix didn't immediately reproduce the error).
+   * Undo the last rollback — restores the pre-rollback state.
    */
+  undoRollback() {
+    if (!this.manifest.rollbackLog || this.manifest.rollbackLog.length === 0) {
+      console.log(chalk.red("No rollback to undo."));
+      return { success: false };
+    }
+    const lastRollback = this.manifest.rollbackLog[this.manifest.rollbackLog.length - 1];
+    console.log(chalk.yellow(`\n↩️  Undoing rollback — restoring pre-rollback state ${lastRollback.preRollbackBackupId}...`));
+
+    const entry = this.manifest.backups.find(b => b.id === lastRollback.preRollbackBackupId);
+    if (!entry) {
+      console.log(chalk.red("Pre-rollback backup not found."));
+      return { success: false };
+    }
+
+    let allRestored = true;
+    for (const file of entry.files) {
+      if (fs.existsSync(file.backup)) {
+        fs.mkdirSync(path.dirname(file.original), { recursive: true });
+        fs.copyFileSync(file.backup, file.original);
+      } else { allRestored = false; }
+    }
+
+    this.manifest.rollbackLog.push({
+      timestamp: Date.now(),
+      action: "undo",
+      restoredBackupId: lastRollback.preRollbackBackupId,
+      success: allRestored,
+    });
+    this._saveManifest();
+    return { success: allRestored };
+  }
+
   markVerified(backupId) {
     const entry = this.manifest.backups.find(b => b.id === backupId);
     if (entry && entry.status === "unstable") {
@@ -143,9 +175,6 @@ class BackupManager {
     }
   }
 
-  /**
-   * Mark a backup as stable (server ran for the full stability threshold).
-   */
   markStable(backupId) {
     const entry = this.manifest.backups.find(b => b.id === backupId);
     if (entry && (entry.status === "verified" || entry.status === "unstable")) {
@@ -156,163 +185,124 @@ class BackupManager {
     }
   }
 
-  /**
-   * Set the error signature on a backup (for tracking what error this fix addressed).
-   */
   setErrorSignature(backupId, signature) {
     const entry = this.manifest.backups.find(b => b.id === backupId);
-    if (entry) {
-      entry.errorSignature = signature;
-      this._saveManifest();
-    }
+    if (entry) { entry.errorSignature = signature; this._saveManifest(); }
   }
 
   /**
-   * Run the retention policy — prune old backups.
-   *
-   * Rules:
-   * 1. Unstable/verified backups older than 7 days → delete
-   * 2. Stable backups older than 7 days → keep only 1 per day (most recent each day)
-   * 3. All stable backups within 7 days → keep
+   * Shutdown backup — called on graceful server shutdown.
+   */
+  createShutdownBackup() {
+    return this.createBackup("server-shutdown");
+  }
+
+  /**
+   * Get all backups for dashboard.
+   */
+  getAll() {
+    return this.manifest.backups;
+  }
+
+  /**
+   * Get rollback log for dashboard.
+   */
+  getRollbackLog() {
+    return this.manifest.rollbackLog || [];
+  }
+
+  /**
+   * Prune old backups per retention policy.
    */
   prune() {
     const now = Date.now();
-    const cutoff = now - RETENTION_UNSTABLE_MS;
+    const cutoff = now - RETENTION_MS;
     let pruned = 0;
-
-    // Separate backups by status
     const toKeep = [];
     const stableOld = [];
 
     for (const entry of this.manifest.backups) {
       if (entry.status === "stable") {
-        if (entry.timestamp < cutoff) {
-          stableOld.push(entry);
-        } else {
-          toKeep.push(entry);
-        }
+        if (entry.timestamp < cutoff) stableOld.push(entry);
+        else toKeep.push(entry);
       } else {
-        // Unstable or verified
-        if (entry.timestamp < cutoff) {
-          this._deleteBackupFiles(entry);
-          pruned++;
-        } else {
-          toKeep.push(entry);
-        }
+        if (entry.timestamp < cutoff) { this._deleteBackupFiles(entry); pruned++; }
+        else toKeep.push(entry);
       }
     }
 
-    // For old stable backups: keep 1 per day
     if (stableOld.length > 0) {
       const byDay = new Map();
       for (const entry of stableOld) {
         const dayKey = new Date(entry.timestamp).toISOString().slice(0, 10);
-        if (!byDay.has(dayKey)) {
-          byDay.set(dayKey, []);
-        }
+        if (!byDay.has(dayKey)) byDay.set(dayKey, []);
         byDay.get(dayKey).push(entry);
       }
-
       for (const [, dayEntries] of byDay) {
-        // Sort by timestamp descending, keep the newest per day
         dayEntries.sort((a, b) => b.timestamp - a.timestamp);
-        toKeep.push(dayEntries[0]); // keep the most recent
-        for (let i = 1; i < dayEntries.length; i++) {
-          this._deleteBackupFiles(dayEntries[i]);
-          pruned++;
-        }
+        toKeep.push(dayEntries[0]);
+        for (let i = 1; i < dayEntries.length; i++) { this._deleteBackupFiles(dayEntries[i]); pruned++; }
       }
     }
 
     this.manifest.backups = toKeep;
     this._saveManifest();
-
-    if (pruned > 0) {
-      console.log(chalk.gray(`  🧹 Pruned ${pruned} old backup(s).`));
-    }
-
+    if (pruned > 0) console.log(chalk.gray(`  🧹 Pruned ${pruned} old backup(s).`));
     return pruned;
   }
 
-  /**
-   * Get summary stats for logging.
-   */
   getStats() {
     const counts = { unstable: 0, verified: 0, stable: 0 };
     for (const entry of this.manifest.backups) {
       counts[entry.status] = (counts[entry.status] || 0) + 1;
     }
-    return {
-      total: this.manifest.backups.length,
-      ...counts,
-    };
+    return { total: this.manifest.backups.length, ...counts };
   }
 
   // -- Private --
 
-  _ensureDirs() {
-    fs.mkdirSync(this.backupsDir, { recursive: true });
-  }
+  _ensureDirs() { fs.mkdirSync(this.backupsDir, { recursive: true }); }
 
   _loadManifest() {
     if (fs.existsSync(this.manifestPath)) {
-      try {
-        return JSON.parse(fs.readFileSync(this.manifestPath, "utf-8"));
-      } catch {
-        return { version: 1, backups: [] };
-      }
+      try { return JSON.parse(fs.readFileSync(this.manifestPath, "utf-8")); }
+      catch { return { version: 1, backups: [], rollbackLog: [] }; }
     }
-    return { version: 1, backups: [] };
+    return { version: 1, backups: [], rollbackLog: [] };
   }
 
   _saveManifest() {
-    fs.writeFileSync(this.manifestPath, JSON.stringify(this.manifest, null, 2), "utf-8");
+    const tmp = this.manifestPath + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(this.manifest, null, 2), "utf-8");
+    fs.renameSync(tmp, this.manifestPath);
   }
 
   _deleteBackupFiles(entry) {
     const backupDir = path.join(this.backupsDir, entry.id);
     if (fs.existsSync(backupDir)) {
-      for (const file of fs.readdirSync(backupDir)) {
-        fs.unlinkSync(path.join(backupDir, file));
-      }
+      for (const file of fs.readdirSync(backupDir)) fs.unlinkSync(path.join(backupDir, file));
       fs.rmdirSync(backupDir);
     }
   }
 
-  /**
-   * Collect all files in the server/ directory for full backup.
-   * Includes: .js, .json, .sql, .db, .sqlite, .yaml, .yml, .env, .html, .css
-   * Excludes: node_modules, .git, large binaries
-   */
   _collectServerFiles() {
     const serverDir = path.join(this.projectRoot, "server");
     if (!fs.existsSync(serverDir)) return [];
-
     const files = [];
     const SKIP = new Set(["node_modules", ".git", ".wolverine"]);
-    const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
 
     const walk = (dir) => {
       let entries;
       try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-
       for (const entry of entries) {
         if (SKIP.has(entry.name)) continue;
-
         const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          walk(fullPath);
-        } else {
-          try {
-            const stat = fs.statSync(fullPath);
-            if (stat.size <= MAX_FILE_SIZE) {
-              files.push(fullPath);
-            }
-          } catch {}
+        if (entry.isDirectory()) walk(fullPath);
+        else {
+          try { if (fs.statSync(fullPath).size <= 10 * 1024 * 1024) files.push(fullPath); } catch {}
         }
       }
     };
-
     walk(serverDir);
     return files;
   }

package/src/brain/brain.js

@@ -32,11 +32,11 @@ const SEED_DOCS = [
     metadata: { topic: "overview" },
   },
   {
-    text: "Wolverine heal pipeline: crash detected → error parsed (file, line, message) → prompt injection scan (AUDIT_MODEL) → rate limit check → fast path repair (CODING_MODEL via Responses/Chat API) → if fast path fails verification → escalate to multi-file agent (REASONING_MODEL with tools: read_file, write_file, list_files, search_files) → verify fix (syntax check + boot probe) → rollback on failure.",
+    text: "Wolverine heal pipeline: crash detected → error parsed (file, line, message, errorType) → prompt injection scan (AUDIT_MODEL) → rate limit check → operational fix attempt (missing_module → npm install, missing_file → create file, permission → chmod — zero AI tokens) → if operational fix doesn't apply → fast path repair (CODING_MODEL, supports both code changes AND shell commands like npm install) → if fast path fails → agent path (REASONING_MODEL with tools including bash_exec for npm install) → if agent fails → sub-agents (explore → plan → fix, fixer has bash_exec) → verify fix (syntax check + boot probe) → rollback on failure. Error types classified: missing_module, missing_file, permission, port_conflict, syntax, runtime, unknown.",
     metadata: { topic: "heal-pipeline" },
   },
   {
-    text: "Wolverine backup system: every fix creates a backup before patching. Status lifecycle: UNSTABLE (just created) → VERIFIED (fix passed boot probe) → STABLE (server ran 30min+ without crash). Retention: unstable backups pruned after 7 days. Stable backups older than 7 days keep 1 per day.",
+    text: "Wolverine backup system: full server/ directory snapshots with lifecycle management. Every fix creates a backup with a reason string before patching. Status lifecycle: UNSTABLE (just created) → VERIFIED (fix passed boot probe) → STABLE (server ran 30min+ without crash). Features: rollbackTo(backupId) creates pre-rollback backup then restores files and restarts server. undoRollback() restores pre-rollback state. Hot-load: admin can load any backup as current server state from dashboard. Shutdown backup on graceful exit. Retention: unstable/verified pruned after 7 days. Stable backups older than 7 days keep 1 per day. Rollback log tracks all rollback/undo operations with timestamps and success status. Dashboard endpoints: POST /api/backups/:id/rollback, POST /api/backups/undo, POST /api/backups/:id/hotload (all require admin auth).",
     metadata: { topic: "backup-system" },
   },
   {
@@ -108,7 +108,7 @@ const SEED_DOCS = [
     metadata: { topic: "sub-agent-workflow" },
   },
   {
-    text: "Sub-agent tool restrictions (claw-code pattern): explore gets read_file/glob/grep/git. plan gets read_file/glob/grep/brain. fix gets read_file/write_file/edit_file/glob/grep. verify gets read_file/glob/grep/bash. research gets read_file/grep/web_fetch/brain. security gets read_file/glob/grep. database gets read_file/write_file/edit_file/glob/grep/bash. No agent gets tools it doesn't need.",
+    text: "Sub-agent tool restrictions (claw-code pattern): explore gets read_file/glob/grep/git. plan gets read_file/glob/grep/brain. fix gets read_file/write_file/edit_file/glob/grep/bash_exec (bash_exec for npm install, chmod, config creation — not all errors are code bugs). verify gets read_file/glob/grep/bash. research gets read_file/grep/web_fetch/brain. security gets read_file/glob/grep. database gets read_file/write_file/edit_file/glob/grep/bash. No agent gets tools it doesn't need.",
     metadata: { topic: "sub-agent-tools" },
   },
   {
@@ -148,7 +148,7 @@ const SEED_DOCS = [
     metadata: { topic: "npm-package" },
   },
   {
-    text: "Dashboard has 9 panels: Overview (stats cards + recent events), Events (live SSE stream), Performance (endpoint metrics), Analytics (memory/CPU charts, route health, response times), Command (admin chat with 3-route classifier), Backups (server/ snapshots with status badges), Brain (vector store stats + function map), Repairs (error/resolution audit trail with tokens and cost), Tools (agent tool harness listing), Usage (token analytics by model/category/tool with USD costs).",
+    text: "Dashboard has 9 panels: Overview (stats cards + recent events), Events (live SSE stream), Performance (endpoint metrics), Analytics (memory/CPU charts, route health, response times), Command (admin chat with 3-route classifier), Backups (full backup management: stats cards, backup list with rollback/hot-load buttons per entry, reason display, status badges, undo last rollback button, rollback log, admin IP allowlist management), Brain (vector store stats + function map), Repairs (error/resolution audit trail with tokens and cost), Tools (agent tool harness listing), Usage (token analytics by model/category/tool with USD costs).",
     metadata: { topic: "dashboard-panels" },
   },
   {
@@ -195,6 +195,22 @@ const SEED_DOCS = [
     text: "Secret redaction is a singleton: initRedactor(projectRoot) called once on startup, then redact(text), redactObj(obj), hasSecrets(text) available everywhere via require('../security/secret-redactor'). No need to pass redactor instances. Every outbound path auto-redacts: event logger, repair history, telemetry heartbeats, brain memories, AI calls, dashboard output. Env variable values replaced with process.env.KEY_NAME.",
     metadata: { topic: "redaction-singleton" },
   },
+  {
+    text: "Admin auth: two-factor gate — WOLVERINE_ADMIN_KEY (header/cookie/query) + IP allowlist. Localhost always allowed (127.0.0.1, ::1, ::ffff:127.0.0.1). Remote IPs added via WOLVERINE_ADMIN_IPS env var (comma-separated) or POST /api/admin/add-ip at runtime from dashboard. addAllowedIp(ip) adds both IPv4 and IPv4-mapped IPv6. 10 failed attempts = 5min lockout. Timing-safe key comparison. Dashboard stores key as cookie after first auth.",
+    metadata: { topic: "admin-auth" },
+  },
+  {
+    text: "Operational fix layer: before calling AI, wolverine checks for common non-code errors that can be fixed instantly with zero tokens. Pattern 1: 'Cannot find module X' (where X is a package name, not a relative path) → runs npm install X (or just npm install if package is already in package.json). Pattern 2: ENOENT on config/data files (.json, .yaml, .env, .log, etc.) → creates the missing file with sensible defaults (empty JSON {}, empty string). Pattern 3: EACCES/EPERM → chmod 755 on the file. This layer runs before the AI repair loop and handles ~30% of production crashes at zero cost.",
+    metadata: { topic: "operational-fix" },
+  },
+  {
+    text: "Error classification: error-parser.js classifies every crash into a type that guides fix strategy. Types: missing_module (Cannot find module 'X' where X is npm package), missing_file (Cannot find module './X' or ENOENT), permission (EACCES/EPERM), port_conflict (EADDRINUSE), syntax (SyntaxError), runtime (TypeError/ReferenceError/RangeError), unknown. The errorType field is available to all downstream handlers: operational fix, fast path, agent, sub-agents.",
+    metadata: { topic: "error-classification" },
+  },
+  {
+    text: "Agent fix strategy table: the agent system prompt includes a decision table mapping error patterns to correct fix actions. Cannot find module 'X' (package) → bash_exec: npm install X. Cannot find module './X' (local) → edit_file: fix require path. ENOENT → write_file: create missing file. EACCES → bash_exec: chmod. EADDRINUSE → bash_exec: kill process. SyntaxError → edit_file: fix code. TypeError → edit_file: fix logic. MODULE_NOT_FOUND + node_modules → bash_exec: rm -rf node_modules && npm install. The fast path AI response format now supports both 'changes' (code edits) and 'commands' (shell commands like npm install). Dangerous commands blocked: rm -rf /, format, mkfs.",
+    metadata: { topic: "agent-fix-strategy" },
+  },
 ];
 
 class Brain {

package/src/core/ai-client.js

@@ -359,7 +359,11 @@ ${stackTrace}
 
 ## Instructions
 1. Identify the root cause of the error.
-2. Produce a minimal fix — change only what is necessary.
+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
+   - "Cannot find module './X'" = wrong import path → use "changes" to fix the require/import
+   - "ENOENT" = missing file → use "commands" to create it, or "changes" to fix the path
+   - SyntaxError/TypeError/ReferenceError = code bug → use "changes" to fix the code
 3. Respond with ONLY valid JSON in this exact format:
 
 {
@@ -370,8 +374,13 @@ ${stackTrace}
       "old": "the exact lines to replace (copy verbatim from the source)",
       "new": "the replacement lines"
     }
-  ]
-}`;
+  ],
+  "commands": ["npm install cors", "mkdir -p server/config"]
+}
+
+"commands" is an array of shell commands to run (optional, use for npm install, file creation, etc).
+"changes" is for code edits (optional, use for actual code fixes).
+Include both if needed, or just one.`;
 
   const result = await aiCall({ model, systemPrompt, userPrompt, maxTokens: 2048, category: "heal" });
   const content = result.content;

package/src/core/error-parser.js

@@ -75,13 +75,52 @@ function parseError(stderr) {
     filePath = path.resolve(filePath);
   }
 
+  // Classify the error type — helps the heal pipeline choose the right strategy
+  const errorType = classifyError(errorMessage, stderr);
+
   return {
     filePath,
     line,
     column,
     errorMessage,
     stackTrace,
+    errorType,
   };
 }
 
-module.exports = { parseError };
+/**
+ * Classify an error into categories to guide fix strategy.
+ * Returns: "missing_module" | "missing_file" | "permission" | "port_conflict" | "syntax" | "runtime" | "unknown"
+ */
+function classifyError(errorMessage, fullStderr) {
+  const msg = (errorMessage || "").toLowerCase();
+  const full = (fullStderr || "").toLowerCase();
+
+  // Missing npm package: Cannot find module 'cors' (not a relative path)
+  if (/cannot find module '(?![./\\])/.test(msg) || /module_not_found/.test(full)) {
+    return "missing_module";
+  }
+  // Missing local file: Cannot find module './routes/api'
+  if (/cannot find module '[./\\]/.test(msg) || /enoent/.test(msg)) {
+    return "missing_file";
+  }
+  // Permission denied
+  if (/eacces|eperm/.test(msg)) {
+    return "permission";
+  }
+  // Port already in use
+  if (/eaddrinuse/.test(msg)) {
+    return "port_conflict";
+  }
+  // Syntax error
+  if (/syntaxerror|unexpected token|unexpected end/.test(msg)) {
+    return "syntax";
+  }
+  // Runtime errors (TypeError, ReferenceError, RangeError)
+  if (/typeerror|referenceerror|rangeerror/.test(msg)) {
+    return "runtime";
+  }
+  return "unknown";
+}
+
+module.exports = { parseError, classifyError };

package/src/core/runner.js

@@ -235,8 +235,23 @@ class WolverineRunner {
     }
   }
 
+  /**
+   * Graceful shutdown — backup, stop subsystems, kill child cleanly.
+   * Prevents wolverine from treating shutdown as a crash.
+   */
   stop() {
+    if (!this.running) return; // prevent double-stop
     this.running = false;
+    this._shuttingDown = true;
+
+    console.log(chalk.yellow("\n  🔒 Graceful shutdown..."));
+
+    // Create shutdown backup
+    try {
+      this.backupManager.createShutdownBackup();
+    } catch {}
+
+    // Stop all monitors (prevents restart triggers during shutdown)
     this._clearStabilityTimer();
     this.healthMonitor.stop();
     this.perfMonitor.stop();
@@ -247,10 +262,16 @@ class WolverineRunner {
     this.tokenTracker.save();
     this.dashboard.stop();
 
-    this.logger.info(EVENT_TYPES.PROCESS_STOP, "Wolverine stopped");
+    this.logger.info(EVENT_TYPES.PROCESS_STOP, "Wolverine stopped (graceful shutdown)");
 
+    // Kill child — remove exit listener first so it doesn't trigger heal
     if (this.child) {
+      this.child.removeAllListeners("exit");
       this.child.kill("SIGTERM");
+      // Force kill after 3s if it doesn't respond
+      setTimeout(() => {
+        try { if (this.child) this.child.kill("SIGKILL"); } catch {}
+      }, 3000);
       this.child = null;
     }
   }

package/src/core/wolverine.js

@@ -73,6 +73,7 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
   console.log(chalk.cyan(`  File:  ${parsed.filePath}`));
   console.log(chalk.cyan(`  Line:  ${parsed.line || "unknown"}`));
   console.log(chalk.cyan(`  Error: ${parsed.errorMessage}`));
+  console.log(chalk.cyan(`  Type:  ${parsed.errorType || "unknown"}`));
 
   // 3. Rate limit check
   const rateCheck = rateLimiter.check(errorSignature);
@@ -111,6 +112,24 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
     }
   }
 
+  // 4c. Pre-heal operational fix — detect common non-code errors
+  // Some crashes aren't code bugs (missing npm packages, missing config files).
+  // Fix these directly without wasting AI tokens.
+  const opsFix = await tryOperationalFix(parsed, cwd, logger);
+  if (opsFix.fixed) {
+    console.log(chalk.green(`  ⚡ Operational fix applied: ${opsFix.action}`));
+    if (logger) logger.info(EVENT_TYPES.HEAL_SUCCESS, `Operational fix: ${opsFix.action}`, { action: opsFix.action });
+    if (repairHistory) {
+      repairHistory.record({
+        error: parsed.errorMessage, file: parsed.filePath, line: parsed.line,
+        resolution: opsFix.action, success: true, mode: "operational",
+        model: "none", tokens: 0, cost: 0, iteration: 0,
+        duration: Date.now() - healStartTime, filesModified: [],
+      });
+    }
+    return { healed: true, explanation: opsFix.action, mode: "operational" };
+  }
+
   // 5. Read the source file + get brain context
   const sourceCode = sandbox.readFile(parsed.filePath);
 
@@ -164,7 +183,7 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
 
       let result;
       if (iteration === 1) {
-        // Fast path — CODING_MODEL, single file
+        // Fast path — CODING_MODEL, single file + optional commands
         console.log(chalk.yellow(`  🧠 Fast path (${getModel("coding")})...`));
         try {
           const repair = await requestRepair({
@@ -173,13 +192,35 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
           });
           rateLimiter.record(errorSignature);
 
-          const sandboxCheck = sandbox.validateChanges(repair.changes);
-          if (!sandboxCheck.valid) throw new Error("Changes outside sandbox");
+          // 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)) {
+                console.log(chalk.red(`  🛡️ Blocked dangerous command: ${cmd}`));
+                continue;
+              }
+              console.log(chalk.blue(`  ⚡ Running: ${cmd}`));
+              try {
+                execSync(cmd, { cwd, stdio: "pipe", timeout: 60000 });
+                console.log(chalk.green(`  ✅ Command succeeded: ${cmd}`));
+              } catch (cmdErr) {
+                console.log(chalk.yellow(`  ⚠️ Command failed: ${cmd} — ${cmdErr.message?.slice(0, 80)}`));
+              }
+            }
+          }
 
-          const patchResults = applyPatch(repair.changes, cwd, sandbox);
-          if (!patchResults.every(r => r.success)) throw new Error("Patch failed");
+          // Apply code changes (if any)
+          if (repair.changes && repair.changes.length > 0) {
+            const sandboxCheck = sandbox.validateChanges(repair.changes);
+            if (!sandboxCheck.valid) throw new Error("Changes outside sandbox");
 
-          for (const r of patchResults) console.log(chalk.green(`  ✅ Patched: ${r.file}`));
+            const patchResults = applyPatch(repair.changes, cwd, sandbox);
+            if (!patchResults.every(r => r.success)) throw new Error("Patch failed");
+
+            for (const r of patchResults) console.log(chalk.green(`  ✅ Patched: ${r.file}`));
+          }
 
           const verification = await verifyFix(parsed.filePath, cwd, errorSignature);
           if (verification.verified) {
@@ -287,4 +328,82 @@ async function heal({ stderr, cwd, sandbox, notifier, rateLimiter, backupManager
   return { healed: false, explanation: goalResult.explanation };
 }
 
+/**
+ * Try to fix common operational errors without AI.
+ * Returns { fixed: boolean, action: string }
+ */
+async function tryOperationalFix(parsed, cwd, logger) {
+  const { execSync } = require("child_process");
+  const msg = parsed.errorMessage || "";
+
+  // Pattern 1: Cannot find module 'X' — missing npm package
+  const missingModule = msg.match(/Cannot find module '([^']+)'/);
+  if (missingModule) {
+    const moduleName = missingModule[1];
+
+    // Only npm install if it's a package name (not a relative/absolute path)
+    if (!moduleName.startsWith(".") && !moduleName.startsWith("/") && !moduleName.startsWith("\\")) {
+      // Check if it's already in package.json but not installed
+      const fs = require("fs");
+      const path = require("path");
+      const pkgPath = path.join(cwd, "package.json");
+      let isInPkg = false;
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        isInPkg = !!allDeps[moduleName];
+      } catch {}
+
+      try {
+        const cmd = isInPkg ? "npm install" : `npm install ${moduleName}`;
+        console.log(chalk.blue(`  📦 Missing module '${moduleName}' — running: ${cmd}`));
+        if (logger) logger.info("heal.ops", `Running: ${cmd}`, { module: moduleName });
+        execSync(cmd, { cwd, stdio: "pipe", timeout: 60000 });
+        return { fixed: true, action: `Installed missing module '${moduleName}' via: ${cmd}` };
+      } catch (e) {
+        console.log(chalk.yellow(`  ⚠️ npm install failed: ${e.message?.slice(0, 100)}`));
+        // Fall through to AI repair
+      }
+    }
+  }
+
+  // Pattern 2: ENOENT on config/data files the server expects
+  const enoent = msg.match(/ENOENT.*?'([^']+)'/);
+  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, "/");
+    if (!rel.startsWith("..") && /\.(json|yaml|yml|toml|ini|conf|cfg|env|log|txt|csv|db|sqlite)$/i.test(missingFile)) {
+      try {
+        fs.mkdirSync(path.dirname(missingFile), { recursive: true });
+        // Create empty file or sensible default
+        const ext = path.extname(missingFile).toLowerCase();
+        const defaults = { ".json": "{}", ".yaml": "", ".yml": "", ".log": "", ".txt": "", ".csv": "", ".env": "" };
+        fs.writeFileSync(missingFile, defaults[ext] || "", "utf-8");
+        console.log(chalk.blue(`  📄 Created missing file: ${rel}`));
+        return { fixed: true, action: `Created missing file: ${rel}` };
+      } catch {}
+    }
+  }
+
+  // Pattern 3: EACCES/EPERM permission errors
+  const permErr = /EACCES|EPERM/.test(msg);
+  if (permErr) {
+    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]}` };
+      } catch {}
+    }
+  }
+
+  return { fixed: false };
+}
+
 module.exports = { heal };

package/src/dashboard/server.js

@@ -68,6 +68,10 @@ class DashboardServer {
       if (req.url === "/api/usage/history") return this._handleUsageHistory(req, res);
       if (req.url === "/api/auth/verify" && req.method === "POST") return this._handleAuthVerify(req, res);
       if (req.url === "/api/command" && req.method === "POST") return this._handleCommand(req, res);
+      if (req.url.startsWith("/api/backups/") && req.url.endsWith("/rollback") && req.method === "POST") return this._handleRollback(req, res);
+      if (req.url === "/api/backups/undo" && req.method === "POST") return this._handleUndoRollback(req, res);
+      if (req.url.startsWith("/api/backups/") && req.url.endsWith("/hotload") && req.method === "POST") return this._handleHotload(req, res);
+      if (req.url === "/api/admin/add-ip" && req.method === "POST") return this._handleAddIp(req, res);
       if (req.url === "/api/chat/clear" && req.method === "POST") {
         this._chatHistory = [];
         res.writeHead(200, { "Content-Type": "application/json" });
@@ -432,7 +436,7 @@ ${existingRoutes || "(none)"}`,
 
     // Backup entire server/ before making changes
     if (this.runner && this.runner.backupManager) {
-      const bid = this.runner.backupManager.createBackup(null);
+      const bid = this.runner.backupManager.createBackup("pre-edit: " + safeCommand.slice(0, 80));
       this.runner.backupManager.markVerified(bid);
       console.log(chalk.gray(`  💾 Backup created: ${bid}`));
     }
@@ -875,7 +879,132 @@ ${context ? "\nBrain:\n" + context : ""}`,
 
   _handleBackups(req, res) {
     res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify(this.backupManager ? this.backupManager.manifest.backups : []));
+    if (this.backupManager) {
+      res.end(JSON.stringify({
+        backups: this.backupManager.getAll(),
+        rollbackLog: this.backupManager.getRollbackLog(),
+        stats: this.backupManager.getStats(),
+      }));
+    } else {
+      res.end(JSON.stringify({ backups: [], rollbackLog: [], stats: {} }));
+    }
+  }
+
+  // ── Backup Management Endpoints ──
+
+  _handleRollback(req, res) {
+    const authResult = this.auth.validate(req);
+    if (!authResult.authorized) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Forbidden", reason: authResult.reason }));
+      return;
+    }
+
+    const backupId = req.url.replace("/api/backups/", "").replace("/rollback", "");
+    if (!this.backupManager) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Backup manager not available" }));
+      return;
+    }
+
+    const result = this.backupManager.rollbackTo(backupId);
+    if (result.success && this.runner) {
+      console.log(chalk.blue("  🔄 Restarting server after rollback..."));
+      this.runner.restart();
+    }
+    if (this.logger) {
+      this.logger.info("backup.rollback", `Rolled back to ${backupId}`, { backupId, preRollbackId: result.preRollbackId, success: result.success });
+    }
+    this._broadcast({ type: "backup.rollback", timestamp: Date.now(), message: `Rolled back to ${backupId}`, severity: "warn" });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(result));
+  }
+
+  _handleUndoRollback(req, res) {
+    const authResult = this.auth.validate(req);
+    if (!authResult.authorized) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Forbidden", reason: authResult.reason }));
+      return;
+    }
+
+    if (!this.backupManager) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Backup manager not available" }));
+      return;
+    }
+
+    const result = this.backupManager.undoRollback();
+    if (result.success && this.runner) {
+      console.log(chalk.blue("  🔄 Restarting server after undo rollback..."));
+      this.runner.restart();
+    }
+    if (this.logger) {
+      this.logger.info("backup.undo", "Undo rollback", { success: result.success });
+    }
+    this._broadcast({ type: "backup.undo", timestamp: Date.now(), message: "Undo rollback executed", severity: "warn" });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(result));
+  }
+
+  _handleHotload(req, res) {
+    const authResult = this.auth.validate(req);
+    if (!authResult.authorized) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Forbidden", reason: authResult.reason }));
+      return;
+    }
+
+    const backupId = req.url.replace("/api/backups/", "").replace("/hotload", "");
+    if (!this.backupManager) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Backup manager not available" }));
+      return;
+    }
+
+    // Hot-load: rollback to the backup state and restart immediately
+    const entry = this.backupManager.manifest.backups.find(b => b.id === backupId);
+    if (!entry) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Backup not found" }));
+      return;
+    }
+
+    const result = this.backupManager.rollbackTo(backupId);
+    if (result.success && this.runner) {
+      console.log(chalk.blue(`  ⚡ Hot-loading backup ${backupId}...`));
+      this.runner.restart();
+    }
+    if (this.logger) {
+      this.logger.info("backup.hotload", `Hot-loaded backup ${backupId}`, { backupId, success: result.success });
+    }
+    this._broadcast({ type: "backup.hotload", timestamp: Date.now(), message: `Hot-loaded backup ${backupId}`, severity: "info" });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ ...result, hotloaded: true }));
+  }
+
+  _handleAddIp(req, res) {
+    const authResult = this.auth.validate(req);
+    if (!authResult.authorized) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Forbidden", reason: authResult.reason }));
+      return;
+    }
+
+    this._readBody(req, (body) => {
+      const ip = (body.ip || "").trim();
+      if (!ip || !/^[\d.:a-fA-F]+$/.test(ip)) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid IP address" }));
+        return;
+      }
+      this.auth.addAllowedIp(ip);
+      if (this.logger) {
+        this.logger.info("admin.add_ip", `Added allowed IP: ${ip}`, { ip });
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ success: true, ip, allowedIps: [...this.auth._allowedIps] }));
+    });
   }
 
   _handleUsage(req, res) {
@@ -1119,7 +1248,30 @@ main{overflow-y:auto;padding:24px}
     </div>
   </div>
 </div>
-<div class="panel" id="p-backups"><div class="card"><h3>Backup History</h3><div id="bk-list"><div class="empty">No backups</div></div></div></div>
+<div class="panel" id="p-backups">
+  <div class="stats" style="grid-template-columns:repeat(4,1fr)">
+    <div class="stat-card up"><div class="stat-val" id="bk-total">0</div><div class="stat-lbl">Total Backups</div></div>
+    <div class="stat-card heal"><div class="stat-val" id="bk-stable">0</div><div class="stat-lbl">Stable</div></div>
+    <div class="stat-card brain"><div class="stat-val" id="bk-verified">0</div><div class="stat-lbl">Verified</div></div>
+    <div class="stat-card roll"><div class="stat-val" id="bk-rollbacks">0</div><div class="stat-lbl">Rollbacks</div></div>
+  </div>
+  <div class="card" style="margin-top:16px">
+    <h3 style="display:flex;justify-content:space-between;align-items:center">Backup Management <button onclick="undoRollback()" id="undo-btn" style="display:none;background:var(--yellow);color:#000;border:none;border-radius:6px;padding:6px 14px;cursor:pointer;font-size:.75rem">↩ Undo Last Rollback</button></h3>
+    <div id="bk-list"><div class="empty">No backups</div></div>
+  </div>
+  <div class="card" style="margin-top:16px">
+    <h3>Rollback Log</h3>
+    <div id="bk-rlog"><div class="empty">No rollbacks performed</div></div>
+  </div>
+  <div class="card" style="margin-top:16px">
+    <h3>Admin IP Allowlist</h3>
+    <div style="display:flex;gap:8px;margin-bottom:12px">
+      <input type="text" id="ip-input" placeholder="e.g. 203.0.113.42" style="flex:1;padding:10px 14px;background:var(--bg);border:1px solid var(--border);border-radius:8px;color:var(--text);font-size:.85rem">
+      <button onclick="addAdminIp()" style="background:var(--accent);color:#fff;border:none;border-radius:8px;padding:10px 18px;cursor:pointer;font-size:.85rem">Add IP</button>
+    </div>
+    <div id="ip-list"><div class="empty">Only localhost by default</div></div>
+  </div>
+</div>
 <div class="panel" id="p-brain">
   <div class="card"><h3>Brain Statistics</h3><div class="ns-grid" id="br-ns"></div></div>
   <div class="card" style="margin-top:16px"><h3>Function Map</h3><div id="br-fmap"><div class="empty">Loading...</div></div></div>
@@ -1252,8 +1404,24 @@ async function refresh(){
     if(brn.functionMap){const fm=brn.functionMap;$('br-fmap').innerHTML=['Routes:'+fm.routes,'Functions:'+fm.functions,'Classes:'+fm.classes,'Files:'+fm.files].map(x=>'<div class="mrow"><span>'+x.split(':')[0]+'</span><span class="vals"><b>'+x.split(':')[1]+'</b></span></div>').join('');}
     const eps=Object.entries(mr);const mh=eps.length?eps.map(([p,m])=>'<div class="mrow"><span class="ep">'+esc(p)+'</span><span class="vals"><b>'+m.avgResponseMs+'ms</b> avg &middot; '+m.requestsPerMin+' req/min &middot; '+m.errorRate+'% err</span></div>').join(''):'<div class="empty">No traffic yet</div>';
     $('ov-metrics').innerHTML=mh;$('perf-list').innerHTML=mh;
-    const bh=br2.length?br2.slice(-15).reverse().map(b=>'<div class="mrow"><span>'+new Date(b.timestamp).toLocaleString()+'</span><span><span class="badge badge-'+b.status+'">'+b.status+'</span> '+b.files.length+' file(s)</span></div>').join(''):'<div class="empty">No backups</div>';
-    $('ov-backups').innerHTML=bh;$('bk-list').innerHTML=bh;
+    const bkData=br2;const bkList=bkData.backups||[];const bkRlog=bkData.rollbackLog||[];const bkStats=bkData.stats||{};
+    $('bk-total').textContent=bkStats.total||0;$('bk-stable').textContent=bkStats.stable||0;$('bk-verified').textContent=bkStats.verified||0;$('bk-rollbacks').textContent=bkRlog.length;
+    if(bkRlog.length>0)$('undo-btn').style.display='inline-block';else $('undo-btn').style.display='none';
+    const ovBh=bkList.length?bkList.slice(-10).reverse().map(b=>'<div class="mrow"><span>'+new Date(b.timestamp).toLocaleString()+'</span><span><span class="badge badge-'+b.status+'">'+b.status+'</span> '+b.fileCount+' file(s)</span></div>').join(''):'<div class="empty">No backups</div>';
+    $('ov-backups').innerHTML=ovBh;
+    const bkFull=bkList.length?bkList.slice(-20).reverse().map(b=>{
+      const age=Math.round((Date.now()-b.timestamp)/60000);const ageStr=age<60?age+'m ago':Math.round(age/60)+'h ago';
+      const reason=b.reason?esc(b.reason):'<i>no reason</i>';
+      const btns=adminKey?'<span style="margin-left:auto;display:flex;gap:4px"><button onclick="rollbackTo(\''+b.id+'\')" style="background:var(--yellow);color:#000;border:none;border-radius:4px;padding:3px 8px;cursor:pointer;font-size:.7rem" title="Rollback to this state">↩ Rollback</button><button onclick="hotload(\''+b.id+'\')" style="background:var(--accent);color:#fff;border:none;border-radius:4px;padding:3px 8px;cursor:pointer;font-size:.7rem" title="Hot-load this backup as current server">⚡ Hot-load</button></span>':'';
+      return '<div class="mrow" style="flex-wrap:wrap;gap:6px"><span style="min-width:140px">'+new Date(b.timestamp).toLocaleString()+'</span><span class="badge badge-'+b.status+'">'+b.status+'</span><span style="color:var(--text2);font-size:.75rem">'+reason+'</span><span style="color:var(--text2);font-size:.7rem">'+b.fileCount+' files &middot; '+ageStr+'</span>'+btns+'</div>';
+    }).join(''):'<div class="empty">No backups</div>';
+    $('bk-list').innerHTML=bkFull;
+    const rlogHtml=bkRlog.length?bkRlog.slice(-10).reverse().map(r=>{
+      const action=r.action==='undo'?'<span style="color:var(--yellow)">UNDO</span>':'<span style="color:var(--accent)">ROLLBACK</span>';
+      const status=r.success?'<span style="color:var(--green)">OK</span>':'<span style="color:var(--red)">FAIL</span>';
+      return '<div class="mrow"><span>'+new Date(r.timestamp).toLocaleString()+'</span><span>'+action+' &rarr; '+esc(r.restoredBackupId||'')+'</span><span>'+status+'</span></div>';
+    }).join(''):'<div class="empty">No rollbacks performed</div>';
+    $('bk-rlog').innerHTML=rlogHtml;
     // Usage analytics
     if(usage&&usage.session){
       $('u-total').textContent=(usage.session.totalTokens||0).toLocaleString();
@@ -1406,6 +1574,57 @@ const tools=[{n:'read_file',d:'Read file with offset/limit',c:'file'},{n:'write_
 const cc={file:'var(--blue)',shell:'var(--yellow)',web:'var(--purple)',ctrl:'var(--green)'};
 $('tool-list').innerHTML=tools.map(t=>'<div class="mrow"><span class="ep" style="color:'+cc[t.c]+'">'+t.n+'</span><span class="vals">'+esc(t.d)+'</span></div>').join('');
 
+async function rollbackTo(id){
+  if(!adminKey){alert('Authenticate first');return;}
+  if(!confirm('Rollback to backup '+id+'? This will restore all server files to that state and restart.'))return;
+  try{
+    const r=await fetch(B+'/api/backups/'+id+'/rollback',{method:'POST',headers:{'Content-Type':'application/json','X-Admin-Key':adminKey}});
+    const d=await r.json();
+    if(d.success){alert('Rolled back to '+id+'. Server restarting... Pre-rollback backup: '+d.preRollbackId);}
+    else{alert('Rollback failed: '+(d.error||'unknown'));}
+    refresh();
+  }catch(e){alert('Error: '+e.message);}
+}
+
+async function hotload(id){
+  if(!adminKey){alert('Authenticate first');return;}
+  if(!confirm('Hot-load backup '+id+' as current server state? This will replace all server files and restart.'))return;
+  try{
+    const r=await fetch(B+'/api/backups/'+id+'/hotload',{method:'POST',headers:{'Content-Type':'application/json','X-Admin-Key':adminKey}});
+    const d=await r.json();
+    if(d.success){alert('Hot-loaded '+id+'. Server restarting...');}
+    else{alert('Hot-load failed: '+(d.error||'unknown'));}
+    refresh();
+  }catch(e){alert('Error: '+e.message);}
+}
+
+async function undoRollback(){
+  if(!adminKey){alert('Authenticate first');return;}
+  if(!confirm('Undo the last rollback? This will restore the pre-rollback state and restart.'))return;
+  try{
+    const r=await fetch(B+'/api/backups/undo',{method:'POST',headers:{'Content-Type':'application/json','X-Admin-Key':adminKey}});
+    const d=await r.json();
+    if(d.success){alert('Rollback undone. Server restarting...');}
+    else{alert('Undo failed: '+(d.error||'unknown'));}
+    refresh();
+  }catch(e){alert('Error: '+e.message);}
+}
+
+async function addAdminIp(){
+  if(!adminKey){alert('Authenticate first');return;}
+  const ip=$('ip-input').value.trim();
+  if(!ip){alert('Enter an IP address');return;}
+  try{
+    const r=await fetch(B+'/api/admin/add-ip',{method:'POST',headers:{'Content-Type':'application/json','X-Admin-Key':adminKey},body:JSON.stringify({ip})});
+    const d=await r.json();
+    if(d.success){
+      $('ip-input').value='';
+      $('ip-list').innerHTML=(d.allowedIps||[]).map(x=>'<div class="mrow"><span>'+esc(x)+'</span></div>').join('');
+      alert('IP '+ip+' added to allowlist');
+    }else{alert('Failed: '+(d.error||'unknown'));}
+  }catch(e){alert('Error: '+e.message);}
+}
+
 refresh();setInterval(refresh,5000);
 fetch(B+'/api/events').then(r=>r.json()).then(evs=>evs.forEach(addEvent)).catch(()=>{});
 </script></body></html>`;

package/src/security/admin-auth.js

@@ -22,9 +22,21 @@ const LOCALHOST_IPS = new Set([
 class AdminAuth {
   constructor() {
     this.adminKey = process.env.WOLVERINE_ADMIN_KEY || null;
-    this._failedAttempts = new Map(); // ip → { count, lastAttempt }
+    // Allowed IPs: localhost always + any IPs in WOLVERINE_ADMIN_IPS (comma-separated)
+    this._allowedIps = new Set(LOCALHOST_IPS);
+    if (process.env.WOLVERINE_ADMIN_IPS) {
+      for (const ip of process.env.WOLVERINE_ADMIN_IPS.split(",")) {
+        this._allowedIps.add(ip.trim());
+      }
+    }
+    this._failedAttempts = new Map();
     this._maxFailedAttempts = 10;
-    this._lockoutMs = 300000; // 5 min lockout after max failures
+    this._lockoutMs = 300000;
+
+    if (!this.adminKey) {
+      console.log("\x1b[33m  ⚠️  No WOLVERINE_ADMIN_KEY set — generate one:\x1b[0m");
+      console.log("\x1b[90m     node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"\x1b[0m");
+    }
   }
 
   /**
@@ -91,9 +103,16 @@ class AdminAuth {
   }
 
   _isLocalhost(ip) {
-    // Normalize IPv6-mapped IPv4
     const normalized = ip.replace(/^::ffff:/, "");
-    return LOCALHOST_IPS.has(ip) || LOCALHOST_IPS.has(normalized) || normalized === "127.0.0.1";
+    return this._allowedIps.has(ip) || this._allowedIps.has(normalized);
+  }
+
+  /**
+   * Add an IP to the allowlist at runtime (from dashboard).
+   */
+  addAllowedIp(ip) {
+    this._allowedIps.add(ip.trim());
+    this._allowedIps.add("::ffff:" + ip.trim());
   }
 
   _extractKey(req) {