brainclaw 1.5.5 → 1.7.0

package/dist/commands/setup.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
@@ -7,7 +8,7 @@ import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { buildAiSurfaceInventory, renderAiSurfaceUsageHints } from '../core/ai-surface-inventory.js';
 import { buildMachineProfile, saveMachineProfile, loadMachineProfile } from '../core/machine-profile.js';
 import { buildAgentInventory, saveAgentInventory, loadAgentInventory } from '../core/agent-inventory.js';
-import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureContinueUserPermissions, ensureCodexMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
+import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureContinueUserPermissions, ensureCodexMcpConfig, ensureHermesMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
 import { MEMORY_DIR, memoryExists, ensureMemoryDir } from '../core/io.js';
 import { saveConfig, defaultConfig } from '../core/config.js';
 import { readSetupState, resolveHomeDir, writeSetupState } from '../core/setup-state.js';
@@ -25,6 +26,9 @@ export const ALL_KNOWN_AGENTS = [
     'antigravity',
     'continue',
     'roo',
+    'kilocode',
+    'mistral-vibe',
+    'hermes',
     'openclaw',
     'nanoclaw',
     'nemoclaw',
@@ -135,13 +139,46 @@ export function parseRepoSelection(choice, repos, cwd = process.cwd()) {
     return indices.map((i) => repos[i]);
 }
 // ─── Step 4: Agent selection ──────────────────────────────────────────────────
-export function parseAgentSelection(choice, detected) {
+function uniqueKnownAgents(names) {
+    const seen = new Set();
+    const result = [];
+    for (const name of names) {
+        if (!name || !ALL_KNOWN_AGENTS.includes(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        result.push(name);
+    }
+    return result;
+}
+export function getInstalledAgentNames(inventory) {
+    return uniqueKnownAgents(inventory?.agents.filter((agent) => agent.installed).map((agent) => agent.name) ?? []);
+}
+export function getDetectedSetupAgentNames(detected, installedAgents = []) {
+    return uniqueKnownAgents([
+        detected,
+        ...ALL_KNOWN_AGENTS.filter((agent) => installedAgents.includes(agent)),
+    ]);
+}
+export function parseAgentSelection(choice, detected, installedAgents = []) {
     const c = choice.trim().toLowerCase();
     if (c === 'a' || c === 'all')
         return [...ALL_KNOWN_AGENTS];
-    if (c === 'd' || c === 'detected')
-        return detected ? [detected] : [];
-    return c.split(',').map((a) => a.trim()).filter((a) => ALL_KNOWN_AGENTS.includes(a));
+    if (c === 'd' || c === 'detected' || c === 'installed') {
+        return getDetectedSetupAgentNames(detected, installedAgents);
+    }
+    const selected = [];
+    for (const token of c.split(',').map((a) => a.trim()).filter(Boolean)) {
+        const index = Number.parseInt(token, 10);
+        if (/^\d+$/.test(token) && index >= 1 && index <= ALL_KNOWN_AGENTS.length) {
+            selected.push(ALL_KNOWN_AGENTS[index - 1]);
+            continue;
+        }
+        if (ALL_KNOWN_AGENTS.includes(token))
+            selected.push(token);
+    }
+    return uniqueKnownAgents(selected);
 }
 // ─── Step 5: Global install ───────────────────────────────────────────────────
 export function initUserStore(home, env = process.env) {
@@ -237,6 +274,11 @@ export function runGlobalInstall(selectedAgents, env = process.env) {
         if (r && (r.created || r.updated))
             written.push(r.filePath);
     }
+    if (selectedAgents.includes('hermes')) {
+        const r = ensureHermesMcpConfig(home);
+        if (r && (r.created || r.updated))
+            written.push(r.filePath);
+    }
     return written;
 }
 // ─── Step 6: Init repos + configure agents ────────────────────────────────────
@@ -331,30 +373,35 @@ function logDetectedAgentSurfaces(detectedName, detectedSurfaces) {
         console.log('These surfaces are tracked separately from coding agents and will use tailored onboarding flows.');
     }
 }
-async function resolveSelectedAgentsForSetup(options, detectedName) {
+async function resolveSelectedAgentsForSetup(options, detectedName, installedAgents = []) {
+    const detectedSetupAgents = getDetectedSetupAgentNames(detectedName, installedAgents);
     console.log('Supported agents:');
     ALL_KNOWN_AGENTS.forEach((a, i) => {
         const tag = a === detectedName ? ' ← detected' : '';
-        console.log(`  ${i + 1}) ${a}${tag}`);
+        const installedTag = installedAgents.includes(a) ? ' ← installed' : '';
+        console.log(`  ${i + 1}) ${a}${tag}${tag ? '' : installedTag}`);
     });
+    if (detectedSetupAgents.length > 0) {
+        console.log(`Detected install set: ${detectedSetupAgents.join(', ')}`);
+    }
     let agentChoice;
     if (options.agents) {
         agentChoice = options.agents;
     }
     else if (options.yes || !process.stdin.isTTY) {
-        agentChoice = detectedName ? 'detected' : 'all';
+        agentChoice = detectedSetupAgents.length > 0 ? 'detected' : 'all';
     }
     else {
-        const defaultChoice = detectedName ? 'detected' : 'all';
+        const defaultChoice = detectedSetupAgents.length > 0 ? 'detected' : 'all';
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
         try {
-            agentChoice = (await rl.question(`Configure agents: (d)etected, (a)ll, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
+            agentChoice = (await rl.question(`Configure agents: (d)etected installed, (a)ll, names, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
         }
         finally {
             rl.close();
         }
     }
-    const selectedAgents = parseAgentSelection(agentChoice, detectedName);
+    const selectedAgents = parseAgentSelection(agentChoice, detectedName, installedAgents);
     console.log(`Selected agents: ${selectedAgents.length === 0 ? '(none)' : selectedAgents.join(', ')}`);
     return selectedAgents;
 }
@@ -364,10 +411,12 @@ export async function runSetupMachine(options = {}) {
     const detectedName = detectedAi?.name;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
+    const agentInventory = testMode ? undefined : buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env);
+    const installedAgents = getInstalledAgentNames(agentInventory);
     console.log(BRAINCLAW_ASCII);
     console.log('Machine bootstrap only — no repositories will be scanned or initialized.');
     logDetectedAgentSurfaces(detectedName, detectedSurfaces);
-    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName, installedAgents);
     console.log('\n→ Installing machine-level brainclaw prerequisites...');
     const written = runGlobalInstall(selectedAgents, env);
     if (written.length > 0) {
@@ -484,8 +533,10 @@ export async function runSetup(options = {}) {
     const detectedName = detectedAi?.name;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
+    const agentInventory = testMode ? undefined : buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env);
+    const installedAgents = getInstalledAgentNames(agentInventory);
     logDetectedAgentSurfaces(detectedName, detectedSurfaces);
-    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName, installedAgents);
     // Step 5: Global install
     console.log('\n→ Installing global brainclaw prerequisites...');
     const written = runGlobalInstall(selectedAgents, env);

package/dist/commands/switch.js

@@ -3,6 +3,7 @@ import { loadActiveProject, saveActiveProject, clearActiveProject } from '../cor
 import { loadCurrentSession, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef } from '../core/store-resolution.js';
+import { resolveProjectCwd } from '../core/cross-project.js';
 import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
 import { loadConfig } from '../core/config.js';
 /**
@@ -16,7 +17,22 @@ export function switchProject(projectRef, options = {}) {
     if (!wsRoot) {
         throw new Error('No brainclaw workspace found. Run `brainclaw init` first.');
     }
-    const resolved = resolveProjectRef(projectRef, cwd);
+    // pln#515 step 4 — resolution priority:
+    // 1. resolveProjectRef: workspace store-chain children (existing path)
+    // 2. resolveProjectCwd: cross_project_links (added so bclaw_switch can
+    //    target externally-linked projects, not just store-chain children).
+    // resolveProjectCwd returns the original cwd on no-match, so we check
+    // for a real change before treating it as a resolution.
+    let resolved = resolveProjectRef(projectRef, cwd);
+    if (!resolved) {
+        try {
+            const linkResolved = resolveProjectCwd(projectRef, cwd);
+            if (linkResolved !== cwd) {
+                resolved = linkResolved;
+            }
+        }
+        catch { /* link resolution failure surfaces as the same error below */ }
+    }
     if (!resolved) {
         throw new Error(`Cannot resolve project "${projectRef}". Use bclaw_switch with list=true to see available projects.`);
     }

package/dist/core/agent-capability.js

@@ -23,6 +23,7 @@ const AGENT_ALIASES = {
     'gemini': 'antigravity',
     'mistral': 'mistral-vibe',
     'vibe': 'mistral-vibe',
+    'hermes-agent': 'hermes',
 };
 /** Resolve an alias to its canonical agent name, or return the input unchanged. */
 export function resolveAgentAlias(name) {
@@ -227,6 +228,24 @@ const PROFILES = {
         invoke_review_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 5',
         invoke_consult_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 3',
     },
+    // Hermes Agent (Nous Research) — autonomous, skills-first agent with native
+    // MCP client support via ~/.hermes/config.yaml. Brainclaw uses Hermes as a
+    // Tier B surface for now: MCP + universal .agents/skills/ skill, no native
+    // Brainclaw hooks until a dedicated Hermes plugin is shipped and validated.
+    hermes: {
+        name: 'hermes', category: 'autonomous-agent', workflowModel: 'task-based',
+        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
+        instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'B',
+        role_capabilities: ['execute', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg', 'temp_file'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'hermes chat -q "{prompt}"',
+        invoke_binary: 'hermes',
+        invoke_review_template: 'hermes chat -q "{prompt}"',
+        invoke_consult_template: 'hermes chat -q "{prompt}"',
+    },
     // --- Autonomous agents (headless, task-based or scheduled) ---
     openclaw: {
         name: 'openclaw', category: 'autonomous-agent', workflowModel: 'task-based',

package/dist/core/agent-files.js

@@ -338,6 +338,7 @@ export const AGENT_EXPORT_REGISTRY = [
     { agentName: 'roo', format: 'roo', relativePath: '.roo/rules/brainclaw.md' },
     { agentName: 'kilocode', format: 'kilocode', relativePath: '.kilo/rules/brainclaw.md' },
     { agentName: 'mistral-vibe', format: 'agents-md', relativePath: 'AGENTS.md' },
+    { agentName: 'hermes', format: 'agents-md', relativePath: 'AGENTS.md' },
     { agentName: 'opencode', format: 'agents-md', relativePath: 'AGENTS.md' },
     { agentName: 'antigravity', format: 'gemini-md', relativePath: 'GEMINI.md' },
     { agentName: 'brainclaw', format: 'board-md', relativePath: 'BOARD.md' },
@@ -456,6 +457,8 @@ const ROO_MCP_RELATIVE_PATH = '.roo/mcp.json';
 const KILOCODE_MCP_RELATIVE_PATH = '.kilo/mcp.json';
 const KILOCODE_CONFIG_RELATIVE_PATH = 'kilo.jsonc';
 const MISTRAL_VIBE_CONFIG_RELATIVE_PATH = '.vibe/config.toml';
+const HERMES_CONFIG_RELATIVE_PATH = '.hermes/config.yaml';
+const HERMES_EXTERNAL_SKILLS_RELATIVE_PATH = '.agents/skills';
 const CONTINUE_CONFIG_RELATIVE_PATH = '.continue/config.json';
 const CONTINUE_PERMISSIONS_RELATIVE_PATH = '.continue/permissions.yaml';
 const OPENCODE_CONFIG_RELATIVE_PATH = 'opencode.json';
@@ -493,6 +496,7 @@ export const LOCAL_ONLY_AGENT_WORKSPACE_FILES = [
     KILOCODE_MCP_RELATIVE_PATH,
     KILOCODE_CONFIG_RELATIVE_PATH,
     MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
+    HERMES_CONFIG_RELATIVE_PATH,
     CONTINUE_CONFIG_RELATIVE_PATH,
     OPENCODE_CONFIG_RELATIVE_PATH,
     WINDSURF_MCP_RELATIVE_PATH,
@@ -1278,6 +1282,78 @@ export function ensureMistralVibeMcpConfig(cwd) {
         relativePath: MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
     };
 }
+const HERMES_BRAINCLAW_MCP_TOOLS = [
+    'bclaw_work',
+    'bclaw_context',
+    'bclaw_find',
+    'bclaw_get',
+    'bclaw_create',
+    'bclaw_update',
+    'bclaw_transition',
+];
+export function ensureHermesMcpConfig(homeDir, workspacePath) {
+    if (!homeDir)
+        return undefined;
+    const filePath = path.join(homeDir, HERMES_CONFIG_RELATIVE_PATH);
+    let existing = {};
+    let existed = false;
+    if (fs.existsSync(filePath)) {
+        existed = true;
+        try {
+            const parsed = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
+            existing = isJsonObject(parsed) ? { ...parsed } : {};
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const mcpServers = isJsonObject(existing.mcp_servers) ? { ...existing.mcp_servers } : {};
+    const current = isJsonObject(mcpServers.brainclaw) ? { ...mcpServers.brainclaw } : {};
+    const currentEnv = isJsonObject(current.env) ? { ...current.env } : {};
+    const currentTools = isJsonObject(current.tools) ? { ...current.tools } : {};
+    const skills = isJsonObject(existing.skills) ? { ...existing.skills } : {};
+    const externalDirs = Array.isArray(skills.external_dirs)
+        ? skills.external_dirs.filter((value) => typeof value === 'string')
+        : [];
+    if (workspacePath) {
+        const projectSkillsDir = path.resolve(workspacePath, HERMES_EXTERNAL_SKILLS_RELATIVE_PATH);
+        const normalized = projectSkillsDir.replace(/\\/g, '/').toLowerCase();
+        if (!externalDirs.some((dir) => dir.replace(/\\/g, '/').toLowerCase() === normalized)) {
+            externalDirs.push(projectSkillsDir);
+        }
+    }
+    const mcpCmd = getBrainclawMcpCommand();
+    mcpServers.brainclaw = {
+        ...current,
+        command: typeof current.command === 'string' ? current.command : mcpCmd.command,
+        args: Array.isArray(current.args) ? current.args : mcpCmd.args,
+        env: {
+            ...currentEnv,
+            BRAINCLAW_AGENT: 'hermes',
+        },
+        tools: {
+            ...currentTools,
+            include: Array.isArray(currentTools.include) ? currentTools.include : HERMES_BRAINCLAW_MCP_TOOLS,
+            prompts: typeof currentTools.prompts === 'boolean' ? currentTools.prompts : false,
+            resources: typeof currentTools.resources === 'boolean' ? currentTools.resources : false,
+        },
+    };
+    const nextConfig = {
+        ...existing,
+        mcp_servers: mcpServers,
+        ...(externalDirs.length > 0 ? { skills: { ...skills, external_dirs: externalDirs } } : {}),
+    };
+    const content = `# Managed by brainclaw — preserves existing Hermes settings\n${yaml.stringify(nextConfig)}`;
+    const { created, updated } = writeTextFileIfChanged(filePath, content);
+    return {
+        kind: 'mcp',
+        label: 'Hermes MCP settings',
+        created: !existed && created,
+        updated: existed && updated,
+        filePath,
+        relativePath: HERMES_CONFIG_RELATIVE_PATH,
+    };
+}
 export function ensureCodexMcpConfig(homeDir, env = process.env) {
     const codexHome = env.CODEX_HOME?.trim() || (homeDir ? path.join(homeDir, '.codex') : null);
     if (!codexHome)
@@ -1814,6 +1890,13 @@ export function writeDetectedAgentAutoConfig(agentName, cwd, env = process.env)
             return [ensureKilocodeMcpConfig(cwd), ensureKilocodeConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
         case 'mistral-vibe':
             return [ensureMistralVibeMcpConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
+        case 'hermes': {
+            const results = [ensureUniversalBrainclawSkill(cwd)];
+            const mcp = ensureHermesMcpConfig(resolveHomeDir(env), cwd);
+            if (mcp)
+                results.push(mcp);
+            return results;
+        }
         case 'codex': {
             const results = [ensureUniversalBrainclawSkill(cwd)];
             const result = ensureCodexMcpConfig(resolveHomeDir(env), env);
@@ -1916,6 +1999,8 @@ export function writeExportCompanionFiles(format, cwd, env = process.env) {
                 results.push(hooks);
             return results;
         }
+        case 'agents-md':
+            return [ensureUniversalBrainclawSkill(cwd)];
         default:
             return [];
     }
@@ -1956,6 +2041,7 @@ export function patchAllMcpConfigs(cwd, env = process.env) {
             ensureAntigravityMcpConfig(homeDir),
             ensureOpenClawMcpConfig(homeDir),
             ensureCodexMcpConfig(homeDir, env),
+            ensureHermesMcpConfig(homeDir),
         ];
         for (const r of userConfigs) {
             if (r)

package/dist/core/agent-integrations.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import yaml from 'yaml';
 import { getInstalledBrainclawVersion } from './brainclaw-version.js';
 import { getAgentCapabilityProfile } from './agent-capability.js';
 const SUPPORTED_AGENT_INTEGRATION_NAMES = new Set([
@@ -16,12 +17,17 @@ const SUPPORTED_AGENT_INTEGRATION_NAMES = new Set([
     'continue',
     'roo',
     'kilocode',
+    'mistral-vibe',
+    'hermes',
     'openclaw',
     'nanoclaw',
     'nemoclaw',
     'picoclaw',
     'zeroclaw',
 ]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 const DEFAULT_SURFACES = {
     'github-copilot': [
         { kind: 'instructions', location: 'workspace', path: '.github/copilot-instructions.md' },
@@ -85,6 +91,16 @@ const DEFAULT_SURFACES = {
         { kind: 'mcp', location: 'workspace', path: '.kilo/mcp.json' },
         { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
+    'mistral-vibe': [
+        { kind: 'instructions', location: 'workspace', path: 'AGENTS.md' },
+        { kind: 'mcp', location: 'workspace', path: '.vibe/config.toml' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
+    ],
+    'hermes': [
+        { kind: 'instructions', location: 'workspace', path: 'AGENTS.md' },
+        { kind: 'mcp', location: 'machine', path: '.hermes/config.yaml' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
+    ],
     'openclaw': [
         { kind: 'skill', location: 'machine', path: '.openclaw/workspace/skills/brainclaw/SKILL.md' },
         { kind: 'mcp', location: 'machine', path: '.openclaw/mcp.json' },
@@ -161,6 +177,24 @@ export function extractMcpCommandVal(agentName, expectedPath) {
             is_valid: true,
         };
     }
+    if (expectedPath.endsWith('.yaml') || expectedPath.endsWith('.yml')) {
+        try {
+            const parsed = yaml.parse(content);
+            const root = isRecord(parsed) ? parsed : {};
+            const servers = isRecord(root.mcp_servers) ? root.mcp_servers : {};
+            const bc = isRecord(servers.brainclaw) ? servers.brainclaw : {};
+            const cmd = bc.command;
+            const args = bc.args;
+            return {
+                command: typeof cmd === 'string' ? cmd : undefined,
+                args: Array.isArray(args) ? args.filter((a) => typeof a === 'string') : undefined,
+                is_valid: true,
+            };
+        }
+        catch {
+            return { is_valid: false };
+        }
+    }
     try {
         const j = JSON.parse(content);
         let cmd;

package/dist/core/agent-inventory.js

@@ -300,6 +300,33 @@ const AGENT_DEFINITIONS = [
         hooks_support: false,
         instruction_file: '.continue/rules/',
     },
+    {
+        name: 'hermes',
+        detect: (home, env) => {
+            if (env.HERMES_SESSION_ID || env.HERMES_AGENT || env.HERMES_HOME) {
+                return { installed: true, method: 'HERMES_* env' };
+            }
+            if (fs.existsSync(path.join(home, '.hermes'))) {
+                return { installed: true, method: '~/.hermes directory' };
+            }
+            const cli = tryCommand('hermes', ['--version'], 3000);
+            if (cli.ok) {
+                return { installed: true, method: 'hermes CLI', version: cli.stdout.trim() };
+            }
+            return { installed: false, method: '' };
+        },
+        models: [
+            { name: 'model-agnostic' },
+        ],
+        native_tools: ['execute_code', 'shell', 'file_read', 'file_write', 'web_search', 'delegate_task'],
+        mcp_support: true,
+        mcp_config_format: '~/.hermes/config.yaml',
+        skills_support: true,
+        skills_path_pattern: '~/.hermes/skills/ and .agents/skills/',
+        rules_support: false,
+        hooks_support: false,
+        instruction_file: 'AGENTS.md',
+    },
 ];
 // ── Public API ─────────────────────────────────────────────────────────────────
 /**

package/dist/core/agentrun-reconciler.js

@@ -50,6 +50,8 @@ export const DEFAULT_HEALTH_CHECK_GRACE_MS = 60_000;
  * declared `failed` with `silent_termination_no_evidence`. Default 30 min.
  */
 export const DEFAULT_STALE_AFTER_MS = 30 * 60_000;
+export const DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS = 5 * 60_000;
+export const DEFAULT_DEAD_PID_READ_SWEEP_LIMIT = 50;
 const TERMINAL_STATUSES = new Set([
     'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
 ]);
@@ -309,6 +311,134 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
         evidence, previous_status, current_status: run.status,
     };
 }
+/**
+ * Read-path reconciliation for a `running` run whose tracked PID reads dead.
+ *
+ * IMPORTANT (pln#520): the tracked PID is NOT trustworthy. On Windows the
+ * ack-wrap spawn (shell:true) records the cmd.exe wrapper PID, not the real
+ * worker (cmd.exe -> claude.cmd -> node.exe), so a dead PID does NOT prove the
+ * worker died — empirically, 6 workers were cancelled here yet committed their
+ * work 4-7 min later. This function therefore NEVER cancels prematurely:
+ *   - work evidence (commit / claim released / assignment completed)
+ *     -> inferred `completed`;
+ *   - past the stale threshold with a dead pid and still no evidence
+ *     -> inferred `failed` (silent_termination_no_evidence). This MUST converge
+ *     HERE: the canonical read path (entity-operations.ts) and the MCP pre-read
+ *     sweep route `running` runs through THIS function, never through
+ *     reconcileAgentRun, so deferring would leave a crashed run `running`
+ *     forever (the trp#292 pattern);
+ *   - otherwise (young, dead pid, no evidence yet) -> non-mutating health-check,
+ *     leaving the run `running` so a worker behind an untrusted pid keeps its
+ *     fair chance.
+ * Net vs pre-pln#520: a genuine silent death converges to `failed` after the
+ * stale window instead of an immediate (often false) `cancelled`.
+ */
+export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {}) {
+    const run = loadAgentRun(runId, cwd);
+    if (!run) {
+        const evidence = {
+            age_ms: 0, has_post_start_commit: false, claim_released: false,
+            assignment_completed: false, process_alive: undefined,
+        };
+        return {
+            run_id: runId, action: 'no_op', reason: 'run not found', evidence,
+            previous_status: 'created', current_status: 'created',
+        };
+    }
+    const evidence = collectEvidence(run, cwd, { nowMs: options.nowMs });
+    if (run.status !== 'running') {
+        return {
+            run_id: run.id, action: 'no_op', reason: `run status is ${run.status}, not running`,
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    if (evidence.process_alive !== false) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: evidence.process_alive === true ? 'process alive' : 'pid liveness unknown',
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    // pid reads dead — but the tracked pid is NOT trustworthy (see doc above),
+    // so a bare dead pid NEVER cancels. Evidence of real work wins; otherwise
+    // surface the uncertainty non-destructively and leave the run `running` for
+    // reconcileAgentRun's stale-threshold path to fail it only after a fair,
+    // evidence-based delay.
+    const actor = options.actor ?? 'reconciler';
+    if (anyCompletionEvidence(evidence)) {
+        try {
+            transitionAgentRun(run.id, 'completed', {
+                actor,
+                status_reason: `inferred=true; evidence: ${describeEvidence(evidence)}`,
+            }, cwd);
+            return {
+                run_id: run.id, action: 'inferred_completed',
+                reason: `inferred=true; ${describeEvidence(evidence)}`,
+                evidence, previous_status: run.status, current_status: 'completed',
+            };
+        }
+        catch (err) {
+            return {
+                run_id: run.id, action: 'no_op',
+                reason: `completion transition rejected: ${err instanceof Error ? err.message : String(err)}`,
+                evidence, previous_status: run.status, current_status: run.status,
+            };
+        }
+    }
+    // Stale + provably dead + still no evidence -> genuine silent failure. This
+    // MUST converge HERE: the canonical read path (entity-operations.ts) and the
+    // MCP pre-read sweep route `running` runs through this function, never
+    // through reconcileAgentRun, so deferring would leave a crashed run `running`
+    // forever (trp#292). The 30-min stale window — vs the immediate cancel before
+    // pln#520 — gives a worker behind an untrusted pid ample time to leave
+    // evidence first. Reported as `failed` (it died), not `cancelled`.
+    const stale = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    if (evidence.age_ms >= stale) {
+        try {
+            transitionAgentRun(run.id, 'failed', {
+                actor,
+                status_reason: 'silent_termination_no_evidence',
+            }, cwd);
+            return {
+                run_id: run.id, action: 'inferred_failed',
+                reason: 'silent_termination_no_evidence',
+                evidence, previous_status: run.status, current_status: 'failed',
+            };
+        }
+        catch (err) {
+            return {
+                run_id: run.id, action: 'no_op',
+                reason: `failure transition rejected: ${err instanceof Error ? err.message : String(err)}`,
+                evidence, previous_status: run.status, current_status: run.status,
+            };
+        }
+    }
+    emitUnverifiedEvent(run, evidence, actor, cwd);
+    return {
+        run_id: run.id, action: 'health_check_unverified',
+        reason: `pid_dead_untrusted_no_evidence (age=${Math.round(evidence.age_ms / 1000)}s) — awaiting evidence or stale window`,
+        evidence, previous_status: run.status, current_status: run.status,
+    };
+}
+export function sweepDeadPidRunningAgentRunsAtRead(cwd, options = {}) {
+    const now = options.nowMs ?? Date.now();
+    const minAgeMs = options.staleAfterMs ?? DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS;
+    const cutoff = now - minAgeMs;
+    const limit = options.limit ?? DEFAULT_DEAD_PID_READ_SWEEP_LIMIT;
+    const candidates = listAgentRuns(cwd, { status: 'running' })
+        .filter((run) => {
+        const lastEventAt = run.last_event_at ?? run.started_at ?? run.created_at;
+        const ts = new Date(lastEventAt).getTime();
+        return Number.isFinite(ts) && ts <= cutoff;
+    })
+        .sort((left, right) => {
+        const leftTs = new Date(left.last_event_at ?? left.started_at ?? left.created_at).getTime();
+        const rightTs = new Date(right.last_event_at ?? right.started_at ?? right.created_at).getTime();
+        return rightTs - leftTs;
+    })
+        .slice(0, limit);
+    return candidates.map((run) => reconcileDeadPidRunningAgentRunAtRead(run.id, cwd, options));
+}
 /**
  * Reconcile every non-terminal agent_run matching `filter`. Useful for
  * batch sweeps from `bclaw_assignment_events` or `brainclaw doctor --dispatch`.

package/dist/core/ai-agent-detection.js

@@ -19,7 +19,8 @@ import os from 'node:os';
  * 9. Antigravity / Gemini CLI (ANTIGRAVITY_* env or ~/.gemini/antigravity/)
  * 10. Continue (CONTINUE_*)
  * 11. Roo Code (ROO_*)
- * 12. OpenClaw (~/.openclaw/ or OPENCLAW_*)
+ * 12. Hermes (HERMES_* or ~/.hermes/)
+ * 13. OpenClaw (~/.openclaw/ or OPENCLAW_*)
  */
 export function detectAiAgent(env = process.env, homeDir = os.homedir()) {
     // Explicit override
@@ -161,6 +162,21 @@ export function detectAiAgent(env = process.env, homeDir = os.homedir()) {
             detection_source: env.VIBE_HOME ? 'VIBE_HOME env var' : '~/.vibe directory',
         };
     }
+    // Hermes Agent — supports MCP and skills from ~/.hermes/. Detect after
+    // editor/CLI agents with stronger session env vars to avoid stealing mixed
+    // shells where Hermes is merely installed.
+    if (env.HERMES_SESSION_ID || env.HERMES_AGENT || env.HERMES_HOME || fs.existsSync(path.join(homeDir, '.hermes'))) {
+        return {
+            name: 'hermes',
+            kind: 'autonomous',
+            trust_level: 'trusted',
+            detection_source: env.HERMES_SESSION_ID || env.HERMES_AGENT
+                ? 'HERMES_* env var'
+                : env.HERMES_HOME
+                    ? 'HERMES_HOME env var'
+                    : '~/.hermes directory',
+        };
+    }
     return undefined;
 }
 /**