wolverine-ai 3.0.1 → 3.1.1

package/.env.example

@@ -0,0 +1,20 @@
+# Wolverine — Secrets Only
+# Copy to .env.local and fill in your keys.
+# All other settings are in server/config/settings.json
+
+# ── API Keys ─────────────────────────────────────────────────────
+# Your OpenAI API key (required)
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+# ── Dashboard Admin Key  (make your own) ──────────────────────────────────────────
+# Required for the agent command interface on the dashboard.
+# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+WOLVERINE_ADMIN_KEY=
+
+# ── Custom Secrets ───────────────────────────────────────────────
+# Add any secret here — wolverine automatically redacts its value
+# from all AI calls, logs, brain storage, and dashboard output.
+#
+# DATABASE_URL=postgres://user:pass@host:5432/db
+# JWT_SECRET=my-secret
+# STRIPE_SECRET_KEY=sk_live_xxx

package/CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+Wolverine is a self-healing Node.js server framework. It wraps a server process, catches crashes AND caught 500 errors, diagnoses them with AI (OpenAI or Anthropic), generates fixes, verifies them, and restarts — automatically. Published as `wolverine-ai` on npm (v3.1.0). 65 exports, 83 files, 6 skills.
+
+## Commands
+
+```bash
+npm start                        # Run server/index.js under wolverine (self-healing)
+npm run server                   # Run server/index.js directly (no healing)
+npm run test:pentest             # Security scan for secret leakage
+npm run demo:list                # List demo scenarios
+npm run demo -- 01               # Run specific demo
+npx wolverine server/index.js    # CLI entry point
+wolverine --info                 # System detection
+wolverine --update               # Safe framework upgrade
+wolverine --backup "reason"      # Create server snapshot
+wolverine --list-backups         # Show all snapshots
+wolverine --rollback <id>        # Restore specific backup
+wolverine --rollback-latest      # Restore most recent
+```
+
+No standard test runner — demos in `tests/fixtures/` serve as integration tests.
+
+## Architecture
+
+### Heal Pipeline (src/core/wolverine.js)
+
+```
+Error detected (crash OR caught 500 via IPC)
+  → Empty stderr? → Just restart, no AI ($0.00)
+  → Parse error → classify type → redact secrets
+  → Injection scan (skip if < 20 chars)
+  → Loop guard: same error failed 3+ times in 10min? → File bug report, stop
+  → Rate limit: 5 heals per 5min max
+  → Operational fix (zero tokens):
+      missing_module → deps.diagnose() → npm install
+      EADDRINUSE → kill stale process
+      ENOENT → create missing file
+      EACCES → chmod
+  → Token budget by complexity: simple=20K, moderate=50K, complex=100K
+  → Goal Loop (3 iterations):
+      1. Fast path: CODING_MODEL, JSON with code+commands, backup diff context
+      2. Agent: dynamic prompt (400 tokens simple, 1200 complex), 18 tools
+      3. Sub-agents: explore→plan→fix (Haiku triage, Sonnet/Opus fix only)
+  → Verify: syntax → boot probe (route probe skipped — ErrorMonitor is safety net)
+  → Success: retryCount reset, record to brain with full context
+  → Fail: rollback, brain records "DO NOT REPEAT", next iteration
+```
+
+`heal()` wraps `_healImpl()` with 5-minute `Promise.race` timeout.
+
+### IPC Error Chain (caught 500s without crash)
+
+1. **error-hook.js** — preloaded via `--require`, patches Fastify/Express for IPC. WeakSet dedup.
+2. **runner.js** — spawns child with `stdio: ["inherit","inherit","pipe","ipc"]`, listens `child.on("message")`
+3. **error-monitor.js** — tracks errors per normalized route (`/api/users/123` → `/api/users/:id`), threshold=1, 60s cooldown. Health check failures also trigger heal.
+
+### AI Client (src/core/ai-client.js)
+
+Dual provider: OpenAI + Anthropic. Auto-detected from model name (`claude-*` → Anthropic). All responses normalized to `{content, toolCalls, usage}`. **Anthropic prompt caching** — system prompt marked `cache_control: ephemeral`, 90% cheaper on repeat calls. Per-model output limits with 10% buffer. Every call tracked: latencyMs, success/failure, tokens, cost.
+
+Embeddings always use OpenAI (Anthropic has no embedding API).
+
+### Agent (src/agent/agent-engine.js)
+
+**Dynamic system prompt**: simple errors (TypeError/ReferenceError) get 400-token compact prompt with 7 tools. Complex errors get full prompt with all 18 tools + strategy table.
+
+18 tools: file (read/write/edit/glob/grep/list_dir/move_file), shell (bash_exec/git_log/git_diff), database (inspect_db/run_db_fix), diagnostics (check_port/check_env), deps (audit_deps/check_migration), research (web_fetch), control (done).
+
+**Cost optimizations**: zero-cost structural compaction (no LLM, extracts signals from messages), tool result truncation (4K cap), token estimation (`text.length/4`), pre/post tool hooks (`.wolverine/hooks.json`), error-graceful tools (`[ERROR]` results not thrown).
+
+**Protected paths**: agent cannot modify `src/`, `bin/`, `tests/`, `node_modules/`, `.env`, `package.json`. Only `server/` is editable.
+
+### Provider Config (server/config/settings.json)
+
+```json
+{ "provider": "hybrid", "openai_settings": {...}, "anthropic_settings": {...}, "hybrid_settings": {...} }
+```
+
+Config loader reads `{provider}_settings`. Env vars override per-role. Missing config sections auto-patched on startup via `_ensureDefaults()`.
+
+### Brain (src/brain/vector-store.js + brain.js)
+
+IVF-indexed vector store: k-means++ clustering, BM25 keyword search, binary persistence. 60 seed docs. Benchmarks: 100=0.2ms, 10K=4.4ms, 50K=23.7ms.
+
+**Namespace isolation**: error heals search only `errors/fixes/learnings/functions` — seed docs (20K tokens) excluded unless query is about wolverine itself. Function map hash check skips re-embedding if unchanged.
+
+### Backup (src/backup/backup-manager.js)
+
+All backups in `~/.wolverine-safe-backups/` (outside project, survives git pull/npm install). States: UNSTABLE → VERIFIED → STABLE (30min). Protected files never rolled back: `settings.json`, `db.js`, `.env.local`.
+
+### Skills (src/skills/ — 6 files)
+
+- **sql.js** — injection prevention, SafeDB, idempotency guard
+- **deps.js** — dependency diagnosis (zero tokens), npm audit, migration paths
+- **update.js** — safe framework upgrade, emergency backup, brain seed merge
+- **backup.js** — agent-friendly backup/rollback with CLI commands
+- **loop-guard.js** — infinite loop detection, bug reports, process dedup (PID file)
+- **skill-registry.js** — auto-discovery + token-scored matching
+
+### Telemetry (src/platform/)
+
+Heartbeats every 60s. Stable instance ID (persisted to `.wolverine/instance-id`). Cumulative usage from disk (not session-only). `byModel` with latency/success/tokens-per-sec/cost-per-call. `byProvider` aggregated. Auto-update checks every 5min, selective git checkout (never touches `server/`).
+
+## Key Constraints
+
+- **Server port is always 3000.** Any other port breaks APIs. Kill 3000 and bind there.
+- **Dashboard on PORT+1** (3001).
+- **heal() has 5-minute timeout.** `Promise.race` recovery.
+- **Global rate limit: 5 heals per 5 minutes.**
+- **Loop guard: 3 failed heals on same error in 10min → stop + bug report.**
+- **Error threshold: 1** — single 500 triggers heal. 60s cooldown per route.
+- **Empty stderr → just restart, no AI.** Prevents token burn on signal kills.
+- **bash_exec: 30s default, 60s cap.**
+- **Process dedup via PID file.** Kills old process on startup.
+- **Both API keys needed for hybrid mode** — OPENAI_API_KEY for embeddings.
+- **Auto-update: selective git checkout** — only updates `src/`, `bin/`, `package.json`. Never touches `server/`.
+- **Rollback protects:** `settings.json`, `db.js`, `.env.local` never overwritten.
+
+## Configuration
+
+- **Secrets:** `.env.local` (OPENAI_API_KEY, ANTHROPIC_API_KEY, WOLVERINE_ADMIN_KEY)
+- **Settings:** `server/config/settings.json` — provider, 3 model presets, cluster, telemetry, rate limits, health checks, autoUpdate, errorMonitor
+- **10 model slots:** reasoning, coding, chat, tool, classifier, audit, compacting, research, embedding
+- **Config priority:** env vars > `{provider}_settings` > defaults
+
+## Files That Matter Most
+
+| File | Why |
+|------|-----|
+| `src/core/wolverine.js` | Heal pipeline, operational fixes, goal loop, token budgets |
+| `src/core/runner.js` | Process manager, IPC, health/error monitors, loop guard, auto-update |
+| `src/core/ai-client.js` | Dual provider, prompt caching, output limits, latency tracking |
+| `src/agent/agent-engine.js` | Dynamic prompt, 18 tools, zero-cost compaction, hooks |
+| `src/agent/sub-agents.js` | Dynamic token budgets, Haiku triage, restricted tool sets |
+| `src/core/verifier.js` | Syntax + boot probe, error classification comparison |
+| `src/brain/vector-store.js` | IVF + BM25 + binary persistence |
+| `src/brain/brain.js` | 60 seed docs, namespace isolation, function map hash |
+| `src/skills/loop-guard.js` | Infinite loop detection, bug reports, process dedup |
+| `src/skills/update.js` | Safe upgrade, emergency backup, brain seed merge |
+| `src/platform/auto-update.js` | Version lock, dep verification, max 1 attempt per boot |
+| `server/config/settings.json` | Provider selection, 3 model presets, all config |

package/README.md

@@ -450,6 +450,8 @@ Three layers prevent token waste:
 
 | Technique | What it does | Cost |
 |-----------|-------------|------|
+| **Dynamic system prompt** | Simple errors get 400-token prompt with 7 tools. Complex get 1200 with 18 + strategy | 50% on 70% of heals |
+| **Brain namespace isolation** | Seed docs (20K tokens) excluded from error heals — only searched for wolverine queries | 50% context reduction |
 | **Prompt caching** | Anthropic system prompt cached server-side — 90% cheaper on repeat calls | 12-16K tokens saved per heal |
 | **Tool result truncation** | Tool output capped at 4K chars — prevents context blowup from large reads | Up to 30K saved per turn |
 | **Zero-cost compaction** | Extracts structural signals (tools, files, errors) from history — no LLM call | $0.00 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "description": "Self-healing Node.js server framework powered by AI. Catches crashes, diagnoses errors, generates fixes, verifies, and restarts — automatically.",
   "main": "src/index.js",
   "bin": {
@@ -49,10 +49,9 @@
     "src/",
     "server/",
     "examples/",
-    "PLATFORM.md",
-    "TELEMETRY.md",
-    "SERVER_BEST_PRACTICES.md",
-    "README.md"
+    "README.md",
+    "CLAUDE.md",
+    ".env.example"
   ],
   "dependencies": {
     "@anthropic-ai/sdk": "^0.82.0",

package/src/agent/agent-engine.js

@@ -351,79 +351,9 @@ class AgentEngine {
   async run({ errorMessage, stackTrace, primaryFile, sourceCode, brainContext }) {
     const model = getModel("reasoning");
 
-    const systemPrompt = `You are Wolverine, an autonomous Node.js server repair agent. A server has an error and you must diagnose and fix it.
-
-You are NOT just a code editor — you are a full server doctor. Errors can be code bugs, missing dependencies, database problems, misplaced files, configuration issues, port conflicts, permission errors, corrupted state, or environment problems. Use your tools to investigate the ACTUAL root cause before attempting a fix.
-
-## YOUR TOOLS
-
-FILE TOOLS:
-- read_file: Read any file (with optional offset/limit for large files)
-- write_file: Write a complete file (creates parent dirs)
-- edit_file: Surgical find-and-replace (preferred for small fixes)
-- glob_files: Find files by pattern (e.g. "**/*.js", "server/**/*.json")
-- grep_code: Search code with regex across the project
-- list_dir: List directory contents (check structure, find misplaced files)
-- move_file: Move or rename files (fix misplaced files)
-
-SHELL TOOLS:
-- bash_exec: Run any shell command (npm install, chmod, kill, etc.)
-- git_log: View recent commits (what changed recently?)
-- git_diff: View uncommitted changes
-
-DATABASE TOOLS:
-- inspect_db: List tables, show schema, or run SELECT on SQLite databases
-- run_db_fix: Run UPDATE/DELETE/INSERT/ALTER on SQLite databases (backs up first)
-
-DIAGNOSTICS:
-- check_port: Check if a port is in use and by what process
-- check_env: Check environment variables (values auto-redacted for security)
-
-DEPENDENCY MANAGEMENT:
-- audit_deps: Full health check (vulnerabilities, outdated, peer conflicts, unused). Use FIRST for dependency errors.
-- check_migration: Check if a package has a known upgrade path (express→fastify, moment→dayjs, etc.)
-
-RESEARCH:
-- web_fetch: Fetch a URL (docs, npm packages, error solutions)
-
-## DIAGNOSIS FLOWCHART — follow this order:
-
-1. READ THE ERROR CAREFULLY — what type of problem is this?
-2. If no file path: use glob_files, grep_code, list_dir to investigate
-3. If file path: read_file to see the code, then investigate related files
-
-## ERROR → FIX STRATEGY TABLE
-
-| Error Pattern | Category | Diagnostic Steps | Fix |
-|---|---|---|---|
-| Cannot find module 'X' | DEPENDENCY | audit_deps first, check package.json | bash_exec: npm install X |
-| Cannot find module './X' | IMPORT | glob_files to find real path | edit_file: fix require path |
-| ENOENT: no such file | FILE MISSING | list_dir to check structure | write_file or move_file |
-| EACCES/EPERM | PERMISSION | bash_exec: ls -la | bash_exec: chmod 755 |
-| EADDRINUSE | PORT | check_port to find blocker | bash_exec: kill PID, or edit config |
-| ECONNREFUSED | SERVICE DOWN | check if DB/service is running | bash_exec: start service |
-| SyntaxError | CODE | read_file to see context | edit_file: fix syntax |
-| TypeError/ReferenceError | CODE | read_file + grep_code | edit_file: fix logic |
-| ER_NO_SUCH_TABLE | DATABASE | inspect_db: tables | run_db_fix: CREATE TABLE or bash_exec migration |
-| SQLITE_ERROR/CONSTRAINT | DATABASE | inspect_db: schema + query | run_db_fix: UPDATE/ALTER |
-| Invalid JSON | CONFIG | read_file the JSON | edit_file: fix JSON syntax |
-| ENOMEM / heap out of memory | RESOURCE | check_env for NODE_OPTIONS | edit config or bash_exec: increase limit |
-| Missing env variable | CONFIG | check_env | write_file .env or edit config |
-| Wrong file location | STRUCTURE | list_dir + glob_files | move_file to correct location |
-| Corrupted node_modules | DEPENDENCY | bash_exec: ls node_modules | bash_exec: rm -rf node_modules && npm install |
-| Git conflict markers | CODE | grep_code: <<<<<<< | edit_file: resolve conflicts |
-
-## RULES
-
-1. INVESTIGATE FIRST — never guess. Read files, check directories, inspect databases before fixing.
-2. Read files before modifying them. Check package.json before editing imports.
-3. Make minimal, targeted changes — fix the root cause, not symptoms.
-4. Use the right tool: bash_exec for operational fixes, edit_file for code, run_db_fix for data.
-5. You can edit ANY file type: .js, .json, .sql, .yaml, .env, .toml, .sh, .dockerfile, etc.
-6. If the error has no file path, USE YOUR TOOLS to find the problem (glob, grep, list_dir, inspect_db).
-7. When done, call the "done" tool with a summary of what you found and fixed.
-
-Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}` : ""}`;
+    // Dynamic system prompt: compact for simple errors (~400 tokens), full for complex (~1200 tokens)
+    const isSimple = /TypeError|ReferenceError|SyntaxError|Cannot find module|Cannot read prop/.test(errorMessage || "");
+    const systemPrompt = isSimple ? _simplePrompt(this.cwd, primaryFile) : _fullPrompt(this.cwd, primaryFile);
 
     // Build user message — handle cases with and without a specific file
     let userContent = `The server has an error:\n\n**Error:** ${errorMessage}\n\n**Stack Trace:**\n\`\`\`\n${stackTrace}\n\`\`\``;
@@ -1114,6 +1044,44 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
   }
 }
 
+// ── Dynamic System Prompts ──
+
+/** Compact prompt for simple code errors (~400 tokens vs ~1200). Saves 50% on 70% of heals. */
+function _simplePrompt(cwd, primaryFile) {
+  return `You are Wolverine, a Node.js server repair agent. Fix the error using minimal changes.
+
+TOOLS: read_file, write_file, edit_file, glob_files, grep_code, bash_exec, done
+RULES: Read the file before editing. Use edit_file for targeted fixes. Call done when finished.
+${primaryFile ? `File: ${primaryFile}` : ""}
+Project: ${cwd}`;
+}
+
+/** Full prompt for complex/unknown errors — all 18 tools + strategy table. */
+function _fullPrompt(cwd, primaryFile) {
+  return `You are Wolverine, an autonomous Node.js server repair agent. Diagnose and fix the error.
+
+You are a full server doctor. Errors can be code bugs, missing deps, database problems, config issues, port conflicts, permissions, or corrupted state. Investigate the root cause before fixing.
+
+TOOLS: read_file, write_file, edit_file, glob_files, grep_code, list_dir, move_file, bash_exec, git_log, git_diff, inspect_db, run_db_fix, check_port, check_env, audit_deps, check_migration, web_fetch, done
+
+STRATEGY:
+- Cannot find module 'X' → bash_exec: npm install X
+- Cannot find module './X' → edit_file: fix require path
+- ENOENT → write_file or move_file
+- EADDRINUSE → check_port then bash_exec: kill
+- TypeError/ReferenceError → read_file then edit_file
+- Database error → inspect_db then run_db_fix
+- Missing env var → check_env
+
+RULES:
+1. Investigate first — read files before modifying
+2. Minimal targeted changes — fix root cause not symptoms
+3. bash_exec for operational fixes, edit_file for code, run_db_fix for data
+4. Call done with summary when finished
+${primaryFile ? `\nFile: ${primaryFile}` : ""}
+Project: ${cwd}`;
+}
+
 // ── Zero-Cost Compaction Helpers (claw-code pattern) ──
 
 /**

package/src/agent/sub-agents.js

@@ -33,19 +33,38 @@ const AGENT_TOOL_SETS = {
 };
 
 // Default model + budget per agent type
-// Cost optimization: triage agents use cheap models (classifier slot = Haiku),
-// only the fixer needs the expensive coding model (Sonnet/Opus).
-// This cuts sub-agent cost by ~90% (6 Haiku calls vs 6 Sonnet calls).
-const AGENT_CONFIGS = {
-  explore:  { model: "classifier", maxTurns: 5,  maxTokens: 15000 },  // Haiku — just reading
-  plan:     { model: "classifier", maxTurns: 3,  maxTokens: 10000 },  // Haiku — simple planning
-  fix:      { model: "coding",    maxTurns: 5,  maxTokens: 50000 },  // Sonnet/Opus — needs reasoning
-  verify:   { model: "classifier", maxTurns: 3,  maxTokens: 8000 },   // Haiku — just checking
-  research: { model: "classifier", maxTurns: 3,  maxTokens: 10000 },  // Haiku — summarization
-  security: { model: "audit",     maxTurns: 3,  maxTokens: 8000 },   // Haiku — pattern matching
-  database: { model: "coding",    maxTurns: 5,  maxTokens: 50000 },  // Sonnet/Opus — needs reasoning
+// Dynamic token budgets: scale with error complexity.
+// Simple errors (TypeError) get tight budgets. Complex errors (database, multi-file) get more.
+// Triage agents use cheap models (Haiku), fixer uses expensive (Sonnet/Opus).
+const AGENT_CONFIGS_BASE = {
+  explore:  { model: "classifier", maxTurns: 5 },
+  plan:     { model: "classifier", maxTurns: 3 },
+  fix:      { model: "coding",    maxTurns: 5 },
+  verify:   { model: "classifier", maxTurns: 3 },
+  research: { model: "classifier", maxTurns: 3 },
+  security: { model: "audit",     maxTurns: 3 },
+  database: { model: "coding",    maxTurns: 5 },
 };
 
+const AGENT_BUDGETS = {
+  simple:  { explore: 8000,  plan: 5000,  fix: 25000, verify: 5000,  research: 5000,  security: 5000,  database: 25000 },
+  moderate:{ explore: 15000, plan: 10000, fix: 50000, verify: 8000,  research: 10000, security: 8000,  database: 50000 },
+  complex: { explore: 25000, plan: 15000, fix: 80000, verify: 10000, research: 15000, security: 10000, database: 80000 },
+};
+
+function getAgentConfig(type, errorComplexity) {
+  const base = AGENT_CONFIGS_BASE[type] || { model: "classifier", maxTurns: 3 };
+  const tier = errorComplexity || "moderate";
+  const budget = AGENT_BUDGETS[tier] || AGENT_BUDGETS.moderate;
+  return { ...base, maxTokens: budget[type] || 15000 };
+}
+
+// Backward compat
+const AGENT_CONFIGS = {};
+for (const type of Object.keys(AGENT_CONFIGS_BASE)) {
+  AGENT_CONFIGS[type] = { ...AGENT_CONFIGS_BASE[type], maxTokens: AGENT_BUDGETS.moderate[type] || 15000 };
+}
+
 // 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.",

package/src/brain/brain.js

@@ -257,6 +257,10 @@ const SEED_DOCS = [
     text: "Token waste prevention: 3 layers. (1) Empty stderr guard — signal kills with no error output just restart, no AI ($0.00). (2) Loop guard — 3 failed heals on same error → stop and file bug report, no more AI calls. (3) Global rate limit — max 5 heals per 5 minutes regardless of error signature. Idle server burns exactly $0.00 in tokens.",
     metadata: { topic: "token-protection" },
   },
+  {
+    text: "Audit optimizations: (1) Brain namespace isolation — seed docs (20K tokens of wolverine self-knowledge) excluded from error healing searches. Only searched when query is about wolverine itself. Cuts context by 50%. (2) Dynamic system prompt — simple errors (TypeError/ReferenceError) get 400-token compact prompt with 7 tools. Complex errors get full 1200-token prompt with 18 tools + strategy table. Saves 50% on 70% of heals. (3) Stability timer race fix — backup ID captured in closure, prevents wrong backup promoted if new heal starts before 30min timer. (4) Dynamic sub-agent budgets — simple: explore 8K/fix 25K, moderate: 15K/50K, complex: 25K/80K. Saves 40% on simple fixes. (5) Function map hash check — skips re-embedding if unchanged (MD5 hash stored in .wolverine/brain/.fmap-hash). 10-20% faster startup.",
+    metadata: { topic: "audit-optimizations" },
+  },
   {
     text: "Agent efficiency (claw-code patterns): (1) Anthropic prompt caching — system prompt marked with cache_control:{type:'ephemeral'}, cached server-side across agent turns, 90% cheaper on repeat calls (12-16K saved tokens per heal). (2) Tool result truncation — capped at 4K chars before entering message history, prevents context blowup from large grep/file reads. (3) Zero-cost structural compaction — extracts signals (tools used, files touched, errors found, actions taken) from message history WITHOUT an LLM call. Costs $0.00 vs old method that burned tokens on a compacting model. Triggers when estimated tokens > 10K (text.length/4 approximation). Preserves last 4 messages verbatim. (2) Token estimation — text.length/4+1, fast approximation without tokenizer, ~10% accurate. Used for budget decisions before API calls. (3) Error-graceful tools — tool errors returned as [ERROR] prefixed results, not thrown. Model sees the error and decides how to proceed. (4) Pre/post tool hooks — shell commands in .wolverine/hooks.json, exit 0=allow, 2=deny. Enables audit logging and policy enforcement without hard-coding.",
     metadata: { topic: "agent-efficiency" },
@@ -303,8 +307,18 @@ class Brain {
     this.functionMap = scanProject(this.projectRoot);
     console.log(chalk.gray(`  🧠 Found: ${this.functionMap.routes.length} routes, ${this.functionMap.functions.length} functions, ${this.functionMap.classes.length} classes`));
 
-    // 3. Embed function map (replace old "functions" entries)
-    await this._embedFunctionMap();
+    // 3. Embed function map — only if changed (hash check saves 10-20% startup time)
+    const crypto = require("crypto");
+    const mapHash = crypto.createHash("md5").update(JSON.stringify(this.functionMap)).digest("hex");
+    const hashPath = path.join(this.projectRoot, ".wolverine", "brain", ".fmap-hash");
+    let lastHash = "";
+    try { lastHash = fs.readFileSync(hashPath, "utf-8").trim(); } catch {}
+    if (mapHash !== lastHash) {
+      await this._embedFunctionMap();
+      try { fs.writeFileSync(hashPath, mapHash, "utf-8"); } catch {}
+    } else {
+      console.log(chalk.gray("  🧠 Function map unchanged — skipping re-embed"));
+    }
 
     // 4. Save
     this.store.save();
@@ -380,9 +394,17 @@ class Brain {
       parts.push("## Server Function Map\n" + this.functionMap.summary);
     }
 
-    // Two-tier recall: keyword first, semantic fallback
+    // Search only operational namespaces — NOT docs (seed docs add 20K tokens of
+    // wolverine self-knowledge that's irrelevant to fixing a TypeError).
+    // Docs are only searched when user asks about wolverine itself.
+    const isAboutWolverine = /wolverine|heal|pipeline|agent|backup|brain|dashboard/i.test(errorMessage || "");
     if (errorMessage) {
-      const memories = await this.recall(errorMessage, { topK: 5, minScore: 0.3 });
+      const searchNamespaces = isAboutWolverine ? undefined : undefined; // search all but filter below
+      const allMemories = await this.recall(errorMessage, { topK: 8, minScore: 0.3 });
+      // Filter: exclude seed docs unless query is about wolverine
+      const memories = isAboutWolverine
+        ? allMemories.slice(0, 5)
+        : allMemories.filter(m => m.namespace !== "docs").slice(0, 5);
       if (memories.length > 0) {
         parts.push("\n## Relevant Context from Brain");
         for (const mem of memories) {

package/src/core/runner.js

@@ -643,15 +643,18 @@ class WolverineRunner {
 
   _startStabilityTimer() {
     this._clearStabilityTimer();
+    // Capture backup ID in closure — prevents race where a new heal overwrites _lastBackupId
+    // before this timer fires, causing the wrong backup to be promoted.
+    const backupId = this._lastBackupId;
     this._stabilityTimer = setTimeout(() => {
-      if (this._lastBackupId && this.running) {
-        this.backupManager.markStable(this._lastBackupId);
+      if (backupId && this.running) {
+        this.backupManager.markStable(backupId);
         this.retryCount = 0;
         const healthStats = this.healthMonitor.getStats();
         if (healthStats.totalChecks > 0) {
           console.log(chalk.green(`  📊 Uptime: ${healthStats.uptimePercent}% (${healthStats.totalPasses}/${healthStats.totalChecks} checks passed)`));
         }
-        this.logger.info(EVENT_TYPES.BACKUP_STABLE, `Backup ${this._lastBackupId} promoted to stable`, { backupId: this._lastBackupId });
+        this.logger.info(EVENT_TYPES.BACKUP_STABLE, `Backup ${backupId} promoted to stable`, { backupId });
       }
     }, STABILITY_THRESHOLD_MS);
   }

package/src/core/wolverine.js

@@ -260,7 +260,7 @@ async function _healImpl({ stderr, cwd, sandbox, notifier, rateLimiter, backupMa
       let priorSummary = "";
       if (priorAttempts && priorAttempts.length > 0) {
         priorSummary = "\nPRIOR ATTEMPTS (do NOT repeat):\n" + priorAttempts.map(a =>
-          `- Attempt ${a.iteration} (${a.mode}): ${a.explanation?.slice(0, 100)}`
+          `- Attempt ${a.iteration} (${a.mode}): ${a.explanation?.slice(0, 50)}`
         ).join("\n") + "\n";
       }