brainclaw 1.6.0 → 1.7.1

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

@@ -311,6 +311,28 @@ 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) {
@@ -337,23 +359,66 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
             evidence, previous_status: run.status, current_status: run.status,
         };
     }
-    try {
-        transitionAgentRun(run.id, 'cancelled', {
-            actor: options.actor ?? 'reconciler',
-            status_reason: 'pid_dead_at_read',
-        }, cwd);
-        return {
-            run_id: run.id, action: 'cancelled_dead_pid', reason: 'pid_dead_at_read',
-            evidence, previous_status: run.status, current_status: 'cancelled',
-        };
+    // 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,
+            };
+        }
     }
-    catch (err) {
-        return {
-            run_id: run.id, action: 'no_op',
-            reason: `cancel 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();

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;
 }
 /**

package/dist/core/claims.js

@@ -6,7 +6,7 @@ import { mutate } from './mutation-pipeline.js';
 import { nowISO } from './ids.js';
 import { JsonStore } from './json-store.js';
 import { loadConfig } from './config.js';
-import { createWorktree } from './worktree.js';
+import { createWorktree, resetWorktreeToRef } from './worktree.js';
 import { appendAuditEntry } from './audit.js';
 import { refreshLiveCompanions } from '../commands/export.js';
 import { loadSessionById } from './identity.js';
@@ -407,10 +407,28 @@ export function createCoordinatorClaim(options) {
     const existingScopeClaim = listClaims(options.cwd).find((claim) => claim.status === 'active' && claim.scope === options.scope);
     if (existingScopeClaim) {
         if (existingScopeClaim.agent === options.agent) {
-            // Same agent already has this scope — reuse the claim (backward compat, same-agent multi-call).
+            // Same agent already has this scope — reuse the claim (backward compat,
+            // same-agent multi-call). If the caller pinned a base ref, the reused
+            // worktree MUST be re-pointed to it; otherwise a dispatch that relied on
+            // the ref (e.g. the dirty-guard bypass) would run the worker on a stale
+            // worktree — the same silent false-negative the guard exists to prevent
+            // (pln#520 Tier 2 / codex r2).
+            let reuseWarning;
+            if (options.worktreeBaseRef) {
+                if (existingScopeClaim.worktree_path) {
+                    const reset = resetWorktreeToRef(existingScopeClaim.worktree_path, options.worktreeBaseRef);
+                    if (!reset.ok) {
+                        reuseWarning = `Reused claim ${existingScopeClaim.id} pinned to ref "${options.worktreeBaseRef}": ${reset.stderr.trim()}`;
+                    }
+                }
+                else {
+                    reuseWarning = `Reused claim ${existingScopeClaim.id} has no worktree to pin to ref "${options.worktreeBaseRef}".`;
+                }
+            }
             return {
                 claimId: existingScopeClaim.id,
                 worktreePath: existingScopeClaim.worktree_path,
+                worktreeWarning: reuseWarning,
                 reusedExisting: true,
             };
         }
@@ -435,7 +453,11 @@ export function createCoordinatorClaim(options) {
             sessionId: options.sessionId,
             agent: options.agent,
             baseRef: options.worktreeBaseRef,
-            resetExistingBranch: options.resetExistingWorktreeBranch,
+            // A pinned base ref implies the branch must be reset to it: createWorktree
+            // otherwise reuses a pre-existing feat/<scope> branch and ignores baseRef.
+            // Deriving it here (not only at the call site) keeps the invariant — "a
+            // pinned ref ⇒ the worktree reflects that ref" — owned by this chokepoint.
+            resetExistingBranch: options.resetExistingWorktreeBranch || Boolean(options.worktreeBaseRef),
         });
     }
     catch (err) {