brainclaw 1.6.0 → 1.7.0

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) {

package/dist/core/dirty-scope.js

@@ -0,0 +1,242 @@
+/**
+ * Scope-aware dirty-working-tree guard for dispatch (pln#520 Tier 2, trp#371).
+ *
+ * The original guard (can_30c295b4) refused review/assign/consult/ideate the
+ * moment ANY uncommitted file existed in the source repo — repo-global, no
+ * comparison to the dispatch scope. In multi-agent use (codex/claude leave
+ * uncommitted files around) that hard-blocks legitimate dispatches, and the
+ * coordination store itself (`.brainclaw/`) is rewritten on every dispatch so
+ * a second `bclaw_coordinate` in the same session ALWAYS saw a dirty tree.
+ *
+ * This helper makes the decision scope-aware. The cardinal rule (converged
+ * across the Tier 2 ideation loop lop_5fc24cc8707992ea): never turn a noisy,
+ * visible false-positive (block a legitimate dispatch) into a SILENT
+ * false-negative (let a worker review/edit stale code with no signal). So
+ * when the scope cannot be proven disjoint from the dirty files, we still
+ * block — `allow_dirty=true` remains the explicit, auditable override.
+ *
+ * Empirical grounding: of ~450 real claim scopes in the store, only 4 contain
+ * a glob and ~60% are not resolvable to paths at all (plan-ids, loop-refs,
+ * prose). So the resolver optimises for the path-prefix case and treats
+ * anything ambiguous as `unknown` (→ conservative block when dirty), rather
+ * than building a glob engine. The rare real globs are delegated to git.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+/** Top-level directories that read as code paths even when not yet on disk. */
+const KNOWN_TOP_LEVEL = new Set([
+    'src', 'lib', 'docs', 'doc', 'test', 'tests', 'packages', 'app', 'apps',
+    'scripts', 'bin', 'public', 'assets', 'examples', 'config',
+]);
+/** Entity-id / loop-ref prefixes that are never file paths. */
+const ENTITY_ID_RE = /^(pln|clm|asg|asgn|run|lop|dec|cst|con|trp|han|can|rtn|rn|seq|sess|agt|art|lsl)[_#]/i;
+function defaultRunGit(cwd, args) {
+    try {
+        const probe = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', timeout: 5000 });
+        if (probe.status !== 0 || typeof probe.stdout !== 'string') {
+            return { ok: false, stdout: '' };
+        }
+        return { ok: true, stdout: probe.stdout };
+    }
+    catch {
+        // Never block a dispatch because git hiccuped — surface as "not probeable".
+        return { ok: false, stdout: '' };
+    }
+}
+/** True for coordination/store paths that are dirty as a side effect of dispatching. */
+export function isSystemDirtyPath(p) {
+    const norm = p.replace(/\\/g, '/');
+    return norm === '.brainclaw'
+        || norm.startsWith('.brainclaw/')
+        || norm === '.git'
+        || norm.startsWith('.git/');
+}
+/**
+ * Parse `git status --porcelain=v1 -z` output into a flat list of paths.
+ *
+ * NUL-separated entries avoid the quoting/newline pitfalls of line parsing.
+ * Rename/copy entries (`R`/`C`) carry the NEW path in the status field and the
+ * ORIGINAL path in the following NUL field — we keep BOTH, because a move out
+ * of scope that creates a file in scope (or vice versa) is a relevant change.
+ */
+export function parsePorcelainZ(stdout) {
+    const parts = stdout.split('\0').filter((p) => p.length > 0);
+    const paths = [];
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i];
+        if (entry.length < 4)
+            continue; // malformed; "XY p" is the minimum
+        const status = entry.slice(0, 2);
+        const newPath = entry.slice(3); // skip "XY " (2 status chars + 1 separator)
+        paths.push(newPath);
+        if (status[0] === 'R' || status[0] === 'C') {
+            const origPath = parts[i + 1];
+            if (origPath !== undefined) {
+                paths.push(origPath);
+                i++; // consume the original-path field
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Resolve a free-string scope into git pathspecs, or `unknown` when it cannot
+ * be proven to denote file paths. All-or-nothing across comma-separated
+ * tokens: a single unresolvable token marks the whole scope unknown, so the
+ * guard never blocks on a partial (and therefore misleading) view.
+ */
+export function resolveScopeToPathspecs(scope, cwd) {
+    if (!scope || !scope.trim()) {
+        return { kind: 'unknown', reason: 'no scope provided' };
+    }
+    const tokens = scope.split(',').map((t) => t.trim()).filter(Boolean);
+    if (tokens.length === 0) {
+        return { kind: 'unknown', reason: 'empty scope' };
+    }
+    const pathspecs = [];
+    for (const token of tokens) {
+        if (ENTITY_ID_RE.test(token) || /^review-loop:/i.test(token)) {
+            return { kind: 'unknown', reason: `token "${token}" is an entity id, not a path` };
+        }
+        if (/\s/.test(token)) {
+            return { kind: 'unknown', reason: `token "${token}" contains whitespace (prose, not a path)` };
+        }
+        const normalized = token.replace(/\\/g, '/').replace(/^\.\//, '');
+        if (/[*?[\]]/.test(normalized)) {
+            // Delegate the rare real glob to git's native pathspec matcher.
+            pathspecs.push(`:(glob)${normalized}`);
+            continue;
+        }
+        const exists = fs.existsSync(path.resolve(cwd, normalized));
+        const topLevel = normalized.split('/')[0];
+        if (exists || KNOWN_TOP_LEVEL.has(topLevel)) {
+            pathspecs.push(normalized);
+            continue;
+        }
+        return {
+            kind: 'unknown',
+            reason: `token "${token}" is not a resolvable path (no such file/dir and not a known top-level)`,
+        };
+    }
+    return { kind: 'pathspecs', pathspecs };
+}
+/** Cap a file list for human-readable messages. */
+function summariseFiles(files, max = 10) {
+    if (files.length <= max)
+        return files.join(', ');
+    return `${files.slice(0, max).join(', ')} (and ${files.length - max} more)`;
+}
+/**
+ * Decide whether a dispatch may proceed given the source repo's dirty state and
+ * the dispatch scope. See the module header for the cardinal rule.
+ */
+export function assessDirtyDispatchGuard(input) {
+    const runGit = input.runGit ?? defaultRunGit;
+    const resolution = resolveScopeToPathspecs(input.scope, input.cwd);
+    // 1. Global probe — is the tree dirty at all (ignoring the coordination store)?
+    const global = runGit(input.cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=normal']);
+    if (!global.ok) {
+        return {
+            decision: 'allow',
+            reason: 'source cwd is not a git repo (or git is unavailable) — dirty guard skipped',
+            dirtyCount: 0,
+            overlapping: [],
+            ignoredSystemDirty: [],
+            scopeResolution: resolution.kind,
+        };
+    }
+    const allPaths = parsePorcelainZ(global.stdout);
+    const ignoredSystemDirty = allPaths.filter(isSystemDirtyPath);
+    const realDirty = allPaths.filter((p) => !isSystemDirtyPath(p));
+    if (realDirty.length === 0) {
+        return {
+            decision: 'allow',
+            reason: ignoredSystemDirty.length > 0
+                ? `working tree clean apart from ${ignoredSystemDirty.length} coordination-store file(s) (.brainclaw/, .git/) which the worker rebuilds itself`
+                : 'working tree clean',
+            dirtyCount: 0,
+            overlapping: [],
+            ignoredSystemDirty,
+            scopeResolution: resolution.kind,
+        };
+    }
+    // 2. Explicit ref → the worktree is built from that ref (the dispatch path
+    //    forces resetExistingWorktreeBranch so a pre-existing branch is reset to
+    //    the ref, not silently reused), so uncommitted working-tree changes are
+    //    intentionally out of scope. Only bypass when the ref actually resolves —
+    //    a bogus/unresolvable ref must NOT widen the allow; fall through to the
+    //    scope-aware check below so a dirty in-scope file still blocks.
+    if (input.checkoutRef) {
+        const refResolves = runGit(input.cwd, ['rev-parse', '--verify', '--quiet', `${input.checkoutRef}^{commit}`]).ok;
+        if (refResolves) {
+            return {
+                decision: 'allow',
+                reason: `dispatch builds its worktree from explicit ref "${input.checkoutRef}"; ${realDirty.length} uncommitted working-tree file(s) are intentionally out of scope`,
+                dirtyCount: realDirty.length,
+                overlapping: [],
+                ignoredSystemDirty,
+                scopeResolution: resolution.kind,
+            };
+        }
+        // else: ref does not resolve → continue to the scope-aware evaluation.
+    }
+    // 3. Scope-aware intersection (delegated to git for glob + segment-boundary correctness).
+    if (resolution.kind === 'pathspecs') {
+        const scoped = runGit(input.cwd, [
+            'status', '--porcelain=v1', '-z', '--untracked-files=normal',
+            '--', ...resolution.pathspecs, ':(exclude).brainclaw/', ':(exclude).git/',
+        ]);
+        // If the scoped probe fails for any reason, fall back conservatively:
+        // treat the whole real-dirty set as potentially overlapping.
+        const overlapping = scoped.ok ? parsePorcelainZ(scoped.stdout).filter((p) => !isSystemDirtyPath(p)) : realDirty;
+        if (overlapping.length === 0) {
+            return {
+                decision: 'allow',
+                reason: `${realDirty.length} uncommitted file(s) but none overlap the dispatch scope`,
+                dirtyCount: realDirty.length,
+                overlapping: [],
+                ignoredSystemDirty,
+                scopeResolution: resolution.kind,
+            };
+        }
+        if (input.allowDirty) {
+            return {
+                decision: 'warn',
+                reason: `allow_dirty=true: proceeding despite ${overlapping.length} dirty file(s) overlapping the dispatch scope: ${summariseFiles(overlapping)}`,
+                dirtyCount: realDirty.length,
+                overlapping,
+                ignoredSystemDirty,
+                scopeResolution: resolution.kind,
+            };
+        }
+        return {
+            decision: 'block',
+            reason: `${overlapping.length} uncommitted file(s) overlap the dispatch scope and the worker spawns from HEAD, so it will not see them: ${summariseFiles(overlapping)}. Commit or stash these, or pass allow_dirty=true to override.`,
+            dirtyCount: realDirty.length,
+            overlapping,
+            ignoredSystemDirty,
+            scopeResolution: resolution.kind,
+        };
+    }
+    // 4. Scope not resolvable to paths → cannot prove disjointness → conservative.
+    if (input.allowDirty) {
+        return {
+            decision: 'warn',
+            reason: `allow_dirty=true: proceeding despite ${realDirty.length} uncommitted file(s); dispatch scope is not resolvable to paths (${resolution.reason}) so overlap could not be ruled out`,
+            dirtyCount: realDirty.length,
+            overlapping: [],
+            ignoredSystemDirty,
+            scopeResolution: resolution.kind,
+        };
+    }
+    return {
+        decision: 'block',
+        reason: `${realDirty.length} uncommitted file(s) and the dispatch scope is not resolvable to file paths (${resolution.reason}), so overlap cannot be ruled out; the worker spawns from HEAD and will not see them: ${summariseFiles(realDirty)}. Commit or stash, pass a resolvable file scope, or pass allow_dirty=true to override.`,
+        dirtyCount: realDirty.length,
+        overlapping: [],
+        ignoredSystemDirty,
+        scopeResolution: resolution.kind,
+    };
+}
+//# sourceMappingURL=dirty-scope.js.map

package/dist/core/facade-schema.js

@@ -64,7 +64,23 @@ export const CoordinateRequestSchema = z.object({
      * dispatched work doesn't depend on the dirty files, or when running
      * tests). Has no effect when the source cwd is not a git repo.
      */
-    allow_dirty: z.boolean().optional(),
+    allow_dirty: z.preprocess(
+    // MCP clients that don't know allow_dirty is a boolean (it was previously
+    // absent from the published inputSchema) send the string "true"/"false".
+    // Coerce those so the documented escape hatch actually works; leave real
+    // booleans and undefined untouched.
+    (value) => (typeof value === 'string' ? value.trim().toLowerCase() === 'true' : value), z.boolean().optional()),
+    /**
+     * pln#520 Tier 2 (P2c) — explicit git ref (commit / branch / tag) the
+     * dispatched worker should build its worktree from, instead of the default
+     * HEAD. When set on a worktree-creating intent (assign / review / reroute),
+     * the worktree is checked out at this ref, so uncommitted working-tree
+     * changes in the source are intentionally out of scope and the scope-aware
+     * dirty guard allows the dispatch. Passed through to
+     * createCoordinatorClaim's worktreeBaseRef. Ignored by intents that don't
+     * create a worktree (consult / ideate / summarize).
+     */
+    ref: z.string().min(1).optional(),
     /**
      * pln#511 step 2 — loop preset selector. When set on intent='ideate',
      * the handler bypasses the kind-default ideation phases and opens the

package/dist/core/schema.js

@@ -1166,6 +1166,8 @@ export const AgentIntegrationNameSchema = z.enum([
     'continue',
     'roo',
     'kilocode',
+    'mistral-vibe',
+    'hermes',
     'openclaw',
     'nanoclaw',
     'nemoclaw',

package/dist/core/worktree.js

@@ -94,6 +94,64 @@ export function hasGitLock(cwd) {
     const lockPath = path.join(gitDir.stdout.trim(), 'index.lock');
     return fs.existsSync(lockPath);
 }
+/**
+ * Re-points an EXISTING worktree to `ref` via a hard reset of its checked-out
+ * branch + working tree. Used when a dispatch reuses an existing claim/worktree
+ * but pins a base ref: the worktree must reflect that ref, not stale state,
+ * otherwise the dirty-guard ref bypass would let the worker run on stale code
+ * (pln#520 Tier 2 / codex r2). Returns ok=false (with stderr) rather than
+ * throwing, so callers surface a visible warning instead of a hard failure.
+ */
+export function resetWorktreeToRef(worktreePath, ref) {
+    if (!fs.existsSync(worktreePath)) {
+        return { ok: false, stderr: `worktree path does not exist: ${worktreePath}` };
+    }
+    if (hasGitLock(worktreePath)) {
+        return { ok: false, stderr: 'git index.lock present — another git operation is in progress' };
+    }
+    const res = runGit(['reset', '--hard', ref], worktreePath);
+    if (!res.ok) {
+        return { ok: false, stderr: res.stderr };
+    }
+    // `reset --hard` realigns HEAD + tracked files, but leaves UNTRACKED residue
+    // from a prior use of the worktree — files the worker could still compile or
+    // test against even though they don't exist at the pinned ref (codex r3).
+    // We do NOT auto-delete (a blind `git clean` would also remove the brainclaw
+    // sidecar and gitignored shared symlinks); instead we detect non-system
+    // untracked files and report them so the caller surfaces a visible warning
+    // rather than letting the stale state pass silently. Ignored files (e.g.
+    // node_modules) are not listed by --untracked-files=normal, so the symlinked
+    // shared paths are unaffected.
+    const status = runGit(['status', '--porcelain=v1', '-z', '--untracked-files=normal'], worktreePath);
+    if (!status.ok) {
+        // The reset succeeded but we cannot confirm the worktree is residue-free -
+        // surface it rather than silently reporting a clean reset (cardinal rule).
+        return {
+            ok: false,
+            stderr: `reset to ${ref} succeeded but the untracked-residue check (git status) failed: ${status.stderr.trim()}`,
+        };
+    }
+    if (status.stdout.length > 0) {
+        const residue = status.stdout
+            .split('\0')
+            .filter((entry) => entry.startsWith('?? '))
+            .map((entry) => entry.slice(3))
+            .filter((p) => {
+            const norm = p.replace(/\\/g, '/');
+            return norm !== '.brainclaw-worktree.json'
+                && !norm.startsWith('.brainclaw/')
+                && !norm.startsWith('.git/');
+        });
+        if (residue.length > 0) {
+            const sample = residue.slice(0, 5).join(', ');
+            return {
+                ok: false,
+                stderr: `reset to ${ref} succeeded but ${residue.length} untracked file(s) remain from prior worktree use (e.g. ${sample}) — the worker may see state absent at the ref. Remove them or dispatch with a fresh scope.`,
+            };
+        }
+    }
+    return { ok: true, stderr: '' };
+}
 /**
  * Detects whether multiple distinct brainclaw sessions are using the same
  * physical worktree directory (shared-checkout risk).