wolverine-ai 4.7.0 → 4.8.0

package/package.json

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

@@ -154,7 +154,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/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,12 +1,17 @@
+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 { AgentEngine } = require("../agent/agent-engine");
 const { ResearchAgent } = require("../agent/research-agent");
@@ -14,6 +19,7 @@ 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 +61,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 +195,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,8 +212,7 @@ 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 relevant skill context (claw-code: pre-enrich prompt with matched tools)
@@ -348,7 +349,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 +554,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 +580,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 +636,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 +667,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 +712,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 +720,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,