overmind-mcp 2.8.40 → 2.8.44

package/dist/services/NousHermesRunner.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { spawn } from 'child_process';
-import { exec } from 'child_process';
+import { exec, execSync } from 'child_process';
 import { promisify } from 'util';
 import { CONFIG, resolveConfigPath, getWorkspaceDir, getAgentHermesHome, getAgentOvermindHome, getSharedHermesHome } from '../lib/config.js';
 import { getLastSessionId, saveSessionId } from '../lib/sessions.js';
@@ -18,34 +18,55 @@ const logger = pino({ name: 'NousHermesRunner' });
 // orphelin. On utilise taskkill /F /T pour propager le kill au sous-arbre complet.
 const killProcessTree = (child) => {
     return new Promise((resolve) => {
-        if (!child || child.exitCode !== null || child.killed) {
+        if (!child) {
+            logger.debug('[KILL] No child process reference provided.');
             resolve();
             return;
         }
+        if (child.exitCode !== null || child.killed) {
+            logger.debug({ pid: child.pid, exitCode: child.exitCode, killed: child.killed }, '[KILL] Process is already dead or marked killed.');
+            resolve();
+            return;
+        }
+        logger.info({ pid: child.pid }, '[KILL] Initiating process tree termination...');
         let settled = false;
         const finish = () => {
             if (settled)
                 return;
             settled = true;
+            logger.debug({ pid: child.pid }, '[KILL] Process tree termination sequence completed.');
             resolve();
         };
         child.once('exit', finish);
-        if (process.platform === 'win32' && child.pid) {
-            exec(`taskkill /F /T /PID ${child.pid}`, () => {
-                // taskkill peut échouer si le process est déjà mort
+        if (process.platform === 'win32' && child.pid && typeof child.pid === 'number' && child.pid > 0) {
+            const cmd = `taskkill /F /T /PID ${child.pid}`;
+            logger.debug({ cmd }, '[KILL] Executing Windows taskkill...');
+            exec(cmd, (err, stdout, stderr) => {
+                if (err) {
+                    logger.debug({ err, stderr }, '[KILL] taskkill failed or process was already dead.');
+                }
+                else {
+                    logger.debug({ stdout }, '[KILL] taskkill completed successfully.');
+                }
             });
         }
         else {
             try {
+                logger.debug({ pid: child.pid }, '[KILL] Dispatched SIGTERM signal.');
                 child.kill('SIGTERM');
             }
-            catch { /* ignored */ }
+            catch (e) {
+                logger.debug({ pid: child.pid, error: e }, '[KILL] SIGTERM dispatch failed.');
+            }
             setTimeout(() => {
                 if (child.exitCode === null && !child.killed) {
                     try {
+                        logger.warn({ pid: child.pid }, '[KILL] SIGTERM ignored. Escalating to SIGKILL...');
                         child.kill('SIGKILL');
                     }
-                    catch { /* ignored */ }
+                    catch (e) {
+                        logger.debug({ pid: child.pid, error: e }, '[KILL] SIGKILL dispatch failed.');
+                    }
                 }
             }, 2000);
         }
@@ -95,30 +116,33 @@ async function findHermesBinary() {
         // Not found in PATH
     }
     // 3. Platform-specific paths
-    const platformPaths = isWin
-        ? [
-            // Hermes venv (Nous Research install) — PRIORITÉ haute (v0.13.0, supporte -z)
-            path.join(process.env.LOCALAPPDATA || '', 'hermes', 'hermes-agent', 'venv', 'Scripts', 'hermes.exe'),
-            // Officiel installer Windows (install.ps1) — chemin natif
-            path.join(process.env.LOCALAPPDATA || '', 'hermes', 'bin', 'hermes.exe'),
-            path.join(process.env.LOCALAPPDATA || '', 'hermes', 'hermes.exe'),
-            // Fallback installations via pip (legacy)
-            path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Python', 'Python312', 'Scripts', 'hermes.exe'),
-            path.join(process.env.APPDATA || '', 'Python', 'Python312', 'Scripts', 'hermes.exe'),
-            path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Python', 'Python311', 'Scripts', 'hermes.exe'),
-            path.join(process.env.APPDATA || '', 'Python', 'Python311', 'Scripts', 'hermes.exe'),
-            'C:\\Python312\\Scripts\\hermes.exe',
-            'C:\\Python311\\Scripts\\hermes.exe',
-            'C:\\Program Files\\Hermes\\hermes.exe',
-        ]
-        : [
-            path.join(process.env.HOME || '', '.local', 'bin', 'hermes'),
-            path.join(process.env.HOME || '', 'miniconda3', 'bin', 'hermes'),
-            path.join(process.env.HOME || '', 'anaconda3', 'bin', 'hermes'),
-            '/usr/local/bin/hermes',
-            '/usr/bin/hermes',
-            '/opt/homebrew/bin/hermes',
-        ];
+    const platformPaths = [];
+    if (isWin) {
+        platformPaths.push(
+        // Hermes venv (Nous Research install) — PRIORITÉ haute (v0.13.0, supporte -z)
+        path.join(process.env.LOCALAPPDATA || '', 'hermes', 'hermes-agent', 'venv', 'Scripts', 'hermes.exe'), 
+        // Officiel installer Windows (install.ps1) — chemin natif
+        path.join(process.env.LOCALAPPDATA || '', 'hermes', 'bin', 'hermes.exe'), path.join(process.env.LOCALAPPDATA || '', 'hermes', 'hermes.exe'));
+        // Dynamically scan for Python versions in LOCALAPPDATA
+        const programsPython = path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Python');
+        if (fs.existsSync(programsPython)) {
+            try {
+                const dirs = fs.readdirSync(programsPython);
+                for (const dir of dirs) {
+                    if (dir.toLowerCase().startsWith('python')) {
+                        platformPaths.push(path.join(programsPython, dir, 'Scripts', 'hermes.exe'));
+                    }
+                }
+            }
+            catch { /* ignored */ }
+        }
+        platformPaths.push(
+        // Fallback installations via pip (legacy)
+        path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Python', 'Python312', 'Scripts', 'hermes.exe'), path.join(process.env.APPDATA || '', 'Python', 'Python312', 'Scripts', 'hermes.exe'), path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Python', 'Python311', 'Scripts', 'hermes.exe'), path.join(process.env.APPDATA || '', 'Python', 'Python311', 'Scripts', 'hermes.exe'), 'C:\\Python312\\Scripts\\hermes.exe', 'C:\\Python311\\Scripts\\hermes.exe', 'C:\\Program Files\\Hermes\\hermes.exe');
+    }
+    else {
+        platformPaths.push(path.join(process.env.HOME || '', '.local', 'bin', 'hermes'), path.join(process.env.HOME || '', 'miniconda3', 'bin', 'hermes'), path.join(process.env.HOME || '', 'anaconda3', 'bin', 'hermes'), '/usr/local/bin/hermes', '/usr/bin/hermes', '/opt/homebrew/bin/hermes');
+    }
     for (const p of platformPaths) {
         if (fs.existsSync(p)) {
             logger.info({ path: p }, 'Found hermes at platform path');
@@ -148,12 +172,12 @@ async function findHermesBinary() {
     return 'hermes';
 }
 /**
- * NousHermesRunner — Runner polyglote pour Hermes Agent (Overmind 2.8.27+).
+ * NousHermesRunner — Runner polyglotte pour Hermes Agent (Overmind 2.8.27+).
  *
  *  • Providers : OpenAI, MiniMax GLOBAL/CN, Zhipu/GLM, Mistral, NVIDIA NIM, OpenRouter (embeddings only)
  *  • Lit settings_<agent>.json + .mcp.<agent>.json depuis .claude/ comme les autres runners
  *  • Interpolation $VAR et ${VAR} sur tout settings + mcp config (via envUtils, regex fix 2.8.25)
- *  • Subtilisation 3-pass (Pass 1: settings-explicit, Pass A: prefer provider-specific,
+ *  • Sélection/Emprunt de jeton 3-pass (Pass 1: settings-explicit, Pass A: prefer provider-specific,
  *    Pass B: re-map generic key, Pass C: rare fallback) — see hermesTokenResolver.ts
  *  • CN/GLOBAL disambiguation for sk-cp-* via ANTHROPIC_BASE_URL (URL wins)
  *  • OVERMIND_MINIMAX_DEFAULT=cn|global|auto for setups where all MiniMax tokens are CN
@@ -163,6 +187,62 @@ async function findHermesBinary() {
  *    to prevent Hermes from picking an exhausted bucket from a previous provider config
  *  • HOME/USERPROFILE propagated to spawned Hermes so ~/.hermes lookups resolve canonically
  */
+function filterConfigYaml(sourceYamlPath, allowedServers) {
+    try {
+        if (!fs.existsSync(sourceYamlPath))
+            return 'mcp_servers: {}\n';
+        const yamlText = fs.readFileSync(sourceYamlPath, 'utf8');
+        const lines = yamlText.split(/\r?\n/);
+        let inMcpServers = false;
+        let currentServerName = '';
+        const serverBlocks = {};
+        const headerLines = [];
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (line.match(/^mcp_servers:\s*$/) || line.match(/^mcp_servers:\s*#.*$/)) {
+                inMcpServers = true;
+                headerLines.push(line);
+                continue;
+            }
+            if (inMcpServers) {
+                const indentMatch = line.match(/^(\s+)/);
+                if (!indentMatch) {
+                    inMcpServers = false;
+                    headerLines.push(line);
+                    continue;
+                }
+                const indent = indentMatch[1].length;
+                const keyMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\s*:/);
+                if (keyMatch && indent === 2) {
+                    currentServerName = keyMatch[1];
+                    serverBlocks[currentServerName] = [line];
+                }
+                else if (currentServerName) {
+                    serverBlocks[currentServerName].push(line);
+                }
+            }
+            else {
+                headerLines.push(line);
+            }
+        }
+        let result = '';
+        for (const line of headerLines) {
+            result += line + '\n';
+            if (line.match(/^mcp_servers:\s*$/) || line.match(/^mcp_servers:\s*#.*$/)) {
+                for (const srv of allowedServers) {
+                    if (serverBlocks[srv]) {
+                        result += serverBlocks[srv].join('\n') + '\n';
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    catch (err) {
+        logger.error({ sourceYamlPath, error: err }, '[YAML_FILTER] Unexpected failure while filtering config.yaml.');
+        return 'mcp_servers: {}\n';
+    }
+}
 export class NousHermesRunner {
     timeoutMs;
     tempFiles = [];
@@ -171,20 +251,22 @@ export class NousHermesRunner {
         this.timeoutMs = CONFIG.TIMEOUT_MS || 900000; // 15 min default
     }
     cleanupTempFiles() {
+        logger.debug({ count: this.tempFiles.length }, '[CLEANUP] Cleaning up temporary run files.');
         for (const tempFile of this.tempFiles) {
             try {
                 if (fs.existsSync(tempFile)) {
                     fs.unlinkSync(tempFile);
-                    logger.debug({ tempFile }, 'Cleaned up temp file');
+                    logger.debug({ tempFile }, '[CLEANUP] Cleaned up temp file');
                 }
             }
             catch (err) {
-                logger.warn({ tempFile, error: err }, 'Failed to cleanup temp file');
+                logger.warn({ tempFile, error: err }, '[CLEANUP] Failed to cleanup temp file');
             }
         }
         this.tempFiles = [];
     }
     async runAgent(options) {
+        logger.info({ agentName: options.agentName, model: options.model, sessionId: options.sessionId }, '[RUN_AGENT] Initiating runAgent entrypoint.');
         try {
             const result = await withSpan('hermes.runAgent', async (span) => {
                 span.setAttribute('agentName', options.agentName || '');
@@ -198,13 +280,14 @@ export class NousHermesRunner {
             });
             this.cleanupTempFiles();
             if (options.agentName && result.sessionId) {
+                logger.info({ agentName: options.agentName, sessionId: result.sessionId }, '[RUN_AGENT] Saving completed session ID.');
                 await saveSessionId(options.agentName, result.sessionId, options.configPath, 'hermes');
             }
             return result;
         }
         catch (error) {
             this.cleanupTempFiles();
-            logger.error({ error: error instanceof Error ? error.message : String(error), agentName: options.agentName }, 'Hermes runner failed');
+            logger.error({ error: error instanceof Error ? error.message : String(error), agentName: options.agentName }, '[RUN_AGENT] Hermes runner execution flow threw an error.');
             throw error;
         }
     }
@@ -213,16 +296,30 @@ export class NousHermesRunner {
         let { sessionId } = options;
         const cwd = options.cwd || process.cwd();
         const configPath = options.configPath || getWorkspaceDir();
+        logger.info({ agentName, autoResume, cwd, configPath, silent }, '[RUN_AGENT_INTERNAL] Starting internal agent runner workflow.');
         // Load .env files FIRST
-        loadEnvQuietly(path.join(cwd, '.env'));
-        loadEnvQuietly(path.join(cwd, '../Workflow/.env'));
+        const envPaths = [path.join(cwd, '.env'), path.join(cwd, '../Workflow/.env')];
+        for (const envPath of envPaths) {
+            if (fs.existsSync(envPath)) {
+                logger.debug({ envPath }, '[RUN_AGENT_INTERNAL] Loading quiet environment file.');
+                loadEnvQuietly(envPath);
+            }
+            else {
+                logger.debug({ envPath }, '[RUN_AGENT_INTERNAL] Environment file not found, skipping.');
+            }
+        }
         // Auto Resume
         if (autoResume && agentName && !sessionId) {
+            logger.info({ agentName }, '[RUN_AGENT_INTERNAL] Auto-resume enabled. Querying last session ID.');
             const lastId = await getLastSessionId(agentName, configPath, 'hermes');
             if (lastId) {
                 sessionId = lastId;
                 if (!silent)
                     console.error(`[NousHermesRunner] Auto-resume session: ${sessionId}`);
+                logger.info({ sessionId }, '[RUN_AGENT_INTERNAL] Resolved last session ID for resume.');
+            }
+            else {
+                logger.info('[RUN_AGENT_INTERNAL] No previous session ID found for auto-resume.');
             }
         }
         const MAX_BUF = 10 * 1024 * 1024;
@@ -233,7 +330,8 @@ export class NousHermesRunner {
         // drift between dev/prod installs and between different spawn cwd's.
         const overmindHermesPath = getAgentOvermindHome(agentName);
         const overmindHermesSubPath = getAgentHermesHome(agentName);
-        if (agentName && !fs.existsSync(overmindHermesPath)) {
+        const agentSettingsPath = agentName ? resolveConfigPath(path.join(path.dirname(CONFIG.CLAUDE.PATHS.SETTINGS), `settings_${agentName}.json`), configPath) : '';
+        if (agentName && !fs.existsSync(overmindHermesPath) && !fs.existsSync(agentSettingsPath)) {
             return { result: '', error: `INVALID_AGENT: Agent Hermes "${agentName}" non trouvé (HERMES_HOME=${overmindHermesSubPath}).` };
         }
         // Load agent settings + MCP config (same pattern as ClaudeRunner)
@@ -242,7 +340,7 @@ export class NousHermesRunner {
         let resolvedProvider;
         const agentCustomEnv = {
             ...process.env,
-            PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1', PYTHONUNBUFFERED: '1',
+            PYTHONIOENCODING: 'utf-8', PYTHONUNBUFFERED: '1',
             PYTHONLEGACYWINDOWSSTDIO: '1', TERM: 'emacs',
             PROMPT_TOOLKIT_NO_INTERACTIVE: '1', ANSICON: '1',
             OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY || '',
@@ -261,6 +359,7 @@ export class NousHermesRunner {
         };
         let tmpSettingsPath = null;
         let tmpMcpPath = null;
+        let loadedSettings = null;
         // Capture the RAW (pre-interpolation) settings tokens so getTokenForIndex can
         // fail-loud on unresolved $VAR references and report which one is missing.
         // (Once interpolateEnvVars() runs, $VAR has been replaced with its value, and
@@ -304,9 +403,29 @@ export class NousHermesRunner {
             // agents that haven't been migrated yet.
             const canonicalSoul = path.join(overmindHermesSubPath, 'SOUL.md');
             const legacySoul = path.join(getSharedHermesHome(), `agent_${agentName}`, '.hermes', 'SOUL.md');
-            const agentPromptPath = fs.existsSync(canonicalSoul) ? canonicalSoul : legacySoul;
-            if (fs.existsSync(agentPromptPath)) {
+            const claudeSoul = path.join(configPath, '.claude', 'agents', `${agentName}.md`);
+            const agentPromptPath = fs.existsSync(claudeSoul)
+                ? claudeSoul
+                : fs.existsSync(canonicalSoul)
+                    ? canonicalSoul
+                    : fs.existsSync(legacySoul)
+                        ? legacySoul
+                        : null;
+            if (agentPromptPath && fs.existsSync(agentPromptPath)) {
                 systemPrompt = fs.readFileSync(agentPromptPath, 'utf8');
+                // Sync system prompt to canonical layout if loaded from legacy or Claude paths
+                if (agentPromptPath !== canonicalSoul) {
+                    try {
+                        if (!fs.existsSync(overmindHermesSubPath)) {
+                            fs.mkdirSync(overmindHermesSubPath, { recursive: true });
+                        }
+                        fs.writeFileSync(canonicalSoul, systemPrompt, 'utf8');
+                        logger.info({ agentName, source: agentPromptPath, target: canonicalSoul }, 'Synced SOUL.md to canonical Hermes path.');
+                    }
+                    catch (e) {
+                        logger.warn({ error: e }, 'Failed to sync SOUL.md to canonical Hermes path');
+                    }
+                }
             }
             // Load environment variables from .claude/settings_<agentName>.json
             try {
@@ -343,6 +462,7 @@ export class NousHermesRunner {
                     }
                     let settings = rawSettings;
                     settings = interpolateEnvVars(settings);
+                    loadedSettings = settings;
                     // Create temporary settings file
                     const tempSettings = path.join(path.dirname(agentSettingsPath), `settings_${agentName}_tmp.json`);
                     fs.writeFileSync(tempSettings, JSON.stringify(settings, null, 2));
@@ -445,7 +565,7 @@ export class NousHermesRunner {
         }
         const finalModel = options.model || resolvedModel || CONFIG.HERMES.DEFAULT_MODEL;
         const finalPrompt = systemPrompt ? `${systemPrompt}\n\n[USER QUERY]:\n${prompt}` : prompt;
-        const cliPrompt = finalPrompt.length > 7000 ? finalPrompt.substring(0, 7000) : finalPrompt;
+        const cliPrompt = finalPrompt;
         // Build CLI args: chat -q (persistent session, NOT -z oneshot)
         // -z + --resume doesn't work — resume is ignored in oneshot mode
         //
@@ -497,19 +617,29 @@ export class NousHermesRunner {
         const effectiveSettings = {};
         if (agentName) {
             try {
-                const canonicalPath = path.join(overmindHermesSubPath, 'settings.json');
-                if (fs.existsSync(canonicalPath)) {
-                    const raw = JSON.parse(fs.readFileSync(canonicalPath, 'utf8'));
-                    if (Array.isArray(raw.enabledMcpjsonServers)) {
-                        effectiveSettings.enabledMcpjsonServers = raw.enabledMcpjsonServers.filter(Boolean);
+                if (loadedSettings) {
+                    if (Array.isArray(loadedSettings.enabledMcpjsonServers)) {
+                        effectiveSettings.enabledMcpjsonServers = loadedSettings.enabledMcpjsonServers.filter(Boolean);
                     }
-                    if (raw.enableAllProjectMcpServers !== undefined) {
-                        effectiveSettings.enableAllProjectMcpServers = raw.enableAllProjectMcpServers === true;
+                    if (loadedSettings.enableAllProjectMcpServers !== undefined) {
+                        effectiveSettings.enableAllProjectMcpServers = loadedSettings.enableAllProjectMcpServers === true;
+                    }
+                }
+                else {
+                    const canonicalPath = path.join(overmindHermesSubPath, 'settings.json');
+                    if (fs.existsSync(canonicalPath)) {
+                        const raw = JSON.parse(fs.readFileSync(canonicalPath, 'utf8'));
+                        if (Array.isArray(raw.enabledMcpjsonServers)) {
+                            effectiveSettings.enabledMcpjsonServers = raw.enabledMcpjsonServers.filter(Boolean);
+                        }
+                        if (raw.enableAllProjectMcpServers !== undefined) {
+                            effectiveSettings.enableAllProjectMcpServers = raw.enableAllProjectMcpServers === true;
+                        }
                     }
                 }
             }
             catch (e) {
-                logger.warn({ error: e }, '[HERMES_ARGS] Failed to read canonical settings.json for toolset hints.');
+                logger.warn({ error: e }, '[HERMES_ARGS] Failed to read settings for toolset hints.');
             }
         }
         const enabledInSettings = effectiveSettings.enabledMcpjsonServers || [];
@@ -537,19 +667,33 @@ export class NousHermesRunner {
                 const hermesConfigPath = path.join(getSharedHermesHome(), 'config.yaml');
                 if (fs.existsSync(hermesConfigPath)) {
                     const yamlText = fs.readFileSync(hermesConfigPath, 'utf8');
-                    // Tiny ad-hoc YAML parser for `mcp_servers:` block: capture the
-                    // top-level keys under that section. This is intentionally
-                    // dependency-free — we don't want to pull in a YAML lib for a
-                    // single field. Hermes' config.yaml uses simple `key: value` lines
-                    // and 2-space indent for the mcp_servers block.
-                    const mcpBlockMatch = yamlText.match(/^mcp_servers:\s*\n((?: {2}[^\n]+\n?)+)/m);
-                    if (mcpBlockMatch) {
-                        const block = mcpBlockMatch[1];
-                        const serverNames = [...block.matchAll(/^ {2}([a-zA-Z0-9_-]+):/gm)].map((m) => m[1]);
-                        if (serverNames.length > 0) {
-                            toolsetList.push(...serverNames);
+                    // Line-by-line YAML parser for the `mcp_servers` section (handles comments, varying indentation, and exits correctly)
+                    const lines = yamlText.split(/\r?\n/);
+                    let inMcpServers = false;
+                    const serverNames = [];
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        if (!trimmed || trimmed.startsWith('#'))
+                            continue;
+                        if (line.match(/^mcp_servers:\s*$/) || line.match(/^mcp_servers:\s*#.*$/)) {
+                            inMcpServers = true;
+                            continue;
+                        }
+                        if (inMcpServers) {
+                            const indentMatch = line.match(/^(\s+)/);
+                            if (!indentMatch) {
+                                inMcpServers = false;
+                                continue;
+                            }
+                            const keyMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\s*:/);
+                            if (keyMatch) {
+                                serverNames.push(keyMatch[1]);
+                            }
                         }
                     }
+                    if (serverNames.length > 0) {
+                        toolsetList.push(...serverNames);
+                    }
                 }
                 if (toolsetList.length === 0) {
                     // Fallback: read .mcp.json (Overmind format) for any servers not in
@@ -568,8 +712,9 @@ export class NousHermesRunner {
             }
         }
         if (toolsetList.length > 0) {
-            cleanArgs.push('--toolsets', toolsetList.join(','));
-            logger.info({ agentName, toolsets: toolsetList }, '[HERMES_ARGS] Passing --toolsets (2.8.36: activates MCP servers as callable tools in this session).');
+            const formattedToolsets = toolsetList.map((name) => name.startsWith('mcp-') ? name : `mcp-${name}`);
+            cleanArgs.push('--toolsets', formattedToolsets.join(','));
+            logger.info({ agentName, toolsets: formattedToolsets }, '[HERMES_ARGS] Passing --toolsets (2.8.36: activates MCP servers as callable tools in this session).');
         }
         if (sessionId)
             cleanArgs.push('--resume', sessionId);
@@ -657,10 +802,10 @@ export class NousHermesRunner {
                             `but process.env.${varName} is empty. Add it to /home/demon/.overmind/.env or fix the settings reference.`);
                     }
                     resolvedValue = fromEnv;
-                    logger.info({ agentName, sourceKey: t.key, referencedVar: varName, resolvedLen: resolvedValue.length }, '[SUBTILISATION] Resolved $VAR reference from settings_<agent>.json against process.env.');
+                    logger.info({ agentName, sourceKey: t.key, referencedVar: varName, resolvedLen: resolvedValue.length }, '[TOKEN_RESOLVER] Resolved $VAR reference from settings_<agent>.json against process.env.');
                 }
                 const detected = detectTokenProvider(resolvedValue);
-                logger.info({ agentName, tokenKey: t.key, detectedProvider: detected.provider, mappedTo: detected.envKey }, '[SUBTILISATION] Using explicit settings_<agent>.json token, re-mapping to detected provider env var.');
+                logger.info({ agentName, tokenKey: t.key, detectedProvider: detected.provider, mappedTo: detected.envKey }, '[TOKEN_RESOLVER] Using explicit settings_<agent>.json token, re-mapping to detected provider env var.');
                 return { tokenEnvKey: t.key, tokenValue: resolvedValue, detectedProvider: detected.provider, source: 'settings-explicit' };
             }
             const candidates = [];
@@ -689,7 +834,7 @@ export class NousHermesRunner {
             // Pass B: re-map the first candidate to the right provider env-var name.
             const first = candidates[0];
             if (first.detected.provider !== 'unknown' && first.detected.envKey !== first.key) {
-                logger.info({ agentName, sourceKey: first.key, detectedProvider: first.detected.provider, remappedTo: first.detected.envKey }, '[SUBTILISATION] Token prefix detected provider mismatch — re-mapping env var.');
+                logger.info({ agentName, sourceKey: first.key, detectedProvider: first.detected.provider, remappedTo: first.detected.envKey }, '[TOKEN_RESOLVER] Token prefix detected provider mismatch — re-mapping env var.');
                 return {
                     tokenEnvKey: first.detected.envKey,
                     tokenValue: first.value,
@@ -930,6 +1075,65 @@ export class NousHermesRunner {
             // edits were being silently deleted after each spawn.
             logger.info({ agentName, settingsPath: tmpAgentSettings, envKeys: Object.keys(settingsJson.env || {}).length }, '[HERMES] Wrote canonical agents/<name>/settings.json (env block from settings_<name>.json + provider-specific seeds).');
         }
+        let effectiveHermesHome = sharedHome;
+        if (agentName && enabledInSettings.length > 0) {
+            try {
+                const runsDir = path.join(sharedHome, 'runs');
+                if (!fs.existsSync(runsDir))
+                    fs.mkdirSync(runsDir, { recursive: true });
+                const runHome = path.join(runsDir, agentName);
+                if (!fs.existsSync(runHome))
+                    fs.mkdirSync(runHome, { recursive: true });
+                // Copy auth.json if exists
+                const sharedAuth = path.join(sharedHome, 'auth.json');
+                const runAuth = path.join(runHome, 'auth.json');
+                if (fs.existsSync(sharedAuth)) {
+                    fs.copyFileSync(sharedAuth, runAuth);
+                }
+                // Robust directory junction/symlink helper
+                const linkDirRobust = (target, source) => {
+                    let exists = false;
+                    let stats = null;
+                    try {
+                        stats = fs.lstatSync(target);
+                        exists = true;
+                    }
+                    catch {
+                        // target does not exist
+                    }
+                    if (exists) {
+                        logger.debug({ target, isJunction: stats ? (stats.isSymbolicLink() || stats.isDirectory()) : false }, '[HERMES_HOME] Target directory/link already exists. Skipping link creation.');
+                    }
+                    else {
+                        logger.info({ target, source }, '[HERMES_HOME] Creating junction/symbolic link.');
+                        if (process.platform === 'win32') {
+                            execSync(`cmd /c mklink /J "${target}" "${source}"`);
+                        }
+                        else {
+                            fs.symlinkSync(source, target);
+                        }
+                    }
+                };
+                // Link agents directory
+                const sharedAgents = path.join(sharedHome, 'agents');
+                const runAgents = path.join(runHome, 'agents');
+                linkDirRobust(runAgents, sharedAgents);
+                // Link sessions directory
+                const sharedSessions = path.join(sharedHome, 'sessions');
+                const runSessions = path.join(runHome, 'sessions');
+                linkDirRobust(runSessions, sharedSessions);
+                // Generate filtered config.yaml
+                const sharedConfig = path.join(sharedHome, 'config.yaml');
+                const runConfig = path.join(runHome, 'config.yaml');
+                const filteredConfig = filterConfigYaml(sharedConfig, enabledInSettings);
+                fs.writeFileSync(runConfig, filteredConfig, 'utf8');
+                effectiveHermesHome = runHome;
+                logger.info({ agentName, runHome, enabledMcp: enabledInSettings }, '[HERMES_HOME] Isolated agent Hermes Home and filtered config.yaml successfully.');
+            }
+            catch (e) {
+                logger.warn({ error: e }, 'Failed to setup isolated run home; falling back to sharedHome');
+            }
+        }
         // AbortSignal
         if (options.signal?.aborted)
             return Promise.reject(new Error('ABORTED'));
@@ -939,10 +1143,27 @@ export class NousHermesRunner {
             let retryCount = 0;
             const maxRetries = getAvailableFallbacks().length + 1;
             let currentSessionId = sessionId;
-            const safeResolve = (v) => { if (!resolved) {
-                resolved = true;
-                resolve(v);
-            } };
+            const abortListener = () => {
+                if (currentChildRef) {
+                    killProcessTree(currentChildRef).then(() => {
+                        cleanupTmpFiles();
+                        safeResolve({ result: '', error: 'ABORTED', rawOutput: '' });
+                    });
+                }
+                else {
+                    cleanupTmpFiles();
+                    safeResolve({ result: '', error: 'ABORTED', rawOutput: '' });
+                }
+            };
+            const safeResolve = (v) => {
+                if (!resolved) {
+                    resolved = true;
+                    if (options.signal) {
+                        options.signal.removeEventListener('abort', abortListener);
+                    }
+                    resolve(v);
+                }
+            };
             const cleanupTmpFiles = () => {
                 for (const f of [tmpSettingsPath, tmpMcpPath]) {
                     if (f && fs.existsSync(f)) {
@@ -1031,12 +1252,11 @@ export class NousHermesRunner {
                 // etc. relative to HERMES_HOME. Setting it to the per-agent home would
                 // tell Hermes "this IS the Hermes root" and make it look for config.yaml
                 // IN the agent dir — wrong layout.
-                const sharedHermesHome = getSharedHermesHome();
                 const child = spawn(hermesBin, cleanArgs, {
                     cwd, shell: false, windowsHide: true,
                     env: {
                         ...spawnEnv,
-                        HERMES_HOME: sharedHermesHome,
+                        HERMES_HOME: effectiveHermesHome,
                         ...(isVenvInstall
                             ? {
                                 VIRTUAL_ENV: venvRoot,
@@ -1067,8 +1287,8 @@ export class NousHermesRunner {
                         void appendOutput(child.pid, chunk, configPath);
                         void appendLiveOutput(child.pid, chunk);
                     }
-                    if (stdout.length + chunk.length > MAX_BUF)
-                        stdout = stdout.slice(-MAX_BUF);
+                    if (stdout.length + chunk.length > this.MAX_BUF)
+                        stdout = stdout.slice(-this.MAX_BUF);
                     else
                         stdout += chunk;
                     if (!silent && agentName)
@@ -1076,8 +1296,8 @@ export class NousHermesRunner {
                 });
                 child.stderr?.on('data', (d) => {
                     const chunk = d.toString();
-                    if (stderr.length + chunk.length > MAX_BUF)
-                        stderr = stderr.slice(-MAX_BUF);
+                    if (stderr.length + chunk.length > this.MAX_BUF)
+                        stderr = stderr.slice(-this.MAX_BUF);
                     else
                         stderr += chunk;
                     if (!silent && agentName)
@@ -1137,13 +1357,9 @@ export class NousHermesRunner {
                     });
                 });
             };
-            options.signal?.addEventListener('abort', () => {
-                if (currentChildRef)
-                    killProcessTree(currentChildRef).then(() => {
-                        cleanupTmpFiles();
-                        safeResolve({ result: '', error: 'ABORTED', rawOutput: '' });
-                    });
-            });
+            if (options.signal) {
+                options.signal.addEventListener('abort', abortListener);
+            }
             let firstToken;
             try {
                 firstToken = getTokenForIndex(0);