specmem-hardwicksoftware 3.7.30 → 3.7.31

package/bootstrap.cjs

@@ -4919,6 +4919,25 @@ async function autoInstallThisMf() {
       // Non-fatal - MCP server will retry
     }
 
+    // Acquire socket lock so statusbar/health checks can detect us
+    const projectPath_uf = getProjectPath();
+    const lockAcquired_uf = tryAcquireSocketLock(projectPath_uf);
+    if (lockAcquired_uf) {
+      writeProjectPidFile(projectPath_uf, process.pid);
+      writeInstanceState(projectPath_uf, {
+        pid: process.pid,
+        projectPath: projectPath_uf,
+        projectHash: hashProjectPath(projectPath_uf),
+        startTime: new Date().toISOString(),
+        status: 'running',
+        bootstrapVersion: '1.0.0',
+        mode: 'ultra-fast'
+      });
+      startupLog('Ultra-fast path: socket lock acquired, PID file written');
+    } else {
+      startupLog('Ultra-fast path: could not acquire socket lock (non-fatal)');
+    }
+
     // Start server BEFORE any other operations
     // The server handles its own deferred initialization
     // CRITICAL: startServer() is now async and imports the ES module directly

package/claude-hooks/settings.json

@@ -55,6 +55,14 @@
       {
         "matcher": "Read",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-enforcer.cjs",
+            "timeout": 2,
+            "env": {
+              "SPECMEM_PROJECT_PATH": "${cwd}"
+            }
+          },
           {
             "type": "command",
             "command": "node /root/.claude/hooks/team-comms-enforcer.cjs",
@@ -84,6 +92,14 @@
       {
         "matcher": "Edit",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-enforcer.cjs",
+            "timeout": 2,
+            "env": {
+              "SPECMEM_PROJECT_PATH": "${cwd}"
+            }
+          },
           {
             "type": "command",
             "command": "node /root/.claude/hooks/team-comms-enforcer.cjs",
@@ -97,6 +113,11 @@
       {
         "matcher": "Write",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-enforcer.cjs",
+            "timeout": 2
+          },
           {
             "type": "command",
             "command": "node /root/.claude/hooks/team-comms-enforcer.cjs",
@@ -110,6 +131,11 @@
       {
         "matcher": "Grep",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-enforcer.cjs",
+            "timeout": 2
+          },
           {
             "type": "command",
             "command": "node /root/.claude/hooks/team-comms-enforcer.cjs",
@@ -147,6 +173,11 @@
       {
         "matcher": "Glob",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-enforcer.cjs",
+            "timeout": 2
+          },
           {
             "type": "command",
             "command": "node /root/.claude/hooks/team-comms-enforcer.cjs",
@@ -184,6 +215,14 @@
       {
         "matcher": "Bash",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-enforcer.cjs",
+            "timeout": 2,
+            "env": {
+              "SPECMEM_PROJECT_PATH": "${cwd}"
+            }
+          },
           {
             "type": "command",
             "command": "node /root/.claude/hooks/team-comms-enforcer.cjs",
@@ -306,6 +345,66 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-tracker.cjs",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-tracker.cjs",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-tracker.cjs",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__specmem__find_memory",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-tracker.cjs",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__specmem__find_code_pointers",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-tracker.cjs",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__specmem__drill_down",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /root/.claude/hooks/specmem-search-tracker.cjs",
+            "timeout": 5
+          }
+        ]
+      },
       {
         "matcher": "Task",
         "hooks": [

package/claude-hooks/specmem-search-enforcer.cjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * SPECMEM SEARCH ENFORCER - PreToolUse Hook
+ * ==========================================
+ *
+ * HARD BLOCKS agents that skip SpecMem semantic search.
+ *
+ * Rules:
+ * 1. Agents CANNOT do ANYTHING until they've called find_memory or find_code_pointers at least once
+ * 2. Every 3 searches (Grep/Glob/Read), agents MUST call find_code_pointers again
+ * 3. After find_code_pointers, agents MUST drill_down before continuing
+ * 4. 2nd search in a cycle: WARNING injected
+ * 5. 3rd search in a cycle: HARD BLOCK (deny)
+ * 6. Tool calls and other non-search tools DO NOT reset the counter
+ * 7. Main session (non-agent) gets suggestions, not blocks
+ *
+ * State: /tmp/specmem-search-enforcer-{session}.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// --- Agent detection (inline, no require chain issues) ---
+function isAgent() {
+  const markers = [
+    process.env.CLAUDE_AGENT === 'true',
+    process.env.CLAUDE_AGENT_TYPE,
+    process.env.TASK_ID,
+    (process.env.CLAUDE_WORKTREE || '').length > 0,
+    (process.env.CLAUDE_SESSION_ID || '').includes('task-'),
+  ];
+  return markers.some(Boolean);
+}
+
+// --- Config ---
+const SEARCH_TOOLS = ['Grep', 'Glob', 'Read', 'Bash'];
+const WRITE_TOOLS = ['Edit', 'Write'];
+const ALL_BLOCKED_TOOLS = [...SEARCH_TOOLS, ...WRITE_TOOLS];
+
+const SPECMEM_SEARCH_TOOLS = [
+  'mcp__specmem__find_memory',
+  'mcp__specmem__find_code_pointers',
+  'mcp__specmem__smart_search',
+];
+
+const SPECMEM_DRILLDOWN_TOOLS = [
+  'mcp__specmem__drill_down',
+  'mcp__specmem__get_memory',
+  'mcp__specmem__get_memory_by_id',
+  'mcp__specmem__getMemoryFull',
+];
+
+const SPECMEM_CODE_POINTER_TOOLS = [
+  'mcp__specmem__find_code_pointers',
+];
+
+const SEARCH_CYCLE_LIMIT = 3; // block on 3rd search
+const WARN_AT = 2; // warn on 2nd search
+
+// --- State management ---
+function getStateFile() {
+  const sessionId = process.env.CLAUDE_SESSION_ID || process.env.TASK_ID || 'default';
+  const sanitized = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return `/tmp/specmem-search-enforcer-${sanitized}.json`;
+}
+
+function getState() {
+  try {
+    const f = getStateFile();
+    if (fs.existsSync(f)) {
+      const data = JSON.parse(fs.readFileSync(f, 'utf-8'));
+      // Expire after 30 min
+      if (data.timestamp && (Date.now() - data.timestamp > 30 * 60 * 1000)) {
+        return freshState();
+      }
+      return data;
+    }
+  } catch (e) {
+    try { fs.unlinkSync(getStateFile()); } catch (_) {}
+  }
+  return freshState();
+}
+
+function freshState() {
+  return {
+    hasUsedSpecmemSearch: false,
+    searchesSinceLastCodePointers: 0,
+    pendingDrilldown: false,
+    lastCodePointersQuery: null,
+    timestamp: Date.now(),
+  };
+}
+
+function saveState(state) {
+  try {
+    state.timestamp = Date.now();
+    fs.writeFileSync(getStateFile(), JSON.stringify(state, null, 2));
+  } catch (e) { /* silent */ }
+}
+
+// --- stdin reader with timeout ---
+function readStdinWithTimeout(timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    let input = '';
+    const timer = setTimeout(() => {
+      process.stdin.destroy();
+      resolve(input);
+    }, timeoutMs);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(input); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(input); });
+  });
+}
+
+// --- Main ---
+async function main() {
+  const inputData = await readStdinWithTimeout(5000);
+
+  try {
+    const hookData = JSON.parse(inputData);
+    const toolName = hookData.tool_name || '';
+    const toolInput = hookData.tool_input || {};
+    const state = getState();
+
+    // --- SpecMem search tool used (find_memory, find_code_pointers, smart_search) ---
+    if (SPECMEM_SEARCH_TOOLS.includes(toolName)) {
+      state.hasUsedSpecmemSearch = true;
+
+      // find_code_pointers resets the search counter AND sets drilldown pending
+      if (SPECMEM_CODE_POINTER_TOOLS.includes(toolName)) {
+        state.searchesSinceLastCodePointers = 0;
+        state.pendingDrilldown = true;
+        state.lastCodePointersQuery = toolInput.query || '(unknown)';
+      }
+
+      saveState(state);
+      process.exit(0); // allow
+    }
+
+    // --- Drilldown tool used (drill_down, get_memory, etc) ---
+    if (SPECMEM_DRILLDOWN_TOOLS.includes(toolName)) {
+      state.pendingDrilldown = false;
+      saveState(state);
+      process.exit(0); // allow
+    }
+
+    // --- Non-agent: suggest only, never block ---
+    if (!isAgent()) {
+      process.exit(0); // allow everything for main session
+    }
+
+    // === AGENT ENFORCEMENT BELOW ===
+
+    // --- Rule 1: Agent hasn't used ANY specmem search yet -> HARD BLOCK everything ---
+    if (!state.hasUsedSpecmemSearch && ALL_BLOCKED_TOOLS.includes(toolName)) {
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: `BLOCKED: You MUST call find_memory or find_code_pointers BEFORE using ${toolName}. No Read/Write/Grep/Glob/Edit/Bash allowed until you search SpecMem first. Run: mcp__specmem__find_code_pointers({query: "your task description"})`
+        }
+      };
+      console.log(JSON.stringify(output));
+      process.exit(0);
+    }
+
+    // --- Rule 3: Pending drilldown after find_code_pointers -> BLOCK until drilled ---
+    if (state.pendingDrilldown && ALL_BLOCKED_TOOLS.includes(toolName)) {
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: `BLOCKED: You ran find_code_pointers("${state.lastCodePointersQuery}") but haven't drilled down into the results yet. You MUST call drill_down({drilldownID: N}) or get_memory({id: "ID"}) before using ${toolName}. Drill into the results first!`
+        }
+      };
+      console.log(JSON.stringify(output));
+      process.exit(0);
+    }
+
+    // --- Count searches for cycle enforcement ---
+    if (SEARCH_TOOLS.includes(toolName)) {
+      state.searchesSinceLastCodePointers++;
+      saveState(state);
+
+      // Rule 5: 3rd search -> HARD BLOCK
+      if (state.searchesSinceLastCodePointers >= SEARCH_CYCLE_LIMIT) {
+        const output = {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: `BLOCKED: You've done ${state.searchesSinceLastCodePointers} searches without calling find_code_pointers. Every 3 searches you MUST call mcp__specmem__find_code_pointers to refresh your semantic context. Do it now before continuing.`
+          }
+        };
+        console.log(JSON.stringify(output));
+        process.exit(0);
+      }
+
+      // Rule 4: 2nd search -> WARNING
+      if (state.searchesSinceLastCodePointers >= WARN_AT) {
+        const output = {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'allow',
+            permissionDecisionReason: `WARNING: ${state.searchesSinceLastCodePointers}/${SEARCH_CYCLE_LIMIT} searches used. You MUST call find_code_pointers before your next search or you'll be blocked. Consider running it now.`,
+            additionalContext: `\u26a0\ufe0f SEARCH LIMIT WARNING: ${state.searchesSinceLastCodePointers}/${SEARCH_CYCLE_LIMIT} searches since last find_code_pointers. Next search WILL BE BLOCKED. Run mcp__specmem__find_code_pointers now.`
+          }
+        };
+        console.log(JSON.stringify(output));
+        process.exit(0);
+      }
+    }
+
+    // --- Write tools increment search counter too (they shouldn't write blind) ---
+    if (WRITE_TOOLS.includes(toolName)) {
+      // Don't count writes toward search limit, but they're allowed if we passed the checks above
+      saveState(state);
+    }
+
+    // Allow everything else (Task, ToolSearch, MCP tools, etc)
+    process.exit(0);
+
+  } catch (error) {
+    // Parse failure = allow (don't break the session)
+    process.exit(0);
+  }
+}
+
+main().catch(() => process.exit(0));

package/claude-hooks/specmem-search-tracker.cjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * SPECMEM SEARCH TRACKER - PostToolUse Hook
+ * ===========================================
+ *
+ * Tracks when agents use SpecMem semantic tools (find_memory, find_code_pointers, drill_down)
+ * and resets the search counter so enforcer unblocks.
+ *
+ * Also tracks Grep/Glob calls to increment search counter.
+ *
+ * AGENTS ONLY - main session skipped.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Agent detection
+function isAgent() {
+  const e = process.env;
+  if (e.CLAUDE_AGENT === '1' || e.CLAUDE_AGENT === 'true') return true;
+  if (e.TASK_ID || e.AGENT_ID || e.WORKTREE_PATH) return true;
+  if (e.CLAUDE_CODE_ENTRYPOINT === 'task') return true;
+  const ppid = e.CLAUDE_PARENT_PID || e.PARENT_PID;
+  if (ppid && ppid !== '1' && ppid !== String(process.pid)) return true;
+  return false;
+}
+
+function main() {
+  if (!isAgent()) {
+    console.log(JSON.stringify({ permissionDecision: 'allow' }));
+    return;
+  }
+
+  const toolName = process.env.TOOL_NAME || '';
+  const sessionId = process.env.SESSION_ID || process.env.CLAUDE_SESSION_ID || process.ppid?.toString() || 'unknown';
+  const stateDir = '/tmp/specmem-enforcer';
+  const stateFile = path.join(stateDir, `${sessionId}.json`);
+
+  try { fs.mkdirSync(stateDir, { recursive: true }); } catch {}
+
+  let state = { searchCount: 0, specmemUsed: false, drilldownRequired: false, drilldownDone: false };
+  try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch {}
+
+  const isSpecmemSearch = /find_memory|find_code_pointers/i.test(toolName);
+  const isDrilldown = /drill_down/i.test(toolName);
+  const isSearchTool = /^(Grep|Glob)$/i.test(toolName);
+
+  if (isSpecmemSearch) {
+    state.specmemUsed = true;
+    state.searchCount = 0; // Reset search counter
+    // find_code_pointers requires drill_down after
+    if (/find_code_pointers/i.test(toolName)) {
+      state.drilldownRequired = true;
+      state.drilldownDone = false;
+    }
+  }
+
+  if (isDrilldown) {
+    state.drilldownDone = true;
+    state.drilldownRequired = false;
+  }
+
+  if (isSearchTool) {
+    state.searchCount = (state.searchCount || 0) + 1;
+  }
+
+  try { fs.writeFileSync(stateFile, JSON.stringify(state)); } catch {}
+  console.log(JSON.stringify({ permissionDecision: 'allow' }));
+}
+
+main();

package/dist/config.js

@@ -837,24 +837,19 @@ export function loadConfig() {
     const parsedUrl = parseDatabaseUrl();
     // Priority: DATABASE_URL > ENV VAR > .specmemrc > default
     // Per-project isolation still applies if DATABASE_URL not set
-    // Container mode: use unix socket dir as host for postgres connection
-    // When SPECMEM_CONTAINER_MODE is set, or container run dir has postgres socket
-    // FIX: Try both {projectPath}/specmem/run and {projectPath}/run to handle
-    // the case where projectPath IS the specmem dir (avoids specmem/specmem/run)
+    // Container mode: postgres via unix socket in specmem/run/ (bind-mounted from container /data/run)
+    // Socket appears after container starts PG — dir must exist, socket arrives when PG is ready
     let containerRunDir = path.join(projectPath, 'specmem', 'run');
-    const containerSocketExists = (() => {
-        try {
-            if (fs.existsSync(path.join(containerRunDir, '.s.PGSQL.5432'))) return true;
-            // Fallback: projectPath might BE the specmem dir
-            const altRunDir = path.join(projectPath, 'run');
-            if (fs.existsSync(path.join(altRunDir, '.s.PGSQL.5432'))) {
-                containerRunDir = altRunDir;
-                return true;
-            }
-            return false;
-        } catch { return false; }
-    })();
+    // Also check projectPath/run in case projectPath IS the specmem dir
+    if (!fs.existsSync(containerRunDir) && fs.existsSync(path.join(projectPath, 'run'))) {
+        containerRunDir = path.join(projectPath, 'run');
+    }
+    const containerSocketExists = fs.existsSync(path.join(containerRunDir, '.s.PGSQL.5432'));
     const isContainerMode = process.env['SPECMEM_CONTAINER_MODE'] === 'true' || containerSocketExists;
+    if (isContainerMode) {
+        // Ensure socket directory exists on host — container bind-mounts here
+        try { fs.mkdirSync(containerRunDir, { recursive: true }); } catch (e) { /* may already exist */ }
+    }
     const defaultDbHost = isContainerMode ? containerRunDir : 'localhost';
     const dbHost = parsedUrl?.host || process.env['SPECMEM_DB_HOST'] || getRcValue(rc, 'database.host', defaultDbHost);
     const dbPort = parsedUrl?.port || projectDbPort;

package/dist/db/connectionPoolGoBrrr.js

@@ -17,10 +17,10 @@ types.setTypeParser(20, (val) => {
     return Number.isSafeInteger(n) ? n : BigInt(val);
 }); // bigint - safe for values > 2^53
 const DEFAULT_POOL_SETTINGS = {
-    maxConnections: 20, // safe default - each project creates its own pool, 100 would exhaust PG max_connections
-    minConnections: 5, // keep some warm connections fr
+    maxConnections: 6, // tuned for 4-core 8GB laptop - 20 was exhausting PG under concurrent tool calls
+    minConnections: 2, // keep a couple warm, don't hog connections
     idleTimeoutMs: 30000, // 30 sec timeout on idle connections
-    connectionTimeoutMs: 30000, // 30 sec to establish connection
+    connectionTimeoutMs: 10000, // 10 sec to establish connection - fail fast under load
     statementTimeoutMs: 30000, // 30 sec statement timeout
     queryTimeoutMs: 60000, // 1 min query timeout for thicc queries
     healthCheckIntervalMs: 30000, // health check every 30 sec

package/dist/index.js

@@ -1608,11 +1608,28 @@ class LocalEmbeddingProvider {
      * Runs in background to not block embedding requests
      */
     tryRestartContainer() {
-        // Container mode: brain container manages embedding server — do NOT interfere.
-        // Self-healing attempts override sandboxSocketPath to wrong path (embeddings.sock vs embed.sock)
-        // and try to start conflicting Docker containers, causing CPU/RAM waste and socket confusion.
+        // Container mode: restart the brain container instead of spawning a new process
         if (process.env.SPECMEM_CONTAINER_MODE === 'true') {
-            logger.debug('container mode active — brain manages embedding server, skipping self-heal restart');
+            const now = Date.now();
+            if (now - this.lastRestartAttempt < LocalEmbeddingProvider.RESTART_COOLDOWN_MS) {
+                logger.debug('container restart cooldown active, skipping');
+                return;
+            }
+            this.lastRestartAttempt = now;
+            try {
+                const { getContainerManager } = require('./container/containerManager.js');
+                const projectPath = process.env.SPECMEM_PROJECT_PATH || process.cwd();
+                const cm = getContainerManager(projectPath);
+                logger.info({ projectPath }, '[LocalEmbeddingProvider] Restarting brain container...');
+                cm.start().then(() => {
+                    logger.info('[LocalEmbeddingProvider] Brain container restarted');
+                    this.restartAttempts = 0;
+                }).catch(err => {
+                    logger.error({ error: err?.message }, '[LocalEmbeddingProvider] Brain container restart failed');
+                });
+            } catch (err) {
+                logger.error({ error: err?.message }, '[LocalEmbeddingProvider] Failed to get container manager');
+            }
             return;
         }
         const now = Date.now();

package/dist/mcp/embeddingServerManager.js

@@ -2313,8 +2313,22 @@ export class EmbeddingServerManager extends EventEmitter {
                         logger.warn({
                             failures: this.config.maxFailuresBeforeRestart,
                             restartCount: this.restartCount,
-                        }, '[EmbeddingServerManager] Too many consecutive failures in container mode - cannot restart container process from host');
+                        }, '[EmbeddingServerManager] Too many consecutive failures in container mode - attempting container restart');
                         this.emit('unhealthy_container', { failures: this.config.maxFailuresBeforeRestart });
+                        // FIX: Auto-restart brain container when embedding is dead
+                        try {
+                            const { getContainerManager } = require('../container/containerManager.js');
+                            const projectPath = process.env['SPECMEM_PROJECT_PATH'] || process.cwd();
+                            const cm = getContainerManager(projectPath);
+                            logger.info({ projectPath }, '[EmbeddingServerManager] Restarting brain container...');
+                            await cm.start();
+                            logger.info('[EmbeddingServerManager] Brain container restarted successfully');
+                            this.isRunning = true;
+                            this.startTime = Date.now();
+                        } catch (containerErr) {
+                            logger.error({ error: containerErr?.message || containerErr },
+                                '[EmbeddingServerManager] Failed to restart brain container');
+                        }
                     }
                     else {
                         logger.warn({

package/dist/mcp/mcpProtocolHandler.js

@@ -424,12 +424,30 @@ export class MCPProtocolHandler {
         }
     }
     /**
-     * batch handle multiple tool calls - for efficiency
+     * batch handle multiple tool calls - with concurrency limit
+     * prevents overwhelming the db pool when claude fires 5+ calls at once
      */
     async handleBatchToolCalls(calls) {
         const results = [];
-        // process in parallel for speed
-        const promises = calls.map(async (call) => {
+        // inline concurrency limiter - no npm deps needed
+        // max 2 concurrent to leave headroom on 4-core/8GB systems
+        const _limitConcurrency = (concurrency) => {
+            let active = 0;
+            const queue = [];
+            const next = () => {
+                while (active < concurrency && queue.length > 0) {
+                    active++;
+                    const { fn, resolve, reject } = queue.shift();
+                    fn().then(resolve, reject).finally(() => { active--; next(); });
+                }
+            };
+            return (fn) => new Promise((resolve, reject) => {
+                queue.push({ fn, resolve, reject });
+                next();
+            });
+        };
+        const limit = _limitConcurrency(2);
+        const promises = calls.map((call) => limit(async () => {
             try {
                 const result = await this.handleToolCall(call.name, call.args);
                 return { name: call.name, result };
@@ -440,7 +458,7 @@ export class MCPProtocolHandler {
                     error: error instanceof Error ? error.message : 'unknown error'
                 };
             }
-        });
+        }));
         const settled = await Promise.allSettled(promises);
         for (const result of settled) {
             if (result.status === 'fulfilled') {

package/dist/mcp/specMemServer.js

@@ -236,8 +236,9 @@ export class SpecMemServer {
             this.announceToOnStartup();
             // Auto-start Codebook Learner (resource-capped background service)
             this._startCodebookLearner();
-            // Auto-trigger background codebase indexing (populates code_definitions)
-            // Runs deferred (10s delay) so it doesn't block MCP startup
+            // NOTE: _triggerCodebaseIndexing() is also called from deferredInitPromise.then()
+            // after DB migrations complete (which create codebase_files table).
+            // This early call may no-op if DB not ready yet — the post-DB call is the critical one.
             this._triggerCodebaseIndexing();
         };
         // get that db connection no cap
@@ -1285,6 +1286,14 @@ export class SpecMemServer {
             await this.initializeMiniCOTServerManager();
             startupLog('Mini COT server manager initialized');
             logger.info('SpecMem MCP server fully initialized — all components ready');
+            // FIX: Trigger codebase indexing AFTER DB init (migrations create codebase_files table)
+            // Previously only called in oninitialized which fires BEFORE deferred DB init,
+            // causing checkCodebaseIndexStatus to see missing table → needsReindex=false → skip
+            try {
+                await this._triggerCodebaseIndexing();
+            } catch (indexErr) {
+                logger.warn({ error: indexErr?.message }, 'Post-DB-init codebase indexing failed (non-fatal)');
+            }
             // Run initial sync on startup — ensures codebase is fresh when Claude Code launches
             await this._runStartupSync();
             // Start idle sync timer — auto-syncs when no tool calls for 60s
@@ -1354,7 +1363,11 @@ export class SpecMemServer {
                 const checkResult = await CheckSyncStatus.execute({ detailed: false }, wm);
                 const syncScore = checkResult?.syncScore ?? 100;
                 // Only resync if drift detected (score < 100)
-                if (syncScore < 100) {
+                // Skip resync if indexing is still pending (syncScore === -1)
+                if (checkResult?.indexingPending) {
+                    process.stderr.write(`[SPECMEM IDLE-SYNC] Indexing still in progress, skipping resync\n`);
+                }
+                else if (syncScore < 100) {
                     process.stderr.write(`[SPECMEM IDLE-SYNC] Drift detected (${syncScore}%), resyncing...\n`);
                     const resyncResult = await ForceResync.execute({ dryRun: false }, wm);
                     const added = resyncResult?.stats?.filesAdded ?? 0;

package/dist/mcp/toolRegistry.js

@@ -94,32 +94,30 @@ _cacheCleanupTimer.unref();
 /**
  * Get the project-scoped embedding cache
  */
-// HIGH-4: Simple lock to prevent concurrent eviction
-let _evictionInProgress = false;
+// HIGH-4: Eviction uses while-loop to guarantee room before creating new entry.
+// Old boolean _evictionInProgress flag was broken: when flag was true, eviction was
+// skipped but new entry was still created at line 125, exceeding the 20-project limit.
 function getProjectEmbeddingCache() {
     const project = getProjectPath();
     _EMBEDDING_CACHE_ACCESS_TIMES.set(project, Date.now());
     if (!_EMBEDDING_CACHE_BY_PROJECT.has(project)) {
-        // HIGH-4: Changed > to >= to evict at limit, not after. Added lock to prevent concurrent eviction.
-        if (_EMBEDDING_CACHE_BY_PROJECT.size >= 20 && !_evictionInProgress) {
-            _evictionInProgress = true;
-            try {
-                // Evict the least recently accessed project cache
-                let oldestProject = null;
-                let oldestTime = Infinity;
-                for (const [p, t] of _EMBEDDING_CACHE_ACCESS_TIMES) {
-                    if (t < oldestTime) {
-                        oldestTime = t;
-                        oldestProject = p;
-                    }
+        // Evict until there's room - loop guarantees we never exceed limit
+        while (_EMBEDDING_CACHE_BY_PROJECT.size >= 20) {
+            let oldestProject = null;
+            let oldestTime = Infinity;
+            for (const [p, t] of _EMBEDDING_CACHE_ACCESS_TIMES) {
+                if (t < oldestTime && p !== project) {
+                    oldestTime = t;
+                    oldestProject = p;
                 }
-                if (oldestProject) {
-                    _EMBEDDING_CACHE_BY_PROJECT.delete(oldestProject);
-                    _EMBEDDING_CACHE_ACCESS_TIMES.delete(oldestProject);
-                    __debugLog('[MCP DEBUG]', Date.now(), 'CACHE_PROJECT_EVICTED', { evictedProject: oldestProject, reason: 'max_projects_reached' });
-                }
-            } finally {
-                _evictionInProgress = false;
+            }
+            if (oldestProject) {
+                _EMBEDDING_CACHE_BY_PROJECT.delete(oldestProject);
+                _EMBEDDING_CACHE_ACCESS_TIMES.delete(oldestProject);
+                __debugLog('[MCP DEBUG]', Date.now(), 'CACHE_PROJECT_EVICTED', { evictedProject: oldestProject, reason: 'max_projects_reached' });
+            } else {
+                // Safety: no evictable project found (all entries are current project?), break to avoid infinite loop
+                break;
             }
         }
         _EMBEDDING_CACHE_BY_PROJECT.set(project, new Map());

package/dist/tools/goofy/checkSyncStatus.js

@@ -27,7 +27,10 @@ export class CheckSyncStatus {
             const driftReport = await watcherManager.checkSync();
             // build summary message
             let summary;
-            if (driftReport.inSync) {
+            if (driftReport.indexingPending) {
+                summary = `Codebase indexing in progress — sync score not yet available. ${driftReport.totalFiles} files on disk awaiting indexing.`;
+            }
+            else if (driftReport.inSync) {
                 summary = `Everything is in sync! ${driftReport.upToDate} files are up to date.`;
             }
             else {
@@ -45,7 +48,8 @@ export class CheckSyncStatus {
             }
             const result = {
                 inSync: driftReport.inSync,
-                syncScore: driftReport.syncScore,
+                syncScore: driftReport.indexingPending ? -1 : driftReport.syncScore,
+                indexingPending: !!driftReport.indexingPending,
                 driftPercentage: driftReport.driftPercentage,
                 summary,
                 stats: {
@@ -70,10 +74,12 @@ export class CheckSyncStatus {
                     contentMismatch: driftReport.contentMismatch
                 };
             }
-            // Update statusbar sync score live
-            try {
-                await watcherManager.writeSyncScore(driftReport.syncScore);
-            } catch (e) { /* non-critical */ }
+            // Update statusbar sync score live (skip if indexing pending — don't write -1)
+            if (!driftReport.indexingPending) {
+                try {
+                    await watcherManager.writeSyncScore(driftReport.syncScore);
+                } catch (e) { /* non-critical */ }
+            }
             logger.info({ inSync: driftReport.inSync, syncScore: driftReport.syncScore }, 'sync check complete');
             // Build human readable response
             const drifted = driftReport.missingFromMcp.length + driftReport.missingFromDisk.length + driftReport.contentMismatch.length;
@@ -99,7 +105,8 @@ export class CheckSyncStatus {
                     if (more > 0) detailLines += `\n  ... and ${more} more`;
                 }
             }
-            const message = `Sync Score: ${Math.round(driftReport.syncScore * 100)}%
+            const displayScore = driftReport.indexingPending ? 'Pending' : `${Math.round(driftReport.syncScore * 100)}%`;
+            const message = `Sync Score: ${displayScore}
 ${summary}
 
 Stats:

package/dist/watcher/fileWatcher.js

@@ -55,6 +55,11 @@ export class WatchForChangesNoCap {
     debounceCleanupTimer = null;
     // FIX 7.14: Track pending flush promises so stop() can await them
     pendingFlushPromises = new Set();
+    // PERF: Batch-level debounce — collect per-file handler results into batches
+    // so git operations changing many files don't fire hundreds of individual handler calls
+    _batchTimer = null;
+    _batchQueue = [];
+    _batchDebounceMs = 500; // collect events for 500ms before dispatching batch
     // stats tracking
     stats = {
         filesWatched: 0,
@@ -75,6 +80,37 @@ export class WatchForChangesNoCap {
             verbose: config.verbose ?? false
         };
     }
+    /**
+     * _enqueueBatchEvent - batch-level debounce for handler calls
+     *
+     * Instead of calling changeHandler() immediately per-file, queue events
+     * and dispatch the entire batch after 500ms of quiet. This prevents
+     * git operations (checkout, merge, rebase) from firing hundreds of
+     * individual handler calls that each trigger sync/DB work.
+     */
+    _enqueueBatchEvent(event) {
+        this._batchQueue.push(event);
+        if (this._batchTimer) clearTimeout(this._batchTimer);
+        this._batchTimer = setTimeout(async () => {
+            this._batchTimer = null;
+            const batch = this._batchQueue.splice(0);
+            if (batch.length === 0 || !this.changeHandler) return;
+            const batchSize = batch.length;
+            if (batchSize > 5) {
+                logger.info({ batchSize }, `batch debounce: dispatching ${batchSize} file events as batch`);
+            }
+            // Process each event in the batch sequentially
+            // (changeHandler expects individual events)
+            for (const evt of batch) {
+                try {
+                    await this.changeHandler(evt);
+                }
+                catch (err) {
+                    logger.error({ error: err, path: evt.path }, 'batch handler error for file');
+                }
+            }
+        }, this._batchDebounceMs);
+    }
     /**
      * startWatching - fires up the file watcher
      *
@@ -189,7 +225,7 @@ export class WatchForChangesNoCap {
                 depth: undefined, // watch all depths
                 // debouncing built into chokidar
                 awaitWriteFinish: {
-                    stabilityThreshold: 300, // wait 300ms for file to stop changing
+                    stabilityThreshold: 500, // wait 500ms for file to stop changing (reduced CPU from rapid fire events)
                     pollInterval: 100 // check every 100ms
                 },
                 // dont follow symlinks (security)
@@ -240,6 +276,18 @@ export class WatchForChangesNoCap {
             await Promise.allSettled([...this.pendingFlushPromises]);
             this.pendingFlushPromises.clear();
         }
+        // PERF: Clear batch timer and flush pending batch events
+        if (this._batchTimer) {
+            clearTimeout(this._batchTimer);
+            this._batchTimer = null;
+        }
+        if (this._pendingBatchEvents.length > 0 && this.changeHandler) {
+            // Flush remaining batch events before shutdown
+            const batch = this._pendingBatchEvents.splice(0);
+            for (const evt of batch) {
+                try { await this.changeHandler(evt); } catch { /* shutting down */ }
+            }
+        }
         // FIX MED-13: Cancel all debounced handlers before clearing to prevent memory leaks
         // The debounce library's clear() method cancels pending timer execution
         for (const handler of this.debouncedHandlers.values()) {
@@ -381,7 +429,9 @@ export class WatchForChangesNoCap {
                     if (latestEvent) {
                         // Update timestamp to reflect when we actually process the event
                         latestEvent.timestamp = new Date();
-                        await this.changeHandler(latestEvent);
+                        // PERF: Route through batch debounce instead of calling handler directly
+                        // This prevents git operations (200+ files) from firing 200 individual handler calls
+                        this._enqueueBatchEvent(latestEvent);
                         this.stats.eventsProcessed++;
                         this.stats.lastEventTime = new Date();
                     }
@@ -435,7 +485,8 @@ export class WatchForChangesNoCap {
                     const flushPromise = Promise.resolve().then(async () => {
                         try {
                             latestEvent.timestamp = new Date();
-                            await this.changeHandler(latestEvent);
+                            // PERF: Route through batch debounce
+                            this._enqueueBatchEvent(latestEvent);
                             this.stats.eventsProcessed++;
                             this.stats.lastEventTime = new Date();
                         }
@@ -479,23 +530,9 @@ export class WatchForChangesNoCap {
                     const latestEvent = this.pendingEventData.get(key);
                     if (latestEvent && this.changeHandler) {
                         this.pendingEventData.delete(key);
-                        // FIX 7.14: Track flush promise so stop() can await it
-                        const flushPromise = Promise.resolve().then(async () => {
-                            try {
-                                latestEvent.timestamp = new Date();
-                                await this.changeHandler(latestEvent);
-                                this.stats.eventsProcessed++;
-                                this.stats.lastEventTime = new Date();
-                            }
-                            catch (error) {
-                                this.stats.errors++;
-                                logger.error({ error, event: latestEvent }, 'error processing stale debounce entry');
-                            }
-                            finally {
-                                this.pendingFlushPromises.delete(flushPromise);
-                            }
-                        });
-                        this.pendingFlushPromises.add(flushPromise);
+                        // PERF: Route stale entries through batch debounce too
+                        latestEvent.timestamp = new Date();
+                        this._enqueueBatchEvent(latestEvent);
                     }
                     else {
                         this.pendingEventData.delete(key);

package/dist/watcher/syncChecker.js

@@ -119,22 +119,26 @@ export class AreWeStillInSync {
             const totalFiles = diskFiles.length;
             const totalMemories = mcpFiles.length;
             const totalDrift = missingFromMcp.length + missingFromDisk.length + contentMismatch.length;
+            // FIX: If codebase_files is empty but disk files exist, indexing hasn't completed yet.
+            // Don't report 0% sync — that's misleading. Report indexing-pending state instead.
+            const indexingPending = totalMemories === 0 && totalFiles > 0;
             // Sync score = what % of disk files are correctly synced in MCP
             // Deleted-from-disk files are cleanup work, not sync failures
             const totalItems = totalFiles || 1;
-            const driftPercentage = totalItems > 0 ? (totalDrift / totalItems) * 100 : 0;
-            const syncScore = totalItems > 0 ? upToDate / totalItems : 1;
+            const driftPercentage = indexingPending ? 0 : (totalItems > 0 ? (totalDrift / totalItems) * 100 : 0);
+            const syncScore = indexingPending ? -1 : (totalItems > 0 ? upToDate / totalItems : 1);
             const report = {
-                inSync: totalDrift === 0,
+                inSync: indexingPending ? false : totalDrift === 0,
                 lastChecked: new Date(),
                 totalFiles,
                 totalMemories,
-                missingFromMcp,
+                missingFromMcp: indexingPending ? [] : missingFromMcp,
                 missingFromDisk,
-                contentMismatch,
-                upToDate,
+                contentMismatch: indexingPending ? [] : contentMismatch,
+                upToDate: indexingPending ? 0 : upToDate,
                 driftPercentage,
-                syncScore
+                syncScore,
+                indexingPending
             };
             this.lastSyncCheck = report.lastChecked;
             this.lastCheckTime = startTime; // FIX 7.03: Record check time for mtime optimization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specmem-hardwicksoftware",
-  "version": "3.7.30",
+  "version": "3.7.31",
   "type": "module",
   "description": "Your Claude Code sessions don't have to start from scratch anymore — SpecMem gives your AI real memory. It won't forget your conversations, your code, or your architecture decisions between sessions. That's the whole point. Semantic code indexing that actually works: TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C, C++, HTML and more. It doesn't just track functions — it gets classes, methods, fields, constants, enums, macros, imports, structs, the whole codebase graph. There's chat memory too, powered by pgvector embeddings. You've also got token compression, team coordination, multi-agent comms, and file watching built in. 74+ MCP tools. Runs on PostgreSQL + Docker. It's kind of a big deal. justcalljon.pro",
   "main": "dist/index.js",

package/scripts/global-postinstall.cjs

@@ -947,9 +947,14 @@ function adjustPgAuth() {
     // Backup and modify
     run(`sudo cp ${pgHbaPath} ${pgHbaPath}.backup`);
 
-    // Add password auth for our user
+    // Add password auth for our user — check if already exists to prevent duplicates
     const authLine = `host    ${DB_CONFIG.name}    ${DB_CONFIG.user}    127.0.0.1/32    md5`;
-    run(`echo '${authLine}' | sudo tee -a ${pgHbaPath}`);
+    const alreadyExists = run(`sudo grep -qF '${authLine}' ${pgHbaPath}`, { silent: true });
+    if (!alreadyExists.success) {
+      run(`echo '${authLine}' | sudo tee -a ${pgHbaPath}`);
+    } else {
+      log.info('pg_hba.conf auth line already present, skipping');
+    }
 
     // Reload PostgreSQL
     run('sudo systemctl reload postgresql 2>/dev/null || sudo -u postgres pg_ctl reload');

package/scripts/specmem-init.cjs

@@ -8799,9 +8799,14 @@ CREATE INDEX IF NOT EXISTS idx_embedding_queue_project ON embedding_queue (proje
         ? path.join(specmemPkg, 'mcp-proxy.cjs')
         : path.join(specmemPkg, 'bootstrap.cjs');
       // Container mode: postgres via unix socket in specmem/run/, user=specmem, trust auth
+      // Socket dir bind-mounted to /data/run in container — PG socket appears here after container starts
       // Legacy mode: postgres on localhost:5432, legacy credentials
       const isContainerMode = process.env.SPECMEM_CONTAINER_MODE === 'true';
       const runDir = path.join(projectPath, 'specmem', 'run');
+      if (isContainerMode) {
+        // Ensure socket directory exists on host — container bind-mounts dataDir:/data
+        try { fs.mkdirSync(runDir, { recursive: true }); } catch (e) { /* may already exist */ }
+      }
       const dbEnv = isContainerMode ? {
         SPECMEM_DB_HOST: runDir,
         SPECMEM_DB_PORT: "5432",

package/specmem/model-config.json

@@ -13,9 +13,10 @@
     "cpus": 8
   },
   "embedding": {
-    "batchSize": 24,
+    "batchSize": 64,
     "maxConcurrent": 5,
-    "timeout": 45000
+    "timeout": 45000,
+    "throttleDelayMs": 50
   },
   "watcher": {
     "debounceMs": 750,
@@ -33,13 +34,13 @@
     "maxChunks": 75
   },
   "resources": {
-    "cpuMin": 20,
-    "cpuMax": 40,
+    "cpuMin": 10,
+    "cpuMax": 45,
     "cpuCoreMin": 1,
     "cpuCoreMax": 4,
     "ramMinMb": 4000,
-    "ramMaxMb": 11500,
-    "updatedAt": "2026-02-21T22:33:46.533Z"
+    "ramMaxMb": 13500,
+    "updatedAt": "2026-02-24T11:56:33.760Z"
   },
   "resourcePool": {
     "embedding": {
@@ -79,5 +80,24 @@
       "description": "Adaptive batch sizing based on CPU/RAM"
     },
     "enabledAt": "2026-02-12T23:19:17.948Z"
+  },
+  "powerMode": {
+    "level": "high",
+    "description": "Max Performance - for 16GB+ RAM systems",
+    "lazyLoading": false,
+    "diskCache": false,
+    "diskCacheMaxMb": 0,
+    "aggressiveCleanup": false,
+    "idleUnloadSeconds": 0,
+    "batchSize": 32,
+    "throttleDelayMs": 50,
+    "setAt": "2026-02-24T11:57:23.121Z"
+  },
+  "heavyOps": {
+    "enabled": true,
+    "enabledAt": "2026-02-24T11:57:35.508Z",
+    "originalBatchSize": 32,
+    "batchSizeMultiplier": 2,
+    "throttleReduction": 0.2
   }
 }

package/specmem/supervisord.conf

@@ -1,6 +1,6 @@
 ; ============================================
 ; SPECMEM BRAIN CONTAINER - DYNAMIC SUPERVISORD CONFIG
-; Generated by specmem-init at 2026-02-22T17:39:56.598Z
+; Generated by specmem-init at 2026-02-24T11:53:24.816Z
 ; Thread counts from model-config.json resourcePool
 ; ============================================
 

package/specmem/user-config.json

@@ -7,5 +7,17 @@
   "serviceMode": {
     "enabled": false,
     "disabledAt": "2026-02-18T21:38:50.526Z"
+  },
+  "powerMode": {
+    "level": "high",
+    "description": "Max Performance - for 16GB+ RAM systems",
+    "lazyLoading": false,
+    "diskCache": false,
+    "diskCacheMaxMb": 0,
+    "aggressiveCleanup": false,
+    "idleUnloadSeconds": 0,
+    "batchSize": 32,
+    "throttleDelayMs": 50,
+    "setAt": "2026-02-24T11:57:23.121Z"
   }
 }